Prototype spec: screen map and route transitions¶
Part of the agent-authored prototype specification.
Screen map (#14125)¶
prototype {action:"screenMap", spec | specPath} is host-only (no device request). It walks the
spec, after component expansion, and returns screenMap {nodes, edges} plus a mermaid flowchart.
Nodes are the root, each stack screen (stack:<id>/<screen>, start on the start screen), each
pager page (pager:<id>/<index>, labelled from a tabBar or bottomNav that names the pager),
bottomSheet and dialog. Edges are push, replace, pop, popToRoot and setPage actions, from
the enclosing screen, each tagged with the testTag, id and text or label of the node that runs it
and its spec path. A screen node carries the testTag of the node that draws it. A pop targets
back (the previous screen is runtime state), and setPage with next or prev keeps the authored
word. visibleWhen alternatives and sheet or dialog opening by state are not resolved.
getNavigationGraph (debug-gated with the rest of that tool) diffs the map against the app’s recorded
graph when given prototypeSpec or prototypeSpecPath, and returns prototypeDiff. A prototype screen
matches a real screen through, in order:
- An explicit
screenMapping(orscreenMappingPath) entry from prototype screen id to real screen name. - Its
testTagequal to the real screen name. - Its stack screen key (whole, slashes included), tab label or sheet/dialog id equal to the real
name ignoring case and punctuation. A trailing
Screen,Activity,Fragment,Page,VieworControlleron either side is optional, soOverviewstill meetsOverviewActivity.
Letters of any script count; a name with none never matches. A mapped screen never falls back to the
other rules, and a mapping to a name the graph lacks reports mappedScreenMissing. The root is a
destination only when the mapping names it. The result lists matched screens,
unmatchedPrototypeScreens, unmatchedRealScreens, observedTransitions, unobservedTransitions
(unmatchedScreen, dynamicTarget for back and next/prev, or notObserved) and
ignoredMappings (keys naming no prototype screen). The live cross-check against screen_changed
events from an explored prototype is not built.
Route contract¶
prototype_routes_v1 gates stack routes, push/replace params, pop force, setStack,
route placeholders and stack:<id> storage keys. CtrlProxy, the embedded renderer (saved
prototypes, ProtoViewer, disposable apps) and the iOS prototype agent advertise it. The host refuses
these fields against a device that does not, so an older runner fails closed. The screens field remains a
map of bare nodes; the optional sibling routes map may contain only screen names of that stack.
Each route has optional params: {name: "string"|"number"|"boolean"} (at most 16, path-key
names), onEnter and onBack (1–32 actions each, with the existing action nesting budget). The
start screen cannot declare params because initial display and popToRoot cannot supply them. Param
names use the uncapped path-key identifier grammar; the runtime checks bound state keys.
Push and replace accept up to 16 scalar literals or existing state/data/item/index value bindings
in params. All declared params are required; the action rejects unknown names and incorrectly
typed literals. setStack {stack, path:[{screen,params?}]} validates each entry the same way
and requires 1–MAX_PROTOTYPE_STACK_DEPTH entries. A non-forced pop of the owning stack in
its screen’s onBack list, including nested timer and request follow-ups, is rejected; force:true
bypasses that guard. Pops in dialog actions are independent. An onEnter list cannot push or replace
its own screen, including through nested action lists. {route.name} uses the repeat tokenizer
and bindable fields, condition operands and whole data-pointer segments. Its name must be declared by the enclosing screen; lifecycle actions
use their named screen’s scope. A nested stack’s screen establishes its own scope. The route repeat
alias remains valid in specs without route features; route-enabled specs reserve it for params.
Runtime (shared by PrototypeRuntime on Android and the iOS session; pure helpers in
PrototypeRouteRuntime and its Swift twin):
- Each path entry is
{screen, params}. Push, replace and setStack resolve bindings when the action runs ({item}/{index}were bound to the row when the repeat was instantiated). They must match the route’s declarations exactly after resolution; otherwise the action leaves the stack unchanged. Popping restores the entry below with its own params. {route.name}binds each screen’s subtree in the stack path to that screen’s topmost entry’s params, and its onEnter/onBack lists to the entry’s params when they run. Text renders the value, a whole-placeholder operand keeps its type, and a whole data-pointer segment takes the value escaped per RFC 6901. Binding happens before/dataresolution; the runtime leaves{index}for the repeat that owns it. Screens outside the path stay unbound.screen_changedis emitted once per navigation when the top screen, depth or top params change, withparamsbesidescreenanddepthonly when the top entry has params. The new top screen’s onEnter runs after that event. Each stack’s first screen also enters once per show (not on a stack whose path a same-id show kept; a stack new to that show still enters). Lifecycle lists nest at most 8 deep, so cross-screen onEnter cycles end.- System Back, the iOS edge swipe and a non-forced authored
poprun the top screen’sonBackinstead of popping when the stack is above depth 1. Apop {force:true}always pops, so a confirm that leaves must use it. A screen with onBack shows no predictive-back preview. - Status, inspect and events keep
stacks.<id>.path: string[]and addparams: object[]parallel to it when any entry has params. - A listed
stack:<id>key stores the path as[{screen, params?}]. The storage restorer checks its shape on Android. The runtime restores it when every screen exists and every entry’s params fit. Otherwise it starts the stack atstartand records that path over the stale one. On a fresh iOS show, the restorer also checks screens and param types, drops a stale key asmismatch, and the coordinator removes it rather than recording the start path. A same-id show’s kept paths win over storage. Restoring emits noscreen_changed; the restored top’s onEnter runs as the show’s first entry.
Stack transitions¶
prototype_stack_transitions_v1 gates every explicit stack transition and push/replace
transition override. Omission means platform; pop/popToRoot have no override. The contract
is validated by both agents, and both advertise the capability.
| Value | Platform behaviour |
|---|---|
platform |
Native navigation animation (default). |
slide |
Directional screen slide, reversed on pop. |
fade |
Screen crossfade. |
none |
Instant screen change. |
sharedAxisX |
Sibling steps along a horizontal flow; 30dp travel plus fade. |
sharedAxisY |
Sibling steps along a vertical flow; 30dp travel plus fade. |
fadeThrough |
Unrelated destinations; outgoing fade, then incoming fade and scale from 0.92. |
zoom |
Item-to-detail container transform from the source key into the destination root. |
The four named patterns and push/replace source require prototype_stack_patterns_v1.
Zoom requires source on each push/replace using it, naming exactly one node’s sharedKey or literal shared.key
inside the target stack’s screens. A key referenced as a zoom source is exempt from the two-node visibility-pair rule;
repeat templates remain disallowed.
With prototype_zoom_transition_v1, Android shares bounds from the outgoing source to the incoming
root and iOS 18+ uses native navigation zoom. Older agents use fadeThrough on Android or platform
push on iOS 17, reported in platformNotes. The rendering capability does not add an authoring
requirement: prototype_stack_patterns_v1 still accepts zoom and source.
Platform, slide and zoom support interactive iOS edge pop; only the composed sharedAxisX/Y and
fadeThrough patterns pop non-interactively. Fallback notes are returned on both platforms.
Android predictive back scrubs every pattern, including the zoom transform, and restores the current
screen on cancellation. PopToRoot reverses the entry edge immediately above the returned screen,
using that edge’s zoom source rather than the topmost entry’s source. Without a zoom edge it uses
the stack’s declared pattern.
Shared-axis pop reverses travel; only X also mirrors for RTL. iOS composes axis movement with opacity and fadeThrough removes the outgoing screen visually before revealing the scaled incoming screen. Fixed named timings are 300 ms for movement and 150 ms for fade effects (two sequential phases for fadeThrough); the motion-token table is not available.
Android slides enter from the end edge with 30% outgoing parallax, mirrored in RTL; pop and
popToRoot reverse that direction. Platform replace crossfades. Animations finish within 300 ms.
motion: "none" and animator duration scale 0 snap immediately. The reduced profile (see Motion
profiles) changes every pattern to a crossfade.
Activity hosts scrub the pop with predictive back on API 34+, settle on commit, and restore the
current screen on cancellation. Earlier APIs pop with the ordinary animation. Overlay windows
and authored actions use ordinary transitions. Each path entry owns its scroll offsets, retained
while covered and discarded on pop, replacement or removal. Settled screen containers expose
paneTitle; outgoing content leaves composition and semantics after the animation.
Stack transitions, including a predictive-back scrub, count in the motion-active window signal
(#15114), so observe(waitFor: stable) waits them out.
A stack’s transition is the screen navigation animation only. The stack’s own visibleWhen
uses the default visibility animation; wrap the stack in a box to give that a custom transition.
Motion v2 (#14208, prototype_motion_v2)¶
- Animated style. A node’s
animate: {tempo?}selects a contract spring (see Motion tokens), oranimate: {durationMs?, easing?}selects timing (0–2000 ms, default 300;standard(default),emphasized,linearorspring, which ignores the duration). Either form makes changes to itsalpha,offset,scale,rotation,backgroundandcoloranimate. An example is a heart that grows and turns red when astyleWhenmatches. Withoutanimatethose changes stay instant. - Scale and rotation. Style
scale(0–4) androtation(-360..360 degrees) are drawn about the node’s centre without changing its layout slot, likeoffset;styleWhencan set them. - Transitions.
transitionalso takesslideStartandslideEnd, which slide in from and out to that edge (a drawer), andscale, which scales in with a fade. Start and end follow the layout direction, so drawers mirror in right-to-left locales. - Zoomable images. An
imagewithzoomable: {maxScale}(1–8) pinches between 1 andmaxScale, pans within its own bounds once zoomed, and toggles between 1x and 2x (ormaxScale) on a double tap. TalkBack gets “Zoom in” and “Zoom out” actions. The zoom is clipped to the image’s box and does not change its layout or reported bounds.onTapstill runs; a zoomable image cannot also haveonDoubleTap(rejected at<path>.zoomable). - Reduced motion. Under
motion: "none"or animator duration scale 0, style changes and transitions snap, soobserveand screenshots stay deterministic. Zoom changes are always applied directly.
Android draws scale and rotation with a graphicsLayer, animates with animateFloatAsState and
animateColorAsState, and zooms with transformable. The iOS agent supports and advertises
prototype_motion_v2: animate, style scale/rotation, slideStart/slideEnd/scale
transitions, and image.zoomable. Motion v3 requirements are detected, but iOS does not advertise
prototype_motion_v3, so the host refuses motion v3 features until iOS advertises that capability.
Transition choreography (#15247, prototype_choreography_v1)¶
- Delayed enters.
transitionalso takes{type, delayMs?}(delayMs0-600 ms) in place of the plain name; the enter starts after the delay and runs a 300 ms tween. A delay applies to enters only, so a hidden node still leaves at once. blurReplace. A blur and fade: the node enters from a 12 dp blur that clears as it fades in, and leaves the other way.Modifier.blurdoes nothing below Android 12, which leaves the plain fade there.- Stagger. A
box,roworcolumntakesstagger: {ms, order?}(ms0-100;orderforward(default),reverseorcenter). Its direct children withvisibleWhenenter one after another in layout order, eachmsapart, including the children arepeatmakes. A child’s owntransition.delayMsadds to its stagger wait. - Limit. No child waits more than 600 ms in all. The validator counts the children and a
literal
repeatand rejects a longer wait at<path>.stagger; a data-boundrepeathas no static count, so the renderer clamps the wait to 600 ms instead. - Reduced motion. Under
motion: "none"or animator duration scale 0 nothing animates, so no delay applies andobservesees the settled tree. - Retained subtrees. A large
fadeornonesubtree that the renderer keeps composed while hidden (a scroll list) still fades without the delay.
The render model carries each child’s wait as enterDelayMs (stagger rank times ms plus its own
delay, at most 600), so the stagger is decided with the tree and not while it draws. The iOS agent
does not advertise the capability yet, so the host refuses these fields there.