@swiftbrowser/web 0.9.9 → 0.9.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swiftbrowser/web",
-  "version": "0.9.9",
+  "version": "0.9.11",
   "type": "module",
   "description": "SwiftBrowser web renderer and dev server: applies render ops from a Swift/Wasm app to the DOM inside an iPhone frame.",
   "repository": {

package/src/layout/engine.ts

@@ -3,11 +3,13 @@
  * renderer's element tree (docs/ops-protocol.md, "Layout engine semantics").
  *
  * `measure(node, proposal)` reports the size a node wants for a proposal and
- * is memoized per (node, proposal); `place(node, proposal, x, y)` records the
- * frame and places the children using the same memoized plans. Context (font,
- * line limit, text alignment, enclosing stack axis, list row) flows down the
- * tree like SwiftUI's environment and is a pure function of the node's
- * ancestors, so it is not part of the memo key.
+ * is memoized per (node, proposal, container); `place(node, proposal, x, y)`
+ * records the frame and places the children using the same memoized plans.
+ * Context (font, line limit, text alignment, enclosing stack axis, list row)
+ * flows down the tree like SwiftUI's environment and is a pure function of
+ * the node's ancestors, so it is not part of the memo key; the container
+ * (`containerRelativeFrame`) is, as a scroll view's viewport is its own
+ * proposal and differs between the widths a stack tries it at.
  *
  * Phase 9: a `LayoutPass` lives across commits. The renderer tells it which
  * nodes changed (`invalidate`, `remove`); a changed node, its ancestors (their
@@ -978,6 +980,18 @@ function proposalKey(p: Proposal): string {
   return `${p.width === null ? 'n' : p.width}|${p.height === null ? 'n' : p.height}`;
 }
 
+/**
+ * The memo key of a plan or placement: the proposal and the container
+ * (`containerRelativeFrame`) it was made under. The container is the screen
+ * everywhere but inside a scroll view, whose viewport is its proposal: a
+ * stack measuring the scroll view at zero, at its ideal and at its final
+ * width makes three containers, and a page sized by the container must not
+ * keep the size the first measurement gave it.
+ */
+function planKey(ctx: Context, p: Proposal): string {
+  return `${proposalKey(p)}@${ctx.container.width}x${ctx.container.height}`;
+}
+
 /**
  * Snap a frame to whole CSS pixels: both edges floor (with an epsilon for
  * float noise), so nested and adjacent frames never overlap by a fraction and
@@ -1100,6 +1114,8 @@ interface ListPlan {
 interface ScrollPlan {
   size: Size;
   content: LayoutNode | null;
+  /** The content's context: the scroll view's, with the viewport as the container. */
+  cctx: Context;
   contentProposal: Proposal;
   contentSize: Size;
 }
@@ -1484,13 +1500,13 @@ export class LayoutPass {
   // Memoization and context
   // -------------------------------------------------------------------------
 
-  private plan<T>(node: LayoutNode, proposal: Proposal, compute: () => T): T {
+  private plan<T>(node: LayoutNode, ctx: Context, proposal: Proposal, compute: () => T): T {
     let byProposal = this.memo.get(node);
     if (!byProposal) {
       byProposal = new Map();
       this.memo.set(node, byProposal);
     }
-    const key = proposalKey(proposal);
+    const key = planKey(ctx, proposal);
     const cached = byProposal.get(key);
     if (cached !== undefined) return cached as T;
     const value = compute();
@@ -1765,7 +1781,7 @@ export class LayoutPass {
   }
 
   private textPlan(node: LayoutNode, ctx: Context, p: Proposal): TextPlan {
-    return this.plan(node, p, () => {
+    return this.plan(node, ctx, p, () => {
       const runs = node.props['runs'];
       if (Array.isArray(runs)) return this.richTextPlan(runs, ctx, p);
       const text = str(node.props['text']) ?? '';
@@ -1974,7 +1990,7 @@ export class LayoutPass {
    * non-empty; the width is the proposal, or the widest row.
    */
   private pickerPlan(node: LayoutNode, ctx: Context, p: Proposal): PickerPlan {
-    return this.plan(node, p, () => {
+    return this.plan(node, ctx, p, () => {
       const options = readOptions(node);
       const selected = readSelected(node, options.length);
       const style = str(node.props['style']);
@@ -2089,7 +2105,7 @@ export class LayoutPass {
   // -------------------------------------------------------------------------
 
   private stackPlan(node: LayoutNode, ctx: Context, p: Proposal, axis: Axis): StackPlan {
-    return this.plan(node, p, () => {
+    return this.plan(node, ctx, p, () => {
       const cctx = this.childContext(node, ctx);
       return this.layoutStack(node.children, cctx, p, axis, this.stackGaps(node, cctx, axis));
     });
@@ -2390,7 +2406,7 @@ export class LayoutPass {
    * frame (outermost) > padding > fixedSize > aspectRatio > child.
    */
   private styledPlan(node: LayoutNode, ctx: Context, p: Proposal): StyledPlan {
-    return this.plan(node, p, () => {
+    return this.plan(node, ctx, p, () => {
       const style = styleOf(node);
       let frame = readFrame(style['frame']);
       // Phase 12 `.containerRelativeFrame`: an affine size against the nearest
@@ -2542,7 +2558,7 @@ export class LayoutPass {
   }
 
   private scrollPlan(node: LayoutNode, ctx: Context, p: Proposal): ScrollPlan {
-    return this.plan(node, p, () => {
+    return this.plan(node, ctx, p, () => {
       const axes = this.scrollAxes(node);
       const content = this.contentOf(node, axes.horizontal && !axes.vertical ? 'horizontal' : 'vertical');
       // Phase 12: the viewport is the container `containerRelativeFrame` measures against.
@@ -2562,7 +2578,7 @@ export class LayoutPass {
         width: p.width === null ? contentSize.width : p.width,
         height: p.height === null ? contentSize.height : p.height,
       };
-      return { size, content, contentProposal, contentSize };
+      return { size, content, cctx, contentProposal, contentSize };
     });
   }
 
@@ -2571,7 +2587,7 @@ export class LayoutPass {
   // -------------------------------------------------------------------------
 
   private listPlan(node: LayoutNode, ctx: Context, p: Proposal): ListPlan {
-    return this.plan(node, p, () => {
+    return this.plan(node, ctx, p, () => {
       const { screen } = this.env;
       const width = finite(p.width) ? p.width : p.width === Infinity ? Infinity : screen.width;
       const layoutWidth = Number.isFinite(width) ? width : screen.width;
@@ -2775,17 +2791,17 @@ export class LayoutPass {
    * Phase 9: placed before, same proposal, same origin, nothing in the
    * subtree invalidated since: the last run's output still holds.
    */
-  private placedAlready(node: LayoutNode, p: Proposal, x: number, y: number): boolean {
+  private placedAlready(node: LayoutNode, ctx: Context, p: Proposal, x: number, y: number): boolean {
     const last = this.placed.get(node);
-    return last !== undefined && last.key === proposalKey(p) && last.x === x && last.y === y;
+    return last !== undefined && last.key === planKey(ctx, p) && last.x === x && last.y === y;
   }
 
   place(node: LayoutNode, ctx: Context, p: Proposal, x: number, y: number): void {
-    if (this.placedAlready(node, p, x, y)) {
+    if (this.placedAlready(node, ctx, p, x, y)) {
       this.stats.skipped += 1;
       return;
     }
-    const key = proposalKey(p);
+    const key = planKey(ctx, p);
     this.placed.set(node, { key, x, y });
     this.stats.placed += 1;
     if (node.id >= 0) {
@@ -3018,7 +3034,8 @@ export class LayoutPass {
         if (inset) scrollChrome['topInset'] = { x, y, width: size.width, height: inset.bar };
         if (inset?.largeTitle) scrollChrome['largeTitle'] = inset.largeTitle;
         this.setChrome(node, scrollChrome);
-        if (plan.content) this.place(plan.content, cctx, plan.contentProposal, content.x, content.y);
+        // The content is placed under the context it was measured in: its container is the viewport.
+        if (plan.content) this.place(plan.content, plan.cctx, plan.contentProposal, content.x, content.y);
         return;
       }
       case 'list':
@@ -3291,7 +3308,7 @@ export class LayoutPass {
         const rowY = y + row.content.y;
         // A row that is skipped keeps the chrome it set itself when it was
         // placed (a link's chevron and label); only the list's keys are new.
-        const own = this.placedAlready(row.node, row.proposal, rowX, rowY) && row.node.id >= 0
+        const own = this.placedAlready(row.node, rowCtx, row.proposal, rowX, rowY) && row.node.id >= 0
           ? this.chrome.get(row.node.id)
           : undefined;
         this.setChrome(row.node, own ? { ...own, ...chrome } : chrome);
@@ -4059,7 +4076,7 @@ export class LayoutPass {
    * stable within a pass.
    */
   private viewThatFitsPlan(node: LayoutNode, ctx: Context, p: Proposal): { chosen: LayoutNode | null; size: Size } {
-    return this.plan(node, p, () => {
+    return this.plan(node, ctx, p, () => {
       const axes = str(node.props['axes']) ?? 'both';
       const checkWidth = axes !== 'vertical';
       const checkHeight = axes !== 'horizontal';
@@ -4160,7 +4177,7 @@ export class LayoutPass {
    * the track. Children are named by `labels` in order.
    */
   private sliderPlan(node: LayoutNode, ctx: Context, p: Proposal): SliderPlan {
-    return this.plan(node, p, () => {
+    return this.plan(node, ctx, p, () => {
       const width = finite(p.width) ? p.width : SLIDER_DEFAULT_WIDTH;
       const cctx = this.childContext(node, ctx);
       const names = Array.isArray(node.props['labels']) ? node.props['labels'].map(str) : [];
@@ -4223,7 +4240,7 @@ export class LayoutPass {
    * trail. The width is the proposal, or label + 8 + capsules.
    */
   private datePickerPlan(node: LayoutNode, ctx: Context, p: Proposal): DatePickerPlan {
-    return this.plan(node, p, () => {
+    return this.plan(node, ctx, p, () => {
       const cctx = this.childContext(node, ctx);
       const seconds = num(node.props['seconds']) ?? 0;
       const components = str(node.props['components']) ?? 'dateAndTime';
@@ -4632,7 +4649,7 @@ export class LayoutPass {
    * aligns its whole column.
    */
   private gridPlan(node: LayoutNode, ctx: Context, p: Proposal): GridPlan {
-    return this.plan(node, p, () => {
+    return this.plan(node, ctx, p, () => {
       const hSpacing = num(node.props['horizontalSpacing']) ?? DEFAULT_SPACING;
       const vSpacing = num(node.props['verticalSpacing']) ?? DEFAULT_SPACING;
       interface Source {
@@ -4799,7 +4816,7 @@ export class LayoutPass {
    * its `rows` the lines along it (`y`, `height`: main axis).
    */
   private lazyGridPlan(node: LayoutNode, ctx: Context, p: Proposal): LazyGridPlan {
-    return this.plan(node, p, () => {
+    return this.plan(node, ctx, p, () => {
       const horizontal = node.kind === 'lazyhgrid';
       const crossOf = (size: { width: number | null; height: number | null }): number | null => (horizontal ? size.height : size.width);
       const items = readGridItems(node.props[horizontal ? 'rows' : 'columns']);
@@ -4922,7 +4939,7 @@ export class LayoutPass {
    * label in the gap at the bottom of its arc.
    */
   private gaugePlan(node: LayoutNode, ctx: Context, p: Proposal): GaugePlan {
-    return this.plan(node, p, () => {
+    return this.plan(node, ctx, p, () => {
       const width = finite(p.width) ? p.width : GAUGE_DEFAULT_WIDTH;
       const cctx = this.childContext(node, ctx);
       const labelCtx: Context = { ...cctx, font: resolveFont({ textStyle: 'caption' }, ctx.font, this.env) };
@@ -5022,7 +5039,7 @@ export class LayoutPass {
    * measured at its ideal size and framed against the plot (src/layout/chart.ts).
    */
   private chartPlan(node: LayoutNode, ctx: Context, p: Proposal): ChartPlan {
-    return this.plan(node, p, () => {
+    return this.plan(node, ctx, p, () => {
       const size = chartSize(p.width, p.height);
       // An infinite proposal reports infinite (the chart is flexible); the
       // geometry is computed for the default size and recomputed when placed.

package/src/renderer.ts

@@ -151,7 +151,8 @@ import { VideoEvents, applyVideo, stopVideos } from './video';
 import { PinchController } from './pinch';
 import { applyCanvas, createCanvasElement } from './canvasDrawing';
 import { scrollToTarget } from './scrollTo';
-import { POSITION_SETTLE_MS, anchorPoint, positionTarget, type PositionCandidate } from './scrollPosition';
+import { POSITION_SETTLE_MS, POSITION_SNAP_WAITS, anchorPoint, positionTarget, restsOnSnapPoint, type PositionCandidate } from './scrollPosition';
+import { TouchPaging } from './touchPaging';
 import { applyDefaultScrollAnchor, keepScrollAnchors } from './scrollAnchor';
 import { EMPTY_CATALOG, assetColorVar, type AssetCatalog } from './assets';
 import { HIERARCHY_OPACITY, colorToCSS, effectsCSS, styleToCSS, type PaintCSS } from './styles';
@@ -363,6 +364,8 @@ export class Renderer {
   private readonly resizeObserver: ResizeObserver | null = null;
   /** `reportsPosition` scroll views mid-scroll: the timer that calls the scroll settled (src/scrollPosition.ts). */
   private readonly positionTimers = new Map<HTMLElement, number>();
+  /** `reportsPosition` scroll views a finger is on: a scroll under it is not settled, however still the finger holds. */
+  private readonly heldScrolls = new Set<HTMLElement>();
   /** The scroll target each `reportsPosition` scroll view last reported, so a settle at the same one says nothing. */
   private readonly reportedPositions = new WeakMap<HTMLElement, number>();
   /**
@@ -394,6 +397,7 @@ export class Renderer {
   /** Text, links and files dragged in from outside the page (src/dragDrop.ts). */
   private readonly externalDrops: ExternalDrops;
   private readonly pinches: PinchController;
+  private readonly touchPaging: TouchPaging;
   /** `video` elements' media events, as `video` events (src/video.ts). */
   private readonly videoEvents: VideoEvents;
   private readonly measurer = new CanvasTextMeasurer();
@@ -862,6 +866,9 @@ export class Renderer {
     root.addEventListener('scroll', this.queueLazyCheck, { capture: true, passive: true });
     root.addEventListener('scroll', this.onPositionScroll, { capture: true, passive: true });
     root.addEventListener('scrollend', this.onPositionScrollEnd, { capture: true, passive: true });
+    root.addEventListener('touchstart', this.onPositionTouchStart, { capture: true, passive: true });
+    root.addEventListener('touchend', this.onPositionTouchEnd, { capture: true, passive: true });
+    root.addEventListener('touchcancel', this.onPositionTouchEnd, { capture: true, passive: true });
     this.videoEvents = new VideoEvents(root, (event) => this.onEvent(event));
     // Phase 8: pointer gestures (the sheet drag among them) are delegated too.
     const host: InteractionHost = {
@@ -879,6 +886,12 @@ export class Renderer {
     this.externalDrops = new ExternalDrops(host);
     // Two-finger gestures: MagnifyGesture and RotateGesture (src/pinch.ts).
     this.pinches = new PinchController(host);
+    // A finger on a paging scroll view pages it as iOS does (src/touchPaging.ts);
+    // the view it drives reports its position once the drive rests it on a page.
+    this.touchPaging = new TouchPaging(root, (el) => {
+      this.heldScrolls.delete(el);
+      this.armPositionReport(el);
+    });
     root.addEventListener('change', this.onChange);
     root.addEventListener('pointerdown', this.onSliderPointerDown);
     if (typeof ResizeObserver !== 'undefined') {
@@ -1574,12 +1587,16 @@ export class Renderer {
     this.root.removeEventListener('scroll', this.onScrollDismissKeyboard, true);
     this.root.removeEventListener('scroll', this.onPositionScroll, true);
     this.root.removeEventListener('scrollend', this.onPositionScrollEnd, true);
+    this.root.removeEventListener('touchstart', this.onPositionTouchStart, true);
+    this.root.removeEventListener('touchend', this.onPositionTouchEnd, true);
+    this.root.removeEventListener('touchcancel', this.onPositionTouchEnd, true);
     for (const timer of this.positionTimers.values()) window.clearTimeout(timer);
     this.positionTimers.clear();
     this.interaction.dispose();
     this.pressEffects.dispose();
     this.externalDrops.dispose();
     this.pinches.dispose();
+    this.touchPaging.dispose();
     this.videoEvents.dispose();
     this.resizeObserver?.disconnect();
     this.hostObserver?.disconnect();
@@ -1667,32 +1684,72 @@ export class Renderer {
   // `.scrollPosition(id:)` reading back (src/scrollPosition.ts)
   // -------------------------------------------------------------------------
 
-  /** A `reportsPosition` scroll view scrolled: it has settled when no further scroll follows for a moment. */
+  /** A `reportsPosition` scroll view scrolled: it has settled when no further scroll follows for a moment (and no finger is on it). */
   private readonly onPositionScroll = (event: Event): void => {
     const el = event.target;
     if (!(el instanceof HTMLElement) || el.dataset['sbReportsPosition'] === undefined) return;
-    const pending = this.positionTimers.get(el);
-    if (pending !== undefined) window.clearTimeout(pending);
-    this.positionTimers.set(
-      el,
-      window.setTimeout(() => this.reportPosition(el), POSITION_SETTLE_MS),
-    );
+    if (this.heldScrolls.has(el)) return;
+    this.armPositionReport(el);
   };
 
   /** The browser says the scroll ended (Chrome, Firefox; Safari waits for the timer). */
   private readonly onPositionScrollEnd = (event: Event): void => {
     const el = event.target;
     if (!(el instanceof HTMLElement) || el.dataset['sbReportsPosition'] === undefined) return;
+    if (this.heldScrolls.has(el)) return;
     this.reportPosition(el);
   };
 
+  /**
+   * A finger came down inside `reportsPosition` scroll views: a pause in the
+   * drag is not a settled scroll (the page would be reported, and an app
+   * that re-centres on it would move the content under the finger). They
+   * report once the finger lifts and the scroll (the snap after a fling)
+   * settles.
+   */
+  private readonly onPositionTouchStart = (event: Event): void => {
+    const target = event.target;
+    if (!(target instanceof Element)) return;
+    for (let el = target.closest<HTMLElement>('[data-sb-reports-position]'); el; el = el.parentElement?.closest<HTMLElement>('[data-sb-reports-position]') ?? null) {
+      this.heldScrolls.add(el);
+      const pending = this.positionTimers.get(el);
+      if (pending !== undefined) {
+        window.clearTimeout(pending);
+        this.positionTimers.delete(el);
+      }
+    }
+  };
+
+  /** The last finger lifted: the held scroll views settle from here (one the finger paged, once its run rests). */
+  private readonly onPositionTouchEnd = (event: Event): void => {
+    if ((event as TouchEvent).touches?.length > 0) return;
+    for (const el of this.heldScrolls) {
+      if (this.touchPaging.drives(el)) continue;
+      this.heldScrolls.delete(el);
+      this.armPositionReport(el);
+    }
+  };
+
+  private armPositionReport(el: HTMLElement): void {
+    const pending = this.positionTimers.get(el);
+    if (pending !== undefined) window.clearTimeout(pending);
+    this.positionTimers.set(
+      el,
+      window.setTimeout(() => this.reportPosition(el), POSITION_SETTLE_MS),
+    );
+  }
+
   /**
    * Which scroll target of a settled scroll view is at its anchor point: the
    * `scrollID` boxes inside it whose nearest scrolling ancestor it is, along
    * the axis it scrolls on (the vertical one when it scrolls both ways). Sent
-   * to that target when it is not the one reported last.
+   * to that target when it is not the one reported last. A snapping scroll
+   * view that settled off its snap points is still between a gesture and
+   * the browser's snap animation: it waits (a bounded number of settles)
+   * until the animation has carried it onto one, so the target reported is
+   * the page the browser chose, never one passing by mid-snap.
    */
-  private reportPosition(el: HTMLElement): void {
+  private reportPosition(el: HTMLElement, waited = 0): void {
     const pending = this.positionTimers.get(el);
     if (pending !== undefined) window.clearTimeout(pending);
     this.positionTimers.delete(el);
@@ -1702,7 +1759,8 @@ export class Renderer {
     const anchor = node.props['positionAnchor'] as { x?: unknown; y?: unknown } | undefined;
     const fraction = horizontal ? anchor?.x : anchor?.y;
     const box = el.getBoundingClientRect();
-    const point = anchorPoint(horizontal ? { start: box.left, length: box.width } : { start: box.top, length: box.height }, typeof fraction === 'number' ? fraction : 0);
+    const viewport = horizontal ? { start: box.left, length: box.width } : { start: box.top, length: box.height };
+    const point = anchorPoint(viewport, typeof fraction === 'number' ? fraction : 0);
     const candidates: PositionCandidate[] = [];
     for (const target of el.querySelectorAll<HTMLElement>('[data-sb-id]')) {
       const id = Number(target.dataset[ID_ATTR]);
@@ -1711,6 +1769,19 @@ export class Renderer {
       const rect = target.getBoundingClientRect();
       candidates.push(horizontal ? { id, start: rect.left, length: rect.width } : { id, start: rect.top, length: rect.height });
     }
+    if (el.dataset['sbSnap'] !== undefined && waited < POSITION_SNAP_WAITS) {
+      const computed = getComputedStyle(el);
+      const padding = parseFloat(horizontal ? computed.scrollPaddingLeft : computed.scrollPaddingTop) || 0;
+      const offset = horizontal ? el.scrollLeft : el.scrollTop;
+      const max = horizontal ? el.scrollWidth - el.clientWidth : el.scrollHeight - el.clientHeight;
+      if (!restsOnSnapPoint(candidates, viewport.start + padding, viewport.length, offset, max)) {
+        this.positionTimers.set(
+          el,
+          window.setTimeout(() => this.reportPosition(el, waited + 1), POSITION_SETTLE_MS),
+        );
+        return;
+      }
+    }
     const target = positionTarget(candidates, point);
     if (target === null || this.reportedPositions.get(el) === target) return;
     this.reportedPositions.set(el, target);

package/src/scrollPosition.ts

@@ -17,6 +17,37 @@ export interface PositionCandidate {
 /** A settled scroll is one with no `scroll` event for this long (`scrollend`, where the browser has it, ends the wait). */
 export const POSITION_SETTLE_MS = 120;
 
+/**
+ * A snapping scroll view that settles off its snap points is between a
+ * gesture and the browser's snap animation (a trackpad swipe ended, the
+ * snap not yet begun): it waits this many settles more for the animation
+ * to carry it onto one before reporting where it is.
+ */
+export const POSITION_SNAP_WAITS = 6;
+
+/** How far from a snap point still counts as on it (subpixel scroll offsets). */
+const SNAP_TOLERANCE = 1;
+
+/**
+ * Whether a snapping scroll view (`scrollTargetBehavior`) is at rest on a
+ * snap point, so that the target at its anchor is the one the browser
+ * chose rather than one passing by mid-snap: a target starts at the
+ * snapport's start (`start` is the viewport's start plus its scroll
+ * padding), or a target longer than the viewport covers the whole of it
+ * (the browser lets the view rest anywhere such a target fills), or the
+ * view is at either end of its range (the last snap point may be out of
+ * reach).
+ */
+export function restsOnSnapPoint(candidates: readonly PositionCandidate[], start: number, viewportLength: number, offset: number, maxOffset: number): boolean {
+  if (offset <= SNAP_TOLERANCE || offset >= maxOffset - SNAP_TOLERANCE) return true;
+  for (const c of candidates) {
+    if (c.length <= 0) continue;
+    if (Math.abs(c.start - start) <= SNAP_TOLERANCE) return true;
+    if (c.start <= start + SNAP_TOLERANCE && c.start + c.length >= start + viewportLength - SNAP_TOLERANCE && c.length > viewportLength + SNAP_TOLERANCE) return true;
+  }
+  return false;
+}
+
 /**
  * The target at `point` along the axis: the one whose extent holds the point
  * (the last of several, as a later sibling draws over an earlier one), else

package/src/styles.css

@@ -740,6 +740,17 @@ svg[data-sb-symbol="progress.indicator"] > line:nth-child(8) { animation-delay:
   scroll-snap-stop: always;
 }
 
+/* A finger pages a paging scroll view as iOS does (src/touchPaging.ts): the
+   browser keeps off its axis and the page drives the offset; a pan along
+   the other axis still scrolls what the view sits in. */
+.sb-scrollview[data-sb-snap="paging"][data-sb-axes="horizontal"] {
+  touch-action: pan-y pinch-zoom;
+}
+
+.sb-scrollview[data-sb-snap="paging"][data-sb-axes="vertical"] {
+  touch-action: pan-x pinch-zoom;
+}
+
 .sb-scroll-content,
 .sb-list-content {
   position: relative;

package/src/touchPaging.ts

@@ -0,0 +1,286 @@
+/**
+ * iOS paging under a finger for `.scrollTargetBehavior(.paging)`
+ * (docs/ops-protocol.md, "Scroll targets"). A `UIScrollView` with paging
+ * follows the finger and, when it lifts, goes one page in the direction of
+ * a flick however short the drag was, or to the nearest page from a slow
+ * release (half a page across is the next page), with its own deceleration.
+ * CSS scroll snapping chooses by the projected end of the fling instead, so
+ * a short flick in Safari and Chrome falls back to the page it left. On a
+ * touch device the browser is kept off the paging axis (`touch-action` in
+ * styles.css) and this controller drives the scroll offset: 1:1 with the
+ * finger, then an eased run to the page `pagingDestination` chooses. Wheel
+ * and trackpad scrolling stay native, snapped by CSS.
+ */
+
+/** A lift moving at least this fast (px per ms) is a flick: one page on in its direction. */
+export const FLICK_VELOCITY = 0.3;
+/** The finger's velocity is measured over its last moves within this window; a pause before the lift is no flick. */
+export const FLICK_WINDOW_MS = 100;
+/** How far a flick carries on inside a page longer than the viewport (its velocity times this). */
+export const FLICK_RUN_MS = 250;
+/** A touch is a drag once it moved this far; the larger axis then decides whose gesture it is. */
+export const DIRECTION_SLOP = 6;
+
+/** Where a scroll view may rest for one page: at its start, or anywhere a page longer than the viewport fills it (`start === end` for a page the viewport's size). */
+export interface RestInterval {
+  start: number;
+  end: number;
+}
+
+export interface TouchSample {
+  t: number;
+  pos: number;
+}
+
+/** The rest intervals of pages (offsets along the axis in scroll coordinates), in order; pages of no length are left out. */
+export function restIntervals(pages: readonly { start: number; length: number }[], viewportLength: number, maxOffset: number): RestInterval[] {
+  const clamp = (v: number) => Math.min(maxOffset, Math.max(0, v));
+  return pages
+    .filter((p) => p.length > 0)
+    .map((p) => ({ start: clamp(p.start), end: clamp(Math.max(p.start, p.start + p.length - viewportLength)) }))
+    .sort((a, b) => a.start - b.start);
+}
+
+/**
+ * The finger's velocity (px per ms) at the lift from its last moves: the
+ * change over the samples inside the window before `now`; zero after a
+ * pause longer than the window, or with fewer than two samples in it.
+ */
+export function flickVelocity(samples: readonly TouchSample[], now: number): number {
+  const recent = samples.filter((s) => now - s.t <= FLICK_WINDOW_MS);
+  if (recent.length < 2) return 0;
+  const first = recent[0]!;
+  const last = recent[recent.length - 1]!;
+  if (last.t <= first.t) return 0;
+  return (last.pos - first.pos) / (last.t - first.t);
+}
+
+/**
+ * The offset to run to when the finger lifts at `offset` with the scroll
+ * offset changing at `velocity` (px per ms, positive toward later pages).
+ * A flick goes one page on in its direction, from the page the offset is
+ * on; inside a page longer than the viewport it runs on as far as its
+ * momentum carries, to the page's edge at most. A slow release goes to
+ * the nearest rest: for pages the viewport's size, the page more than
+ * half across.
+ */
+export function pagingDestination(offset: number, velocity: number, intervals: readonly RestInterval[], maxOffset: number): number {
+  const clamp = (v: number) => Math.min(maxOffset, Math.max(0, v));
+  if (intervals.length === 0) return clamp(offset);
+  if (velocity >= FLICK_VELOCITY) {
+    // The page the offset is on: the last starting at or before it.
+    let at = 0;
+    for (let i = 0; i < intervals.length; i++) if (intervals[i]!.start <= offset + 1) at = i;
+    const page = intervals[at]!;
+    if (offset < page.end - 1) return clamp(Math.min(offset + velocity * FLICK_RUN_MS, page.end));
+    const next = intervals[at + 1];
+    return clamp(next ? next.start : page.end);
+  }
+  if (velocity <= -FLICK_VELOCITY) {
+    // The page the offset is on: the first ending at or after it.
+    let at = intervals.length - 1;
+    for (let i = intervals.length - 1; i >= 0; i--) if (intervals[i]!.end >= offset - 1) at = i;
+    const page = intervals[at]!;
+    if (offset > page.start + 1) return clamp(Math.max(offset + velocity * FLICK_RUN_MS, page.start));
+    const previous = intervals[at - 1];
+    return clamp(previous ? previous.end : page.start);
+  }
+  let best = offset;
+  let distance = Infinity;
+  for (const i of intervals) {
+    const rest = Math.min(i.end, Math.max(i.start, offset));
+    const d = Math.abs(offset - rest);
+    if (d < distance) {
+      distance = d;
+      best = rest;
+    }
+  }
+  return clamp(best);
+}
+
+/** The eased run to a page: ease-out, 200...450 ms by distance. */
+export function runDuration(distance: number): number {
+  return Math.min(450, 200 + Math.abs(distance) * 0.3);
+}
+
+export function easeOut(t: number): number {
+  const u = 1 - Math.min(1, Math.max(0, t));
+  return 1 - u * u * u;
+}
+
+interface Gesture {
+  el: HTMLElement;
+  horizontal: boolean;
+  startX: number;
+  startY: number;
+  /** Null until the drag passed the slop; then whether it is ours (along the paging axis) or the browser's. */
+  ours: boolean | null;
+  /** The scroll offset where our drag took over. */
+  from: number;
+  /** The finger position (along the axis) where our drag took over. */
+  fromPos: number;
+  samples: TouchSample[];
+}
+
+interface Run {
+  el: HTMLElement;
+  frame: number;
+  /** The offset the last frame wrote: another writer moving the view ends the run. */
+  written: number;
+}
+
+const PAGING_SELECTOR = '.sb-scrollview[data-sb-snap="paging"]';
+
+/** Pages of a paging scroll view in scroll coordinates along its axis: the children of its `scrollTargetLayout` stack, else of its content. */
+export function pagesOf(el: HTMLElement, horizontal: boolean): { start: number; length: number }[] {
+  const targets = [...el.querySelectorAll<HTMLElement>('[data-sb-scroll-target] > *')].filter((t) => t.parentElement?.closest('.sb-scrollview, .sb-list') === el);
+  const children = targets.length > 0 ? targets : [...((el.firstElementChild?.children ?? []) as Iterable<Element>)];
+  const box = el.getBoundingClientRect();
+  const computed = getComputedStyle(el);
+  const padding = parseFloat(horizontal ? computed.scrollPaddingLeft : computed.scrollPaddingTop) || 0;
+  const offset = horizontal ? el.scrollLeft : el.scrollTop;
+  return children.map((child) => {
+    const rect = child.getBoundingClientRect();
+    return horizontal ? { start: rect.left - box.left - padding + offset, length: rect.width } : { start: rect.top - box.top - padding + offset, length: rect.height };
+  });
+}
+
+export class TouchPaging {
+  private gesture: Gesture | null = null;
+  private run: Run | null = null;
+
+  /**
+   * `onRest(el)`: the view came to rest on a page after a gesture of ours
+   * (the renderer reports its position then; while a drive is on, a
+   * `scrollend` the browser fires for a frame's write is no settling).
+   */
+  constructor(
+    private readonly root: HTMLElement,
+    private readonly onRest: (el: HTMLElement) => void = () => {},
+  ) {
+    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 });
+  }
+
+  /** Whether a finger's drag along the paging axis, or the run after it, is moving `el`. */
+  drives(el: HTMLElement): boolean {
+    return (this.gesture?.el === el && this.gesture.ours === true) || this.run?.el === el;
+  }
+
+  dispose(): void {
+    this.root.removeEventListener('touchstart', this.onTouchStart);
+    this.root.removeEventListener('touchmove', this.onTouchMove);
+    this.root.removeEventListener('touchend', this.onTouchEnd);
+    this.root.removeEventListener('touchcancel', this.onTouchEnd);
+    this.stopRun();
+  }
+
+  private readonly onTouchStart = (event: TouchEvent): void => {
+    this.gesture = null;
+    const touch = event.touches[0];
+    if (!touch || event.touches.length !== 1 || !(event.target instanceof Element)) return;
+    const el = event.target.closest<HTMLElement>(PAGING_SELECTOR);
+    if (!el) return;
+    const axes = el.dataset['sbAxes'];
+    if (axes !== 'horizontal' && axes !== 'vertical') return;
+    const horizontal = axes === 'horizontal';
+    this.gesture = { el, horizontal, startX: touch.clientX, startY: touch.clientY, ours: null, from: 0, fromPos: 0, samples: [] };
+    // A finger on a page still running to its place catches it: the drag is
+    // ours from here, and the lift runs it on to a page.
+    if (this.run?.el === el) {
+      this.stopRun();
+      this.gesture.ours = true;
+      this.gesture.from = horizontal ? el.scrollLeft : el.scrollTop;
+      this.gesture.fromPos = horizontal ? touch.clientX : touch.clientY;
+      el.style.scrollSnapType = 'none';
+    }
+  };
+
+  private readonly onTouchMove = (event: TouchEvent): void => {
+    const g = this.gesture;
+    const touch = event.touches[0];
+    if (!g || !touch) return;
+    const pos = g.horizontal ? touch.clientX : touch.clientY;
+    if (g.ours === null) {
+      const dx = touch.clientX - g.startX;
+      const dy = touch.clientY - g.startY;
+      if (Math.abs(dx) < DIRECTION_SLOP && Math.abs(dy) < DIRECTION_SLOP) return;
+      g.ours = g.horizontal ? Math.abs(dx) >= Math.abs(dy) : Math.abs(dy) > Math.abs(dx);
+      if (!g.ours) {
+        this.gesture = null;
+        return;
+      }
+      // Ours: the snap is off while the offset follows the finger (a snapping
+      // container snaps every offset it is given), back on once it rests.
+      g.el.style.scrollSnapType = 'none';
+      g.from = g.horizontal ? g.el.scrollLeft : g.el.scrollTop;
+      g.fromPos = pos;
+    }
+    const max = g.horizontal ? g.el.scrollWidth - g.el.clientWidth : g.el.scrollHeight - g.el.clientHeight;
+    const offset = Math.min(max, Math.max(0, g.from - (pos - g.fromPos)));
+    if (g.horizontal) g.el.scrollLeft = offset;
+    else g.el.scrollTop = offset;
+    g.samples.push({ t: event.timeStamp, pos });
+    if (g.samples.length > 20) g.samples.shift();
+  };
+
+  private readonly onTouchEnd = (event: TouchEvent): void => {
+    const g = this.gesture;
+    if (!g) return;
+    if (event.touches.length > 0) return;
+    this.gesture = null;
+    if (!g.ours) return;
+    const el = g.el;
+    const max = g.horizontal ? el.scrollWidth - el.clientWidth : el.scrollHeight - el.clientHeight;
+    const offset = g.horizontal ? el.scrollLeft : el.scrollTop;
+    // The finger's velocity, as the offset's: a finger moving back moves the content on.
+    const velocity = event.type === 'touchcancel' ? 0 : -flickVelocity(g.samples, event.timeStamp);
+    const viewport = g.horizontal ? el.clientWidth : el.clientHeight;
+    const destination = pagingDestination(offset, velocity, restIntervals(pagesOf(el, g.horizontal), viewport, max), max);
+    this.runTo(el, g.horizontal, offset, destination);
+  };
+
+  /** Runs the offset to `to` with an ease-out, then lets the container snap again. */
+  private runTo(el: HTMLElement, horizontal: boolean, from: number, to: number): void {
+    this.stopRun();
+    const distance = to - from;
+    if (Math.abs(distance) < 0.5) {
+      el.style.scrollSnapType = '';
+      this.onRest(el);
+      return;
+    }
+    const duration = runDuration(distance);
+    const started = performance.now();
+    const step = (now: number): void => {
+      const run = this.run;
+      const current = horizontal ? el.scrollLeft : el.scrollTop;
+      // Another writer moved the view (an app re-centring on the page): the run is over.
+      if (run && Math.abs(current - run.written) > 1) {
+        this.stopRun();
+        this.onRest(el);
+        return;
+      }
+      const t = (now - started) / duration;
+      const offset = t >= 1 ? to : from + distance * easeOut(t);
+      if (horizontal) el.scrollLeft = offset;
+      else el.scrollTop = offset;
+      if (t >= 1) {
+        this.run = null;
+        el.style.scrollSnapType = '';
+        this.onRest(el);
+        return;
+      }
+      this.run = { el, frame: requestAnimationFrame(step), written: offset };
+    };
+    this.run = { el, frame: requestAnimationFrame(step), written: from };
+  }
+
+  private stopRun(): void {
+    if (!this.run) return;
+    cancelAnimationFrame(this.run.frame);
+    this.run.el.style.scrollSnapType = '';
+    this.run = null;
+  }
+}