Prototype web frames for every form factor¶
Frame schema v2 extends the web renderer’s single-screen device frames to foldables in every posture, watches, TVs and cars, and sets how the renderer and a spec behave on each. The registry is described in Prototype web renderer.
Vocabulary the frames reuse¶
The frames reuse what the repository already models, so one vocabulary drives a real device, a spec and the web page:
- Form factors:
phone,tablet,foldable,tv,watchandautomotive(src/models/formFactor.ts). - Panel roles and postures:
inner,cover,rearandexternal;closed,half_opened,opened,rear_display,flippedandtent(src/models/DisplayPanel.ts), the namessetPosturetakes.POSTURE_PANEL_ROLESsays which panel a posture lights. - What a spec can read: platform state
/device/widthClass(compact,mediumorexpandedat 600 and 840 dp on Android;compactorregularon iOS). On Android it can also read/device/posture(flat,tabletoporbook). Both come fromplatformModules.device.statein the prototype contract.
Frame schema v2¶
A v2 frame adds optional fields to a v1 frame; a v1 entry is a v2 frame with one panel.
formFactor: one of the form factors above;phonewhen omitted.panels: a list of screens, each with aroleand the v1 screen fields (screen,cornerRadiusDp,cutout,statusBarDp,navBar,safeArea). The v1 top-level screen fields are panel 0 with roleinner, so an entry lists only its other panels (cover,rearorexternal), each role at most once. The parsed frame’spanelsstarts with theinnerpanel.hinge:{axis: "vertical" | "horizontal", panel, positionDp, widthDp, occluding}, wherepanelis the role of the panel it folds (innerwhen omitted) andpositionDpis the hinge’s leading edge from that panel’s left (vertical) or top (horizontal) edge in portrait. The hinge lies strictly inside the panel.occludinghinges removewidthDpfrom the layout; a seamless fold haswidthDp: 0.postures: for each supported posture, the panel that is active and the hinge angle the web view draws, for example{posture: "half_opened", panel: "inner", hingeDegrees: 90}.mask:rect(default) orround, andinput:touch(default),dpadorrotary. These describe the device, not the renderer’s behaviour.
The source object gains hinge, the hinge geometry’s source (required when a frame has a hinge),
and kinds. The kinds field is a per-field source kind (publicSpec, avdProfile, simulatorProfile or measured)
for screen, insets and hinge, so the registry can mix measured and published values and say
which is which.
Foldables¶
Book-style foldables have a vertical hinge across a wide inner panel. Flip-style foldables have a horizontal hinge across a tall inner panel, with a small cover screen. The two differ in which panel a posture lights and how the hinge splits it.
- What a spec sees. The active panel’s size sets
/device/widthClass. On Android the posture maps to/device/posture:openedisflat, a horizontalhalf_openedistabletop, a verticalhalf_openedisbook. iOS has no posture state, so an iOS frame never sets it. The prototype contract needs no new signal:widthClassandposturealready exist. - Reflow. The still renderer lays the spec out on the active panel. With an occluding hinge it
lays out on the panel minus the hinge, as Android reports the display feature. With a seamless
fold it lays out across the whole panel. A
closedposture on a book foldable and on a flip renders the cover panel. - Changing posture in the page is a fourth view dimension beside variant, revision and orientation, so each posture is pre-rendered like an orientation.
Watches and TVs¶
- Watch. A Wear OS round watch has a
roundmask, which clips the screen to a circle. An Apple Watch keeps therectmask with its corner radius. A watch frame has no status bar or navigation bar. A Digital Crown or rotary bezel is frame decoration (input: "rotary"), not behaviour. A watch iscompactand has no landscape view. - TV. A TV frame has no bezel padding beyond its stand, no status or navigation bar and
input: "dpad". On adpadframe the renderer marks the first focusable element with a focus ring, because a 10-foot UI with no focus is not a usable preview. A focusable element is a spec node, or a part drawn inside one (a tab bar item, a dialog action), whose role is button, checkbox, switch, slider, tab or text box, and not disabled. An open dialog takes focus from the screen below, as on both platforms. A TV is landscape only. - Orientation. A watch draws only portrait; a TV or car draws only landscape and its page opens there. Every frame records its geometry in portrait, so a landscape-only frame is its portrait geometry turned a quarter turn. A frame that draws one orientation has no rotate control, and a still asked for the other orientation is an error naming the one it has. A Compose or SwiftUI preview is sized in the frame’s first orientation.
Cars¶
A car frame is a landscape panel with the system bars the head unit draws. A frame is enough for the still view; driving restrictions (#14922) are device behaviour the web page does not simulate, so a car frame never hides content.
Initial frames¶
The v2 entries match the hardware profiles AutoMobile provisions, so a frame’s geometry can be measured on the same emulator or simulator a session runs on.
| Frame | Platform | Form factor | Postures (active panel) | Geometry source |
|---|---|---|---|---|
| Pixel Fold | Android | foldable, book | closed (cover), half_opened (inner, book), opened (inner) |
pixel_fold hardware profile, the default foldable profile |
| Flip foldable | Android | foldable, flip | closed (cover), half_opened (inner, tabletop), opened (inner) |
the SDK’s horizontal-fold foldable profile |
| Wear OS small round | Android | watch | none | wearos_small_round, the default watch profile |
| Apple Watch | iOS | watch | none | the simulator device type |
| Android TV 1080p | Android | tv | none | tv_1080p, the default TV profile |
| Apple TV | iOS | tv | none | the simulator device type |
| Car 1024p landscape | Android | automotive | none | automotive_1024p_landscape, the default car profile |
No frame lists rear_display, flipped or tent. The phone and tablet frames are v1 entries.
Where geometry comes from¶
Each value records its source. In order of preference: a measurement on an emulator or simulator,
the Android SDK hardware profile (avdmanager list device) or the simulator device type
(simctl list devicetypes, whose profile records the screen size and scale), then a public
specification. A value nobody has measured says so in its source.
Testing¶
Snapshots stay bounded by testing each dimension once rather than their product:
- every frame in its default posture, portrait and landscape where the form factor rotates;
- every posture of each foldable in portrait;
- one reference spec per form factor in the CI browser check.
A unit test asserts that each postures entry names a panel the frame has, at most once per
posture, and that a hinge lies on its panel. The v1 cutout and safe-area checks run on every
panel.