Prototype spec: patch and presentation¶
Part of the agent-authored prototype specification.
Patch (#11675)¶
Use show for a new screen or a window, theme or root change. Use patch for
content (/data), state (/state) or one node by id (replaceNode). Android CtrlProxy advertises
prototype_patch_v1 and applies patches in place; the iOS prototype agent advertises it too
(a relaunched app loads the current agent), so an older agent still needs the whole spec with show.
{action:"patch", id, ops, baseRevision?} sends a patch_prototype frame
{requestId, id, baseRevision?, ops} only to a device advertising
prototype_patch_v1. Android and iOS use prototype_result replies. Success
carries revision; a state conflict carries
{success:false,error,conflict:{revision,state:{key:scalar}}}. Revisions are
non-negative safe integers; conflict values are strings, booleans or finite
numbers with valid state keys. Malformed reply fields are dropped. Each shown
prototype’s status and inspect entry carries revision: the newest one the host
saw, from a landed patch reply or a device /data write event, never moving back. It
is absent until one arrives after the show; the device’s inspect reply has no revision
of its own, so inspect keeps the host’s.
Ops apply in order, completely or not at all. The ops add, replace, remove and
test address /data or /data followed by an RFC 6901 JSON pointer. In the pointer, ~0
escapes ~ and ~1 escapes /. Array indices are canonical non-negative decimal
integers, and - appends for add only. Parent paths must exist. The ops replace,
remove and test require the addressed value to exist. The ops add, replace and
test carry value, and remove does not. State ops address exactly
/state/<key>, where keys match [A-Za-z_][A-Za-z0-9_]{0,63} and values are
strings, booleans or finite numbers.
replaceNode carries {op:"replaceNode",id,node}. The id must identify exactly
one node in the tree, cannot be the root or inside a repeat, and the replacement
must keep that id. Replacement nodes cannot contain use nodes or element
anchors. Inline the component, use a bounds anchor, or use show.
The agent writes data, and the user writes state. Data-only patches and patches
containing only data ops and replaceNode ignore baseRevision. That holds until the device has written the
prototype’s data with a data action (see Data actions). From then on a
/data op also needs baseRevision and conflicts with newer overlapping device writes. Any state
op, including test, requires baseRevision. A device supporting the capability
must refuse the whole patch with conflict if the user changed a touched state
key since that revision, returning the current revision and those keys’ values.
There are at most 64 ops, the frame is capped at 1 MiB, and the resulting whole
spec must satisfy every spec/data limit, including node count and depth. The
host tracks a cloned copy of each id’s device spec from its last acknowledged show,
with components expanded and anchors resolved. It applies ops to a copy and
runs the full validator before sending. Errors preserve deterministic paths.
The host validates state ops against the agent-declared state and leaves value
comparison for /state test to the device; its copy cannot know user edits.
Patches are FIFO per device, one in flight at a time. A pending show makes patch refuse as busy, and patches do not delay shows. If a dispatched show and an acknowledged patch overlap, their device-side order is unknown. The host then forgets its spec, warns, and requires a further successful show before patching. A failed dispatched show, dismissed event, successful dismiss, session release, device removal or unbinding also ends tracking.
Inspect retains each reported tracked id and drops missing ids (adopted siblings do not end tracking); a fifth-surface refusal with replaceOthers: false retains the acknowledged specs. A timeout or connection loss after dispatch is indeterminate and requires a new show; a failure before dispatch keeps the tracked copy; an atomic device refusal leaves it unchanged. A successful patch refreshes shown status data and sets the entry’s lastAction to patch (kept by a later inspect, reset by the next show), without changing lastResult, timestamps or event snapshots.
Re-showing a prototype¶
show_prototype always carries a full spec, and patch_prototype is the gated content/state/node contract (#11675).
When spec.id is the prototype already on screen and reset is absent or false,
the device replaces it in place. It keeps the display the prototype is on and ignores the
request’s displayId. Each pager keeps its settled page,
matched by pager id and clamped to the new page count.
The new spec’s state
is authoritative. The device drops values the user changed by tapping or typing
unless the spec includes them. The exception is the keys the spec’s storage block lists, whose
stored values replace the spec’s (see Storage). The device rebuilds the window content from the new
runtime, so a text field shows the spec’s value and the device drops edits still in flight from
the previous showing. Event sequences continue per id, as for any
re-show.
A fresh show happens on reset: true, a different id, or nothing on screen:
pages start from the spec and the device uses the requested display. The host sends reset only
when true. A device that predates it ignores the field and always starts
fresh. The host reports a display that a same-id show ignored as a warning
on the tool result.
Presenting alternatives¶
The host has no carousel helper. Show
one design with show and discuss the others in chat, or show one spec whose pager holds every design
with a visible label per page (see the full-screen pager example). Nothing waits on the device for a
choice.
Device destination policy¶
via: "device" requests on Android pass PrototypeEgressPolicy, which checks the URL host before any
DNS lookup, every resolved address, and the address of the connected socket. A refused destination
fails the request with blocked_destination. It refuses:
- the names
localhostand*.localhost, and a numeric host that is not a valid IPv4 or IPv6 literal; 0.0.0.0/8, loopback (127.0.0.0/8,::1), the unspecified IPv6 address, link-local (169.254.0.0/16,fe80::/10), site-local IPv6 and Teredo;- the emulator’s host-machine aliases (
10.0.2.1to10.0.2.6, and Genymotion’s10.0.3.2); - IPv6 forms that embed a refused IPv4 address (IPv4-compatible, IPv4-mapped, SIIT, both NAT64 prefixes and 6to4);
- ports 3000-3010 (the daemon’s range) and 8765 (CtrlProxy) on a private address (
10/8,172.16/12,192.168/16,100.64/10,fc00::/7).
The host makes no adb reverse for a prototype, so localhost on the device never reaches a host
server. A prototype reaches a host-local server with via: "host", or with via: "device" at an
address the device can reach that the policy permits. The session-scoped portReverse tool is
separate and does not change this policy. iOS simulators apply the agent’s own
destination policy, which also refuses loopback.