@swiftbrowser/web 0.1.0

package/src/renderer.ts

@@ -0,0 +1,2882 @@
+/**
+ * DOM renderer for the ops protocol (docs/ops-protocol.md).
+ *
+ * The renderer owns a `Map<ElementId, HTMLElement>` and a mirror of the
+ * element tree as `LayoutNode`s; id 0 is the root container supplied by the
+ * host page. Every op is applied to the DOM immediately; at `commit` the
+ * layout engine (src/layout) computes a frame for every element and
+ * `layoutDom.ts` positions the elements absolutely from it (a `sb:commit`
+ * CustomEvent is dispatched on the root so tests and tooling can observe pass
+ * boundaries). Animated passes are handed to the `Animator`.
+ *
+ * Most kinds are a single DOM element whose children are the element's
+ * children. Compound kinds (`navstack`, `navscreen`, `section`, `toggle`,
+ * `navlink`, `tabview`) own some chrome of their own (a navigation bar, a
+ * switch, a chevron, a tab bar...) and expose a *slot* element that receives
+ * the protocol children, so `insert` indices stay exact.
+ *
+ * Phase 4: after every layout pass the renderer compares each `geometry`
+ * element's frame size with the size it last reported and sends one
+ * `geometry` event per changed element (batched after the ops being applied),
+ * so Swift's re-render converges as soon as the size is stable.
+ *
+ * Phase 6 (docs/phase6/chrome.md): `menu` opens the same popover a `menu`
+ * picker does, built from its item children when it opens; `toolbar` and
+ * `searchfield` are navscreen children the engine places in the bar;
+ * `tapgesture` sends a `tap` for a click anywhere on it that no inner
+ * control claimed.
+ *
+ * Phase 7: `navsplit` holds two `navstack` columns with a hairline between
+ * them (`.sb-navsplit-separator`, placed from the engine's `separator` rect);
+ * a `navlink` with `selected: true` carries `data-sb-selected` (a rounded fill
+ * background; the engine drops its chevron inside a split view's sidebar);
+ * the candidates a `viewthatfits` did not choose get the `hidden` attribute.
+ */
+
+import {
+  Animator,
+  EXIT_CLONE_CLASS,
+  emptyPass,
+  setTransition,
+  transitionOf,
+  type PassRecord,
+  type UpdatedRecord,
+} from './animation';
+import {
+  CanvasTextMeasurer,
+  LayoutPass,
+  type LayoutEnvironment,
+  type LayoutNode,
+  type LayoutResult,
+  type Rect,
+} from './layout';
+import { LayoutReporter } from './layoutEvents';
+import { applyLayout, setTabHidden, type BoxChange } from './layoutDom';
+import { ghostClone } from './ghost';
+import { InteractionController, type InteractionHost } from './interaction';
+import { symbolOf, textOf, unwrapStyledNode } from './nodeQueries';
+import {
+  INTERACTION_KINDS,
+  ROOT_ID,
+  isAssetImage,
+  type Animation,
+  type ButtonProps,
+  type ChartItemProps,
+  type ChartProps,
+  type ColorProps,
+  type ColorScheme,
+  type DecoratedProps,
+  type DynamicTypeSize,
+  type ElementId,
+  type ElementKind,
+  type ElementProps,
+  type ElementPropsByKind,
+  type FontWeight,
+  type GaugeProps,
+  type GeometryEvent,
+  type GestureProps,
+  type GridProps,
+  type GridRowProps,
+  type HStackProps,
+  type LayoutEvent,
+  type LazyVGridProps,
+  type ImageProps,
+  type ListProps,
+  type ListRowProps,
+  type NavLinkProps,
+  type NavScreenProps,
+  type Op,
+  type PickerProps,
+  type RendererEvent,
+  type ScrollViewProps,
+  type SearchFieldProps,
+  type SectionProps,
+  type ShapeProps,
+  type SheetProps,
+  type SpacerProps,
+  type Style,
+  type StyledProps,
+  type SwipeActionsProps,
+  type TabProps,
+  type TabViewProps,
+  type TextFieldProps,
+  type TextProps,
+  type ToggleProps,
+  type ToolbarProps,
+  type ViewThatFitsProps,
+  type VStackProps,
+  type ZStackProps,
+  // Phase 8: alerts, controls, effects
+  type AlertProps,
+  type DatePickerProps,
+  type SliderProps,
+  type StepperProps,
+  type TextEditorProps,
+  type RootProps,
+} from './protocol';
+import {
+  combineDateSeconds,
+  dateInputValue,
+  formatPickerDate,
+  formatPickerTime,
+  sameUTCDay,
+  sliderFraction,
+  snapSliderValue,
+  timeInputValue,
+} from './layout';
+import { renderSymbol } from './symbols';
+import { EMPTY_CATALOG, assetColorVar, type AssetCatalog } from './assets';
+import { colorToCSS, effectsCSS, styleToCSS, type PaintCSS } from './styles';
+import { DEFAULT_TYPE_SIZE, TEXT_STYLE_WEIGHT, resolveTextStyle, textStyleVar } from './typography';
+
+export type EventCallback = (event: RendererEvent) => void;
+
+export class RendererError extends Error {
+  constructor(message: string, readonly op?: Op) {
+    super(op ? `${message} (op: ${JSON.stringify(op)})` : message);
+    this.name = 'RendererError';
+  }
+}
+
+const KIND_ATTR = 'sbKind';
+const ID_ATTR = 'sbId';
+/** `animationToken` of a `styled` box, kept across `update` to detect changes. */
+const ANIMATION_TOKEN = 'sbAnimationToken';
+
+/** Duration of the navigation push/pop slide; keep in sync with styles.css (`--sb-nav-easing`). */
+export const NAV_TRANSITION_MS = 400;
+/** Duration of the sheet present/dismiss slide; keep in sync with styles.css. */
+export const SHEET_TRANSITION_MS = 400;
+// Phase 8: the sheet drag (and every other pointer gesture) lives in src/interaction.ts.
+export { SHEET_DISMISS_DRAG } from './interaction';
+
+const ALL_KINDS: ReadonlySet<string> = new Set<ElementKind>([
+  'text',
+  'vstack',
+  'hstack',
+  'spacer',
+  'button',
+  'styled',
+  'zstack',
+  'image',
+  'divider',
+  'scrollview',
+  'list',
+  'section',
+  'textfield',
+  'toggle',
+  'navstack',
+  'navscreen',
+  'navlink',
+  'color',
+  'shape',
+  'sheet',
+  'tabview',
+  'tab',
+  'picker',
+  'geometry',
+  'layout',
+  'grid',
+  'gridrow',
+  'lazyvgrid',
+  'gauge',
+  'decorated',
+  'menu',
+  'toolbar',
+  'searchfield',
+  'tapgesture',
+  // Phase 7
+  'navsplit',
+  'viewthatfits',
+  'chart',
+  'chartitem',
+  // Phase 8: gestures, rows, navigation
+  ...INTERACTION_KINDS,
+  // Phase 8: alerts, controls
+  'alert',
+  'stepper',
+  'slider',
+  'datepicker',
+  'texteditor',
+]);
+
+/** Duration of the alert / dialog fade (Phase 8); keep in sync with styles.css. */
+export const ALERT_TRANSITION_MS = 250;
+/** Diameter of the slider thumb (Phase 8); keep in sync with the engine and styles.css. */
+const SLIDER_THUMB = 27;
+
+/** Width of the menu a `menu` picker (or a Phase 6 `menu`) opens, like an iOS context menu. */
+export const PICKER_MENU_WIDTH = 250;
+/** Row height inside the picker menu. */
+export const PICKER_MENU_ROW = 44;
+/** Height of a section header caption row in the popover (Phase 6). */
+const MENU_CAPTION_HEIGHT = 32;
+/** Thickness of a group separator in the popover (Phase 6). */
+const MENU_SEPARATOR_HEIGHT = 8;
+/** Gap between the control and its menu. */
+const PICKER_MENU_GAP = 4;
+/** Minimum distance between the menu and the screen edge. */
+const PICKER_MENU_MARGIN = 8;
+
+/** Kinds whose enter/exit is animated by their own CSS, not by transitions. */
+const SELF_ANIMATING: ReadonlySet<string> = new Set(['navscreen', 'sheet', 'alert']);
+
+/** `styled` animations by element (cleared on `update`). */
+const ANIMATIONS = new WeakMap<HTMLElement, Animation>();
+
+/** iPhone 15 Pro logical screen, used when the root is not rendered (tests, hidden tabs). */
+const DEFAULT_SCREEN = { width: 393, height: 852 };
+const DEFAULT_SAFE_AREA = { top: 59, leading: 0, bottom: 34, trailing: 0 };
+
+/** The parts of the layout environment the page controls. */
+export interface RendererEnvironment {
+  dynamicTypeSize: DynamicTypeSize;
+  colorScheme: ColorScheme;
+}
+
+export class Renderer {
+  /** All live elements by id, including the root (id 0). */
+  readonly elements = new Map<ElementId, HTMLElement>();
+  /** The element tree as the layout engine reads it; id 0 is the root. */
+  readonly nodes = new Map<ElementId, LayoutNode>();
+  /** Parent id of every attached element. */
+  readonly parents = new Map<ElementId, ElementId>();
+  private readonly root: HTMLElement;
+  private readonly onEvent: EventCallback;
+  /** Animates style changes, frame changes and transitions of animated passes. */
+  readonly animator: Animator;
+  /** Number of `commit` ops applied so far. */
+  commits = 0;
+  /** Number of layout passes run so far. */
+  layouts = 0;
+  /** The most recent layout result (null before the first commit). */
+  layoutResult: LayoutResult | null = null;
+  /** What the current render pass did so far (handed to the Animator at `commit`). */
+  private pass: PassRecord = emptyPass();
+  /**
+   * Phase 8: owns every pointer gesture (drags, long presses, swipe rows,
+   * swipe back, the sheet drag, pull to refresh) and arbitrates between them.
+   */
+  readonly interaction: InteractionController;
+  private readonly measurer = new CanvasTextMeasurer();
+  /**
+   * Phase 9: the layout pass lives across commits and is told what changed
+   * (`update`, `insert`, `remove`), so a commit lays out only the subtrees
+   * it touched. Replaced whenever the environment (screen size, type size,
+   * color scheme, fonts) changes, which invalidates everything.
+   */
+  private engine: LayoutPass | null = null;
+  private engineEnvKey = '';
+  private environment: RendererEnvironment = { dynamicTypeSize: 'large', colorScheme: 'light' };
+  /** Phase 5: the app's asset catalog manifest (empty until `setAssetCatalog`). */
+  private assets: AssetCatalog = EMPTY_CATALOG;
+  /** The `<style>` holding the catalog colors as custom properties (see `setAssetCatalog`). */
+  private assetStyle: HTMLStyleElement | null = null;
+  /** Safe-area insets; read from the device tokens on first use unless `setSafeArea` set them. */
+  private safeArea: LayoutEnvironment['safeArea'] | null = null;
+  /** DOM boxes applied by the last layout, by id (see layoutDom.ts). */
+  private boxes = new Map<ElementId, Rect>();
+  /** Elements whose inline style was reset since the last layout. */
+  private readonly dirty = new Set<ElementId>();
+  /** The open popover (of a `menu` picker or a `menu` element), if any. */
+  private menu: OpenMenu | null = null;
+  /** Size last reported for every `geometry` element (whole px). */
+  private readonly reportedGeometry = new Map<ElementId, { width: number; height: number }>();
+  /** `geometry` and `layout` events collected by layout passes, sent once the ops are applied. */
+  private pendingGeometry: (GeometryEvent | LayoutEvent)[] = [];
+  /** Phase 6: dedupes `layout` events per element (src/layoutEvents.ts). */
+  private readonly layoutReporter = new LayoutReporter();
+  /** Nesting depth of `applyOps` (events are flushed when it returns to 0). */
+  private applying = 0;
+
+  private readonly onClick = (event: MouseEvent): void => {
+    // `closest` picks the innermost control, so a button inside a
+    // `tapgesture` (or a menu label) handles the click alone.
+    const target = (event.target as HTMLElement | null)?.closest<HTMLElement>(
+      '.sb-button, .sb-navlink, .sb-navbar-back, .sb-switch, .sb-sheet-scrim, ' +
+        '.sb-tabbar-item, .sb-segment, .sb-picker-option, .sb-picker-menu-item, .sb-picker[data-sb-style="menu"], ' +
+        '.sb-menu, .sb-tapgesture, .sb-stepper-button, .sb-alert-scrim, .sb-alert-ok, ' +
+        // Phase 8: swipe action buttons, the edit-mode row control and selectable rows (the row sends `tap` itself)
+        '.sb-swipe-action, .sb-listrow-control, .sb-listrow[data-sb-selectable]',
+    );
+    if (!target || !this.root.contains(target)) return;
+    if (this.interaction.handleClick(target)) {
+      event.preventDefault();
+      return;
+    }
+    if (target.classList.contains('sb-stepper-button')) {
+      // Phase 8: a half of the −/+ control; a dimmed half (`canDecrement` /
+      // `canIncrement` false) swallows the click.
+      const stepper = target.closest<HTMLElement>('.sb-stepper');
+      const id = Number(stepper?.dataset[ID_ATTR]);
+      const value = Number(target.dataset['sbStep']);
+      if (!stepper || !Number.isInteger(id) || !Number.isInteger(value)) return;
+      event.preventDefault();
+      if (target.getAttribute('aria-disabled') === 'true') return;
+      this.onEvent({ type: 'step', id, value });
+      return;
+    }
+    if (target.classList.contains('sb-alert-scrim') || target.classList.contains('sb-alert-ok')) {
+      // Phase 8: the renderer-drawn OK, or the scrim of a dialog (an alert
+      // with buttons is modal; without any it dismisses too) ask Swift to
+      // dismiss with the alert's own id.
+      const alert = target.closest<HTMLElement>('.sb-alert');
+      const id = Number(alert?.dataset[ID_ATTR]);
+      if (!alert || !Number.isInteger(id)) return;
+      event.preventDefault();
+      if (target.classList.contains('sb-alert-scrim')) {
+        const hasButtons = alert.querySelector('.sb-alert-buttons > [data-sb-id]') !== null;
+        if (alert.dataset['sbStyle'] !== 'dialog' && hasButtons) return;
+      }
+      this.onEvent({ type: 'tap', id });
+      return;
+    }
+    if (target.classList.contains('sb-tabbar-item')) {
+      // A tab bar item asks Swift to select the tab; `selected` is authoritative.
+      const tabview = target.closest<HTMLElement>('.sb-tabview');
+      const id = Number(tabview?.dataset[ID_ATTR]);
+      const index = Number(target.dataset['sbIndex']);
+      if (!tabview || !Number.isInteger(id) || !Number.isInteger(index)) return;
+      event.preventDefault();
+      this.onEvent({ type: 'select', id, value: index });
+      return;
+    }
+    if (target.classList.contains('sb-segment') || target.classList.contains('sb-picker-option')) {
+      const picker = target.closest<HTMLElement>('.sb-picker');
+      const id = Number(picker?.dataset[ID_ATTR]);
+      const index = Number(target.dataset['sbIndex']);
+      if (!picker || !Number.isInteger(id) || !Number.isInteger(index)) return;
+      event.preventDefault();
+      // Move the pill / checkmark right away; Swift's `update` confirms (or reverts) it.
+      setPickerSelection(picker, index);
+      this.onEvent({ type: 'select', id, value: index });
+      return;
+    }
+    if (target.classList.contains('sb-picker-menu-item')) {
+      // A popover row: a picker option (`select`) or a button / navlink (`tap`).
+      if (!this.menu) return;
+      const action = target.dataset['sbAction'];
+      const id = Number(target.dataset['sbTarget']);
+      const index = Number(target.dataset['sbIndex']);
+      if (!Number.isInteger(id)) return;
+      event.preventDefault();
+      this.closeMenu();
+      if (action === 'tap') this.onEvent({ type: 'tap', id });
+      else if (Number.isInteger(index)) this.onEvent({ type: 'select', id, value: index });
+      return;
+    }
+    if (target.classList.contains('sb-picker') || target.classList.contains('sb-menu')) {
+      const id = Number(target.dataset[ID_ATTR]);
+      if (!Number.isInteger(id)) return;
+      event.preventDefault();
+      if (this.menu?.anchorId === id) this.closeMenu();
+      else if (target.classList.contains('sb-menu')) this.openMenu(target, id, this.menuRows(id));
+      else this.openMenu(target, id, this.pickerRows(id));
+      return;
+    }
+    if (target.classList.contains('sb-sheet-scrim')) {
+      // A tap outside the card asks Swift to dismiss the sheet.
+      const sheet = target.closest<HTMLElement>('.sb-sheet');
+      const id = Number(sheet?.dataset[ID_ATTR]);
+      if (!sheet || !Number.isInteger(id)) return;
+      event.preventDefault();
+      this.onEvent({ type: 'tap', id });
+      return;
+    }
+    if (target.classList.contains('sb-navbar-back')) {
+      const id = Number(target.dataset['sbTarget']);
+      if (!Number.isInteger(id)) return;
+      event.preventDefault();
+      this.onEvent({ type: 'tap', id });
+      return;
+    }
+    if (target.classList.contains('sb-switch')) {
+      const toggle = target.closest<HTMLElement>('.sb-toggle');
+      const id = Number(toggle?.dataset[ID_ATTR]);
+      if (!toggle || !Number.isInteger(id)) return;
+      event.preventDefault();
+      const value = target.getAttribute('aria-checked') !== 'true';
+      // Flip optimistically so the switch animates right away; Swift's
+      // `update` confirms (or reverts) the state.
+      setSwitchState(toggle, value);
+      this.onEvent({ type: 'toggle', id, value });
+      return;
+    }
+    const id = Number(target.dataset[ID_ATTR]);
+    if (!Number.isInteger(id)) return;
+    event.preventDefault();
+    this.onEvent({ type: 'tap', id });
+  };
+
+  /**
+   * Phase 12: after a commit, the bound text fields (`data-sb-focus`) take or
+   * give up focus to match what Swift asked for. The `focus` event the move
+   * raises is echoed back so the state and the DOM agree.
+   */
+  private syncFocus(): void {
+    const active = document.activeElement;
+    for (const input of this.root.querySelectorAll<HTMLInputElement>('.sb-textfield[data-sb-focus]')) {
+      const wanted = input.dataset['sbFocus'] === 'true';
+      if (wanted && active !== input) input.focus();
+      else if (!wanted && active === input) input.blur();
+    }
+  }
+
+  /** Phase 12: a bound field (`data-sb-focus`) reports focus changes. */
+  private readonly onFocusChange = (event: FocusEvent): void => {
+    const input = event.target as HTMLInputElement | null;
+    if (!input || !(input instanceof HTMLInputElement) || !input.classList.contains('sb-textfield')) return;
+    if (input.dataset['sbFocus'] === undefined || !this.root.contains(input)) return;
+    const id = Number(input.dataset[ID_ATTR]);
+    if (!Number.isInteger(id)) return;
+    const focused = event.type === 'focusin';
+    if (input.dataset['sbFocus'] === String(focused)) return;
+    input.dataset['sbFocus'] = String(focused);
+    this.onEvent({ type: 'focus', id, value: focused });
+  };
+
+  private readonly onKeyDown = (event: KeyboardEvent): void => {
+    if (event.key === 'Escape' && this.menu) {
+      event.preventDefault();
+      this.closeMenu();
+      return;
+    }
+    if (event.key !== 'Enter' && event.key !== ' ') return;
+    const target = event.target as HTMLElement | null;
+    if (!target) return;
+    // Phase 12: Enter in a text field under `.onSubmit`.
+    if (event.key === 'Enter' && target.classList.contains('sb-textfield') && target.dataset['sbSubmit'] === 'true') {
+      const id = Number(target.dataset[ID_ATTR]);
+      if (Number.isInteger(id)) {
+        event.preventDefault();
+        this.onEvent({ type: 'submit', id });
+      }
+      return;
+    }
+    if (
+      !target.classList.contains('sb-navlink') &&
+      !target.classList.contains('sb-menu') &&
+      !(target.classList.contains('sb-picker') && target.dataset['sbStyle'] === 'menu')
+    ) {
+      return;
+    }
+    event.preventDefault();
+    target.click();
+  };
+
+  /**
+   * While a picker menu is open, a click anywhere outside it closes the menu;
+   * inside the screen the click is swallowed so nothing under the pointer
+   * fires (iOS dismisses a menu without passing the tap through).
+   */
+  private readonly onDocumentClick = (event: MouseEvent): void => {
+    const menu = this.menu;
+    if (!menu) return;
+    const target = event.target as Node | null;
+    if (target && menu.el.contains(target)) return;
+    this.closeMenu();
+    if (target && this.root.contains(target)) {
+      event.stopPropagation();
+      event.preventDefault();
+    }
+  };
+
+  private readonly onInput = (event: Event): void => {
+    const input = event.target as HTMLInputElement | null;
+    if (!input || !this.root.contains(input)) return;
+    // A `textfield` (or a Phase 8 `texteditor`) is the input itself; a
+    // `searchfield` wraps its input.
+    const isField = input.classList.contains('sb-textfield') || input.classList.contains('sb-texteditor');
+    const isSearch = input.classList.contains('sb-searchfield-input');
+    if (!isField && !isSearch) return;
+    const owner = isField ? input : input.closest<HTMLElement>('.sb-searchfield');
+    const id = Number(owner?.dataset[ID_ATTR]);
+    if (!Number.isInteger(id)) return;
+    this.onEvent({ type: 'text', id, value: input.value });
+  };
+
+  /**
+   * Phase 8: the native `<input type="date|time">` over a `datepicker`
+   * capsule committed a value. The changed component replaces its part of
+   * the picker's `seconds`; the other part is kept.
+   */
+  private readonly onChange = (event: Event): void => {
+    const input = event.target as HTMLInputElement | null;
+    if (!input || !input.classList.contains('sb-datepicker-input') || !this.root.contains(input)) return;
+    const picker = input.closest<HTMLElement>('.sb-datepicker');
+    const id = Number(picker?.dataset[ID_ATTR]);
+    if (!picker || !Number.isInteger(id) || input.value === '') return;
+    const seconds = Number(picker.dataset['sbSeconds']) || 0;
+    const value = combineDateSeconds(seconds, input.type === 'date' ? { date: input.value } : { time: input.value });
+    if (value === seconds) return;
+    // Show the new value right away; Swift's `update` confirms (or reverts) it.
+    picker.dataset['sbSeconds'] = String(value);
+    setDatePickerValue(picker, value);
+    this.onEvent({ type: 'date', id, value });
+  };
+
+  // Phase 8 slider: a pointer on the slider moves the thumb to it and follows
+  // it; `slide` events are coalesced to one per animation frame.
+  private sliderDrag: SliderDrag | null = null;
+
+  private beginSliderDrag(slider: HTMLElement, event: PointerEvent): void {
+    const track = slider.querySelector<HTMLElement>(':scope > .sb-slider-track');
+    const id = Number(slider.dataset[ID_ATTR]);
+    if (!track || !Number.isInteger(id)) return;
+    event.preventDefault();
+    const drag: SliderDrag = { slider, track, id, pointerId: event.pointerId, pending: null, sent: null, frame: null };
+    this.sliderDrag = drag;
+    window.addEventListener('pointermove', this.onSliderMove);
+    window.addEventListener('pointerup', this.onSliderUp);
+    window.addEventListener('pointercancel', this.onSliderUp);
+    this.slideTo(drag, event.clientX);
+  }
+
+  private slideTo(drag: SliderDrag, clientX: number): void {
+    const rect = drag.track.getBoundingClientRect();
+    // The presenting tree may be scaled (behind a sheet): measure the thumb in screen px too.
+    const scale = drag.track.offsetWidth > 0 ? rect.width / drag.track.offsetWidth : 1;
+    const thumb = SLIDER_THUMB * scale;
+    const travel = rect.width - thumb;
+    const fraction = travel > 0 ? (clientX - rect.left - thumb / 2) / travel : 0;
+    const min = Number(drag.slider.dataset['sbMin']) || 0;
+    const max = Number(drag.slider.dataset['sbMax']);
+    const stepText = drag.slider.dataset['sbStep'];
+    const step = stepText ? Number(stepText) : null;
+    const value = snapSliderValue(fraction, min, Number.isFinite(max) ? max : 1, step);
+    setSliderPosition(drag.slider, sliderFraction(value, min, Number.isFinite(max) ? max : 1));
+    drag.pending = value;
+    if (drag.frame === null) {
+      drag.frame = window.requestAnimationFrame(() => {
+        drag.frame = null;
+        this.flushSlide(drag);
+      });
+    }
+  }
+
+  private flushSlide(drag: SliderDrag): void {
+    if (drag.pending === null || drag.pending === drag.sent) return;
+    drag.sent = drag.pending;
+    this.onEvent({ type: 'slide', id: drag.id, value: drag.pending });
+  }
+
+  private readonly onSliderMove = (event: PointerEvent): void => {
+    const drag = this.sliderDrag;
+    if (!drag || event.pointerId !== drag.pointerId) return;
+    this.slideTo(drag, event.clientX);
+  };
+
+  private readonly onSliderUp = (event: PointerEvent): void => {
+    const drag = this.sliderDrag;
+    if (!drag || event.pointerId !== drag.pointerId) return;
+    this.sliderDrag = null;
+    window.removeEventListener('pointermove', this.onSliderMove);
+    window.removeEventListener('pointerup', this.onSliderUp);
+    window.removeEventListener('pointercancel', this.onSliderUp);
+    if (drag.frame !== null) window.cancelAnimationFrame(drag.frame);
+    drag.frame = null;
+    this.flushSlide(drag);
+    // The click that follows is the slide itself, not a tap on an enclosing control.
+    this.swallowNextClick();
+  };
+
+  /** Suppress the click that follows a drag so a control under the pointer does not fire. */
+  private swallowNextClick(): void {
+    const swallow = (click: Event): void => {
+      click.stopPropagation();
+      click.preventDefault();
+    };
+    this.root.addEventListener('click', swallow, { capture: true, once: true });
+    window.setTimeout(() => this.root.removeEventListener('click', swallow, { capture: true }), 0);
+  }
+
+  // Phase 8 slider: the pointer down that starts a drag (the gesture
+  // controller in src/interaction.ts leaves `.sb-slider` alone).
+  private readonly onSliderPointerDown = (event: PointerEvent): void => {
+    if (event.button !== 0 || this.sliderDrag) return;
+    const target = event.target as HTMLElement | null;
+    const slider = target?.closest<HTMLElement>('.sb-slider');
+    if (slider && this.root.contains(slider)) this.beginSliderDrag(slider, event);
+  };
+
+  constructor(root: HTMLElement, onEvent: EventCallback) {
+    this.root = root;
+    this.onEvent = onEvent;
+    root.dataset[ID_ATTR] = String(ROOT_ID);
+    root.dataset[KIND_ATTR] = 'root';
+    this.elements.set(ROOT_ID, root);
+    this.nodes.set(ROOT_ID, { id: ROOT_ID, kind: 'root', props: {}, children: [] });
+    this.animator = new Animator(root, { selfAnimatingKinds: SELF_ANIMATING });
+    // Delegated listeners instead of one per control: elements can be
+    // created detached and moved around freely.
+    root.addEventListener('click', this.onClick);
+    root.addEventListener('keydown', this.onKeyDown);
+    root.addEventListener('input', this.onInput);
+    root.addEventListener('focusin', this.onFocusChange);
+    root.addEventListener('focusout', this.onFocusChange);
+    // Phase 8: pointer gestures (the sheet drag among them) are delegated too.
+    const host: InteractionHost = {
+      root,
+      send: (event) => this.onEvent(event),
+      nodeOf: (id) => this.nodes.get(id),
+      openContextMenu: (anchor, id) => this.openContextMenu(anchor, id),
+      isMenuOpen: (id) => this.menu?.anchorId === id,
+      closeMenu: () => this.closeMenu(),
+    };
+    this.interaction = new InteractionController(host);
+    root.addEventListener('change', this.onChange);
+    root.addEventListener('pointerdown', this.onSliderPointerDown);
+  }
+
+  /** Apply a batch of ops in order. Throws `RendererError` on an invalid op. */
+  applyOps(ops: readonly Op[]): void {
+    this.applying += 1;
+    try {
+      this.applyAll(ops);
+    } finally {
+      this.applying -= 1;
+    }
+    // Geometry events go out after the whole batch (one batch per layout
+    // pass); Swift's answer re-enters `applyOps` with the next pass.
+    if (this.applying === 0) this.flushGeometry();
+  }
+
+  private applyAll(ops: readonly Op[]): void {
+    for (const op of ops) {
+      switch (op.op) {
+        case 'create':
+          this.create(op.id, op.kind, op.props, op);
+          break;
+        case 'update':
+          this.update(op.id, op.props, op);
+          break;
+        case 'insert':
+          this.insert(op.parent, op.id, op.index, op);
+          break;
+        case 'remove':
+          this.remove(op.id, op);
+          break;
+        case 'defaults':
+          // Consumed by the loader (wasm.ts); nothing to render.
+          break;
+        case 'commit': {
+          const pass = this.pass;
+          this.pass = emptyPass();
+          const changes = this.layout();
+          this.animator.commit(pass, op.animation, changes);
+          this.commits += 1;
+          this.syncFocus();
+          this.root.dispatchEvent(
+            new CustomEvent('sb:commit', { detail: { commits: this.commits, animation: op.animation ?? null } }),
+          );
+          break;
+        }
+        default: {
+          const unknown: never = op;
+          throw new RendererError(`Unknown op ${JSON.stringify(unknown)}`);
+        }
+      }
+    }
+  }
+
+  /** Detach everything under the root and forget all non-root elements. */
+  reset(): void {
+    this.root.replaceChildren();
+    this.elements.clear();
+    this.elements.set(ROOT_ID, this.root);
+    this.nodes.clear();
+    this.nodes.set(ROOT_ID, { id: ROOT_ID, kind: 'root', props: {}, children: [] });
+    this.parents.clear();
+    this.boxes.clear();
+    this.dirty.clear();
+    this.layoutResult = null;
+    this.engine = null;
+    this.pass = emptyPass();
+    this.closeMenu();
+    this.reportedGeometry.clear();
+    this.layoutReporter.clear();
+    this.pendingGeometry = [];
+    refreshSheets(this.root);
+  }
+
+  // -------------------------------------------------------------------------
+  // Layout
+  // -------------------------------------------------------------------------
+
+  /**
+   * Set the device environment (Dynamic Type size, color scheme) and re-lay
+   * the tree out. The page calls this on boot and whenever a control changes.
+   */
+  setEnvironment(environment: Partial<RendererEnvironment>): void {
+    const next = { ...this.environment, ...environment };
+    if (next.dynamicTypeSize === this.environment.dynamicTypeSize && next.colorScheme === this.environment.colorScheme) {
+      return;
+    }
+    this.environment = next;
+    if (this.commits > 0) this.layout();
+  }
+
+  /**
+   * Phase 5: give the renderer the app's asset catalog manifest (src/assets.ts).
+   * Named images take their intrinsic size and `src` from it, and every
+   * catalog color becomes a `--sb-asset-color-<slug>` custom property
+   * declared for `.device[data-theme="light"]` and `.device[data-theme="dark"]`
+   * in one `<style>` element, so named colors follow the theme through plain
+   * CSS (`var()`) and need no re-render when it changes. Images already in
+   * the tree are re-resolved; the tree is laid out again.
+   */
+  setAssetCatalog(catalog: AssetCatalog | null): void {
+    this.assets = catalog ?? EMPTY_CATALOG;
+    const doc = this.root.ownerDocument;
+    const css = assetColorsCSS(this.assets);
+    if (css) {
+      if (!this.assetStyle) {
+        this.assetStyle = doc.createElement('style');
+        this.assetStyle.dataset['sbAssetColors'] = '';
+        (doc.head ?? doc.documentElement).append(this.assetStyle);
+      }
+      this.assetStyle.textContent = css;
+    } else if (this.assetStyle) {
+      this.assetStyle.remove();
+      this.assetStyle = null;
+    }
+    for (const [id, node] of this.nodes) {
+      if (node.kind !== 'image') continue;
+      const el = this.elements.get(id);
+      if (el) applyImage(el, node.props as unknown as ImageProps, this.assets);
+    }
+    // Catalog sizes feed image measurement: start the layout pass over.
+    this.engine = null;
+    if (this.commits > 0) this.layout();
+  }
+
+  /** The asset catalog in use (empty when the app has none). */
+  get assetCatalog(): AssetCatalog {
+    return this.assets;
+  }
+
+  /**
+   * Use explicit safe-area insets (device mode: the real `env(safe-area-inset-*)`
+   * values) instead of the frame's `--device-safe-top/bottom` tokens; `null`
+   * goes back to the tokens. Re-lays the tree out when the insets changed.
+   */
+  setSafeArea(insets: LayoutEnvironment['safeArea'] | null): void {
+    const next = insets ? { ...insets } : readSafeArea(this.root);
+    const current = this.safeArea;
+    if (
+      current &&
+      current.top === next.top &&
+      current.leading === next.leading &&
+      current.bottom === next.bottom &&
+      current.trailing === next.trailing
+    ) {
+      return;
+    }
+    this.safeArea = next;
+    if (this.commits > 0) this.layout();
+  }
+
+  /**
+   * The root's size changed (device mode: a resize or rotation). The engine
+   * reads `#screen`'s current size on every pass, so this just re-lays out.
+   */
+  viewportChanged(): void {
+    if (this.commits > 0) this.layout();
+  }
+
+  /** The environment the engine lays out for. */
+  layoutEnvironment(): LayoutEnvironment {
+    const width = this.root.clientWidth || DEFAULT_SCREEN.width;
+    const height = this.root.clientHeight || DEFAULT_SCREEN.height;
+    if (!this.safeArea) this.safeArea = readSafeArea(this.root);
+    return {
+      screen: { width, height },
+      safeArea: this.safeArea,
+      dynamicTypeSize: this.environment.dynamicTypeSize,
+      devicePixelRatio: typeof window !== 'undefined' ? window.devicePixelRatio || 1 : 1,
+      colorScheme: this.environment.colorScheme,
+      assets: this.assets,
+    };
+  }
+
+  /**
+   * Run the layout engine over the current tree and position every element.
+   * Returns the elements whose box changed. Runs at every `commit`; call it
+   * directly after something the engine cannot see changed (fonts loaded,
+   * device size).
+   */
+  layout(): BoxChange[] {
+    const root = this.nodes.get(ROOT_ID);
+    if (!root) return [];
+    const env = this.layoutEnvironment();
+    const envKey = JSON.stringify({ ...env, assets: undefined });
+    if (!this.engine || envKey !== this.engineEnvKey) {
+      this.engine = new LayoutPass(env, this.measurer, (node) => {
+        const parentId = this.parents.get(node.id);
+        return parentId === undefined ? null : (this.nodes.get(parentId) ?? null);
+      });
+      this.engineEnvKey = envKey;
+    }
+    const result = this.engine.run(root.children);
+    this.layoutResult = result;
+    this.layouts += 1;
+    const ctx = {
+      root: this.root,
+      elements: this.elements,
+      nodes: this.nodes,
+      parents: this.parents,
+      boxes: this.boxes,
+      dirty: this.dirty,
+      env,
+    };
+    const changes = applyLayout(ctx, result);
+    this.boxes = ctx.boxes;
+    this.collectGeometry(result);
+    this.collectLayouts(result);
+    if (this.applying === 0) this.flushGeometry();
+    return changes;
+  }
+
+  /**
+   * Queue a `geometry` event for every `geometry` element whose laid-out size
+   * (whole px) differs from the one last reported. Nothing is queued for an
+   * unchanged size, which is what lets the Swift re-render loop converge.
+   */
+  private collectGeometry(result: LayoutResult): void {
+    for (const [id, node] of this.nodes) {
+      if (node.kind !== 'geometry') continue;
+      const frame = result.frames.get(id);
+      if (!frame) continue; // e.g. inside a hidden tab
+      const width = Math.round(frame.width);
+      const height = Math.round(frame.height);
+      const last = this.reportedGeometry.get(id);
+      if (last && last.width === width && last.height === height) continue;
+      this.reportedGeometry.set(id, { width, height });
+      this.pendingGeometry.push({ type: 'geometry', id, width, height });
+    }
+  }
+
+  /**
+   * Phase 6: queue a `layout` event for every `layout` element whose record
+   * (the proposal it was placed with and its children's min / ideal / max)
+   * differs from the last one sent. Swift's answer updates the element's
+   * props, which lays out again; an unchanged record sends nothing, so the
+   * loop converges.
+   */
+  private collectLayouts(result: LayoutResult): void {
+    for (const event of this.layoutReporter.collect(result)) this.pendingGeometry.push(event);
+  }
+
+  /** Phase 6: the last `layout` event sent for every `layout` element (for tests). */
+  get reportedLayouts(): ReadonlyMap<ElementId, LayoutEvent> {
+    return this.layoutReporter.reported;
+  }
+
+  private flushGeometry(): void {
+    if (this.pendingGeometry.length === 0) return;
+    const events = this.pendingGeometry;
+    this.pendingGeometry = [];
+    // One `batch` per pass: Swift renders once for all of them.
+    if (events.length === 1) this.onEvent(events[0]!);
+    else this.onEvent({ type: 'batch', events });
+  }
+
+  // -------------------------------------------------------------------------
+  // Popover menus (a `menu` picker's options, or a Phase 6 `menu`'s items)
+  // -------------------------------------------------------------------------
+
+  /** The rows of a `menu` picker's popover: one radio row per option. */
+  private pickerRows(id: ElementId): MenuRow[] {
+    const node = this.nodes.get(id);
+    const props = (node?.props ?? {}) as Partial<PickerProps>;
+    const options = Array.isArray(props.options) ? props.options.map(String) : [];
+    const selected = clampIndex(props.selected, options.length);
+    return options.map((title, index) => ({ kind: 'select', id, index, title, checked: index === selected }));
+  }
+
+  /**
+   * The rows of a `menu` element's popover, built from its current items
+   * (every child but the label) so conditional items are reflected: buttons
+   * and navlinks become tap rows, pickers a checked section, dividers and
+   * sections separators and captions, texts disabled captions.
+   */
+  private menuRows(id: ElementId): MenuRow[] {
+    const node = this.nodes.get(id);
+    return node ? collectMenuRows(node.children.slice(1)) : [];
+  }
+
+  /** Open a popover of `rows` under (or above) `anchor`, which is element `id`. */
+  private openMenu(anchor: HTMLElement, id: ElementId, rows: MenuRow[]): void {
+    this.closeMenu();
+    const menu = div('sb-picker-menu');
+    menu.setAttribute('role', 'menu');
+    menu.dataset['sbFor'] = String(id);
+    let height = 0;
+    for (const row of rows) {
+      menu.append(menuRowElement(row));
+      height += row.kind === 'caption' ? MENU_CAPTION_HEIGHT : row.kind === 'separator' ? MENU_SEPARATOR_HEIGHT : PICKER_MENU_ROW;
+    }
+    // Anchor to the control: trailing edges aligned, below it when there is
+    // room, else above; clamped inside the screen.
+    const rootRect = this.root.getBoundingClientRect();
+    const anchorRect = anchor.getBoundingClientRect();
+    const width = Math.min(PICKER_MENU_WIDTH, Math.max(0, rootRect.width - 2 * PICKER_MENU_MARGIN));
+    let left = anchorRect.right - rootRect.left - width;
+    left = Math.max(PICKER_MENU_MARGIN, Math.min(left, rootRect.width - width - PICKER_MENU_MARGIN));
+    let top = anchorRect.bottom - rootRect.top + PICKER_MENU_GAP;
+    if (top + height > rootRect.height - PICKER_MENU_MARGIN) {
+      top = anchorRect.top - rootRect.top - PICKER_MENU_GAP - height;
+      menu.dataset['sbPlacement'] = 'above';
+    } else {
+      menu.dataset['sbPlacement'] = 'below';
+    }
+    top = Math.max(PICKER_MENU_MARGIN, top);
+    menu.style.left = `${Math.round(left)}px`;
+    menu.style.top = `${Math.round(top)}px`;
+    menu.style.width = `${Math.round(width)}px`;
+    this.root.append(menu);
+    anchor.setAttribute('aria-expanded', 'true');
+    this.menu = { el: menu, anchor, anchorId: id };
+    document.addEventListener('click', this.onDocumentClick, true);
+  }
+
+  /**
+   * Phase 8: open the popover of a `contextmenu` element (a long press or a
+   * right click on its content), its items (every child but the content)
+   * listed like a `menu`'s. Choosing one sends `tap` with the item's id.
+   */
+  openContextMenu(anchor: HTMLElement, id: ElementId): void {
+    if (this.menu?.anchorId === id) return;
+    const node = this.nodes.get(id);
+    if (!node || !this.root.contains(anchor)) return;
+    this.openMenu(anchor, id, collectMenuRows(node.children.slice(1)));
+  }
+
+  /** Close the open popover (no-op when none is open). */
+  closeMenu(): void {
+    const menu = this.menu;
+    if (!menu) return;
+    this.menu = null;
+    document.removeEventListener('click', this.onDocumentClick, true);
+    menu.el.remove();
+    menu.anchor.setAttribute('aria-expanded', 'false');
+  }
+
+  /** The open popover element (for tests), or null. */
+  get openMenuElement(): HTMLElement | null {
+    return this.menu?.el ?? null;
+  }
+
+  /** Drop cached text widths (after web fonts load) and lay out again. */
+  fontsChanged(): void {
+    this.measurer.clearCache();
+    this.engine = null;
+    if (this.commits > 0) this.layout();
+  }
+
+  dispose(): void {
+    this.closeMenu();
+    this.root.removeEventListener('click', this.onClick);
+    this.root.removeEventListener('keydown', this.onKeyDown);
+    this.root.removeEventListener('input', this.onInput);
+    this.root.removeEventListener('focusin', this.onFocusChange);
+    this.root.removeEventListener('focusout', this.onFocusChange);
+    this.interaction.dispose();
+    this.root.removeEventListener('change', this.onChange);
+    this.root.removeEventListener('pointerdown', this.onSliderPointerDown);
+    this.reset();
+  }
+
+  // -------------------------------------------------------------------------
+  // Ops
+  // -------------------------------------------------------------------------
+
+  private create(id: ElementId, kind: ElementKind, props: ElementProps, op: Op): void {
+    if (id === ROOT_ID) throw new RendererError('Element 0 is the root and cannot be created', op);
+    if (this.elements.has(id)) throw new RendererError(`Element ${id} already exists`, op);
+    if (!ALL_KINDS.has(kind)) throw new RendererError(`Unknown element kind ${String(kind)}`, op);
+    const el = createShell(kind);
+    el.className = `sb-${kind}`;
+    el.dataset[ID_ATTR] = String(id);
+    el.dataset[KIND_ATTR] = kind;
+    this.elements.set(id, el);
+    this.nodes.set(id, { id, kind, props: asRecord(props), children: [] });
+    applyProps(el, kind, props, this.assets);
+  }
+
+  private update(id: ElementId, props: ElementProps, op: Op): void {
+    if (id === ROOT_ID) {
+      // Phase 12: the root carries no element props; an update of it is the
+      // app's `.preferredColorScheme`, which the page applies as its theme.
+      const scheme = (props as RootProps).colorScheme;
+      if (scheme === 'light' || scheme === 'dark' || scheme === null) {
+        this.root.dispatchEvent(new CustomEvent('sb:color-scheme', { detail: { colorScheme: scheme } }));
+        return;
+      }
+      throw new RendererError('Element 0 is the root and has no props', op);
+    }
+    const el = this.elements.get(id);
+    if (!el) throw new RendererError(`Cannot update unknown element ${id}`, op);
+    const kind = el.dataset[KIND_ATTR] as ElementKind;
+    const node = this.nodes.get(id);
+    if (node) {
+      node.props = asRecord(props);
+      // Phase 9: the next layout re-measures this subtree and its ancestors;
+      // a screen's title also feeds the next screen's back label.
+      if (node.kind === 'navscreen') {
+        const stackId = this.parents.get(id);
+        const stack = stackId === undefined ? undefined : this.nodes.get(stackId);
+        if (stack) this.engine?.invalidateDown(stack);
+      }
+      this.engine?.invalidate(node);
+    }
+    // Remember how the element looked before, in case the pass is animated.
+    const previous = this.pass.updated.get(el);
+    const before = previous ? previous.before : this.animator.snapshot(el);
+    const oldToken = el.dataset[ANIMATION_TOKEN];
+    // `update` replaces the props entirely, so drop whatever the previous
+    // props produced before applying the new ones. The layout box is kept:
+    // the engine re-lays out at `commit`, and removals recorded later in the
+    // pass measure their old position against intact ancestors.
+    const { left, top, width, height } = el.style;
+    el.removeAttribute('style');
+    if (left) el.style.left = left;
+    if (top) el.style.top = top;
+    if (width) el.style.width = width;
+    if (height) el.style.height = height;
+    for (const key of Object.keys(el.dataset)) {
+      if (key !== ID_ATTR && key !== KIND_ATTR) delete el.dataset[key];
+    }
+    ANIMATIONS.delete(el);
+    setTransition(el, undefined);
+    if (kind === 'text') el.textContent = '';
+    applyProps(el, kind, props, this.assets);
+    const newToken = el.dataset[ANIMATION_TOKEN];
+    const tokenChanged = (previous?.tokenChanged ?? false) || (newToken !== undefined && newToken !== oldToken);
+    const record: UpdatedRecord = { el, before, tokenChanged };
+    const animation = ANIMATIONS.get(el);
+    if (animation) record.animation = animation;
+    this.pass.updated.set(el, record);
+    this.dirty.add(id);
+    if (kind === 'navscreen') {
+      const stack = el.parentElement?.closest<HTMLElement>('.sb-navstack');
+      if (stack) refreshNavStack(stack);
+    }
+    if (kind === 'sheet' && el.parentElement) refreshSheets(el.parentElement);
+    if (kind === 'tabview') refreshTabBar(el);
+    if (kind === 'tab') {
+      const tabview = tabViewOf(el);
+      if (tabview) refreshTabBar(tabview);
+    }
+    // The popover shows what its control had when it opened; drop it when
+    // the control (or, for a `menu`, anything inside it) changes.
+    if (this.menu && (this.menu.anchorId === id || this.menu.anchor.contains(el))) this.closeMenu();
+  }
+
+  private insert(parentId: ElementId, id: ElementId, index: number, op: Op): void {
+    if (id === ROOT_ID) throw new RendererError('Element 0 is the root and cannot be inserted', op);
+    const parent = this.elements.get(parentId);
+    if (!parent) throw new RendererError(`Cannot insert into unknown parent ${parentId}`, op);
+    const el = this.elements.get(id);
+    if (!el) throw new RendererError(`Cannot insert unknown element ${id}`, op);
+    if (el === parent || el.contains(parent)) {
+      throw new RendererError(`Inserting ${id} into ${parentId} would create a cycle`, op);
+    }
+    if (!Number.isInteger(index) || index < 0) {
+      throw new RendererError(`Invalid child index ${index}`, op);
+    }
+    const container = slotOf(parent);
+    // Moves: `index` is the element's position in the parent's child list
+    // *after* the op is applied. Detaching first makes the index arithmetic
+    // identical for fresh inserts and for moves within the same parent.
+    const previousParent = el.parentElement;
+    const wasAttached = el.isConnected;
+    el.remove();
+    const reference = container.children[index] ?? null;
+    container.insertBefore(el, reference);
+    if (!wasAttached) this.pass.inserted.add(el);
+    // Mirror the move in the layout tree.
+    const node = this.nodes.get(id);
+    const parentNode = this.nodes.get(parentId);
+    if (node && parentNode) {
+      const oldParentId = this.parents.get(id);
+      const oldParent = oldParentId !== undefined ? this.nodes.get(oldParentId) : undefined;
+      if (oldParent) {
+        const at = oldParent.children.indexOf(node);
+        if (at >= 0) oldParent.children.splice(at, 1);
+        this.engine?.invalidateUp(oldParent);
+      }
+      parentNode.children.splice(Math.min(index, parentNode.children.length), 0, node);
+      this.parents.set(id, parentId);
+      // Phase 9: the subtree's context may differ under its new parent (or
+      // position); the parents on both sides may change size.
+      this.engine?.invalidateUp(parentNode);
+      this.engine?.invalidateDown(node);
+    }
+    if (el.classList.contains('sb-navscreen') && parent.classList.contains('sb-navstack')) {
+      if (container.children.length > 1 && previousParent !== container) animatePush(el);
+      refreshNavStack(parent);
+    }
+    if (previousParent) {
+      const oldStack = previousParent.closest<HTMLElement>('.sb-navstack');
+      if (oldStack && oldStack !== parent) refreshNavStack(oldStack);
+      if (previousParent !== container && previousParent.querySelector(':scope > .sb-sheet') === null) {
+        refreshSheets(previousParent);
+      }
+    }
+    if (el.classList.contains('sb-sheet')) {
+      if (!wasAttached) animateSheetIn(el);
+      refreshSheets(container);
+    }
+    // Phase 8: an alert fades in (and scales from 1.1) on its own.
+    if (el.classList.contains('sb-alert') && !wasAttached) animateAlertIn(el);
+    if (el.classList.contains('sb-tab')) {
+      if (parent.classList.contains('sb-tabview')) refreshTabBar(parent);
+      const oldTabView = previousParent && previousParent !== container ? tabViewOf(previousParent) : null;
+      if (oldTabView && oldTabView !== parent) refreshTabBar(oldTabView);
+    }
+  }
+
+  private remove(id: ElementId, op: Op): void {
+    if (id === ROOT_ID) throw new RendererError('Element 0 is the root and cannot be removed', op);
+    const el = this.elements.get(id);
+    if (!el) throw new RendererError(`Cannot remove unknown element ${id}`, op);
+    const parent = el.parentElement;
+    const stack = parent?.classList.contains('sb-navstack-screens')
+      ? parent.parentElement
+      : null;
+    if (stack && el.classList.contains('sb-navscreen') && el === parent?.lastElementChild && el.previousElementSibling) {
+      // Phase 8: after a swipe back the clone starts where the drag left the
+      // screen (`--sb-nav-from`), and the screen below is handed back to the
+      // stylesheet so it finishes its slide to 0 as the new top screen.
+      this.interaction.screenRemoved(el);
+      animatePop(stack, el);
+    }
+    const isSheet = el.classList.contains('sb-sheet');
+    if (isSheet && parent) animateSheetOut(parent, el);
+    // Phase 8: a dismissed alert leaves a fading ghost, like a sheet.
+    const isAlert = el.classList.contains('sb-alert');
+    if (isAlert && parent) animateAlertOut(parent, el);
+    const tabview = el.classList.contains('sb-tab') ? tabViewOf(el) : null;
+    if (this.menu && (el === this.menu.anchor || el.contains(this.menu.anchor) || this.menu.anchor.contains(el))) {
+      this.closeMenu();
+    }
+    if (parent && !isSheet && !isAlert) {
+      // Keep what the Animator needs for an exit transition; it decides at
+      // `commit` whether the pass is animated.
+      const ancestors: HTMLElement[] = [];
+      for (let a = parent; a && a !== this.root; a = a.parentElement!) ancestors.push(a);
+      this.pass.removed.push({ el, ancestors, rect: this.animator.rectOf(el), transition: transitionOf(el) });
+    }
+    this.pass.inserted.delete(el);
+    this.pass.updated.delete(el);
+    el.remove();
+    // Phase 9: the layout pass drops the subtree's output; the parent re-measures.
+    const removedNode = this.nodes.get(id);
+    if (removedNode) {
+      const parentId = this.parents.get(id);
+      const parentNode = parentId === undefined ? undefined : this.nodes.get(parentId);
+      if (parentNode) this.engine?.invalidateUp(parentNode);
+      this.engine?.remove(removedNode);
+    }
+    this.forget(id);
+    for (const descendant of el.querySelectorAll<HTMLElement>('[data-sb-id]')) {
+      this.forget(Number(descendant.dataset[ID_ATTR]));
+    }
+    if (stack) refreshNavStack(stack);
+    if (isSheet && parent) refreshSheets(parent);
+    if (tabview) refreshTabBar(tabview);
+  }
+
+  /** Forget an element in every map; detaches its node from the tree. */
+  private forget(id: ElementId): void {
+    this.elements.delete(id);
+    this.boxes.delete(id);
+    this.dirty.delete(id);
+    this.reportedGeometry.delete(id);
+    this.layoutReporter.forget(id);
+    const node = this.nodes.get(id);
+    const parentId = this.parents.get(id);
+    const parentNode = parentId !== undefined ? this.nodes.get(parentId) : undefined;
+    if (node && parentNode) {
+      const at = parentNode.children.indexOf(node);
+      if (at >= 0) parentNode.children.splice(at, 1);
+    }
+    this.nodes.delete(id);
+    this.parents.delete(id);
+  }
+}
+
+interface OpenMenu {
+  el: HTMLElement;
+  /** The control that opened it (a `menu` picker or a `menu` element). */
+  anchor: HTMLElement;
+  anchorId: ElementId;
+}
+
+/** One row of a popover menu. */
+type MenuRow =
+  | { kind: 'tap'; id: ElementId; title: string; symbol: string | null; destructive: boolean; disabled: boolean }
+  | { kind: 'select'; id: ElementId; index: number; title: string; checked: boolean }
+  | { kind: 'caption'; text: string }
+  | { kind: 'text'; text: string }
+  | { kind: 'separator' };
+
+// `textOf`, `symbolOf` and `unwrapStyledNode` live in src/nodeQueries.ts
+// (Phase 8 shares them with the swipe actions).
+
+/** Whether a `styled` wrapper in the chain down to the element disables it. */
+function disabledOf(node: LayoutNode): boolean {
+  let current: LayoutNode | undefined = node;
+  while (current && current.kind === 'styled') {
+    const style = current.props['style'];
+    if (typeof style === 'object' && style !== null && (style as Record<string, unknown>)['disabled'] === true) return true;
+    current = current.children.length === 1 ? current.children[0] : undefined;
+  }
+  return false;
+}
+
+/**
+ * Turn a `menu`'s items into popover rows. A picker's options form their
+ * own group, separated from neighbouring rows like iOS does; explicit
+ * `divider`s are separators too (never doubled).
+ */
+function collectMenuRows(items: readonly LayoutNode[], rows: MenuRow[] = []): MenuRow[] {
+  let pendingSeparator = false;
+  const separate = (): void => {
+    if (rows.length > 0 && rows[rows.length - 1]!.kind !== 'separator') rows.push({ kind: 'separator' });
+  };
+  for (const item of items) {
+    const base = unwrapStyledNode(item);
+    if (pendingSeparator && base.kind !== 'divider') {
+      separate();
+      pendingSeparator = false;
+    }
+    switch (base.kind) {
+      case 'button':
+      case 'navlink':
+        rows.push({
+          kind: 'tap',
+          id: base.id,
+          title: textOf(base),
+          symbol: symbolOf(base),
+          destructive: base.props['role'] === 'destructive',
+          disabled: disabledOf(item),
+        });
+        break;
+      case 'picker': {
+        const raw = base.props['options'];
+        const options = Array.isArray(raw) ? raw.map(String) : [];
+        const selected = clampIndex(base.props['selected'], options.length);
+        separate();
+        options.forEach((title, index) => rows.push({ kind: 'select', id: base.id, index, title, checked: index === selected }));
+        pendingSeparator = true;
+        break;
+      }
+      case 'divider':
+        separate();
+        break;
+      case 'section': {
+        const header = base.props['header'];
+        if (typeof header === 'string' && header.length > 0) rows.push({ kind: 'caption', text: header });
+        collectMenuRows(base.children, rows);
+        break;
+      }
+      case 'text':
+        rows.push({ kind: 'text', text: textOf(base) });
+        break;
+      case 'menu': {
+        // A nested menu: its label as a caption, its items flattened.
+        const [label, ...nested] = base.children;
+        if (label) rows.push({ kind: 'caption', text: textOf(label) });
+        collectMenuRows(nested, rows);
+        break;
+      }
+      default:
+        // Groups, stacks and the like: their children in order.
+        collectMenuRows(base.children, rows);
+        break;
+    }
+  }
+  return rows;
+}
+
+/** Build the DOM for one popover row (the renderer's click handler reads the data attributes). */
+function menuRowElement(row: MenuRow): HTMLElement {
+  switch (row.kind) {
+    case 'select': {
+      const item = document.createElement('button');
+      item.type = 'button';
+      item.className = 'sb-picker-menu-item';
+      item.setAttribute('role', 'menuitemradio');
+      item.setAttribute('aria-checked', String(row.checked));
+      item.dataset['sbAction'] = 'select';
+      item.dataset['sbTarget'] = String(row.id);
+      item.dataset['sbIndex'] = String(row.index);
+      const check = span('sb-picker-menu-check');
+      const glyph = renderSymbol('checkmark');
+      if (glyph) check.append(glyph);
+      const title = span('sb-picker-menu-title');
+      title.textContent = row.title;
+      item.append(check, title);
+      return item;
+    }
+    case 'tap': {
+      const item = document.createElement('button');
+      item.type = 'button';
+      item.className = 'sb-picker-menu-item';
+      item.setAttribute('role', 'menuitem');
+      item.dataset['sbAction'] = 'tap';
+      item.dataset['sbTarget'] = String(row.id);
+      if (row.destructive) item.dataset['sbRole'] = 'destructive';
+      if (row.disabled) item.disabled = true;
+      const title = span('sb-picker-menu-title');
+      title.textContent = row.title;
+      item.append(title);
+      if (row.symbol) {
+        const symbol = span('sb-picker-menu-symbol');
+        const glyph = renderSymbol(row.symbol);
+        if (glyph) symbol.append(glyph);
+        symbol.dataset['sbSymbol'] = row.symbol;
+        item.append(symbol);
+      }
+      return item;
+    }
+    case 'caption': {
+      const caption = div('sb-picker-menu-caption');
+      caption.textContent = row.text;
+      return caption;
+    }
+    case 'text': {
+      const text = div('sb-picker-menu-static');
+      text.setAttribute('aria-disabled', 'true');
+      text.textContent = row.text;
+      return text;
+    }
+    case 'separator': {
+      const separator = div('sb-picker-menu-separator');
+      separator.setAttribute('role', 'separator');
+      return separator;
+    }
+  }
+}
+
+/** Props as the engine reads them (untrusted JSON, so a plain record). */
+function asRecord(props: unknown): Record<string, unknown> {
+  return typeof props === 'object' && props !== null ? (props as Record<string, unknown>) : {};
+}
+
+/** Safe-area insets from the page's device tokens (`--device-safe-top/bottom`). */
+function readSafeArea(root: HTMLElement): LayoutEnvironment['safeArea'] {
+  const cs = getComputedStyle(root);
+  const read = (name: string, fallback: number): number => {
+    const value = parseFloat(cs.getPropertyValue(name));
+    return Number.isFinite(value) ? value : fallback;
+  };
+  return {
+    top: read('--device-safe-top', DEFAULT_SAFE_AREA.top),
+    leading: 0,
+    bottom: read('--device-safe-bottom', DEFAULT_SAFE_AREA.bottom),
+    trailing: 0,
+  };
+}
+
+/** Convenience factory mirroring the function-style API in the brief. */
+export function createRenderer(root: HTMLElement, onEvent: EventCallback): Renderer {
+  return new Renderer(root, onEvent);
+}
+
+// ---------------------------------------------------------------------------
+// Element shells and slots
+// ---------------------------------------------------------------------------
+
+/** Slot elements of compound kinds, registered by `createShell`. */
+const SLOTS = new WeakMap<HTMLElement, HTMLElement>();
+
+/** The DOM node that receives an element's protocol children. */
+export function slotOf(el: HTMLElement): HTMLElement {
+  return SLOTS.get(el) ?? el;
+}
+
+function div(className: string): HTMLDivElement {
+  const el = document.createElement('div');
+  el.className = className;
+  return el;
+}
+
+/** Create the element and any chrome it owns; props are applied separately. */
+function createShell(kind: ElementKind): HTMLElement {
+  switch (kind) {
+    case 'button': {
+      const el = document.createElement('button');
+      el.type = 'button';
+      return el;
+    }
+    case 'text':
+      return document.createElement('span');
+    case 'textfield': {
+      const el = document.createElement('input');
+      el.autocomplete = 'off';
+      el.spellcheck = false;
+      return el;
+    }
+    case 'image': {
+      const el = document.createElement('span');
+      el.setAttribute('role', 'img');
+      return el;
+    }
+    case 'divider': {
+      const el = document.createElement('div');
+      el.setAttribute('role', 'separator');
+      return el;
+    }
+    case 'navstack': {
+      const el = document.createElement('div');
+      const slot = div('sb-slot sb-navstack-screens');
+      el.append(slot);
+      SLOTS.set(el, slot);
+      return el;
+    }
+    case 'list': {
+      // The inner box is sized to the content so the list scrolls it.
+      const el = document.createElement('div');
+      const slot = div('sb-slot sb-list-content');
+      el.append(slot);
+      SLOTS.set(el, slot);
+      return el;
+    }
+    case 'scrollview': {
+      const el = document.createElement('div');
+      const slot = div('sb-slot sb-scroll-content');
+      el.append(slot);
+      SLOTS.set(el, slot);
+      return el;
+    }
+    case 'navscreen': {
+      const el = document.createElement('div');
+      const bar = div('sb-navbar');
+      const back = document.createElement('button');
+      back.type = 'button';
+      back.className = 'sb-navbar-back';
+      const chevron = renderSymbol('chevron.left');
+      if (chevron) back.append(chevron);
+      back.append(span('sb-navbar-back-label'));
+      const inlineTitle = span('sb-navbar-title');
+      bar.append(back, inlineTitle, div('sb-navbar-trailing'));
+      const body = div('sb-navscreen-body');
+      const slot = div('sb-slot sb-navscreen-content');
+      body.append(div('sb-navbar-large-title'), slot);
+      // Phase 8: a 24px strip along the leading edge of a pushed screen
+      // that, on touch devices, keeps the browser from scrolling so a swipe
+      // back can start there (styles.css; the controller forwards plain taps).
+      const edge = div('sb-navscreen-edge');
+      edge.setAttribute('aria-hidden', 'true');
+      el.append(bar, body, edge);
+      SLOTS.set(el, slot);
+      return el;
+    }
+    case 'section': {
+      const el = document.createElement('div');
+      const slot = div('sb-slot sb-section-rows');
+      el.append(div('sb-section-header'), slot, div('sb-section-footer'));
+      SLOTS.set(el, slot);
+      return el;
+    }
+    case 'toggle': {
+      const el = document.createElement('div');
+      const label = div('sb-slot sb-toggle-label');
+      const sw = document.createElement('button');
+      sw.type = 'button';
+      sw.className = 'sb-switch';
+      sw.setAttribute('role', 'switch');
+      sw.setAttribute('aria-checked', 'false');
+      sw.append(span('sb-switch-knob'));
+      el.append(label, sw);
+      SLOTS.set(el, label);
+      return el;
+    }
+    case 'navlink': {
+      const el = document.createElement('div');
+      el.setAttribute('role', 'button');
+      el.tabIndex = 0;
+      const chevron = renderSymbol('chevron.right');
+      const slot = div('sb-slot sb-navlink-label');
+      el.append(slot);
+      SLOTS.set(el, slot);
+      if (chevron) {
+        chevron.classList.add('sb-navlink-chevron');
+        el.append(chevron);
+      }
+      return el;
+    }
+    case 'sheet': {
+      // A full-screen layer: a scrim over the presenting content and the
+      // card (grabber + content slot) sliding up from the bottom.
+      const el = document.createElement('div');
+      el.setAttribute('role', 'dialog');
+      el.setAttribute('aria-modal', 'true');
+      const scrim = div('sb-sheet-scrim');
+      const card = div('sb-sheet-card');
+      const grabber = div('sb-sheet-grabber');
+      grabber.setAttribute('aria-hidden', 'true');
+      const slot = div('sb-slot sb-sheet-content');
+      card.append(grabber, slot);
+      el.append(scrim, card);
+      SLOTS.set(el, slot);
+      return el;
+    }
+    case 'color':
+    case 'shape': {
+      const el = document.createElement('div');
+      el.setAttribute('aria-hidden', 'true');
+      return el;
+    }
+    case 'tabview': {
+      // The tabs go into the content slot; the bar is chrome drawn on top.
+      const el = document.createElement('div');
+      const slot = div('sb-slot sb-tabview-content');
+      const bar = div('sb-tabbar');
+      bar.setAttribute('role', 'tablist');
+      el.append(slot, bar);
+      SLOTS.set(el, slot);
+      return el;
+    }
+    case 'tab': {
+      const el = document.createElement('div');
+      el.setAttribute('role', 'tabpanel');
+      return el;
+    }
+    case 'picker':
+      // Segments or the label/value row are built from the props.
+      return document.createElement('div');
+    case 'gauge': {
+      // The labels are protocol children (in the slot); the track and its
+      // fill are chrome positioned from the engine's `track` / `fill` rects.
+      const el = document.createElement('div');
+      el.setAttribute('role', 'meter');
+      el.setAttribute('aria-valuemin', '0');
+      el.setAttribute('aria-valuemax', '1');
+      const slot = div('sb-slot sb-gauge-labels');
+      const track = div('sb-gauge-track');
+      track.setAttribute('aria-hidden', 'true');
+      const fill = div('sb-gauge-fill');
+      fill.setAttribute('aria-hidden', 'true');
+      el.append(slot, track, fill);
+      SLOTS.set(el, slot);
+      return el;
+    }
+    case 'menu': {
+      // Phase 6: the label (first child) is the visible control; the other
+      // children are the items, hidden inline and listed in the popover.
+      const el = document.createElement('div');
+      el.setAttribute('role', 'button');
+      el.setAttribute('aria-haspopup', 'menu');
+      el.setAttribute('aria-expanded', 'false');
+      el.tabIndex = 0;
+      return el;
+    }
+    case 'toolbar': {
+      const el = document.createElement('div');
+      el.setAttribute('role', 'toolbar');
+      return el;
+    }
+    case 'chart': {
+      // Phase 7: the marks, grid, ticks, text labels and legend are chrome
+      // (src/chartDom.ts, drawn from the engine's `plot` and label rects);
+      // the `chartitem` children live in the slot above it so annotations
+      // draw over the marks.
+      const el = document.createElement('div');
+      el.setAttribute('role', 'img');
+      const chrome = div('sb-chart-chrome');
+      chrome.setAttribute('aria-hidden', 'true');
+      const slot = div('sb-slot sb-chart-items');
+      el.append(chrome, slot);
+      SLOTS.set(el, slot);
+      return el;
+    }
+    case 'chartitem':
+      return document.createElement('div');
+    case 'searchfield': {
+      // Phase 6: a rounded field with a magnifier; the input sends `text` events.
+      const el = document.createElement('div');
+      el.setAttribute('role', 'search');
+      const glyph = renderSymbol('magnifyingglass');
+      if (glyph) el.append(glyph);
+      const input = document.createElement('input');
+      input.type = 'text';
+      input.className = 'sb-searchfield-input';
+      input.autocomplete = 'off';
+      input.spellcheck = false;
+      input.setAttribute('aria-label', 'Search');
+      el.append(input);
+      return el;
+    }
+    case 'tapgesture':
+      return document.createElement('div');
+    case 'navsplit': {
+      // Phase 7: the two columns go into the slot; the separator is chrome
+      // positioned from the engine's `separator` rect.
+      const el = document.createElement('div');
+      const slot = div('sb-slot sb-navsplit-columns');
+      const separator = div('sb-navsplit-separator');
+      separator.setAttribute('aria-hidden', 'true');
+      el.append(slot, separator);
+      SLOTS.set(el, slot);
+      return el;
+    }
+    case 'viewthatfits':
+      return document.createElement('div');
+    // Phase 8: gestures, rows, navigation
+    case 'gesture':
+    case 'contextmenu':
+      return document.createElement('div');
+    case 'swipeactions':
+    case 'listrow': {
+      // The protocol children go into a content slot that paints the row
+      // background and slides aside; the action buttons the controller
+      // builds (src/interaction.ts) sit behind it. A `listrow` also owns
+      // the edit-mode control (selection circle / minus) at `chrome.editControl`.
+      const el = document.createElement('div');
+      const slot = div('sb-slot sb-swipe-content');
+      el.append(slot);
+      SLOTS.set(el, slot);
+      if (kind === 'listrow') {
+        const control = document.createElement('button');
+        control.type = 'button';
+        control.className = 'sb-listrow-control';
+        control.hidden = true;
+        control.tabIndex = -1;
+        const circle = span('sb-listrow-circle');
+        const check = renderSymbol('checkmark');
+        if (check) {
+          check.classList.add('sb-listrow-check');
+          circle.append(check);
+        }
+        const minus = renderSymbol('minus');
+        if (minus) {
+          minus.classList.add('sb-listrow-minus');
+          circle.append(minus);
+        }
+        control.append(circle);
+        el.append(control);
+      }
+      return el;
+    }
+    case 'alert': {
+      // Phase 8: a full-screen layer: the scrim, then a layer (scaled by the
+      // appear animation about the card's center) holding the card(s), the
+      // title and message, the button slot and the renderer-drawn OK. The
+      // engine positions all of them in screen coordinates.
+      const el = document.createElement('div');
+      el.setAttribute('role', 'alertdialog');
+      el.setAttribute('aria-modal', 'true');
+      const scrim = div('sb-alert-scrim');
+      const layer = div('sb-alert-layer');
+      const card = div('sb-alert-card');
+      card.setAttribute('aria-hidden', 'true');
+      const cancelCard = div('sb-alert-cancel-card');
+      cancelCard.setAttribute('aria-hidden', 'true');
+      const slot = div('sb-slot sb-alert-buttons');
+      const ok = document.createElement('button');
+      ok.type = 'button';
+      ok.className = 'sb-alert-ok';
+      ok.textContent = 'OK';
+      layer.append(card, cancelCard, div('sb-alert-title'), div('sb-alert-message'), slot, ok);
+      el.append(scrim, layer);
+      SLOTS.set(el, slot);
+      return el;
+    }
+    case 'stepper': {
+      // Phase 8: the label (slot) leads; the −/+ control is chrome at the engine's `control` rect.
+      const el = document.createElement('div');
+      const slot = div('sb-slot sb-stepper-label');
+      const control = div('sb-stepper-control');
+      const half = (step: number, symbol: string, label: string): HTMLButtonElement => {
+        const button = document.createElement('button');
+        button.type = 'button';
+        button.className = 'sb-stepper-button';
+        button.dataset['sbStep'] = String(step);
+        button.setAttribute('aria-label', label);
+        const glyph = renderSymbol(symbol);
+        if (glyph) button.append(glyph);
+        else button.textContent = step < 0 ? '−' : '+';
+        return button;
+      };
+      control.append(half(-1, 'minus', 'Decrement'), half(1, 'plus', 'Increment'));
+      el.append(slot, control);
+      SLOTS.set(el, slot);
+      return el;
+    }
+    case 'slider': {
+      // Phase 8: the labels are protocol children; track, fill and thumb are chrome.
+      const el = document.createElement('div');
+      el.setAttribute('role', 'slider');
+      const slot = div('sb-slot sb-slider-labels');
+      const track = div('sb-slider-track');
+      const fill = div('sb-slider-fill');
+      const thumb = div('sb-slider-thumb');
+      for (const part of [track, fill, thumb]) part.setAttribute('aria-hidden', 'true');
+      el.append(slot, track, fill, thumb);
+      SLOTS.set(el, slot);
+      return el;
+    }
+    case 'datepicker': {
+      // Phase 8: the label (slot) leads; a date and a time capsule (text plus
+      // an invisible native input over it) are chrome at `date` / `time`.
+      const el = document.createElement('div');
+      const slot = div('sb-slot sb-datepicker-label');
+      const capsule = (type: 'date' | 'time'): HTMLElement => {
+        const box = div(`sb-datepicker-capsule sb-datepicker-${type}`);
+        const text = span('sb-datepicker-text');
+        const input = document.createElement('input');
+        input.type = type;
+        input.className = 'sb-datepicker-input';
+        input.setAttribute('aria-label', type === 'date' ? 'Date' : 'Time');
+        box.append(text, input);
+        return box;
+      };
+      el.append(slot, capsule('date'), capsule('time'));
+      SLOTS.set(el, slot);
+      return el;
+    }
+    case 'texteditor': {
+      const el = document.createElement('textarea');
+      el.autocomplete = 'off';
+      el.spellcheck = false;
+      return el;
+    }
+    default:
+      return document.createElement('div');
+  }
+}
+
+function span(className: string): HTMLSpanElement {
+  const el = document.createElement('span');
+  el.className = className;
+  return el;
+}
+
+// ---------------------------------------------------------------------------
+// Navigation
+// ---------------------------------------------------------------------------
+
+/**
+ * Recompute per-screen state for a `navstack`: only the last screen is
+ * interactive, and every screen at depth > 0 shows a back button labelled
+ * with the previous screen's title.
+ */
+function refreshNavStack(stack: HTMLElement): void {
+  const screens = Array.from(slotOf(stack).children) as HTMLElement[];
+  screens.forEach((screen, i) => {
+    const isTop = i === screens.length - 1;
+    screen.toggleAttribute('inert', !isTop);
+    screen.setAttribute('aria-hidden', String(!isTop));
+    screen.dataset['sbNavPosition'] = isTop ? 'top' : 'below';
+    const previous = screens[i - 1];
+    const back = screen.querySelector<HTMLElement>(':scope > .sb-navbar > .sb-navbar-back');
+    const label = back?.querySelector<HTMLElement>('.sb-navbar-back-label');
+    const depth = Number(screen.dataset['sbDepth'] ?? '0');
+    if (back && label) {
+      const show = depth > 0;
+      back.hidden = !show;
+      // The layout engine picks the label (previous title, "Back" or none)
+      // so it never collides with the title; fall back until it has run.
+      label.textContent = label.dataset['sbLayoutLabel'] ?? (previous?.dataset['sbTitle'] || 'Back');
+      back.dataset['sbTarget'] = screen.dataset[ID_ATTR] ?? '';
+    }
+  });
+}
+
+/**
+ * Run `done` once the CSS animation on `target` itself has ended (not one
+ * bubbling up from a descendant). A late first frame (heavy layout) can push
+ * the end past `expectedMs`, so the fallback waits for the running animation
+ * objects instead of cutting the animation short.
+ */
+function afterAnimation(target: HTMLElement, expectedMs: number, done: () => void): void {
+  let finished = false;
+  const finish = (): void => {
+    if (finished) return;
+    finished = true;
+    target.removeEventListener('animationend', onEnd);
+    target.removeEventListener('animationcancel', onEnd);
+    done();
+  };
+  const onEnd = (event: Event): void => {
+    if (event.target === target) finish();
+  };
+  target.addEventListener('animationend', onEnd);
+  target.addEventListener('animationcancel', onEnd);
+  window.setTimeout(() => {
+    const running = target.getAnimations().filter((a) => a.playState === 'running');
+    if (running.length === 0) {
+      finish();
+      return;
+    }
+    Promise.allSettled(running.map((a) => a.finished)).then(finish, finish);
+    window.setTimeout(finish, expectedMs * 3);
+  }, expectedMs + 50);
+}
+
+function animatePush(screen: HTMLElement): void {
+  screen.classList.remove('sb-navscreen--push');
+  // Force a style flush so re-adding the class restarts the animation.
+  void screen.offsetWidth;
+  screen.classList.add('sb-navscreen--push');
+  afterAnimation(screen, NAV_TRANSITION_MS, () => screen.classList.remove('sb-navscreen--push'));
+}
+
+/**
+ * The protocol removes a popped screen immediately; to animate it out a
+ * visual clone (stripped of element ids so it is invisible to the renderer)
+ * slides away on top of the stack and is dropped afterwards.
+ */
+function animatePop(stack: HTMLElement, screen: HTMLElement): void {
+  const clone = ghostClone(screen);
+  clone.removeAttribute('inert');
+  clone.setAttribute('aria-hidden', 'true');
+  clone.classList.add('sb-navscreen--pop');
+  stack.append(clone);
+  afterAnimation(clone, NAV_TRANSITION_MS, () => clone.remove());
+}
+
+// ---------------------------------------------------------------------------
+// Tab views (Phase 4)
+// ---------------------------------------------------------------------------
+
+/** The `tabview` element whose content slot holds `el` (a tab or the slot itself), or null. */
+function tabViewOf(el: HTMLElement): HTMLElement | null {
+  const slot = el.classList.contains('sb-tabview-content') ? el : el.parentElement;
+  if (!slot?.classList.contains('sb-tabview-content')) return null;
+  const tabview = slot.parentElement;
+  return tabview?.classList.contains('sb-tabview') ? tabview : null;
+}
+
+function clampIndex(value: unknown, count: number): number {
+  const n = typeof value === 'number' && Number.isFinite(value) ? Math.floor(value) : 0;
+  return count === 0 ? 0 : Math.min(count - 1, Math.max(0, n));
+}
+
+/**
+ * Rebuild the tab bar items from the `tab` children (title + symbol) and mark
+ * the selected tab: only it is visible and interactive. The layout engine
+ * confirms the hidden set at `commit`; this keeps the DOM right in between.
+ */
+function refreshTabBar(tabview: HTMLElement): void {
+  const bar = tabview.querySelector<HTMLElement>(':scope > .sb-tabbar');
+  if (!bar) return;
+  const tabs = Array.from(slotOf(tabview).children).filter((c) => c.classList.contains('sb-tab')) as HTMLElement[];
+  const selected = clampIndex(Number(tabview.dataset['sbSelected'] ?? 0), tabs.length);
+  while (bar.children.length > tabs.length) bar.lastElementChild?.remove();
+  while (bar.children.length < tabs.length) {
+    const item = document.createElement('button');
+    item.type = 'button';
+    item.className = 'sb-tabbar-item';
+    item.setAttribute('role', 'tab');
+    item.append(span('sb-tabbar-icon'), span('sb-tabbar-title'));
+    bar.append(item);
+  }
+  tabs.forEach((tab, i) => {
+    const item = bar.children[i] as HTMLElement;
+    const title = tab.dataset['sbTitle'] ?? '';
+    const symbol = tab.dataset['sbSymbol'] ?? '';
+    const isSelected = i === selected;
+    item.dataset['sbIndex'] = String(i);
+    item.setAttribute('aria-selected', String(isSelected));
+    item.setAttribute('aria-label', title);
+    item.toggleAttribute('data-sb-selected', isSelected);
+    const icon = item.querySelector<HTMLElement>(':scope > .sb-tabbar-icon');
+    if (icon && icon.dataset['sbSymbol'] !== symbol) {
+      icon.dataset['sbSymbol'] = symbol;
+      const svg = symbol ? renderSymbol(symbol) : null;
+      if (svg) icon.replaceChildren(svg);
+      else icon.replaceChildren();
+      icon.toggleAttribute('data-sb-missing', Boolean(symbol) && !svg);
+      icon.hidden = !symbol;
+    }
+    const label = item.querySelector<HTMLElement>(':scope > .sb-tabbar-title');
+    if (label && label.textContent !== title) label.textContent = title;
+    setTabHidden(tab, !isSelected);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Sheets
+// ---------------------------------------------------------------------------
+
+/**
+ * Recompute sheet state under `container` (normally the root): only the last
+ * sheet is interactive, and the container records the top sheet's detent so
+ * styles.css can scale and dim the presenting content behind a `large` one.
+ */
+function refreshSheets(container: HTMLElement): void {
+  // Exit clones of dismissed sheets are not sheets any more.
+  const sheets = Array.from(container.children).filter(
+    (c) => c.classList.contains('sb-sheet') && !c.classList.contains(EXIT_CLONE_CLASS),
+  ) as HTMLElement[];
+  sheets.forEach((sheet, i) => {
+    const isTop = i === sheets.length - 1;
+    sheet.dataset['sbSheetPosition'] = isTop ? 'top' : 'below';
+    sheet.toggleAttribute('inert', !isTop);
+  });
+  const top = sheets[sheets.length - 1];
+  if (top) container.dataset['sbSheet'] = top.dataset['sbDetent'] ?? 'large';
+  else delete container.dataset['sbSheet'];
+}
+
+function animateSheetIn(sheet: HTMLElement): void {
+  sheet.classList.remove('sb-sheet--in');
+  void sheet.offsetWidth;
+  sheet.classList.add('sb-sheet--in');
+  const card = sheet.querySelector<HTMLElement>(':scope > .sb-sheet-card') ?? sheet;
+  afterAnimation(card, SHEET_TRANSITION_MS, () => sheet.classList.remove('sb-sheet--in'));
+}
+
+/**
+ * Like `animatePop`: the protocol removes a dismissed sheet at once, so a
+ * clone (without element ids) slides down and fades its scrim, then goes.
+ */
+function animateSheetOut(container: HTMLElement, sheet: HTMLElement): void {
+  const clone = ghostClone(sheet);
+  clone.setAttribute('aria-hidden', 'true');
+  clone.toggleAttribute('inert', true);
+  clone.classList.add('sb-sheet--out', EXIT_CLONE_CLASS);
+  const card = clone.querySelector<HTMLElement>(':scope > .sb-sheet-card');
+  if (card) {
+    // The slide starts where a drag left the card (`--sb-sheet-drag`).
+    card.style.transition = '';
+    card.style.transform = '';
+  }
+  container.append(clone);
+  afterAnimation(card ?? clone, SHEET_TRANSITION_MS, () => clone.remove());
+}
+
+function applySheet(el: HTMLElement, props: SheetProps): void {
+  const detents = Array.isArray(props.detents) && props.detents.length ? props.detents : ['large'];
+  // Phase 8: `full` is `.fullScreenCover` (no radius, grabber or drag; the presenting tree keeps its scale).
+  const first = detents[0] === 'medium' ? 'medium' : detents[0] === 'full' ? 'full' : 'large';
+  el.dataset['sbDetent'] = first;
+  el.dataset['sbDetents'] = detents.join(' ');
+}
+
+// Phase 8: alerts appear with a 0.25s fade (the alert card scales from 1.1,
+// see styles.css) and leave with a fade played by a ghost clone, like sheets.
+function animateAlertIn(alert: HTMLElement): void {
+  alert.classList.remove('sb-alert--in');
+  void alert.offsetWidth;
+  alert.classList.add('sb-alert--in');
+  const layer = alert.querySelector<HTMLElement>(':scope > .sb-alert-layer') ?? alert;
+  afterAnimation(layer, ALERT_TRANSITION_MS, () => alert.classList.remove('sb-alert--in'));
+}
+
+function animateAlertOut(container: HTMLElement, alert: HTMLElement): void {
+  const clone = ghostClone(alert);
+  clone.setAttribute('aria-hidden', 'true');
+  clone.toggleAttribute('inert', true);
+  clone.classList.remove('sb-alert--in');
+  clone.classList.add('sb-alert--out', EXIT_CLONE_CLASS);
+  container.append(clone);
+  afterAnimation(clone, ALERT_TRANSITION_MS, () => clone.remove());
+}
+
+interface SliderDrag {
+  slider: HTMLElement;
+  track: HTMLElement;
+  id: ElementId;
+  pointerId: number;
+  /** The latest snapped value, sent at the next animation frame. */
+  pending: number | null;
+  /** The last value sent, so an unchanged frame sends nothing. */
+  sent: number | null;
+  frame: number | null;
+}
+
+function applyAlert(el: HTMLElement, props: AlertProps): void {
+  el.dataset['sbStyle'] = props.style === 'dialog' ? 'dialog' : 'alert';
+  // The title and message are drawn at layout from the engine's centered lines.
+  el.setAttribute('aria-label', props.title ?? '');
+}
+
+function applyStepper(el: HTMLElement, props: StepperProps): void {
+  const halves = el.querySelectorAll<HTMLElement>(':scope > .sb-stepper-control > .sb-stepper-button');
+  halves[0]?.setAttribute('aria-disabled', String(props.canDecrement === false));
+  halves[1]?.setAttribute('aria-disabled', String(props.canIncrement === false));
+}
+
+function applySlider(el: HTMLElement, props: SliderProps): void {
+  const min = Number.isFinite(props.min) ? props.min : 0;
+  const max = Number.isFinite(props.max) && props.max > min ? props.max : min + 1;
+  const value = Number.isFinite(props.value) ? props.value : min;
+  const step = props.step != null && Number.isFinite(props.step) && props.step > 0 ? props.step : null;
+  el.dataset['sbMin'] = String(min);
+  el.dataset['sbMax'] = String(max);
+  el.dataset['sbStep'] = step === null ? '' : String(step);
+  el.dataset['sbValue'] = String(value);
+  el.setAttribute('aria-valuemin', String(min));
+  el.setAttribute('aria-valuemax', String(max));
+  el.setAttribute('aria-valuenow', String(value));
+}
+
+/**
+ * Move the thumb and fill of a slider to `fraction` (0...1) right away, from
+ * the track's current box; the engine's next layout places them from `value`.
+ */
+function setSliderPosition(slider: HTMLElement, fraction: number): void {
+  const track = slider.querySelector<HTMLElement>(':scope > .sb-slider-track');
+  const fill = slider.querySelector<HTMLElement>(':scope > .sb-slider-fill');
+  const thumb = slider.querySelector<HTMLElement>(':scope > .sb-slider-thumb');
+  if (!track || !fill || !thumb) return;
+  const travel = Math.max(0, track.offsetWidth - SLIDER_THUMB);
+  const center = track.offsetLeft + SLIDER_THUMB / 2 + fraction * travel;
+  thumb.style.left = `${center - SLIDER_THUMB / 2}px`;
+  fill.style.width = `${Math.max(0, center - track.offsetLeft)}px`;
+}
+
+function applyDatePicker(el: HTMLElement, props: DatePickerProps): void {
+  const seconds = Number.isFinite(props.seconds) ? props.seconds : 0;
+  const components = props.components === 'date' || props.components === 'hourAndMinute' ? props.components : 'dateAndTime';
+  el.dataset['sbSeconds'] = String(seconds);
+  el.dataset['sbComponents'] = components;
+  el.dataset['sbMin'] = props.min != null && Number.isFinite(props.min) ? String(props.min) : '';
+  el.dataset['sbMax'] = props.max != null && Number.isFinite(props.max) ? String(props.max) : '';
+  if (props.labelsHidden === true) el.dataset['sbLabelsHidden'] = '';
+  setDatePickerValue(el, seconds);
+}
+
+/**
+ * Show `seconds` in the capsules (US English, UTC) and in the native inputs;
+ * `min` / `max` (from the element's data) bound the date input, and the time
+ * input only when they fall on the shown day.
+ */
+function setDatePickerValue(el: HTMLElement, seconds: number): void {
+  const bound = (key: 'sbMin' | 'sbMax'): number | null => {
+    const text = el.dataset[key];
+    return text ? Number(text) : null;
+  };
+  const min = bound('sbMin');
+  const max = bound('sbMax');
+  for (const type of ['date', 'time'] as const) {
+    const capsule = el.querySelector<HTMLElement>(`:scope > .sb-datepicker-${type}`);
+    if (!capsule) continue;
+    const text = capsule.querySelector<HTMLElement>(':scope > .sb-datepicker-text');
+    const input = capsule.querySelector<HTMLInputElement>(':scope > .sb-datepicker-input');
+    const label = type === 'date' ? formatPickerDate(seconds) : formatPickerTime(seconds);
+    if (text && text.textContent !== label) text.textContent = label;
+    if (!input) continue;
+    const format = type === 'date' ? dateInputValue : timeInputValue;
+    const value = format(seconds);
+    if (input.value !== value) input.value = value;
+    const limit = (b: number | null): string =>
+      b !== null && Number.isFinite(b) && (type === 'date' || sameUTCDay(b, seconds)) ? format(b) : '';
+    input.min = limit(min);
+    input.max = limit(max);
+  }
+}
+
+/** Like `applyTextField`: the caret survives an echo of the text the editor shows. */
+function applyTextEditor(area: HTMLTextAreaElement, props: TextEditorProps): void {
+  const text = props.text ?? '';
+  if (area.value !== text) area.value = text;
+}
+
+// ---------------------------------------------------------------------------
+// Props → DOM
+// ---------------------------------------------------------------------------
+
+function applyProps(el: HTMLElement, kind: ElementKind, props: ElementProps, assets: AssetCatalog): void {
+  switch (kind) {
+    case 'text':
+      applyText(el, props as TextProps);
+      break;
+    case 'vstack':
+      applyVStack(el, props as VStackProps);
+      applyScrollTarget(el, (props as VStackProps).scrollTarget === true);
+      break;
+    case 'hstack':
+      applyHStack(el, props as HStackProps);
+      applyScrollTarget(el, (props as HStackProps).scrollTarget === true);
+      break;
+    case 'spacer':
+      applySpacer(el, props as SpacerProps);
+      break;
+    case 'button':
+      applyButton(el, (props as ButtonProps) ?? {});
+      break;
+    case 'styled':
+      applyStyle(el, (props as StyledProps).style ?? {});
+      break;
+    case 'zstack':
+      applyZStack(el, props as ZStackProps);
+      break;
+    case 'image':
+      applyImage(el, props as ImageProps, assets);
+      break;
+    case 'divider':
+    case 'navstack':
+    case 'geometry':
+    case 'menu':
+    case 'tapgesture':
+    case 'navsplit':
+      // No props.
+      break;
+    case 'navlink':
+      // Phase 7: a selected row (inside a `List(selection:)`) gets a rounded fill.
+      el.toggleAttribute('data-sb-selected', (props as NavLinkProps | undefined)?.selected === true);
+      break;
+    case 'viewthatfits': {
+      const axes = (props as ViewThatFitsProps | undefined)?.axes;
+      el.dataset['sbAxes'] = axes === 'horizontal' || axes === 'vertical' ? axes : 'both';
+      break;
+    }
+    case 'toolbar': {
+      const placement = (props as ToolbarProps).placement;
+      el.dataset['sbPlacement'] =
+        placement === 'leading' || placement === 'principal' || placement === 'bottom' ? placement : 'trailing';
+      break;
+    }
+    case 'searchfield':
+      applySearchField(el, props as SearchFieldProps);
+      break;
+    case 'list': {
+      const list = props as ListProps;
+      el.dataset['sbListStyle'] = list.style ?? 'insetGrouped';
+      // Phase 8: edit mode (the engine shifts `listrow` content) and pull to refresh.
+      el.toggleAttribute('data-sb-editing', list.editing === true);
+      applyRefreshable(el, list.refreshable === true, list.refreshing === true);
+      break;
+    }
+    case 'tabview': {
+      const selected = (props as TabViewProps).selected;
+      el.dataset['sbSelected'] = String(Number.isFinite(selected) ? Math.max(0, Math.floor(selected)) : 0);
+      break;
+    }
+    case 'tab': {
+      const { title, systemImage } = props as TabProps;
+      el.dataset['sbTitle'] = title ?? '';
+      el.dataset['sbSymbol'] = systemImage ?? '';
+      el.setAttribute('aria-label', title ?? '');
+      break;
+    }
+    case 'picker':
+      applyPicker(el, props as PickerProps);
+      break;
+    case 'scrollview': {
+      const scroll = props as ScrollViewProps;
+      el.dataset['sbAxes'] = scroll.axes ?? 'vertical';
+      applyRefreshable(el, scroll.refreshable === true, scroll.refreshing === true);
+      if (scroll.snap === 'viewAligned' || scroll.snap === 'paging') el.dataset['sbSnap'] = scroll.snap;
+      else delete el.dataset['sbSnap'];
+      break;
+    }
+    case 'section':
+      applySection(el, props as SectionProps);
+      break;
+    case 'textfield':
+      applyTextField(el as HTMLInputElement, props as TextFieldProps);
+      break;
+    case 'toggle':
+      setSwitchState(el, Boolean((props as ToggleProps).isOn));
+      break;
+    case 'navscreen':
+      applyNavScreen(el, props as NavScreenProps);
+      break;
+    case 'color':
+      applyColor(el, props as ColorProps);
+      break;
+    case 'shape':
+      applyShape(el, props as ShapeProps);
+      break;
+    case 'sheet':
+      applySheet(el, props as SheetProps);
+      break;
+    case 'layout':
+      // Pure layout: `proposal`, `size` and `frames` are read by the engine.
+      break;
+    case 'grid': {
+      const grid = props as GridProps;
+      el.dataset['sbAlignment'] = grid.alignment ?? 'center';
+      break;
+    }
+    case 'gridrow': {
+      const row = props as GridRowProps;
+      if (row.alignment) el.dataset['sbAlignment'] = row.alignment;
+      break;
+    }
+    case 'lazyvgrid': {
+      const grid = props as LazyVGridProps;
+      el.dataset['sbAlignment'] = grid.alignment ?? 'center';
+      el.dataset['sbColumns'] = String(Array.isArray(grid.columns) ? grid.columns.length : 0);
+      break;
+    }
+    case 'gauge':
+      applyGauge(el, props as GaugeProps);
+      break;
+    case 'decorated': {
+      const decorated = props as DecoratedProps;
+      el.dataset['sbRole'] = decorated.role === 'background' ? 'background' : 'overlay';
+      el.dataset['sbAlignment'] = decorated.alignment ?? 'center';
+      break;
+    }
+    case 'chart': {
+      // Phase 7: the chrome is (re)drawn at layout from the node's props, so
+      // an `update` with new marks redraws at the next commit; nothing
+      // animates. Only a summary lands on the element itself.
+      const chart = props as ChartProps;
+      el.dataset['sbMarks'] = String(Array.isArray(chart.marks) ? chart.marks.length : 0);
+      break;
+    }
+    case 'chartitem': {
+      const item = props as ChartItemProps;
+      el.dataset['sbRole'] = item.role ?? 'annotation';
+      el.dataset['sbPosition'] = item.position ?? 'overlay';
+      break;
+    }
+    // Phase 8: gestures, rows, navigation. The attributes are what the
+    // controller (src/interaction.ts) and the stylesheet read; the engine
+    // reads the props from the node tree.
+    case 'gesture': {
+      const gesture = (props as GestureProps | undefined) ?? {};
+      el.toggleAttribute('data-sb-drag', gesture.drag === true);
+      el.toggleAttribute('data-sb-long-press', gesture.longPress === true);
+      break;
+    }
+    case 'swipeactions': {
+      const swipe = (props as SwipeActionsProps | undefined) ?? { trailing: 0, leading: 0 };
+      el.dataset['sbTrailing'] = String(Math.max(0, Math.floor(Number(swipe.trailing) || 0)));
+      el.dataset['sbLeading'] = String(Math.max(0, Math.floor(Number(swipe.leading) || 0)));
+      break;
+    }
+    case 'contextmenu':
+      break;
+    case 'listrow': {
+      const row = (props as ListRowProps | undefined) ?? {};
+      el.toggleAttribute('data-sb-selectable', row.selectable === true);
+      el.toggleAttribute('data-sb-selected', row.selected === true);
+      el.toggleAttribute('data-sb-deletable', row.deletable === true);
+      if (row.selectable) el.setAttribute('aria-selected', String(row.selected === true));
+      else el.removeAttribute('aria-selected');
+      const control = el.querySelector<HTMLElement>(':scope > .sb-listrow-control');
+      control?.setAttribute('aria-label', row.selectable ? (row.selected ? 'Deselect' : 'Select') : 'Delete');
+      break;
+    }
+    // Phase 8: alerts and controls.
+    case 'alert':
+      applyAlert(el, (props as AlertProps) ?? {});
+      break;
+    case 'stepper':
+      applyStepper(el, (props as StepperProps) ?? {});
+      break;
+    case 'slider':
+      applySlider(el, (props as SliderProps) ?? {});
+      break;
+    case 'datepicker':
+      applyDatePicker(el, (props as DatePickerProps) ?? {});
+      break;
+    case 'texteditor':
+      applyTextEditor(el as HTMLTextAreaElement, (props as TextEditorProps) ?? {});
+      break;
+    default: {
+      const unknown: never = kind;
+      throw new RendererError(`Unknown element kind ${String(unknown)}`);
+    }
+  }
+}
+
+function applyText(el: HTMLElement, props: TextProps): void {
+  el.textContent = props.text ?? '';
+}
+
+/**
+ * Phase 8 `.refreshable`: a `list` / `scrollview` gets a 40px spinner row
+ * (`.sb-refresh`, positioned by the stylesheet above the content) that shows
+ * while `refreshing`; the controller sends `refresh` after a pull past 60.
+ */
+function applyRefreshable(el: HTMLElement, refreshable: boolean, refreshing: boolean): void {
+  el.toggleAttribute('data-sb-refreshable', refreshable);
+  el.toggleAttribute('data-sb-refreshing', refreshable && refreshing);
+  let indicator = el.querySelector<HTMLElement>(':scope > .sb-refresh');
+  if (!refreshable) {
+    indicator?.remove();
+    return;
+  }
+  if (!indicator) {
+    indicator = div('sb-refresh');
+    indicator.setAttribute('aria-hidden', 'true');
+    indicator.append(div('sb-refresh-spinner'));
+    el.prepend(indicator);
+  }
+}
+
+/** Phase 6: the gauge's value (0...1) and style; the bar geometry comes from the engine. */
+function applyGauge(el: HTMLElement, props: GaugeProps): void {
+  const value = Number.isFinite(props.value) ? Math.min(1, Math.max(0, props.value)) : 0;
+  el.dataset['sbStyle'] = props.style ?? 'automatic';
+  el.dataset['sbValue'] = String(value);
+  el.setAttribute('aria-valuenow', String(value));
+}
+
+function applyColor(el: HTMLElement, props: ColorProps): void {
+  el.style.backgroundColor = props.color ? colorToCSS(props.color) : 'transparent';
+}
+
+/** Radius that turns a box into each shape (the layout engine sizes it). */
+const SHAPE_RADIUS: Record<ShapeProps['shape'], (cornerRadius: number) => string> = {
+  rectangle: () => '0px',
+  roundedRectangle: (r) => `${Math.max(0, r)}px`,
+  circle: () => '50%',
+  capsule: () => '9999px',
+  ellipse: () => '50%',
+  // Phase 6: `ContainerRelativeShape` draws like a rounded rectangle.
+  containerRelative: (r) => `${Math.max(0, r)}px`,
+};
+
+/**
+ * `fill: null` with no stroke paints the current foreground color (a bare
+ * `Circle()`); with a stroke it is `Shape.stroke(_:)`, which only outlines.
+ * Phase 6: `fill` and `stroke.color` are ShapeStyles (gradients, materials,
+ * hierarchical fills). A gradient stroke uses its first stop (CSS borders are
+ * flat). The stroke is a CSS border, which lies inside the box: that is
+ * `.strokeBorder` (`inset: true`); a plain `.stroke` is drawn the same way,
+ * and `data-sb-stroke` records which one it was.
+ */
+function applyShape(el: HTMLElement, props: ShapeProps): void {
+  const shape = props.shape in SHAPE_RADIUS ? props.shape : 'rectangle';
+  const s = el.style;
+  el.dataset['sbShape'] = shape;
+  s.borderRadius = SHAPE_RADIUS[shape](Number(props.cornerRadius) || 0);
+  const stroke = props.stroke;
+  if (props.fill) applyPaint(el, styleToCSS(props.fill, 'paint'));
+  else if (!stroke) s.background = 'var(--sb-foreground-paint, currentColor)'; // a gradient foreground paints the shape too
+  else s.backgroundColor = 'transparent';
+  if (stroke) {
+    const width = Number.isFinite(stroke.lineWidth) ? Math.max(0, stroke.lineWidth) : 1;
+    const color = stroke.color ? styleToCSS(stroke.color, 'paint').solid : 'currentColor';
+    s.border = `${width}px solid ${color}`;
+    el.dataset['sbStroke'] = stroke.inset ? 'inset' : 'center';
+  }
+}
+
+/** Paint an area with a resolved ShapeStyle: a color, a gradient image or a material over a blurred backdrop. */
+function applyPaint(el: HTMLElement, paint: PaintCSS): void {
+  const s = el.style;
+  if (paint.kind === 'gradient') {
+    s.backgroundColor = 'transparent';
+    s.backgroundImage = paint.value;
+  } else {
+    s.backgroundColor = paint.value;
+  }
+  if (paint.backdropFilter) {
+    s.setProperty('backdrop-filter', paint.backdropFilter);
+    s.setProperty('-webkit-backdrop-filter', paint.backdropFilter);
+  }
+}
+
+// Stacks, spacers and zstacks are pure layout: the engine reads their props
+// from the node tree; the attributes only make the DOM easy to inspect.
+function applyVStack(el: HTMLElement, props: VStackProps): void {
+  el.dataset['alignment'] = props.alignment;
+  el.dataset['sbSpacing'] = props.spacing == null ? 'default' : String(props.spacing);
+}
+
+function applyHStack(el: HTMLElement, props: HStackProps): void {
+  el.dataset['alignment'] = props.alignment;
+  el.dataset['sbSpacing'] = props.spacing == null ? 'default' : String(props.spacing);
+}
+
+function applySpacer(el: HTMLElement, props: SpacerProps): void {
+  el.dataset['sbMinLength'] = props.minLength == null ? 'default' : String(props.minLength);
+}
+
+function applyButton(el: HTMLElement, props: ButtonProps): void {
+  el.dataset['sbStyle'] = props.style ?? 'automatic';
+  if (props.role) el.dataset['sbRole'] = props.role;
+}
+
+function applyZStack(el: HTMLElement, props: ZStackProps): void {
+  el.dataset['alignment'] = props.alignment;
+}
+
+/**
+ * An `image` is an SF Symbol (`systemName`, drawn from the open icon set) or,
+ * Phase 5, a catalog image (`name`): a bitmap in an `<img>` that fills the
+ * frame the layout engine computed, or a `.symbolset` SVG used as a mask over
+ * the current color so it tints like a symbol. Names the catalog does not
+ * know get the same dashed placeholder as unmapped symbols, with the name as
+ * the tooltip, so the gap is easy to spot and fix.
+ */
+function applyImage(el: HTMLElement, props: ImageProps, assets: AssetCatalog): void {
+  const missing = (name: string): void => {
+    el.replaceChildren();
+    el.title = name;
+    el.setAttribute('aria-label', name);
+    el.dataset['sbMissing'] = '';
+  };
+  const found = (name: string, child: Element): void => {
+    el.replaceChildren(child);
+    el.removeAttribute('title');
+    el.setAttribute('aria-label', name);
+    delete el.dataset['sbMissing'];
+  };
+  if (isAssetImage(props)) {
+    const name = props.name ?? '';
+    delete el.dataset['sbSymbol'];
+    el.dataset['sbAsset'] = name;
+    if (props.resizable) el.dataset['sbResizable'] = '';
+    else delete el.dataset['sbResizable'];
+    const asset = assets.images[name];
+    if (!asset) {
+      missing(name);
+      return;
+    }
+    if (asset.kind === 'symbol') {
+      const mask = document.createElement('span');
+      mask.className = 'sb-image-mask';
+      const url = `url("${asset.src}")`;
+      mask.style.setProperty('mask-image', url);
+      mask.style.setProperty('-webkit-mask-image', url);
+      found(name, mask);
+      return;
+    }
+    // Reuse the <img>: replacing it on every update left the box empty
+    // until the new bitmap decoded, which made the brand header's truck
+    // frames flicker at 20 fps. A changed source is decoded off-screen
+    // first and swapped in only once it is ready.
+    const existing = el.firstElementChild;
+    if (existing instanceof HTMLImageElement) {
+      el.removeAttribute('title');
+      el.setAttribute('aria-label', name);
+      delete el.dataset['sbMissing'];
+      // `src` the property is absolute; compare the attribute as written.
+      if (existing.getAttribute('src') !== asset.src && existing.dataset['sbPending'] !== asset.src) {
+        swapImageSource(existing, asset.src);
+      }
+      return;
+    }
+    const img = document.createElement('img');
+    img.src = asset.src;
+    img.alt = '';
+    img.draggable = false;
+    img.decoding = 'async';
+    found(name, img);
+    return;
+  }
+  const name = props.systemName ?? '';
+  delete el.dataset['sbAsset'];
+  delete el.dataset['sbResizable'];
+  el.dataset['sbSymbol'] = name;
+  const svg = renderSymbol(name);
+  if (svg) found(name, svg);
+  else missing(name);
+}
+
+/**
+ * Points `img` at `src` once the bitmap is decoded, so the previous frame
+ * stays visible meanwhile; a newer request supersedes a pending one.
+ */
+function swapImageSource(img: HTMLImageElement, src: string): void {
+  img.dataset['sbPending'] = src;
+  const probe = new Image();
+  probe.src = src;
+  const commit = (): void => {
+    if (img.dataset['sbPending'] !== src) return;
+    delete img.dataset['sbPending'];
+    img.setAttribute('src', src);
+  };
+  if (typeof probe.decode === 'function') probe.decode().then(commit, commit);
+  else probe.complete ? commit() : (probe.onload = probe.onerror = commit);
+}
+
+function applySection(el: HTMLElement, props: SectionProps): void {
+  const header = el.querySelector<HTMLElement>(':scope > .sb-section-header');
+  const footer = el.querySelector<HTMLElement>(':scope > .sb-section-footer');
+  if (header) {
+    header.textContent = props.header ?? '';
+    header.hidden = !props.header;
+  }
+  if (footer) {
+    footer.textContent = props.footer ?? '';
+    footer.hidden = !props.footer;
+  }
+}
+
+function applyTextField(input: HTMLInputElement, props: TextFieldProps): void {
+  input.type = props.secure ? 'password' : 'text';
+  input.placeholder = props.placeholder ?? '';
+  input.dataset['sbStyle'] = props.style ?? 'plain';
+  const text = props.text ?? '';
+  // Leave the caret alone when Swift echoes the value the field already shows.
+  if (input.value !== text) input.value = text;
+  // Phase 12: a bound field reports focus changes and follows the bound value;
+  // the move happens once the element is in the document (see `syncFocus`).
+  if (typeof props.focused === 'boolean') {
+    input.dataset['sbFocus'] = String(props.focused);
+  } else {
+    delete input.dataset['sbFocus'];
+  }
+  if (props.submit === true) input.dataset['sbSubmit'] = 'true';
+  else delete input.dataset['sbSubmit'];
+  if (typeof props.submitLabel === 'string' && props.submitLabel.length > 0) input.enterKeyHint = props.submitLabel;
+  else input.removeAttribute('enterkeyhint');
+}
+
+/** Phase 12 `.scrollTargetLayout()`: the stack's children snap (styles.css). */
+function applyScrollTarget(el: HTMLElement, target: boolean): void {
+  if (target) el.dataset['sbScrollTarget'] = 'true';
+  else delete el.dataset['sbScrollTarget'];
+}
+
+/** Like `applyTextField`: the caret survives an echo of the value the field shows. */
+function applySearchField(el: HTMLElement, props: SearchFieldProps): void {
+  const input = el.querySelector<HTMLInputElement>(':scope > .sb-searchfield-input');
+  if (!input) return;
+  const placeholder = typeof props.placeholder === 'string' && props.placeholder.length > 0 ? props.placeholder : 'Search';
+  input.placeholder = placeholder;
+  input.setAttribute('aria-label', placeholder);
+  const text = props.text ?? '';
+  if (input.value !== text) input.value = text;
+}
+
+function setSwitchState(toggle: HTMLElement, isOn: boolean): void {
+  toggle.dataset['sbOn'] = String(isOn);
+  const sw = toggle.querySelector<HTMLElement>(':scope > .sb-switch');
+  sw?.setAttribute('aria-checked', String(isOn));
+}
+
+function applyNavScreen(el: HTMLElement, props: NavScreenProps): void {
+  const title = props.title ?? '';
+  const depth = Number.isFinite(props.depth) ? props.depth : 0;
+  const mode = props.displayMode ?? 'automatic';
+  const large = mode === 'large' || (mode === 'automatic' && depth === 0);
+  el.dataset['sbTitle'] = title;
+  el.dataset['sbDepth'] = String(depth);
+  el.dataset['sbDisplay'] = large ? 'large' : 'inline';
+  const inlineTitle = el.querySelector<HTMLElement>(':scope > .sb-navbar > .sb-navbar-title');
+  const largeTitle = el.querySelector<HTMLElement>(':scope > .sb-navscreen-body > .sb-navbar-large-title');
+  if (inlineTitle) inlineTitle.textContent = large ? '' : title;
+  if (largeTitle) {
+    largeTitle.textContent = large ? title : '';
+    largeTitle.hidden = !large;
+  }
+  el.setAttribute('aria-label', title);
+}
+
+/**
+ * Segmented: one `.sb-segment` radio button per option, the selected one
+ * carrying the pill. Menu: the label leading, the selected option plus a
+ * `chevron.up.chevron.down` glyph trailing; the element itself is the button
+ * that opens the menu. Inline (Phase 6): a dim label row when the label is
+ * non-empty, then one `.sb-picker-option` radio row per option with a
+ * trailing checkmark on the selected one.
+ */
+function applyPicker(el: HTMLElement, props: PickerProps): void {
+  const options = Array.isArray(props.options) ? props.options.map(String) : [];
+  const selected = clampIndex(props.selected, options.length);
+  const style = props.style === 'segmented' ? 'segmented' : props.style === 'inline' ? 'inline' : 'menu';
+  const label = props.label ?? '';
+  el.dataset['sbStyle'] = style;
+  el.dataset['sbSelected'] = String(selected);
+  el.dataset['sbLabel'] = label;
+  el.replaceChildren();
+  if (style === 'inline') {
+    el.setAttribute('role', 'radiogroup');
+    el.setAttribute('aria-label', label);
+    el.removeAttribute('tabindex');
+    el.removeAttribute('aria-haspopup');
+    el.removeAttribute('aria-expanded');
+    if (label) {
+      const labelRow = div('sb-picker-inline-label');
+      labelRow.textContent = label;
+      el.append(labelRow);
+    }
+    options.forEach((option, index) => {
+      const row = document.createElement('button');
+      row.type = 'button';
+      row.className = 'sb-picker-option';
+      row.setAttribute('role', 'radio');
+      row.setAttribute('aria-checked', String(index === selected));
+      row.dataset['sbIndex'] = String(index);
+      const title = span('sb-picker-option-title');
+      title.textContent = option;
+      const check = span('sb-picker-option-check');
+      const glyph = renderSymbol('checkmark');
+      if (glyph) check.append(glyph);
+      row.append(title, check);
+      el.append(row);
+    });
+    return;
+  }
+  if (style === 'segmented') {
+    el.setAttribute('role', 'radiogroup');
+    el.setAttribute('aria-label', label);
+    el.removeAttribute('tabindex');
+    el.removeAttribute('aria-haspopup');
+    el.removeAttribute('aria-expanded');
+    // The gray track sits at the control's frame (which, in a list row, is
+    // narrower than the row box the element occupies).
+    el.append(div('sb-segment-track'));
+    options.forEach((option, index) => {
+      const segment = document.createElement('button');
+      segment.type = 'button';
+      segment.className = 'sb-segment';
+      segment.setAttribute('role', 'radio');
+      segment.setAttribute('aria-checked', String(index === selected));
+      segment.dataset['sbIndex'] = String(index);
+      const text = span('sb-segment-title');
+      text.textContent = option;
+      segment.append(text);
+      el.append(segment);
+    });
+    return;
+  }
+  el.setAttribute('role', 'button');
+  el.setAttribute('aria-haspopup', 'menu');
+  el.setAttribute('aria-expanded', 'false');
+  el.tabIndex = 0;
+  const labelEl = span('sb-picker-label');
+  labelEl.textContent = label;
+  const value = span('sb-picker-value');
+  const valueText = span('sb-picker-value-text');
+  valueText.textContent = options[selected] ?? '';
+  value.append(valueText);
+  const chevron = renderSymbol('chevron.up.chevron.down');
+  if (chevron) value.append(chevron);
+  el.append(labelEl, value);
+  el.setAttribute('aria-label', `${label}, ${options[selected] ?? ''}`);
+}
+
+/** Move a segmented picker's pill or an inline picker's checkmark (optimistically, before Swift confirms). */
+function setPickerSelection(picker: HTMLElement, index: number): void {
+  picker.dataset['sbSelected'] = String(index);
+  picker.querySelectorAll<HTMLElement>(':scope > .sb-segment, :scope > .sb-picker-option').forEach((segment, i) => {
+    segment.setAttribute('aria-checked', String(i === index));
+  });
+}
+
+const FONT_WEIGHT: Record<FontWeight, string> = {
+  ultraLight: '100',
+  thin: '200',
+  light: '300',
+  regular: '400',
+  medium: '500',
+  semibold: '600',
+  bold: '700',
+  heavy: '800',
+  black: '900',
+};
+
+const FONT_FAMILY_MONO =
+  'ui-monospace, "SF Mono", Menlo, Monaco, "Cascadia Mono", "Roboto Mono", Consolas, monospace';
+const FONT_FAMILY_SERIF = 'ui-serif, "New York", Georgia, "Times New Roman", serif';
+const FONT_FAMILY_ROUNDED =
+  'ui-rounded, "SF Pro Rounded", -apple-system, BlinkMacSystemFont, "SF Pro Text", "Helvetica Neue", Inter, system-ui, sans-serif';
+
+/**
+ * Visual styling of a `styled` box. Layout fields (`padding`, `frame`,
+ * `layoutPriority`, `fixedSize`, `lineLimit`, `multilineTextAlignment`) are
+ * read by the layout engine from the node tree; they only leave data
+ * attributes here. Font and color settings are set as inline CSS so children
+ * inherit them (the engine resolves text fonts itself).
+ */
+export function applyStyle(el: HTMLElement, style: Style): void {
+  const s = el.style;
+
+  if (style.padding) {
+    const { top = 0, leading = 0, bottom = 0, trailing = 0 } = style.padding;
+    el.dataset['sbPadding'] = `${top} ${trailing} ${bottom} ${leading}`;
+  }
+
+  if (style.font) {
+    const { size, weight, design, textStyle, relativeTo } = style.font;
+    if (size != null) {
+      // A fixed size; `relativeTo` scales it like that text style (the
+      // scale factor is a CSS variable the page sets per Dynamic Type size).
+      s.fontSize = relativeTo ? `calc(${size}px * var(--sb-ts-${relativeTo}-scale, 1))` : `${size}px`;
+      // Do not inherit a text style's px line height from an ancestor.
+      s.lineHeight = '1.3';
+      if (relativeTo) el.dataset['sbRelativeTo'] = relativeTo;
+    } else if (textStyle) {
+      // Text styles follow Dynamic Type through CSS variables (see
+      // typography.ts); the fallbacks are the Large sizes.
+      const large = resolveTextStyle(textStyle, DEFAULT_TYPE_SIZE);
+      s.fontSize = `var(${textStyleVar(textStyle, 'size')}, ${large.fontSize}px)`;
+      s.lineHeight = `var(${textStyleVar(textStyle, 'lh')}, ${large.lineHeight}px)`;
+      el.dataset['sbTextStyle'] = textStyle;
+      const implied = TEXT_STYLE_WEIGHT[textStyle];
+      if (!weight && implied) s.fontWeight = FONT_WEIGHT[implied];
+    }
+    if (weight) s.fontWeight = FONT_WEIGHT[weight] ?? '400';
+    if (design === 'monospaced') s.fontFamily = FONT_FAMILY_MONO;
+    else if (design === 'rounded') s.fontFamily = FONT_FAMILY_ROUNDED;
+    else if (design === 'serif') s.fontFamily = FONT_FAMILY_SERIF;
+    else if (design === 'default') s.fontFamily = 'var(--sb-font-family)';
+  }
+
+  if (style.foreground) {
+    const paint = styleToCSS(style.foreground, 'text');
+    // Buttons default to the accent color; a foreground set by an ancestor
+    // styled box wins, as it does in SwiftUI.
+    s.color = paint.solid;
+    s.setProperty('--sb-button-color', paint.solid);
+    if (paint.kind === 'gradient') {
+      // Text paints the gradient through its own background clipped to the
+      // glyphs (see `.sb-text` in styles.css); the custom properties inherit
+      // down to every text in the subtree. `currentColor` consumers
+      // (symbols, strokes) fall back to the first stop set above.
+      s.setProperty('--sb-text-gradient', paint.value);
+      s.setProperty('--sb-text-clip', 'text');
+      s.setProperty('--sb-text-color', 'transparent');
+      s.setProperty('--sb-foreground-paint', paint.value);
+      el.dataset['sbGradientText'] = '';
+    } else {
+      // A flat foreground ends a gradient inherited from an ancestor.
+      s.setProperty('--sb-text-gradient', 'initial');
+      s.setProperty('--sb-text-clip', 'initial');
+      s.setProperty('--sb-text-color', 'initial');
+      s.setProperty('--sb-foreground-paint', 'initial');
+    }
+  }
+
+  if (style.background) {
+    applyPaint(el, styleToCSS(style.background, 'paint'));
+    // A painted background is a view of its own: hittable (styles.css).
+    el.dataset['sbBackground'] = '';
+  } else {
+    delete el.dataset['sbBackground'];
+  }
+
+  if (style.frame) {
+    const { width, height, minWidth, maxWidth, minHeight, maxHeight, alignment } = style.frame;
+    const parts: string[] = [];
+    if (width != null) parts.push(`w${width}`);
+    if (height != null) parts.push(`h${height}`);
+    if (minWidth != null) parts.push(`minw${minWidth}`);
+    if (maxWidth != null) parts.push(`maxw${maxWidth}`);
+    if (minHeight != null) parts.push(`minh${minHeight}`);
+    if (maxHeight != null) parts.push(`maxh${maxHeight}`);
+    el.dataset['sbFrame'] = parts.join(' ');
+    el.dataset['sbFrameAlignment'] = alignment ?? 'center';
+  }
+
+  if (style.cornerRadius != null) {
+    s.borderRadius = `${style.cornerRadius}px`;
+    s.overflow = 'hidden';
+  }
+
+  // Phase 6 visual effects: CSS only, the layout engine never sees them.
+  const effects = effectsCSS(style);
+  if (effects.transform) s.transform = effects.transform;
+  if (effects.transformOrigin) s.transformOrigin = effects.transformOrigin;
+  if (effects.filter) s.filter = effects.filter;
+  // Phase 7: `.hidden()` keeps the box (the engine lays it out) but draws
+  // nothing and takes no input; `.mask { }` clips the box to a style's alpha.
+  if (effects.hidden) {
+    s.visibility = 'hidden';
+    s.pointerEvents = 'none';
+    el.dataset['sbHidden'] = '';
+  }
+  if (effects.maskImage) {
+    for (const prefix of ['', '-webkit-']) {
+      s.setProperty(`${prefix}mask-image`, effects.maskImage);
+      s.setProperty(`${prefix}mask-size`, '100% 100%');
+      s.setProperty(`${prefix}mask-repeat`, 'no-repeat');
+    }
+  }
+  if (style.clipped) {
+    s.overflow = 'hidden';
+    el.dataset['sbClipped'] = '';
+  }
+  // Phase 8: `.allowsHitTesting(false)` lets input through the subtree.
+  if (style.hitTesting === false) {
+    s.pointerEvents = 'none';
+    el.dataset['sbHitTesting'] = 'false';
+  }
+
+  let opacity = style.opacity;
+  if (style.disabled) {
+    // `.disabled(true)`: dim the subtree and block input.
+    opacity = (opacity ?? 1) * 0.4;
+    s.pointerEvents = 'none';
+    el.dataset['sbDisabled'] = '';
+    el.setAttribute('aria-disabled', 'true');
+  } else {
+    el.removeAttribute('aria-disabled');
+  }
+  if (opacity != null) {
+    s.opacity = String(opacity);
+  }
+
+  // Phase 3 text and layout hints (the engine reads them from the node tree).
+  if (style.layoutPriority != null && Number.isFinite(style.layoutPriority)) {
+    el.dataset['sbLayoutPriority'] = String(style.layoutPriority);
+  }
+  if (style.lineLimit != null && style.lineLimit > 0) {
+    el.dataset['sbLineLimit'] = String(Math.floor(style.lineLimit));
+  }
+  if (style.multilineTextAlignment) el.dataset['sbTextAlign'] = style.multilineTextAlignment;
+  if (style.fixedSize) {
+    const { horizontal, vertical } = style.fixedSize;
+    el.dataset['sbFixedSize'] = `${horizontal ? 'h' : ''}${vertical ? 'v' : ''}`;
+  }
+  // Phase 5: `.aspectRatio` is pure layout (the engine sizes the child); the
+  // box reports the child's size either way, so `fill` has nothing to clip
+  // here (SwiftUI needs `.clipped()` for that too).
+  if (style.aspectRatio) {
+    const { ratio, contentMode } = style.aspectRatio;
+    el.dataset['sbAspectRatio'] = `${ratio ?? 'auto'} ${contentMode ?? 'fit'}`;
+  }
+  if (style.animationToken != null) el.dataset[ANIMATION_TOKEN] = String(style.animationToken);
+  if (style.animation) ANIMATIONS.set(el, style.animation);
+  if (style.transition) setTransition(el, style.transition);
+
+  // Phase 6 (docs/phase6/layout-containers.md).
+  if (style.tint) {
+    // `.tint`: gauges, switches and prominent buttons below read `--sb-tint`.
+    s.setProperty('--sb-tint', colorToCSS(style.tint));
+  }
+  if (style.position) {
+    const { x, y } = style.position;
+    el.dataset['sbPosition'] = `${x} ${y}`;
+  }
+  if (style.gridCellColumns != null && Number.isFinite(style.gridCellColumns)) {
+    el.dataset['sbGridCellColumns'] = String(Math.max(1, Math.floor(style.gridCellColumns)));
+  }
+  if (style.gridCellAnchor) {
+    const { x, y } = style.gridCellAnchor;
+    el.dataset['sbGridCellAnchor'] = `${x} ${y}`;
+  }
+}
+
+// Colors and ShapeStyles resolve in src/styles.ts; re-exported for callers of the renderer.
+export { colorToCSS, styleToCSS } from './styles';
+
+/**
+ * The `<style>` text declaring every catalog color as a custom property per
+ * theme (the device sets `data-theme`, see styles.css). A colorset without a
+ * dark variant keeps its light value in dark mode, as on iOS. Empty string
+ * for a catalog without colors.
+ */
+export function assetColorsCSS(catalog: AssetCatalog): string {
+  const names = Object.keys(catalog.colors).sort();
+  if (names.length === 0) return '';
+  const declarations = (scheme: 'light' | 'dark'): string =>
+    names
+      .map((name) => {
+        const color = catalog.colors[name];
+        if (!color) return '';
+        const value = scheme === 'dark' ? (color.dark ?? color.light) : color.light;
+        return `  ${assetColorVar(name)}: ${sanitizeColor(value)};\n`;
+      })
+      .join('');
+  return (
+    `.device[data-theme="light"] {\n${declarations('light')}}\n` +
+    `.device[data-theme="dark"] {\n${declarations('dark')}}\n`
+  );
+}
+
+/** A manifest color value is injected into a stylesheet: keep only CSS color syntax characters. */
+function sanitizeColor(value: string): string {
+  return /^[A-Za-z0-9#(),.%\s/-]+$/.test(value) ? value : 'magenta';
+}
+
+// Re-exported so callers can build typed fixtures without importing protocol.ts.
+export type { Op, ElementKind, ElementPropsByKind, RendererEvent };