Skip to content

Add extension hooks for runloop, routes and actions - #682

Open
simonhamp wants to merge 4 commits into
refactor/action-pipelinefrom
feat/extension-hooks
Open

simonhamp wants to merge 4 commits into
refactor/action-pipelinefrom
feat/extension-hooks

Conversation

@simonhamp

Copy link
Copy Markdown
Member

Stacks on #681 (the action pipeline). Review that first; this diff is only the hooks.

This adds general extension points to core so the server-driven UI client can live in its own package (midgard) instead of shipping inside every app. Once midgard moves onto these, #665 gets much smaller. Nothing here knows about that client. Every hook is tested with a small extension written in the test itself.

Runloop extensions

Edge\Contracts\RunloopExtension, with a no-op Edge\Extensions\RunloopExtensionBase, registered with NativeComponent::extend(). forgetExtensions() resets the list for tests.

  • beginFrame() and endFrame($root) run around every render, on the Element path and the streaming path.
  • nextWake($tree) returns how many milliseconds until the extension needs a turn, or 0 to repaint now. nextEventTimeout() sleeps for the shorter of that and its own poll timers. While the error screen is up the loop still blocks, as before.
  • tick($tree) runs at the top of each turn in run() and runLoop(), inside runGuardedInteraction, then dispatched events are flushed. Returning true repaints. If a tick ends the loop (navigates, say), later extensions don't tick and the loop stops before drawing.
  • handleNativeEvent($name, $payload) can claim a native event before GlobalEventTransport and the app's listeners, like the __deeplink and AsyncTask cases.
  • resolveCallback($component, $id) answers for UI callback ids an extension registered. The uiEventArgs() extraction is pulled out so the handler gets the same event value a screen method would.
  • aroundAction($component, $method, $args, $source, $next) wraps every developer action. The first registered is the outermost.
  • componentUnmounted($component) is called from unmount(), children first. The audit didn't list this, but the client has to drop pending requests for a component that is gone, and child components have no screen event of their own.

Route tables

NativeRouter::setRouteTable($name, $entries) takes entries of URI pattern => ['class' => ..., 'context' => ...], with an optional layout. routeTable() and routeEntryFor($uri) read them back, and clearRoutes() clears them. The entry's context reaches the screen through a new NativeComponent::setRouteContext() before mount(). This happens in the router (start, navigate, replace, preloadStack) and in the harness (visit() and follow()). The method does nothing by default.

Smaller pieces

  • ComponentMethodInvoker::reserveTrait(): methods a reserved trait declares can't be named by a template or a remote call. On a component that uses the trait they are refused by name in any case. Aliased methods are refused by the file they come from. Components that don't use the trait keep their own same-named methods.
  • The harness fires ScreenMounted, ScreenResumed and ScreenUnmounted where the router does, and wait($seconds) moves Carbon's clock and runs extension ticks before drawing a frame.
  • Seams ported from the reference branch as they were: Element::wireType() (used by toArray() and the streaming collector), collector setCallbacks(?…), callbacks(), openElement() and owner(), the protected CallbackRegistry::parseExpression(), NavBar::actionElement(), TabBar::tabElement(), NativeComponent::chromeLayout() and PendingAsyncTask::anyScreen().
  • The Route::native() closure moves to Http\NativeScreenEntry::handle() unchanged. It is public API so a package can open screens from its own routes or middleware.

What to watch

  • The double-claim rule in dispatchUiEvent(). Extension ids may come from outside the app, so one could be made to equal a callback the screen owns. If the screen and an extension, or two extensions, claim the same id, nothing runs and it is logged. This stays in core on purpose.
  • aroundAction() ordering. It fires inside runAction() after assertCallable() and assertRemoteCallable(), so a refused call never reaches an extension. $next takes no arguments, so an extension can't swap in a method or arguments the guards didn't check. It can short-circuit by not calling $next.
  • Route tables never shadow an app route. They are matched after every app route, parameterized ones included, and an entry whose pattern the app already has is dropped at registration.
  • setRouteContext() is public so the router can call it, so a screen overriding it would otherwise become template-callable. ensureCallable() refuses it by name.

Tests: 2623 passed, 5 skipped, 4 risky (--filter '/^(?!.*turns a component dd).*$/'). PHPStan reports only the three RunsAndroid.php errors that #680 fixes. Pint is clean.

🤖 Generated with Claude Code

simonhamp and others added 4 commits November 14, 2026 17:57
Element::wireType() lets a PHP-only element reach the renderers as a type
they already know. The collector gains accessors for its bound registry,
open element and owner, and setCallbacks() takes null so a caller can put
back what it found. CallbackRegistry reads expressions through a
protected parseExpression(), NavBar and TabBar accept prebuilt elements,
and NativeComponent::chromeLayout() is the one place a screen's layout
is built. PendingAsyncTask::anyScreen() runs completions on whichever
screen is on top.

The body of Route::native() moves to Http\NativeScreenEntry so a package
can open a screen from its own route or middleware the same way.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A RunloopExtension registered with NativeComponent::extend() is called
around each frame (both render paths), can ask the loop to wake with
nextWake(), takes a tick() at the top of every turn, can claim a native
event before the app's listeners, can answer for UI callback ids it
registered, wraps every developer action through aroundAction(), and is
told when a component unmounts.

Two rules stay in core. A callback id that more than one scope claims
(the screen and an extension, or two extensions) is dropped and logged,
since an extension's ids may come from outside the app. And
aroundAction() runs inside runAction() after the callable guards, with a
$next that takes no arguments, so a refused call never reaches an
extension and none can swap in a method the guards did not see.

The test harness gains wait(), which moves Carbon's clock and takes the
idle turn the loop takes when it wakes on its own.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
ComponentMethodInvoker::reserveTrait() keeps every method a trait
declares out of reach of templates and remote calls. A package uses it
for a trait whose public methods are plumbing it calls itself. On a
component that uses the trait the methods are refused by name in any
case, so an override on the app's class is refused too, and a method
brought in under an alias is refused by the file it comes from. A
component that does not use the trait keeps its own same-named methods.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
NativeRouter::setRouteTable() lets a package add routes while the app
runs. Each entry names a screen class and a context. Tables are matched
only after every app route, so a table route never shadows one of the
app's, even a parameterized one, and an entry whose pattern the app
already has is dropped. clearRoutes() clears them. routeEntryFor() says
which entry a URI opens.

The entry's context reaches the screen through a new
NativeComponent::setRouteContext() before mount(), in the router and in
the harness's visit() and follow(). It does nothing by default, and a
template can never call it.

The harness now fires ScreenMounted, ScreenResumed and ScreenUnmounted
where the router does, so a package listening for them behaves the same
under test.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant