Prototype web renderer¶
The web renderer draws a prototype inside a device frame as one self-contained HTML page. This document covers the per-prototype resources (the page, the embed envelope and the single-file Compose and SwiftUI sources), spec revisions, the page, its browser check, the still renderer and the device frame registry.
The renderer is described across these pages:
- Browser, Android and iOS parity checks
- Still renderer
- Still renderer coverage
- Still renderer coverage of overlays, media and pickers
- Skins, frames and the device frame registry
Resource¶
automobile:prototype/{id}/web{?frame,revision,variant,mcpSessionId} (text/html) is registered in
src/server/prototypeResources.ts and read by readPrototypeWebResource in
src/features/prototype/web/prototypeWebResource.ts.
- Variants. The page’s variants are the ids whose latest revision carries the same
variant.groupas{id}’s, in first-seen order, labelled byvariant.label. An id without a group is the only variant, labelled by its id. Thevariantparameter (default{id}) picks the one shown first and must be in that set. - Revision and frame.
revision(default the latest) is a kept revision of the variant shown first.framedefaults todefaultDeviceFrameIdof the platform that showed that revision, elsepixel-9. - Errors. An unknown id lists the known ids; an evicted revision names the oldest kept; an
unknown revision lists the kept ones; an unknown frame or variant lists the valid ones. All are
ActionableErrors. - Session filter.
mcpSessionIdnarrows the lookup to the revisions that MCP session produced (PrototypeSpecRevisionFilter). The default revision is that session’s latest, andrevisionslists only its own. A revision of another session, or a session with none kept, is anActionableError. The page’s inlined history is not filtered, so variants without a revision from that session still render. - Read result.
_metais{revision, deviceRevision?, mcpSessionId?, revisions, variants, frame, sha256, rendererVersion};mcpSessionIdis the producing session of the revision shown first andrendererVersionis the server release version. - Embed envelope.
automobile:prototype/{id}/embed{?revision,variant,mcpSessionId}(application/json) is read byreadPrototypeEmbedResourceinsrc/features/prototype/web/prototypeEmbedResource.ts. Its text is{format: "automobile-prototype-embed", version: 1, requires, spec}. Thespecis the stored spec of the variant and revision the web page would show first. This host computesrequiresasrequiredPrototypeCapabilities(spec), so the web library can refuse a spec it cannot draw whole (Prototype web library). Variant, revision, the session filter and errors are the web resource’s; there is noframe. Its_metais the web resource’s withoutframe, itssha256hashing the envelope text. - Embed glyphs. When any glyph the spec names resolves, the envelope
carries
glyphs(additive within version 1) and, when any has no glyph,iconMissing, built byprototypeEmbedGlyphsfrom the samePrototypeIconGlyphSourceas the still. The builder collects the keys statically from the contract over the component-expanded spec, not from a render. They cover everyiconNameslot in its object’siconVariant(elsefilled). They also cover the glyphs a control draws with noiconNameslot: filter chip and segment checks, the select arrow, the date picker’s month arrows. Every iconName-valid string instateordataadds a key infilledand in each variant an icon node uses, because a state change can hand that name to any icon. A value is the allow-listed shapes as SVG markup. Both skins draw these Material glyphs (#16526). - Single-file formats.
automobile:prototype/{id}/compose{?frame,revision,mcpSessionId}(text/x-kotlin) andautomobile:prototype/{id}/swiftui{?frame,revision,mcpSessionId}(text/x-swift) are read byreadPrototypeSourceResourceinsrc/features/prototype/prototypeSourceResource.ts. They render theautomobile:prototype/nativehost file (nativePrototypeTemplates.ts) with aninlineinput. It holds the spec JSON as a string constant; Kotlin splits it into joined literals of at most 16 384 characters to stay under the JVM’s 65 535-byte constant limit. It also holds a header comment naming the URI, revision, frame, library coordinate and required capabilities. Per referenced asset it names its bundle path andautomobile:prototype/native/asset?id=…&assetId=…URI (assets are never inlined). Last comes a preview sized to the frame’s screen (@Preview(widthDp, heightDp),#Previewwith.frame). The native resource’s output is unchanged withoutinline. Revision and errors follow the web resource. Theframeparameter defaults todefaultDeviceFrameIdof the format’s platform (pixel-9,iphone-16), since the format fixes the platform. The shader and Swift-equivalent asset id refusals are the native resource’s. Its_metais{revision, deviceRevision?, mcpSessionId?, revisions, frame, sha256, rendererVersion}. - Listing. Each known id gets concrete resources
automobile:prototype/{id}/{web,embed,compose,swiftui}namedprototype-{id}-{format}, titled{id} (web),{id} (embed),{id} (Compose)and{id} (SwiftUI). The server registers them when the id’s first revision appears and unregisters them when the id is evicted. Each change sendslist_changed. List entries carry nosize,annotationsor_meta, because the registry’s entries do not; the read result carries_meta. - Updates. Every new revision, and every byte-cap pruning of another id’s history, sends
resources/updatedfor the parameter-free URI of every format of the id. It also covers the web and embed URIs of each id in its variant group and of each id in the group it left (or was evicted from), in revision order. The concrete resource matches subscriptions exactly, so a subscription with any query (?revision=N,?frame=…) is never notified.
Spec revisions¶
PrototypeSpecRevisions (src/features/prototype/prototypeSpecRevisions.ts) is fed by
PrototypeShownSpecs, so a revision exists exactly when the shown-spec mirror accepts a spec:
endShowstoring a spec records ashow; refused, superseded and poisoned shows, and shows the mirror leaves untracked (persisted/data), record nothing.commitPatchcommitting records apatchwith the reply’srevisionasdeviceRevision. Device data writes record nothing.- Every MCP connection on the daemon shares the store, so each revision keeps the connection
that produced it as
mcpSessionId. That iscurrentConnectionMcpSessionId()at the prototype tool call, the identity autolock and ownership already use. A call with no connection records none. The tool’s show and patch output return the same id so a client can filter by it. It is attribution only: prototype status scopes and the shown-spec mirror stay keyed by device. - Numbers start at 1 per id and never repeat, even after the id is evicted. Each revision keeps a
copy of the spec, the platform of the device, the host clock time and the variant. A show states
its
variantafresh (none leaves the group); a patch keeps the id’s last one.variantis host-only and never sent to the device. - Bounds: the last
MAX_PROTOTYPE_SPEC_REVISIONS(20) per id, andMAX_PROTOTYPE_SPEC_REVISION_BYTES(32 MiB) of spec JSON across ids. Over the byte cap the oldest non-latest revision goes first; when only latest revisions remain, the least recently revised other id is dropped whole. Each id whose history shrinks this way gets aprunedevent, and each id dropped whole anevictedone. - The daemon keeps one store for the process (
daemonPrototypeSpecRevisions), outliving any one prototype host; a host with injected state gets its own. Nothing is persisted across restarts.
Page¶
buildPrototypeWebPage(input) in src/features/prototype/web/webPage.ts returns one HTML
document, its sha256, the frame used, the unsupported nodes of the first view and the revisions
it inlined per variant.
- Views. The page pre-renders every inlined revision of every variant in each orientation the frame
has (portrait and landscape; portrait only for a watch; landscape only for a TV or car). It also renders
every posture of a foldable frame (such views carry
data-posture). When the outermost stack an orientation and posture draws has more than one screen, it renders once per screen of that stack. Screens go start first, then the others in key order, and such views carrydata-screen. This is needed since avisibleWhencan show a different stack in each. - First view. The first view is the chosen variant’s chosen
revision (default: latest) in the frame’s first orientation (
data-orientationonbody). It uses the frame’s default posture and its start screen; the rest arehidden. The budget keeps or drops views by screen index: every orientation and posture’s start together, then each one’s next screen together. Every view renders in the input’slocaleandtextSize, passed to the still. - Controls. Only seven. Rotate switches portrait/landscape; it is absent for watch, TV and car frames, which
have one orientation. A layout posture select (
layout-posture) appears only for a frame with postures, in registry order; switching shows that posture’s views and fits the new view. Zoom and pan offer fit, 50–400 %, wheel, drag and double-click to fit. The opt-in 3D view (Prototype web 3D device view) has posture and hinge controls only for a frame with a hinge and postures. A variant select appears only with more than one variant. A screen select appears only when some revision in the page has more than one screen view. The revision history (newest first,r<N> · show|patch) appears only when some variant has more than one revision in the page. - Screen select. The screen select lists the shown revision’s own screen views and is hidden with fewer than two, so it never offers a view the page lacks. Switching variant or revision keeps the chosen screen when the new revision has it, else shows that revision’s start. Rotating or changing posture relists the shown view’s own screens. Controls are buttons and a select with labels. A toolbar note says the preview is static: taps do nothing, and the controls switch pre-rendered views. Below 720 px wide the history sits under the stage, so the stage keeps the width.
- Script.
prototypeWebPageRuntime, thenprototypeWeb3dRuntime, are inlined from theirtoString()into the one pinned script, so each must stay self-contained. It only shows and hides views, lists the shown revision’s screens in the screen select, moves the stage and animates rotation. UI state stays in memory, with no storage, cookies or URL changes. It must stay at or below 150 KB. - Rotation. Rotate turns the frame 90° (counterclockwise into landscape, clockwise back)
with the Web Animations API. The outgoing view turns away from upright while the incoming view,
pre-rendered in the new orientation, turns in from a quarter turn. Both track one frame, and
the stage’s fitted scale animates with them. Android (
data-platformonbody) cross-fades the content over a 500 ms turn. The iOS frame hands over to the new layout in the first quarter of a 400 ms turn, as its window re-lays out while the bounds animate. The end state is the plain landscape view. A second rotate finishes the running turn first. Theprefers-reduced-motion: reducesetting skips the animation. - Rotation lock.
data-rotation-lock="on"onbodylocks rotation. While locked the app keeps the frame’s natural orientation. Rotate still turns the frame, but the same portrait view turns with it and ends sideways in the landscape frame. The fitted scale uses its turned size. Changing the lock re-lays out in place: the frame does not move, and the outgoing and incoming views cross-fade at their own angles with the platform’s turn timing. Reduced motion skips both animations. Nothing in the page sets the attribute yet; the quick settings tile will. - No network. The CSP is
default-src 'none', the script pinned by its SHA-256, inline styles, anddata:images and fonts. The page references no external URL, and declares an emptydata:icon so no browser requests/favicon.icoagainst that CSP. - Budget. The page is at most 2 MiB. The build always keeps the start screen of each variant’s latest revision and
of the revision shown first, then their other screens while they fit. It adds older
revisions newest first while their start screen and history entry fit, each followed
by its other screens while they fit. It measures the shell (head, toolbar with every screen of the shown
revision, full history list and script) first. If the kept start screens alone do
not fit, the build fails with an
ActionableErrornaming the largest view. - Images.
buildPrototypeWebPageWithImages(webImageEncoding.ts) builds the page once to learn every bound asset animagedraws and its boxes. It reads each asset’s bytes from aPrototypeWebAssetSourceand re-encodes it with sharp (loadSharp) to WebP quality 80 at the largest size the frame draws it. It then builds again with the encoded images. An iOS frame applies the EXIF orientation first, asUIImage(data:)does; an Android frame keeps the stored pixels, asBitmapFactoryignores the tag. - Image boxes. A box is the frame
density times the node’s fixed dp size. The
cropandfillmodes must cover their fixed axes. When one axis is fixed, they also cover theirfillaxes at the screen’s long side (the landscape width). Thefitmode and other unfixed axes fit inside the long side; the image is never enlarged. When the encoded images do not all fit the budget, the build re-encodes assets with such afillaxis, bounding it by the screen’s short side (the portrait width). The page then keeps the longest prefix of images, in budget order, at their long-side encodes that still inlines as many images as all-compact encodes would. - Natural size. An
imagethat wraps both axes, with no weight or authoredaspectRatio, draws at its natural size in points: the source’s oriented pixel size, before any downscale. This holds on every frame and density, as iOS drawsUIImage(data:). Its height follows the aspect ratio, and authored minimums and maximums still bound it. - Image fallbacks. The build skips a missing, non-image
or undecodable asset (logged). It reports one whose data URI alone exceeds the page as
assetOverBudget. The encoded data URIs are capped cumulatively, in budget order, atmaxImageBytes(default: the page budget). The first image past the cap and every later one stay placeholders reportedassetOverBudget, and the later ones are never encoded. The page budget decides which of the rest fit. An image draws more markup than a placeholder. When the second build’s always-kept views no longer fit, the first build stands, its images reportedassetOverBudget. - Image sources. The resource reads assets from the host asset cache of each device currently
showing one of the variants (Android and iOS cache their uploads); without one, images stay placeholders.
Asset ids are chosen per device and the page holds one image per id, so an id two of those
devices cached with different bytes stays a placeholder.
It snapshots the shown variant’s revisions before encoding, so a revision landing meanwhile does
not change the page’s
_meta. - Image budget. Each image is one
:rootrule in the head defining--pa-<slot>(itsdata:image/webpURI),-bg(transparent),-ar(its aspect ratio),-w(its natural width) and-on(1). Views only reference the slot, so view bytes do not depend on which images fit and every orientation and revision shares one copy. A rule is charged once, in this order: the images of the shown revision’s start screen, then of the other pinned start screens, then each screen’s images right after that screen is kept. Within one build an image that does not fit is never retried and draws its placeholder; it is reportedassetOverBudget, and one with no bytesassetNotInlined. - Determinism. The same input yields byte-identical HTML.