peachsim 0.1.1641 → 0.1.1653

package/src/device-catalog.ts

@@ -0,0 +1,1159 @@
+export type RuntimePlatform = 'ios' | 'android'
+
+// hardware side-button layout. top/height are in the frame's coordinate
+// system (y=0 is the top of the device chrome, not the screen) so shell's
+// DeviceFrame can position them without re-doing the math per device.
+export interface HardwareButtonSpec {
+  side: 'left' | 'right' | 'top' | 'bottom'
+  top: number
+  height: number
+}
+
+export interface HardwareButtons {
+  // mechanical width of all side buttons for this device class.
+  width: number
+  lock: HardwareButtonSpec // right side (power / sleep)
+  ringToggle: HardwareButtonSpec // left side
+  volumeUp: HardwareButtonSpec // left side
+  volumeDown: HardwareButtonSpec // left side
+}
+
+// "modern" era (home indicator, dynamic island or notch) iPhones. button
+// positions mirror Apple's own Simulator chrome, pixel-measured per chrome
+// class from real Simulator.app device windows (method + full matrix in
+// packages/peach-engine/assets/device-frame-geometry). frameInsets is the
+// visible 2d chrome around the display: the black border plus however much
+// of the housing rail the front view actually shows. every profile keeps its
+// simulator calibration except the iphone air. its curved housing edge turns
+// away from a head-on view, so it renders the bare 1.435mm display border.
+// top/height are points from the top of the device chrome (frame-outer top),
+// so they don't depend on the device height. each arg is [top, height]: the
+// action / ring-silent switch, volume up, volume down (all on the left rail)
+// and the power / side button (right).
+function modernButtons(
+  action: [number, number],
+  volumeUp: [number, number],
+  volumeDown: [number, number],
+  power: [number, number],
+): HardwareButtons {
+  return {
+    width: 3,
+    ringToggle: { side: 'left', top: action[0], height: action[1] },
+    volumeUp: { side: 'left', top: volumeUp[0], height: volumeUp[1] },
+    volumeDown: { side: 'left', top: volumeDown[0], height: volumeDown[1] },
+    lock: { side: 'right', top: power[0], height: power[1] },
+  }
+}
+
+// "legacy" era (home button) iPhones. Apple-derived from bezel.supply's
+// iphone-se-3rd-gen frame (see packages/peach-engine/assets/device-frame-geometry): top/height
+// are points from the top of the device chrome (frame-outer top), the same
+// origin the modern buttons use. the SE shell has a symmetric ~111pt
+// forehead+chin, so these sit lower than the old placeholder values did.
+export const LEGACY_HARDWARE_BUTTONS: HardwareButtons = {
+  width: 2.5,
+  lock: { side: 'right', top: 188.7, height: 68.1 },
+  ringToggle: { side: 'left', top: 113.2, height: 36 },
+  volumeUp: { side: 'left', top: 188.2, height: 68.1 },
+  volumeDown: { side: 'left', top: 269, height: 68.1 },
+}
+
+export const PIXEL_HARDWARE_BUTTONS: HardwareButtons = {
+  width: 3,
+  // pixel 8 android studio art has right-edge opaque runs at y=671..833
+  // (power) and y=971..1301 (the continuous volume rocker), at 2.625x.
+  lock: { side: 'right', top: 671 / 2.625, height: 163 / 2.625 },
+  ringToggle: { side: 'left', top: -1000, height: 0 },
+  volumeUp: { side: 'right', top: 971 / 2.625, height: 165 / 2.625 },
+  volumeDown: { side: 'right', top: 1136 / 2.625, height: 166 / 2.625 },
+}
+
+export const GALAXY_HARDWARE_BUTTONS: HardwareButtons = {
+  width: 3,
+  lock: { side: 'right', top: 248, height: 72 },
+  ringToggle: { side: 'left', top: -1000, height: 0 },
+  volumeUp: { side: 'right', top: 144, height: 62 },
+  volumeDown: { side: 'right', top: 216, height: 62 },
+}
+
+export const ANDROID_GESTURE_NAV_BAR_HEIGHT = 24
+
+const ANDROID_OS_VERSION = '17'
+
+const ANDROID_API_LEVEL = 37
+
+const PIXEL_8_WIDTH = 1080 / 2.625
+
+const PIXEL_8_HEIGHT = 2400 / 2.625
+
+// pixel 8 api 37 rev6: qwerty, symbol and pad ime bounds include the
+// gesture bar, 883 physical pixels at 420dpi.
+const GBOARD_PANEL_HEIGHTS = {
+  qwerty: 883 / 2.625,
+  pad: 883 / 2.625,
+  emoji: 395,
+}
+
+const PIXEL_8_STATUS_BAR_HEIGHT = 132 / 2.625
+
+// api 37 pixel 8 overlay: status_bar_height_landscape=28dp; pixel rounding yields 74px.
+const PIXEL_8_LANDSCAPE_STATUS_BAR_HEIGHT = Math.round(28 * 2.625) / 2.625
+
+export interface FrameInsets {
+  top: number
+  right: number
+  bottom: number
+  left: number
+}
+
+export function uniformFrameInsets(value: number): FrameInsets {
+  return { top: value, right: value, bottom: value, left: value }
+}
+
+export type DevicePosture = 'closed' | 'open'
+
+// width of a foldable's central division (fold) band, in points. on the duo
+// the ios 27.1 simulator reports a 40pt division region which reads inactive
+// at fullyOpen, so a flat inner display lays out one continuous surface
+// (scripts/ops/duo-sim.ts); the band turns active as the hinge leaves flat,
+// and at book each split pane holds 20pt of margin on its hinge side
+// (packages/peach-engine/src/ios/SplitView.tsx). surfaces that compose two
+// groups side by side on the flat display (home) still balance their margins
+// around the band centre, so no group straddles the hinge line
+// (packages/peach-engine/src/ios/home/layout.ts).
+export const DUO_DIVISION_REGION_WIDTH = 40
+
+export interface CameraCutout {
+  diameter: number
+  top?: number
+  // distance from the trailing display edge on a camera that is not centred
+  trailing?: number
+}
+
+export interface PhysicalCutoutRect {
+  left: number
+  top: number
+  width: number
+  height: number
+}
+
+// display corner radii, clockwise from the top left. every device carries all
+// four; a uniform display repeats one value. a consumer that can only take one
+// scalar names the corner it reads and says why; nothing averages them.
+export interface CornerRadii {
+  topLeft: number
+  topRight: number
+  bottomRight: number
+  bottomLeft: number
+}
+
+export function cornerRadii(value: number): CornerRadii {
+  return { topLeft: value, topRight: value, bottomRight: value, bottomLeft: value }
+}
+
+// the barrel is a stadium lying along a folded display's leading edge, absent
+// when the display is open. `width` is its full thickness, `endInset` how far
+// its cap sits below the top of the body, and `protrusion` how much of it
+// stands out past the body's own silhouette (the rest hides behind the body).
+export interface DeviceHingeBarrel {
+  width: number
+  endInset: number
+  protrusion: number
+}
+
+// a housing whose body is a light rail around a black glass ring, measured
+// from apple's product art. `rail` is the visible rail width per edge, so the
+// black glass ring is frameInsets minus rail. devices without a housing draw
+// one black body with a metallic ring.
+export interface DeviceHousing {
+  rail: FrameInsets
+  hingeBarrel: DeviceHingeBarrel | null
+}
+
+export interface DeviceSpec {
+  // the registry key this profile came from, so a consumer holding only a
+  // published spec can still ask the registry model-keyed questions. the
+  // device-spec bus is the only channel some consumers have, and a display
+  // name is not an identity.
+  model: DeviceModel
+  platform: RuntimePlatform
+  name: string
+  width: number
+  height: number
+  scale: number
+  statusBarHeight: number
+  landscapeStatusBarHeight: number
+  homeIndicatorHeight: number
+  // terminal panel heights, excluding any input accessory. layout
+  // families can differ on the same display, so they are recorded separately.
+  keyboardPanelHeights: { qwerty: number; pad: number; emoji: number }
+  navigationBarHeight: number
+  navigationBarMode: 'gesture' | 'three-button' | 'none'
+  displayCutout: { top: number; left: number; right: number; bottom: number }
+  // effective circular fit of the native display mask, per corner. canvas
+  // renderers that only support circular corners use this value.
+  cornerRadius: CornerRadii
+  // tangent extent of the native corner curve, retained for future exact-shape
+  // profiling. the live DOM frame uses cornerRadius because Safari does not
+  // support CSS corner-shape and treats this larger value as a circular radius.
+  continuousCornerRadius: CornerRadii
+  // UIScreen _displayCornerRadius, the corner UIKit builds concentric sheet
+  // corners from, where it is not the mask fit above.
+  systemCornerRadius?: CornerRadii
+  // rendered frame body around the screen. per-edge values preserve asymmetric
+  // native device artwork instead of forcing every body through one bezel scalar.
+  frameInsets: FrameInsets
+  // body corner radii, when the body is not concentric with the display. a
+  // folded device's spine is a flat cut, so its corners there are far tighter
+  // than display radius plus inset. omit it and the concentric rule applies.
+  frameCornerRadius?: CornerRadii
+  housing?: DeviceHousing
+  // dynamic island geometry in points, uikit's own: the width and bottom edge
+  // of the sensor cutout in the ios 27.0 runtime's BoundingPathBitmap for the
+  // panel (UIKitCore BoundingPathData.bundle), and the 36.67pt height of the
+  // screen's _exclusionArea measured on the iphone 16 and 17 pro.
+  dynamicIsland: { width: number; height: number; top: number } | null
+  // the vertical centre line ios lays the status bar clock and icons on, in
+  // points. it is not the island's centre: the ios 27.0 17 pro row sits 3.33pt
+  // below the iphone 16 row while its island sits 2.67pt lower. framebuffer
+  // measured on the iphone 16, 17 pro and air; the other profiles keep their
+  // earlier island-derived values.
+  statusRowCenter?: number
+  cameraCutout: CameraCutout | null
+  safeAreaInsets: { top: number; bottom: number; left: number; right: number }
+  osVersion: string
+  iosVersion: string
+  androidApiLevel: number | null
+  systemName: 'iOS' | 'Android'
+  manufacturer: string
+  brand: string
+  modelName: string
+  // native screen pixel density (ppi) — used by Physical Size mode to render
+  // the device at its real-world dimensions on the user's display.
+  physicalPPI: number
+  // side button layout. modern devices build one per-device via modernButtons()
+  // (Apple-derived positions); iphone-se (home button) uses
+  // LEGACY_HARDWARE_BUTTONS; Android uses PIXEL_/GALAXY_HARDWARE_BUTTONS.
+  hardwareButtons: HardwareButtons
+  // experimental prototypes resolve by exact id on contributor surfaces
+  // (spec lookup, ?device= param, `device set <model>`) but are hidden from
+  // every picker/list UI and unresolvable off dev, so an in-progress
+  // experiment never surfaces to users. see isDeviceResolvableById.
+  experimental?: boolean
+  // unreleased hardware. it resolves by exact id on contributor surfaces but
+  // only a development surface offers it in a picker, and it stays
+  // unresolvable off dev, so a shipped build cannot boot it. see
+  // isDeviceResolvableById.
+  developmentOnly?: boolean
+  // posture is present on a resolved posture-aware profile. ordinary devices
+  // keep it absent so their existing device shape remains unchanged.
+  posture?: DevicePosture
+  // central fold (division) band width in points, present on an open foldable
+  // profile. the os region is active only while folded; flat-open it reads
+  // zero-width, but the band centre (the hinge line) still anchors two-group
+  // compositions. see DUO_DIVISION_REGION_WIDTH.
+  reservedDivisionWidth?: number
+  supportedPostures?: readonly DevicePosture[]
+  orientation?: InterfaceOrientation
+  // which landscape a rotated profile shows. on an open duo's portrait
+  // profile this selects its turn from the wide frame: left counterclockwise,
+  // right clockwise. both native physical poses show the portrait interface.
+  landscapeSide?: LandscapeSide
+  // the foreground scene turned the duo's vertical bar off
+  // (withSceneVerticalBar). absent while the bar is automatic.
+  verticalBar?: 'disabled'
+}
+
+export type DeviceModel =
+  | 'canvas-workspace'
+  | 'iphone-se'
+  | 'iphone-14'
+  | 'iphone-15'
+  | 'iphone-15-plus'
+  | 'iphone-15-pro'
+  | 'iphone-15-pro-max'
+  | 'iphone-16'
+  | 'iphone-16-plus'
+  | 'iphone-16-pro'
+  | 'iphone-16-pro-max'
+  | 'iphone-17'
+  | 'iphone-17-air'
+  | 'iphone-17-pro'
+  | 'iphone-17-pro-max'
+  | 'iphone-duo'
+  | 'ipad-pro-11'
+  | 'ipad-pro-13'
+  | 'pixel-8'
+  | 'pixel-8-three-button'
+  | 'pixel-9-pro-xl'
+  | 'pixel-10'
+  | 'galaxy-s24'
+  | 'galaxy-s24-ultra'
+
+function iosDevice(
+  spec: Omit<
+    DeviceSpec,
+    | 'statusBarHeight'
+    | 'platform'
+    | 'navigationBarHeight'
+    | 'navigationBarMode'
+    | 'displayCutout'
+    | 'cameraCutout'
+    | 'osVersion'
+    | 'androidApiLevel'
+    | 'systemName'
+    | 'manufacturer'
+    | 'brand'
+    | 'modelName'
+    | 'scale'
+    | 'landscapeStatusBarHeight'
+    | 'homeIndicatorHeight'
+    | 'iosVersion'
+    | 'dynamicIsland'
+    | 'keyboardPanelHeights'
+  > &
+    Partial<
+      Pick<
+        DeviceSpec,
+        | 'scale'
+        | 'landscapeStatusBarHeight'
+        | 'homeIndicatorHeight'
+        | 'iosVersion'
+        | 'keyboardPanelHeights'
+      >
+    > &
+    (
+      | { dynamicIsland: NonNullable<DeviceSpec['dynamicIsland']> }
+      | { dynamicIsland?: null; statusBarHeight: number }
+    ),
+): DeviceSpec {
+  const profile = {
+    // normal-scale dynamic split providers share this intrinsic height and
+    // linked-sdk whole-point rounding. safe areas are independent.
+    // source receipt: docs/ios-framework-oracle/status-bar-hit-region-and-scene-routing.md
+    statusBarHeight:
+      'statusBarHeight' in spec ? spec.statusBarHeight : Math.round(53.666666666666664),
+    scale: 3,
+    landscapeStatusBarHeight: 0,
+    homeIndicatorHeight: 34,
+    iosVersion: '27.0',
+    dynamicIsland: null,
+    keyboardPanelHeights: { qwerty: 301, pad: 301, emoji: 395 },
+    ...spec,
+  }
+  return {
+    ...profile,
+    platform: 'ios',
+    navigationBarHeight: 0,
+    navigationBarMode: profile.homeIndicatorHeight > 0 ? 'gesture' : 'none',
+    displayCutout: {
+      top: profile.dynamicIsland ? profile.safeAreaInsets.top : 0,
+      bottom: 0,
+      left: 0,
+      right: 0,
+    },
+    cameraCutout: null,
+    osVersion: profile.iosVersion,
+    androidApiLevel: null,
+    systemName: 'iOS',
+    manufacturer: 'Apple',
+    brand: 'Apple',
+    modelName: profile.name,
+  }
+}
+
+// corner metrics come from Apple's framebufferMask PDFs in each
+// .simdevicetype bundle. cornerRadius is the effective circle fit;
+// continuousCornerRadius is the straight-edge tangent extent of the mask.
+// they are deliberately different because no circular arc can reproduce an
+// Apple continuous corner.
+// profile construction is pure; helper-only imports must not retain the catalog.
+export const devices: Record<DeviceModel, DeviceSpec> = {
+  'canvas-workspace': /* @__PURE__ */ iosDevice({
+    model: 'canvas-workspace',
+    name: 'Canvas Workspace',
+    width: 1440,
+    height: 900,
+    scale: 1,
+    statusBarHeight: 0,
+    homeIndicatorHeight: 0,
+    cornerRadius: /* @__PURE__ */ cornerRadii(0),
+    continuousCornerRadius: /* @__PURE__ */ cornerRadii(0),
+    frameInsets: /* @__PURE__ */ uniformFrameInsets(16),
+    safeAreaInsets: { top: 0, bottom: 0, left: 0, right: 0 },
+    // no native device has this geometry; carries the iphone 16 keyboard
+    // height so the experimental profile still shows a keyboard.
+    physicalPPI: 110,
+    hardwareButtons: /* @__PURE__ */ modernButtons(
+      [185.8, 41.7],
+      [258.2, 67.6],
+      [344, 67.6],
+      [281.5, 106.9],
+    ),
+    experimental: true,
+  }),
+  'iphone-se': /* @__PURE__ */ iosDevice({
+    model: 'iphone-se',
+    name: 'iPhone SE',
+    width: 375,
+    height: 667,
+    scale: 2,
+    statusBarHeight: 20,
+    homeIndicatorHeight: 0,
+    cornerRadius: /* @__PURE__ */ cornerRadii(0),
+    continuousCornerRadius: /* @__PURE__ */ cornerRadii(0),
+    // legacy home-button frame uses asymmetric LEGACY_*_BEZEL constants in the
+    // shell (111pt forehead/chin, 29pt sides); uniform frameInsets are a sane
+    // modern-path value and mirror the SE's ~28.7pt side bezel.
+    frameInsets: /* @__PURE__ */ uniformFrameInsets(28.7),
+    safeAreaInsets: { top: 20, bottom: 0, left: 0, right: 0 },
+    keyboardPanelHeights: { qwerty: 226, pad: 226, emoji: 320 },
+    physicalPPI: 326,
+    hardwareButtons: LEGACY_HARDWARE_BUTTONS,
+  }),
+  'iphone-14': /* @__PURE__ */ iosDevice({
+    model: 'iphone-14',
+    name: 'iPhone 14',
+    width: 390,
+    height: 844,
+    statusBarHeight: 47,
+    cornerRadius: /* @__PURE__ */ cornerRadii(46.2),
+    continuousCornerRadius: /* @__PURE__ */ cornerRadii(67.462),
+    frameInsets: /* @__PURE__ */ uniformFrameInsets(19.5),
+    safeAreaInsets: { top: 47, bottom: 34, left: 0, right: 0 },
+    physicalPPI: 460,
+    hardwareButtons: /* @__PURE__ */ modernButtons(
+      [141.7, 29.7],
+      [205.9, 69.6],
+      [289.5, 69.6],
+      [228.9, 114.5],
+    ),
+  }),
+  'iphone-15': /* @__PURE__ */ iosDevice({
+    model: 'iphone-15',
+    name: 'iPhone 15',
+    width: 393,
+    height: 852,
+    cornerRadius: /* @__PURE__ */ cornerRadii(53.9),
+    continuousCornerRadius: /* @__PURE__ */ cornerRadii(73.402),
+    frameInsets: /* @__PURE__ */ uniformFrameInsets(18.2),
+    dynamicIsland: { width: 125, height: 110 / 3, top: 34 / 3 },
+    statusRowCenter: 32.75,
+    safeAreaInsets: { top: 59, bottom: 34, left: 0, right: 0 },
+    physicalPPI: 460,
+    hardwareButtons: /* @__PURE__ */ modernButtons(
+      [171.7, 32],
+      [235.8, 65.3],
+      [320.5, 65.3],
+      [280.6, 105.2],
+    ),
+  }),
+  'iphone-15-plus': /* @__PURE__ */ iosDevice({
+    model: 'iphone-15-plus',
+    name: 'iPhone 15 Plus',
+    width: 430,
+    height: 932,
+    cornerRadius: /* @__PURE__ */ cornerRadii(53.9),
+    continuousCornerRadius: /* @__PURE__ */ cornerRadii(74.654),
+    frameInsets: /* @__PURE__ */ uniformFrameInsets(17.3),
+    dynamicIsland: { width: 376 / 3, height: 110 / 3, top: 34 / 3 },
+    statusRowCenter: 30.05,
+    safeAreaInsets: { top: 59, bottom: 34, left: 0, right: 0 },
+    keyboardPanelHeights: { qwerty: 311, pad: 311, emoji: 405 },
+    physicalPPI: 460,
+    hardwareButtons: /* @__PURE__ */ modernButtons(
+      [172.1, 33],
+      [236.1, 66.6],
+      [321.2, 66.6],
+      [281, 106.8],
+    ),
+  }),
+  'iphone-15-pro': /* @__PURE__ */ iosDevice({
+    model: 'iphone-15-pro',
+    name: 'iPhone 15 Pro',
+    width: 393,
+    height: 852,
+    cornerRadius: /* @__PURE__ */ cornerRadii(53.9),
+    continuousCornerRadius: /* @__PURE__ */ cornerRadii(73.402),
+    frameInsets: /* @__PURE__ */ uniformFrameInsets(15.3),
+    dynamicIsland: { width: 125, height: 110 / 3, top: 34 / 3 },
+    statusRowCenter: 32.4,
+    safeAreaInsets: { top: 59, bottom: 34, left: 0, right: 0 },
+    physicalPPI: 460,
+    hardwareButtons: /* @__PURE__ */ modernButtons(
+      [159.1, 31.5],
+      [220.1, 61.9],
+      [299, 61.9],
+      [260.8, 98.9],
+    ),
+  }),
+  'iphone-15-pro-max': /* @__PURE__ */ iosDevice({
+    model: 'iphone-15-pro-max',
+    name: 'iPhone 15 Pro Max',
+    width: 430,
+    height: 932,
+    cornerRadius: /* @__PURE__ */ cornerRadii(53.9),
+    continuousCornerRadius: /* @__PURE__ */ cornerRadii(74.654),
+    frameInsets: /* @__PURE__ */ uniformFrameInsets(15.3),
+    dynamicIsland: { width: 376 / 3, height: 110 / 3, top: 34 / 3 },
+    statusRowCenter: 32.3,
+    safeAreaInsets: { top: 59, bottom: 34, left: 0, right: 0 },
+    keyboardPanelHeights: { qwerty: 311, pad: 311, emoji: 405 },
+    physicalPPI: 460,
+    hardwareButtons: /* @__PURE__ */ modernButtons(
+      [173.3, 32.2],
+      [253.4, 61.7],
+      [343.3, 61.7],
+      [268.5, 98.5],
+    ),
+  }),
+  'iphone-16': /* @__PURE__ */ iosDevice({
+    model: 'iphone-16',
+    name: 'iPhone 16',
+    width: 393,
+    height: 852,
+    // 2026-07-10: cornerRadius corrected 58 → 53.9 to Apple's own framebuffer
+    // mask (extracted from the simdevicetype bundle PDF; see
+    // packages/peach-engine/assets/device-frame-geometry). radius is a paint clip only — the
+    // calibrated conformance-oracle layout fields below are unchanged.
+    cornerRadius: /* @__PURE__ */ cornerRadii(53.9),
+    continuousCornerRadius: /* @__PURE__ */ cornerRadii(73.402),
+    // uikit's concentric-corner getter on the ios 27 iphone 16 returns 55.
+    systemCornerRadius: /* @__PURE__ */ cornerRadii(55),
+    frameInsets: /* @__PURE__ */ uniformFrameInsets(15.3),
+    dynamicIsland: { width: 125, height: 110 / 3, top: 34 / 3 },
+    statusRowCenter: 29.65,
+    safeAreaInsets: { top: 59, bottom: 34, left: 0, right: 0 },
+    keyboardPanelHeights: { qwerty: 301, pad: 302, emoji: 395 },
+    physicalPPI: 460,
+    hardwareButtons: /* @__PURE__ */ modernButtons(
+      [159.1, 31.5],
+      [220.1, 61.9],
+      [299, 61.9],
+      [260.8, 98.9],
+    ),
+  }),
+  'iphone-16-plus': /* @__PURE__ */ iosDevice({
+    model: 'iphone-16-plus',
+    name: 'iPhone 16 Plus',
+    width: 430,
+    height: 932,
+    cornerRadius: /* @__PURE__ */ cornerRadii(53.9),
+    continuousCornerRadius: /* @__PURE__ */ cornerRadii(74.654),
+    frameInsets: /* @__PURE__ */ uniformFrameInsets(15.3),
+    dynamicIsland: { width: 376 / 3, height: 110 / 3, top: 34 / 3 },
+    statusRowCenter: 30.05,
+    safeAreaInsets: { top: 59, bottom: 34, left: 0, right: 0 },
+    keyboardPanelHeights: { qwerty: 311, pad: 311, emoji: 405 },
+    physicalPPI: 460,
+    hardwareButtons: /* @__PURE__ */ modernButtons(
+      [173.3, 32.2],
+      [253.4, 61.7],
+      [343.3, 61.7],
+      [268.5, 98.5],
+    ),
+  }),
+  'iphone-16-pro': /* @__PURE__ */ iosDevice({
+    model: 'iphone-16-pro',
+    name: 'iPhone 16 Pro',
+    width: 402,
+    height: 874,
+    cornerRadius: /* @__PURE__ */ cornerRadii(61),
+    continuousCornerRadius: /* @__PURE__ */ cornerRadii(84.661),
+    frameInsets: /* @__PURE__ */ uniformFrameInsets(15.3),
+    dynamicIsland: { width: 125, height: 110 / 3, top: 14 },
+    statusRowCenter: 32.5,
+    safeAreaInsets: { top: 62, bottom: 34, left: 0, right: 0 },
+    physicalPPI: 460,
+    hardwareButtons: /* @__PURE__ */ modernButtons(
+      [159.1, 31.5],
+      [220.1, 61.9],
+      [299, 61.9],
+      [260.8, 98.9],
+    ),
+  }),
+  'iphone-16-pro-max': /* @__PURE__ */ iosDevice({
+    model: 'iphone-16-pro-max',
+    name: 'iPhone 16 Pro Max',
+    width: 440,
+    height: 956,
+    cornerRadius: /* @__PURE__ */ cornerRadii(61.3),
+    continuousCornerRadius: /* @__PURE__ */ cornerRadii(85.163),
+    frameInsets: /* @__PURE__ */ uniformFrameInsets(15.4),
+    dynamicIsland: { width: 376 / 3, height: 110 / 3, top: 14 },
+    statusRowCenter: 33,
+    safeAreaInsets: { top: 62, bottom: 34, left: 0, right: 0 },
+    keyboardPanelHeights: { qwerty: 311, pad: 311, emoji: 405 },
+    physicalPPI: 460,
+    hardwareButtons: /* @__PURE__ */ modernButtons(
+      [178.8, 32.2],
+      [266.8, 61.8],
+      [352.7, 61.8],
+      [292.2, 98.3],
+    ),
+  }),
+  'iphone-17': /* @__PURE__ */ iosDevice({
+    model: 'iphone-17',
+    name: 'iPhone 17',
+    width: 402,
+    height: 874,
+    cornerRadius: /* @__PURE__ */ cornerRadii(61),
+    continuousCornerRadius: /* @__PURE__ */ cornerRadii(84.661),
+    // display border 1.44mm plus the visible flat housing rail.
+    frameInsets: /* @__PURE__ */ uniformFrameInsets(15.3),
+    dynamicIsland: { width: 125, height: 110 / 3, top: 14 },
+    statusRowCenter: 32.65,
+    safeAreaInsets: { top: 62, bottom: 34, left: 0, right: 0 },
+    physicalPPI: 460,
+    hardwareButtons: /* @__PURE__ */ modernButtons(
+      [159.1, 31.5],
+      [220.1, 61.9],
+      [299, 61.9],
+      [260.8, 98.9],
+    ),
+  }),
+  'iphone-17-air': /* @__PURE__ */ iosDevice({
+    model: 'iphone-17-air',
+    // apple markets this as "iphone air" (not "iphone 17 air"). the real air
+    // is 420x912 with thin bezels and a lower-sitting island. it is not the
+    // 430x932 Plus body it used to be cloned from.
+    name: 'iPhone Air',
+    width: 420,
+    height: 912,
+    cornerRadius: /* @__PURE__ */ cornerRadii(64.6),
+    continuousCornerRadius: /* @__PURE__ */ cornerRadii(88.313),
+    // WHICH QUANTITY THIS IS, because it has been flipped twice and each pass
+    // read the other one as a bug: frameInsets is the VISIBLE FACE-ON frame —
+    // the black display border plus however much housing rail you actually see
+    // looking straight at the phone. It is NOT the caliper silhouette.
+    //
+    // Apple publishes a 74.7×156.2mm body around a 1260×2736 display at 460ppi,
+    // which is 15.475pt per side to the silhouette; that is the number to use if
+    // you ever need physical dimensions, and it is what commit 4966fe6cac put
+    // here. But most of that width on the Air is curved titanium turning away
+    // from a head-on view, so rendering it as frame draws the Air with the
+    // THICKEST bezel of any iPhone we ship when the real Air has the thinnest.
+    //
+    // So: 1.435mm display border = 8.69pt, plus ~2pt of rail that is actually
+    // face-on. The 17 Pro's flat rail contributes ~6.6pt on the same basis,
+    // which is why it sits at 15.3 and the Air should not.
+    frameInsets: /* @__PURE__ */ uniformFrameInsets(10.7),
+    dynamicIsland: { width: 125, height: 110 / 3, top: 20 },
+    statusRowCenter: 39,
+    safeAreaInsets: { top: 68, bottom: 34, left: 0, right: 0 },
+    keyboardPanelHeights: { qwerty: 311, pad: 311, emoji: 405 },
+    physicalPPI: 460,
+    hardwareButtons: /* @__PURE__ */ modernButtons(
+      [178.8, 32.2],
+      [266.8, 61.8],
+      [352.7, 61.8],
+      [292.2, 98.3],
+    ),
+  }),
+  'iphone-17-pro': /* @__PURE__ */ iosDevice({
+    model: 'iphone-17-pro',
+    name: 'iPhone 17 Pro',
+    width: 402,
+    height: 874,
+    cornerRadius: /* @__PURE__ */ cornerRadii(61),
+    continuousCornerRadius: /* @__PURE__ */ cornerRadii(84.661),
+    // the ios 27 simulator's ContainerRelativeShape at the root draws 62
+    // less its smallest inset from the display (54 at 8pt, 32 at 30pt).
+    systemCornerRadius: /* @__PURE__ */ cornerRadii(62),
+    // display border 1.44mm plus the visible flat housing rail.
+    frameInsets: /* @__PURE__ */ uniformFrameInsets(15.3),
+    dynamicIsland: { width: 125, height: 110 / 3, top: 14 },
+    statusRowCenter: 33,
+    safeAreaInsets: { top: 62, bottom: 34, left: 0, right: 0 },
+    // keyboardDidShow on the ios 27.0 simulator: 301 for the default keyboard,
+    // 302 for the number pad.
+    keyboardPanelHeights: { qwerty: 301, pad: 302, emoji: 395 },
+    physicalPPI: 460,
+    hardwareButtons: /* @__PURE__ */ modernButtons(
+      [159.1, 31.5],
+      [220.1, 61.9],
+      [299, 61.9],
+      [260.8, 98.9],
+    ),
+  }),
+  'iphone-17-pro-max': /* @__PURE__ */ iosDevice({
+    model: 'iphone-17-pro-max',
+    name: 'iPhone 17 Pro Max',
+    width: 440,
+    height: 956,
+    // same ios 26.4 440x956 dynamic island max profile as the measured
+    // iphone 16 pro max screens proof oracle.
+    cornerRadius: /* @__PURE__ */ cornerRadii(61.3),
+    continuousCornerRadius: /* @__PURE__ */ cornerRadii(85.163),
+    // display border 1.36mm plus the visible flat housing rail.
+    frameInsets: /* @__PURE__ */ uniformFrameInsets(15.4),
+    dynamicIsland: { width: 376 / 3, height: 110 / 3, top: 14 },
+    statusRowCenter: 33,
+    safeAreaInsets: { top: 62, bottom: 34, left: 0, right: 0 },
+    keyboardPanelHeights: { qwerty: 311, pad: 311, emoji: 405 },
+    physicalPPI: 460,
+    hardwareButtons: /* @__PURE__ */ modernButtons(
+      [178.8, 32.2],
+      [266.8, 61.8],
+      [352.7, 61.8],
+      [292.2, 98.3],
+    ),
+  }),
+  'iphone-duo': {
+    // offered on contributor surfaces only while the 27 home and the hinge
+    // measurements are still settling (nate, 2026-09-15).
+    developmentOnly: true,
+    .../* @__PURE__ */ iosDevice({
+      model: 'iphone-duo',
+      name: 'iPhone Duo',
+      width: 466,
+      height: 678,
+      statusBarHeight: 66,
+      // the ios 27.1 duo simulator draws the gesture home indicator in both
+      // postures: a 167pt x 5pt pill 8pt above the display bottom on the
+      // cover, sized by the same rule as the other iphones (HomeIndicator).
+      // hinge on the left. the hinge-side display corners measure 5pt in
+      // apple's 2d outer product art; the free side keeps the 61pt pro curve.
+      cornerRadius: { topLeft: 5, topRight: 61, bottomRight: 61, bottomLeft: 5 },
+      continuousCornerRadius: {
+        topLeft: 5,
+        topRight: 61,
+        bottomRight: 61,
+        bottomLeft: 5,
+      },
+      // the ios 27.1 duo simulator reports 59, and sheets 8pt in on the free
+      // side carry 51 there (41 at 18pt in).
+      systemCornerRadius: { topLeft: 5, topRight: 59, bottomRight: 59, bottomLeft: 5 },
+      // display edge to silhouette, measured off apple's 2d outer product art
+      // at 3x. the barrel is not part of the body: it protrudes 11.67pt past
+      // the left silhouette, so the full outer width is frame + protrusion.
+      frameInsets: { top: 16.3333, right: 16.3333, bottom: 16, left: 14 },
+      // the spine is a flat cut, so its corners are tiny; the free side keeps
+      // the 75pt body curve the pro bodies use.
+      frameCornerRadius: {
+        topLeft: 4.3333,
+        topRight: 75,
+        bottomRight: 75,
+        bottomLeft: 3.3333,
+      },
+      housing: {
+        rail: { top: 7.5, right: 8, bottom: 7.3333, left: 5.3333 },
+        hingeBarrel: { width: 16.6667, endInset: 7.3333, protrusion: 11.6667 },
+      },
+      // 84pt trailing Vertical Bar on the outer display (Apple iOS 27 UI kit).
+      safeAreaInsets: { top: 0, bottom: 34, left: 0, right: 84 },
+      iosVersion: '27.1',
+      // focused keyboard frames on the ios 27.1 duo simulator's cover: qwerty
+      // (0,426,466,252), number pad 256, emoji (0,340,466,338)pt
+      // (plans/contrast/duo-platform.md)
+      keyboardPanelHeights: { qwerty: 252, pad: 256, emoji: 338 },
+      physicalPPI: 460,
+      // official model extraction for button positions is outside this slice.
+      hardwareButtons: /* @__PURE__ */ modernButtons([0, 0], [0, 0], [0, 0], [0, 0]),
+      posture: 'closed',
+      supportedPostures: ['closed', 'open'],
+    }),
+    // the ios 27.1 simulator's camera occlusion region: 37pt, 29 1/3 in from
+    // the top and trailing edges
+    cameraCutout: {
+      diameter: 37,
+      top: 88 / 3,
+      trailing: 88 / 3,
+    },
+  },
+  'ipad-pro-11': {
+    // frame and hardware buttons are not sourced yet, so this stays off the
+    // shipping picker the same way the duo does.
+    developmentOnly: true,
+    .../* @__PURE__ */ ipadProDevice(
+      'ipad-pro-11',
+      'iPad Pro 11-inch (M5)',
+      834,
+      1210,
+      11,
+    ),
+  },
+  'ipad-pro-13': /* @__PURE__ */ ipadProDevice(
+    'ipad-pro-13',
+    'iPad Pro 13-inch (M5)',
+    1032,
+    1376,
+    13,
+  ),
+  'pixel-8': {
+    model: 'pixel-8',
+    platform: 'android',
+    name: 'Pixel 8',
+    width: PIXEL_8_WIDTH,
+    height: PIXEL_8_HEIGHT,
+    scale: 2.625,
+    statusBarHeight: PIXEL_8_STATUS_BAR_HEIGHT,
+    landscapeStatusBarHeight: PIXEL_8_LANDSCAPE_STATUS_BAR_HEIGHT,
+    homeIndicatorHeight: 0,
+    navigationBarHeight: ANDROID_GESTURE_NAV_BAR_HEIGHT,
+    keyboardPanelHeights: GBOARD_PANEL_HEIGHTS,
+    navigationBarMode: 'gesture',
+    displayCutout: {
+      top: PIXEL_8_STATUS_BAR_HEIGHT,
+      bottom: 0,
+      left: 0,
+      right: 0,
+    },
+    cornerRadius: /* @__PURE__ */ cornerRadii(39),
+    continuousCornerRadius: /* @__PURE__ */ cornerRadii(39),
+    // android studio's pixel 8 device art places the 1080x2400 display at
+    // (49,55) in a 1187x2513 body. the right side button occupies the final
+    // 8 physical pixels, so the body insets are 49/50/58/55 at 2.625x.
+    frameInsets: {
+      top: 55 / 2.625,
+      right: 50 / 2.625,
+      bottom: 58 / 2.625,
+      left: 49 / 2.625,
+    },
+    dynamicIsland: null,
+    cameraCutout: { diameter: 72.5 / 2.625 },
+    safeAreaInsets: {
+      top: PIXEL_8_STATUS_BAR_HEIGHT,
+      bottom: ANDROID_GESTURE_NAV_BAR_HEIGHT,
+      left: 0,
+      right: 0,
+    },
+    osVersion: ANDROID_OS_VERSION,
+    iosVersion: '',
+    androidApiLevel: ANDROID_API_LEVEL,
+    systemName: 'Android',
+    manufacturer: 'Google',
+    brand: 'google',
+    modelName: 'Pixel 8',
+    physicalPPI: 428,
+    hardwareButtons: PIXEL_HARDWARE_BUTTONS,
+  },
+  'pixel-8-three-button': {
+    model: 'pixel-8-three-button',
+    platform: 'android',
+    name: 'Pixel 8 (3-button)',
+    width: PIXEL_8_WIDTH,
+    height: PIXEL_8_HEIGHT,
+    scale: 2.625,
+    statusBarHeight: PIXEL_8_STATUS_BAR_HEIGHT,
+    landscapeStatusBarHeight: PIXEL_8_LANDSCAPE_STATUS_BAR_HEIGHT,
+    homeIndicatorHeight: 0,
+    navigationBarHeight: 48,
+    keyboardPanelHeights: GBOARD_PANEL_HEIGHTS,
+    navigationBarMode: 'three-button',
+    displayCutout: {
+      top: PIXEL_8_STATUS_BAR_HEIGHT,
+      bottom: 0,
+      left: 0,
+      right: 0,
+    },
+    cornerRadius: /* @__PURE__ */ cornerRadii(39),
+    continuousCornerRadius: /* @__PURE__ */ cornerRadii(39),
+    frameInsets: {
+      top: 55 / 2.625,
+      right: 50 / 2.625,
+      bottom: 58 / 2.625,
+      left: 49 / 2.625,
+    },
+    dynamicIsland: null,
+    cameraCutout: { diameter: 72.5 / 2.625 },
+    safeAreaInsets: {
+      top: PIXEL_8_STATUS_BAR_HEIGHT,
+      bottom: 48,
+      left: 0,
+      right: 0,
+    },
+    osVersion: ANDROID_OS_VERSION,
+    iosVersion: '',
+    androidApiLevel: ANDROID_API_LEVEL,
+    systemName: 'Android',
+    manufacturer: 'Google',
+    brand: 'google',
+    modelName: 'Pixel 8',
+    physicalPPI: 428,
+    hardwareButtons: PIXEL_HARDWARE_BUTTONS,
+  },
+  'pixel-9-pro-xl': {
+    model: 'pixel-9-pro-xl',
+    platform: 'android',
+    name: 'Pixel 9 Pro XL',
+    width: 448,
+    height: 997,
+    scale: 3,
+    statusBarHeight: 40,
+    landscapeStatusBarHeight: 40,
+    homeIndicatorHeight: 0,
+    navigationBarHeight: ANDROID_GESTURE_NAV_BAR_HEIGHT,
+    keyboardPanelHeights: GBOARD_PANEL_HEIGHTS,
+    navigationBarMode: 'gesture',
+    displayCutout: { top: 40, bottom: 0, left: 0, right: 0 },
+    cornerRadius: /* @__PURE__ */ cornerRadii(41),
+    continuousCornerRadius: /* @__PURE__ */ cornerRadii(41),
+    // Pixel 9 Pro XL body 162.8×76.6mm over a 70.2mm panel → ~1.8mm ≈ 12pt.
+    frameInsets: /* @__PURE__ */ uniformFrameInsets(12),
+    dynamicIsland: null,
+    cameraCutout: { diameter: 24 },
+    safeAreaInsets: {
+      top: 40,
+      bottom: ANDROID_GESTURE_NAV_BAR_HEIGHT,
+      left: 0,
+      right: 0,
+    },
+    osVersion: ANDROID_OS_VERSION,
+    iosVersion: '',
+    androidApiLevel: ANDROID_API_LEVEL,
+    systemName: 'Android',
+    manufacturer: 'Google',
+    brand: 'google',
+    modelName: 'Pixel 9 Pro XL',
+    physicalPPI: 486,
+    hardwareButtons: PIXEL_HARDWARE_BUTTONS,
+  },
+  'pixel-10': {
+    model: 'pixel-10',
+    platform: 'android',
+    name: 'Pixel 10',
+    width: 360,
+    height: 808,
+    scale: 3,
+    statusBarHeight: 40,
+    landscapeStatusBarHeight: 40,
+    homeIndicatorHeight: 0,
+    navigationBarHeight: ANDROID_GESTURE_NAV_BAR_HEIGHT,
+    keyboardPanelHeights: GBOARD_PANEL_HEIGHTS,
+    navigationBarMode: 'gesture',
+    displayCutout: { top: 40, bottom: 0, left: 0, right: 0 },
+    cornerRadius: /* @__PURE__ */ cornerRadii(40),
+    continuousCornerRadius: /* @__PURE__ */ cornerRadii(40),
+    // the 72mm body surrounds a roughly 65.1mm-wide 6.3-inch panel, which
+    // resolves to about 18 logical points of frame around the 1080px display.
+    frameInsets: /* @__PURE__ */ uniformFrameInsets(18),
+    dynamicIsland: null,
+    cameraCutout: { diameter: 26 },
+    safeAreaInsets: {
+      top: 40,
+      bottom: ANDROID_GESTURE_NAV_BAR_HEIGHT,
+      left: 0,
+      right: 0,
+    },
+    osVersion: ANDROID_OS_VERSION,
+    iosVersion: '',
+    androidApiLevel: ANDROID_API_LEVEL,
+    systemName: 'Android',
+    manufacturer: 'Google',
+    brand: 'google',
+    modelName: 'Pixel 10',
+    physicalPPI: 422,
+    hardwareButtons: PIXEL_HARDWARE_BUTTONS,
+  },
+  'galaxy-s24': {
+    model: 'galaxy-s24',
+    platform: 'android',
+    name: 'Galaxy S24',
+    width: 360,
+    height: 780,
+    scale: 3,
+    statusBarHeight: 36,
+    landscapeStatusBarHeight: 36,
+    homeIndicatorHeight: 0,
+    navigationBarHeight: ANDROID_GESTURE_NAV_BAR_HEIGHT,
+    keyboardPanelHeights: GBOARD_PANEL_HEIGHTS,
+    navigationBarMode: 'gesture',
+    displayCutout: { top: 36, bottom: 0, left: 0, right: 0 },
+    cornerRadius: /* @__PURE__ */ cornerRadii(36),
+    continuousCornerRadius: /* @__PURE__ */ cornerRadii(36),
+    // Galaxy S24 body 147.0×70.6mm over a 65.9mm panel → ~1.2mm ≈ 8pt (Samsung
+    // flat-display bezels are noticeably thinner than Pixel's).
+    frameInsets: /* @__PURE__ */ uniformFrameInsets(8),
+    dynamicIsland: null,
+    cameraCutout: { diameter: 18 },
+    safeAreaInsets: {
+      top: 36,
+      bottom: ANDROID_GESTURE_NAV_BAR_HEIGHT,
+      left: 0,
+      right: 0,
+    },
+    osVersion: ANDROID_OS_VERSION,
+    iosVersion: '',
+    androidApiLevel: ANDROID_API_LEVEL,
+    systemName: 'Android',
+    manufacturer: 'Samsung',
+    brand: 'samsung',
+    modelName: 'SM-S921B',
+    physicalPPI: 416,
+    hardwareButtons: GALAXY_HARDWARE_BUTTONS,
+  },
+  'galaxy-s24-ultra': {
+    model: 'galaxy-s24-ultra',
+    platform: 'android',
+    name: 'Galaxy S24 Ultra',
+    width: 384,
+    // samsung publishes a 1440x3120 panel; 3.75x resolves to 384x832.
+    height: 832,
+    scale: 3.75,
+    statusBarHeight: 36,
+    landscapeStatusBarHeight: 36,
+    homeIndicatorHeight: 0,
+    navigationBarHeight: ANDROID_GESTURE_NAV_BAR_HEIGHT,
+    keyboardPanelHeights: GBOARD_PANEL_HEIGHTS,
+    navigationBarMode: 'gesture',
+    displayCutout: { top: 36, bottom: 0, left: 0, right: 0 },
+    cornerRadius: /* @__PURE__ */ cornerRadii(24),
+    continuousCornerRadius: /* @__PURE__ */ cornerRadii(24),
+    // Galaxy S24 Ultra body 162.3×79.0mm over a 72.4mm panel → ~1.5mm ≈ 9pt.
+    frameInsets: /* @__PURE__ */ uniformFrameInsets(9),
+    dynamicIsland: null,
+    cameraCutout: { diameter: 18 },
+    safeAreaInsets: {
+      top: 36,
+      bottom: ANDROID_GESTURE_NAV_BAR_HEIGHT,
+      left: 0,
+      right: 0,
+    },
+    osVersion: ANDROID_OS_VERSION,
+    iosVersion: '',
+    androidApiLevel: ANDROID_API_LEVEL,
+    systemName: 'Android',
+    manufacturer: 'Samsung',
+    brand: 'samsung',
+    modelName: 'SM-S928B',
+    physicalPPI: 505,
+    hardwareButtons: GALAXY_HARDWARE_BUTTONS,
+  },
+}
+
+export const DEFAULT_DEVICE: DeviceModel = 'iphone-17-pro'
+
+// the device `peach ios` / `peach android` fall back to when the current setting
+// belongs to the other platform. lives here so the CLI never hardcodes a
+// model id the device registry owns.
+export const DEFAULT_DEVICE_BY_PLATFORM: Record<RuntimePlatform, DeviceModel> = {
+  ios: DEFAULT_DEVICE,
+  android: 'pixel-10',
+}
+
+// the interface poses a scene can support, uikit's interface orientations
+// without upside down (no home-indicator iphone presents it). landscape left
+// is the body turned clockwise. a scene's poses keep this order, so the first
+// is the one it arrives in from a pose it does not support: a landscape-only
+// app comes up in landscape right from portrait, as expo's orientation
+// registry deduces it.
+export type InterfacePose = 'portrait' | 'landscape-left' | 'landscape-right'
+
+export const ALL_INTERFACE_POSES: readonly InterfacePose[] = [
+  'portrait',
+  'landscape-right',
+  'landscape-left',
+]
+
+// springboard does not rotate on the phones that hold a scene's interface
+export const HOME_INTERFACE_POSES: readonly InterfacePose[] = ['portrait']
+
+// the turn, clockwise in degrees, that shows a display interface laid out in
+// `display` on the glass of a body standing in `body`: zero when the interface
+// turned with the body, otherwise the body's turn away from it.
+export type DisplayHold = -90 | 0 | 90 | 180
+
+export type SizeClass = 'compact' | 'regular'
+
+export type InterfaceOrientation = 'portrait' | 'landscape'
+
+// uikit's UIInterfaceOrientationLandscapeLeft and ...Right: left is the
+// portrait device turned clockwise, the top of the glass on the right; right
+// is the mirror, as detox's setOrientation('landscape') requests.
+export type LandscapeSide = 'left' | 'right'
+
+export type RotateDirection = 'left' | 'right'
+
+// the iphones whose HORIZONTAL size class is regular in landscape. apple never
+// published a width threshold past the iphone 6 plus, so this is a family rule
+// and deliberately not a number: plus, pro max and air bodies go regular in
+// landscape, every other iphone stays compact, and every iphone is compact x
+// regular in portrait. sources are in plans/sootsim/ios-size-class-table.md,
+// where apple's own word covers the 6 plus and the family rule, and the rows for
+// iphone 12 and later are marked INFERRED from that rule rather than measured on
+// a device. a surprise here is a bug in that table, not in the caller.
+
+// UIViewController.preferredVerticalBarBehavior, per horizontal size class:
+// what the foreground scene asks of the duo's vertical bar.
+export type VerticalBarBehavior = 'automatic' | 'disabled'
+
+export type SceneVerticalBar = Readonly<Record<SizeClass, VerticalBarBehavior>>
+
+export const AUTOMATIC_VERTICAL_BAR: SceneVerticalBar = {
+  compact: 'automatic',
+  regular: 'automatic',
+}
+
+export function isDeviceModel(value: string): value is DeviceModel {
+  return Object.hasOwn(devices, value)
+}
+
+export function listDeviceModels(): DeviceModel[] {
+  return Object.keys(devices).filter(isDeviceModel)
+}
+
+// devices a picker, tray, or list may offer. experimental prototypes never
+// appear, and developmentOnly devices appear only where the caller says it is
+// running on a development surface.
+export function listSelectableDeviceModels(options?: {
+  developmentMode?: boolean
+}): DeviceModel[] {
+  return listDeviceModels().filter((model) => {
+    const spec = devices[model]
+    if (spec.experimental) return false
+    return spec.developmentOnly !== true || options?.developmentMode === true
+  })
+}
+
+// reverse lookup by display name (e.g. "iPhone 16 Pro Max" → 'iphone-16-pro-max').
+// useful for consuming external manifests that record the human-readable
+// device name without a slug. returns null when no match exists.
+export function getDeviceByName(name: string): DeviceSpec | null {
+  for (const spec of Object.values(devices)) {
+    if (spec.name === name) return spec
+  }
+  return null
+}
+
+function ipadProDevice(
+  model: 'ipad-pro-11' | 'ipad-pro-13',
+  name: string,
+  width: number,
+  height: number,
+  diagonalInches: number,
+): DeviceSpec {
+  return iosDevice({
+    model,
+    name,
+    // iPad Pro 11-inch (M5) 12GB, iOS 27.0, simulator DBD4B183, UIKit probe
+    // scenario `metrics`. portrait UIScreen.bounds 834×1210, scale 2,
+    // nativeBounds 1668×2420. the window matched the screen.
+    width,
+    height,
+    scale: 2,
+    // portrait statusBarFrame was 834×32 at the top, and safeAreaInsets.top
+    // was 32. landscape statusBarFrame stayed 32 tall while safeAreaInsets.top
+    // was 10; this field is the portrait bar.
+    statusBarHeight: 32,
+    landscapeStatusBarHeight: 32,
+    // portrait and landscape safeAreaInsets.bottom were both 20. the probe
+    // has no separate home-indicator height.
+    homeIndicatorHeight: 20,
+    // UIScreen _displayCornerRadius, both orientations. the framebuffer
+    // mask's tangent extent was not measured separately.
+    cornerRadius: cornerRadii(30),
+    continuousCornerRadius: cornerRadii(30),
+    // housing is unsourced. the frame is the display until it is measured.
+    frameInsets: uniformFrameInsets(0),
+    // portrait safeAreaInsets. landscape was top 10, left 0, bottom 20, right 0.
+    safeAreaInsets: { top: 32, bottom: 20, left: 0, right: 0 },
+    // portrait docked keyboard, UIKeyboardFrameEndUserInfoKey
+    // {0, 870, 834, 340}. landscape posted a zero-height frame.
+    keyboardPanelHeights: { qwerty: 340, pad: 340, emoji: 427 },
+    // hypot(1668, 2420) / 11, measured native pixels over the device type's
+    // 11-inch name. not a separate density read.
+    physicalPPI: Math.hypot(width * 2, height * 2) / diagonalInches,
+    hardwareButtons: modernButtons([0, 0], [0, 0], [0, 0], [0, 0]),
+  })
+}