@swiftbrowser/web 0.1.0

package/src/chartDom.ts

@@ -0,0 +1,481 @@
+/**
+ * Phase 7: the chrome of a `chart` element (docs/ops-protocol.md, "Phase 7:
+ * charts").
+ *
+ * The engine (src/layout/chart.ts) hands over the plot rectangle, the axis
+ * bands, the legend item rects and the text label rects as `chrome`, and the
+ * label texts as `chromeText`; this module turns the chart's props into DOM
+ * inside its `.sb-chart-chrome` container:
+ *
+ * - one `<svg class="sb-chart-plot">` the size of the plot (`overflow:
+ *   hidden`) holding the grid lines and the marks in array order, with
+ *   `<defs>` for gradient fills and `clipPath`s for masks;
+ * - 1 × 4 px tick marks outside the plot;
+ * - the axis text labels (`.sb-chart-label`, caption font, secondary color);
+ * - the legend items (`.sb-chart-legend-item`: a glyph and a caption label).
+ *
+ * Everything is rebuilt whenever the props or the geometry change (an
+ * `update` with new `marks` redraws at the next commit); nothing animates.
+ * `chartitem` children are ordinary slot children the engine frames.
+ */
+
+import type { LayoutNode, LayoutResult, Rect, ResolvedFont } from './layout';
+import {
+  CHART_TICK_LENGTH,
+  areaPath,
+  legendGlyphSize,
+  linePath,
+  mapX,
+  mapY,
+  rectMarkRect,
+  symbolPath,
+  unitRect,
+} from './layout/chart';
+import {
+  isColor,
+  isColorGradientStyle,
+  isHierarchicalStyle,
+  isLinearGradientStyle,
+  isMaterialStyle,
+  isRadialGradientStyle,
+  type ChartAxis,
+  type ChartLegend,
+  type ChartMark,
+  type ChartProps,
+  type GradientStop,
+  type ShapeStyle,
+} from './protocol';
+import { MATERIAL_ALPHA, colorToCSS, styleToCSS } from './styles';
+
+const SVG_NS = 'http://www.w3.org/2000/svg';
+const LINE_WIDTH_DEFAULT = 2;
+const RULE_WIDTH_DEFAULT = 1;
+const SYMBOL_SIZE_DEFAULT = 8;
+/** Materials paint as a translucent system gray in SVG (no backdrop blur there). */
+const MATERIAL_GRAY = '120, 120, 128';
+
+/** Signature of the last chrome drawn per chart element, to skip unchanged redraws. */
+const DRAWN = new WeakMap<HTMLElement, string>();
+
+/** Draw (or redraw) a chart's chrome from its props and the engine's rects. */
+export function applyChartChrome(el: HTMLElement, node: LayoutNode, result: LayoutResult, box: Rect): void {
+  const container = el.querySelector<HTMLElement>(':scope > .sb-chart-chrome');
+  if (!container) return;
+  const chrome = result.chrome.get(node.id);
+  const plot = chrome?.['plot'];
+  if (!chrome || !plot) {
+    container.replaceChildren();
+    DRAWN.delete(el);
+    return;
+  }
+  const texts = result.chromeText.get(node.id) ?? {};
+  const font = result.fonts.get(node.id);
+  const signature = JSON.stringify([node.props, chrome, texts, font?.css ?? '', box.x, box.y]);
+  if (DRAWN.get(el) === signature) return;
+  DRAWN.set(el, signature);
+
+  const props = node.props as unknown as Partial<ChartProps>;
+  const doc = el.ownerDocument;
+  const idPrefix = `sb-chart-${node.id}`;
+  const nodes: Element[] = [];
+
+  nodes.push(buildPlot(doc, props, plot, box, idPrefix));
+  nodes.push(...buildTicks(doc, props, plot, box));
+  for (const key of Object.keys(chrome)) {
+    if (!key.startsWith('xlabel') && !key.startsWith('ylabel')) continue;
+    const rect = chrome[key] as Rect;
+    const layout = texts[key];
+    if (!layout) continue;
+    const label = doc.createElement('span');
+    label.className = 'sb-chart-label';
+    label.dataset['sbAxis'] = key.startsWith('x') ? 'x' : 'y';
+    label.style.font = layout.font.css;
+    label.style.textAlign = layout.alignment === 'trailing' ? 'right' : layout.alignment === 'center' ? 'center' : 'left';
+    label.style.lineHeight = `${rect.height}px`;
+    label.textContent = layout.lines.join('\n');
+    position(label, rect, box);
+    nodes.push(label);
+  }
+  nodes.push(...buildLegend(doc, props.legend ?? null, chrome, box, font, idPrefix));
+  container.replaceChildren(...nodes);
+}
+
+function position(el: HTMLElement | SVGElement, rect: Rect, origin: Rect): void {
+  const s = el.style;
+  s.position = 'absolute';
+  s.left = `${rect.x - origin.x}px`;
+  s.top = `${rect.y - origin.y}px`;
+  s.width = `${rect.width}px`;
+  s.height = `${rect.height}px`;
+}
+
+function svg<K extends keyof SVGElementTagNameMap>(doc: Document, name: K, attrs: Record<string, string | number> = {}): SVGElementTagNameMap[K] {
+  const el = doc.createElementNS(SVG_NS, name);
+  for (const [key, value] of Object.entries(attrs)) el.setAttribute(key, String(value));
+  return el;
+}
+
+const r2 = (v: number): number => Math.round(v * 100) / 100;
+const fin = (v: unknown, fallback: number): number => (typeof v === 'number' && Number.isFinite(v) ? v : fallback);
+
+// ---------------------------------------------------------------------------
+// The plot SVG
+// ---------------------------------------------------------------------------
+
+function buildPlot(doc: Document, props: Partial<ChartProps>, plot: Rect, box: Rect, idPrefix: string): SVGSVGElement {
+  const w = Math.max(0, plot.width);
+  const h = Math.max(0, plot.height);
+  const root = svg(doc, 'svg', { class: 'sb-chart-plot', width: w, height: h, viewBox: `0 0 ${w} ${h}` });
+  position(root, plot, box);
+  const defs = svg(doc, 'defs');
+  root.append(defs);
+  // Marks are laid out in the SVG's own coordinates: the plot at (0, 0).
+  const local: Rect = { x: 0, y: 0, width: w, height: h };
+
+  const grid = svg(doc, 'g', { class: 'sb-chart-grid' });
+  for (const u of gridLines(props.xAxis)) {
+    const x = r2(Math.floor(mapX(local, u)) + 0.5);
+    grid.append(svg(doc, 'line', { class: 'sb-chart-gridline', 'data-sb-axis': 'x', x1: x, y1: 0, x2: x, y2: h }));
+  }
+  for (const u of gridLines(props.yAxis)) {
+    const y = r2(Math.floor(mapY(local, u)) + 0.5);
+    grid.append(svg(doc, 'line', { class: 'sb-chart-gridline', 'data-sb-axis': 'y', x1: 0, y1: y, x2: w, y2: y }));
+  }
+  root.append(grid);
+
+  const marks = svg(doc, 'g', { class: 'sb-chart-marks' });
+  const ids = { next: 0, prefix: idPrefix };
+  const list = Array.isArray(props.marks) ? props.marks : [];
+  list.forEach((mark) => {
+    if (!mark || typeof mark !== 'object') return;
+    const el = buildMark(doc, defs, mark, local, ids);
+    if (el) marks.append(el);
+  });
+  root.append(marks);
+  return root;
+}
+
+function gridLines(axis: ChartAxis | null | undefined): number[] {
+  return axis && Array.isArray(axis.gridLines) ? axis.gridLines.filter((v) => typeof v === 'number' && Number.isFinite(v)) : [];
+}
+
+interface IdSource {
+  next: number;
+  prefix: string;
+}
+
+function nextId(ids: IdSource, kind: string): string {
+  return `${ids.prefix}-${kind}${ids.next++}`;
+}
+
+function buildMark(doc: Document, defs: SVGDefsElement, mark: ChartMark, plot: Rect, ids: IdSource): SVGElement | null {
+  let el: SVGElement | null;
+  let bbox: Rect;
+  switch (mark.kind) {
+    case 'rect': {
+      bbox = rectMarkRect(plot, mark);
+      const radius = Math.max(0, fin(mark.cornerRadius, 0));
+      el = svg(doc, 'rect', {
+        x: r2(bbox.x),
+        y: r2(bbox.y),
+        width: r2(Math.max(0, bbox.width)),
+        height: r2(Math.max(0, bbox.height)),
+        rx: r2(radius),
+        ry: r2(radius),
+      });
+      el.style.fill = paintFor(doc, defs, mark.style, bbox, ids);
+      break;
+    }
+    case 'line': {
+      const points = (Array.isArray(mark.points) ? mark.points : [])
+        .filter((p) => p && typeof p === 'object')
+        .map((p) => ({ x: mapX(plot, fin(p.x, 0)), y: mapY(plot, fin(p.y, 0)) }));
+      bbox = boundsOf(points, plot);
+      const paint = paintFor(doc, defs, mark.style, bbox, ids);
+      const group = svg(doc, 'g');
+      const path = svg(doc, 'path', {
+        class: 'sb-chart-line',
+        d: linePath(points, mark.interpolation),
+        fill: 'none',
+        'stroke-width': r2(Math.max(0, fin(mark.lineWidth, LINE_WIDTH_DEFAULT))),
+        'stroke-linecap': 'round',
+        'stroke-linejoin': 'round',
+      });
+      path.style.stroke = paint;
+      group.append(path);
+      if (mark.symbol) {
+        const size = fin(mark.symbolSize, SYMBOL_SIZE_DEFAULT);
+        for (const p of points) group.append(symbolEl(doc, mark.symbol, p.x, p.y, size, paint));
+      }
+      el = group;
+      break;
+    }
+    case 'area': {
+      const points = (Array.isArray(mark.points) ? mark.points : [])
+        .filter((p) => p && typeof p === 'object')
+        .map((p) => ({ x: mapX(plot, fin(p.x, 0)), y0: mapY(plot, fin(p.y0, 0)), y1: mapY(plot, fin(p.y1, 0)) }));
+      bbox = boundsOf(points.flatMap((p) => [{ x: p.x, y: p.y0 }, { x: p.x, y: p.y1 }]), plot);
+      el = svg(doc, 'path', { class: 'sb-chart-area', d: areaPath(points, mark.interpolation) });
+      el.style.fill = paintFor(doc, defs, mark.style, bbox, ids);
+      break;
+    }
+    case 'point': {
+      const size = fin(mark.symbolSize, SYMBOL_SIZE_DEFAULT);
+      const cx = mapX(plot, fin(mark.x, 0));
+      const cy = mapY(plot, fin(mark.y, 0));
+      bbox = { x: cx - size / 2, y: cy - size / 2, width: size, height: size };
+      el = symbolEl(doc, mark.symbol, cx, cy, size, paintFor(doc, defs, mark.style, bbox, ids));
+      break;
+    }
+    case 'rule': {
+      bbox = unitRect(plot, fin(mark.x0, 0), fin(mark.x1, 0), fin(mark.y0, 0), fin(mark.y1, 0));
+      el = svg(doc, 'line', {
+        class: 'sb-chart-rule',
+        x1: r2(mapX(plot, fin(mark.x0, 0))),
+        y1: r2(mapY(plot, fin(mark.y0, 0))),
+        x2: r2(mapX(plot, fin(mark.x1, 0))),
+        y2: r2(mapY(plot, fin(mark.y1, 0))),
+        'stroke-width': r2(Math.max(0, fin(mark.lineWidth, RULE_WIDTH_DEFAULT))),
+        'stroke-linecap': 'butt',
+      });
+      el.style.stroke = paintFor(doc, defs, mark.style, bbox, ids);
+      break;
+    }
+    default:
+      return null;
+  }
+  el.classList.add('sb-chart-mark');
+  el.dataset['sbMark'] = mark.kind;
+  const opacity = fin(mark.opacity, 1);
+  if (opacity < 1) el.setAttribute('opacity', String(Math.max(0, opacity)));
+  const clip = mark.mask ? clipPathFor(doc, defs, mark.mask, plot, ids) : null;
+  if (clip) el.setAttribute('clip-path', `url(#${clip})`);
+  return el;
+}
+
+function boundsOf(points: readonly { x: number; y: number }[], fallback: Rect): Rect {
+  if (points.length === 0) return fallback;
+  let minX = Infinity;
+  let minY = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+  for (const p of points) {
+    minX = Math.min(minX, p.x);
+    minY = Math.min(minY, p.y);
+    maxX = Math.max(maxX, p.x);
+    maxY = Math.max(maxY, p.y);
+  }
+  return { x: minX, y: minY, width: maxX - minX, height: maxY - minY };
+}
+
+/** A symbol glyph: a filled path, or a stroked one for the line glyphs (cross, plus, asterisk). */
+function symbolEl(doc: Document, symbol: string | null | undefined, cx: number, cy: number, size: number, paint: string): SVGPathElement {
+  const glyph = symbolPath(symbol, cx, cy, size);
+  const path = svg(doc, 'path', { class: 'sb-chart-symbol', d: glyph.d, 'data-sb-symbol': symbol ?? 'circle' });
+  if (glyph.stroked) {
+    path.setAttribute('fill', 'none');
+    path.setAttribute('stroke-width', String(r2(glyph.strokeWidth)));
+    path.setAttribute('stroke-linecap', 'round');
+    path.style.stroke = paint;
+  } else {
+    path.style.fill = paint;
+  }
+  return path;
+}
+
+/**
+ * A `clipPath` holding the mask mark's geometry (an `area` path or a `rect`;
+ * other kinds clip nothing). Returns its id, or null.
+ */
+function clipPathFor(doc: Document, defs: SVGDefsElement, mask: ChartMark, plot: Rect, ids: IdSource): string | null {
+  if (!mask || typeof mask !== 'object') return null;
+  let shape: SVGElement;
+  if (mask.kind === 'rect') {
+    const r = rectMarkRect(plot, mask);
+    shape = svg(doc, 'rect', {
+      x: r2(r.x),
+      y: r2(r.y),
+      width: r2(Math.max(0, r.width)),
+      height: r2(Math.max(0, r.height)),
+      rx: r2(Math.max(0, fin(mask.cornerRadius, 0))),
+    });
+  } else if (mask.kind === 'area') {
+    const points = (Array.isArray(mask.points) ? mask.points : [])
+      .filter((p) => p && typeof p === 'object')
+      .map((p) => ({ x: mapX(plot, fin(p.x, 0)), y0: mapY(plot, fin(p.y0, 0)), y1: mapY(plot, fin(p.y1, 0)) }));
+    shape = svg(doc, 'path', { d: areaPath(points, mask.interpolation) });
+  } else {
+    return null;
+  }
+  const id = nextId(ids, 'clip');
+  const clip = svg(doc, 'clipPath', { id });
+  clip.append(shape);
+  defs.append(clip);
+  return id;
+}
+
+// ---------------------------------------------------------------------------
+// ShapeStyle → SVG paint
+// ---------------------------------------------------------------------------
+
+/**
+ * The SVG paint for a ShapeStyle: a CSS color for flat styles (the same
+ * tokens the renderer uses: `--sb-color-*` for semantic and named colors,
+ * the fill tokens for hierarchical levels), or `url(#gradient)` after adding
+ * a `<linearGradient>` / `<radialGradient>` to `defs`. `bbox` is the mark's
+ * pixel bounds, which a radial gradient's center and radii refer to.
+ */
+function paintFor(doc: Document, defs: SVGDefsElement, style: ShapeStyle | undefined, bbox: Rect, ids: IdSource): string {
+  if (!style || typeof style !== 'object') return 'var(--sb-color-accent)';
+  if (isColor(style)) return colorToCSS(style);
+  if (isHierarchicalStyle(style)) return styleToCSS(style, 'paint').value;
+  if (isMaterialStyle(style)) {
+    const alpha = (MATERIAL_ALPHA[style.material] ?? MATERIAL_ALPHA.regular) * clamp01(style.opacity ?? 1);
+    return `rgba(${MATERIAL_GRAY}, ${r2(alpha * 0.5)})`;
+  }
+  const opacity = clamp01(style.opacity ?? 1);
+  if (isLinearGradientStyle(style)) {
+    const { stops, start, end } = style.linearGradient;
+    const id = nextId(ids, 'grad');
+    const gradient = svg(doc, 'linearGradient', {
+      id,
+      gradientUnits: 'objectBoundingBox',
+      x1: r2(unit(start?.x, 0.5)),
+      y1: r2(unit(start?.y, 0)),
+      x2: r2(unit(end?.x, 0.5)),
+      y2: r2(unit(end?.y, 1)),
+    });
+    appendStops(doc, gradient, stops ?? [], opacity);
+    defs.append(gradient);
+    return `url(#${id})`;
+  }
+  if (isRadialGradientStyle(style)) {
+    const { stops, center, startRadius, endRadius } = style.radialGradient;
+    const id = nextId(ids, 'grad');
+    const cx = bbox.x + unit(center?.x, 0.5) * bbox.width;
+    const cy = bbox.y + unit(center?.y, 0.5) * bbox.height;
+    const fallbackRadius = Math.hypot(bbox.width, bbox.height) / 2;
+    const r = endRadius != null && Number.isFinite(endRadius) && endRadius > 0 ? endRadius : fallbackRadius;
+    const fr = Math.max(0, startRadius != null && Number.isFinite(startRadius) ? startRadius : 0);
+    const gradient = svg(doc, 'radialGradient', { id, gradientUnits: 'userSpaceOnUse', cx: r2(cx), cy: r2(cy), r: r2(r), fr: r2(fr) });
+    appendStops(doc, gradient, stops ?? [], opacity);
+    defs.append(gradient);
+    return `url(#${id})`;
+  }
+  if (isColorGradientStyle(style)) {
+    // `Color.gradient`: a subtle vertical gradient from a lighter to a darker shade.
+    const base = colorToCSS(style.colorGradient);
+    const id = nextId(ids, 'grad');
+    const gradient = svg(doc, 'linearGradient', { id, gradientUnits: 'objectBoundingBox', x1: 0.5, y1: 0, x2: 0.5, y2: 1 });
+    gradient.append(stopEl(doc, 0, `color-mix(in srgb, ${base}, white 12%)`, opacity));
+    gradient.append(stopEl(doc, 1, `color-mix(in srgb, ${base}, black 12%)`, opacity));
+    defs.append(gradient);
+    return `url(#${id})`;
+  }
+  return 'magenta';
+}
+
+function appendStops(doc: Document, gradient: SVGElement, stops: readonly GradientStop[], opacity: number): void {
+  const valid = stops.filter((stop) => stop && typeof stop === 'object' && stop.color);
+  if (valid.length === 0) {
+    gradient.append(stopEl(doc, 0, 'transparent', opacity), stopEl(doc, 1, 'transparent', opacity));
+    return;
+  }
+  for (const stop of valid) gradient.append(stopEl(doc, clamp01(unit(stop.location, 0)), colorToCSS(stop.color), opacity));
+  if (valid.length === 1) gradient.append(stopEl(doc, 1, colorToCSS(valid[0]!.color), opacity));
+}
+
+function stopEl(doc: Document, offset: number, color: string, opacity: number): SVGStopElement {
+  const stop = svg(doc, 'stop', { offset: r2(offset) });
+  stop.style.stopColor = color;
+  if (opacity < 1) stop.style.stopOpacity = String(opacity);
+  return stop;
+}
+
+function unit(v: number | undefined, fallback: number): number {
+  return v != null && Number.isFinite(v) ? v : fallback;
+}
+
+function clamp01(v: number): number {
+  return Number.isFinite(v) ? Math.min(1, Math.max(0, v)) : 1;
+}
+
+// ---------------------------------------------------------------------------
+// Ticks and legend
+// ---------------------------------------------------------------------------
+
+/** 1 px ticks, 4 px long, outside the plot on the axis's side. */
+function buildTicks(doc: Document, props: Partial<ChartProps>, plot: Rect, box: Rect): HTMLElement[] {
+  const ticks: HTMLElement[] = [];
+  const x = props.xAxis;
+  if (x && Array.isArray(x.ticks)) {
+    const top = x.position === 'top' ? plot.y - CHART_TICK_LENGTH : plot.y + plot.height;
+    for (const u of x.ticks) {
+      if (typeof u !== 'number' || !Number.isFinite(u)) continue;
+      const tick = doc.createElement('span');
+      tick.className = 'sb-chart-tick';
+      tick.dataset['sbAxis'] = 'x';
+      position(tick, { x: Math.floor(mapX(plot, u)), y: top, width: 1, height: CHART_TICK_LENGTH }, box);
+      ticks.push(tick);
+    }
+  }
+  const y = props.yAxis;
+  if (y && Array.isArray(y.ticks)) {
+    const left = y.position === 'leading' ? plot.x - CHART_TICK_LENGTH : plot.x + plot.width;
+    for (const u of y.ticks) {
+      if (typeof u !== 'number' || !Number.isFinite(u)) continue;
+      const tick = doc.createElement('span');
+      tick.className = 'sb-chart-tick';
+      tick.dataset['sbAxis'] = 'y';
+      position(tick, { x: left, y: Math.floor(mapY(plot, u)), width: CHART_TICK_LENGTH, height: 1 }, box);
+      ticks.push(tick);
+    }
+  }
+  return ticks;
+}
+
+/** One `.sb-chart-legend-item` per legend entry at the engine's `legend<i>` rect. */
+function buildLegend(
+  doc: Document,
+  legend: ChartLegend | null,
+  chrome: Record<string, Rect>,
+  box: Rect,
+  font: ResolvedFont | undefined,
+  idPrefix: string,
+): HTMLElement[] {
+  const items: HTMLElement[] = [];
+  if (!legend || !Array.isArray(legend.items)) return items;
+  const ids: IdSource = { next: 0, prefix: `${idPrefix}-legend` };
+  legend.items.forEach((entry, i) => {
+    const rect = chrome[`legend${i}`];
+    if (!rect || !entry || typeof entry !== 'object') return;
+    const item = doc.createElement('div');
+    item.className = 'sb-chart-legend-item';
+    if (font) item.style.font = font.css;
+    position(item, rect, box);
+    const glyphSize = legendGlyphSize(entry.symbol);
+    const glyph = svg(doc, 'svg', {
+      class: 'sb-chart-legend-glyph',
+      width: glyphSize.width,
+      height: glyphSize.height,
+      viewBox: `0 0 ${glyphSize.width} ${glyphSize.height}`,
+    });
+    const defs = svg(doc, 'defs');
+    glyph.append(defs);
+    const bbox: Rect = { x: 0, y: 0, width: glyphSize.width, height: glyphSize.height };
+    const paint = paintFor(doc, defs, entry.style, bbox, ids);
+    if (entry.symbol) {
+      glyph.append(symbolEl(doc, entry.symbol, glyphSize.width / 2, glyphSize.height / 2, glyphSize.width, paint));
+    } else {
+      const line = svg(doc, 'rect', { x: 0, y: 0, width: glyphSize.width, height: glyphSize.height, rx: glyphSize.height / 2 });
+      line.style.fill = paint;
+      glyph.append(line);
+    }
+    const label = doc.createElement('span');
+    label.className = 'sb-chart-legend-label';
+    label.textContent = typeof entry.label === 'string' ? entry.label : String(entry.label ?? '');
+    item.append(glyph, label);
+    items.push(item);
+  });
+  return items;
+}

