@stacknav/core 0.2.0 → 0.3.1

package/src/animate.ts

@@ -1,36 +1,67 @@
-// A small animation toolkit: a cubic-bezier solver, a cancellable tween, and
-// the easing curves the iOS transition uses.
+// A small animation toolkit. The pages themselves are moved by CSS (see
+// styles.ts), so what is here is the arithmetic CSS cannot do for the engine:
+// a curve it can both hand to CSS and sample in JS, the spellings CSS wants,
+// a cancellable tween used only to report progress, and the two helpers that
+// hand a run over to the browser.
 
-export type Easing = (t: number) => number;
+/**
+ * An easing curve. Callable, so the engine can sample it; `css` is the same
+ * curve spelled for `transition-timing-function`, which is what actually
+ * drives the pixels. A plain `(t) => number` is still a valid easing, it just
+ * falls back to `linear` on the CSS side.
+ */
+export interface Easing {
+  (t: number): number;
+  readonly css?: string;
+}
 
 export function cubicBezier(x1: number, y1: number, x2: number, y2: number): Easing {
-  const A = (a: number, b: number) => 1 - 3 * b + 3 * a;
-  const B = (a: number, b: number) => 3 * b - 6 * a;
-  const C = (a: number) => 3 * a;
-  const calc = (t: number, a: number, b: number) => ((A(a, b) * t + B(a, b)) * t + C(a)) * t;
-  const slope = (t: number, a: number, b: number) => 3 * A(a, b) * t * t + 2 * B(a, b) * t + C(a);
-  return (x) => {
+  // The coefficients are constant for the lifetime of a curve.
+  const ax = 1 - 3 * x2 + 3 * x1, bx = 3 * x2 - 6 * x1, cx = 3 * x1;
+  const ay = 1 - 3 * y2 + 3 * y1, by = 3 * y2 - 6 * y1, cy = 3 * y1;
+  const sampleX = (t: number) => ((ax * t + bx) * t + cx) * t;
+  const sampleY = (t: number) => ((ay * t + by) * t + cy) * t;
+  const f = (x: number) => {
     if (x <= 0) return 0;
     if (x >= 1) return 1;
     let t = x;
+    // Newton converges quickly for ordinary curves. Flat slopes can send it
+    // outside [0, 1], so fall back to a bounded search when it fails.
     for (let i = 0; i < 8; i++) {
-      const s = slope(t, x1, x2);
-      if (s === 0) break;
-      t -= (calc(t, x1, x2) - x) / s;
+      const error = sampleX(t) - x;
+      if (Math.abs(error) < 1e-8) return sampleY(t);
+      const slope = (3 * ax * t + 2 * bx) * t + cx;
+      if (Math.abs(slope) < 1e-8) break;
+      const next = t - error / slope;
+      if (next < 0 || next > 1) break;
+      t = next;
+    }
+    let lo = 0, hi = 1;
+    for (let i = 0; i < 30; i++) {
+      t = (lo + hi) / 2;
+      if (sampleX(t) < x) lo = t;
+      else hi = t;
     }
-    return calc(t, y1, y2);
+    return sampleY(t);
   };
+  return Object.assign(f, { css: `cubic-bezier(${x1}, ${y1}, ${x2}, ${y2})` });
 }
 
 // `#__PURE__` marks the module-load calls as droppable, so a bundler that does
 // not honour the package's `sideEffects` flag can still leave this module out
 // when nothing here is imported.
 export const easings: { linear: Easing; ios: Easing; easeOut: Easing } = {
-  linear: (t) => t,
+  linear: /*#__PURE__*/ Object.assign((t: number) => t, { css: 'linear' }),
   ios: /*#__PURE__*/ cubicBezier(0.32, 0.72, 0, 1), // the common approximation of UIKit's navigation curve
   easeOut: /*#__PURE__*/ cubicBezier(0.2, 0.8, 0.2, 1),
 };
 
+/** How an easing should be spelled for CSS. A curve with no spelling runs linearly. */
+export const cssEasing = (ease: Easing | undefined): string => ease?.css ?? 'linear';
+
+/** How a duration should be spelled for CSS. */
+export const cssDuration = (ms: number): string => (ms > 0 ? `${ms}ms` : '0s');
+
 export interface TweenOptions {
   from: number;
   to: number;
@@ -44,13 +75,18 @@ export type CancellableTween = Promise<void> & { cancel(): void };
 /**
  * Animates a number from `from` to `to` over `duration` ms, calling `onUpdate`
  * every frame. Returns a promise that resolves when the tween is done;
- * `promise.cancel()` stops it early. A duration of 0 or less jumps straight
- * to `to`.
+ * `promise.cancel()` stops it early and resolves the promise. A duration of
+ * 0 or less jumps straight to `to`.
+ *
+ * The engine does not use this to move pages, CSS does that. It uses it to
+ * report `progress` to listeners, and only while someone is listening.
  */
 export function tween({ from, to, duration, ease = easings.linear, onUpdate }: TweenOptions): CancellableTween {
   let raf = 0;
   let done = false;
+  let finish: () => void;
   const promise = new Promise<void>((resolve) => {
+    finish = resolve;
     if (duration <= 0) {
       onUpdate(to);
       done = true;
@@ -61,6 +97,7 @@ export function tween({ from, to, duration, ease = easings.linear, onUpdate }: T
       if (done) return;
       const k = Math.min(1, (now - t0) / duration);
       onUpdate(from + (to - from) * ease(k));
+      if (done) return;
       if (k < 1) raf = requestAnimationFrame(step);
       else {
         done = true;
@@ -72,9 +109,41 @@ export function tween({ from, to, duration, ease = easings.linear, onUpdate }: T
   promise.cancel = () => {
     done = true;
     cancelAnimationFrame(raf);
+    finish();
   };
   return promise;
 }
 
+/**
+ * Commits the styles written so far, so the *next* write is seen as a change
+ * and starts a CSS transition from here instead of being collapsed into it.
+ * One forced layout per transition, in place of a frame of JavaScript per
+ * frame of animation.
+ */
+export function commitStyles(el: HTMLElement): void {
+  void el.offsetWidth;
+}
+
+/**
+ * Resolves once the CSS transitions of `properties` on these elements have
+ * finished. Nothing running resolves immediately: no transition started, a
+ * zero duration, `prefers-reduced-motion`, an element that is not being
+ * rendered. Interrupted animations reject, which counts as finished.
+ *
+ * Only the named properties are waited on, so an app is free to keep its own
+ * animation running on a page without stalling the stack.
+ */
+export function animationsFinished(els: Array<HTMLElement | null | undefined>, properties: readonly string[] = ['transform', 'opacity']): Promise<void> {
+  const running: Array<Promise<unknown>> = [];
+  for (const el of els) {
+    if (typeof el?.getAnimations !== 'function') continue;
+    for (const animation of el.getAnimations()) {
+      const property = (animation as { transitionProperty?: string }).transitionProperty;
+      if (property && properties.includes(property)) running.push(animation.finished.catch(() => {}));
+    }
+  }
+  return running.length ? Promise.all(running).then(() => {}) : Promise.resolve();
+}
+
 export const prefersReducedMotion = (): boolean =>
   typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;

package/src/edge-pan-gesture.ts

@@ -31,6 +31,8 @@ interface Drag {
   target: EventTarget & { setPointerCapture?(id: number): void };
   x0: number;
   y0: number;
+  /** +1 when back is a drag to the right, -1 when the container reads right-to-left */
+  dir: number;
   handle: InteractivePopHandle | null;
   p: number;
   samples: Array<[number, number]>;
@@ -41,6 +43,9 @@ interface Drag {
  * interactive pop from it. Built on pointer events, so it handles both mouse
  * and touch. Vertical movement early in the gesture hands the touch back to
  * native scrolling.
+ *
+ * "Leading" is whichever edge the container reads from, so in a right-to-left
+ * container the strip sits on the right and back is a drag to the left.
  */
 export function createEdgePanGesture(options: Partial<EdgePanGestureOptions> = {}): EdgePanGesture {
   const o: EdgePanGestureOptions = {
@@ -57,6 +62,20 @@ export function createEdgePanGesture(options: Partial<EdgePanGestureOptions> = {
 
   let stack: NavigationStack;
   let strip: HTMLElement | null = null;
+
+  /**
+   * Which way forward is, read the same way the pages read it: `--sn-dir` when
+   * the stylesheet sets it, the container's reading direction otherwise. Taking
+   * it from one place is what keeps the drag and the transition from disagreeing
+   * about which edge is the back edge.
+   */
+  const direction = (): number => {
+    const style = typeof getComputedStyle === 'function' ? getComputedStyle(stack.container) : null;
+    const declared = Number(style?.getPropertyValue('--sn-dir'));
+    if (declared < 0) return -1;
+    if (declared > 0) return 1;
+    return style?.direction === 'rtl' ? -1 : 1;
+  };
   let drag: Drag | null = null;
   let suppressClick = false;
   let offs: Array<() => void> = [];
@@ -64,13 +83,15 @@ export function createEdgePanGesture(options: Partial<EdgePanGestureOptions> = {
   const onDown = (ev: PointerEvent) => {
     if (drag || !stack.canPop()) return;
     if (ev.pointerType === 'mouse' && ev.button !== 0) return;
-    if (ev.currentTarget === stack.container && !o.anywhere) return;
-    drag = { id: ev.pointerId, target: ev.currentTarget as Drag['target'], x0: ev.clientX, y0: ev.clientY, handle: null, p: 1, samples: [[ev.clientX, performance.now()]] };
+    if (!o.anywhere && ev.target !== strip) return;
+    drag = { id: ev.pointerId, target: ev.currentTarget as Drag['target'], x0: ev.clientX, y0: ev.clientY, dir: direction(), handle: null, p: 1, samples: [[ev.clientX, performance.now()]] };
   };
 
   const onMove = (ev: PointerEvent) => {
     if (!drag || ev.pointerId !== drag.id) return;
-    const dx = ev.clientX - drag.x0;
+    // Signed so that "forward along the drag" is always positive, whichever
+    // edge the container calls leading.
+    const dx = (ev.clientX - drag.x0) * drag.dir;
     const dy = ev.clientY - drag.y0;
     if (!drag.handle) {
       if (Math.abs(dy) > o.verticalCancelSlop && Math.abs(dy) > Math.abs(dx)) {
@@ -104,7 +125,7 @@ export function createEdgePanGesture(options: Partial<EdgePanGestureOptions> = {
     const s = d.samples;
     const [x1, t1] = s[0];
     const [x2, t2] = s[s.length - 1];
-    const velocity = t2 > t1 ? ((x2 - x1) / (t2 - t1)) * 1000 : 0;
+    const velocity = (t2 > t1 ? ((x2 - x1) / (t2 - t1)) * 1000 : 0) * d.dir;
     const cancelled = ev.type === 'pointercancel';
     const complete = !cancelled && (velocity > o.completeVelocity || (d.p < 1 - o.completeThreshold && velocity > o.cancelVelocity));
     // The click that follows a drag release must not activate whatever is under the pointer.
@@ -126,10 +147,16 @@ export function createEdgePanGesture(options: Partial<EdgePanGestureOptions> = {
   const listen = (el: HTMLElement) => Object.entries(EVENTS).forEach(([k, f]) => el.addEventListener(k, f as EventListener));
   const unlisten = (el: HTMLElement) => Object.entries(EVENTS).forEach(([k, f]) => el.removeEventListener(k, f as EventListener));
 
+  /**
+   * Whether the strip is shown at all is a CSS question — the stylesheet hides
+   * it when there is nothing to go back to, or when the whole page is the
+   * target — so this only has to say what is true.
+   */
   const refresh = () => {
     if (!strip) return;
     strip.style.width = o.edgeWidth + 'px';
-    strip.style.display = o.anywhere || stack.entries.length < 2 ? 'none' : '';
+    stack.container.classList.toggle('sn-anywhere', o.anywhere);
+    stack.container.classList.toggle('sn-can-pop', stack.entries.length > 1);
   };
 
   const gesture: EdgePanGesture = {
@@ -138,10 +165,11 @@ export function createEdgePanGesture(options: Partial<EdgePanGestureOptions> = {
     attach(s) {
       stack = s;
       strip = document.createElement('div');
+      strip.className = 'sn-edge';
       strip.setAttribute('aria-hidden', 'true');
-      Object.assign(strip.style, { position: 'absolute', left: '0', top: '0', bottom: '0', zIndex: '10', touchAction: 'none' });
       stack.container.append(strip);
-      listen(strip);
+      // Pointer events from the strip bubble here; one listener per event
+      // avoids applying each move and recording its velocity sample twice.
       listen(stack.container);
       stack.container.addEventListener('click', onClick, true);
       offs = (['push', 'pop', 'replace', 'reset'] as const).map((e) => stack.on(e, refresh));
@@ -151,9 +179,9 @@ export function createEdgePanGesture(options: Partial<EdgePanGestureOptions> = {
     detach() {
       if (!strip) return;
       offs.forEach((f) => f());
-      unlisten(strip);
       unlisten(stack.container);
       stack.container.removeEventListener('click', onClick, true);
+      stack.container.classList.remove('sn-anywhere', 'sn-can-pop');
       strip.remove();
       strip = null;
     },

package/src/index.ts

@@ -24,7 +24,7 @@ export { createEdgePanGesture } from './edge-pan-gesture.ts';
 export type { EdgePanGesture, EdgePanGestureOptions } from './edge-pan-gesture.ts';
 export { attachBrowserHistory, isIOSBrowser } from './history-adapter.ts';
 export type { BrowserHistoryOptions } from './history-adapter.ts';
-export { cubicBezier, easings, tween, prefersReducedMotion } from './animate.ts';
+export { cubicBezier, easings, cssEasing, cssDuration, tween, commitStyles, animationsFinished, prefersReducedMotion } from './animate.ts';
 export type { Easing, TweenOptions, CancellableTween } from './animate.ts';
 export {
   resolveDirection,

package/src/ios-transition.ts

@@ -5,7 +5,13 @@ import type { SettleInput, StackEntry, Transition } from './navigation-stack.ts'
 export interface IOSTransitionOptions {
   /** ms, programmatic push/pop */
   duration: number;
-  /** the curve a programmatic push/pop runs on */
+  /**
+   * the curve a programmatic push/pop runs on. CSS runs it, so it has to be
+   * one CSS can spell: everything `cubicBezier()` and `parseEasing()` build
+   * carries a `css` property. A bare `(t) => number` of your own has none, so
+   * the pages would run `linear` while `progress` reported your curve; give it
+   * a `css` property, or write the whole transition yourself.
+   */
   ease: Easing;
   /** fraction of the width the lower page travels */
   parallax: number;
@@ -17,7 +23,7 @@ export interface IOSTransitionOptions {
   /** ms bounds for finishing an interactive pop */
   settleMin: number;
   settleMax: number;
-  /** the curve the remaining distance of an interactive pop runs on */
+  /** the curve the remaining distance of an interactive pop runs on; see `ease` */
   settleEase: Easing;
   /** px/s assumed when the pointer was slower than this */
   settleVelocityFloor: number;
@@ -53,9 +59,6 @@ export interface IOSTransition extends Transition {
   refresh(el?: Element | null): void;
 }
 
-const DIM = /*#__PURE__*/ Symbol('dim');
-type Dimmable = StackEntry & { [DIM]?: HTMLElement };
-
 /**
  * The iOS navigation transition: the upper page slides in from the trailing
  * edge with a shadow on its leading edge, while the lower page parallaxes
@@ -65,6 +68,11 @@ type Dimmable = StackEntry & { [DIM]?: HTMLElement };
  * `IOS_TRANSITION_CSS_VARS`), read when a transition starts. A variable that
  * is set wins over the JS option, so a stylesheet can slow the animation down
  * or restyle it per theme without the app rebuilding the transition.
+ *
+ * p is only ever written at the ends of a phase. The stack puts that phase's
+ * duration and curve in `--sn-t` / `--sn-e` and CSS interpolates between the
+ * two writes, so the animation costs a handful of style writes rather than one
+ * per page per frame, and runs on the compositor rather than the main thread.
  */
 export function createIOSTransition(options: Partial<IOSTransitionOptions> = {}): IOSTransition {
   const o: IOSTransitionOptions = {
@@ -102,21 +110,28 @@ export function createIOSTransition(options: Partial<IOSTransitionOptions> = {})
       settleVelocityFloor: parseNumber(read(v.settleVelocityFloor)) ?? o.settleVelocityFloor,
       timeScale: parseNumber(read(v.timeScale)) ?? o.timeScale,
     };
+    if (dim?.parentElement) dim.style.setProperty('--sn-dim-fallback', o.dimColor);
   };
 
-  const dimOf = (entry: Dimmable): HTMLElement => {
-    let d = entry[DIM];
-    if (!d) {
-      d = document.createElement('div');
-      d.setAttribute('aria-hidden', 'true');
-      Object.assign(d.style, { position: 'fixed', inset: '0', pointerEvents: 'none', opacity: '0', zIndex: '2147483647' });
-      entry[DIM] = d;
+  // One overlay, moved to whichever page is underneath. Everything about it
+  // except its opacity is a rule in the stylesheet; JS supplies the fallback colour.
+  let dim: HTMLElement | null = null;
+  const dimOf = (lower: StackEntry): HTMLElement => {
+    if (!dim) {
+      dim = document.createElement('div');
+      dim.className = 'sn-dim';
+      dim.setAttribute('aria-hidden', 'true');
     }
-    d.style.background = r.dimColor;
-    if (d.parentElement !== entry.el) entry.el.append(d);
-    return d;
+    dim.style.setProperty('--sn-dim-fallback', o.dimColor);
+    if (dim.parentElement !== lower.el) lower.el.append(dim);
+    return dim;
   };
 
+  /** Four decimals is well past a subpixel, and keeps the style strings short. */
+  const round = (n: number): number => Math.round(n * 1e4) / 1e4 || 0;
+  /** A share of the page's own width, signed by the stylesheet's reading direction. */
+  const shift = (fraction: number): string => `translate3d(calc(${round(fraction * 100)}% * var(--sn-dir,1)),0,0)`;
+
   return {
     options: o,
     get resolved(): Readonly<IOSTransitionOptions> {
@@ -139,25 +154,27 @@ export function createIOSTransition(options: Partial<IOSTransitionOptions> = {})
 
     begin(lower, upper) {
       refresh(upper.el.parentElement);
-      upper.el.style.boxShadow = r.shadow;
+      upper.el.style.boxShadow = `var(--sn-shadow, ${o.shadow})`;
       if (lower) dimOf(lower);
     },
+    /**
+     * The state at p, written declaratively. Two calls with `--sn-t` set to a
+     * duration make an animation; a call per pointer move with `--sn-t: 0s`
+     * makes a drag. Nothing here measures layout: the travel is a share of the
+     * page, so a resize mid-transition stays honest.
+     */
     apply(lower, upper, p) {
-      const w = upper.el.parentElement?.clientWidth ?? 0;
-      upper.el.style.transform = `translate3d(${(1 - p) * w}px,0,0)`;
+      upper.el.style.transform = shift(1 - p);
       if (lower) {
-        lower.el.style.transform = `translate3d(${-p * r.parallax * w}px,0,0)`;
-        dimOf(lower).style.opacity = String(p * r.dimMax);
+        lower.el.style.transform = shift(-p * r.parallax);
+        dim!.style.opacity = String(p * r.dimMax);
       }
     },
     end(lower, upper) {
       upper.el.style.boxShadow = '';
       upper.el.style.transform = '';
-      if (lower) {
-        lower.el.style.transform = '';
-        const d = (lower as Dimmable)[DIM];
-        if (d) d.remove();
-      }
+      if (lower) lower.el.style.transform = '';
+      dim?.remove();
     },
   };
 }

package/src/navigation-stack.ts

@@ -1,4 +1,4 @@
-import { tween, type Easing } from './animate.ts';
+import { animationsFinished, commitStyles, cssDuration, cssEasing, tween, type CancellableTween, type Easing } from './animate.ts';
 
 /** One mounted page. `key` and `data` belong to the caller; the stack only carries them. */
 export interface StackEntry<T = unknown> {
@@ -17,9 +17,17 @@ export interface SettleInput {
  * Describes what the pages look like at any progress p (1 = upper page fully
  * open, 0 = upper page fully off-screen). Push runs p from 0 to 1, pop from
  * 1 to 0.
+ *
+ * `apply` is a declarative write, not a frame. For a timed phase the stack
+ * calls it twice, once at each end, and CSS interpolates between them: the
+ * stack puts that phase's duration and curve in `--sn-t` / `--sn-e` on the
+ * container, which the stylesheet's `transition` rules read. During a drag
+ * `--sn-t` is `0s`, so the same write lands instantly. Keep `apply` to
+ * `transform` and `opacity` and the browser keeps it off the main thread.
  */
 export interface Transition {
   readonly duration: number;
+  /** Sampled to report `progress`; its `css` spelling is what drives the pixels. */
   readonly ease: Easing;
   settle(input: SettleInput): { duration: number; ease: Easing };
   begin?(lower: StackEntry | null, upper: StackEntry): void;
@@ -249,7 +257,7 @@ export class NavigationStack {
       finish: async ({ complete, velocity = 0 }) => {
         const remainingPx = (complete ? p : 1 - p) * this.width();
         const { duration, ease } = this.transition.settle({ remainingPx, velocity });
-        await tween({ from: p, to: complete ? 0 : 1, duration, ease, onUpdate: (v) => this._apply(lower, upper, v) });
+        await this._animate(lower, upper, p, complete ? 0 : 1, duration, ease);
         this._end(lower, upper, 'interactive');
         if (complete) {
           this.entries.pop();
@@ -265,7 +273,9 @@ export class NavigationStack {
 
   destroy(): void {
     while (this.entries.length) this._unmount(this.entries.pop()!);
-    this.container.classList.remove('sn-container');
+    this.container.classList.remove('sn-container', 'sn-busy');
+    this.container.style.removeProperty('--sn-t');
+    this.container.style.removeProperty('--sn-e');
   }
 
   // -------------------------------------------------------------- internals
@@ -315,7 +325,7 @@ export class NavigationStack {
     return { el, index, key, data };
   }
   private _unmount(entry: StackEntry): StackEntry {
-    entry.el.classList.remove(this.pageClass, 'sn-page-visible');
+    entry.el.classList.remove(this.pageClass, 'sn-page-visible', 'sn-page-upper', 'sn-page-lower');
     entry.el.style.transform = '';
     entry.el.remove();
     return entry;
@@ -328,9 +338,20 @@ export class NavigationStack {
     return this._unmount(entry);
   }
 
+  /**
+   * The duration and curve of the phase in flight, as CSS reads them. `0s`
+   * means land where you are told, now, which is what a drag wants and what
+   * `prefers-reduced-motion` reduces every phase to.
+   */
+  private _timing(duration: number, ease?: Easing): void {
+    this.container.style.setProperty('--sn-t', cssDuration(duration));
+    this.container.style.setProperty('--sn-e', cssEasing(ease));
+  }
+
   private _begin(lower: StackEntry | null, upper: StackEntry, kind: TransitionKind): void {
-    if (lower) lower.el.classList.add('sn-page-visible');
-    upper.el.classList.add('sn-page-visible');
+    this._timing(0);
+    lower?.el.classList.add('sn-page-visible', 'sn-page-lower');
+    upper.el.classList.add('sn-page-visible', 'sn-page-upper');
     this.transition.begin?.(lower, upper);
     this._emit('transitionstart', { lower, upper, kind });
   }
@@ -339,24 +360,56 @@ export class NavigationStack {
     this._emit('progress', { lower, upper, p });
   }
   private _end(lower: StackEntry | null, upper: StackEntry, kind: TransitionKind): void {
+    this._timing(0);
+    upper.el.classList.remove('sn-page-upper');
+    lower?.el.classList.remove('sn-page-lower');
     this.transition.end?.(lower, upper);
     this._emit('transitionend', { lower, upper, kind });
   }
+
+  /**
+   * Hands the run from `from` to `to` over to the browser: commit where the
+   * pages are, say how long and on what curve, write where they are going,
+   * then wait to be told they arrived. No frame of it is ours.
+   */
+  private async _animate(lower: StackEntry | null, upper: StackEntry, from: number, to: number, duration: number, ease: Easing): Promise<void> {
+    if (duration <= 0 || from === to) return this._apply(lower, upper, to);
+    commitStyles(upper.el);
+    this._timing(duration, ease);
+    this.transition.apply(lower, upper, to);
+    const ticker = this._ticker(lower, upper, from, to, duration, ease);
+    await animationsFinished([upper.el, lower?.el]);
+    ticker?.cancel();
+    this._timing(0);
+    this._emit('progress', { lower, upper, p: to });
+  }
+
+  /**
+   * `progress` used to be a by-product of animating in JS. Now that CSS
+   * animates, reporting it costs a frame loop, so one only runs while someone
+   * is subscribed. Chrome that just has to move with the pages is better off
+   * reading `--sn-t` / `--sn-e` and the `sn-page-upper` / `sn-page-lower`
+   * classes in CSS, which keeps it on the compositor too.
+   */
+  private _ticker(lower: StackEntry | null, upper: StackEntry, from: number, to: number, duration: number, ease: Easing): CancellableTween | null {
+    if (!this._listeners.get('progress')?.size) return null;
+    return tween({ from, to, duration, ease, onUpdate: (p) => this._emit('progress', { lower, upper, p }) });
+  }
+
   private async _transition(lower: StackEntry | null, upper: StackEntry, from: number, to: number, animated: boolean, kind: TransitionKind): Promise<void> {
     this._begin(lower, upper, kind);
     this._apply(lower, upper, from);
-    const duration = animated ? this.transition.duration : 0;
-    await tween({ from, to, duration, ease: this.transition.ease, onUpdate: (p) => this._apply(lower, upper, p) });
+    await this._animate(lower, upper, from, to, animated ? this.transition.duration : 0, this.transition.ease);
     this._end(lower, upper, kind);
   }
 
-  /** Makes only the top page visible, resets every transform, renumbers the indexes. */
+  /** Makes only the top page visible, returns every page to its resting state, renumbers the indexes. */
   private _settle(): void {
     const top = this.top;
     this.entries.forEach((e, i) => {
       e.index = i;
       e.el.classList.toggle('sn-page-visible', e === top);
-      e.el.style.transform = e === top ? 'translate3d(0,0,0)' : '';
+      e.el.style.transform = '';
     });
   }
 }

package/src/styles.ts

@@ -1,28 +1,61 @@
 /**
- * The only styles the engine needs. These cover layout, not appearance: the
- * look lives in the transition and is tuned through the `--sn-*` custom
- * properties (see `IOS_TRANSITION_CSS_VARS` and the README). Those properties
- * are documented but deliberately not declared, because leaving one unset is
- * what makes its JS default apply.
+ * The only styles the engine needs. These cover layout and the motion itself,
+ * not appearance: the look lives in the transition and is tuned through the
+ * `--sn-*` custom properties (see `IOS_TRANSITION_CSS_VARS` and the README).
+ * Those properties are documented but deliberately not declared, because
+ * leaving one unset is what makes its JS default apply.
+ *
+ * The engine does not animate the pages; the browser does. Each phase it
+ * writes `--sn-t` and `--sn-e` on the container — the duration and curve in
+ * force right now — and then writes where the pages should end up. While a
+ * pointer is down `--sn-t` is `0s`, so the page lands exactly where the
+ * pointer puts it; for a push, a pop or the settle after a release it is that
+ * phase's length and `transition` runs it out, on the compositor.
  *
  * The string is kept minified because it ships inside every consumer's JS
  * bundle (`injectStyles()` is the default path); `scripts/write-css.mjs`
  * expands it into the readable `dist/stacknav.css`. What each rule is for:
  *
  * - `.sn-container`: the stack's scroll-clipping frame.
+ * - `.sn-container:dir(rtl)`: reading direction is a CSS question, so the
+ *   transform the engine writes is signed by `--sn-dir` rather than by JS.
  * - `.sn-page`: absolutely fills the container and is its own scroll container.
  *   `touch-action: pan-y` keeps vertical scrolling native while horizontal
  *   drags reach the gesture; `visibility: hidden` keeps pages beneath the top
  *   mounted (scroll position, form state) but out of sight and out of the
- *   accessibility tree.
+ *   accessibility tree. The identity transform is the resting state, and the
+ *   containing block the dim overlay is positioned against.
  * - `.sn-page-visible`: the top page, and both pages during a transition.
- * - `.sn-busy .sn-page`: no clicks land on a page that is mid-transition.
+ * - `.sn-page-upper` / `.sn-page-lower`: the two pages taking part in the
+ *   transition in flight. Only these transition, and only these are promoted,
+ *   so a deep stack costs nothing at rest. Both `transform` and `opacity` are
+ *   listed, so a transition of your own can fade a page as well as move it and
+ *   still be run by the browser; the iOS look only ever changes `transform`,
+ *   and a property that does not change starts no transition.
+ * - `.sn-dim`: the overlay the lower page dims behind. CSS resolves its colour;
+ *   the transition supplies a fallback colour and writes its opacity.
+ * - `.sn-edge`: the strip the swipe-back gesture listens on. `inset-inline-start`
+ *   puts it on the leading edge in either reading direction; its width is the
+ *   gesture's `edgeWidth` option, and whether it is shown at all follows from
+ *   the container's classes.
+ * - `.sn-busy`: no clicks land on a page that is mid-transition, and a drag
+ *   does not select the text under it.
+ * - `prefers-reduced-motion`: forces the phase duration to zero in CSS. The
+ *   `!important` is intentional: it must override the inline `--sn-t` written
+ *   by the engine, including when the preference changes during a transition.
  */
 export const STACKNAV_CSS =
   '.sn-container{position:relative;overflow:hidden}' +
-  '.sn-page{position:absolute;inset:0;overflow-y:auto;overflow-x:hidden;-webkit-overflow-scrolling:touch;overscroll-behavior-y:contain;touch-action:pan-y;visibility:hidden;will-change:transform}' +
+  '.sn-container:dir(rtl){--sn-dir:-1}' +
+  '.sn-page{position:absolute;inset:0;overflow-y:auto;overflow-x:hidden;-webkit-overflow-scrolling:touch;overscroll-behavior-y:contain;touch-action:pan-y;visibility:hidden;transform:translate3d(0,0,0)}' +
   '.sn-page-visible{visibility:visible}' +
-  '.sn-busy .sn-page{pointer-events:none}';
+  '.sn-page-upper,.sn-page-lower{will-change:transform;transition-property:transform,opacity;transition-duration:var(--sn-t,0s);transition-timing-function:var(--sn-e,linear)}' +
+  '.sn-dim{position:fixed;inset:0;z-index:2147483647;pointer-events:none;background:var(--sn-dim-color,var(--sn-dim-fallback,#000));opacity:0;transition:opacity var(--sn-t,0s) var(--sn-e,linear)}' +
+  '.sn-edge{position:absolute;inset-block:0;inset-inline-start:0;z-index:10;touch-action:none}' +
+  '.sn-container:not(.sn-can-pop) .sn-edge,.sn-container.sn-anywhere .sn-edge{display:none}' +
+  '.sn-busy{user-select:none;-webkit-user-select:none}' +
+  '.sn-busy .sn-page{pointer-events:none}' +
+  '@media(prefers-reduced-motion:reduce){.sn-container{--sn-t:0s!important}}';
 
 export const STACKNAV_STYLE_ID = 'stacknav-styles';