@embedpdf/plugin-stage 3.0.0-next.6 → 3.0.0-next.8

package/dist/index.js

@@ -1,8 +1,151 @@
 import { createCapabilityToken, definePlugin } from "@embedpdf/core";
-import { InteractionToken } from "@embedpdf/plugin-interaction";
 import * as S from "@embedpdf/core-stage";
 import { ZoomMode, ZoomMode as ZoomMode$1 } from "@embedpdf/core-stage";
 import { addRotations, applyPoint, applyRect, displaySize, intersectRects, pageGeometry, pageTransform, rotateScaleMatrix, snapToDevice } from "@embedpdf/core-geometry";
+//#region src/motion.ts
+/**
+* The camera's MOTION vocabulary — every formula, pure.
+*
+* The capability owns the impure drivers (scheduler frames, dispatch, gesture
+* state); the LAWS those drivers integrate live here, parameterized by dt/t
+* with no state, no scheduler, no dispatch — unit-testable in isolation, and
+* with zero plugin dependencies, liftable into stage-core if the native port
+* ever wants them.
+*
+* Two families:
+*   • ballistic — one per-axis law for every free motion: `glideStep` (the
+*     touch fling, decaying on UIScrollView's curve) and `springStep` (a
+*     critically-damped return to the clamp). A glide that reaches a content
+*     edge converts to a spring with its velocity carried in, so the bounce
+*     grows out of physics rather than a scripted overshoot.
+*   • resistance — the iOS rubber-band curve `rubberOut` and its exact
+*     inverse `rubberIn`: dragging `d` px past an edge displays an
+*     asymptotically-bounded stretch, and re-entering a gesture over a
+*     stretched camera (the mid-bounce catch) reconstructs the
+*     finger-integrated position the curve came from.
+* Plus the tween interpolators: `easeOutCubic` for coordinate tweens and
+* `zoomLerp` — GEOMETRIC zoom interpolation (zoom is multiplicative; equal
+* ratios per unit time, not equal deltas — the linear lerp's visible "dip").
+*/
+/** Resistance coefficient of the rubber-band curve (the iOS feel). */
+const RUBBER = .55;
+/** Glide decay per ms — UIScrollView's normal deceleration rate. */
+const FLING_DECAY = .998;
+/** rad/ms — critically damped, ~400ms to settle. */
+const SPRING_OMEGA = .015;
+/**
+* Overshoot distance → displayed stretch: asymptotic to the viewport
+* dimension `dim`, so the content never leaves the screen however far the
+* finger travels. `rubberOut(0) === 0` — inside the bounds the curve is
+* invisible.
+*/
+const rubberOut = (d, dim) => (1 - 1 / (d * RUBBER / dim + 1)) * dim;
+/** Exact inverse of `rubberOut` (defined for `out < dim`). */
+const rubberIn = (out, dim) => out * dim / (RUBBER * (dim - out));
+/**
+* One frame of free glide: exponential velocity decay, position advanced by
+* the midpoint integral of the decay over `dt` (exact for the exponential —
+* frame-rate independent).
+*/
+const glideStep = (p, v, dt) => {
+	const k = Math.pow(FLING_DECAY, dt);
+	const np = p + v * (dt * (1 + k) / 2);
+	const nv = v * k;
+	return Math.abs(nv) < .02 ? {
+		p: np,
+		v: 0,
+		done: true
+	} : {
+		p: np,
+		v: nv,
+		done: false
+	};
+};
+/**
+* One frame of critically-damped spring toward `edge` — semi-implicit Euler
+* on x'' = −ω²(x−e) − 2ωx'. Lands exactly ON the edge (position snapped,
+* velocity zeroed) once inside half a pixel at negligible speed.
+*/
+const springStep = (p, v, edge, dt) => {
+	const nv = v + (-.015 * SPRING_OMEGA * (p - edge) - 2 * SPRING_OMEGA * v) * dt;
+	const np = p + nv * dt;
+	if (Math.abs(np - edge) < .5 && Math.abs(nv) < .01) return {
+		p: edge,
+		v: 0,
+		done: true
+	};
+	return {
+		p: np,
+		v: nv,
+		done: false
+	};
+};
+const easeOutCubic = (t) => 1 - Math.pow(1 - t, 3);
+/**
+* Geometric zoom interpolation: `z0·(z1/z0)^k`. Zoom is multiplicative, so a
+* constant-RATE zoom moves equal ratios per unit time; interpolating the
+* level linearly instead makes the start rush and the end crawl (and, under
+* a focal anchor, swings the anchored point along a curved path).
+*/
+const zoomLerp = (z0, z1, k) => z0 * Math.pow(z1 / z0, k);
+//#endregion
+//#region src/responsive.ts
+/**
+* Container queries for the settings bag — the pure half. The capability owns
+* the driver (when to re-resolve, how to react); the LAWS live here: what a
+* box is, when a query matches, and what the effective settings are. No state,
+* no dispatch — property-testable in isolation (the `wheel.ts` convention).
+*
+* The query vocabulary is deliberately just the box: a headless, DOM-free
+* stage knows exactly one environmental fact — the viewport it was told.
+* Anything else (pointer coarseness, platform, app state) is either per-event
+* (`PointerSample.pointerType`) or the app's own business via `update()`.
+*/
+/** The reported viewport as a queryable box. A square box is 'portrait' (CSS). */
+const boxOf = (vp) => ({
+	width: vp.width,
+	height: vp.height,
+	orientation: vp.height >= vp.width ? "portrait" : "landscape"
+});
+/** All bounds inclusive, all fields optional, conditions AND-ed (CSS ranges). */
+const matchesQuery = (q, box) => (q.minWidth === void 0 || box.width >= q.minWidth) && (q.maxWidth === void 0 || box.width <= q.maxWidth) && (q.minHeight === void 0 || box.height >= q.minHeight) && (q.maxHeight === void 0 || box.height <= q.maxHeight) && (q.orientation === void 0 || box.orientation === q.orientation);
+const ruleMatches = (rule, box) => typeof rule.when === "function" ? !!rule.when(box) : matchesQuery(rule.when, box);
+/** Merge a patch over settings, skipping undefined values (Partial semantics). */
+const mergeSettings = (into, patch) => {
+	const out = { ...into };
+	let key;
+	for (key in patch) {
+		const value = patch[key];
+		if (value !== void 0) Object.assign(out, { [key]: value });
+	}
+	return out;
+};
+/**
+* Setting-value equality: primitives by identity, the flat objects the
+* settings vocabulary uses (`{ px }`, `{ x, y }`, page frames, zoom specs) by
+* one level of own-key comparison. Settings values are never nested deeper.
+*/
+const eqSetting = (a, b) => {
+	if (a === b) return true;
+	if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false;
+	const ka = Object.keys(a);
+	const kb = Object.keys(b);
+	return ka.length === kb.length && ka.every((k) => a[k] === b[k]);
+};
+const resolveResponsive = (base, rules, box) => {
+	let effective = base;
+	const active = [];
+	for (const rule of rules) {
+		if (!ruleMatches(rule, box)) continue;
+		if (rule.name !== void 0) active.push(rule.name);
+		if (rule.settings) effective = mergeSettings(effective, rule.settings);
+	}
+	return {
+		effective,
+		active
+	};
+};
+//#endregion
 //#region src/settings.ts
 /**
 * Out-of-the-box defaults — a sensible document-reading feel. They are JUST
@@ -48,6 +191,18 @@ const DEFAULT_SETTINGS = {
 	scrollBehavior: "smooth",
 	viewUnitsPerPoint: 96 / 72
 };
+/**
+* Out-of-the-box responsive rules — the platform feel with zero configuration:
+* a compact container gets the thin gutter phones use (space, not device — an
+* embedded 500px pane on a desktop is compact too). Override the whole list
+* with `stagePlugin({ responsive: [...] })`; `responsive: []` opts out. The
+* 'compact' name is queryable app-side via `stage.matches('compact')`.
+*/
+const DEFAULT_RESPONSIVE = [{
+	name: "compact",
+	when: { maxWidth: 600 },
+	settings: { padding: 4 }
+}];
 const SETTINGS_EFFECT = {
 	flow: "reflow",
 	layout: "scene",
@@ -86,8 +241,9 @@ const settingsEqual = (a, b) => SETTING_KEYS.every((k) => valueEq(a[k], b[k]));
 * Layering, stated honestly:
 *   • stage-core — PURE spatial math (no DOM, no time). Ports to Rust later.
 *   • this capability — the IMPURE platform shell. It dispatches, caches, and owns
-*     the camera tween. It is NOT pure; the one host dependency it has (frame
-*     timing) enters through an injected Scheduler, never a hidden global.
+*     the camera tween. It is NOT pure; its one host dependency (frame timing)
+*     enters through the Scheduler seam — injectable, defaulting to the host's
+*     own frame clock when one exists (see the seam below).
 *
 * The model: EVERY camera move is defined by what it holds fixed.
 *   • gestures (pan/pinch/wheel)  — the content under the pointer. Physics, no setting.
@@ -373,11 +529,15 @@ function createStageCapability(ctx, config = {}) {
 		fitAlign: ctx.getState().fitAlign,
 		direction: ctx.getState().direction
 	});