package/src/devEvents.ts

@@ -0,0 +1,35 @@
+/**
+ * Custom Vite websocket events exchanged between the dev-server plugin
+ * (plugins/swift-wasm.ts) and the page (src/main.ts) for hot reload.
+ *
+ * This file is imported by both sides, so it must stay free of DOM and Node
+ * types.
+ */
+
+import 'vite/types/customEvent.d.ts';
+
+export interface BuildStartPayload {
+  /** Products being rebuilt, e.g. `["Counter", "Todos"]`. */
+  apps: string[];
+}
+
+export interface BuildEndPayload {
+  apps: string[];
+  ok: boolean;
+  durationMs: number;
+}
+
+export interface BuildErrorPayload {
+  /** The product whose build failed. */
+  app: string;
+  /** Combined stdout + stderr of `scripts/build-wasm.sh`. */
+  output: string;
+}
+
+declare module 'vite/types/customEvent.d.ts' {
+  interface CustomEventMap {
+    'sb:build-start': BuildStartPayload;
+    'sb:build-end': BuildEndPayload;
+    'sb:build-error': BuildErrorPayload;
+  }
+}

package/src/deviceMode.ts

@@ -0,0 +1,80 @@
+/**
+ * Frame mode vs device mode for the app page.
+ *
+ * - Frame (desktop, tests): the app renders inside the fake iPhone bezel with
+ *   a drawn status bar and the toolbar's theme / Text size controls.
+ * - Device (a real phone): the app fills the viewport, the OS draws the status
+ *   bar, and the layout engine gets the real safe-area insets from
+ *   `env(safe-area-inset-*)`, exposed as `--sb-inset-*` on `:root`.
+ *
+ * `?mode=device` / `?mode=frame` force a mode; otherwise a coarse pointer
+ * means a touch device at any width (Phase 7: a tablet fills the viewport
+ * instead of showing the phone bezel; the old 500 px limit is gone). The
+ * inline script in app/index.html applies the same rule before the first
+ * paint.
+ */
+
+import type { EdgeInsets } from './layout';
+
+export type PageMode = 'frame' | 'device';
+
+export function decidePageMode(
+  search: string = location.search,
+  win: Pick<Window, 'matchMedia'> = window,
+): PageMode {
+  const mode = new URLSearchParams(search).get('mode');
+  if (mode === 'device') return 'device';
+  if (mode === 'frame') return 'frame';
+  const coarse = typeof win.matchMedia === 'function' && win.matchMedia('(pointer: coarse)').matches;
+  return coarse ? 'device' : 'frame';
+}
+
+/** Mark the document so styles.css can switch the chrome. */
+export function applyPageMode(mode: PageMode): void {
+  document.documentElement.dataset['sbMode'] = mode;
+}
+
+/**
+ * The real safe-area insets, read from the `--sb-inset-*` custom properties
+ * (`env(safe-area-inset-*)`, 0 outside standalone / landscape). Values that
+ * do not parse count as 0.
+ */
+export function readViewportInsets(): EdgeInsets {
+  const cs = getComputedStyle(document.documentElement);
+  const read = (name: string): number => {
+    const value = parseFloat(cs.getPropertyValue(name));
+    return Number.isFinite(value) && value > 0 ? value : 0;
+  };
+  return {
+    top: read('--sb-inset-top'),
+    leading: read('--sb-inset-left'),
+    bottom: read('--sb-inset-bottom'),
+    trailing: read('--sb-inset-right'),
+  };
+}
+
+/**
+ * Call `onChange` (debounced) whenever the viewport may have changed size or
+ * insets: window `resize`, `orientationchange` and `visualViewport` resizes.
+ * Returns a function that stops listening.
+ */
+export function watchViewport(onChange: () => void, debounceMs = 100): () => void {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const schedule = (): void => {
+    if (timer !== undefined) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = undefined;
+      onChange();
+    }, debounceMs);
+  };
+  window.addEventListener('resize', schedule);
+  window.addEventListener('orientationchange', schedule);
+  const vv = window.visualViewport;
+  vv?.addEventListener('resize', schedule);
+  return () => {
+    if (timer !== undefined) clearTimeout(timer);
+    window.removeEventListener('resize', schedule);
+    window.removeEventListener('orientationchange', schedule);
+    vv?.removeEventListener('resize', schedule);
+  };
+}

package/src/ghost.ts

@@ -0,0 +1,25 @@
+/**
+ * Visual clones used for exit animations (popped screens, dismissed sheets,
+ * removed elements with a transition) must stay invisible to the renderer,
+ * which looks elements up by `data-sb-id`. Stripping that attribute, however,
+ * also strips the stylesheet's positioning rules keyed on it, which made a
+ * clone's content collapse to flow layout mid-transition. Clones therefore
+ * carry the id under `data-sb-ghost` instead, and the stylesheet applies its
+ * element rules to both attributes.
+ */
+export const GHOST_ATTR = 'data-sb-ghost';
+
+/** Deep-clone `el` for an exit animation, renaming every element id to a ghost id. */
+export function ghostClone(el: HTMLElement): HTMLElement {
+  const clone = el.cloneNode(true) as HTMLElement;
+  const rename = (node: Element): void => {
+    const id = node.getAttribute('data-sb-id');
+    if (id !== null) {
+      node.removeAttribute('data-sb-id');
+      node.setAttribute(GHOST_ATTR, id);
+    }
+  };
+  rename(clone);
+  for (const node of clone.querySelectorAll('[data-sb-id]')) rename(node);
+  return clone;
+}