Prototype web library¶
The goal is to ship the prototype web renderer as an npm library any website can use to embed a
prototype in a device frame. It is the web member of the embeddable renderer family (#13720) beside the
Compose library and the AutoMobilePrototype Swift package
(Native prototype embedding). Prototype web renderer
describes the renderer itself.
packages/prototype-web/ (@kaeawc/auto-mobile-prototype-web) is not published yet, and there is
no interactive runtime. The planned release is in the devlog entries under Background.
Package¶
packages/prototype-web/holds onlypackage.json(no dependencies), the entriespackages/prototype-web/src/index.tsandpackages/prototype-web/src/element.ts, their hand-written public typesindex.d.tsandelement.d.ts, andbuild.ts. It is not a Bun workspace, so the rootbun.lockand the pinned runtime graph do not change.bun run buildin that directory bundles each entry on its own withbun build --target=browserintodist/index.jsanddist/element.js(gitignored).dist/element.jsis the package’s only side effect. The library source issrc/features/prototype/web/embed/.- The same build bundles the page entry
packages/prototype-web/src/page.tsinto the committedsrc/features/prototype/web/prototypeWebPageBundle.generated.ts. The entry holdsmountand a boot that mounts the options in the page’sscript[type="application/json"][data-prototype-page]on its[data-prototype-host]. The functionprototypeWebPageBundle()reads that file and never bundles at request time. Nothing serves it yet: the prototype web resource still returns the static page frombuildPrototypeWebPage, with no script. - The file carries a version mark where the bundle names the root
package.jsonversion. The functionprototypeWebPageBundle()replaces the mark with the release’s version, so a version bump does not change the file. - The test
prototypeWebPageBundle.test.tsrebuilds the file and fails when the committed one differs. Regenerate it withbun run buildinpackages/prototype-web/, or compare withbun build.ts --check. - Every export has one budget: 500,000 bytes of HTML, JS and CSS counted together, minified, with
no gzip limit (
MAX_PROTOTYPE_WEB_EXPORT_BYTESinbuild.ts). The build refuses to write an export over it, and the bundle tests fail on one. test/features/prototype/web/prototypeWebPackage.typecheck.tsassigns each export and public type both ways betweenindex.d.tsand the implementation, so the typecheck fails when they drift.prototypeWebLibraryBundle.test.tsis the boundary check. Each entry’s browser bundle reaches no Node builtin and stays within the export budget above, and the element adds at most 8,000 bytes overindex. Its only inputs aresrc/features/prototype/, the CtrlProxy protocol constants and the rootpackage.json, whoseversionis the library version.webLibrary.integration.test.ts, run byPrototype Web Screenshots, mounts the library build in Chromium and compares its pixels with the still’stoHtmloutput drawn the same way. It also draws<automobile-prototype>from the element build and compares it withmount.
API¶
renderPrototype(spec | envelope, options)is pure: it returns the still’s element tree, the frame and orientation drawn,unsupportedNodesand the outermost stack’s screens (start first). It throwsPrototypeWebRefusalcarrying{code, message, missing, libraryVersion}.mount(element, options)attaches an open shadow root and builds the DOM withcreateElement,setAttributeandstyle.setProperty, neverinnerHTML. Its shell stylesheet is a constructable stylesheet. It returns{update, destroy, state};updatemerges options, keeping zoom, orientation and screen, and an unknown screen draws the stack’s start.- Options:
spec,frame,orientation,zoom,mode,screen,controls,localeandtextSize. - The frame is an id, a frame object, or
falsefor the default frame’s screen alone. A frame object is adeviceFrames.jsonentry withoutsource.prototypeWebFrameObject.tschecks it without zod. It applies the registry schema’s fields, ranges and cross-field rules (deviceFrameRules.ts), and a unit test keeps the two in agreement. - Zoom is
fitor a scale from 0.5 to 4. - Mode is
light,dark, orsystem, which followsprefers-color-scheme. - Controls are
false, or any ofrotate,zoomandscreen. - Callbacks:
onRender(unsupportedNodes),onScreenChange,onOrientationChange,onZoomChangeandonError. - The host element is 640 px tall unless the page sets its height;
fitscales the frame into the viewport below the controls and refits on resize.
Element¶
Importing @kaeawc/auto-mobile-prototype-web/element registers <automobile-prototype>, once and
only where customElements exists. PrototypeElementController (embed/prototypeWebElement.ts)
holds its logic; the class in packages/prototype-web/src/element.ts only forwards its lifecycle.
- Attributes
frame,orientation,zoom,mode,screenandcontrolsset the scalar options. - The
frameandcontrolsattributes takefalseornoneto turn them off. - The
controlsattribute lists names separated by spaces or commas. - The
zoomattribute isfitor a number. An unknownorientationormodeis ignored. - The spec comes from the
specproperty, else the first child<script type="application/json">. It is never read from an attribute or fetched. Unparseable JSON draws theinvalidInputerror view. Aspecset before the module defined the element is replayed through the setter on upgrade. - It mounts when connected with a spec and destroys the mount when disconnected. Connected without one, it watches its children and mounts once a JSON script arrives. While the page is still parsing, it waits for the script’s text to parse; after that, invalid JSON draws the error view.
- A changed attribute passes on only its own option, so the toolbar’s orientation and zoom stay.
A changed spec updates the mount. A removed attribute mounts afresh, because
updatekeeps an option it is not given. - Events are
CustomEvents carrying themountcallback’s detail:render,screenchange,orientationchange,zoomchangeanderror. Events fired while the first mount draws are dispatched once it returns, so a listener can set the spec or remove the element.
Refusal¶
- An envelope with a
versionother than 1, or whoserequiresnames a capability outsidePROTOTYPE_WEB_CAPABILITIES, draws an error view (role="alert") and callsonError. PROTOTYPE_WEB_CAPABILITIESis generated fromknownPrototypeCapabilities()byscripts/prototype/generate-prototype-web-capabilities.ts; a unit test fails when it is stale.- A bare spec is drawn without a capability check. An unknown frame, an invalid frame object (the
message names each problem’s path), an orientation the frame lacks or an invalid locale is
refused with
invalidOption. - Envelope glyphs are parsed with the browser’s
DOMParserinto allow-listed SVG shapes; without one (in a worker) icons draw the placeholder.
Browser-safe still renderer¶
renderPrototypeStill(src/features/prototype/web/webStill.ts) is a pure function from spec, frame, orientation, mode and screen to an element tree. It runs no actions, timers or requests and serializes deterministically. The page runtime (webPageRuntime.ts) only switches pre-rendered views and moves the stage.renderPrototypeStillandtoHtmlbundle for the browser with no Node builtin. To keep the closure small and browser-safe:- element builders share repeated style-property names, attribute names and style values as
identifiers from
webCss.ts, so each long literal is bundled once; - device-frame provenance lives in
deviceFrameSources.json, the string-table zod schema inprototypeStringsSchema.tsand the frame schema indeviceFrameSchema.ts, all outside the closure; - the closure reads only the contract values in the generated
prototypeRenderContract.generated.ts, not the whole contract JSON; - the derived-format path takes an optional injected logger instead of importing the server’s;
- an invalid locale, text size or frame throws a plain
PrototypeWebInputError, which the server’s page builder and resource readers rethrow as anActionableErrorwith the same message. test/features/prototype/web/stillBrowserBundle.test.tsfails on any Node builtin, the contract JSON, zod, the server logger orActionableErrorin the closure. It also fails on a bundle over 500,000 bytes of HTML, JS and CSS counted together, minified (no separate gzip limit).
Embed envelope¶
automobile:prototype/{id}/embed serves {format: "automobile-prototype-embed", version: 1,
requires, spec}, where requires is requiredPrototypeCapabilities(spec) computed by the host
that validated the spec, so a web renderer can refuse a spec it cannot draw whole. Its revision,
variant and error rules and its glyphs and iconMissing fields are described under “Embed
envelope” in Prototype web renderer.
Action trace fixtures¶
test/fixtures/prototype-spec/action-traces/ holds shared traces: a spec, then steps that each run
one tap’s actions or advance a fake clock, with the expected state, /data, stack paths, pager
pages and shown flag after each step. The TypeScript tests (prototypeActionTraces.test.ts), the
Android runtime tests (PrototypeActionTracesTest) and the Swift agent tests
(PrototypeActionTracesTests) each run every trace. A trace one platform cannot run yet is listed
under that platform in action-trace-skips.json with its issue, and a skipped trace that passes
fails the run, so the list only shrinks.