@swiftbrowser/web 0.1.0

package/src/interaction.ts

@@ -0,0 +1,1113 @@
+/**
+ * Phase 8 pointer interaction (docs/ops-protocol.md, "Phase 8: interaction").
+ *
+ * One `pointerdown` on the screen starts a *session*; the session lists, in
+ * priority order, every behaviour that could own this pointer:
+ *
+ * 1. swipe back (a pointer down within 24 px of a pushed `navscreen`'s
+ *    leading edge), like the iOS screen-edge pan gesture it outranks all;
+ * 2. the wrappers between the target and the root, innermost first: a
+ *    `gesture` (drag, long press), a `contextmenu` (long press) and a swipe
+ *    row (`swipeactions`, or a deletable `listrow` without one);
+ * 3. the sheet card (drag down to dismiss);
+ * 4. pull to refresh on a `refreshable` scroller at its top.
+ *
+ * Nothing owns the pointer at first. On each move the candidates are asked in
+ * order whether the motion so far is theirs (swipe back: rightwards; a drag
+ * gesture: `minimumDistance` in any direction; a swipe row: horizontal; a
+ * sheet or refresh: downwards). The first to say yes *claims* the pointer:
+ * the rest are dropped, the pointer is captured and every further move goes
+ * to the owner until the pointer lifts or the browser cancels it (a native
+ * scroll started: `pointercancel`). Long presses run on a timer from the
+ * pointer down and win only if nothing moved 10 px; a long press or any
+ * claimed drag swallows the click that follows. Taps that claim nothing
+ * reach the renderer's click handler untouched, so controls inside gestures
+ * and rows keep working.
+ *
+ * Horizontal wheel scrolling slides swipe rows and vertical wheel at the
+ * top of a `refreshable` scroller pulls to refresh; touch moves are read
+ * directly for pull to refresh (the browser cancels the pointer once it
+ * scrolls the list).
+ */
+
+import type { LayoutNode } from './layout';
+import { symbolOf, textOf, tintOf, unwrapStyledNode } from './nodeQueries';
+import type { DragEvent, ElementId, RendererEvent } from './protocol';
+import { colorToCSS } from './styles';
+import {
+  SWIPE_ACTION_WIDTH,
+  SWIPE_FULL_EXTRA,
+  SWIPE_START_DISTANCE,
+  clampSwipeOffset,
+  settleSwipe,
+  swipeActionsWidth,
+  swipeEdgeOf,
+  swipeRestOffset,
+  velocityFrom,
+  type SwipeEdge,
+  type SwipeSpec,
+} from './swipe';
+import { renderSymbol } from './symbols';
+
+/** Dragging a sheet down further than this dismisses it (sends a `tap`). */
+export const SHEET_DISMISS_DRAG = 100;
+/** A pointer down this close to a pushed screen's leading edge may swipe back. */
+export const SWIPE_BACK_EDGE = 24;
+/** Releasing a swipe back faster than this (points per second) pops regardless of distance. */
+export const SWIPE_BACK_VELOCITY = 500;
+/** A pull past this many points at the top of a `refreshable` scroller sends `refresh`. */
+export const REFRESH_PULL = 60;
+/** Height of the spinner row shown while `refreshing`. */
+export const REFRESH_ROW = 40;
+/** Default `minimumDuration` of a long press, and the context menu's. */
+export const LONG_PRESS_MS = 500;
+/** Moving this far cancels a long press. */
+const LONG_PRESS_SLOP = 10;
+/** Default `minimumDistance` of a drag gesture. */
+const DRAG_MIN_DISTANCE = 10;
+/** A sheet drag, a swipe back and a pull start after this much motion. */
+const PAN_SLOP = 8;
+/** Duration of the slide a swipe row or a swipe back settles with; keep in sync with styles.css. */
+const SETTLE_MS = 300;
+/** Time Swift gets to remove a swiped-back screen before it snaps back. */
+const SWIPE_BACK_TIMEOUT_MS = 700;
+/** A wheel sequence ends after this much silence. */
+const WHEEL_IDLE_MS = 150;
+
+const ID_ATTR = 'sbId';
+
+/** What the controller needs from the renderer. */
+export interface InteractionHost {
+  readonly root: HTMLElement;
+  send(event: RendererEvent): void;
+  nodeOf(id: ElementId): LayoutNode | undefined;
+  /** Open the popover of a `contextmenu` element anchored to it. */
+  openContextMenu(anchor: HTMLElement, id: ElementId): void;
+  /** Whether the popover of element `id` is open. */
+  isMenuOpen(id: ElementId): boolean;
+  closeMenu(): void;
+}
+
+interface Sample {
+  t: number;
+  x: number;
+  y: number;
+}
+
+/** One swipe action button, from the `swipeactions` children or a deletable row's implied Delete. */
+interface ActionSpec {
+  id: ElementId;
+  title: string;
+  symbol: string | null;
+  destructive: boolean;
+  tint: string | null;
+  event: 'tap' | 'delete';
+}
+
+/** A row whose content slides to reveal actions. */
+interface SwipeHost {
+  el: HTMLElement;
+  id: ElementId;
+  spec: SwipeSpec;
+  actions: Record<SwipeEdge, ActionSpec[]>;
+}
+
+type Candidate =
+  | { kind: 'swipeback'; screen: HTMLElement; below: HTMLElement | null; id: ElementId; width: number }
+  | {
+      kind: 'gesture';
+      el: HTMLElement;
+      id: ElementId;
+      drag: boolean;
+      longPress: boolean;
+      minDistance: number;
+      minDuration: number;
+    }
+  | { kind: 'contextmenu'; el: HTMLElement; id: ElementId }
+  | { kind: 'swipe'; host: SwipeHost }
+  | { kind: 'sheet'; sheet: HTMLElement; card: HTMLElement; id: ElementId }
+  | { kind: 'refresh'; scroller: HTMLElement; id: ElementId };
+
+interface Session {
+  pointerId: number;
+  startX: number;
+  startY: number;
+  x: number;
+  y: number;
+  samples: Sample[];
+  candidates: Candidate[];
+  claimed: Candidate | null;
+  /** A long press fired: the session ignores further motion. */
+  done: boolean;
+  suppressClick: boolean;
+  longPressTimer: number | null;
+  /** The pointer went down on a pushed screen's edge strip (touch): a plain tap is forwarded. */
+  edgeStrip: HTMLElement | null;
+  // gesture drag
+  gestureRect: DOMRect | null;
+  pendingDrag: DragEvent | null;
+  raf: number | null;
+  // swipe row
+  swipeStart: number;
+  swipeOffset: number;
+  // sheet / refresh
+  dy: number;
+}
+
+interface OpenSwipe {
+  host: SwipeHost;
+  offset: number;
+}
+
+interface SwipeBackState {
+  screen: HTMLElement;
+  below: HTMLElement | null;
+  /** Set once released past the threshold: the `tap` went out, the `remove` is awaited. */
+  completing: boolean;
+  timer: number | null;
+}
+
+function round2(v: number): number {
+  return Math.round(v * 100) / 100;
+}
+
+function clamp01(v: number): number {
+  return Math.max(0, Math.min(1, v));
+}
+
+export class InteractionController {
+  private session: Session | null = null;
+  private openSwipe: OpenSwipe | null = null;
+  private swipeBack: SwipeBackState | null = null;
+  /** Wheel-driven swipe of a row: the host, its live offset and the idle timer that settles it. */
+  private wheelSwipe: { host: SwipeHost; offset: number; timer: number } | null = null;
+  /** Wheel-driven pull at the top of a refreshable scroller. */
+  private wheelPull: { scroller: HTMLElement; pulled: number; sent: boolean; timer: number } | null = null;
+  /** Touch-driven pull (the browser cancels the pointer once the list scrolls). */
+  private touchPull: { scroller: HTMLElement; id: ElementId; startY: number; sent: boolean } | null = null;
+
+  constructor(private readonly host: InteractionHost) {
+    const root = host.root;
+    root.addEventListener('pointerdown', this.onPointerDown);
+    root.addEventListener('selectstart', this.onSelectStart);
+    root.addEventListener('contextmenu', this.onContextMenu);
+    root.addEventListener('wheel', this.onWheel, { passive: false });
+    root.addEventListener('scroll', this.onScroll, true);
+    root.addEventListener('touchstart', this.onTouchStart, { passive: true });
+    root.addEventListener('touchmove', this.onTouchMove, { passive: true });
+    root.addEventListener('touchend', this.onTouchEnd, { passive: true });
+    root.addEventListener('touchcancel', this.onTouchEnd, { passive: true });
+    document.addEventListener('pointerdown', this.onDocumentPointerDown, true);
+  }
+
+  dispose(): void {
+    const root = this.host.root;
+    root.removeEventListener('pointerdown', this.onPointerDown);
+    root.removeEventListener('selectstart', this.onSelectStart);
+    root.removeEventListener('contextmenu', this.onContextMenu);
+    root.removeEventListener('wheel', this.onWheel);
+    root.removeEventListener('scroll', this.onScroll, true);
+    root.removeEventListener('touchstart', this.onTouchStart);
+    root.removeEventListener('touchmove', this.onTouchMove);
+    root.removeEventListener('touchend', this.onTouchEnd);
+    root.removeEventListener('touchcancel', this.onTouchEnd);
+    document.removeEventListener('pointerdown', this.onDocumentPointerDown, true);
+    this.detachWindow();
+    this.session = null;
+  }
+
+  // -------------------------------------------------------------------------
+  // Clicks the renderer delegates (its `onClick` picks the innermost target)
+  // -------------------------------------------------------------------------
+
+  /** Handle a click on a swipe action or an edit-mode row control; false when `target` is neither. */
+  handleClick(target: HTMLElement): boolean {
+    if (target.classList.contains('sb-swipe-action')) {
+      const id = Number(target.dataset['sbTarget']);
+      const action = target.dataset['sbAction'] === 'delete' ? 'delete' : 'tap';
+      const rowEl = target.closest<HTMLElement>('.sb-swipeactions, .sb-listrow');
+      if (rowEl) this.closeRow(rowEl);
+      if (Number.isInteger(id)) this.host.send({ type: action, id });
+      return true;
+    }
+    if (target.classList.contains('sb-listrow-control')) {
+      const row = target.closest<HTMLElement>('.sb-listrow');
+      const id = Number(row?.dataset[ID_ATTR]);
+      if (!row || !Number.isInteger(id)) return true;
+      if (row.hasAttribute('data-sb-selectable')) {
+        this.host.send({ type: 'tap', id });
+      } else if (row.hasAttribute('data-sb-deletable')) {
+        // The minus reveals the Delete button; tapping that sends `delete`.
+        const host = this.swipeHostFor(row);
+        if (host) this.revealEdge(host, 'trailing');
+      }
+      return true;
+    }
+    return false;
+  }
+
+  // -------------------------------------------------------------------------
+  // Pointer sessions
+  // -------------------------------------------------------------------------
+
+  private readonly onPointerDown = (event: PointerEvent): void => {
+    if (this.session || !event.isPrimary || (event.pointerType === 'mouse' && event.button !== 0)) return;
+    const target = event.target as HTMLElement | null;
+    if (!target) return;
+    // Pointer downs in a text field select text, never gesture; a slider
+    // (Phase 8 controls) owns its own pointer drag in the renderer.
+    const inField = target.closest('input, textarea, [contenteditable], .sb-slider') !== null;
+    const candidates = inField ? [] : this.collectCandidates(target, event);
+    const edgeStrip = target.classList.contains('sb-navscreen-edge') ? target : null;
+    if (candidates.length === 0 && !edgeStrip) return;
+    // A mouse drag would otherwise select the row text, and a later press on
+    // that selection would start a native drag of it (which cancels the
+    // pointer). No selection is ever wanted where a gesture may start.
+    clearSelectionIn(this.host.root);
+    this.host.root.dataset['sbPointerSession'] = '';
+    const session: Session = {
+      pointerId: event.pointerId,
+      startX: event.clientX,
+      startY: event.clientY,
+      x: event.clientX,
+      y: event.clientY,
+      samples: [{ t: event.timeStamp, x: event.clientX, y: event.clientY }],
+      candidates,
+      claimed: null,
+      done: false,
+      suppressClick: false,
+      longPressTimer: null,
+      edgeStrip,
+      gestureRect: null,
+      pendingDrag: null,
+      raf: null,
+      swipeStart: 0,
+      swipeOffset: 0,
+      dy: 0,
+    };
+    this.session = session;
+    window.addEventListener('pointermove', this.onPointerMove);
+    window.addEventListener('pointerup', this.onPointerUp);
+    window.addEventListener('pointercancel', this.onPointerCancel);
+    // The innermost long-press wrapper arms its timer right away.
+    const presser = candidates.find((c) => (c.kind === 'gesture' && c.longPress) || c.kind === 'contextmenu');
+    if (presser) {
+      const duration = presser.kind === 'gesture' ? presser.minDuration : LONG_PRESS_MS;
+      session.longPressTimer = window.setTimeout(() => this.fireLongPress(session, presser), duration);
+    }
+    // An immediate drag gesture (`minimumDistance: 0`) owns the pointer from the start.
+    const immediate = candidates.find((c) => c.kind === 'gesture' && c.drag && c.minDistance <= 0);
+    if (immediate && candidates[0] === immediate) this.claim(session, immediate, event);
+  };
+
+  private readonly onPointerMove = (event: PointerEvent): void => {
+    const session = this.session;
+    if (!session || event.pointerId !== session.pointerId) return;
+    session.x = event.clientX;
+    session.y = event.clientY;
+    session.samples.push({ t: event.timeStamp, x: event.clientX, y: event.clientY });
+    if (session.samples.length > 12) session.samples.shift();
+    if (session.done) return;
+    const dx = session.x - session.startX;
+    const dy = session.y - session.startY;
+    const distance = Math.hypot(dx, dy);
+    if (session.longPressTimer !== null && distance > LONG_PRESS_SLOP) {
+      window.clearTimeout(session.longPressTimer);
+      session.longPressTimer = null;
+    }
+    if (!session.claimed) {
+      const owner = session.candidates.find((c) => this.wants(c, dx, dy, distance));
+      if (!owner) return;
+      this.claim(session, owner, event);
+    }
+    if (session.claimed) this.move(session, session.claimed, dx, dy);
+  };
+
+  private readonly onPointerUp = (event: PointerEvent): void => {
+    const session = this.session;
+    if (!session || event.pointerId !== session.pointerId) return;
+    this.finishSession(session, false);
+  };
+
+  private readonly onPointerCancel = (event: PointerEvent): void => {
+    const session = this.session;
+    if (!session || event.pointerId !== session.pointerId) return;
+    this.finishSession(session, true);
+  };
+
+  /** While a session runs nothing in the screen may start a text selection. */
+  private readonly onSelectStart = (event: Event): void => {
+    if (this.session) event.preventDefault();
+  };
+
+  private finishSession(session: Session, cancelled: boolean): void {
+    this.session = null;
+    this.detachWindow();
+    delete this.host.root.dataset['sbPointerSession'];
+    if (session.longPressTimer !== null) window.clearTimeout(session.longPressTimer);
+    if (session.raf !== null) cancelAnimationFrame(session.raf);
+    const dx = session.x - session.startX;
+    const dy = session.y - session.startY;
+    const velocity = velocityFrom(session.samples);
+    if (session.claimed) {
+      if (cancelled) this.cancel(session, session.claimed, dx, dy);
+      else this.end(session, session.claimed, dx, dy, velocity);
+      session.suppressClick = true;
+    } else if (!cancelled && session.edgeStrip && Math.hypot(dx, dy) < LONG_PRESS_SLOP && !session.done) {
+      // A plain tap on the (touch-only) edge strip goes to whatever is under it.
+      this.forwardTap(session.edgeStrip, session.x, session.y);
+      return;
+    }
+    if (session.suppressClick) suppressNextClick();
+  }
+
+  private detachWindow(): void {
+    window.removeEventListener('pointermove', this.onPointerMove);
+    window.removeEventListener('pointerup', this.onPointerUp);
+    window.removeEventListener('pointercancel', this.onPointerCancel);
+  }
+
+  /** Every behaviour that could own a pointer that went down on `target`, in priority order. */
+  private collectCandidates(target: HTMLElement, event: PointerEvent): Candidate[] {
+    const out: Candidate[] = [];
+    const screen = target.closest<HTMLElement>('.sb-navscreen');
+    if (screen && screen.dataset['sbNavPosition'] === 'top' && Number(screen.dataset['sbDepth'] ?? '0') > 0 && !this.swipeBack) {
+      const rect = screen.getBoundingClientRect();
+      const id = Number(screen.dataset[ID_ATTR]);
+      if (event.clientX - rect.left <= SWIPE_BACK_EDGE && Number.isInteger(id)) {
+        const below = screen.previousElementSibling as HTMLElement | null;
+        out.push({ kind: 'swipeback', screen, id, width: rect.width || screen.offsetWidth, below: below?.classList.contains('sb-navscreen') ? below : null });
+      }
+    }
+    for (let el: HTMLElement | null = target; el && el !== this.host.root; el = el.parentElement) {
+      const id = Number(el.dataset[ID_ATTR]);
+      if (el.classList.contains('sb-gesture') && Number.isInteger(id)) {
+        const node = this.host.nodeOf(id);
+        const props = node?.props ?? {};
+        const drag = props['drag'] === true;
+        const longPress = props['longPress'] === true;
+        if (!drag && !longPress) continue;
+        const minDistance = typeof props['minimumDistance'] === 'number' ? Math.max(0, props['minimumDistance']) : DRAG_MIN_DISTANCE;
+        const minDuration = typeof props['minimumDuration'] === 'number' ? Math.max(0, props['minimumDuration']) * 1000 : LONG_PRESS_MS;
+        out.push({ kind: 'gesture', el, id, drag, longPress, minDistance, minDuration });
+      } else if (el.classList.contains('sb-contextmenu') && Number.isInteger(id)) {
+        out.push({ kind: 'contextmenu', el, id });
+      } else if (el.classList.contains('sb-swipeactions') || el.classList.contains('sb-listrow')) {
+        const host = this.swipeHostFor(el);
+        if (host) out.push({ kind: 'swipe', host });
+      }
+    }
+    const card = target.closest<HTMLElement>('.sb-sheet-card');
+    const sheet = card?.parentElement;
+    if (card && sheet?.classList.contains('sb-sheet') && sheet.dataset['sbSheetPosition'] !== 'below') {
+      const id = Number(sheet.dataset[ID_ATTR]);
+      const detents = (sheet.dataset['sbDetents'] ?? '').split(' ');
+      // A full-screen cover (`detents: ["full"]`) has no drag to dismiss.
+      if (Number.isInteger(id) && !detents.includes('full')) out.push({ kind: 'sheet', sheet, card, id });
+    }
+    const scroller = this.refreshableScrollerOf(target);
+    if (scroller && scroller.el.scrollTop <= 0) out.push({ kind: 'refresh', scroller: scroller.el, id: scroller.id });
+    return out;
+  }
+
+  private refreshableScrollerOf(target: Element): { el: HTMLElement; id: ElementId } | null {
+    const el = target.closest<HTMLElement>('.sb-list[data-sb-refreshable], .sb-scrollview[data-sb-refreshable]');
+    const id = Number(el?.dataset[ID_ATTR]);
+    return el && Number.isInteger(id) ? { el, id } : null;
+  }
+
+  /** Whether the motion so far belongs to `c`. */
+  private wants(c: Candidate, dx: number, dy: number, distance: number): boolean {
+    switch (c.kind) {
+      case 'swipeback':
+        return dx >= PAN_SLOP && dx > Math.abs(dy);
+      case 'gesture':
+        return c.drag && distance >= Math.max(c.minDistance, 0.5);
+      case 'contextmenu':
+        return false;
+      case 'swipe': {
+        if (Math.abs(dx) < SWIPE_START_DISTANCE || Math.abs(dx) <= Math.abs(dy)) return false;
+        // Nothing to reveal that way (and nothing open to close): leave the pointer to the list.
+        const open = this.openSwipe?.host.el === c.host.el ? this.openSwipe.offset : 0;
+        const edge = swipeEdgeOf(open + dx);
+        return edge !== null && (c.host.spec[edge].count > 0 || open !== 0);
+      }
+      case 'sheet':
+        return dy >= PAN_SLOP && dy > Math.abs(dx);
+      case 'refresh':
+        return dy >= PAN_SLOP && dy > Math.abs(dx) && c.scroller.scrollTop <= 0;
+    }
+  }
+
+  private claim(session: Session, c: Candidate, event: PointerEvent): void {
+    session.claimed = c;
+    session.candidates = [c];
+    if (session.longPressTimer !== null) {
+      window.clearTimeout(session.longPressTimer);
+      session.longPressTimer = null;
+    }
+    const captureOn = c.kind === 'gesture' ? c.el : c.kind === 'swipe' ? c.host.el : this.host.root;
+    try {
+      captureOn.setPointerCapture(event.pointerId);
+    } catch {
+      // Not every environment (or an already-cancelled pointer) allows capture.
+    }
+    switch (c.kind) {
+      case 'gesture': {
+        session.gestureRect = c.el.getBoundingClientRect();
+        this.host.send(this.dragEvent(session, c, 'began', { x: 0, y: 0 }));
+        break;
+      }
+      case 'swipe': {
+        const open = this.openSwipe?.host.el === c.host.el ? this.openSwipe.offset : 0;
+        if (this.openSwipe && this.openSwipe.host.el !== c.host.el) this.closeRow(this.openSwipe.host.el);
+        session.swipeStart = open;
+        session.swipeOffset = open;
+        c.host.el.dataset['sbSwiping'] = '';
+        const content = contentOf(c.host.el);
+        if (content) content.style.transition = 'none';
+        this.ensureActions(c.host);
+        break;
+      }
+      case 'swipeback': {
+        this.host.closeMenu();
+        if (this.openSwipe) this.closeRow(this.openSwipe.host.el);
+        c.screen.dataset['sbSwipeDragging'] = '';
+        c.screen.style.transition = 'none';
+        if (c.below) {
+          c.below.style.transition = 'none';
+          c.below.style.visibility = 'visible';
+        }
+        this.swipeBack = { screen: c.screen, below: c.below, completing: false, timer: null };
+        break;
+      }
+      case 'sheet':
+        c.sheet.dataset['sbDragging'] = '';
+        c.card.style.transition = 'none';
+        break;
+      case 'refresh': {
+        const content = scrollContentOf(c.scroller);
+        if (content) content.style.transition = 'none';
+        c.scroller.dataset['sbPulling'] = '';
+        break;
+      }
+      case 'contextmenu':
+        break;
+    }
+  }
+
+  private move(session: Session, c: Candidate, dx: number, dy: number): void {
+    switch (c.kind) {
+      case 'gesture': {
+        // Coalesced: the latest position goes out once per animation frame.
+        session.pendingDrag = this.dragEvent(session, c, 'changed', { x: 0, y: 0 });
+        if (session.raf === null) {
+          session.raf = requestAnimationFrame(() => {
+            session.raf = null;
+            const pending = session.pendingDrag;
+            session.pendingDrag = null;
+            if (pending && this.session === session) this.host.send(pending);
+          });
+        }
+        return;
+      }
+      case 'swipe': {
+        const offset = clampSwipeOffset(session.swipeStart + dx, c.host.spec, c.host.el.offsetWidth);
+        session.swipeOffset = offset;
+        this.applySwipeOffset(c.host, offset);
+        return;
+      }
+      case 'swipeback': {
+        const x = Math.max(0, dx);
+        const progress = clamp01(x / c.width);
+        c.screen.style.transform = `translateX(${x}px)`;
+        if (c.below) {
+          c.below.style.transform = `translateX(${-30 * (1 - progress)}%)`;
+          c.below.style.setProperty('--sb-nav-dim', String(round2(0.12 * (1 - progress))));
+        }
+        return;
+      }
+      case 'sheet': {
+        const y = Math.max(0, dy);
+        session.dy = y;
+        c.card.style.transform = `translateY(${y}px)`;
+        c.card.style.setProperty('--sb-sheet-drag', `${y}px`);
+        return;
+      }
+      case 'refresh': {
+        const pulled = Math.max(0, dy);
+        session.dy = pulled;
+        const content = scrollContentOf(c.scroller);
+        // The content follows with resistance; the spinner fades in over the pull distance.
+        if (content) content.style.transform = `translateY(${Math.min(REFRESH_PULL * 1.5, pulled * 0.6)}px)`;
+        c.scroller.style.setProperty('--sb-pull', String(round2(clamp01(pulled / REFRESH_PULL))));
+        return;
+      }
+      case 'contextmenu':
+        return;
+    }
+  }
+
+  private end(session: Session, c: Candidate, dx: number, _dy: number, velocity: { x: number; y: number }): void {
+    switch (c.kind) {
+      case 'gesture':
+        this.host.send(this.dragEvent(session, c, 'ended', velocity));
+        return;
+      case 'swipe':
+        this.settleRow(c.host, session.swipeOffset, velocity.x);
+        return;
+      case 'swipeback': {
+        const x = Math.max(0, dx);
+        const pop = x > c.width / 3 || velocity.x > SWIPE_BACK_VELOCITY;
+        if (pop) this.completeSwipeBack(c, x);
+        else this.snapBackSwipeBack();
+        return;
+      }
+      case 'sheet':
+        if (session.dy > SHEET_DISMISS_DRAG) {
+          // Keep the dragged offset: the exit clone continues from here.
+          delete c.sheet.dataset['sbDragging'];
+          this.host.send({ type: 'tap', id: c.id });
+          return;
+        }
+        this.resetSheet(c);
+        return;
+      case 'refresh': {
+        this.resetPull(c.scroller);
+        if (session.dy >= REFRESH_PULL) this.host.send({ type: 'refresh', id: c.id });
+        return;
+      }
+      case 'contextmenu':
+        return;
+    }
+  }
+
+  private cancel(session: Session, c: Candidate, _dx: number, _dy: number): void {
+    switch (c.kind) {
+      case 'gesture':
+        this.host.send(this.dragEvent(session, c, 'cancelled', { x: 0, y: 0 }));
+        return;
+      case 'swipe':
+        this.settleRow(c.host, session.swipeOffset, 0);
+        return;
+      case 'swipeback':
+        this.snapBackSwipeBack();
+        return;
+      case 'sheet':
+        this.resetSheet(c);
+        return;
+      case 'refresh':
+        this.resetPull(c.scroller);
+        return;
+      case 'contextmenu':
+        return;
+    }
+  }
+
+  private fireLongPress(session: Session, c: Candidate): void {
+    session.longPressTimer = null;
+    if (this.session !== session || session.claimed) return;
+    session.done = true;
+    session.suppressClick = true;
+    if (c.kind === 'gesture') this.host.send({ type: 'longpress', id: c.id });
+    else if (c.kind === 'contextmenu') this.host.openContextMenu(c.el, c.id);
+  }
+
+  private dragEvent(session: Session, c: Extract<Candidate, { kind: 'gesture' }>, phase: DragEvent['phase'], velocity: { x: number; y: number }): DragEvent {
+    const rect = session.gestureRect ?? c.el.getBoundingClientRect();
+    return {
+      type: 'drag',
+      id: c.id,
+      phase,
+      translation: { width: round2(session.x - session.startX), height: round2(session.y - session.startY) },
+      location: { x: round2(session.x - rect.left), y: round2(session.y - rect.top) },
+      startLocation: { x: round2(session.startX - rect.left), y: round2(session.startY - rect.top) },
+      velocity: { width: round2(velocity.x), height: round2(velocity.y) },
+    };
+  }
+
+  /** A tap on the touch-only edge strip: click whatever is under it. */
+  private forwardTap(strip: HTMLElement, x: number, y: number): void {
+    strip.style.pointerEvents = 'none';
+    const under = document.elementFromPoint(x, y);
+    strip.style.pointerEvents = '';
+    under?.dispatchEvent(new MouseEvent('click', { bubbles: true, cancelable: true, clientX: x, clientY: y }));
+  }
+
+  // -------------------------------------------------------------------------
+  // Swipe rows
+  // -------------------------------------------------------------------------
+
+  /**
+   * The swipe host an element belongs to: a `swipeactions` (inside a list),
+   * or a deletable `listrow` without one, which implies a single Delete.
+   */
+  private swipeHostFor(el: HTMLElement): SwipeHost | null {
+    if (!el.closest('.sb-list')) return null;
+    const id = Number(el.dataset[ID_ATTR]);
+    if (!Number.isInteger(id)) return null;
+    if (el.classList.contains('sb-listrow')) {
+      // A `listrow` whose content is a `swipeactions` (a `List(selection:)`
+      // or editable row with swipe actions): the row is the host, so the
+      // actions reach the row's edge and the whole row slides.
+      const inner = el.querySelector<HTMLElement>('.sb-swipeactions');
+      if (inner && inner.closest('.sb-listrow') === el) return this.swipeHostFor(inner);
+    }
+    if (el.classList.contains('sb-swipeactions')) {
+      const node = this.host.nodeOf(id);
+      if (!node) return null;
+      const row = el.closest<HTMLElement>('.sb-listrow');
+      const hostEl = row && row.querySelector('.sb-swipeactions') === el ? row : el;
+      const trailingCount = Math.max(0, Math.floor(Number(node.props['trailing']) || 0));
+      const leadingCount = Math.max(0, Math.floor(Number(node.props['leading']) || 0));
+      const items = node.children.slice(1);
+      const toSpec = (item: LayoutNode): ActionSpec | null => {
+        const button = unwrapStyledNode(item);
+        if (button.kind !== 'button') return null;
+        const tint = tintOf(item);
+        return {
+          id: button.id,
+          title: textOf(button),
+          symbol: symbolOf(button),
+          destructive: button.props['role'] === 'destructive',
+          tint: tint ? colorToCSS(tint) : null,
+          event: 'tap',
+        };
+      };
+      const trailing = items.slice(0, trailingCount).map(toSpec).filter((a): a is ActionSpec => a !== null);
+      const leading = items.slice(trailingCount, trailingCount + leadingCount).map(toSpec).filter((a): a is ActionSpec => a !== null);
+      return {
+        el: hostEl,
+        id,
+        spec: {
+          trailing: { count: trailing.length, fullSwipe: node.props['fullSwipeTrailing'] !== false },
+          leading: { count: leading.length, fullSwipe: node.props['fullSwipeLeading'] !== false },
+        },
+        actions: { trailing, leading },
+      };
+    }
+    if (el.classList.contains('sb-listrow') && el.hasAttribute('data-sb-deletable') && !el.querySelector('.sb-swipeactions')) {
+      return {
+        el,
+        id,
+        spec: { trailing: { count: 1, fullSwipe: true }, leading: { count: 0, fullSwipe: false } },
+        actions: {
+          trailing: [{ id, title: 'Delete', symbol: null, destructive: true, tint: null, event: 'delete' }],
+          leading: [],
+        },
+      };
+    }
+    return null;
+  }
+
+  /** Build (once) the action buttons of both edges behind the row content. */
+  private ensureActions(host: SwipeHost): void {
+    for (const edge of ['trailing', 'leading'] as SwipeEdge[]) {
+      const actions = host.actions[edge];
+      let container = host.el.querySelector<HTMLElement>(`:scope > .sb-swipe-actions[data-sb-edge="${edge}"]`);
+      if (actions.length === 0) {
+        container?.remove();
+        continue;
+      }
+      if (container) continue;
+      container = document.createElement('div');
+      container.className = 'sb-swipe-actions';
+      container.dataset['sbEdge'] = edge;
+      container.style.width = '0px';
+      for (const action of actions) {
+        const button = document.createElement('button');
+        button.type = 'button';
+        button.className = 'sb-swipe-action';
+        button.dataset['sbTarget'] = String(action.id);
+        button.dataset['sbAction'] = action.event;
+        if (action.destructive) button.dataset['sbRole'] = 'destructive';
+        if (action.tint) button.style.setProperty('--sb-swipe-tint', action.tint);
+        if (action.symbol) {
+          const glyph = renderSymbol(action.symbol);
+          if (glyph) {
+            const symbol = document.createElement('span');
+            symbol.className = 'sb-swipe-action-symbol';
+            symbol.dataset['sbSymbol'] = action.symbol;
+            symbol.append(glyph);
+            button.append(symbol);
+          }
+        }
+        const title = document.createElement('span');
+        title.className = 'sb-swipe-action-title';
+        title.textContent = action.title;
+        button.append(title);
+        container.append(button);
+      }
+      // Behind the content slot (which paints the row background).
+      host.el.prepend(container);
+    }
+  }
+
+  private applySwipeOffset(host: SwipeHost, offset: number): void {
+    const content = contentOf(host.el);
+    if (content) content.style.transform = offset === 0 ? '' : `translateX(${round2(offset)}px)`;
+    const edge = swipeEdgeOf(offset);
+    for (const e of ['trailing', 'leading'] as SwipeEdge[]) {
+      const container = host.el.querySelector<HTMLElement>(`:scope > .sb-swipe-actions[data-sb-edge="${e}"]`);
+      if (!container) continue;
+      if (e !== edge) {
+        container.style.width = '0px';
+        delete container.dataset['sbStretch'];
+        delete container.dataset['sbFull'];
+        continue;
+      }
+      const total = swipeActionsWidth(host.spec[e].count);
+      const shown = Math.abs(offset);
+      container.style.width = `${round2(shown)}px`;
+      container.toggleAttribute('data-sb-stretch', shown > total);
+      container.toggleAttribute('data-sb-full', host.spec[e].fullSwipe && shown > total + SWIPE_FULL_EXTRA);
+    }
+    if (offset !== 0) host.el.dataset['sbSwipeOpen'] = edge ?? '';
+    else delete host.el.dataset['sbSwipeOpen'];
+  }
+
+  /** The pointer lifted (or a wheel sequence ended) at `offset`: open, close or perform the first action. */
+  private settleRow(host: SwipeHost, offset: number, velocityX: number): void {
+    delete host.el.dataset['sbSwiping'];
+    const content = contentOf(host.el);
+    if (content) content.style.transition = '';
+    const edge = swipeEdgeOf(offset);
+    const settle = settleSwipe(offset, velocityX, host.spec);
+    if (!edge || settle === 'closed') {
+      this.closeRow(host.el);
+      return;
+    }
+    if (settle === 'full') {
+      const first = host.actions[edge][0];
+      this.closeRow(host.el);
+      if (first) this.host.send({ type: first.event, id: first.id });
+      return;
+    }
+    const rest = swipeRestOffset('open', edge, host.spec);
+    this.applySwipeOffset(host, rest);
+    this.openSwipe = { host, offset: rest };
+  }
+
+  /** Slide the row open to show one edge's actions (the edit-mode minus). */
+  private revealEdge(host: SwipeHost, edge: SwipeEdge): void {
+    if (this.openSwipe && this.openSwipe.host.el !== host.el) this.closeRow(this.openSwipe.host.el);
+    this.ensureActions(host);
+    const content = contentOf(host.el);
+    if (content) content.style.transition = '';
+    const rest = swipeRestOffset('open', edge, host.spec);
+    // Start the containers at 0 so the first frame transitions.
+    this.applySwipeOffset(host, 0);
+    void host.el.offsetWidth;
+    this.applySwipeOffset(host, rest);
+    this.openSwipe = { host, offset: rest };
+  }
+
+  /** Close an open (or dragged) row with the slide animation; drops its action buttons afterwards. */
+  closeRow(rowEl: HTMLElement): void {
+    if (this.openSwipe?.host.el === rowEl) this.openSwipe = null;
+    if (this.wheelSwipe?.host.el === rowEl) {
+      window.clearTimeout(this.wheelSwipe.timer);
+      this.wheelSwipe = null;
+    }
+    delete rowEl.dataset['sbSwiping'];
+    delete rowEl.dataset['sbSwipeOpen'];
+    const content = contentOf(rowEl);
+    if (content) {
+      content.style.transition = '';
+      content.style.transform = '';
+    }
+    const containers = rowEl.querySelectorAll<HTMLElement>(':scope > .sb-swipe-actions');
+    containers.forEach((c) => {
+      c.style.width = '0px';
+      delete c.dataset['sbStretch'];
+      delete c.dataset['sbFull'];
+    });
+    window.setTimeout(() => {
+      if (rowEl.dataset['sbSwipeOpen'] === undefined && rowEl.dataset['sbSwiping'] === undefined) {
+        rowEl.querySelectorAll(':scope > .sb-swipe-actions').forEach((c) => c.remove());
+      }
+    }, SETTLE_MS);
+  }
+
+  /** The row currently showing its actions (for tests), or null. */
+  get openSwipeRow(): HTMLElement | null {
+    return this.openSwipe?.host.el ?? null;
+  }
+
+  /** A pointer went down anywhere: an open row not under it closes (and the tap is swallowed). */
+  private readonly onDocumentPointerDown = (event: PointerEvent): void => {
+    const open = this.openSwipe;
+    if (!open) return;
+    const target = event.target as Node | null;
+    if (target && open.host.el.contains(target)) return;
+    this.closeRow(open.host.el);
+    if (target && this.host.root.contains(target)) suppressNextClick();
+  };
+
+  /** Scrolling a list closes its open row and ends a wheel pull. */
+  private readonly onScroll = (event: Event): void => {
+    const target = event.target as HTMLElement | null;
+    if (this.openSwipe && target && target.contains(this.openSwipe.host.el)) this.closeRow(this.openSwipe.host.el);
+    if (this.wheelPull && target === this.wheelPull.scroller && target.scrollTop > 0) this.endWheelPull();
+  };
+
+  // -------------------------------------------------------------------------
+  // Wheel: horizontal slides rows, vertical at the top pulls to refresh
+  // -------------------------------------------------------------------------
+
+  private readonly onWheel = (event: WheelEvent): void => {
+    const target = event.target as HTMLElement | null;
+    if (!target) return;
+    const horizontal = Math.abs(event.deltaX) > Math.abs(event.deltaY);
+    if (horizontal) {
+      const rowEl = target.closest<HTMLElement>('.sb-swipeactions, .sb-listrow');
+      const host = rowEl ? this.swipeHostFor(rowEl) : null;
+      if (!host) return;
+      let state = this.wheelSwipe;
+      if (!state || state.host.el !== host.el) {
+        if (state) this.finishWheelSwipe();
+        const open = this.openSwipe?.host.el === host.el ? this.openSwipe.offset : 0;
+        if (this.openSwipe && this.openSwipe.host.el !== host.el) this.closeRow(this.openSwipe.host.el);
+        host.el.dataset['sbSwiping'] = '';
+        const content = contentOf(host.el);
+        if (content) content.style.transition = 'none';
+        this.ensureActions(host);
+        state = { host, offset: open, timer: 0 };
+        this.wheelSwipe = state;
+      } else {
+        window.clearTimeout(state.timer);
+      }
+      // Scrolling right moves the content left (reveals the trailing edge).
+      const next = clampSwipeOffset(state.offset - event.deltaX, host.spec, host.el.offsetWidth);
+      if (next === 0 && state.offset === 0) {
+        // Nothing to reveal that way: let the page have the wheel.
+        this.finishWheelSwipe();
+        return;
+      }
+      event.preventDefault();
+      state.offset = next;
+      this.applySwipeOffset(host, next);
+      state.timer = window.setTimeout(() => this.finishWheelSwipe(), WHEEL_IDLE_MS);
+      return;
+    }
+    // Vertical: a pull (wheel up) at the top of a refreshable scroller.
+    const scroller = this.refreshableScrollerOf(target);
+    if (!scroller || scroller.el.scrollTop > 0 || event.deltaY >= 0) {
+      if (this.wheelPull && event.deltaY > 0) this.endWheelPull();
+      return;
+    }
+    let pull = this.wheelPull;
+    if (!pull || pull.scroller !== scroller.el) {
+      if (pull) this.endWheelPull();
+      pull = { scroller: scroller.el, pulled: 0, sent: false, timer: 0 };
+      this.wheelPull = pull;
+    } else {
+      window.clearTimeout(pull.timer);
+    }
+    pull.pulled += -event.deltaY;
+    scroller.el.style.setProperty('--sb-pull', String(round2(clamp01(pull.pulled / REFRESH_PULL))));
+    if (pull.pulled >= REFRESH_PULL && !pull.sent) {
+      pull.sent = true;
+      this.host.send({ type: 'refresh', id: scroller.id });
+    }
+    pull.timer = window.setTimeout(() => this.endWheelPull(), WHEEL_IDLE_MS * 2);
+  };
+
+  private finishWheelSwipe(): void {
+    const state = this.wheelSwipe;
+    if (!state) return;
+    window.clearTimeout(state.timer);
+    this.wheelSwipe = null;
+    this.settleRow(state.host, state.offset, 0);
+  }
+
+  private endWheelPull(): void {
+    const pull = this.wheelPull;
+    if (!pull) return;
+    window.clearTimeout(pull.timer);
+    this.wheelPull = null;
+    pull.scroller.style.removeProperty('--sb-pull');
+  }
+
+  // -------------------------------------------------------------------------
+  // Touch pull to refresh (independent of the pointer, which the native
+  // scroll cancels) and the native context menu
+  // -------------------------------------------------------------------------
+
+  private readonly onTouchStart = (event: TouchEvent): void => {
+    const touch = event.touches[0];
+    if (!touch || event.touches.length !== 1) return;
+    const scroller = this.refreshableScrollerOf(event.target as Element);
+    if (!scroller || scroller.el.scrollTop > 0) return;
+    this.touchPull = { scroller: scroller.el, id: scroller.id, startY: touch.clientY, sent: false };
+  };
+
+  private readonly onTouchMove = (event: TouchEvent): void => {
+    const pull = this.touchPull;
+    const touch = event.touches[0];
+    if (!pull || !touch) return;
+    if (pull.scroller.scrollTop > 0) {
+      this.touchPull = null;
+      return;
+    }
+    const dy = touch.clientY - pull.startY;
+    if (dy >= REFRESH_PULL && !pull.sent) {
+      pull.sent = true;
+      this.host.send({ type: 'refresh', id: pull.id });
+    }
+  };
+
+  private readonly onTouchEnd = (): void => {
+    this.touchPull = null;
+  };
+
+  private readonly onContextMenu = (event: MouseEvent): void => {
+    const target = event.target as HTMLElement | null;
+    const el = target?.closest<HTMLElement>('.sb-contextmenu, .sb-gesture[data-sb-long-press]');
+    if (!el) return;
+    // The browser's menu never shows on a gesture or context-menu subtree.
+    event.preventDefault();
+    if (!el.classList.contains('sb-contextmenu')) return;
+    const id = Number(el.dataset[ID_ATTR]);
+    if (!Number.isInteger(id) || this.host.isMenuOpen(id)) return;
+    this.host.openContextMenu(el, id);
+  };
+
+  // -------------------------------------------------------------------------
+  // Sheet drag and pull to refresh resets
+  // -------------------------------------------------------------------------
+
+  private resetSheet(c: Extract<Candidate, { kind: 'sheet' }>): void {
+    c.card.style.transition = '';
+    c.card.style.transform = '';
+    c.card.style.removeProperty('--sb-sheet-drag');
+    delete c.sheet.dataset['sbDragging'];
+  }
+
+  private resetPull(scroller: HTMLElement): void {
+    const content = scrollContentOf(scroller);
+    if (content) {
+      content.style.transition = '';
+      content.style.transform = '';
+    }
+    delete scroller.dataset['sbPulling'];
+    scroller.style.removeProperty('--sb-pull');
+  }
+
+  // -------------------------------------------------------------------------
+  // Swipe back
+  // -------------------------------------------------------------------------
+
+  /**
+   * Released past the threshold: the `tap` goes out and the screens stay
+   * where the drag left them (`--sb-nav-from`), so the pop clone the
+   * renderer makes when the `remove` arrives continues from there. Should
+   * Swift not pop, the screen snaps back after a moment.
+   */
+  private completeSwipeBack(c: Extract<Candidate, { kind: 'swipeback' }>, x: number): void {
+    const state = this.swipeBack;
+    if (!state) return;
+    state.completing = true;
+    c.screen.style.setProperty('--sb-nav-from', `${round2(x)}px`);
+    c.screen.dataset['sbSwipePop'] = '';
+    this.host.send({ type: 'tap', id: c.id });
+    state.timer = window.setTimeout(() => {
+      if (this.swipeBack === state && c.screen.isConnected) this.snapBackSwipeBack();
+    }, SWIPE_BACK_TIMEOUT_MS);
+  }
+
+  /** Released short of the threshold (or cancelled): both screens slide back to their resting places. */
+  private snapBackSwipeBack(): void {
+    const state = this.swipeBack;
+    if (!state) return;
+    this.swipeBack = null;
+    if (state.timer !== null) window.clearTimeout(state.timer);
+    const { screen, below } = state;
+    delete screen.dataset['sbSwipeDragging'];
+    delete screen.dataset['sbSwipePop'];
+    screen.style.removeProperty('--sb-nav-from');
+    // Dropping the inline transforms lets the stylesheet's 0.4 s transition
+    // carry each screen from where it is to its resting transform.
+    void screen.offsetWidth;
+    screen.style.transition = '';
+    screen.style.transform = '';
+    if (below) {
+      below.style.transition = '';
+      below.style.transform = '';
+      below.style.visibility = '';
+      below.style.removeProperty('--sb-nav-dim');
+    }
+  }
+
+  /**
+   * The renderer is about to remove `screen` from its stack. When a swipe
+   * back put it there, the screen below is handed back to the stylesheet so
+   * it slides the rest of the way to 0 (it becomes the top screen), and the
+   * pop clone starts from `--sb-nav-from`. Returns true in that case.
+   */
+  screenRemoved(screen: HTMLElement): boolean {
+    const state = this.swipeBack;
+    if (!state || state.screen !== screen) return false;
+    this.swipeBack = null;
+    if (state.timer !== null) window.clearTimeout(state.timer);
+    const below = state.below;
+    if (below) {
+      // Before-change style is the dragged position; the transition runs
+      // once `refreshNavStack` makes it the top screen.
+      void below.offsetWidth;
+      below.style.transition = '';
+      below.style.transform = '';
+      below.style.visibility = '';
+      below.style.removeProperty('--sb-nav-dim');
+    }
+    return state.completing;
+  }
+
+  /** Whether a swipe back is in progress (dragging or awaiting the pop). */
+  get swipingBack(): boolean {
+    return this.swipeBack !== null;
+  }
+}
+
+/** Drop a text selection that lies inside `root` (a press on selected text would drag the text instead). */
+function clearSelectionIn(root: HTMLElement): void {
+  const selection = root.ownerDocument.getSelection?.();
+  if (!selection || selection.isCollapsed || selection.rangeCount === 0) return;
+  const anchor = selection.anchorNode;
+  if (anchor && root.contains(anchor)) selection.removeAllRanges();
+}
+
+/** The content slot of a swipe row (`swipeactions` / `listrow`). */
+function contentOf(rowEl: HTMLElement): HTMLElement | null {
+  return rowEl.querySelector<HTMLElement>(':scope > .sb-swipe-content');
+}
+
+/** The scrolled content box of a `list` / `scrollview`. */
+function scrollContentOf(scroller: HTMLElement): HTMLElement | null {
+  return scroller.querySelector<HTMLElement>(':scope > .sb-list-content, :scope > .sb-scroll-content');
+}
+
+/**
+ * Swallow the click that follows a drag or a long press so nothing under the
+ * pointer fires. Registered on the window's capture phase, ahead of the
+ * renderer's document-level menu-closing listener.
+ */
+export function suppressNextClick(): void {
+  const swallow = (click: Event): void => {
+    click.stopImmediatePropagation();
+    click.preventDefault();
+    cleanup();
+  };
+  const cleanup = (): void => {
+    window.removeEventListener('click', swallow, true);
+    window.removeEventListener('pointerdown', cleanup, true);
+    window.clearTimeout(timer);
+  };
+  window.addEventListener('click', swallow, true);
+  // The click arrives right after the pointer lifts; drop the guard if none
+  // does, and as soon as a new pointer goes down (its click is a new tap).
+  window.addEventListener('pointerdown', cleanup, true);
+  const timer = window.setTimeout(cleanup, 150);
+}
+
+export { SWIPE_ACTION_WIDTH };