@swiftbrowser/web 0.1.0

package/src/protocol.ts

@@ -0,0 +1,1421 @@
+/**
+ * TypeScript mirror of docs/ops-protocol.md.
+ *
+ * The Swift core emits a stream of ops that the renderer applies to the DOM.
+ * Element ids are integers assigned by Swift; id 0 is the root container (the
+ * device screen) and is never created or removed.
+ */
+
+export type ElementId = number;
+
+// ---------------------------------------------------------------------------
+// Colors
+// ---------------------------------------------------------------------------
+
+/** Explicit sRGB color; every component is in 0...1. */
+export interface RGBAColor {
+  r: number;
+  g: number;
+  b: number;
+  a: number;
+}
+
+export type SemanticColorName =
+  | 'primary'
+  | 'secondary'
+  | 'accent'
+  | 'systemBackground'
+  | 'secondarySystemBackground'
+  | 'clear';
+
+/**
+ * Semantic color the renderer resolves for the current color scheme. `a`
+ * (0...1) is an optional opacity multiplier applied on top of the token.
+ */
+export interface NamedColor {
+  name: SemanticColorName;
+  a?: number;
+}
+
+/**
+ * Phase 5: a color from the app's asset catalog (a `.colorset`, possibly
+ * namespaced like `dough/plain-bg`). The renderer resolves it for the current
+ * color scheme through the catalog manifest (src/assets.ts); `opacity`
+ * (0...1) multiplies the catalog alpha. Unknown names render magenta.
+ */
+export interface AssetColor {
+  named: string;
+  opacity: number;
+}
+
+export type Color = RGBAColor | NamedColor | AssetColor;
+
+// Phase 6 (docs/phase6/styles.md): ShapeStyle, everything a view can be
+// painted with. A `Color` is one; the others resolve to CSS that depends on
+// the role (text or paint), see src/styles.ts.
+
+/** A unit point in the view's bounds (0...1 on each axis). */
+export interface UnitPoint {
+  x: number;
+  y: number;
+}
+
+/**
+ * Every non-color ShapeStyle may carry an `opacity` multiplier (0...1) at
+ * its top level (`.quaternary.opacity(0.5)`, `.thinMaterial.opacity(0.8)`),
+ * applied like a semantic color's `a`.
+ */
+export interface StyleOpacity {
+  opacity?: number;
+}
+
+/**
+ * `.primary` ... `.quaternary`. As a foreground (text) the label colors; as a
+ * background, fill or stroke the iOS fill colors of the same level.
+ */
+export interface HierarchicalStyle extends StyleOpacity {
+  hierarchical: 1 | 2 | 3 | 4;
+}
+
+export interface GradientStop {
+  color: Color;
+  /** 0...1 along the gradient. */
+  location: number;
+}
+
+export interface LinearGradient {
+  stops: GradientStop[];
+  start: UnitPoint;
+  end: UnitPoint;
+}
+export interface LinearGradientStyle extends StyleOpacity {
+  linearGradient: LinearGradient;
+}
+
+export interface RadialGradient {
+  stops: GradientStop[];
+  center: UnitPoint;
+  /** Points. */
+  startRadius: number;
+  endRadius: number;
+}
+export interface RadialGradientStyle extends StyleOpacity {
+  radialGradient: RadialGradient;
+}
+
+/** `Color.gradient`: a subtle vertical gradient derived from one color. */
+export interface ColorGradientStyle extends StyleOpacity {
+  colorGradient: Color;
+}
+
+export type MaterialName = 'ultraThin' | 'thin' | 'regular' | 'thick' | 'ultraThick';
+/** A translucent material: the system background at some opacity over a blurred backdrop. */
+export interface MaterialStyle extends StyleOpacity {
+  material: MaterialName;
+}
+
+export type ShapeStyle =
+  | Color
+  | HierarchicalStyle
+  | LinearGradientStyle
+  | RadialGradientStyle
+  | ColorGradientStyle
+  | MaterialStyle;
+
+// ---------------------------------------------------------------------------
+// Style
+// ---------------------------------------------------------------------------
+
+export interface EdgeInsets {
+  top?: number;
+  leading?: number;
+  bottom?: number;
+  trailing?: number;
+}
+
+export type FontWeight =
+  | 'ultraLight'
+  | 'thin'
+  | 'light'
+  | 'regular'
+  | 'medium'
+  | 'semibold'
+  | 'bold'
+  | 'heavy'
+  | 'black';
+export type FontDesign = 'default' | 'serif' | 'rounded' | 'monospaced';
+
+/** iOS text styles; resolved by the renderer for the current Dynamic Type size. */
+export type TextStyle =
+  | 'largeTitle'
+  | 'title'
+  | 'title2'
+  | 'title3'
+  | 'headline'
+  | 'subheadline'
+  | 'body'
+  | 'callout'
+  | 'footnote'
+  | 'caption'
+  | 'caption2';
+
+/**
+ * Every field is optional. `size` and `textStyle` are mutually exclusive: a
+ * `textStyle` scales with Dynamic Type, a fixed `size` does not unless
+ * `relativeTo` names the text style it should scale like. `headline` implies
+ * `semibold` unless `weight` is given.
+ */
+export interface Font {
+  textStyle?: TextStyle;
+  size?: number;
+  relativeTo?: TextStyle;
+  weight?: FontWeight;
+  design?: FontDesign;
+}
+
+export type FrameAlignment =
+  | 'center'
+  | 'leading'
+  | 'trailing'
+  | 'top'
+  | 'bottom'
+  | 'topLeading'
+  | 'topTrailing'
+  | 'bottomLeading'
+  | 'bottomTrailing';
+
+/** A frame dimension: points, or `"infinity"` to fill the available space. */
+export type Dimension = number | 'infinity';
+
+export interface Frame {
+  width?: number | null;
+  height?: number | null;
+  minWidth?: Dimension | null;
+  maxWidth?: Dimension | null;
+  minHeight?: Dimension | null;
+  maxHeight?: Dimension | null;
+  /** Positions the single child inside the frame; defaults to `center`. */
+  alignment?: FrameAlignment;
+}
+
+// Phase 3 animation (docs/ops-protocol.md, "Phase 3 additions").
+
+export type AnimationType = 'default' | 'linear' | 'easeIn' | 'easeOut' | 'easeInOut' | 'spring';
+
+/**
+ * `duration` defaults to 0.35s. For `spring` it is the perceptual duration
+ * and `bounce` (0 = critically damped, 0.3 = bouncy) shapes the curve.
+ */
+export interface Animation {
+  type: AnimationType;
+  duration?: number;
+  bounce?: number;
+  delay?: number;
+}
+
+export type TransitionKind = 'opacity' | 'scale' | 'slide' | 'move' | 'offset' | 'identity' | 'asymmetric';
+export type Edge = 'top' | 'leading' | 'bottom' | 'trailing';
+
+export interface TransitionPart {
+  kind: TransitionKind;
+  /** `move` only. */
+  edge?: Edge;
+  /** `scale` only; defaults to 0.5. */
+  scale?: number;
+  /** `offset` only: the translation (points) the view enters from / exits to. */
+  x?: number;
+  y?: number;
+  /**
+   * Phase 6, `asymmetric` only (`.asymmetric(insertion:removal:)`): the
+   * transition played when the view is inserted, and the one when removed.
+   */
+  insertion?: Transition;
+  removal?: Transition;
+}
+
+/** One transition, or several combined. */
+export type Transition = TransitionPart | TransitionPart[];
+
+export type TextAlignment = 'leading' | 'center' | 'trailing';
+
+export interface FixedSize {
+  horizontal: boolean;
+  vertical: boolean;
+}
+
+// Phase 5 (docs/ops-protocol.md, "Phase 5 additions").
+
+export type ContentMode = 'fit' | 'fill';
+
+/**
+ * `.aspectRatio(_:contentMode:)`. `ratio: null` keeps the child's own ideal
+ * aspect ratio (`.scaledToFit()` is `{ ratio: null, contentMode: "fit" }`,
+ * `.scaledToFill()` the `fill` form).
+ */
+export interface AspectRatio {
+  ratio: number | null;
+  contentMode: ContentMode;
+}
+
+/** `.shadow(color:radius:x:y:)`; rendered as a `drop-shadow` filter. */
+export interface Shadow {
+  color: Color;
+  radius: number;
+  x: number;
+  y: number;
+}
+
+/** Every field is optional. */
+export interface Style {
+  padding?: EdgeInsets;
+  font?: Font;
+  /** Phase 6: any ShapeStyle (text role). Gradients paint the text itself. */
+  foreground?: ShapeStyle;
+  /** Phase 6: any ShapeStyle (paint role). */
+  background?: ShapeStyle;
+  frame?: Frame;
+  cornerRadius?: number;
+  opacity?: number;
+  /** Dims the subtree (`opacity: 0.4`) and blocks input (`pointer-events: none`). */
+  disabled?: boolean;
+  // Phase 3
+  /** Stack space distribution priority (default 0). */
+  layoutPriority?: number;
+  /** Maximum lines of text in the subtree; `null` lifts an inherited limit. */
+  lineLimit?: number | null;
+  multilineTextAlignment?: TextAlignment;
+  /** The child is proposed `nil` on the fixed axes and takes its ideal size. */
+  fixedSize?: FixedSize;
+  /**
+   * `.animation(_:value:)`: whenever `animationToken` changes in an `update`,
+   * the layout and style changes of this subtree in that commit animate with
+   * `animation`.
+   */
+  animation?: Animation;
+  animationToken?: number;
+  /** How this subtree appears and disappears inside an animated commit. */
+  transition?: Transition;
+  // Phase 5
+  /** Sizes the child to an aspect ratio inside the proposal (see `AspectRatio`). */
+  aspectRatio?: AspectRatio;
+  // Phase 6 visual effects (docs/phase6/styles.md): CSS only, no layout effect.
+  /** `.offset(x:y:)`: translation in points. */
+  offset?: { x: number; y: number };
+  /** `.rotationEffect`: degrees, clockwise positive. */
+  rotation?: number;
+  /** Unit point the rotation turns around (default 0.5/0.5). */
+  rotationAnchor?: UnitPoint;
+  /** `.scaleEffect`: per-axis scale factors. */
+  scale?: { x: number; y: number };
+  /** Unit point the scale grows from (default 0.5/0.5). */
+  scaleAnchor?: UnitPoint;
+  shadow?: Shadow;
+  /** `.clipped()`: `overflow: hidden` on the box. */
+  clipped?: boolean;
+
+  // Phase 6 (docs/phase6/layout-containers.md)
+  /** `.gridCellColumns(_:)`: how many `grid` columns the cell spans (default 1). */
+  gridCellColumns?: number;
+  /** `.gridCellAnchor(_:)`: unit point the cell is aligned by inside its cell box. */
+  gridCellAnchor?: UnitPoint;
+  /** `.tint(_:)`: sets `--sb-tint` on the box so gauges, switches and prominent buttons below pick it up. */
+  tint?: Color;
+  /**
+   * `.position(x:y:)`: the box takes the whole proposal (the child's ideal
+   * size on nil axes) and centers the child, measured with a nil proposal,
+   * at (x, y) inside it.
+   */
+  position?: Point;
+
+  // Phase 6 (docs/phase6/chrome.md)
+  /**
+   * `.badge(_:)`: when the styled element is a list row, this text is drawn
+   * trailing in the row in the secondary color (17pt) and its width is
+   * reserved, so the row content is proposed less width. `null` clears it.
+   */
+  badge?: string | null;
+  /**
+   * `.listRowInsets(_:)`: replaces the row's default insets (16 horizontal,
+   * 11 vertical) for the list row this styled element is.
+   */
+  listRowInsets?: EdgeInsets;
+  /**
+   * `.imageScale(_:)`: symbol images in the subtree (`image` with
+   * `systemName`, and catalog `symbol` images) measure 0.8 / 1 / 1.25 of the
+   * font line height.
+   */
+  imageScale?: ImageScale;
+}
+
+
+export interface Point {
+  x: number;
+  y: number;
+}
+
+export type ImageScale = 'small' | 'medium' | 'large';
+
+// ---------------------------------------------------------------------------
+// Element kinds and props
+// ---------------------------------------------------------------------------
+
+export type VStackAlignment = 'leading' | 'center' | 'trailing';
+export type HStackAlignment = 'top' | 'center' | 'bottom';
+
+export interface TextProps {
+  text: string;
+}
+export interface VStackProps {
+  spacing: number | null;
+  alignment: VStackAlignment;
+  /** Phase 12 `.scrollTargetLayout()`: the children are the enclosing scroll view's snap points. */
+  scrollTarget?: boolean;
+}
+export interface HStackProps {
+  spacing: number | null;
+  alignment: HStackAlignment;
+  scrollTarget?: boolean;
+}
+export interface SpacerProps {
+  minLength: number | null;
+}
+export type ButtonStyle = 'automatic' | 'plain' | 'bordered' | 'borderedProminent';
+/** Phase 8: `cancel` is the role an `alert` draws apart (bold, or in its own card). */
+export type ButtonRole = 'destructive' | 'cancel' | null;
+/**
+ * The label is the button's child. Phase 1 modules send `{}`; both fields are
+ * therefore optional and default to `automatic` / no role.
+ */
+export interface ButtonProps {
+  style?: ButtonStyle;
+  role?: ButtonRole;
+}
+export interface StyledProps {
+  style: Style;
+}
+
+// Phase 2 kinds (docs/ops-protocol.md, "Phase 2 additions").
+
+/** Same alignment names as `Frame.alignment`; later children draw on top. */
+export interface ZStackProps {
+  alignment: FrameAlignment;
+}
+/** `systemName` is an SF Symbol name; the renderer picks the closest glyph. */
+export interface SymbolImageProps {
+  systemName: string;
+}
+/**
+ * Phase 5: an image from the app's asset catalog. `name` is the catalog
+ * name, possibly namespaced (`dough/plain-full`). A non-resizable image is
+ * always its intrinsic point size; a `.resizable()` one fills the proposal
+ * (the intrinsic size on unconstrained axes). The renderer looks the name up
+ * in the catalog manifest (src/assets.ts).
+ */
+export interface AssetImageProps {
+  name: string;
+  resizable: boolean;
+}
+export type ImageProps = SymbolImageProps | AssetImageProps;
+export type DividerProps = Record<string, never>;
+export type ScrollAxes = 'vertical' | 'horizontal' | 'both';
+export interface ScrollViewProps {
+  axes: ScrollAxes;
+}
+/**
+ * Phase 4: `insetGrouped` (the default when omitted, as Phase 2 modules send
+ * `{}`), `grouped` (full-width sections with hairlines; `Form`) or `plain`.
+ */
+export type ListStyle = 'plain' | 'insetGrouped' | 'grouped';
+export interface ListProps {
+  style?: ListStyle;
+}
+export interface SectionProps {
+  header: string | null;
+  footer: string | null;
+}
+export type TextFieldStyle = 'plain' | 'roundedBorder';
+export interface TextFieldProps {
+  text: string;
+  placeholder: string;
+  style: TextFieldStyle;
+  secure: boolean;
+  /** Phase 12 `.focused(...)`: whether the field should have focus; present only on bound fields, which report `focus` events. */
+  focused?: boolean;
+  /** Phase 12 `.onSubmit`: the Enter key sends a `submit` event. */
+  submit?: boolean;
+  /** Phase 12 `.submitLabel`: the return key's label (`enterkeyhint`). */
+  submitLabel?: string;
+}
+export interface ToggleProps {
+  isOn: boolean;
+}
+export type NavStackProps = Record<string, never>;
+export type NavDisplayMode = 'automatic' | 'large' | 'inline';
+export interface NavScreenProps {
+  title: string;
+  displayMode: NavDisplayMode;
+  /** 0 for the root screen; the renderer draws a back button when > 0. */
+  depth: number;
+}
+/** Phase 7 adds `selected` (see the block at the end of this file). */
+export interface NavLinkProps {
+  selected?: boolean;
+}
+
+// Phase 3 kinds (docs/ops-protocol.md, "Phase 3 additions").
+
+/** A box filled with `color`; fills its proposal. */
+export interface ColorProps {
+  color: Color;
+}
+/** Phase 6 adds `containerRelative` (`ContainerRelativeShape`): a rounded rectangle with `cornerRadius`. */
+export type ShapeKind = 'rectangle' | 'roundedRectangle' | 'circle' | 'capsule' | 'ellipse' | 'containerRelative';
+export interface Stroke {
+  /** Phase 6: any ShapeStyle; a gradient stroke falls back to its first stop. */
+  color: ShapeStyle;
+  lineWidth: number;
+  /**
+   * Phase 6: `.strokeBorder` draws the stroke inside the shape's bounds. The
+   * renderer draws every stroke inside the box; `inset` is recorded as
+   * `data-sb-stroke`.
+   */
+  inset?: boolean;
+}
+/** `fill: null` means the current foreground color; fills its proposal. */
+export interface ShapeProps {
+  shape: ShapeKind;
+  cornerRadius: number;
+  /** Phase 6: any ShapeStyle. */
+  fill: ShapeStyle | null;
+  stroke: Stroke | null;
+}
+/** Phase 8: `full` is `.fullScreenCover` (the card fills the screen). */
+export type Detent = 'medium' | 'large' | 'full';
+/**
+ * Always a root-level element (child of id 0) placed after the app's tree. A
+ * `tap` with the sheet's own id is a dismiss request.
+ */
+export interface SheetProps {
+  detents: Detent[];
+}
+
+// Phase 4 kinds (docs/ops-protocol.md, "Phase 4 additions").
+
+/** Fills the screen; a 49pt tab bar plus the bottom safe area at the bottom. */
+export interface TabViewProps {
+  /** Index of the selected `tab` child (authoritative; a tap sends `select`). */
+  selected: number;
+}
+/** One tab of a `tabview`: its content is the child; the bar item shows `title` and `systemImage`. */
+export interface TabProps {
+  title: string;
+  systemImage: string | null;
+}
+export type PickerStyle = 'segmented' | 'menu' | 'inline';
+/**
+ * `segmented`: an iOS segmented control (32pt). `menu`: a row with `label`
+ * leading and the selected option plus a chevron trailing that opens a menu.
+ * `inline` (Phase 6): one 44pt row per option with a checkmark on the
+ * selected one, preceded by a dim `label` row when the label is non-empty;
+ * inside a `menu` element the options become a section of the popover.
+ * Choosing sends `select` with the index.
+ */
+export interface PickerProps {
+  style: PickerStyle;
+  label: string;
+  options: string[];
+  selected: number;
+}
+/**
+ * `GeometryReader`: fills its proposal and reports its size through a
+ * `geometry` event whenever it changes. Exactly one child.
+ */
+export type GeometryProps = Record<string, never>;
+
+// Phase 6 kinds (docs/phase6/layout-containers.md).
+
+/** A proposal axis as Swift sees it: points, `"infinity"` or `null` (nil). */
+export type ProposalDimension = number | 'infinity' | null;
+export interface LayoutProposal {
+  width: ProposalDimension;
+  height: ProposalDimension;
+}
+export interface LayoutSize {
+  width: number;
+  height: number;
+}
+export interface LayoutFrame {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+/**
+ * A custom SwiftUI `Layout` evaluated on the Swift side with host-measured
+ * subviews. The children are the subviews, in order. `size` and `frames`
+ * (relative to the element's origin, one per child) are Swift's answer for
+ * `proposal`, or `null` before the first answer; the renderer measures the
+ * children and reports them through a `layout` event.
+ */
+export interface LayoutProps {
+  proposal: LayoutProposal | null;
+  size: LayoutSize | null;
+  frames: LayoutFrame[] | null;
+  /**
+   * The layout's own `sizeThatFits` for a zero, unspecified and infinite
+   * proposal (`"infinity"` for an unbounded dimension), sent with every
+   * answer. A parent measuring the layout with a proposal other than the
+   * answered one reads its flexibility from these instead of guessing.
+   */
+  sizes?: LayoutSizes | null;
+}
+export interface LayoutSizes {
+  min: LayoutFlexSize;
+  ideal: LayoutFlexSize;
+  max: LayoutFlexSize;
+}
+/** A size whose dimensions may be unbounded. */
+export interface LayoutFlexSize {
+  width: number | 'infinity';
+  height: number | 'infinity';
+}
+/** `Grid`: `horizontalSpacing`/`verticalSpacing` default to 8. Children are `gridrow`s or single full-span cells. */
+export interface GridProps {
+  horizontalSpacing: number | null;
+  verticalSpacing: number | null;
+  alignment: FrameAlignment;
+}
+export type GridRowAlignment = 'top' | 'center' | 'bottom' | 'firstTextBaseline' | 'lastTextBaseline';
+/** `GridRow`: the children are the cells. `alignment: null` uses the grid's. */
+export interface GridRowProps {
+  alignment: GridRowAlignment | null;
+}
+export type GridItemSize =
+  | { kind: 'fixed'; value: number }
+  | { kind: 'flexible'; minimum: number; maximum: Dimension }
+  | { kind: 'adaptive'; minimum: number; maximum: Dimension };
+/** `GridItem`: `spacing` (to the next column) defaults to 8, `alignment` to the grid's. */
+export interface GridItem {
+  size: GridItemSize;
+  spacing: number | null;
+  alignment: FrameAlignment | null;
+}
+/** `LazyVGrid`: `spacing` between rows defaults to 8. Children are the cells (flattened). Nothing is lazy. */
+export interface LazyVGridProps {
+  columns: GridItem[];
+  spacing: number | null;
+  alignment: FrameAlignment;
+}
+export type GaugeStyle =
+  | 'automatic'
+  | 'linearCapacity'
+  | 'accessoryLinear'
+  | 'accessoryCircular'
+  | 'accessoryCircularCapacity';
+/**
+ * `Gauge`: `value` is normalized to 0...1. Children in order: the label (when
+ * `hasLabel`) and the current value label (when `hasCurrentValueLabel`).
+ * Circular styles render as linear for now.
+ */
+export interface GaugeProps {
+  value: number;
+  style: GaugeStyle;
+  hasLabel: boolean;
+  hasCurrentValueLabel: boolean;
+}
+export type DecorationRole = 'overlay' | 'background';
+/**
+ * `.overlay { }` / `.background { }` with a view: children are
+ * `[content, decoration]`. The decoration is proposed the content's size,
+ * aligned inside it and never affects the size.
+ */
+export interface DecoratedProps {
+  role: DecorationRole;
+  alignment: FrameAlignment;
+}
+// Phase 6 kinds (docs/phase6/chrome.md).
+
+/**
+ * `Menu { items } label: { label }`: children are `[label, ...items]`. Only
+ * the label is laid out (the element is the label's size); tapping it opens
+ * a popover built from the current items (`button`/`navlink` rows that send
+ * `tap`, `picker` sections that send `select`, `divider`, `section`, `text`).
+ */
+export type MenuProps = Record<string, never>;
+export type ToolbarPlacement = 'trailing' | 'leading' | 'principal' | 'bottom';
+/**
+ * `.toolbar { ToolbarItem(placement:) { ... } }`, an extra child of a
+ * `navscreen` after its content. The children are the items, laid out at
+ * their ideal size in a 16pt-spaced hstack inside the navigation bar
+ * (`bottom`: a 49pt bar plus the bottom safe area, items spread evenly).
+ */
+export interface ToolbarProps {
+  placement: ToolbarPlacement;
+}
+/**
+ * `.searchable(text:)`, an extra child of a `navscreen`: a 36pt rounded
+ * search bar under the title area (52pt added to the bar). Typing sends
+ * `text` events exactly like a `textfield`.
+ */
+export interface SearchFieldProps {
+  text: string;
+  /** Defaults to "Search". */
+  placeholder: string;
+}
+/** `.onTapGesture`: one child, the child's size; a click anywhere on it sends `tap`. */
+export type TapGestureProps = Record<string, never>;
+
+export interface ElementPropsByKind {
+  text: TextProps;
+  vstack: VStackProps;
+  hstack: HStackProps;
+  spacer: SpacerProps;
+  button: ButtonProps;
+  styled: StyledProps;
+  zstack: ZStackProps;
+  image: ImageProps;
+  divider: DividerProps;
+  scrollview: ScrollViewProps;
+  list: ListProps;
+  section: SectionProps;
+  textfield: TextFieldProps;
+  toggle: ToggleProps;
+  navstack: NavStackProps;
+  navscreen: NavScreenProps;
+  navlink: NavLinkProps;
+  color: ColorProps;
+  shape: ShapeProps;
+  sheet: SheetProps;
+  tabview: TabViewProps;
+  tab: TabProps;
+  picker: PickerProps;
+  geometry: GeometryProps;
+  layout: LayoutProps;
+  grid: GridProps;
+  gridrow: GridRowProps;
+  lazyvgrid: LazyVGridProps;
+  gauge: GaugeProps;
+  decorated: DecoratedProps;
+  menu: MenuProps;
+  toolbar: ToolbarProps;
+  searchfield: SearchFieldProps;
+  tapgesture: TapGestureProps;
+}
+
+export type ElementKind = keyof ElementPropsByKind;
+
+export type ElementProps = ElementPropsByKind[ElementKind];
+
+/** Discriminated `kind` + matching `props` pair. */
+export type ElementDescriptor = {
+  [K in ElementKind]: { kind: K; props: ElementPropsByKind[K] };
+}[ElementKind];
+
+// ---------------------------------------------------------------------------
+// Ops
+// ---------------------------------------------------------------------------
+
+export type CreateOp = { op: 'create'; id: ElementId } & ElementDescriptor;
+
+export interface UpdateOp {
+  op: 'update';
+  id: ElementId;
+  /** Replaces the element's props entirely. */
+  props: ElementProps;
+}
+
+export interface InsertOp {
+  op: 'insert';
+  parent: ElementId;
+  id: ElementId;
+  /** Insert as child `index` of `parent`, moving the element if already attached. */
+  index: number;
+}
+
+export interface RemoveOp {
+  op: 'remove';
+  id: ElementId;
+}
+
+/**
+ * End of a render pass. Renderers may batch DOM work until this. With
+ * `animation` (from `withAnimation`) every frame and style change of the pass
+ * animates, inserted elements transition in and removed ones out.
+ */
+export interface CommitOp {
+  op: 'commit';
+  animation?: Animation;
+}
+
+/**
+ * Phase 11: the app's `UserDefaults`, whole, after a change. The host keeps
+ * them (localStorage, per app) and hands them back at the next launch through
+ * the `SB_DEFAULTS` environment variable. Not a rendering op: the loader
+ * consumes it before the renderer sees the batch.
+ */
+export interface DefaultsOp {
+  op: 'defaults';
+  values: Record<string, unknown>;
+}
+
+export type Op = CreateOp | UpdateOp | InsertOp | RemoveOp | CommitOp | DefaultsOp;
+
+// ---------------------------------------------------------------------------
+// Events (renderer → Swift)
+// ---------------------------------------------------------------------------
+
+export type ColorScheme = 'light' | 'dark';
+
+export type DynamicTypeSize =
+  | 'xSmall'
+  | 'small'
+  | 'medium'
+  | 'large'
+  | 'xLarge'
+  | 'xxLarge'
+  | 'xxxLarge'
+  | 'accessibility1'
+  | 'accessibility2'
+  | 'accessibility3'
+  | 'accessibility4'
+  | 'accessibility5';
+
+export const DYNAMIC_TYPE_SIZES: readonly DynamicTypeSize[] = [
+  'xSmall',
+  'small',
+  'medium',
+  'large',
+  'xLarge',
+  'xxLarge',
+  'xxxLarge',
+  'accessibility1',
+  'accessibility2',
+  'accessibility3',
+  'accessibility4',
+  'accessibility5',
+];
+
+export function isDynamicTypeSize(value: unknown): value is DynamicTypeSize {
+  return typeof value === 'string' && (DYNAMIC_TYPE_SIZES as readonly string[]).includes(value);
+}
+
+/**
+ * A `button`, `navlink`, `tapgesture`, (for the back button) `navscreen` or
+ * (for a dismiss request) `sheet` was tapped.
+ */
+export interface TapEvent {
+  type: 'tap';
+  id: ElementId;
+}
+/** A `textfield` or `searchfield` received input. */
+export interface TextEvent {
+  type: 'text';
+  id: ElementId;
+  value: string;
+}
+/** A `toggle` was switched. */
+export interface ToggleEvent {
+  type: 'toggle';
+  id: ElementId;
+  value: boolean;
+}
+/**
+ * The device appearance or text size changed (also sent once right after
+ * `_start`). Either field may be omitted; this renderer always sends both.
+ */
+export interface EnvironmentEvent {
+  type: 'environment';
+  colorScheme?: ColorScheme;
+  dynamicTypeSize?: DynamicTypeSize;
+}
+
+/** A `tabview` bar item or a `picker` option was chosen; `value` is the index. */
+export interface SelectEvent {
+  type: 'select';
+  id: ElementId;
+  value: number;
+}
+/**
+ * A `geometry` element's laid-out size (whole CSS px), sent after a layout
+ * pass only when it differs from the last reported size.
+ */
+export interface GeometryEvent {
+  type: 'geometry';
+  id: ElementId;
+  width: number;
+  height: number;
+}
+
+/** Host measurements of one subview of a `layout` element (points, 2 decimals; `"infinity"` for an unbounded axis). */
+export interface LayoutChildMeasurement {
+  min: { width: Dimension; height: Dimension };
+  ideal: { width: Dimension; height: Dimension };
+  max: { width: Dimension; height: Dimension };
+}
+/**
+ * Phase 6: sent after a layout pass for every `layout` element whose record
+ * (the proposal it was placed with and its children's min / ideal / max sizes)
+ * differs from the last one sent for that id. Swift answers by updating the
+ * element's `size` and `frames` props.
+ */
+export interface LayoutEvent {
+  type: 'layout';
+  id: ElementId;
+  proposal: LayoutProposal;
+  children: LayoutChildMeasurement[];
+}
+
+/**
+ * Everything the renderer sends to Swift. Taps travel through `sb_event(id)`,
+ * the rest as UTF-8 JSON through `sb_alloc` + `sb_event_json`.
+ */
+export type RendererEvent =
+  | TapEvent
+  | TextEvent
+  | ToggleEvent
+  | EnvironmentEvent
+  | SelectEvent
+  | GeometryEvent
+  | LayoutEvent
+  | BatchEvent
+  // Phase 8: gestures, rows, navigation (see the block at the end of this file)
+  | InteractionEvent
+  // Phase 8: alerts, controls (see the block at the end of this file)
+  | Phase8ControlEvent;
+
+/**
+ * Several events delivered in one `sb_event_json` call: Swift applies each
+ * and renders once. The renderer sends one per layout pass for the pass's
+ * `geometry` and `layout` events, so a screen with many measured elements
+ * costs one render instead of one per element. Never nested.
+ */
+export interface BatchEvent {
+  type: 'batch';
+  events: Exclude<RendererEvent, BatchEvent>[];
+}
+
+/** Headless-mode echo of a replayed event; never sent to the browser renderer. */
+export type EventEchoOp = { op: 'event' } & RendererEvent;
+
+export const ROOT_ID: ElementId = 0;
+
+/** `spacing: null` means "system default", which the renderer treats as 8px. */
+export const DEFAULT_SPACING = 8;
+
+export function isNamedColor(color: ShapeStyle): color is NamedColor {
+  return typeof (color as NamedColor).name === 'string';
+}
+
+export function isAssetColor(color: ShapeStyle): color is AssetColor {
+  return typeof (color as AssetColor).named === 'string';
+}
+
+export function isRGBAColor(style: ShapeStyle): style is RGBAColor {
+  const c = style as RGBAColor;
+  return typeof c.r === 'number' && typeof c.g === 'number' && typeof c.b === 'number';
+}
+
+/** True for the three `Color` forms (explicit, semantic, catalog). */
+export function isColor(style: ShapeStyle): style is Color {
+  return isRGBAColor(style) || isNamedColor(style) || isAssetColor(style);
+}
+
+export function isHierarchicalStyle(style: ShapeStyle): style is HierarchicalStyle {
+  return typeof (style as HierarchicalStyle).hierarchical === 'number';
+}
+
+export function isLinearGradientStyle(style: ShapeStyle): style is LinearGradientStyle {
+  const g = (style as LinearGradientStyle).linearGradient;
+  return typeof g === 'object' && g !== null;
+}
+
+export function isRadialGradientStyle(style: ShapeStyle): style is RadialGradientStyle {
+  const g = (style as RadialGradientStyle).radialGradient;
+  return typeof g === 'object' && g !== null;
+}
+
+export function isColorGradientStyle(style: ShapeStyle): style is ColorGradientStyle {
+  const c = (style as ColorGradientStyle).colorGradient;
+  return typeof c === 'object' && c !== null;
+}
+
+export function isMaterialStyle(style: ShapeStyle): style is MaterialStyle {
+  return typeof (style as MaterialStyle).material === 'string';
+}
+
+/** True for the asset catalog form of `image` props (`{ name, resizable }`). */
+export function isAssetImage(props: ImageProps): props is AssetImageProps {
+  return typeof (props as AssetImageProps).name === 'string';
+}
+
+/** Cheap structural check used when parsing an untrusted JSON buffer. */
+export function isOp(value: unknown): value is Op {
+  if (typeof value !== 'object' || value === null) return false;
+  const op = (value as { op?: unknown }).op;
+  return (
+    op === 'create' || op === 'update' || op === 'insert' || op === 'remove' || op === 'commit' || op === 'defaults'
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Phase 7: navigation, ViewThatFits, styles
+// (docs/ops-protocol.md, "Phase 7"; charts live in their own block)
+// ---------------------------------------------------------------------------
+
+/** `NavigationSplitView` in the regular size class: children are `[sidebar, detail]`, each a `navstack`. */
+export type NavSplitProps = Record<string, never>;
+
+export type ViewThatFitsAxes = 'horizontal' | 'vertical' | 'both';
+/**
+ * `ViewThatFits`: the children are the candidates, in order. The engine shows
+ * the first whose ideal size fits the proposal on `axes` (default `both`), or
+ * the last when none fits; the others get no frame and are hidden.
+ */
+export interface ViewThatFitsProps {
+  axes?: ViewThatFitsAxes;
+}
+
+export interface ElementPropsByKind {
+  navsplit: NavSplitProps;
+  viewthatfits: ViewThatFitsProps;
+}
+
+export interface Style {
+  /** `.hidden()`: the box keeps its layout but draws nothing and takes no input. */
+  hidden?: true;
+  /**
+   * `.mask { Gradient / Color }`: a CSS `mask-image` built from the style
+   * (gradients as CSS gradients, a `Color` as a solid mask with its alpha).
+   */
+  mask?: ShapeStyle;
+}
+
+/** `UserInterfaceSizeClass`: `regular` when the screen is at least 700 CSS px wide. */
+export type HorizontalSizeClass = 'compact' | 'regular';
+/** Threshold (CSS px) between the compact and regular horizontal size class. */
+export const REGULAR_WIDTH_MIN = 700;
+
+export interface EnvironmentEvent {
+  horizontalSizeClass?: HorizontalSizeClass;
+}
+
+/** The `horizontalSizeClass` for a screen `width` CSS px wide. */
+export function horizontalSizeClassFor(width: number): HorizontalSizeClass {
+  return Number.isFinite(width) && width >= REGULAR_WIDTH_MIN ? 'regular' : 'compact';
+}
+
+// ---------------------------------------------------------------------------
+// Phase 7: charts (docs/ops-protocol.md, "Phase 7"). Swift turns data into
+// unit coordinates (0...1 of the plot rectangle, y top → bottom); the renderer
+// measures labels, derives the plot rectangle and draws the marks as SVG.
+// ---------------------------------------------------------------------------
+
+export type ChartInterpolation =
+  | 'linear'
+  | 'cardinal'
+  | 'catmullRom'
+  | 'monotone'
+  | 'stepStart'
+  | 'stepCenter'
+  | 'stepEnd';
+
+export type ChartSymbol = 'circle' | 'square' | 'triangle' | 'diamond' | 'cross' | 'plus' | 'asterisk';
+
+/** Fields every mark carries. */
+export interface ChartMarkBase {
+  style: ShapeStyle;
+  /** 0...1, default 1. */
+  opacity?: number;
+  /** An `area` or `rect` mark whose geometry clips this mark (an SVG `clipPath`). */
+  mask?: ChartMark | null;
+}
+/** `BarMark` / `RectangleMark`: a filled `<rect>` over the unit rect. */
+export interface ChartRectMark extends ChartMarkBase {
+  kind: 'rect';
+  x0: number;
+  x1: number;
+  y0: number;
+  y1: number;
+  /** Px, default 0. */
+  cornerRadius?: number;
+  /** Px: the rect is this wide, centered on `(x0 + x1) / 2`. */
+  fixedWidth?: number | null;
+}
+export interface ChartLinePoint {
+  x: number;
+  y: number;
+}
+/** `LineMark`: a stroked `<path>` plus one symbol glyph per point. */
+export interface ChartLineMark extends ChartMarkBase {
+  kind: 'line';
+  points: ChartLinePoint[];
+  /** Px, default 2. */
+  lineWidth?: number;
+  interpolation?: ChartInterpolation;
+  symbol?: ChartSymbol | null;
+  /** Px, default 8. */
+  symbolSize?: number;
+}
+export interface ChartAreaPoint {
+  x: number;
+  /** `y0 <= y1` (y runs top → bottom, so `y0` is the upper edge). */
+  y0: number;
+  y1: number;
+}
+/** `AreaMark`: a filled `<path>` between the two curves. */
+export interface ChartAreaMark extends ChartMarkBase {
+  kind: 'area';
+  points: ChartAreaPoint[];
+  interpolation?: ChartInterpolation;
+}
+/** `PointMark`: one symbol glyph. */
+export interface ChartPointMark extends ChartMarkBase {
+  kind: 'point';
+  x: number;
+  y: number;
+  symbol: ChartSymbol;
+  /** Px, default 8. */
+  symbolSize?: number;
+}
+/** `RuleMark`: a stroked line between the two points. */
+export interface ChartRuleMark extends ChartMarkBase {
+  kind: 'rule';
+  x0: number;
+  x1: number;
+  y0: number;
+  y1: number;
+  /** Px, default 1. */
+  lineWidth?: number;
+}
+export type ChartMark = ChartRectMark | ChartLineMark | ChartAreaMark | ChartPointMark | ChartRuleMark;
+
+export type ChartXAxisPosition = 'bottom' | 'top';
+export type ChartYAxisPosition = 'trailing' | 'leading';
+export interface ChartAxisLabel {
+  /** Unit position along the axis (y: 0 is the top). */
+  at: number;
+  text: string;
+}
+/** `null` for the whole axis means hidden. Positions are unit values along the axis. */
+export interface ChartAxis {
+  position: ChartXAxisPosition | ChartYAxisPosition;
+  gridLines: number[];
+  ticks: number[];
+  /** Default text labels; view labels are `chartitem` children with role `xLabel` / `yLabel`. */
+  labels: ChartAxisLabel[];
+}
+
+export type ChartLegendPosition = 'top' | 'bottom' | 'leading' | 'trailing';
+export interface ChartLegendItem {
+  label: string;
+  style: ShapeStyle;
+  /** `null`: an 18 × 3 line glyph instead of a symbol. */
+  symbol: ChartSymbol | null;
+}
+export interface ChartLegend {
+  position: ChartLegendPosition;
+  items: ChartLegendItem[];
+}
+
+/** `Chart`: children are `chartitem`s (annotations and view axis labels), in any order. */
+export interface ChartProps {
+  marks: ChartMark[];
+  xAxis: ChartAxis | null;
+  yAxis: ChartAxis | null;
+  legend: ChartLegend | null;
+}
+
+export type ChartItemRole = 'annotation' | 'xLabel' | 'yLabel';
+export type ChartItemPosition = 'top' | 'bottom' | 'leading' | 'trailing' | 'overlay';
+/**
+ * One view inside a `chart`: an annotation placed against the unit rect
+ * `x0…x1 × y0…y1` of its mark, or an axis label view whose tick is
+ * `x0 == x1` (x) / `y0 == y1` (y). Exactly one child.
+ */
+export interface ChartItemProps {
+  role: ChartItemRole;
+  x0: number;
+  x1: number;
+  y0: number;
+  y1: number;
+  position: ChartItemPosition;
+  alignment: FrameAlignment;
+  /** Px between the mark's rect and the annotation (default 0). */
+  spacing: number;
+}
+
+// Declaration merging adds the Phase 7 kinds to `ElementPropsByKind` (and so
+// to `ElementKind`, `ElementProps`, `ElementDescriptor` and `CreateOp`)
+// without touching the Phase 1-6 table above.
+export interface ElementPropsByKind {
+  chart: ChartProps;
+  chartitem: ChartItemProps;
+}
+
+export const CHART_KINDS: readonly ElementKind[] = ['chart', 'chartitem'];
+
+// ---------------------------------------------------------------------------
+// Phase 8: gestures, rows, navigation (docs/ops-protocol.md, "Phase 8:
+// interaction"). `gesture`, `swipeactions`, `contextmenu` and `listrow` are
+// layout-transparent wrappers; the renderer tracks pointers on them
+// (src/interaction.ts). Declaration merging adds the kinds, the `Style` hint
+// and the `list` / `scrollview` fields without touching the tables above.
+// ---------------------------------------------------------------------------
+
+/**
+ * `.gesture(DragGesture())` / `.onLongPressGesture`: exactly one child, the
+ * child's size. With `drag`, a pointer that moves `minimumDistance` (default
+ * 10, 0 for an immediate gesture) starts a drag and the element receives
+ * `drag` events; with `longPress`, a pointer held `minimumDuration` (default
+ * 0.5 s) without moving 10 px sends `longpress`.
+ */
+export interface GestureProps {
+  drag?: boolean;
+  longPress?: boolean;
+  minimumDistance?: number;
+  minimumDuration?: number;
+}
+
+/**
+ * `.swipeActions`: children are `[content, ...trailing actions, ...leading
+ * actions]` (`trailing` and `leading` count them); the actions are `button`s
+ * (a `tint` style colors one, role `destructive` is red). A horizontal pan on
+ * the row reveals 74 pt buttons behind the content; tapping one sends `tap`
+ * with the button's id. A full swipe (allowed by default) past the actions'
+ * width + 60 performs the first declared action of that edge.
+ */
+export interface SwipeActionsProps {
+  trailing: number;
+  leading: number;
+  fullSwipeTrailing?: boolean;
+  fullSwipeLeading?: boolean;
+}
+
+/** `.contextMenu { }`: `[content, ...items]`; a long press or right click lists the items (as in a `menu`) in a popover. */
+export type ContextMenuProps = Record<string, never>;
+
+/**
+ * A `List` row that can be selected (`selectable`, `selected`) or deleted
+ * (`deletable`, from `ForEach.onDelete`). A tap on a selectable row sends
+ * `tap` with the row id; swipe-to-delete or the edit-mode minus sends `delete`.
+ */
+export interface ListRowProps {
+  selectable?: boolean;
+  selected?: boolean;
+  deletable?: boolean;
+}
+
+export interface ElementPropsByKind {
+  gesture: GestureProps;
+  swipeactions: SwipeActionsProps;
+  contextmenu: ContextMenuProps;
+  listrow: ListRowProps;
+}
+
+export const INTERACTION_KINDS: readonly ElementKind[] = ['gesture', 'swipeactions', 'contextmenu', 'listrow'];
+
+export interface ListProps {
+  /** `EditButton` / `editMode`: every `listrow` gains a 44 pt leading control and its content shifts right 44. */
+  editing?: boolean;
+  /** `.refreshable`: a pull past 60 pt at the top sends `refresh`. */
+  refreshable?: boolean;
+  /** Swift sets it while the refresh action runs; a 40 pt spinner row shows above the content. */
+  refreshing?: boolean;
+}
+
+export interface ScrollViewProps {
+  refreshable?: boolean;
+  refreshing?: boolean;
+  /** Phase 12 `.scrollTargetBehavior`: CSS scroll snapping on the axis. */
+  snap?: 'viewAligned' | 'paging';
+}
+
+export interface Style {
+  /** `.allowsHitTesting(false)`: `pointer-events: none` on the subtree. */
+  hitTesting?: boolean;
+}
+
+export type DragPhase = 'began' | 'changed' | 'ended' | 'cancelled';
+
+/**
+ * A `gesture` with `drag`: coalesced to one per animation frame while
+ * `changed`. Coordinates are points relative to the element's box;
+ * `velocity` is in points per second (`ended` only, else 0).
+ */
+export interface DragEvent {
+  type: 'drag';
+  id: ElementId;
+  phase: DragPhase;
+  translation: { width: number; height: number };
+  location: Point;
+  startLocation: Point;
+  velocity: { width: number; height: number };
+}
+/** A `gesture` with `longPress` was held `minimumDuration` without moving 10 px. */
+export interface LongPressEvent {
+  type: 'longpress';
+  id: ElementId;
+}
+/** A `listrow` was swiped to delete or its edit-mode Delete button tapped. */
+export interface DeleteEvent {
+  type: 'delete';
+  id: ElementId;
+}
+/** A `list` / `scrollview` with `refreshable` was pulled past 60 pt. */
+export interface RefreshEvent {
+  type: 'refresh';
+  id: ElementId;
+}
+
+/** The Phase 8 events (merged into `RendererEvent` above). */
+export type InteractionEvent = DragEvent | LongPressEvent | DeleteEvent | RefreshEvent;
+// Phase 8: alerts, controls, effects
+// (docs/ops-protocol.md, "Phase 8: interaction"; gestures, swipe actions,
+// context menus, list rows and refresh live in their own block)
+// ---------------------------------------------------------------------------
+
+export type AlertStyle = 'alert' | 'dialog';
+/**
+ * A root-level element (child of id 0) placed after the tree, like `sheet`.
+ * The children are the `button`s in order; a `cancel` role is drawn apart.
+ * With no button children the renderer draws an "OK" that sends `tap` with
+ * the alert's own id; so does a tap on a dialog's scrim.
+ */
+export interface AlertProps {
+  title: string;
+  message: string | null;
+  style: AlertStyle;
+}
+
+/** The label (may be empty) is the child; a tap on a half sends `step` ±1. */
+export interface StepperProps {
+  canIncrement: boolean;
+  canDecrement: boolean;
+}
+
+export type SliderLabel = 'label' | 'min' | 'max';
+/**
+ * The children are `[label?, minimumValueLabel?, maximumValueLabel?]`, those
+ * present in that order, named by `labels`. Dragging sends `slide` with the
+ * value in `min…max` snapped to `step`; `value` is authoritative.
+ */
+export interface SliderProps {
+  value: number;
+  min: number;
+  max: number;
+  step: number | null;
+  labels?: SliderLabel[];
+}
+
+export type DatePickerComponents = 'date' | 'hourAndMinute' | 'dateAndTime';
+/**
+ * Compact style: the label child leads, one or two capsules trail showing
+ * `seconds` (since 1970, UTC) formatted in US English. A change in the native
+ * picker sends `date` with the combined seconds.
+ */
+export interface DatePickerProps {
+  seconds: number;
+  components: DatePickerComponents;
+  min: number | null;
+  max: number | null;
+  /** `.labelsHidden()`: the label child is not laid out. */
+  labelsHidden?: boolean;
+}
+
+/** A `<textarea>` filling the proposal; input sends `text` like a `textfield`. */
+export interface TextEditorProps {
+  text: string;
+}
+
+/** A `stepper` half was tapped: +1 or −1. */
+export interface StepEvent {
+  type: 'step';
+  id: ElementId;
+  value: number;
+}
+/** A `slider` was dragged or tapped: the value in its range, snapped to `step`. */
+export interface SlideEvent {
+  type: 'slide';
+  id: ElementId;
+  value: number;
+}
+/** A `datepicker` changed: seconds since 1970, UTC. */
+export interface DateEvent {
+  type: 'date';
+  id: ElementId;
+  value: number;
+}
+export type Phase8ControlEvent = StepEvent | SlideEvent | DateEvent | FocusEvent | SubmitEvent;
+
+/** Phase 12: a bound `textfield` (one with `focused` in its props) gained or lost focus. */
+export interface FocusEvent {
+  type: 'focus';
+  id: ElementId;
+  value: boolean;
+}
+
+/** Phase 12: the Enter key in a `textfield` with `submit`. */
+export interface SubmitEvent {
+  type: 'submit';
+  id: ElementId;
+}
+
+/** Phase 12: `.preferredColorScheme` arrives as an `update` of the root with this; `null` returns to the viewer's setting. */
+export interface RootProps {
+  colorScheme?: 'light' | 'dark' | null;
+}
+
+export interface ElementPropsByKind {
+  alert: AlertProps;
+  stepper: StepperProps;
+  slider: SliderProps;
+  datepicker: DatePickerProps;
+  texteditor: TextEditorProps;
+}
+
+export const PHASE8_CONTROL_KINDS: readonly ElementKind[] = ['alert', 'stepper', 'slider', 'datepicker', 'texteditor'];
+
+/** `.rotation3DEffect(_:axis:anchor:perspective:)`. */
+export interface Rotation3D {
+  /** Degrees. */
+  angle: number;
+  axis: { x: number; y: number; z: number };
+  /** Unit point the rotation turns around (default 0.5/0.5). */
+  anchor?: UnitPoint;
+  /** SwiftUI's perspective factor (default 1 → a 500px CSS perspective). */
+  perspective?: number;
+}
+
+export interface Style {
+  /**
+   * CSS `perspective(500px / perspective) rotate3d(x, y, z, angle)`, composed
+   * after the 2D rotation and before the scale (see styles.ts `effectsCSS`).
+   */
+  rotation3D?: Rotation3D;
+  /** `.blur(radius:)`: `filter: blur(<radius>px)`, combined with `shadow` in one `filter`. */
+  blur?: number;
+  /**
+   * `.ignoresSafeArea(edges:)`: the engine extends the box to the screen
+   * edge on each listed side when the box touches that safe-area edge. The
+   * child's proposal and position are unchanged (the extension is background).
+   */
+  ignoresSafeArea?: 'all' | Edge[];
+}
+
+/** `.repeatCount(_:autoreverses:)` / `.repeatForever(autoreverses:)`. */
+export interface AnimationRepeat {
+  count: number | 'forever';
+  autoreverses: boolean;
+}
+
+export interface Animation {
+  /** WAAPI `iterations` (Infinity for `forever`) and `direction: alternate` when autoreversing. */
+  repeat?: AnimationRepeat;
+}
+
+/** `active` when visible and focused, `inactive` when visible but unfocused, `background` when hidden. */
+export type ScenePhase = 'active' | 'inactive' | 'background';
+
+export interface EnvironmentEvent {
+  scenePhase?: ScenePhase;
+}