Prototype live preview server¶
The prototype tool’s serve and stop actions run a small HTTP server that shows a prototype’s
web page in a browser and reloads it on each show and landed patch.
Components¶
PrototypePreviewPageSourceis the only thing the server reads: prototype ids, an id’s related ids (its variant group), the page HTML, and a change signal. The default source wraps the spec revisions theautomobile:prototype/<id>/webresource reads, so the served page is that resource’s HTML, byte for byte, and a change is a recorded revision (or an eviction).PrototypePreviewServerowns the lifecycle: bind, stop, idle timeout, and the event streams. Its socket goes throughPreviewHttpBinder(node:http in production, an in-process fake in unit tests) and its timers through the injectedTimer.daemonPrototypePreview.tsholds the daemon’s one server, so the daemon’s shutdown stageprototype preview serverstops it without loading the prototype runtime.
Routes¶
| Path | Content |
|---|---|
/ |
Index of ids with web output |
/p/<id> |
Shell: the page in an iframe plus the reload script |
/p/<id>/page |
The web resource HTML; frame and variant query parameters pass through |
/p/<id>/events |
Server-sent events: ready {generation} on connect, reload {id, generation} |
Browsers drop the dot segments . and .. from a path, even escaped as %2e. So for those two
ids every link uses the query form /p?id=<id> with view=page or view=events. The parser
accepts both forms for any id.
The web page’s CSP allows only its own runtime script and no network, so the page is never
modified. The reload script lives in the shell, whose CSP pins that script’s hash and allows
connect-src 'self' and frame-src 'self'. The shell renders the iframe without src and loads
it on the first ready (or on a stream error before one). The shell therefore requests the page
only after it subscribes to the stream, and a change between the two cannot go unseen. On reload
the shell reads the variant picked in the same-origin iframe and reloads the iframe with it. The
generation field counts changes: a later ready with a
different generation means a change was missed, and the shell reloads.
A page for P gets reload when the changed id is P, is in P’s variant group now, or was at
the previous change. A variant that leaves the group therefore still reloads its pages once.
Invariants¶
- One server per daemon.
serve,stopand the idle stop are serialized, so concurrent calls from several MCP connections never leave two sockets bound.servewhile running keeps the server unlessportorremotediffer. - A loopback server answers only
Hostvalues127.0.0.1:<port>,localhost:<port>and[::1]:<port>(421 otherwise), which refuses DNS rebinding.remote: truebinds0.0.0.0and skips the check. - Idle means no open event stream and no request or change for
idleTimeoutMs; an open tab keeps the server alive. A 15 s SSE comment keeps open streams from idling out of intermediaries. - Stop ends every event stream before closing the listener (
closeAllConnections), so the port is free when the call returns.
Headless mode¶
Headless mode (#17974) needs no source of its own. A show or patch on the virtual device runs the
same Android path as a device. The status store records it into the daemon’s spec revisions, and
the default PrototypePreviewPageSource serves it and signals the reload. The serve and stop
actions are host-only. In every mode the registration’s shouldEnsureDevice skips device
resolution for them (and for screenMap, share and the mock-backend actions). The
nonDeviceHandler runs them on the virtual device, so a disconnected device cannot block the
preview. Outside headless mode their results carry no virtualDevice report. The status action
still resolves a device, because its entries are
scoped to the device that showed them.