Prototype web renderer: skins, frames and frame registry¶
Part of the prototype web renderer.
- Posture. A foldable frame draws the panel its
posturelights. The default isopened, else its first posture. A frame without postures takes none, and an unknown posture is an error listing the frame’s. Theclosedposture draws the cover panel. The spec lays out on that panel in the drawn orientation, minus an occluding hinge’s width. It shows in the two segments either side of the hinge (the second copyaria-hiddenand inert). A seamless fold lays out across the whole panel and draws a crease shaded by itshingeDegrees, none when flat. Landscape turns the hinge with the panel, so a flip’s hinge runs top to bottom there. - Skins.
webSkin.tsholds one skin per platform. The frame’s platform picks it, and theskinoption overrides it. A skin replaces the renderers of the components its platform draws natively (designCoveragenativeinschemas/prototype-spec-contract.json). It also replaces those of the Material components the iOS renderer draws with SwiftUI defaults. Every other component draws the shared Material 3 renderer on both. Only the iOS skin reads a node’siosnamespace, and only the Android one reads itsandroidnamespace. The Android skin replaces nothing. The iOS skin draws these components: button: the iOS renderer’s SwiftUI styles at the regular control size, in the 17 px body style (scaled by the frame’s Dynamic Type size) and tinted with the theme’sprimary. Thefilledstyle is a 6 px-radius tint fill under white text with 7x12 px padding. Thetonalstyle is the tint at 0.15 opacity under tint text, andelevatedis that with a 1 px shadow. Theoutlinedstyle is a 1 px tint capsule with 8x16 px padding, andtextis bare tint text. Theios.buttonStylefield drawsglassProminentas a filled andglassas a tonal capsule, without blur.slider: the system slider. Its label sits 4 px above a 28 px row. The row’s 4 px track is systemBlue up to the value and systemFill after it. A white 28 px thumb sits over it, and the thumb’s centre travels 14 px inside each end. The value is its state, elsemin, clamped and not snapped.- Material components follow the iOS renderer’s SwiftUI views. Text sizes are
body 17, subheadline 15,
.title320,.title28 and.largeTitle34 px, scaled by the frame’s Dynamic Type size. Like the iOS renderer, the skin ignoresios.navigationTitleandios.sheet.sizing. switch: a body label filling a 44 px row before a 51x31 capsule track (primaryon,surfaceContainerHighestoff) with a 27 px thumb.checkbox: a 17 px check square, filled when checked, 8 px before its label.listItem: a body headline over a subheadlineonSurfaceVariantsupporting line, 56 px tall or 72 px with one. Its trailing control is that switch track or check square.chip: 32 px with 12 px padding in the medium subheadline style and the content colour, in a 44 px target.topAppBar: a 64 px row padded 4 px with 48 px icon buttons. Its title is a.title3semibold title (12 px in, 4 px after a navigation icon), or a.title(medium) or.largeTitle(large) line below the row. With anenterAlwaysorexitUntilCollapsedonScroll, it is framed at 48 or 88 px.card:surfaceContainerHighwhen filled, elsesurface, with anoutlineVariantoutline when outlined.textField: a field with a label, variant, supporting text ormaxLengthputs its.footnoteonSurfaceVariantlabel 4 px above an input padded 12 px. Below the input sits a.captionrow of supporting text and thecount/maxcounter. Thefilledvariant is asurfaceContainerHighestfill with 4 px top corners over a 1 pxoutlineline. Theoutlinedvariant is a 1 px 4 px-radiusoutlinestroke. Either turns red on an error. Any other text field is a rounded-border input. The label never floats, an empty field shows only its placeholder, icons sit 4 px beside the field and the error message is a red.captionline below it.bottomNav: items spaced 8 px onsurfaceContainer, padded 12 px above and 4 px below. Each item is a 64x32secondaryContainercapsule over a.captionlabel (semibold when selected, else medium) in at least 64 px.tabBar: no background or divider. Each tab is its icon over a.captionlabel, 2 px apart, at least 44 px tall (64 px when it minimizes), the selected one in a capsule.bottomSheet: an iOSbottomSheetcentres its child 8 px below a 36x5 handle 6 px from the top, onsurfacewith a 16 px radius.timePicker,datePickerandpasteButtonare still placeholders on both skins.- Frame. The screen has the frame’s size for the orientation, its corner radius and bezel, a
generic status bar and the cutout (an
islanddraws as a pill, a punch hole as a circle). It also has the navigation chrome. Android draws its handle (data-nav="handle") or three generic button marks, which move to the right edge in landscape when the frame reserves that inset. iOS draws its home indicator (data-nav="homeIndicator"). - Status bar: the status bar is never a picture of a real OS. It is a clock and generic
cellular, Wi-Fi and battery marks (
data-statuswith adata-level) drawn from a fixed state (9:41, four bars, Wi-Fi on, full battery). In the interactive page the runtime rewrites every clock from the browser’s local time in the sameh:mm12-hour form, re-armed at each minute boundary. An iPhone with an island centres the clock and the marks in the ears beside it, and Android puts them at the start and end. Its content is light or dark:window.statusBarlightordarkpicks it. Withautoor none, it takes whichever of white or black contrasts more with the app’s top colour. - Top colour: the top colour comes from geometry, not from reading CSS properties one by one. A small layout pass places the window’s content on the screen, then samples evenly spaced points along the screen’s top edge. The pass handles flex lines with growth and shrink, gaps, arrangement and alignment, and a reversed line placed from its end. It also handles one-cell boxes, collection grids’ column tracks, block flow, minimum and maximum sizes, aspect ratio, and padding including the safe-area insets. It also handles absolute insets, relative offsets and translations, overflow clips, corner radii, and CSS paint order with z-index.
- Rounded corners: a point in a rounded corner’s cut-away region is outside the box. Neither its background nor its overflow clip’s descendants paint there, so a circle meets the top edge at one point. Logical corners follow the element’s direction, so right to left rounds the opposite side. A box of unmeasured height keeps square corners, because its real height could scale the radii down.
- Sampling: at each point the colour is the
last opaque background painted there, else the screen background. The colour at the most
points wins. Element opacity multiplies down the tree, so a background counts only when it is opaque
after that opacity. A fully transparent subtree paints nothing. The window placement is part of the
layout, so only what a window paints at the top edge counts. A bottom sheet or a small centred floating
window leaves the screen background there, while a wide floating panel at
topStartthat reaches the edge sets the colour. - Unmeasured content: the pass does not measure text and other unsized content. It takes an unknown height or offset as non-zero. A content-sized width covers nothing, but a wrapper whose in-flow children all have measurable sizes takes their stacked or largest size, padding included. A flex item whose automatic minimum depends on that content does not shrink. A box, row or column child with no self-alignment starts at its container’s start as the renderer emits it. The pass does not lay out a subtree that starts below the top edge inside an overflow clip, or behind a transform other than a translation.
- Landscape: landscape swaps the screen size, uses the landscape safe areas, and moves the cutout from the top edge to the left edge. A frame whose landscape top inset is 0 (an iPhone) draws no status bar in landscape.
- Safe areas:
safeAreaPaddingadds the inset on each named edge to the node’s padding. LikewindowInsetsPadding, an edge an ancestor already applied adds nothing more. An inset adds to a component’s own padding on that edge (imeadds nothing, since the still has no keyboard). The renderer exposes safe areas as--safe-top,--safe-bottom,--safe-leftand--safe-right. Both devices draw a window’s content edge to edge, and a top app bar takes no inset of its own. So it clears the status bar only throughsafeAreaPadding. Likewise content clears the landscape cutout side (an iPhone’s 59 pt left inset) only throughsafeAreaPaddingon thestartedge. - Determinism. Serialization writes attributes and style properties in sorted order, so the same input renders the same bytes. Event-handler attributes are rejected.
Device frame registry¶
src/features/prototype/web/deviceFrames.json is data only: adding a device is one entry, with
no code change. The file deviceFrameSchema.ts holds its strict schema, and the registry’s unit test
validates every entry. So an invalid entry fails CI instead of rendering wrong geometry. Nothing
validates the registry at load. Instead deviceFrames.ts stays free of zod so the still renderer
bundles for the browser (see Prototype web library), and fills the
schema’s defaults and inner panel itself. A unit test holds that result equal to the schema’s
parse.
It is called a frame registry, never a device profile, because deviceProfile already means
the session broker’s OEM manufacturer profiles.
Each entry records:
screen: portrait width and height in dp (points on iOS) and the density.cornerRadiusDp, thecutout(none,punchHole,notchorisland, with its geometry),statusBarDpand thenavBar(none,gestureorbuttons).safeAreafor portrait and landscape. Landscape is stored, not derived, because a cutout and the navigation bar move to different edges on each platform.frame: the bezel width and colour drawn around the screen.source: where the screen geometry and the insets came from. Values not yet measured on an emulator or simulator say so, and replacing them with measured values is a data change. Sources live indeviceFrameSources.json, keyed by frame id, because only the schema test reads them; the renderer importsdeviceFrames.json, so provenance stays out of the browser bundle. The test validates each entry with its source merged back in, and rejects a frame without a source or a source naming no frame.
Beyond the schema, a registry is invalid when two entries share an id, a cutout lies outside the portrait screen, or a safe area leaves no screen in either orientation.
When a request names no frame, the default is pixel-9 for Android and iphone-16 for iOS. An
unknown frame id is an error that lists the valid ids.