@swiftbrowser/web 0.3.0 → 0.4.0

package/src/layout/index.ts

@@ -16,7 +16,7 @@
  * | `section`           | `rows` (the inset card), `header`, `footer` (when present) |
  * | list rows           | `row` (the full-width row rect inside the card); `navlink` rows add `label` and `chevron` (20px at the trailing edge); rows with a Phase 6 `badge` style add `badge` (the text's rect at the trailing inset, full row height) |
  * | `scrollview`        | `content` (the content rect at scroll offset 0) |
- * | `list`/`scrollview` | `bottomInset` (Phase 4, only under a tab bar that reaches the screen bottom: the part of the frame the bar covers; the DOM adds its height as scrollable content inset) |
+ * | `list`/`scrollview` | `bottomInset` (Phase 4, only under a tab bar that reaches the screen bottom, or a bottom toolbar or search field reaching its screen's bottom: the part of the frame the bar covers; the DOM adds its height as scrollable content inset), `topInset` / `largeTitle` (the screen's bar and the large title row it runs under: its screen's content, or a vertical one in it touching the bar) |
  * | `tabview`           | `bar` (49 + bottom safe area at the bottom), `item0` … `itemN-1` (equal-width 49px items in the bar), `content` (above the bar) |
  * | `tab`               | `content` (the selected tab's safe content area: below the status bar, above the bar); non-selected tabs are in `hidden` |
  * | `picker`            | segmented: `segment0` … `segmentN-1` (equal widths, 32 high); menu: `label` (leading), `value` (the selected option plus chevron, trailing) |
@@ -74,7 +74,10 @@ export {
   makeFont,
   DYNAMIC_TYPE_SIZES,
   TEXT_STYLE_SIZES,
-  LINE_HEIGHTS,
+  LINE_HEIGHT_RATIO,
+  LEADINGS,
+  leadingFor,
+  textHeight,
   FONT_FAMILIES,
   FONT_WEIGHTS,
   type TextStyle,

package/src/layout/measure.ts

@@ -20,6 +20,8 @@ function canvasFont(font: ResolvedFont): string {
  * is available (Node), it falls back to the monospace estimate.
  */
 export class CanvasTextMeasurer implements TextMeasurer {
+  /** Set by the renderer: measures a `host` element's content in the DOM. */
+  measureHost?: TextMeasurer['measureHost'];
   private context: Canvas2D | null | undefined;
   private readonly cache = new Map<string, number>();
   private readonly fallback = new MonospaceTextMeasurer();

package/src/layout/text.ts

@@ -262,12 +262,15 @@ export function wrapRuns(
   }
 
   const merged = lines.map(mergePieces);
-  const heights = merged.map((line) => {
-    if (line.length === 0) return base.lineHeight;
+  // The first line is a line tall, each further one a leading (the
+  // distance from the line above's baseline).
+  const heights = merged.map((line, index) => {
+    const metric = (font: ResolvedFont): number => (index === 0 ? font.lineHeight : font.leading);
+    if (line.length === 0) return metric(base);
     let height = 0;
     for (const piece of line) {
       const font = (runs[piece.run] as TextRunInput).font;
-      height = Math.max(height, piece.height ?? font.lineHeight, font.lineHeight);
+      height = Math.max(height, piece.height ?? metric(font), metric(font));
     }
     return height;
   });

package/src/layout/types.ts

@@ -62,8 +62,10 @@ export interface ResolvedFont {
   size: number;
   /** CSS numeric weight, 100...900. */
   weight: number;
-  /** Line height in CSS px (an integer). */
+  /** A line's height in CSS px (a multiple of 1/3: a 3x device pixel). */
   lineHeight: number;
+  /** The distance between a paragraph's baselines (the HIG leading); an SF Symbol image is this square. */
+  leading: number;
   /** A CSS `font` shorthand (`weight size/lineHeight family`) usable verbatim. */
   css: string;
   /**
@@ -79,6 +81,12 @@ export interface ResolvedFont {
 export interface TextMeasurer {
   /** Width of one line of text in CSS px when drawn with `font`. */
   measureWidth(text: string, font: ResolvedFont): number;
+  /**
+   * A `host` element's content (src/hostContent.ts, by key) laid out at
+   * `width` CSS px, or at its own ideal width when null: its size. Absent in
+   * headless layouts, where a host measures as a 10×10 placeholder.
+   */
+  measureHost?: ((content: string, width: number | null) => Size) | undefined;
 }
 
 export interface LayoutEnvironment {
@@ -93,6 +101,13 @@ export interface LayoutEnvironment {
    * images then measure as unknown (44×44 placeholders).
    */
   assets?: AssetCatalog;
+  /**
+   * The root's height is its content's, not the screen's: a SwiftUI island
+   * in a page's own layout (@swiftbrowser/react's `SwiftUIView`). A plain
+   * root is proposed the screen width and no height and placed at the top;
+   * navigation and tab roots still fill the screen.
+   */
+  contentHeight?: boolean;
 }
 
 export type TextAlignment = 'leading' | 'center' | 'trailing';

package/src/layout/typography.ts

@@ -4,8 +4,11 @@
  * Point sizes come from Apple's Human Interface Guidelines, "Typography" >
  * "Specifications" > "iOS, iPadOS Dynamic Type sizes" and "Larger
  * accessibility type sizes" (https://developer.apple.com/design/human-interface-guidelines/typography).
- * Line heights for the Large (default) sizes are the iOS values from the same
- * tables; other sizes use round(size * 1.2).
+ * A line is as tall as SwiftUI makes a `Text`: SF Pro's ascender plus
+ * descender (`UIFont.lineHeight`, 1.1934 × the point size), rounded up to a
+ * device pixel on a 3x iPhone (body 17 → 20.33, large title 34 → 40.67;
+ * measured in the iOS 26.2 simulator). The HIG's tables list a taller
+ * leading (body 22): the distance between a paragraph's lines (`LEADINGS`).
  */
 
 import type { DynamicTypeSize, FontFamily, LayoutEnvironment, ResolvedFont } from './types';
@@ -60,8 +63,13 @@ export const TEXT_STYLE_SIZES: Record<TextStyle, readonly number[]> = {
   caption2: [11, 11, 11, 11, 13, 15, 17, 20, 24, 29, 34, 40],
 };
 
-/** iOS line heights for the standard (Large) point sizes. */
-export const LINE_HEIGHTS: Readonly<Record<number, number>> = {
+/**
+ * The HIG's leading for the standard (Large) point sizes: the distance
+ * between the baselines of a paragraph's lines, which SwiftUI keeps (a
+ * multi-line body `Text` is 20.33 + 22 per further line); other sizes use
+ * round(size * 1.2). An SF Symbol image takes a square of it.
+ */
+export const LEADINGS: Readonly<Record<number, number>> = {
   34: 41,
   28: 34,
   22: 28,
@@ -120,10 +128,22 @@ export function textStyleSize(style: TextStyle, size: DynamicTypeSize): number {
   return row[sizeCategoryIndex(size)] ?? row[LARGE_INDEX] ?? 17;
 }
 
-/** Line height for a point size: the iOS value for standard sizes, else round(size * 1.2). */
+/** SF Pro's ascender plus descender per point (1950 + 494 of 2048 units per em). */
+export const LINE_HEIGHT_RATIO = 2444 / 2048;
+
+/** A line's height at a point size: `UIFont.lineHeight`, rounded up to a 3x pixel. */
 export function lineHeightFor(size: number): number {
-  const known = LINE_HEIGHTS[size];
-  return known ?? Math.round(size * 1.2);
+  return Math.ceil(size * LINE_HEIGHT_RATIO * 3 - 1e-6) / 3;
+}
+
+/** The distance between a paragraph's baselines at a point size. */
+export function leadingFor(size: number): number {
+  return LEADINGS[size] ?? Math.round(size * 1.2);
+}
+
+/** The height of `lines` lines of text in `font`: the first line, then its leading per further line. */
+export function textHeight(lines: number, font: ResolvedFont): number {
+  return lines > 0 ? font.lineHeight + (lines - 1) * font.leading : 0;
 }
 
 function formatPx(value: number): string {
@@ -138,14 +158,14 @@ export function makeFont(
   modifiers: { weightModifier?: number | undefined; familyModifier?: FontFamily | undefined } = {},
 ): ResolvedFont {
   const lineHeight = lineHeightFor(size);
-  const css = `${weight} ${formatPx(size)}/${lineHeight}px ${FONT_FAMILIES[family]}`;
-  const font: ResolvedFont = { family, size, weight, lineHeight, css };
+  const css = `${weight} ${formatPx(size)}/${formatPx(lineHeight)} ${FONT_FAMILIES[family]}`;
+  const font: ResolvedFont = { family, size, weight, lineHeight, leading: leadingFor(size), css };
   if (modifiers.weightModifier !== undefined) font.weightModifier = modifiers.weightModifier;
   if (modifiers.familyModifier !== undefined) font.familyModifier = modifiers.familyModifier;
   return font;
 }
 
-/** Body text for the current `dynamicTypeSize` (17/22 at Large). */
+/** Body text for the current `dynamicTypeSize` (17/20.33 at Large). */
 export function defaultFont(env: LayoutEnvironment): ResolvedFont {
   return makeFont('system', textStyleSize('body', env.dynamicTypeSize), 400);
 }

package/src/layoutDom.ts

@@ -37,7 +37,8 @@ import type { LayoutEnvironment, LayoutNode, LayoutResult, Rect, ResolvedFont, T
 import { applyChartChrome } from './chartDom';
 import { bitmapLaidOut } from './bitmaps';
 import { drawRichText } from './richText';
-import { bindLargeTitle } from './largeTitle';
+import { bindScrollUnderBar, largeTitleOf, largeTitleScrolls } from './largeTitle';
+import { bindScrollEdgeBottom } from './scrollEdge';
 
 export interface LayoutDomContext {
   root: HTMLElement;
@@ -236,6 +237,27 @@ function positionBox(el: HTMLElement, box: Rect, origin: { x: number; y: number
 }
 
 /** Position a chrome node inside its element: `rect` is in screen coordinates. */
+/**
+ * An edit-mode control fades in when it first appears (the list started
+ * editing), marked `data-sb-appear` for the animation's duration. A control
+ * that is laid out again while shown, or whose row is moved in the DOM (a
+ * reorder re-inserts the row, which would restart a CSS animation on it),
+ * is not marked and stays put.
+ */
+function placeEditControl(node: HTMLElement | null, rect: Rect | undefined, origin: Rect): void {
+  if (!node) return;
+  const wasHidden = node.hidden;
+  placeChrome(node, rect, origin);
+  if (wasHidden && !node.hidden) {
+    node.dataset['sbAppear'] = '';
+    const settle = (): void => {
+      delete node.dataset['sbAppear'];
+    };
+    node.addEventListener('animationend', settle, { once: true });
+    node.addEventListener('animationcancel', settle, { once: true });
+  }
+}
+
 function placeChrome(node: HTMLElement | null, rect: Rect | undefined, origin: Rect): void {
   if (!node) return;
   if (!rect) {
@@ -261,16 +283,21 @@ function positionSheetCard(sheet: HTMLElement, frame: Rect): void {
   s.height = `${frame.height}px`;
 }
 
-function setFont(el: HTMLElement, font: ResolvedFont | undefined): void {
+/**
+ * `lines` > 1: a paragraph, whose lines are a leading apart (the engine makes
+ * it the first line's height plus a leading per further line).
+ */
+function setFont(el: HTMLElement, font: ResolvedFont | undefined, lines = 1): void {
   if (!font) return;
-  if (el.style.font !== font.css) el.style.font = font.css;
+  const css = lines > 1 ? font.css.replace(/\/[\d.]+px /, `/${Math.round(font.leading * 100) / 100}px `) : font.css;
+  if (el.style.font !== css) el.style.font = css;
 }
 
 const TEXT_ALIGN: Record<string, string> = { leading: 'left', center: 'center', trailing: 'right' };
 
 /** Render the engine's exact lines into a text node (`white-space: pre` keeps them). */
 function setTextLayout(el: HTMLElement, layout: TextLayout): void {
-  setFont(el, layout.font);
+  setFont(el, layout.font, layout.lines.length);
   const align = TEXT_ALIGN[layout.alignment] ?? 'left';
   if (el.style.textAlign !== align) el.style.textAlign = align;
   if (layout.rich && el.dataset['sbRich'] !== undefined) {
@@ -373,8 +400,9 @@ function applyChrome(
     }
     case 'textfield':
     case 'texteditor':
-      // A vertical text field draws in the font its lines were measured in.
-      setFont(el, result.fonts.get(node.id));
+      // A vertical text field draws in the font its lines were measured in,
+      // a leading apart.
+      setFont(el, result.fonts.get(node.id), el instanceof HTMLTextAreaElement ? 2 : 1);
       padIntoFrame(el, box, frame);
       return;
     // Phase 8 controls: their chrome sits at the engine's rects inside the element's box.
@@ -463,7 +491,7 @@ function applyChrome(
       if (header && texts?.['header']) setTextLayout(header, texts['header']);
       if (footer && texts?.['footer']) {
         // The prop text in the engine's font and rect, wrapped there.
-        setFont(footer, texts['footer'].font);
+        setFont(footer, texts['footer'].font, texts['footer'].lines.length);
         footer.style.textAlign = 'left';
         footer.style.whiteSpace = 'pre-wrap';
         const original = typeof node.props['footer'] === 'string' ? node.props['footer'] : texts['footer'].lines.join('\n');
@@ -479,7 +507,8 @@ function applyChrome(
         // Extra scrollable space at the end (the engine's frames are unchanged).
         content.style.height = `${size.height + bottomInset}px`;
       }
-      bindLargeTitle(el, chrome?.['largeTitle'] !== undefined);
+      bindScrollUnderBar(el, frame, chrome?.['topInset'], chrome?.['largeTitle']);
+      bindScrollEdgeBottom(el, chrome?.['bottomInset']);
       return;
     }
     case 'scrollview': {
@@ -494,24 +523,33 @@ function applyChrome(
         s.marginLeft = `${rect ? rect.x - frame.x : 0}px`;
         s.marginTop = `${rect ? rect.y - frame.y : 0}px`;
       }
-      bindLargeTitle(el, chrome?.['largeTitle'] !== undefined);
+      bindScrollUnderBar(el, frame, chrome?.['topInset'], chrome?.['largeTitle']);
+      bindScrollEdgeBottom(el, String(node.props['axes'] ?? 'vertical') === 'horizontal' ? undefined : chrome?.['bottomInset']);
       return;
     }
     case 'navscreen': {
       const bar = el.querySelector<HTMLElement>(':scope > .sb-navbar');
-      const largeTitle = el.querySelector<HTMLElement>(':scope > .sb-navscreen-body > .sb-navbar-large-title');
+      const largeTitle = largeTitleOf(el);
       const inlineTitle = el.querySelector<HTMLElement>(':scope > .sb-navbar > .sb-navbar-title');
       const texts = result.chromeText.get(node.id);
       const barRect = chrome?.['bar'];
       if (bar && barRect) {
         placeChrome(bar, barRect, frame);
-        // The 44px bar row sits under the status bar portion of the rect.
-        bar.style.paddingTop = `${Math.max(0, barRect.height - NAV_BAR_HEIGHT)}px`;
+        // The 44px bar row sits under the status bar portion of the rect
+        // (iOS 26: an inline bar keeps 10 more below it).
+        const row = chrome?.['barRow'];
+        const top = row ? row.y - barRect.y : Math.max(0, barRect.height - NAV_BAR_HEIGHT);
+        const bottom = row ? Math.max(0, barRect.y + barRect.height - (row.y + row.height)) : 0;
+        bar.style.paddingTop = `${top}px`;
+        bar.style.paddingBottom = `${bottom}px`;
       }
       const largeRect = chrome?.['largeTitle'];
       if (largeTitle) {
         if (largeRect) {
-          placeChrome(largeTitle, largeRect, frame);
+          // A title that scrolls with the screen's scroll view is placed by
+          // it (src/largeTitle.ts).
+          if (largeTitleScrolls(el, largeTitle)) largeTitle.hidden = false;
+          else placeChrome(largeTitle, largeRect, frame);
           if (texts?.['largeTitle']) {
             setFont(largeTitle, texts['largeTitle'].font);
             const line = texts['largeTitle'].lines.join('\n');
@@ -539,6 +577,10 @@ function applyChrome(
       if (back && backLabel && backRect && texts?.['back']) {
         const text = texts['back'].lines[0] ?? '';
         back.style.maxWidth = `${backRect.width}px`;
+        // The bar pads its row 16 (styles.css); a split view's sidebar
+        // toggle can push the back button further in (chrome.back).
+        const indent = barRect ? Math.max(0, backRect.x - barRect.x - 16) : 0;
+        back.style.marginLeft = indent > 0 ? `${indent}px` : '';
         backLabel.dataset['sbLayoutLabel'] = text;
         if (backLabel.textContent !== text) backLabel.textContent = text;
         setFont(back, texts['back'].font);
@@ -563,9 +605,15 @@ function applyChrome(
       items.forEach((item, i) => placeChrome(item, chrome?.[`item${i}`], barRect));
       return;
     }
+    case 'inspector': {
+      setFlag(el, 'sbPresented', node.props['presented'] === true ? '' : null);
+      return;
+    }
     case 'navsplit': {
-      // Phase 7: the hairline between the two columns.
+      // Phase 7: the hairline between the two columns, and the sidebar toggle.
       placeChrome(el.querySelector<HTMLElement>(':scope > .sb-navsplit-separator'), chrome?.['separator'], box);
+      placeChrome(el.querySelector<HTMLElement>(':scope > .sb-navsplit-toggle'), chrome?.['toggle'], box);
+      setFlag(el, 'sbSidebarHidden', node.props['sidebarVisible'] === false ? '' : null);
       return;
     }
     case 'gauge': {
@@ -583,8 +631,10 @@ function applyChrome(
       return;
     case 'listrow':
       // Phase 8: the edit-mode control (selection circle / minus) at the
-      // engine's `editControl` rect; hidden when the list is not editing.
-      placeChrome(el.querySelector<HTMLElement>(':scope > .sb-listrow-control'), chrome?.['editControl'], box);
+      // engine's `editControl` rect and the reorder grip at `reorderControl`;
+      // hidden when the list is not editing.
+      placeEditControl(el.querySelector<HTMLElement>(':scope > .sb-listrow-control'), chrome?.['editControl'], box);
+      placeEditControl(el.querySelector<HTMLElement>(':scope > .sb-swipe-content > .sb-listrow-grip'), chrome?.['reorderControl'], box);
       return;
     case 'picker': {
       setFont(el, result.fonts.get(node.id));

package/src/pointerEffects.ts

@@ -0,0 +1,182 @@
+/**
+ * What a page with a mouse adds to a phone's UI: `hover` events (`.onHover`),
+ * tooltips (`.help`), cursors (`.pointerStyle`), and SF Symbols' effects
+ * (`.symbolEffect`) drawn with CSS. The Swift shim draws an iPhone and sends
+ * none of these; producers in the page (@swiftbrowser/react) do.
+ */
+
+import type { ElementId, Style, SymbolEffectStyle } from './protocol';
+
+// ---------------------------------------------------------------------------
+// Hover
+// ---------------------------------------------------------------------------
+
+const HOVER_ATTR = 'sbHover';
+
+/** Sends `hover` as a mouse enters and leaves the boxes marked `data-sb-hover` under `root`. */
+export class HoverTracker {
+  private readonly hovered = new Set<HTMLElement>();
+
+  constructor(
+    private readonly root: HTMLElement,
+    private readonly send: (id: ElementId, value: boolean) => void,
+  ) {
+    root.addEventListener('pointerover', this.onOver);
+    root.addEventListener('pointerout', this.onOut);
+  }
+
+  dispose(): void {
+    this.root.removeEventListener('pointerover', this.onOver);
+    this.root.removeEventListener('pointerout', this.onOut);
+    this.hovered.clear();
+  }
+
+  private readonly onOver = (event: PointerEvent): void => {
+    if (event.pointerType === 'touch') return;
+    for (let el = event.target as HTMLElement | null; el && el !== this.root; el = el.parentElement) {
+      if (el.dataset[HOVER_ATTR] === undefined || this.hovered.has(el)) continue;
+      this.hovered.add(el);
+      this.report(el, true);
+    }
+  };
+
+  private readonly onOut = (event: PointerEvent): void => {
+    if (event.pointerType === 'touch') return;
+    const next = event.relatedTarget as Node | null;
+    for (const el of [...this.hovered]) {
+      if (next && el.contains(next)) continue;
+      this.hovered.delete(el);
+      this.report(el, false);
+    }
+  };
+
+  private report(el: HTMLElement, value: boolean): void {
+    const id = Number(el.dataset['sbId']);
+    if (Number.isInteger(id) && el.isConnected) this.send(id, value);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Style fields
+// ---------------------------------------------------------------------------
+
+/** One run of each effect at speed 1 (seconds) and its keyframes on the CSS `scale`, `rotate`, `translate` and `opacity` properties. */
+const EFFECTS: Record<string, { duration: number; frames: Keyframe[] }> = {
+  bounce: {
+    duration: 0.5,
+    frames: [
+      { scale: '1', translate: '0 0', offset: 0 },
+      { scale: '1.18', translate: '0 -12%', offset: 0.35 },
+      { scale: '0.94', translate: '0 0', offset: 0.7 },
+      { scale: '1', translate: '0 0', offset: 1 },
+    ],
+  },
+  pulse: { duration: 1.2, frames: [{ opacity: '1' }, { opacity: '0.35' }, { opacity: '1' }] },
+  variableColor: { duration: 1.2, frames: [{ opacity: '1' }, { opacity: '0.5', offset: 0.33 }, { opacity: '0.75', offset: 0.66 }, { opacity: '1' }] },
+  rotate: { duration: 1, frames: [{ rotate: '0deg' }, { rotate: '360deg' }] },
+  wiggle: {
+    duration: 0.6,
+    frames: [{ rotate: '0deg' }, { rotate: '-14deg', offset: 0.25 }, { rotate: '14deg', offset: 0.6 }, { rotate: '0deg' }],
+  },
+  breathe: { duration: 2, frames: [{ scale: '1', opacity: '1' }, { scale: '1.1', opacity: '0.7' }, { scale: '1', opacity: '1' }] },
+};
+
+const playing = new WeakMap<HTMLElement, { key: string; animation: globalThis.Animation }>();
+const triggers = new WeakMap<HTMLElement, number>();
+
+/** Apply the pointer and effect fields of a `styled` element's style (called on create and update). */
+export function applyPointerAndEffects(el: HTMLElement, style: Style): void {
+  if (style.hover) el.dataset[HOVER_ATTR] = '';
+  if (style.help) {
+    el.title = style.help;
+    el.dataset['sbHelp'] = '';
+  } else if (el.hasAttribute('title') && el.classList.contains('sb-styled')) {
+    el.removeAttribute('title');
+  }
+  if (style.pointerStyle) el.style.cursor = style.pointerStyle;
+  applySymbolEffect(el, style.symbolEffect);
+  if (style.matchedGeometry) el.dataset['sbMatched'] = style.matchedGeometry;
+  if (style.contentTransition) {
+    el.dataset['sbContentTransition'] = style.contentTransition.kind;
+    const { countsDown } = style.contentTransition;
+    if (countsDown === undefined) delete el.dataset['sbCountsDown'];
+    else el.dataset['sbCountsDown'] = String(countsDown);
+  }
+}
+
+function applySymbolEffect(el: HTMLElement, effect: SymbolEffectStyle | undefined): void {
+  const s = el.style;
+  if (!effect) {
+    stopEffect(el);
+    return;
+  }
+  el.dataset['sbSymbolEffect'] = effect.effect;
+  // State effects: a look kept while the style carries them.
+  if (effect.effect === 'scale') {
+    s.transition = 'scale 0.25s';
+    s.scale = effect.direction === 'down' ? '0.85' : '1.2';
+    return;
+  }
+  if (effect.effect === 'appear' || effect.effect === 'disappear') {
+    s.transition = 'opacity 0.25s, scale 0.25s';
+    const shown = effect.effect === 'appear';
+    s.opacity = shown ? '1' : '0';
+    s.scale = shown ? '1' : '0.6';
+    return;
+  }
+  const spec = EFFECTS[effect.effect];
+  if (!spec || typeof el.animate !== 'function') return;
+  const duration = (spec.duration / Math.max(effect.speed ?? 1, 0.01)) * 1000;
+  const repeat = effect.repeat === 'forever' ? Infinity : Math.max(1, effect.repeat ?? 1);
+  if (effect.trigger !== undefined) {
+    // A discrete effect plays once per new trigger (never for the first value).
+    const last = triggers.get(el);
+    triggers.set(el, effect.trigger);
+    if (last === undefined || last === effect.trigger) return;
+    playing.get(el)?.animation.cancel();
+    playing.set(el, { key: `once:${effect.trigger}`, animation: el.animate(spec.frames, { duration, iterations: repeat, easing: 'ease-in-out' }) });
+    return;
+  }
+  // An indefinite effect keeps running across updates that leave it alone.
+  const key = `${effect.effect}:${duration}:${repeat === Infinity ? 'forever' : repeat}`;
+  const current = playing.get(el);
+  if (current && current.key === key && current.animation.playState !== 'finished') return;
+  current?.animation.cancel();
+  const iterations = effect.repeat === undefined ? Infinity : repeat;
+  playing.set(el, { key, animation: el.animate(spec.frames, { duration, iterations, easing: 'ease-in-out' }) });
+}
+
+function stopEffect(el: HTMLElement): void {
+  const current = playing.get(el);
+  if (current && !current.key.startsWith('once:')) {
+    current.animation.cancel();
+    playing.delete(el);
+  }
+  triggers.delete(el);
+}
+
+// ---------------------------------------------------------------------------
+// Geometry readers that report their frame
+// ---------------------------------------------------------------------------
+
+export interface SafeAreaInsets {
+  top: number;
+  leading: number;
+  bottom: number;
+  trailing: number;
+}
+
+/** How far the device's safe area reaches into a box at `rect` in a root of `size`. */
+export function safeAreaOverlap(
+  rect: { x: number; y: number; width: number; height: number },
+  size: { width: number; height: number },
+  safeArea: SafeAreaInsets,
+): SafeAreaInsets {
+  const clamp = (value: number, max: number): number => Math.round(Math.min(Math.max(value, 0), max));
+  return {
+    top: clamp(safeArea.top - rect.y, rect.height),
+    bottom: clamp(rect.y + rect.height - (size.height - safeArea.bottom), rect.height),
+    leading: clamp(safeArea.leading - rect.x, rect.width),
+    trailing: clamp(rect.x + rect.width - (size.width - safeArea.trailing), rect.width),
+  };
+}