Prototype web preview¶
Read a prototype as a web page, or keep a live browser preview open while an agent iterates. You can also export the page to a file, or take the spec with its renderer requirements. To put a prototype in a real app, see Embedding a prototype in an app.
Preview as a web page¶
To look at a prototype without a device or an app, read automobile:prototype/<id>/web. It is one
self-contained HTML page (text/html, no network access) with:
- the prototype in a device frame
- rotate and zoom controls
- a screen picker when the prototype’s stack has more than one screen
- its revision history
| Parameter | Meaning |
|---|---|
frame |
A device frame id such as pixel-9 or iphone-16. Defaults to the platform that showed the prototype. |
revision |
A kept revision. Defaults to the latest. |
variant |
The prototype id of the alternative to show first (see below). |
mcpSessionId |
Only revisions this MCP session produced (see below). Defaults to every session’s. |
Revision 1 is the first show of the id. Each later show and each patch that lands adds one; taps and typing on the device do not. AutoMobile keeps the last 20 revisions. Asking for an older one returns an error that names the oldest kept revision.
The result’s _meta reports:
| Field | Meaning |
|---|---|
revision |
The revision shown. |
deviceRevision |
The device’s own counter for that patch. |
mcpSessionId |
The MCP session whose show or patch produced the revision, when it had one. |
revisions |
The kept revisions. |
variants |
The alternatives in the prototype’s variant group. |
frame |
The device frame drawn. |
sha256 |
The page’s hash. |
rendererVersion |
The renderer that drew the page. |
Every MCP session on the daemon shares one revision history, so another session’s show can land
between yours and your read. A successful show or patch returns mcpSessionId. Pass it as the
mcpSessionId parameter to read only your session’s revisions:
- The default revision is then your latest.
revisionslists only yours.- A
revisionanother session produced is an error.
The page itself still offers every kept revision.
Images draw the assets uploaded with the prototype to an Android device that is still showing it, re-encoded at the size the frame draws them. The page stays under 2 MiB, and the revision shown first gets its images before older revisions. A grey placeholder replaces an image that does not fit, or whose asset the server does not have (iOS uploads, or no device showing the prototype any more). Upload the assets again with the next show to bring them back.
resources/list lists automobile:prototype/<id>/web for every prototype shown in this daemon
session. Subscribe to that URI, without parameters, to hear about every new revision. A
subscription to a URI with revision= never gets another notification.
To compare design alternatives, show each under its own id with the same variant group, for
example variant: {group: "checkout", label: "Compact"}. The web page of any of them offers every
alternative in the group by its label. The device keeps showing whichever was shown last.
Live preview in a browser¶
To keep a browser tab on a prototype while an agent iterates, call prototype with
{action: "serve", id: "<id>"}. It needs no device request and works the same on a device and in
headless mode. It returns previewServer with pageUrl (the live page
for that id) and url (an index of every prototype shown in this daemon).
Each show and each patch that lands reloads the open page within about a second, keeping the
variant picked in its switcher. The page is the same HTML as automobile:prototype/<id>/web. Add
?frame=<frame id> or ?variant=<id> to the page URL to choose them. Serving an id not shown yet
succeeds with a warning, and its page loads once it is shown.
| Parameter | Meaning |
|---|---|
id |
The prototype whose page URL to return. Optional: without it, use the index url. |
port |
TCP port, 0 to 65535. 0 or absent picks a free port. If the port is in use, the call fails: pass another port or omit it. |
remote |
true binds every network interface so other machines can open the preview at this host’s address. Anyone who can reach the port sees every shown prototype. Default false: 127.0.0.1 only. |
idleTimeoutMs |
Stop after this long with no open preview page and no request, show or patch. 1000 to 86400000, default 1800000 (30 minutes). |
One preview server runs per daemon and every MCP session shares it. Calling serve while it runs
returns the same server; a different port or remote value restarts it on the new address. A
loopback server answers only requests addressed to 127.0.0.1, localhost or [::1].
{action: "stop"} closes the port and the open pages’ connections. The server also stops when the
daemon exits, and after the idle timeout. After the first serve, status reports
previewServer: running, url, port, host, remote, idleTimeoutMs, or stoppedReason
(stop, idle or daemon). After the server stops, call serve again for a new URL.
Export the web page to a file¶
To host the page, attach it to a CI run or send it to someone without a device, call the
exportPrototypeWeb tool. It is off by default: enable it with setToolEnabled (see
Dynamic tools). It needs no device. It writes the same bytes the
automobile:prototype/<id>/web resource returns for the same parameters, with no network access
and the same Content Security Policy. It returns the file’s details instead of the HTML.
| Parameter | Meaning |
|---|---|
id |
The shown prototype’s id. Required. |
frame, revision, variant, mcpSessionId |
As for the resource above. |
outputPath |
An absolute .html file path, or a directory (an existing one, or a path ending in /); any other path is refused. Defaults to prototype-web/ in the AutoMobile data directory. In a directory the file is named <id>-<frame>-r<revision>-<hash>.html. |
overwrite |
true replaces an existing file with different content; a symlink at outputPath is replaced, not written through. Without it the call is refused and nothing is written. A file that already holds the same bytes is left as it is. |
The result is {path, sha256, bytes, frame, revision, variants, rendererVersion}. sha256 is the
hash of the written file and matches the resource’s _meta.sha256. The page already offers every
variant in its group, so one file covers the whole set.
Errors name what to change:
- An unknown id lists the known prototypes.
- A revision older than the kept 20 names the oldest kept one.
- An unknown frame lists the valid frames.
- A relative or unwritable
outputPathasks for a writable absolute path. - A file path that does not end in
.htmlasks for an.htmlfile or a directory.
Embed envelope¶
To take a prototype’s spec together with what it needs from a renderer, read
automobile:prototype/<id>/embed (application/json). It returns:
{
"format": "automobile-prototype-embed",
"version": 1,
"requires": ["..."],
"spec": { "...": "..." },
"glyphs": { "filled/home": "<path d=\"...\"></path>" },
"iconMissing": ["filled/..."]
}
spec is the prototype’s spec, and requires lists the renderer capabilities it needs, as this
server computed them. Keep the two together: a renderer that lacks a listed capability should
refuse the spec rather than draw part of it. A version other than 1 is a newer format.
glyphs is present when the spec names an icon that has a glyph. It maps <variant>/<name> to the
Material Icons glyph’s shapes, as SVG markup for a 0 0 24 24 viewBox, so a renderer needs no icon
set of its own. It covers:
- every icon the spec’s icon fields name, in the icon’s
variant(elsefilled) - the glyphs controls draw on their own: a filter chip’s or segment’s selection check, a select’s dropdown arrow and a date picker’s month arrows
- every icon name that appears as a string in
stateordata, infilledand in each variant the spec’s icons use. An icon whose name changes with state still has its glyph.
A variant without that glyph carries the filled one. iconMissing lists the keys with no glyph
at all; draw a placeholder for them. The same glyphs serve Android and iOS frames.
revision, variant and mcpSessionId work as for the web page; there is no frame. Errors,
listing and subscriptions also match the web page, and _meta reports the same fields except
frame.
Derived collections¶
Use a top-level derive entry such as
{"results":{"collection":{"of":{"data":"/rows"},"where":[{"field":"name","op":"contains","value":{"state":"query"}}],"sort":{"field":"name","order":"asc"},"limit":50}}}.
Bind rows with repeat.items: {"derived":"results"}. Collections preserve the original objects,
filter before sorting and limiting, and scan at most 500 items. Non-array sources yield no rows.
Up to four clauses combine with AND; operators are contains, eq, neq, gt, gte, lt, and lte.
Clause values read state or a literal string/number. Missing fields and type mismatches do not match.
Add reduce: {"op":"count"} or {"op":"sum","field":"amount"} (also min or max)
to produce a scalar after limiting; empty reductions return zero. Scalars support format.
Collections require prototype_derive_v1; update a renderer that refuses this capability.