Skip to content

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, watch and automotive (src/models/formFactor.ts).
  • Panel roles and postures: inner, cover, rear and external; closed, half_opened, opened, rear_display, flipped and tent (src/models/DisplayPanel.ts), the names setPosture takes. POSTURE_PANEL_ROLES says which panel a posture lights.
  • What a spec can read: platform state /device/widthClass (compact, medium or expanded at 600 and 840 dp on Android; compact or regular on iOS). On Android it can also read /device/posture (flat, tabletop or book). Both come from platformModules.device.state in 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; phone when omitted.
  • panels: a list of screens, each with a role and the v1 screen fields (screen, cornerRadiusDp, cutout, statusBarDp, navBar, safeArea). The v1 top-level screen fields are panel 0 with role inner, so an entry lists only its other panels (cover, rear or external), each role at most once. The parsed frame’s panels starts with the inner panel.
  • hinge: {axis: "vertical" | "horizontal", panel, positionDp, widthDp, occluding}, where panel is the role of the panel it folds (inner when omitted) and positionDp is the hinge’s leading edge from that panel’s left (vertical) or top (horizontal) edge in portrait. The hinge lies strictly inside the panel. occluding hinges remove widthDp from the layout; a seamless fold has widthDp: 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) or round, and input: touch (default), dpad or rotary. 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: opened is flat, a horizontal half_opened is tabletop, a vertical half_opened is book. iOS has no posture state, so an iOS frame never sets it. The prototype contract needs no new signal: widthClass and posture already 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 closed posture 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 round mask, which clips the screen to a circle. An Apple Watch keeps the rect mask 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 is compact and has no landscape view.
  • TV. A TV frame has no bezel padding beyond its stand, no status or navigation bar and input: "dpad". On a dpad frame 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.