-	let hasPlaced = false;
+	let placementStarted = false;
+	let gestureDepth = 0;
+	let gestureZoomed = false;
+	let gestureElastic = false;
+	let gestureRaw = null;
 	const REST_MS = 150;
 	let restRaf = 0;
 	const armRest = () => {
-		if (!canAnimate || !hasPlaced) return;
+		if (!canAnimate || !placementStarted) return;
 		if (ctx.getState().cameraResting) ctx.dispatch({
 			type: "CAMERA_REST",
 			resting: false
@@ -400,12 +560,69 @@ function createStageCapability(ctx, config = {}) {
 	};
 	const setCam = (next, bounds = stayBounds()) => {
 		const clamped = S.clampCamera(next, bounds, vp(), constraint());
-		if (clamped.zoom !== cam().zoom) armRest();
+		if (clamped.zoom !== cam().zoom) if (gestureDepth > 0) {
+			gestureZoomed = true;
+			if (ctx.getState().cameraResting) ctx.dispatch({
+				type: "CAMERA_REST",
+				resting: false
+			});
+			if (restRaf) {
+				scheduler.caf(restRaf);
+				restRaf = 0;
+			}
+		} else armRest();
 		ctx.dispatch({
 			type: "CAMERA",
 			camera: clamped
 		});
 	};
+	const axisTravels = (origin, content, view, zoom) => !S.travelRange(origin, content, view, zoom, constraint().padding).fits;
+	/** Unclamped finger-integrated camera → the DISPLAYED camera: clamp, then
+	*  re-apply the overshoot through the resistance curve, per travelling axis.
+	*  Inside the bounds this is exactly the clamp (rubber of zero is zero);
+	*  on a fitting axis it is exactly the clamp ALWAYS. */
+	const rubberize = (raw) => {
+		const clamped = S.clampCamera(raw, stayBounds(), vp(), constraint());
+		const v = vp();
+		const b = stayBounds();
+		const axis = (rawA, clampedA, dim, travels) => {
+			if (!travels) return clampedA;
+			const dWorld = rawA - clampedA;
+			if (dWorld === 0) return clampedA;
+			const out = rubberOut(Math.abs(dWorld) * raw.zoom, Math.max(1, dim));
+			return clampedA + Math.sign(dWorld) * out / raw.zoom;
+		};
+		return {
+			zoom: raw.zoom,
+			x: axis(raw.x, clamped.x, v.width, axisTravels(b.x, b.width, v.width, raw.zoom)),
+			y: axis(raw.y, clamped.y, v.height, axisTravels(b.y, b.height, v.height, raw.zoom))
+		};
+	};
+	/** Displayed camera → the raw position `rubberize` would have produced it
+	*  from. Overshoot is capped just under the asymptote so the inverse stays
+	*  finite whatever state a catch finds the camera in. */
+	const unrubberize = (displayed) => {
+		const clamped = S.clampCamera(displayed, stayBounds(), vp(), constraint());
+		const v = vp();
+		const b = stayBounds();
+		const axis = (dispA, clampedA, dim, travels) => {
+			if (!travels) return clampedA;
+			const dWorld = dispA - clampedA;
+			if (dWorld === 0) return clampedA;
+			const d = Math.max(1, dim);
+			const out = Math.min(Math.abs(dWorld) * displayed.zoom, d - 1);
+			return clampedA + Math.sign(dWorld) * rubberIn(out, d) / displayed.zoom;
+		};
+		return {
+			zoom: displayed.zoom,
+			x: axis(displayed.x, clamped.x, v.width, axisTravels(b.x, b.width, v.width, displayed.zoom)),
+			y: axis(displayed.y, clamped.y, v.height, axisTravels(b.y, b.height, v.height, displayed.zoom))
+		};
+	};
+	const setCamRaw = (c) => ctx.dispatch({
+		type: "CAMERA",
+		camera: c
+	});
 	/**
 	* Cursor reconciliation, one direction per interaction:
 	*   navigation  → cursor is INTENT, set explicitly; the camera honors it as far
@@ -439,7 +656,6 @@ function createStageCapability(ctx, config = {}) {
 		}
 		cancelAnim();
 		const from = cam();
-		const ease = (t) => 1 - Math.pow(1 - t, 3);
 		let started = false;
 		let t0 = 0;
 		const tick = (now) => {
@@ -447,7 +663,7 @@ function createStageCapability(ctx, config = {}) {
 				started = true;
 				t0 = now;
 			}
-			const k = ease(Math.min(1, (now - t0) / ms));
+			const k = easeOutCubic(Math.min(1, (now - t0) / ms));
 			setCam({
 				x: lerp(from.x, target.x, k),
 				y: lerp(from.y, target.y, k),
@@ -461,6 +677,116 @@ function createStageCapability(ctx, config = {}) {
 		};
 		raf = scheduler.raf(tick);
 	};
+	/**
+	* Zoom-anchored tween — animates THE INVARIANT, not the coordinates. A
+	* camera move is defined by what it holds fixed; for an anchored zoom that
+	* is "the focal page-point stays at `pt` while scale changes". Lerping
+	* x/y/zoom independently (the plain tween) breaks that mid-flight: holding
+	* a screen point requires `x(t) = focal.x − pt.x / zoom(t)` — hyperbolic in
+	* the zoom — so linear coordinates swing the tapped point along a curved
+	* path (the visible "dip"). Here the zoom interpolates GEOMETRICALLY
+	* (constant rate — zoom is multiplicative) and each frame's camera derives
+	* from the anchor at that zoom, then clamps: the focal point is stationary
+	* by construction, and a zoom-out rails into its fit progressively as the
+	* shrinking travel range lets the clamp take over.
+	*/
+	const animateZoomAnchored = (focal, pt, targetZoom, ms = 240, then) => {
+		if (!canAnimate) {
+			const sc = buildScene();
+			if (sc.itemCount) setCam(S.cameraForAnchorAtScreen(focal, sc, pt, targetZoom));
+			then?.();
+			return;
+		}
+		cancelAnim();
+		const z0 = cam().zoom;
+		let started = false;
+		let t0 = 0;
+		const tick = (now) => {
+			if (!started) {
+				started = true;
+				t0 = now;
+			}
+			const k = easeOutCubic(Math.min(1, (now - t0) / ms));
+			const z = zoomLerp(z0, targetZoom, k);
+			const sc = buildScene();
+			if (sc.itemCount) setCam(S.cameraForAnchorAtScreen(focal, sc, pt, z));
+			if (k < 1) raf = scheduler.raf(tick);
+			else {
+				raf = 0;
+				then?.();
+			}
+		};
+		raf = scheduler.raf(tick);
+	};
+	const startCameraPhysics = (vxFinger, vyFinger) => {
+		if (!canAnimate) {
+			setCam(cam());
+			return;
+		}
+		cancelAnim();
+		const zoom = cam().zoom;
+		const c0 = cam();
+		const cl0 = S.clampCamera(c0, stayBounds(), vp(), constraint());
+		const b0 = stayBounds();
+		const v0 = vp();
+		const mk = (camA, clampedA, fingerV) => ({
+			p: camA * zoom,
+			v: -fingerV / 1e3,
+			springing: camA !== clampedA,
+			done: false
+		});
+		const ax = mk(c0.x, cl0.x, axisTravels(b0.x, b0.width, v0.width, zoom) ? vxFinger : 0);
+		const ay = mk(c0.y, cl0.y, axisTravels(b0.y, b0.height, v0.height, zoom) ? vyFinger : 0);
+		if (!ax.springing && !ay.springing && Math.hypot(ax.v, ay.v) < .02) return;
+		let started = false;
+		let last = 0;
+		const tick = (now) => {
+			raf = 0;
+			const dt = started ? Math.min(64, Math.max(1, now - last)) : 16;
+			started = true;
+			last = now;
+			const cl = S.clampCamera({
+				x: ax.p / zoom,
+				y: ay.p / zoom,
+				zoom
+			}, stayBounds(), vp(), constraint());
+			const step = (a, edgeWorld) => {
+				if (a.done) return;
+				const r = a.springing ? springStep(a.p, a.v, edgeWorld * zoom, dt) : glideStep(a.p, a.v, dt);
+				a.p = r.p;
+				a.v = r.v;
+				a.done = r.done;
+			};
+			step(ax, cl.x);
+			step(ay, cl.y);
+			const ncl = S.clampCamera({
+				x: ax.p / zoom,
+				y: ay.p / zoom,
+				zoom
+			}, stayBounds(), vp(), constraint());
+			const convert = (a, clampedA) => {
+				if (!a.springing && Math.abs(clampedA * zoom - a.p) > 1e-6) {
+					a.p = clampedA * zoom;
+					a.springing = true;
+					a.done = false;
+				}
+			};
+			convert(ax, ncl.x);
+			convert(ay, ncl.y);
+			setCamRaw({
+				x: ax.p / zoom,
+				y: ay.p / zoom,
+				zoom
+			});
+			syncCursorFromCamera();
+			if (ax.done && ay.done) {
+				setCam(cam());
+				return;
+			}
+			raf = scheduler.raf(tick);
+		};
+		raf = scheduler.raf(tick);
+	};
 	const anchorAt = (at) => {
 		const sc = buildScene();
 		return sc.itemCount ? S.anchorFromCamera(cam(), sc, vp(), at) : {
@@ -627,8 +953,19 @@ function createStageCapability(ctx, config = {}) {
 			visibleRect
 		};
 	};
+	const EMPTY_SCROLL_METRICS = {
+		scrollLeft: 0,
+		scrollTop: 0,
+		scrollWidth: 0,
+		scrollHeight: 0,
+		clientWidth: 0,
+		clientHeight: 0,
+		scrollableX: false,
+		scrollableY: false
+	};
 	let scrollMemo = null;
 	const scrollMetricsNow = () => {
+		if (!ctx.getState().placed) return EMPTY_SCROLL_METRICS;
 		const sc = buildScene();
 		const m = S.scrollMetrics(cam(), sc.itemCount ? stayBounds() : {
 			x: 0,
@@ -641,9 +978,11 @@ function createStageCapability(ctx, config = {}) {
 		scrollMemo = m;
 		return m;
 	};
+	const EMPTY_VISIBLE_PAGES = [];
 	let visSig = "";
 	let vis = [];
 	const visiblePages = () => {
+		if (!ctx.getState().placed) return EMPTY_VISIBLE_PAGES;
 		const c = cam();
 		const v = vp();
 		const sc = buildScene();
@@ -660,6 +999,72 @@ function createStageCapability(ctx, config = {}) {
 		return out;
 	};
 	const snapshotSettings = () => pickSettings(ctx.getState());
+	/**
+	* Settings change, reacted per the registry — the strongest effect among the
+	* touched settings wins: 'reflow' ⊃ 'scene'/'refit' ⊃ 'reclamp' ⊃ 'none'.
+	* The ONE reactive applier: the public `update()` and the responsive driver
+	* both land here, so a breakpoint crossing gets exactly the invariant a
+	* hand-written update would.
+	*/
+	const applySettings = (patch) => {
+		cancelAnim();
+		const touched = (effect) => SETTING_KEYS.some((k) => patch[k] !== void 0 && SETTINGS_EFFECT[k] === effect);
+		const align = touched("refit") && !touched("scene") && !touched("reflow") ? ctx.getState().zoomAlign : ctx.getState().anchorAlign;
+		const anchor = anchorAt(alignPoint(align, vp()));
+		ctx.dispatch({
+			type: "PATCH",
+			patch
+		});
+		if (touched("scene")) sceneCache = null;
+		if (touched("reflow")) goToTarget(ctx.getState().cursor, { behavior: "instant" });
+		else if (touched("scene") || touched("refit")) reapply(anchor, align);
+		else if (touched("reclamp")) setCam(cam());
+	};
+	let base = snapshotSettings();
+	let rules = config.responsive ?? DEFAULT_RESPONSIVE;
+	let lastEffective = base;
+	const publishActive = (active) => {
+		const prev = ctx.getState().activeRules;
+		if (prev.length !== active.length || active.some((n, i) => n !== prev[i])) ctx.dispatch({
+			type: "RESPONSIVE",
+			active
+		});
+	};
+	/**
+	* Re-resolve and apply what CHANGED since the last resolution. `react: true`
+	* routes the patch through `applySettings` (full anchor-preserving update);
+	* `react: false` (inside `setViewport`, whose caller runs its own reframe)
+	* just lands the patch + cache invalidation and reports the strongest
+	* effect so the caller can escalate a rule-driven flow flip.
+	*/
+	const syncResponsive = (react) => {
+		const { effective, active } = resolveResponsive(base, rules, boxOf(vp()));
+		const patch = {};
+		for (const k of SETTING_KEYS) if (!eqSetting(effective[k], lastEffective[k])) Object.assign(patch, { [k]: effective[k] });
+		lastEffective = effective;
+		publishActive(active);
+		const keys = Object.keys(patch);
+		if (keys.length === 0) return "none";
+		if (react) {
+			applySettings(patch);
+			return "none";
+		}
+		ctx.dispatch({
+			type: "PATCH",
+			patch
+		});
+		const rank = {
+			none: 0,
+			reclamp: 1,
+			refit: 2,
+			scene: 3,
+			reflow: 4
+		};
+		let strongest = "none";
+		for (const k of keys) if (rank[SETTINGS_EFFECT[k]] > rank[strongest]) strongest = SETTINGS_EFFECT[k];
+		if (strongest === "scene" || strongest === "reflow") sceneCache = null;
+		return strongest;
+	};
 	const initialViewProviders = [];
 	const api = {
 		camera: cam,
@@ -678,6 +1083,7 @@ function createStageCapability(ctx, config = {}) {
 			label: p.label ?? null
 		})),
 		pageRect: (pon) => {
+			if (!ctx.getState().placed) return null;
 			const meta = ctx.document();
 			const index = meta ? meta.pages.findIndex((p) => p.pageObjectNumber === pon) : -1;
 			if (index < 0) return null;
@@ -778,11 +1184,12 @@ function createStageCapability(ctx, config = {}) {
 			anchor: currentAnchor()
 		}),
 		setViewport: (v) => {
-			if (!hasPlaced) {
+			if (!placementStarted) {
 				ctx.dispatch({
 					type: "VP",
 					vp: v
 				});
+				syncResponsive(false);
 				if (v.width > 0 && v.height > 0 && (ctx.document()?.pageCount ?? 0) > 0) api.placeInitial();
 				return;
 			}
@@ -792,7 +1199,8 @@ function createStageCapability(ctx, config = {}) {
 				type: "VP",
 				vp: v
 			});
-			reapply(anchor);
+			if (syncResponsive(false) === "reflow") goToTarget(ctx.getState().cursor, { behavior: "instant" });
+			else reapply(anchor);
 		},
 		setDevicePixelRatio: (ratio) => {
 			if (ratio > 0 && ratio !== dpr()) ctx.dispatch({
@@ -807,7 +1215,10 @@ function createStageCapability(ctx, config = {}) {
 		},
 		panBy: (dx, dy) => {
 			cancelAnim();
-			setCam(S.panByScreen(cam(), dx, dy));
+			if (gestureDepth > 0 && gestureElastic) {
+				gestureRaw = S.panByScreen(gestureRaw ?? unrubberize(cam()), dx, dy);
+				setCamRaw(rubberize(gestureRaw));
+			} else setCam(S.panByScreen(cam(), dx, dy));
 			syncCursorFromCamera();
 		},
 		scrollTo: (opts) => {
@@ -833,13 +1244,71 @@ function createStageCapability(ctx, config = {}) {
 			const before = buildScene();
 			const focal = before.itemCount ? S.anchorAtPoint(before, S.toWorld(cam(), pt)) : null;
 			setCam(S.zoomAround(cam(), pt, factor));
-			ctx.dispatch({
+			if (gestureDepth === 0) ctx.dispatch({
 				type: "PATCH",
 				patch: { zoom: { level: cam().zoom } }
 			});
 			const after = buildScene();
 			if (after !== before && focal && after.itemCount) setCam(S.cameraForAnchorAtScreen(focal, after, pt, cam().zoom));
+			if (gestureDepth > 0 && gestureElastic) gestureRaw = unrubberize(cam());
+			syncCursorFromCamera();
+		},
+		beginGesture: (options) => {
+			gestureDepth++;
+			if (gestureDepth === 1) {
+				cancelAnim();
+				gestureZoomed = false;
+				gestureElastic = options?.elastic === true;
+				gestureRaw = null;
+			}
+		},
+		endGesture: () => {
+			if (gestureDepth === 0) return;
+			gestureDepth--;
+			if (gestureDepth > 0) return;
+			gestureRaw = null;
+			const wasElastic = gestureElastic;
+			gestureElastic = false;
+			if (gestureZoomed) {
+				gestureZoomed = false;
+				ctx.dispatch({
+					type: "PATCH",
+					patch: { zoom: { level: cam().zoom } }
+				});
+				armRest();
+			}
 			syncCursorFromCamera();
+			if (wasElastic) {
+				const c = cam();
+				const cl = S.clampCamera(c, stayBounds(), vp(), constraint());
+				if (cl.x !== c.x || cl.y !== c.y) startCameraPhysics(0, 0);
+			}
+		},
+		fling: (vx, vy) => startCameraPhysics(vx, vy),
+		cameraInMotion: () => raf !== 0,
+		doubleTapZoom: (pt) => {
+			cancelAnim();
+			const sc0 = buildScene();
+			if (!sc0.itemCount) return;
+			const item = paged() ? sc0.items[0] : sc0.items[itemIndexOfPage(ctx.getState().cursor)];
+			const fit = fitBox(item);
+			const auto = S.resolveZoom({ mode: S.ZoomMode.Automatic }, fit, vp(), pad());
+			const stops = [
+				auto,
+				S.resolveZoom({ mode: S.ZoomMode.FitWidth }, fit, vp(), pad()),
+				Math.min(auto * 2.5, S.ZOOM_MAX)
+			].sort((a, b) => a - b).filter((z, i, all) => i === 0 || z > all[i - 1] * 1.1);
+			const near = (z, stop) => z > stop / 1.1 && z < stop * 1.1;
+			const onRung = stops.findIndex((s) => near(cam().zoom, s));
+			const target = onRung >= 0 ? stops[(onRung + 1) % stops.length] : stops[0];
+			ctx.dispatch({
+				type: "PATCH",
+				patch: { zoom: { level: target } }
+			});
+			const sc = buildScene();
+			if (!sc.itemCount) return;
+			const focal = S.anchorAtPoint(sc, S.toWorld(cam(), pt));
+			animateZoomAnchored(focal, pt, target, 240, syncCursorFromCamera);
 		},
 		zoomIn: () => api.zoomAround(alignPoint(ctx.getState().zoomAlign, vp()), 1.2),
 		zoomOut: () => api.zoomAround(alignPoint(ctx.getState().zoomAlign, vp()), 1 / 1.2),
@@ -849,7 +1318,7 @@ function createStageCapability(ctx, config = {}) {
 		fitAll: () => api.update({ zoom: { mode: S.ZoomMode.FitAll } }),
 		automatic: () => api.update({ zoom: { mode: S.ZoomMode.Automatic } }),
 		refit: () => {
-			if (!hasPlaced) return;
+			if (!placementStarted) return;
 			cancelAnim();
 			reapply(currentAnchor());
 		},
@@ -924,20 +1393,17 @@ function createStageCapability(ctx, config = {}) {
 		},
 		next: (opts) => step(1, opts),
 		prev: (opts) => step(-1, opts),
+		lensId: () => ctx.id,
 		update: (patch) => {
-			cancelAnim();
-			const touched = (effect) => SETTING_KEYS.some((k) => patch[k] !== void 0 && SETTINGS_EFFECT[k] === effect);
-			const align = touched("refit") && !touched("scene") && !touched("reflow") ? ctx.getState().zoomAlign : ctx.getState().anchorAlign;
-			const anchor = anchorAt(alignPoint(align, vp()));
-			ctx.dispatch({
-				type: "PATCH",
-				patch
-			});
-			if (touched("scene")) sceneCache = null;
-			if (touched("reflow")) goToTarget(ctx.getState().cursor, { behavior: "instant" });
-			else if (touched("scene") || touched("refit")) reapply(anchor, align);
-			else if (touched("reclamp")) setCam(cam());
+			base = mergeSettings(base, patch);
+			syncResponsive(true);
 		},
+		setResponsive: (next) => {
+			rules = next;
+			syncResponsive(true);
+		},
+		matches: (name) => ctx.getState().activeRules.includes(name),
+		activeRules: () => ctx.getState().activeRules,
 		setFlow: (flow) => api.update({ flow }),
 		setLayout: (layout) => api.update({ layout }),
 		setSpread: (spread) => api.update({ spread }),
@@ -957,9 +1423,13 @@ function createStageCapability(ctx, config = {}) {
 		setScrollBehavior: (behavior) => api.update({ scrollBehavior: behavior }),
 		applyViewState: (view) => {
 			cancelAnim();
+			base = mergeSettings(base, pickSettings(view));
+			const { effective, active } = resolveResponsive(base, rules, boxOf(vp()));
+			lastEffective = effective;
+			publishActive(active);
 			ctx.dispatch({
 				type: "PATCH",
-				patch: pickSettings(view)
+				patch: effective
 			});
 			ctx.dispatch({
 				type: "CURSOR",
@@ -975,62 +1445,24 @@ function createStageCapability(ctx, config = {}) {
 			});
 		},
 		placeInitial: () => {
-			hasPlaced = true;
+			placementStarted = true;
 			const sorted = [...initialViewProviders].sort((a, b) => b.priority - a.priority);
 			for (const p of sorted) {
 				const view = p.fn();
 				if (view) {
 					api.applyViewState(view);
+					ctx.dispatch({ type: "PLACED" });
 					return;
 				}
 			}
 			api.resetView();
+			ctx.dispatch({ type: "PLACED" });
 		},
 		resetView: () => goToTarget(0, { behavior: "instant" })
 	};
 	return api;
 }
 //#endregion
-//#region src/scroll-handler.ts
-/**
-* Pan-the-camera as an interaction handler. Live under the built-in `pan` tool
-* (the `scroll` tag) and — with `panFallback` — under every tool, where it then
-* captures ONLY page-gap drags (on-page downs belong to the active tool, which
-* claims them first at higher priority). It uses the sample's viewport delta, so
-* it pans over the whole viewport (pages and gaps).
-*
-* Cursor feel: a closed hand (`grabbing`) while dragging; an open hand (`grab`)
-* hovering a gap under a non-pan tool. The pan tool's own resting `grab` comes
-* from its `Tool.cursor`, so hovering it needs no claim here.
-*/
-function createScrollHandler(stage, interaction, options = {}) {
-	const panFallback = options.panFallback ?? true;
-	let last = {
-		x: 0,
-		y: 0
-	};
-	const isPanTool = () => interaction.activeTool().enables.has("scroll");
-	return {
-		id: "stage-scroll",
-		priority: 10,
-		enabledFor: (tool) => tool.enables.has("scroll") || panFallback,
-		onDown: (s) => {
-			if (!isPanTool() && s.page) return false;
-			last = s.viewport;
-			interaction.setCursor("stage-grab", "grabbing", 40);
-			return true;
-		},
-		onMove: (s) => {
-			stage.panBy(s.viewport.x - last.x, s.viewport.y - last.y);
-			last = s.viewport;
-		},
-		onUp: () => interaction.setCursor("stage-grab", null),
-		onHover: (s) => {
-			if (panFallback && !isPanTool()) interaction.setCursor("stage-pan-fallback", s.page ? null : "grab", 5);
-		}
-	};
-}
-//#endregion
 //#region src/effects.ts
 /**
 * The one effect a stage lens needs: when the document's page registry changes
@@ -1053,13 +1485,14 @@ function registerStageEffects(ctx, token) {
 //#endregion
 //#region src/reducer.ts
 const initialStageState = (config) => {
-	const { scheduler: _scheduler, ...overrides } = config;
+	const { scheduler: _scheduler, responsive: _responsive, ...overrides } = config;
 	return {
 		camera: {
 			x: 0,
 			y: 0,
 			zoom: 1
 		},
+		placed: false,
 		cameraResting: true,
 		vp: {
 			width: 0,
@@ -1067,6 +1500,7 @@ const initialStageState = (config) => {
 		},
 		dpr: 1,
 		cursor: 0,
+		activeRules: [],
 		...DEFAULT_SETTINGS,
 		...overrides
 	};
@@ -1096,6 +1530,10 @@ const stageReducer = (state, a) => {
 			...state,
 			cameraResting: a.resting
 		};
+		case "PLACED": return state.placed ? state : {
+			...state,
+			placed: true
+		};
 		case "VP": return {
 			...state,
 			vp: a.vp
@@ -1109,6 +1547,10 @@ const stageReducer = (state, a) => {
 			cursor: a.cursor
 		};
 		case "PATCH": return applyPatch(state, a.patch);
+		case "RESPONSIVE": return {
+			...state,
+			activeRules: a.active
+		};
 		default: return state;
 	}
 };
@@ -1123,19 +1565,14 @@ const StageToken = createCapabilityToken("stage");
 * sibling files.
 */
 const stagePlugin = (options = {}) => {
-	const { id = "stage", token = StageToken, interaction = false, panFallback = true, ...config } = options;
+	const { id = "stage", token = StageToken, ...config } = options;
 	return definePlugin({
 		id,
 		token,
 		scope: "document",
-		optional: interaction ? [InteractionToken] : void 0,
 		initialState: () => initialStageState(config),
 		reduce: stageReducer,
 		capability: (ctx) => createStageCapability(ctx, config),
-		init: interaction ? (ctx) => {
-			const ix = ctx.tryGet(InteractionToken);
-			if (ix) ix.registerHandler(createScrollHandler(ctx.get(token), ix, { panFallback }));
-		} : void 0,
 		effects: (ctx) => registerStageEffects(ctx, token)
 	});
 };
@@ -1282,19 +1719,46 @@ function destinationToReveal(dest, layout, bbox) {
 	};
 }
 //#endregion
-//#region src/wheel.ts
-/** The per-notch step for discrete wheels — the zoom buttons' ratio. */
-const NOTCH = 1.2;
-/** Zoom factor for a ctrl/cmd wheel event (the caller decides zoom vs pan). */
-function wheelZoomFactor(e) {
-	if (e.deltaMode !== 0) return Math.pow(NOTCH, -Math.sign(e.deltaY));
-	if (e.ctrlKey) {
-		if (Math.abs(e.deltaY) >= 100) return Math.pow(NOTCH, -Math.sign(e.deltaY));
-		return Math.exp(-e.deltaY / 100);
-	}
-	return Math.exp(-e.deltaY * .0015);
+//#region src/scroll-handler.ts
+/**
+* Pan-the-camera as an interaction handler. Live under the built-in `pan` tool
+* (the `scroll` tag) and — with `panFallback` — under every tool, where it then
+* captures ONLY page-gap drags (on-page downs belong to the active tool, which
+* claims them first at higher priority). It uses the sample's viewport delta, so
+* it pans over the whole viewport (pages and gaps).
+*
+* Cursor feel: a closed hand (`grabbing`) while dragging; an open hand (`grab`)
+* hovering a gap under a non-pan tool. The pan tool's own resting `grab` comes
+* from its `Tool.cursor`, so hovering it needs no claim here.
+*/
+function createScrollHandler(stage, interaction, options = {}) {
+	const panFallback = options.panFallback ?? true;
+	let last = {
+		x: 0,
+		y: 0
+	};
+	const isPanTool = () => interaction.activeTool().enables.has("scroll");
+	return {
+		id: "stage-scroll",
+		priority: 10,
+		enabledFor: (tool) => tool.enables.has("scroll") || panFallback,
+		onDown: (s) => {
+			if (!isPanTool() && s.page) return false;
+			last = s.viewport;
+			interaction.setCursor("stage-grab", "grabbing", 40);
+			return true;
+		},
+		onMove: (s) => {
+			stage.panBy(s.viewport.x - last.x, s.viewport.y - last.y);
+			last = s.viewport;
+		},
+		onUp: () => interaction.setCursor("stage-grab", null),
+		onHover: (s) => {
+			if (panFallback && !isPanTool()) interaction.setCursor("stage-pan-fallback", s.page ? null : "grab", 5);
+		}
+	};
 }
 //#endregion
-export { DEFAULT_SETTINGS, StageToken, ZoomMode, destinationToReveal, settingsEqual, stagePlugin, wheelZoomFactor };
+export { DEFAULT_RESPONSIVE, DEFAULT_SETTINGS, StageToken, ZoomMode, boxOf, createScrollHandler, destinationToReveal, matchesQuery, resolveResponsive, settingsEqual, stagePlugin };
 
 //# sourceMappingURL=index.js.map