@embedpdf/plugin-stage 3.0.0-next.13 → 3.0.0-next.15

package/dist/index.js

@@ -1,20 +1,149 @@
-import { destinationToReveal } from "./destination.js";
-import { n as StageToken, t as ZoomMode } from "./contract-CPSX8ANN.js";
-import { definePlugin } from "@embedpdf/core";
+import { n as StageToken, t as ZoomMode } from "./contract-BoOt8rJM.js";
+import { composeApi, createHostToken, definePlugin, defineState, memo, toPageRef } from "@embedpdf/core";
 import { ActionsToken } from "@embedpdf/plugin-actions/contract";
 import { ActionsToken as ActionsToken$1 } from "@embedpdf/plugin-actions/contract/host";
-import * as S from "@embedpdf/core-stage";
-import { ZoomMode as ZoomMode$1 } from "@embedpdf/core-stage";
-import { addRotations, applyPoint, applyRect, displaySize, intersectRects, pageTransform, rotateScaleMatrix, snapToDevice } from "@embedpdf/core-geometry";
+import { ZOOM_MAX, ZoomMode as ZoomMode$1, anchorAtPoint, anchorFromCamera, cameraForAnchorAtScreen, cameraFromAnchor, cameraFromScroll, cameraWorldRect, clampCamera, gridLayout, groupPages, linearLayout, panByScreen, placeCamera, resolveZoom, revealCamera, scrollMetrics, toScreen, toWorld, travelRange, zoomAround } from "@embedpdf/core-stage";
+import { NO_FRAME, addRotations, applyPoint, applyRect, displaySize, intersectRects, pageTransform, rotateScaleMatrix, snapToDevice } from "@embedpdf/core-geometry";
+//#region src/working-set.ts
+/** A lens's working set, from the pages it lays out. */
+function workingSetOf(pages) {
+	return pages.map(({ ref, visibleRect, transform }) => {
+		if (visibleRect.width <= 0 || visibleRect.height <= 0) return {
+			page: ref,
+			role: "near",
+			pixels: 0
+		};
+		const pixels = visibleRect.width * visibleRect.height * transform.renderScale ** 2;
+		return {
+			page: ref,
+			role: "visible",
+			visible: visibleRect,
+			pixels: Math.round(pixels)
+		};
+	});
+}
+/**
+* Tells the engine what the lens shows, now and whenever it changes: once per
+* camera move, so at most once per input event while the camera moves.
+*/
+function connectWorkingSet(ctx, stage) {
+	let told = "";
+	const tell = (shown) => {
+		const pages = workingSetOf(shown);
+		const key = keyOf(pages);
+		if (key === told) return;
+		told = key;
+		ctx.doc.setWorkingSet(ctx.id, pages);
+	};
+	ctx.watch(() => stage.listVisiblePages(), tell);
+	tell(stage.listVisiblePages());
+}
+/** A working set as one comparable string. */
+function keyOf(pages) {
+	return pages.map(({ page, role, visible, pixels }) => {
+		const part = visible ? `${Math.round(visible.x)},${Math.round(visible.y)},${Math.round(visible.width)},${Math.round(visible.height)}` : "";
+		return `${page.objectNumber}:${role}:${pixels}:${part}`;
+	}).join("|");
+}
+//#endregion
+//#region src/connect.ts
+/** The id of the main lens; additional lenses register under their own id. */
+const DEFAULT_LENS_ID = "stage";
+function connectStage(ctx, stage) {
+	ctx.watch(() => ctx.document()?.revision ?? 0, () => stage.refit());
+	connectWorkingSet(ctx, stage);
+	if (ctx.id !== "stage") return;
+	const actions = ctx.tryGet(ActionsToken$1);
+	if (!actions) return;
+	feedPageState(ctx, stage, actions);
+	registerNavigationExecutors(ctx, stage, actions);
+}
+/**
+* The page-state feed. The stage is authoritative for what page the viewer is
+* on; the actions plugin's lifecycle coordinator owns when page-lifecycle
+* triggers fire. The feed reports `{ currentPage, visiblePages, placed, cause }`
+* (page refs, not indexes, so reordering is safe) on placement and on every
+* change; the coordinator buffers reports until the document has opened and
+* diffs them against what it last emitted, so this side only reports.
+*/
+function feedPageState(ctx, stage, actions) {
+	const snapshot = () => {
+		const state = ctx.state.get();
+		if (!state.placed) return null;
+		return {
+			currentPage: stage.getCurrentPage(),
+			visiblePages: stage.listVisiblePages().map((page) => page.ref),
+			cause: state.motionCause
+		};
+	};
+	ctx.watch(() => {
+		const current = snapshot();
+		return current === null ? "unplaced" : `${current.currentPage?.objectNumber ?? -1}|${current.visiblePages.map((page) => page.objectNumber).sort((left, right) => left - right).join(",")}`;
+	}, () => {
+		const current = snapshot();
+		if (current === null) return;
+		actions.reportPageState({
+			currentPage: current.currentPage,
+			visiblePages: current.visiblePages,
+			placed: true,
+			cause: current.cause
+		});
+	});
+}
+/**
+* The GoTo and Named page verbs for the action engine. The dispatcher runs
+* them as deferred navigation effects, after every document node of a tree
+* succeeded, never in the middle of a walk. They move the view by its own
+* `scrollBehavior` setting, as a link does. /N Print is not handled here: the
+* dispatcher owns it (policy and the UI adapter).
+*/
+function registerNavigationExecutors(ctx, stage, actions) {
+	ctx.cleanup(actions.registerExecutor("goto", (node) => {
+		if (node.type !== "goto") return {
+			status: "inert",
+			reason: "not a goto node"
+		};
+		if (!ctx.getPage(node.destination.page)) return {
+			status: "failed",
+			error: "the destination page is not in this document"
+		};
+		stage.goToDestination(node.destination);
+		return { status: "executed" };
+	}));
+	ctx.cleanup(actions.registerExecutor("named", (node) => {
+		if (node.type !== "named") return {
+			status: "inert",
+			reason: "not a named node"
+		};
+		switch (node.name) {
+			case "NextPage":
+				stage.nextPage();
+				return { status: "executed" };
+			case "PrevPage":
+				stage.previousPage();
+				return { status: "executed" };
+			case "FirstPage":
+				stage.goToFirstPage();
+				return { status: "executed" };
+			case "LastPage":
+				stage.goToLastPage();
+				return { status: "executed" };
+			default: return {
+				status: "inert",
+				reason: `unknown named action '${node.name}'`
+			};
+		}
+	}));
+}
+//#endregion
 //#region src/motion.ts
 /**
-* The camera's MOTION vocabulary — every formula, pure.
+* 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.
+* The capability owns the impure drivers (the clock's frames, state writes,
+* gesture state); the laws those drivers integrate live here, parameterized
+* by elapsed time with no state and no clock, so they are unit-testable in
+* isolation and have no plugin dependencies.
 *
 * Two families:
 *   • ballistic — one per-axis law for every free motion: `glideStep` (the
@@ -22,119 +151,307 @@ import { addRotations, applyPoint, applyRect, displaySize, intersectRects, pageT
 *     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.
+*   • resistance — the iOS rubber-band curve `rubberOut` and its exact inverse
+*     `rubberIn`: dragging past an edge displays an asymptotically bounded
+*     stretch, and re-entering a gesture over a stretched camera (catching it
+*     mid-bounce) 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").
+* `zoomLerp`, a geometric zoom interpolation (zoom is multiplicative: equal
+* ratios per unit time, not equal deltas).
 */
 /** Resistance coefficient of the rubber-band curve (the iOS feel). */
 const RUBBER = .55;
-/** Glide decay per ms — UIScrollView's normal deceleration rate. */
+/** Glide decay per ms: UIScrollView's normal deceleration rate. */
 const FLING_DECAY = .998;
-/** rad/ms — critically damped, ~400ms to settle. */
+/** rad/ms; critically damped, settling in about 400 ms. */
 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.
+* Overshoot distance → displayed stretch, asymptotic to the viewport
+* dimension, 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));
+const rubberOut = (distance, dimension) => (1 - 1 / (distance * RUBBER / dimension + 1)) * dimension;
+/** The exact inverse of `rubberOut` (defined for `stretch < dimension`). */
+const rubberIn = (stretch, dimension) => stretch * dimension / (RUBBER * (dimension - stretch));
 /**
-* 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).
+* One frame of free glide: exponential velocity decay, the position advanced
+* by the midpoint integral of the decay over `elapsedMs` (exact for the
+* exponential, so 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,
+const glideStep = (position, velocity, elapsedMs) => {
+	const decay = Math.pow(FLING_DECAY, elapsedMs);
+	const nextPosition = position + velocity * (elapsedMs * (1 + decay) / 2);
+	const nextVelocity = velocity * decay;
+	return Math.abs(nextVelocity) < .02 ? {
+		position: nextPosition,
+		velocity: 0,
 		done: true
 	} : {
-		p: np,
-		v: nv,
+		position: nextPosition,
+		velocity: nextVelocity,
 		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.
+* One frame of a critically-damped spring toward `edge`: semi-implicit Euler
+* on x'' = −ω²(x−e) − 2ωx'. Lands exactly on the edge (position snapped,
+* velocity zeroed) once within 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,
+const springStep = (position, velocity, edge, elapsedMs) => {
+	const nextVelocity = velocity + (-.015 * SPRING_OMEGA * (position - edge) - 2 * SPRING_OMEGA * velocity) * elapsedMs;
+	const nextPosition = position + nextVelocity * elapsedMs;
+	if (Math.abs(nextPosition - edge) < .5 && Math.abs(nextVelocity) < .01) return {
+		position: edge,
+		velocity: 0,
 		done: true
 	};
 	return {
-		p: np,
-		v: nv,
+		position: nextPosition,
+		velocity: nextVelocity,
 		done: false
 	};
 };
-const easeOutCubic = (t) => 1 - Math.pow(1 - t, 3);
+const easeOutCubic = (progress) => 1 - Math.pow(1 - progress, 3);
+/**
+* Geometric zoom interpolation: `from·(to/from)^progress`. Zoom is
+* multiplicative, so a constant-rate zoom moves equal ratios per unit time;
+* interpolating the level linearly makes the start rush and the end crawl
+* (and, under a focal anchor, swings the anchored point along a curve).
+*/
+const zoomLerp = (from, to, progress) => from * Math.pow(to / from, progress);
+//#endregion
+//#region src/camera/animation.ts
 /**
-* 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).
+* Camera motion over the host's frames (`ctx.clock`): the coordinate tween,
+* the zoom-anchored tween (it animates the invariant, so the focal page-point
+* holds still by construction), and the momentum and edge physics (glide,
+* spring). One frame is waited for at a time: `cancelAnimation`, every verb's
+* first act, is also "catch".
 */
-const zoomLerp = (z0, z1, k) => z0 * Math.pow(z1 / z0, k);
+/** The default tween duration. */
+const TWEEN_MS = 240;
+const lerp = (from, to, progress) => from + (to - from) * progress;
+function createAnimation({ events, clock, scene }, write) {
+	const { motionEnded } = events;
+	const { camera, viewport, buildScene, stayBounds, constraint } = scene;
+	const { writeCamera, writeCameraUnclamped, axisTravels, syncCursorFromCamera } = write;
+	let cancelFrame = null;
+	const cancelAnimation = () => {
+		cancelFrame?.();
+		cancelFrame = null;
+	};
+	/** A tween or fling reached its natural end. */
+	const endMotion = () => {
+		cancelFrame = null;
+		motionEnded.emit({ camera: camera() });
+	};
+	const animateTo = (target, bounds, durationMs = TWEEN_MS, then) => {
+		if (!clock.hasFrames) {
+			writeCamera(target, bounds);
+			then?.();
+			return;
+		}
+		cancelAnimation();
+		const from = camera();
+		let started = false;
+		let startedAt = 0;
+		const tick = (now) => {
+			if (!started) {
+				started = true;
+				startedAt = now;
+			}
+			const progress = easeOutCubic(Math.min(1, (now - startedAt) / durationMs));
+			writeCamera({
+				x: lerp(from.x, target.x, progress),
+				y: lerp(from.y, target.y, progress),
+				zoom: lerp(from.zoom, target.zoom, progress)
+			}, bounds);
+			if (progress < 1) cancelFrame = clock.nextFrame(tick);
+			else {
+				endMotion();
+				then?.();
+			}
+		};
+		cancelFrame = clock.nextFrame(tick);
+	};
+	/**
+	* The zoom-anchored tween animates the invariant, not the coordinates: the
+	* focal page-point stays at `point` while the scale changes. Lerping x, y
+	* and zoom independently breaks that mid-flight, because holding a screen
+	* point requires `x(t) = focal.x − point.x / zoom(t)`, hyperbolic in the
+	* zoom, so linear coordinates swing the tapped point along a curve (a
+	* visible dip). Here the zoom interpolates geometrically (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 as the shrinking travel range lets the clamp
+	* take over.
+	*/
+	const animateZoomAnchored = (focal, point, targetZoom, durationMs = TWEEN_MS, then) => {
+		if (!clock.hasFrames) {
+			const scene = buildScene();
+			if (scene.itemCount) writeCamera(cameraForAnchorAtScreen(focal, scene, point, targetZoom));
+			then?.();
+			return;
+		}
+		cancelAnimation();
+		const startZoom = camera().zoom;
+		let started = false;
+		let startedAt = 0;
+		const tick = (now) => {
+			if (!started) {
+				started = true;
+				startedAt = now;
+			}
+			const progress = easeOutCubic(Math.min(1, (now - startedAt) / durationMs));
+			const zoom = zoomLerp(startZoom, targetZoom, progress);
+			const scene = buildScene();
+			if (scene.itemCount) writeCamera(cameraForAnchorAtScreen(focal, scene, point, zoom));
+			if (progress < 1) cancelFrame = clock.nextFrame(tick);
+			else {
+				endMotion();
+				then?.();
+			}
+		};
+		cancelFrame = clock.nextFrame(tick);
+	};
+	const startCameraPhysics = (fingerVelocityX, fingerVelocityY) => {
+		if (!clock.hasFrames) {
+			writeCamera(camera());
+			return;
+		}
+		cancelAnimation();
+		const zoom = camera().zoom;
+		const start = camera();
+		const startClamped = clampCamera(start, stayBounds(), viewport(), constraint());
+		const startBounds = stayBounds();
+		const startViewport = viewport();
+		const axisState = (cameraPosition, clampedPosition, fingerVelocity) => ({
+			position: cameraPosition * zoom,
+			velocity: -fingerVelocity / 1e3,
+			springing: cameraPosition !== clampedPosition,
+			done: false
+		});
+		const axisX = axisState(start.x, startClamped.x, axisTravels(startBounds.x, startBounds.width, startViewport.width, zoom) ? fingerVelocityX : 0);
+		const axisY = axisState(start.y, startClamped.y, axisTravels(startBounds.y, startBounds.height, startViewport.height, zoom) ? fingerVelocityY : 0);
+		if (!axisX.springing && !axisY.springing && Math.hypot(axisX.velocity, axisY.velocity) < .02) return;
+		let started = false;
+		let lastFrameAt = 0;
+		const tick = (now) => {
+			cancelFrame = null;
+			const elapsedMs = started ? Math.min(64, Math.max(1, now - lastFrameAt)) : 16;
+			started = true;
+			lastFrameAt = now;
+			const home = clampCamera({
+				x: axisX.position / zoom,
+				y: axisY.position / zoom,
+				zoom
+			}, stayBounds(), viewport(), constraint());
+			const step = (axis, edgeWorld) => {
+				if (axis.done) return;
+				const next = axis.springing ? springStep(axis.position, axis.velocity, edgeWorld * zoom, elapsedMs) : glideStep(axis.position, axis.velocity, elapsedMs);
+				axis.position = next.position;
+				axis.velocity = next.velocity;
+				axis.done = next.done;
+			};
+			step(axisX, home.x);
+			step(axisY, home.y);
+			const nextHome = clampCamera({
+				x: axisX.position / zoom,
+				y: axisY.position / zoom,
+				zoom
+			}, stayBounds(), viewport(), constraint());
+			const convert = (axis, clampedPosition) => {
+				if (!axis.springing && Math.abs(clampedPosition * zoom - axis.position) > 1e-6) {
+					axis.position = clampedPosition * zoom;
+					axis.springing = true;
+					axis.done = false;
+				}
+			};
+			convert(axisX, nextHome.x);
+			convert(axisY, nextHome.y);
+			writeCameraUnclamped({
+				x: axisX.position / zoom,
+				y: axisY.position / zoom,
+				zoom
+			});
+			syncCursorFromCamera();
+			if (axisX.done && axisY.done) {
+				writeCamera(camera());
+				motionEnded.emit({ camera: camera() });
+				return;
+			}
+			cancelFrame = clock.nextFrame(tick);
+		};
+		cancelFrame = clock.nextFrame(tick);
+	};
+	return {
+		cancelAnimation,
+		animateTo,
+		animateZoomAnchored,
+		startCameraPhysics,
+		api: {
+			fling: (velocityX, velocityY) => startCameraPhysics(velocityX, velocityY),
+			isMoving: () => cancelFrame !== null,
+			stopMotion: () => {
+				if (!cancelFrame) return;
+				cancelAnimation();
+				motionEnded.emit({ camera: camera() });
+			}
+		}
+	};
+}
 //#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).
+* 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, so they are property-testable in isolation.
 *
-* 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 query vocabulary is only 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
+* `updateSettings()`.
 */
 /** 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"
+const boxOf = (size) => ({
+	width: size.width,
+	height: size.height,
+	orientation: size.height >= size.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);
+/** All bounds inclusive, all fields optional, every condition must hold (CSS ranges). */
+const matchesQuery = (query, box) => (query.minWidth === void 0 || box.width >= query.minWidth) && (query.maxWidth === void 0 || box.width <= query.maxWidth) && (query.minHeight === void 0 || box.height >= query.minHeight) && (query.maxHeight === void 0 || box.height <= query.maxHeight) && (query.orientation === void 0 || box.orientation === query.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). */
+/**
+* Merge a patch over settings, skipping undefined values (Partial semantics).
+* Each value replaces the setting whole; a `pageFrame` that names only some
+* sides reserves 0 on the others.
+*/
 const mergeSettings = (into, patch) => {
-	const out = { ...into };
+	const merged = { ...into };
 	let key;
 	for (key in patch) {
-		const value = patch[key];
-		if (value !== void 0) Object.assign(out, { [key]: value });
+		const value = key === "pageFrame" ? frameOf(patch.pageFrame) : patch[key];
+		if (value !== void 0) Object.assign(merged, { [key]: value });
 	}
-	return out;
+	return merged;
+};
+const frameOf = (frame) => frame === void 0 ? void 0 : {
+	...NO_FRAME,
+	...frame
 };
 /**
 * 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 eqSetting = (left, right) => {
+	if (left === right) return true;
+	if (typeof left !== "object" || typeof right !== "object" || left === null || right === null) return false;
+	const leftKeys = Object.keys(left);
+	return leftKeys.length === Object.keys(right).length && leftKeys.every((key) => left[key] === right[key]);
 };
 const resolveResponsive = (base, rules, box) => {
 	let effective = base;
@@ -152,11 +469,11 @@ const resolveResponsive = (base, rules, box) => {
 //#endregion
 //#region src/settings.ts
 /**
-* Out-of-the-box defaults — a sensible document-reading feel. They are JUST
-* defaults: every field is overridable in `stagePlugin(config)` and at runtime via
-* the setters / `update()`. The plugin ships NO named presets ("document",
-* "canvas", …) — a preset is simply an object the app keeps and passes to
-* `update()`, so that taxonomy stays a customer concern.
+* Out-of-the-box defaults: a document-reading feel. Every field is overridable
+* in `stagePlugin(config)` and at runtime through `updateSettings()`. The
+* plugin ships no named presets ("document", "canvas", …): a preset is an
+* object the app keeps and passes to `updateSettings()`, so that taxonomy
+* stays the app's concern.
 */
 const DEFAULT_SETTINGS = {
 	flow: "continuous",
@@ -193,14 +510,17 @@ const DEFAULT_SETTINGS = {
 	viewRotation: 0,
 	zoom: { mode: ZoomMode$1.Automatic },
 	scrollBehavior: "smooth",
+	interaction: true,
+	panFallback: true,
+	zoomGestures: true,
 	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
+* 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')`.
+* 'compact' name is queryable by the app through `stage.matchesRule('compact')`.
 */
 const DEFAULT_RESPONSIVE = [{
 	name: "compact",
@@ -225,690 +545,702 @@ const SETTINGS_EFFECT = {
 	viewRotation: "scene",
 	zoom: "refit",
 	scrollBehavior: "none",
+	interaction: "none",
+	panFallback: "none",
+	zoomGestures: "none",
 	viewUnitsPerPoint: "scene"
 };
 const SETTING_KEYS = Object.keys(SETTINGS_EFFECT);
-const valueEq = (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);
-	return ka.length === Object.keys(b).length && ka.every((k) => a[k] === b[k]);
+/** Field-by-field settings equality, derived from the registry, so a new
+*  setting is covered automatically: what an adapter compares settings with. */
+const settingsEqual = (left, right) => SETTING_KEYS.every((key) => eqSetting(left[key], right[key]));
+/** The settings slice of a larger object (state, or a saved view), derived
+*  from the registry so the shape is never spelled out by hand. */
+const pickSettings = (source) => {
+	const settings = {};
+	for (const key of SETTING_KEYS) settings[key] = source[key];
+	return settings;
+};
+//#endregion
+//#region src/model.ts
+const initialStageState = (config) => {
+	const { responsive: _responsive, ...overrides } = config;
+	return {
+		camera: {
+			x: 0,
+			y: 0,
+			zoom: 1
+		},
+		placed: false,
+		cameraResting: true,
+		viewport: {
+			width: 0,
+			height: 0
+		},
+		dpr: 1,
+		cursor: 0,
+		motionCause: "user",
+		activeRules: [],
+		...mergeSettings(DEFAULT_SETTINGS, overrides)
+	};
+};
+const setCamera = (state, camera) => state.camera === camera ? state : {
+	...state,
+	camera
+};
+const setCameraResting = (state, resting) => state.cameraResting === resting ? state : {
+	...state,
+	cameraResting: resting
+};
+const markPlaced = (state) => state.placed ? state : {
+	...state,
+	placed: true
+};
+const setViewport = (state, viewport) => state.viewport === viewport ? state : {
+	...state,
+	viewport
+};
+const setDpr = (state, dpr) => state.dpr === dpr ? state : {
+	...state,
+	dpr
+};
+const setCursor = (state, cursor) => state.cursor === cursor ? state : {
+	...state,
+	cursor
+};
+const setMotionCause = (state, motionCause) => state.motionCause === motionCause ? state : {
+	...state,
+	motionCause
+};
+/**
+* Merge a settings patch. Undefined values are skipped, so a partial restore
+* never clears a setting; the area that patches decides what camera
+* follow-up the change needs.
+*/
+function patchSettings(state, patch) {
+	let next = state;
+	let key;
+	for (key in patch) {
+		const value = patch[key];
+		if (value === void 0 || Object.is(next[key], value)) continue;
+		if (next === state) next = { ...state };
+		Object.assign(next, { [key]: value });
+	}
+	return next;
+}
+const setActiveRules = (state, activeRules) => state.activeRules === activeRules ? state : {
+	...state,
+	activeRules
 };
-/** Field-by-field settings equality, derived from the registry — a new setting is
-*  covered automatically. (The React `useStageSettings` selector equality.) */
-const settingsEqual = (a, b) => SETTING_KEYS.every((k) => valueEq(a[k], b[k]));
 //#endregion
-//#region src/capability.ts
+//#region src/camera/gestures.ts
 /**
-* The Stage capability — selectors (pure reads) + intents (the only writers).
-*
-* 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; 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.
-*   • focal zoom (zoomIn/zoomTo/fit-mode switches) — the zoomAlign viewport point.
-*   • reframes (resize/rotate/re-layout)           — the page-point at the anchorAlign
-*     viewport point: captured there before the change, restored there after.
-*   • arrivals (goToPage/next/prev/reset)          — nothing prior: a fresh landing at
-*     arrivalAlign, THE SAME at every zoom (landing is policy, never a zoom side effect).
-*   • explicit (reveal/destination/viewpoint)      — whatever the call specifies.
-* fitAlign stands apart: the clamp's standing rest constraint wherever an axis has no
-* freedom against the TRUE bounds — it shapes every move above, and is why a fitting
-* axis settles identically whatever arrivalAlign says.
-*
-* "Does it fit the viewport?" still decides SIZE and SUBJECT — never alignment:
-*   • step size: next/prev step by ITEM (spread) when the item fits, by PAGE when
-*     zoomed in past it.
-*   • subject:   you arrive AT the unit that fits (item, page — or the whole scene
-*     under fit-all).
-*
-* The `cursor` is THE current page in both flows: navigation sets it; continuous
-* scrolling syncs it from the camera; paged panning never moves it.
+* Direct manipulation: set, pan, scroll and pinch-zoom the camera, and the
+* gesture bracket. The camera moves freely and the cursor is derived from it
+* (the manipulation direction of cursor reconciliation).
 */
-function createStageCapability(ctx, config = {}) {
-	const host = globalThis;
-	const canAnimate = !!config.scheduler || typeof host.requestAnimationFrame === "function";
-	const scheduler = config.scheduler ?? (typeof host.requestAnimationFrame === "function" ? {
-		raf: (cb) => host.requestAnimationFrame(cb),
-		caf: (h) => host.cancelAnimationFrame(h)
-	} : {
-		raf: () => 0,
-		caf: () => {}
-	});
-	const cam = () => ctx.getState().camera;
-	const vp = () => ctx.getState().vp;
-	const dpr = () => ctx.getState().dpr;
-	const pad = () => ctx.getState().padding;
-	const paged = () => ctx.getState().flow === "paged";
-	const isFitAll = () => {
-		const z = ctx.getState().zoom;
-		return "mode" in z && z.mode === S.ZoomMode.FitAll;
-	};
-	let groupingCache = null;
-	const grouping = () => {
-		const doc = ctx.document();
-		const st = ctx.getState();
-		const key = `${doc ? doc.pageCount : 0}|${st.spread}`;
-		if (groupingCache && groupingCache.key === key) return groupingCache;
-		const g = S.groupPages(doc ? doc.pageCount : 0, st.spread);
-		groupingCache = {
-			key,
-			grouping: g,
-			firstPages: g.map((item) => item[0])
-		};
-		return groupingCache;
-	};
-	const itemIndexOfPage = (pageIndex) => {
-		const fp = grouping().firstPages;
-		let lo = 0;
-		let hi = fp.length;
-		while (lo < hi) {
-			const mid = lo + hi >> 1;
-			if (fp[mid] <= pageIndex) lo = mid + 1;
-			else hi = mid;
+function createGestures(ctx, { scene }, write, { cancelAnimation, animateTo, startCameraPhysics }, { scrollMetricsNow }) {
+	const { camera, viewport, padding, buildScene, stayBounds, constraint } = scene;
+	const { gesture, armRest, writeCamera, writeCameraUnclamped, rubberize, unrubberize, syncCursorFromCamera, markCause } = write;
+	const scrollTo = (options) => {
+		markCause("user");
+		cancelAnimation();
+		if (!buildScene().itemCount) return;
+		const next = cameraFromScroll(camera(), stayBounds(), viewport(), padding(), options);
+		if (options.behavior === "smooth") animateTo(next, stayBounds(), void 0, syncCursorFromCamera);
+		else {
+			writeCamera(next);
+			syncCursorFromCamera();
 		}
-		return Math.max(0, lo - 1);
-	};
-	const effectiveZoom = () => {
-		const z = ctx.getState().zoom;
-		return "level" in z ? z.level : Math.max(ctx.getState().camera.zoom, 1e-4);
-	};
-	const wrapLineWidth = () => Math.max(1, (vp().width - 2 * pad()) / effectiveZoom());
-	const worldPageFrame = () => {
-		const m = ctx.getState().pageFrame;
-		if (!m.top && !m.right && !m.bottom && !m.left) return m;
-		const ez = effectiveZoom();
-		return {
-			top: m.top / ez,
-			right: m.right / ez,
-			bottom: m.bottom / ez,
-			left: m.left / ez
-		};
 	};
-	const frameKey = () => {
-		const m = ctx.getState().pageFrame;
-		if (!m.top && !m.right && !m.bottom && !m.left) return "-";
-		const w = worldPageFrame();
-		return `${Math.round(w.top)},${Math.round(w.right)},${Math.round(w.bottom)},${Math.round(w.left)}`;
-	};
-	const worldGap = () => {
-		const g = ctx.getState().gap;
-		return typeof g === "number" ? g : g.px ? g.px / effectiveZoom() : 0;
+	return { api: {
+		setCamera: (next) => {
+			markCause("user");
+			cancelAnimation();
+			writeCamera(next);
+			syncCursorFromCamera();
+		},
+		panBy: (dx, dy) => {
+			markCause("user");
+			cancelAnimation();
+			if (gesture.depth > 0 && gesture.elastic) {
+				gesture.raw = panByScreen(gesture.raw ?? unrubberize(camera()), dx, dy);
+				writeCameraUnclamped(rubberize(gesture.raw));
+			} else writeCamera(panByScreen(camera(), dx, dy));
+			syncCursorFromCamera();
+		},
+		scrollTo,
+		scrollBy: ({ left, top, behavior }) => {
+			const metrics = scrollMetricsNow();
+			scrollTo({
+				left: left === void 0 ? void 0 : metrics.scrollLeft + left,
+				top: top === void 0 ? void 0 : metrics.scrollTop + top,
+				behavior
+			});
+		},
+		zoomAround: (point, factor) => {
+			cancelAnimation();
+			const before = buildScene();
+			const focal = before.itemCount ? anchorAtPoint(before, toWorld(camera(), point)) : null;
+			writeCamera(zoomAround(camera(), point, factor));
+			if (gesture.depth === 0) ctx.state.update(patchSettings, { zoom: { level: camera().zoom } });
+			const after = buildScene();
+			if (after !== before && focal && after.itemCount) writeCamera(cameraForAnchorAtScreen(focal, after, point, camera().zoom));
+			if (gesture.depth > 0 && gesture.elastic) gesture.raw = unrubberize(camera());
+			syncCursorFromCamera();
+		},
+		beginGesture: (options) => {
+			gesture.depth++;
+			if (gesture.depth === 1) {
+				cancelAnimation();
+				gesture.zoomed = false;
+				gesture.elastic = options?.elastic === true;
+				gesture.raw = null;
+			}
+		},
+		endGesture: () => {
+			if (gesture.depth === 0) return;
+			gesture.depth--;
+			if (gesture.depth > 0) return;
+			gesture.raw = null;
+			const wasElastic = gesture.elastic;
+			gesture.elastic = false;
+			if (gesture.zoomed) {
+				gesture.zoomed = false;
+				ctx.state.update(patchSettings, { zoom: { level: camera().zoom } });
+				armRest();
+			}
+			syncCursorFromCamera();
+			if (wasElastic) {
+				const current = camera();
+				const clamped = clampCamera(current, stayBounds(), viewport(), constraint());
+				if (clamped.x !== current.x || clamped.y !== current.y) startCameraPhysics(0, 0);
+			}
+		}
+	} };
+}
+//#endregion
+//#region src/camera/write.ts
+/**
+* The camera write path: the one low-level clamped write (`writeCamera`), the
+* elastic unclamped write and its rubber-band curves, the rest detector that
+* gates device snapping, the gesture bracket state, and cursor reconciliation
+* from the camera (manipulation only; navigation sets the cursor as intent).
+*/
+/** How long the zoom must hold still before the camera counts as resting. */
+const REST_MS = 150;
+function createCameraWrite(ctx, { clock, placement, scene }) {
+	const { camera, viewport, paged, buildScene, stayBounds, constraint } = scene;
+	const gesture = {
+		depth: 0,
+		zoomed: false,
+		elastic: false,
+		raw: null
 	};
-	const gapKey = () => {
-		const g = ctx.getState().gap;
-		return typeof g === "number" ? String(g) : `px:${Math.round(worldGap())}`;
+	let cancelRest = null;
+	const stopRestCountdown = () => {
+		cancelRest?.();
+		cancelRest = null;
 	};
-	const layoutFor = (groups) => {
-		const st = ctx.getState();
-		const raw = ctx.document()?.pages ?? [];
-		const vr = st.viewRotation;
-		const pages = vr === 0 ? raw : raw.map((p) => ({
-			...p,
-			rotation: addRotations(p.rotation, vr)
-		}));
-		const pageFrame = worldPageFrame();
-		const gap = worldGap();
-		const vupp = st.viewUnitsPerPoint;
-		if (st.layout === "grid") return S.gridLayout(pages, groups, {
-			gap,
-			sizing: st.sizing,
-			direction: st.direction,
-			pageFrame,
-			viewUnitsPerPoint: vupp,
-			columns: typeof st.columns === "number" ? st.columns : void 0,
-			lineWidth: st.columns === "auto" ? wrapLineWidth() : void 0
-		});
-		return st.layout === "horizontal" ? S.linearLayout(pages, groups, {
-			axis: "x",
-			gap,
-			sizing: st.sizing,
-			direction: st.direction,
-			pageFrame,
-			viewUnitsPerPoint: vupp
-		}) : S.linearLayout(pages, groups, {
-			axis: "y",
-			gap,
-			sizing: st.sizing,
-			direction: st.direction,
-			pageFrame,
-			viewUnitsPerPoint: vupp
+	const armRest = () => {
+		if (!clock.hasFrames || !placement.started) return;
+		ctx.state.update(setCameraResting, false);
+		stopRestCountdown();
+		cancelRest = clock.after(REST_MS, () => {
+			cancelRest = null;
+			ctx.state.update(setCameraResting, true);
 		});
 	};
-	const columnsKey = () => {
-		const st = ctx.getState();
-		if (st.layout !== "grid") return "-";
-		return st.columns === "auto" ? `auto:${Math.round(wrapLineWidth())}` : String(st.columns);
-	};
-	const SCENE_KEY_FNS = {
-		columns: columnsKey,
-		gap: gapKey,
-		pageFrame: frameKey
-	};
-	const SCENE_KEYS = SETTING_KEYS.filter((k) => SETTINGS_EFFECT[k] === "scene");
-	const settingsKey = () => SCENE_KEYS.map((k) => {
-		const fn = SCENE_KEY_FNS[k];
-		if (fn) return fn();
-		const v = ctx.getState()[k];
-		return typeof v === "object" && v !== null ? JSON.stringify(v) : String(v);
-	}).join("|");
-	let sceneCache = null;
-	const docKey = () => {
-		const doc = ctx.document();
-		return doc ? `${doc.pageCount}.${doc.revision}` : "0.0";
+	const writeCamera = (next, bounds = stayBounds()) => {
+		const clamped = clampCamera(next, bounds, viewport(), constraint());
+		if (clamped.zoom !== camera().zoom) if (gesture.depth > 0) {
+			gesture.zoomed = true;
+			ctx.state.update(setCameraResting, false);
+			stopRestCountdown();
+		} else armRest();
+		ctx.state.update(setCamera, clamped);
 	};
-	const buildScene = () => {
-		const st = ctx.getState();
-		const { grouping: g } = grouping();
-		if (st.flow === "paged") {
-			const idx = g.length ? Math.min(itemIndexOfPage(st.cursor), g.length - 1) : 0;
-			const key = `paged|${docKey()}|${settingsKey()}|${idx}`;
-			if (sceneCache && sceneCache.key === key) return sceneCache.scene;
-			const scene = layoutFor(g.length ? [g[idx]] : []);
-			sceneCache = {
-				key,
-				scene
-			};
-			return scene;
-		}
-		const key = `cont|${docKey()}|${settingsKey()}`;
-		if (sceneCache && sceneCache.key === key) return sceneCache.scene;
-		const scene = layoutFor(g);
-		sceneCache = {
-			key,
-			scene
+	const axisTravels = (origin, content, view, zoom) => !travelRange(origin, content, view, zoom, constraint().padding).fits;
+	/** The 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, and on a fitting axis
+	*  it is always the clamp. */
+	const rubberize = (raw) => {
+		const clamped = clampCamera(raw, stayBounds(), viewport(), constraint());
+		const size = viewport();
+		const bounds = stayBounds();
+		const axis = (rawPosition, clampedPosition, dimension, travels) => {
+			if (!travels) return clampedPosition;
+			const overshootWorld = rawPosition - clampedPosition;
+			if (overshootWorld === 0) return clampedPosition;
+			const stretch = rubberOut(Math.abs(overshootWorld) * raw.zoom, Math.max(1, dimension));
+			return clampedPosition + Math.sign(overshootWorld) * stretch / raw.zoom;
 		};
-		return scene;
-	};
-	const sceneRect = () => {
-		const { width, height } = buildScene().size;
 		return {
-			x: 0,
-			y: 0,
-			width,
-			height
+			zoom: raw.zoom,
+			x: axis(raw.x, clamped.x, size.width, axisTravels(bounds.x, bounds.width, size.width, raw.zoom)),
+			y: axis(raw.y, clamped.y, size.height, axisTravels(bounds.y, bounds.height, size.height, raw.zoom))
 		};
 	};
-	const itemRect = (it) => ({
-		x: it.x,
-		y: it.y,
-		width: it.width,
-		height: it.height
-	});
-	const pageRectOf = (it, pageIndex) => {
-		const box = it.pages.find((p) => p.pageIndex === pageIndex) ?? it.pages[0];
-		return {
-			x: box.x,
-			y: box.y,
-			width: box.width,
-			height: box.height
+	/** The displayed camera → the raw position `rubberize` would have produced
+	*  it from. The 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 = clampCamera(displayed, stayBounds(), viewport(), constraint());
+		const size = viewport();
+		const bounds = stayBounds();
+		const axis = (displayedPosition, clampedPosition, dimension, travels) => {
+			if (!travels) return clampedPosition;
+			const overshootWorld = displayedPosition - clampedPosition;
+			if (overshootWorld === 0) return clampedPosition;
+			const span = Math.max(1, dimension);
+			const stretch = Math.min(Math.abs(overshootWorld) * displayed.zoom, span - 1);
+			return clampedPosition + Math.sign(overshootWorld) * rubberIn(stretch, span) / displayed.zoom;
 		};
-	};
-	/** The item shown for the cursor: the slice's only item (paged) / the full-scene item. */
-	const cursorItem = () => {
-		const sc = buildScene();
-		return paged() ? sc.items[0] : sc.items[itemIndexOfPage(ctx.getState().cursor)];
-	};
-	/**
-	* CONTENT-space rect on a page → WORLD rect: the same quarter-turn matrix
-	* `pageRectToScreen` uses, minus the camera — so a positioned reveal and
-	* the rendered overlay can never disagree about where a rect is.
-	*/
-	const worldRectForContent = (it, pageIndex, rect) => {
-		const box = it.pages.find((p) => p.pageIndex === pageIndex) ?? it.pages[0];
-		const content = displaySize({
-			width: box.width,
-			height: box.height
-		}, box.rotation);
-		const wr = applyRect(rotateScaleMatrix(box.contentScale, content.width, content.height, box.rotation), rect);
 		return {
-			x: box.x + wr.x,
-			y: box.y + wr.y,
-			width: wr.width,
-			height: wr.height
+			zoom: displayed.zoom,
+			x: axis(displayed.x, clamped.x, size.width, axisTravels(bounds.x, bounds.width, size.width, displayed.zoom)),
+			y: axis(displayed.y, clamped.y, size.height, axisTravels(bounds.y, bounds.height, size.height, displayed.zoom))
 		};
 	};
+	const writeCameraUnclamped = (next) => ctx.state.update(setCamera, next);
 	/**
-	* One axis of a positioned-reveal camera. `undefined` = 'nearest' (only
-	* move if the target is outside the padded view) — unless the zoom just
-	* changed, where "don't move" is meaningless and the spec's slack-axis
-	* rule (center) applies. 'keep' never moves the axis (PDF /XYZ null).
-	*/
-	const revealAxis = (a, camPos, rectPos, rectExtent, vpExtent, zoom, zoomChanged) => {
-		if (a === "keep") return camPos;
-		const p = pad();
-		if (a === void 0) {
-			if (!zoomChanged) {
-				const lo = camPos + p / zoom;
-				const hi = camPos + (vpExtent - p) / zoom;
-				if (rectPos >= lo && rectPos + rectExtent <= hi) return camPos;
-				if (rectExtent > hi - lo || rectPos < lo) return rectPos - p / zoom;
-				return rectPos + rectExtent - (vpExtent - p) / zoom;
-			}
-			a = "center";
-		}
-		if (a === "start") return rectPos - p / zoom;
-		if (a === "end") return rectPos + rectExtent - (vpExtent - p) / zoom;
-		const f = a === "center" ? .5 : Math.min(1, Math.max(0, a));
-		return rectPos + rectExtent / 2 - vpExtent * f / zoom;
-	};
-	const fits = (rect, zoom) => {
-		const v = vp();
-		const p = pad();
-		const eps = .5;
-		return rect.width * zoom <= v.width - 2 * p + eps && rect.height * zoom <= v.height - 2 * p + eps;
-	};
-	const alignFraction = (a) => a === "start" ? 0 : a === "center" ? .5 : a === "end" ? 1 : Math.min(1, Math.max(0, a));
-	const alignPoint = (al, v) => {
-		const rtl = ctx.getState().direction === "rtl";
-		const ax = rtl && al.x === "start" ? "end" : rtl && al.x === "end" ? "start" : al.x;
-		const p = pad();
-		return {
-			x: p + (v.width - 2 * p) * alignFraction(ax),
-			y: p + (v.height - 2 * p) * alignFraction(al.y)
-		};
-	};
-	const anchorPoint = () => alignPoint(ctx.getState().anchorAlign, vp());
-	/** Fit-box for resolving the zoom intent: whole scene (fit-all), the current item
-	*  (paged — per-page fit), or the document max (continuous — doc-stable zoom). */
-	const fitBox = (item) => {
-		if (isFitAll()) return buildScene().size;
-		return paged() ? {
-			width: item.width,
-			height: item.height
-		} : buildScene().maxItemSize;
-	};
-	/** Clamp rect for a camera write targeting this item (scene-wide in continuous). */
-	const boundsFor = (it) => paged() ? itemRect(it) : sceneRect();
-	/** Clamp rect for a "stay" write (pan/zoom): the slice item (paged) / the scene. */
-	const stayBounds = () => paged() ? itemRect(buildScene().items[0]) : sceneRect();
-	const constraint = () => ({
-		bounded: ctx.getState().bounded,
-		padding: pad(),
-		fitAlign: ctx.getState().fitAlign,
-		direction: ctx.getState().direction
-	});
-	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 || !placementStarted) return;
-		if (ctx.getState().cameraResting) ctx.dispatch({
-			type: "CAMERA_REST",
-			resting: false
-		});
-		if (restRaf) scheduler.caf(restRaf);
-		let t0 = 0;
-		const tick = (ts) => {
-			restRaf = 0;
-			if (!t0) t0 = ts;
-			if (ts - t0 >= REST_MS) {
-				ctx.dispatch({
-					type: "CAMERA_REST",
-					resting: true
-				});
-				return;
-			}
-			restRaf = scheduler.raf(tick);
-		};
-		restRaf = scheduler.raf(tick);
-	};
-	const setCam = (next, bounds = stayBounds()) => {
-		const clamped = S.clampCamera(next, bounds, vp(), constraint());
-		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
-	*                 as the clamp allows — and a clamped camera never revokes it.
-	*   manipulation → (pan / drag / pinch) the camera moves freely; the cursor is
-	*                 DERIVED from it. Only those verbs call this. Paged never syncs.
+	* Cursor reconciliation, one direction per interaction:
+	*   navigation   → the cursor is intent, set explicitly; the camera honors
+	*                  it as far as the clamp allows, and a clamped camera
+	*                  never revokes it.
+	*   manipulation → (pan, drag, pinch) the camera moves freely and the
+	*                  cursor is derived from it. Only those verbs call this.
+	* Paged flow never syncs.
 	*/
 	const syncCursorFromCamera = () => {
 		if (paged()) return;
-		const sc = buildScene();
-		if (!sc.itemCount) return;
-		const page = S.anchorFromCamera(cam(), sc, vp()).pageIndex;
-		if (page !== ctx.getState().cursor) ctx.dispatch({
-			type: "CURSOR",
-			cursor: page
-		});
-	};
-	let raf = 0;
-	const cancelAnim = () => {
-		if (raf) {
-			scheduler.caf(raf);
-			raf = 0;
-		}
-	};
-	const lerp = (a, b, k) => a + (b - a) * k;
-	const animateTo = (target, bounds, ms = 240, then) => {
-		if (!canAnimate) {
-			setCam(target, bounds);
-			then?.();
-			return;
-		}
-		cancelAnim();
-		const from = cam();
-		let started = false;
-		let t0 = 0;
-		const tick = (now) => {
-			if (!started) {
-				started = true;
-				t0 = now;
-			}
-			const k = easeOutCubic(Math.min(1, (now - t0) / ms));
-			setCam({
-				x: lerp(from.x, target.x, k),
-				y: lerp(from.y, target.y, k),
-				zoom: lerp(from.zoom, target.zoom, k)
-			}, bounds);
-			if (k < 1) raf = scheduler.raf(tick);
-			else {
-				raf = 0;
-				then?.();
-			}
-		};
-		raf = scheduler.raf(tick);
+		const scene = buildScene();
+		if (!scene.itemCount) return;
+		ctx.state.update(setCursor, anchorFromCamera(camera(), scene, viewport()).pageIndex);
 	};
-	/**
-	* 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) : {
-			pageIndex: ctx.getState().cursor,
-			fx: .5,
-			fy: 0
-		};
+	/** Tag what drives the next camera or cursor change (see `StageState.motionCause`). */
+	const markCause = (cause) => ctx.state.update(setMotionCause, cause);
+	return {
+		gesture,
+		armRest,
+		writeCamera,
+		writeCameraUnclamped,
+		axisTravels,
+		rubberize,
+		unrubberize,
+		syncCursorFromCamera,
+		markCause
 	};
-	const currentAnchor = () => anchorAt(anchorPoint());
+}
+//#endregion
+//#region src/services/placement-latch.ts
+const createPlacementLatch = () => ({
+	started: false,
+	pending: null
+});
+/**
+* Run a navigation verb now, or, before the first placement, when it happens.
+* Before placement there is no viewport to move a camera in, and placement
+* would reset it anyway, so the last call waits and lands instantly after the
+* initial view: an app that reveals something as the document opens sees it
+* on the first frame.
+*/
+function whenPlaced(latch, options, run) {
+	if (latch.started) {
+		run(options);
+		return;
+	}
+	latch.pending = () => run({
+		...options,
+		behavior: "instant"
+	});
+}
+//#endregion
+//#region src/navigation/arrive.ts
+/**
+* Anchors and arrivals. The anchor is the durable "what am I looking at":
+* captured before a structural change and re-applied after, one mechanism for
+* layout, spread, zoom, resize and restore. Navigation is canonical:
+* goToPage(N) always ends in the same camera state whatever the zoom or the
+* starting point.
+*/
+function createArrival(ctx, { scene, placement }, { writeCamera, markCause }, { cancelAnimation, animateTo }) {
+	const { camera, viewport, padding, paged, isFitAll, grouping, itemIndexOfPage, buildScene, sceneRect, itemRect, pageRectOf, cursorItem, fits, alignPoint, fitBox, boundsFor, constraint, indexOfTarget } = scene;
+	const state = () => ctx.state.get();
+	const pageCount = () => ctx.document()?.pageCount ?? 0;
 	/**
-	* Run a placement whose RESOLVED zoom may change the scene (wrapped mode: zoom is
-	* a layout input). Re-run it until the scene it placed against is the scene that
-	* results — every non-wrapped mode is stable after the first pass by construction,
-	* and wrapped fit-modes converge on the second (the fit-box is wrap-independent).
-	* Capped at 3 passes for the one genuinely circular case (fit-all + wrapped).
+	* Run a placement whose resolved zoom may change the scene (in wrapped mode
+	* zoom is a layout input), until the scene it placed against is the scene
+	* that results. Every non-wrapped mode is stable after the first pass, and
+	* wrapped fit modes converge on the second (the fit box does not depend on
+	* wrapping). Capped at 3 passes for the one circular case (fit-all +
+	* wrapped).
 	*/
 	const stabilized = (place) => {
 		for (let attempt = 0; attempt < 3; attempt++) {
-			const scene = buildScene();
+			const before = buildScene();
 			place();
-			if (buildScene() === scene) return;
+			if (buildScene() === before) return;
 		}
 	};
 	const applyAnchor = (anchor, align) => {
 		stabilized(() => {
-			const scene = buildScene();
-			if (!scene.itemCount) return;
-			const item = scene.items[scene.itemOfPage(anchor.pageIndex)];
-			const zoom = S.resolveZoom(ctx.getState().zoom, fitBox(item), vp(), pad());
-			const at = alignPoint(align ?? ctx.getState().anchorAlign, vp());
-			setCam(S.cameraFromAnchor(anchor, scene, vp(), zoom, at), boundsFor(item));
+			const current = buildScene();
+			if (!current.itemCount) return;
+			const item = current.items[current.itemOfPage(anchor.pageIndex)];
+			const zoom = resolveZoom(state().zoom, fitBox(item), viewport(), padding());
+			const at = alignPoint(align ?? state().anchorAlign, viewport());
+			writeCamera(cameraFromAnchor(anchor, current, viewport(), zoom, at), boundsFor(item));
 		});
 	};
 	/**
-	* Re-apply the view after a structural/zoom/viewport change. Normally anchor-
-	* preserving (keep looking at the same spot, held at the invariant point).
-	* Under fit-all the subject is the WHOLE scene, so "keep my anchor" is
-	* meaningless — re-place instead (this is what centers the scene even when
-	* unbounded).
+	* Re-apply the view after a structural, zoom or viewport change. Normally
+	* anchor-preserving (keep looking at the same spot, held at the invariant
+	* point). Under fit-all the subject is the whole scene, so keeping an
+	* anchor is meaningless: re-place instead (which also centers the scene
+	* when unbounded).
 	*/
 	const reapply = (anchor, align) => {
-		if (isFitAll()) goToTarget(ctx.getState().cursor, { behavior: "instant" });
+		if (isFitAll()) goToTarget(state().cursor, { behavior: "instant" });
 		else applyAnchor(anchor, align);
 	};
-	/** Tag what drives the NEXT camera/cursor change — dispatched on flips
-	*  only, read by the page-state feed (see StageState.motionCause). */
-	const markCause = (cause) => {
-		if (ctx.getState().motionCause !== cause) ctx.dispatch({
-			type: "MOTION_CAUSE",
-			cause
-		});
-	};
-	const goToTarget = (pageIndex, opts) => {
+	const goToTarget = (pageIndex, options) => {
 		markCause("programmatic");
-		cancelAnim();
-		const doc = ctx.document();
-		if (!doc || doc.pageCount === 0) return;
-		const target = Math.max(0, Math.min(pageIndex, doc.pageCount - 1));
-		if (target !== ctx.getState().cursor) ctx.dispatch({
-			type: "CURSOR",
-			cursor: target
-		});
-		if (opts?.viewpoint) {
-			ctx.dispatch({
-				type: "PATCH",
-				patch: { zoom: opts.viewpoint.zoom }
-			});
-			applyAnchor(opts.viewpoint.anchor);
+		cancelAnimation();
+		if (pageCount() === 0) return;
+		const target = Math.max(0, Math.min(pageIndex, pageCount() - 1));
+		ctx.state.update(setCursor, target);
+		if (options?.viewpoint) {
+			ctx.state.update(patchSettings, { zoom: options.viewpoint.zoom });
+			applyAnchor(options.viewpoint.anchor);
 			return;
 		}
 		const placement = () => {
-			const sc = buildScene();
-			if (!sc.itemCount) return null;
-			const item = paged() ? sc.items[0] : sc.items[itemIndexOfPage(target)];
-			const zoom = S.resolveZoom(ctx.getState().zoom, fitBox(item), vp(), pad());
+			const current = buildScene();
+			if (!current.itemCount) return null;
+			const item = paged() ? current.items[0] : current.items[itemIndexOfPage(target)];
+			const zoom = resolveZoom(state().zoom, fitBox(item), viewport(), padding());
 			const subject = isFitAll() ? sceneRect() : fits(itemRect(item), zoom) ? itemRect(item) : pageRectOf(item, target);
-			const want = {
-				...ctx.getState().arrivalAlign,
-				...opts?.arrivalAlign
+			const landing = {
+				...state().arrivalAlign,
+				...options?.arrivalAlign
 			};
-			const placed = S.placeCamera(subject, vp(), zoom, pad(), {
-				x: want.x === "keep" ? "start" : want.x,
-				y: want.y === "keep" ? "start" : want.y
-			}, ctx.getState().direction);
+			const placed = placeCamera(subject, viewport(), zoom, padding(), {
+				x: landing.x === "keep" ? "start" : landing.x,
+				y: landing.y === "keep" ? "start" : landing.y
+			}, state().direction);
 			const bounds = boundsFor(item);
-			const settled = S.clampCamera(placed, bounds, vp(), {
+			const settled = clampCamera(placed, bounds, viewport(), {
 				...constraint(),
 				bounded: true
 			});
 			return {
 				camera: {
 					zoom,
-					x: want.x === "keep" ? cam().x : settled.x,
-					y: want.y === "keep" ? cam().y : settled.y
+					x: landing.x === "keep" ? camera().x : settled.x,
+					y: landing.y === "keep" ? camera().y : settled.y
 				},
 				bounds
 			};
 		};
-		if ((opts?.behavior ?? ctx.getState().scrollBehavior) === "smooth") {
-			const p = placement();
-			if (p) animateTo(p.camera, p.bounds);
+		if ((options?.behavior ?? state().scrollBehavior) === "smooth") {
+			const landing = placement();
+			if (landing) animateTo(landing.camera, landing.bounds);
 		} else stabilized(() => {
-			const p = placement();
-			if (p) setCam(p.camera, p.bounds);
+			const landing = placement();
+			if (landing) writeCamera(landing.camera, landing.bounds);
 		});
 	};
-	/** Step by the navigation unit: the ITEM when it fits the viewport, else the PAGE. */
-	const step = (direction, opts) => {
-		const st = ctx.getState();
+	/** Step by the navigation unit: the item when it fits the viewport, else the page. */
+	const step = (direction, options) => {
 		const item = cursorItem();
 		if (!item) return;
-		const { grouping: g } = grouping();
-		if (isFitAll() || fits(itemRect(item), cam().zoom)) {
-			const idx = Math.max(0, Math.min(itemIndexOfPage(st.cursor) + direction, g.length - 1));
-			goToTarget(g[idx][0], opts);
-		} else goToTarget(st.cursor + direction, opts);
+		const { grouping: groups } = grouping();
+		if (isFitAll() || fits(itemRect(item), camera().zoom)) {
+			const index = Math.max(0, Math.min(itemIndexOfPage(state().cursor) + direction, groups.length - 1));
+			goToTarget(groups[index][0], options);
+		} else goToTarget(state().cursor + direction, options);
 	};
-	const ponForIndex = (index) => ctx.document()?.pages[index]?.pageObjectNumber ?? index + 1;
+	const resetView = () => goToTarget(0, { behavior: "instant" });
+	return {
+		stabilized,
+		applyAnchor,
+		reapply,
+		goToTarget,
+		resetView,
+		api: {
+			goToPage: (page, options) => {
+				const index = indexOfTarget(page);
+				if (index !== null) whenPlaced(placement, options, (go) => goToTarget(index, go));
+			},
+			goToFirstPage: (options) => whenPlaced(placement, options, (go) => goToTarget(0, go)),
+			goToLastPage: (options) => whenPlaced(placement, options, (go) => goToTarget(Math.max(0, (ctx.document()?.pageCount ?? 1) - 1), go)),
+			canGoNext: () => state().cursor < pageCount() - 1,
+			canGoPrevious: () => state().cursor > 0,
+			nextPage: (options) => whenPlaced(placement, options, (go) => step(1, go)),
+			previousPage: (options) => whenPlaced(placement, options, (go) => step(-1, go)),
+			resetView
+		}
+	};
+}
+//#endregion
+//#region src/destination.ts
+function revealOfDestination(destination, size) {
+	const { width, height } = size;
+	switch (destination.kind) {
+		case "xyz": {
+			const { x, y, zoom } = destination;
+			return {
+				rect: {
+					x: x ?? 0,
+					y: y ?? 0,
+					width: 0,
+					height: 0
+				},
+				anchor: {
+					x: x != null ? "start" : "keep",
+					y: y != null ? "start" : "keep"
+				},
+				zoom: zoom != null && zoom !== 0 ? { level: zoom } : "keep"
+			};
+		}
+		case "fit": return { zoom: "fit" };
+		case "fitB": return {
+			rect: {
+				x: 0,
+				y: 0,
+				width,
+				height
+			},
+			zoom: "fit"
+		};
+		case "fitH":
+		case "fitBH": {
+			const { y } = destination;
+			return {
+				rect: {
+					x: 0,
+					y: y ?? 0,
+					width,
+					height: 0
+				},
+				zoom: "fit-width",
+				anchor: { y: y != null ? "start" : "keep" }
+			};
+		}
+		case "fitV":
+		case "fitBV": {
+			const { x } = destination;
+			return {
+				rect: {
+					x: x ?? 0,
+					y: 0,
+					width: 0,
+					height
+				},
+				zoom: "fit-height",
+				anchor: { x: x != null ? "start" : "keep" }
+			};
+		}
+		case "fitR": {
+			const { x, y, width: rectWidth, height: rectHeight } = destination;
+			return {
+				rect: {
+					x,
+					y,
+					width: rectWidth,
+					height: rectHeight
+				},
+				zoom: "fit"
+			};
+		}
+	}
+}
+//#endregion
+//#region src/navigation/reveal.ts
+/**
+* Reveals and destinations. A bare reveal is not navigation: minimal
+* visibility, cursor untouched (in paged flow, revealing a page is navigating
+* to it). A positioned reveal (rect, anchor or zoom: a search hit) is an
+* arrival: the cursor is set up front, the camera lands per the anchor
+* policy, and a resolved zoom becomes the zoom intent. A destination is a
+* positioned reveal of the spot it names.
+*/
+function createReveal(ctx, { scene, placement }, { writeCamera, markCause }, { cancelAnimation, animateTo }, { stabilized, goToTarget }) {
+	const { camera, viewport, padding, paged, itemIndexOfPage, worldPageFrame, buildScene, sceneRect, pageRectOf, worldRectForContent, boundsFor, indexOfTarget } = scene;
+	const state = () => ctx.state.get();
+	/**
+	* One axis of a positioned-reveal camera. `undefined` is 'nearest' (move
+	* only when the target is outside the padded view), unless the zoom just
+	* changed: then "do not move" is meaningless and the slack-axis rule
+	* (center) applies. 'keep' never moves the axis (PDF /XYZ null).
+	*/
+	const revealAxis = (anchor, cameraPosition, rectPosition, rectExtent, viewportExtent, zoom, zoomChanged) => {
+		if (anchor === "keep") return cameraPosition;
+		const inset = padding();
+		if (anchor === void 0) {
+			if (!zoomChanged) {
+				const low = cameraPosition + inset / zoom;
+				const high = cameraPosition + (viewportExtent - inset) / zoom;
+				if (rectPosition >= low && rectPosition + rectExtent <= high) return cameraPosition;
+				if (rectExtent > high - low || rectPosition < low) return rectPosition - inset / zoom;
+				return rectPosition + rectExtent - (viewportExtent - inset) / zoom;
+			}
+			anchor = "center";
+		}
+		if (anchor === "start") return rectPosition - inset / zoom;
+		if (anchor === "end") return rectPosition + rectExtent - (viewportExtent - inset) / zoom;
+		const fraction = anchor === "center" ? .5 : Math.min(1, Math.max(0, anchor));
+		return rectPosition + rectExtent / 2 - viewportExtent * fraction / zoom;
+	};
+	const revealAt = (pageIndex, options) => {
+		markCause("programmatic");
+		const pageCount = ctx.document()?.pageCount ?? 0;
+		if (pageCount === 0) return;
+		const target = Math.max(0, Math.min(pageIndex, pageCount - 1));
+		if (!(!!options && (options.rect != null || options.anchor !== void 0 || options.zoom !== void 0 && options.zoom !== "keep"))) {
+			if (paged()) {
+				goToTarget(target, options);
+				return;
+			}
+			const current = buildScene();
+			if (!current.itemCount) return;
+			const page = pageRectOf(current.items[itemIndexOfPage(target)], target);
+			const frame = worldPageFrame();
+			const box = {
+				x: page.x - frame.left,
+				y: page.y - frame.top,
+				width: page.width + frame.left + frame.right,
+				height: page.height + frame.top + frame.bottom
+			};
+			const next = revealCamera(camera(), box, viewport(), padding());
+			const now = camera();
+			if (next.x === now.x && next.y === now.y) return;
+			cancelAnimation();
+			if ((options?.behavior ?? state().scrollBehavior) === "smooth") animateTo(next, sceneRect());
+			else writeCamera(next, sceneRect());
+			return;
+		}
+		cancelAnimation();
+		ctx.state.update(setCursor, target);
+		const place = () => {
+			const current = buildScene();
+			if (!current.itemCount) return null;
+			const item = paged() ? current.items[0] : current.items[itemIndexOfPage(target)];
+			const world = options.rect ? worldRectForContent(item, target, options.rect) : pageRectOf(item, target);
+			const zoomDirective = options.zoom ?? "keep";
+			const availableWidth = Math.max(1, viewport().width - 2 * padding());
+			const availableHeight = Math.max(1, viewport().height - 2 * padding());
+			let zoom = typeof zoomDirective === "object" ? zoomDirective.level : zoomDirective === "fit" ? Math.min(availableWidth / world.width, availableHeight / world.height) : zoomDirective === "fit-width" ? availableWidth / world.width : zoomDirective === "fit-height" ? availableHeight / world.height : camera().zoom;
+			if (!Number.isFinite(zoom) || zoom <= 0) zoom = camera().zoom;
+			const zoomChanged = zoomDirective !== "keep";
+			const anchor = options.anchor ?? {};
+			return {
+				camera: {
+					x: revealAxis(anchor.x, camera().x, world.x, world.width, viewport().width, zoom, zoomChanged),
+					y: revealAxis(anchor.y, camera().y, world.y, world.height, viewport().height, zoom, zoomChanged),
+					zoom
+				},
+				bounds: boundsFor(item),
+				zoomChanged
+			};
+		};
+		const first = place();
+		if (!first) return;
+		if (first.zoomChanged) ctx.state.update(patchSettings, { zoom: { level: first.camera.zoom } });
+		if ((options.behavior ?? state().scrollBehavior) === "smooth") {
+			const landing = place() ?? first;
+			animateTo(landing.camera, landing.bounds);
+		} else stabilized(() => {
+			const landing = place();
+			if (landing) writeCamera(landing.camera, landing.bounds);
+		});
+	};
+	const reveal = (page, options) => {
+		const index = indexOfTarget(page);
+		if (index !== null) whenPlaced(placement, options, (go) => revealAt(index, go));
+	};
+	const goToDestination = (destination, options) => {
+		const layout = ctx.getPage(destination.page);
+		if (!layout) return;
+		whenPlaced(placement, {
+			...revealOfDestination(destination, layout.size),
+			behavior: options?.behavior
+		}, (go) => revealAt(layout.index, go));
+	};
+	return { api: {
+		reveal,
+		goToDestination
+	} };
+}
+//#endregion
+//#region src/navigation/zoom.ts
+/**
+* Zoom verbs. Pointer-less zooms magnify around the zoomAlign focal point
+* (pinch and wheel pass their own pointer to `zoomAround`: physics beats
+* policy); fit modes are zoom intents written through the settings; the
+* double-tap ladder ascends reading postures.
+*/
+/** The zoom factor of one zoomIn or zoomOut step. */
+const ZOOM_STEP = 1.2;
+function createZoom(ctx, { scene }, { syncCursorFromCamera }, { cancelAnimation, animateZoomAnchored }, gestures, settings) {
+	const { camera, viewport, padding, paged, itemIndexOfPage, buildScene, alignPoint, fitBox } = scene;
+	const state = () => ctx.state.get();
+	const zoomAlignPoint = () => alignPoint(state().zoomAlign, viewport());
+	const setViewRotation = (viewRotation) => settings.updateSettings({ viewRotation });
+	return { api: {
+		doubleTapZoom: (point) => {
+			cancelAnimation();
+			const before = buildScene();
+			if (!before.itemCount) return;
+			const item = paged() ? before.items[0] : before.items[itemIndexOfPage(state().cursor)];
+			const fit = fitBox(item);
+			const automatic = resolveZoom({ mode: ZoomMode$1.Automatic }, fit, viewport(), padding());
+			const stops = [
+				automatic,
+				resolveZoom({ mode: ZoomMode$1.FitWidth }, fit, viewport(), padding()),
+				Math.min(automatic * 2.5, ZOOM_MAX)
+			].sort((left, right) => left - right).filter((zoom, index, all) => index === 0 || zoom > all[index - 1] * 1.1);
+			const near = (zoom, stop) => zoom > stop / 1.1 && zoom < stop * 1.1;
+			const onRung = stops.findIndex((stop) => near(camera().zoom, stop));
+			const target = onRung >= 0 ? stops[(onRung + 1) % stops.length] : stops[0];
+			ctx.state.update(patchSettings, { zoom: { level: target } });
+			const after = buildScene();
+			if (!after.itemCount) return;
+			animateZoomAnchored(anchorAtPoint(after, toWorld(camera(), point)), point, target, void 0, syncCursorFromCamera);
+		},
+		zoomIn: () => gestures.zoomAround(zoomAlignPoint(), ZOOM_STEP),
+		zoomOut: () => gestures.zoomAround(zoomAlignPoint(), 1 / ZOOM_STEP),
+		zoomTo: (zoom, options) => {
+			if (typeof zoom === "number") {
+				if (options?.around) gestures.zoomAround(options.around, zoom / camera().zoom);
+				else settings.updateSettings({ zoom: { level: zoom } });
+				return;
+			}
+			settings.updateSettings({ zoom });
+		},
+		zoomBy: (factor, options) => gestures.zoomAround(options?.around ?? zoomAlignPoint(), factor),
+		fitWidth: () => settings.updateSettings({ zoom: { mode: ZoomMode$1.FitWidth } }),
+		fitPage: () => settings.updateSettings({ zoom: { mode: ZoomMode$1.FitPage } }),
+		fitAll: () => settings.updateSettings({ zoom: { mode: ZoomMode$1.FitAll } }),
+		fitAutomatic: () => settings.updateSettings({ zoom: { mode: ZoomMode$1.Automatic } }),
+		setViewRotation,
+		rotateViewBy: (delta) => setViewRotation(addRotations(state().viewRotation, delta === 90 ? 90 : 270))
+	} };
+}
+//#endregion
+//#region src/read/pages.ts
+/**
+* The page reads: laid-out pages with their transforms (PDF points → view px
+* → device px), the scroller projection, the visible set (memoized so reads
+* stay reference-stable), coordinate conversions and the camera, zoom and
+* viewpoint reads.
+*/
+function createPageReads(ctx, { scene }) {
+	const { camera, viewport, dpr, padding, paged, buildScene, cacheKey, stayBounds, cursorItem, currentAnchor } = scene;
+	const state = () => ctx.state.get();
+	const pageObjectNumberAt = (index) => ctx.document()?.pages[index]?.ref.objectNumber ?? index + 1;
 	const unrotatedPoints = (box) => {
 		const content = displaySize({
 			width: box.width,
@@ -920,38 +1252,38 @@ function createStageCapability(ctx, config = {}) {
 		};
 	};
 	const withTransform = (box) => {
-		const reg = ctx.document()?.pages[box.pageIndex];
-		const pageSize = reg ? {
-			width: reg.size.width,
-			height: reg.size.height
+		const registered = ctx.document()?.pages[box.pageIndex];
+		const pageSize = registered ? {
+			width: registered.size.width,
+			height: registered.size.height
 		} : unrotatedPoints(box);
-		const c = cam();
+		const current = camera();
 		const ratio = dpr();
-		const rawX = (box.x - c.x) * c.zoom;
-		const rawY = (box.y - c.y) * c.zoom;
-		const resting = ctx.getState().cameraResting;
+		const rawX = (box.x - current.x) * current.zoom;
+		const rawY = (box.y - current.y) * current.zoom;
+		const resting = state().cameraResting;
 		const screenX = resting ? snapToDevice(rawX, ratio) : rawX;
 		const screenY = resting ? snapToDevice(rawY, ratio) : rawY;
 		const transform = pageTransform({
 			pageSize,
 			rotation: box.rotation,
-			scale: box.contentScale * c.zoom,
-			baseScale: ctx.getState().viewUnitsPerPoint * (reg?.userUnit ?? 1),
+			scale: box.contentScale * current.zoom,
+			baseScale: state().viewUnitsPerPoint * (registered?.userUnit ?? 1),
 			dpr: ratio
 		});
-		const v = vp();
+		const size = viewport();
 		const onScreen = intersectRects({
 			x: -screenX,
 			y: -screenY,
-			width: v.width,
-			height: v.height
+			width: size.width,
+			height: size.height
 		}, {
 			x: 0,
 			y: 0,
 			width: transform.viewWidth,
 			height: transform.viewHeight
 		});
-		const visibleRect = onScreen.width > 0 && onScreen.height > 0 ? transform.viewToContentRect(onScreen) : {
+		const visibleRect = onScreen.width > 0 && onScreen.height > 0 ? transform.viewToPageRect(onScreen) : {
 			x: 0,
 			y: 0,
 			width: 0,
@@ -959,14 +1291,14 @@ function createStageCapability(ctx, config = {}) {
 		};
 		return {
 			...box,
-			pon: ponForIndex(box.pageIndex),
+			ref: toPageRef(pageObjectNumberAt(box.pageIndex)),
 			screenX,
 			screenY,
 			transform,
 			visibleRect
 		};
 	};
-	const EMPTY_SCROLL_METRICS = {
+	const emptyScrollMetrics = {
 		scrollLeft: 0,
 		scrollTop: 0,
 		scrollWidth: 0,
@@ -976,84 +1308,549 @@ function createStageCapability(ctx, config = {}) {
 		scrollableX: false,
 		scrollableY: false
 	};
-	let scrollMemo = null;
+	let lastMetrics = null;
 	const scrollMetricsNow = () => {
-		if (!ctx.getState().placed) return EMPTY_SCROLL_METRICS;
-		const sc = buildScene();
-		const m = S.scrollMetrics(cam(), sc.itemCount ? stayBounds() : {
+		if (!state().placed) return emptyScrollMetrics;
+		const metrics = scrollMetrics(camera(), buildScene().itemCount ? stayBounds() : {
 			x: 0,
 			y: 0,
 			width: 0,
 			height: 0
-		}, vp(), pad());
-		const p = scrollMemo;
-		if (p && p.scrollLeft === m.scrollLeft && p.scrollTop === m.scrollTop && p.scrollWidth === m.scrollWidth && p.scrollHeight === m.scrollHeight && p.clientWidth === m.clientWidth && p.clientHeight === m.clientHeight) return p;
-		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();
-		const items = paged() ? sc.items.slice(0, 1) : sc.query(S.cameraWorldRect(c, v));
-		const sig = `${sceneCache.key}|${ctx.getState().flow}|${c.x},${c.y},${c.zoom}|${v.width}x${v.height}|${dpr()}|r${ctx.getState().cameraResting ? 1 : 0}`;
-		if (sig === visSig) return vis;
-		visSig = sig;
-		vis = items.flatMap((it) => it.pages).map(withTransform);
-		return vis;
-	};
-	const pickSettings = (src) => {
-		const out = {};
-		for (const k of SETTING_KEYS) out[k] = src[k];
-		return out;
-	};
-	const snapshotSettings = () => pickSettings(ctx.getState());
+		}, viewport(), padding());
+		const previous = lastMetrics;
+		if (previous && previous.scrollLeft === metrics.scrollLeft && previous.scrollTop === metrics.scrollTop && previous.scrollWidth === metrics.scrollWidth && previous.scrollHeight === metrics.scrollHeight && previous.clientWidth === metrics.clientWidth && previous.clientHeight === metrics.clientHeight) return previous;
+		lastMetrics = metrics;
+		return metrics;
+	};
+	const noVisiblePages = [];
+	const placedVisiblePages = memo(() => {
+		const current = camera();
+		const size = viewport();
+		buildScene();
+		return [
+			cacheKey(),
+			state().flow,
+			current.x,
+			current.y,
+			current.zoom,
+			size.width,
+			size.height,
+			dpr(),
+			state().cameraResting
+		];
+	}, (_sceneKey, _flow, x, y, zoom, width, height, _dpr, _resting) => {
+		const scene = buildScene();
+		return (paged() ? scene.items.slice(0, 1) : scene.query(cameraWorldRect({
+			x,
+			y,
+			zoom
+		}, {
+			width,
+			height
+		}))).flatMap((item) => item.pages).map(withTransform);
+	});
+	const visiblePages = () => state().placed ? placedVisiblePages() : noVisiblePages;
+	const getPageFrame = (page) => {
+		if (!state().placed) return null;
+		const index = ctx.getPage(page)?.index ?? -1;
+		if (index < 0) return null;
+		const scene = buildScene();
+		if (!scene.itemCount) return null;
+		const box = scene.items[scene.itemOfPage(index)].pages.find((candidate) => candidate.pageIndex === index);
+		return box ? withTransform(box) : null;
+	};
+	const pageToWorld = (page, point) => {
+		const frame = getPageFrame(page);
+		if (!frame) return null;
+		const content = displaySize({
+			width: frame.width,
+			height: frame.height
+		}, frame.rotation);
+		const offset = applyPoint(rotateScaleMatrix(frame.contentScale, content.width, content.height, frame.rotation), point);
+		return {
+			x: frame.x + offset.x,
+			y: frame.y + offset.y
+		};
+	};
+	const visiblePageOf = (page) => {
+		const objectNumber = ctx.getPage(page)?.ref.objectNumber;
+		if (objectNumber === void 0) return null;
+		return visiblePages().find((visible) => visible.ref.objectNumber === objectNumber) ?? null;
+	};
+	return {
+		scrollMetricsNow,
+		visiblePages,
+		api: {
+			getCamera: camera,
+			getViewportSize: viewport,
+			getScrollMetrics: scrollMetricsNow,
+			listVisiblePages: visiblePages,
+			isPageVisible: (page) => visiblePageOf(page) !== null,
+			getCurrentPageIndex: () => state().cursor,
+			getCurrentPage: () => ctx.document()?.pages[state().cursor]?.ref ?? null,
+			getPageCount: () => ctx.document()?.pageCount ?? 0,
+			listCurrentItemPages: () => {
+				const item = cursorItem();
+				const pages = ctx.document()?.pages ?? [];
+				return item ? item.pageIndexes.map((index) => pages[index]).filter((page) => page !== void 0) : [];
+			},
+			getPageFrame,
+			getPageAt: (point) => {
+				for (const page of visiblePages()) {
+					const localX = point.x - page.screenX;
+					const localY = point.y - page.screenY;
+					if (localX >= 0 && localY >= 0 && localX <= page.transform.viewWidth && localY <= page.transform.viewHeight) return {
+						ref: page.ref,
+						point: page.transform.viewToPage({
+							x: localX,
+							y: localY
+						}),
+						scale: page.transform.viewScale,
+						rotation: page.rotation,
+						zoom: page.transform.zoom
+					};
+				}
+				return null;
+			},
+			viewportToPage: (page, point) => {
+				const target = visiblePageOf(page);
+				if (!target) return null;
+				return target.transform.viewToPage({
+					x: point.x - target.screenX,
+					y: point.y - target.screenY
+				});
+			},
+			pageToWorld,
+			pageRectToViewport: (page, rect) => {
+				const frame = getPageFrame(page);
+				if (!frame) return null;
+				const content = displaySize({
+					width: frame.width,
+					height: frame.height
+				}, frame.rotation);
+				const world = applyRect(rotateScaleMatrix(frame.contentScale, content.width, content.height, frame.rotation), rect);
+				const current = camera();
+				const topLeft = toScreen(current, {
+					x: frame.x + world.x,
+					y: frame.y + world.y
+				});
+				return {
+					x: topLeft.x,
+					y: topLeft.y,
+					width: world.width * current.zoom,
+					height: world.height * current.zoom
+				};
+			},
+			worldToViewport: (world) => toScreen(camera(), world),
+			viewportToWorld: (point) => toWorld(camera(), point),
+			pageToViewport: (page, point) => {
+				const world = pageToWorld(page, point);
+				return world ? toScreen(camera(), world) : null;
+			},
+			getViewRotation: () => state().viewRotation,
+			getZoomLevel: () => camera().zoom,
+			getZoomMode: () => {
+				const zoom = state().zoom;
+				return "mode" in zoom ? zoom.mode : "custom";
+			},
+			getViewpoint: () => ({
+				anchor: currentAnchor(),
+				zoom: state().zoom
+			})
+		}
+	};
+}
+//#endregion
+//#region src/services/events.ts
+function createEvents(ctx) {
+	const pageChanged = ctx.events.source();
+	const zoomChanged = ctx.events.source();
+	const cameraChanged = ctx.events.source();
+	const motionEnded = ctx.events.source();
+	const settingsChanged = ctx.events.source();
+	const viewportChanged = ctx.events.source();
+	ctx.state.onChange(({ previous, next }) => {
+		if (previous.camera !== next.camera) {
+			cameraChanged.emit({ camera: next.camera });
+			if (previous.camera.zoom !== next.camera.zoom) zoomChanged.emit({
+				level: next.camera.zoom,
+				previousLevel: previous.camera.zoom,
+				mode: "mode" in next.zoom ? next.zoom.mode : "custom"
+			});
+		}
+		if (previous.cursor !== next.cursor) pageChanged.emit({
+			page: ctx.document()?.pages[next.cursor]?.ref ?? null,
+			pageIndex: next.cursor,
+			previousPageIndex: previous.cursor
+		});
+		if (previous.viewport !== next.viewport) viewportChanged.emit({ size: next.viewport });
+		const changed = SETTING_KEYS.filter((key) => !eqSetting(previous[key], next[key]));
+		if (changed.length) settingsChanged.emit({
+			settings: pickSettings(next),
+			changed
+		});
+	});
+	return {
+		pageChanged,
+		zoomChanged,
+		cameraChanged,
+		motionEnded,
+		settingsChanged,
+		viewportChanged
+	};
+}
+//#endregion
+//#region src/services/scene.ts
+/**
+* The scene model: the document's item grouping, the layout, the memoized
+* scene (continuous flow lays out the whole document; paged flow a one-item
+* slice at the origin), and the pure geometry reads every area builds on:
+* fit, alignment points, clamp bounds and anchors. Reads only; nothing here
+* changes state.
+*/
+function createScene(ctx) {
+	const state = () => ctx.state.get();
+	const camera = () => state().camera;
+	const viewport = () => state().viewport;
+	const dpr = () => state().dpr;
+	const padding = () => state().padding;
+	const paged = () => state().flow === "paged";
+	const isFitAll = () => {
+		const zoom = state().zoom;
+		return "mode" in zoom && zoom.mode === ZoomMode$1.FitAll;
+	};
+	const grouping = memo(() => [ctx.document()?.pageCount ?? 0, state().spread], (pageCount, spread) => {
+		const groups = groupPages(pageCount, spread);
+		return {
+			grouping: groups,
+			firstPages: groups.map((item) => item[0])
+		};
+	});
+	const itemCountFull = () => grouping().grouping.length;
+	const itemIndexOfPage = (pageIndex) => {
+		const firstPages = grouping().firstPages;
+		let low = 0;
+		let high = firstPages.length;
+		while (low < high) {
+			const middle = low + high >> 1;
+			if (firstPages[middle] <= pageIndex) low = middle + 1;
+			else high = middle;
+		}
+		return Math.max(0, low - 1);
+	};
+	const effectiveZoom = () => {
+		const zoom = state().zoom;
+		return "level" in zoom ? zoom.level : Math.max(state().camera.zoom, 1e-4);
+	};
+	const wrapLineWidth = () => Math.max(1, (viewport().width - 2 * padding()) / effectiveZoom());
+	const worldPageFrame = () => {
+		const frame = state().pageFrame;
+		if (!frame.top && !frame.right && !frame.bottom && !frame.left) return frame;
+		const zoom = effectiveZoom();
+		return {
+			top: frame.top / zoom,
+			right: frame.right / zoom,
+			bottom: frame.bottom / zoom,
+			left: frame.left / zoom
+		};
+	};
+	const frameKey = () => {
+		const frame = state().pageFrame;
+		if (!frame.top && !frame.right && !frame.bottom && !frame.left) return "-";
+		const world = worldPageFrame();
+		return `${Math.round(world.top)},${Math.round(world.right)},${Math.round(world.bottom)},${Math.round(world.left)}`;
+	};
+	const worldGap = () => {
+		const gap = state().gap;
+		return typeof gap === "number" ? gap : gap.px ? gap.px / effectiveZoom() : 0;
+	};
+	const gapKey = () => {
+		const gap = state().gap;
+		return typeof gap === "number" ? String(gap) : `px:${Math.round(worldGap())}`;
+	};
+	const layoutFor = (groups) => {
+		const settings = state();
+		const registryPages = ctx.document()?.pages ?? [];
+		const viewRotation = settings.viewRotation;
+		const pages = viewRotation === 0 ? registryPages : registryPages.map((page) => ({
+			...page,
+			rotation: addRotations(page.rotation, viewRotation)
+		}));
+		const pageFrame = worldPageFrame();
+		const gap = worldGap();
+		const viewUnitsPerPoint = settings.viewUnitsPerPoint;
+		if (settings.layout === "grid") return gridLayout(pages, groups, {
+			gap,
+			sizing: settings.sizing,
+			direction: settings.direction,
+			pageFrame,
+			viewUnitsPerPoint,
+			columns: typeof settings.columns === "number" ? settings.columns : void 0,
+			lineWidth: settings.columns === "auto" ? wrapLineWidth() : void 0
+		});
+		return linearLayout(pages, groups, {
+			axis: settings.layout === "horizontal" ? "x" : "y",
+			gap,
+			sizing: settings.sizing,
+			direction: settings.direction,
+			pageFrame,
+			viewUnitsPerPoint
+		});
+	};
+	const columnsKey = () => {
+		const settings = state();
+		if (settings.layout !== "grid") return "-";
+		return settings.columns === "auto" ? `auto:${Math.round(wrapLineWidth())}` : String(settings.columns);
+	};
+	const SCENE_KEY_FUNCTIONS = {
+		columns: columnsKey,
+		gap: gapKey,
+		pageFrame: frameKey
+	};
+	const SCENE_KEYS = SETTING_KEYS.filter((key) => SETTINGS_EFFECT[key] === "scene");
+	const settingsKey = () => SCENE_KEYS.map((key) => {
+		const keyFunction = SCENE_KEY_FUNCTIONS[key];
+		if (keyFunction) return keyFunction();
+		const value = state()[key];
+		return typeof value === "object" && value !== null ? JSON.stringify(value) : String(value);
+	}).join("|");
+	let sceneCache = null;
+	const documentKey = () => {
+		const document = ctx.document();
+		return document ? `${document.pageCount}.${document.revision}` : "0.0";
+	};
+	const buildScene = () => {
+		const { grouping: groups } = grouping();
+		if (state().flow === "paged") {
+			const index = groups.length ? Math.min(itemIndexOfPage(state().cursor), groups.length - 1) : 0;
+			const key = `paged|${documentKey()}|${settingsKey()}|${index}`;
+			if (sceneCache && sceneCache.key === key) return sceneCache.scene;
+			const scene = layoutFor(groups.length ? [groups[index]] : []);
+			sceneCache = {
+				key,
+				scene
+			};
+			return scene;
+		}
+		const key = `continuous|${documentKey()}|${settingsKey()}`;
+		if (sceneCache && sceneCache.key === key) return sceneCache.scene;
+		const scene = layoutFor(groups);
+		sceneCache = {
+			key,
+			scene
+		};
+		return scene;
+	};
+	/** Drop the memoized scene (a 'scene' or 'reflow' setting changed, or a view was restored). */
+	const invalidate = () => {
+		sceneCache = null;
+	};
+	/** The current scene's cache key, part of the visible-pages signature. */
+	const cacheKey = () => sceneCache.key;
+	const sceneRect = () => {
+		const { width, height } = buildScene().size;
+		return {
+			x: 0,
+			y: 0,
+			width,
+			height
+		};
+	};
+	const itemRect = (item) => ({
+		x: item.x,
+		y: item.y,
+		width: item.width,
+		height: item.height
+	});
+	const pageRectOf = (item, pageIndex) => {
+		const box = item.pages.find((page) => page.pageIndex === pageIndex) ?? item.pages[0];
+		return {
+			x: box.x,
+			y: box.y,
+			width: box.width,
+			height: box.height
+		};
+	};
+	/** The item shown for the cursor: the slice's only item (paged) or the full-scene item. */
+	const cursorItem = () => {
+		const scene = buildScene();
+		return paged() ? scene.items[0] : scene.items[itemIndexOfPage(state().cursor)];
+	};
+	/**
+	* A page-space rect on a page → a world rect: the same quarter-turn
+	* matrix `pageRectToViewport` uses, minus the camera, so a positioned
+	* reveal and the rendered overlay never disagree about where a rect is.
+	*/
+	const worldRectForContent = (item, pageIndex, rect) => {
+		const box = item.pages.find((page) => page.pageIndex === pageIndex) ?? item.pages[0];
+		const content = displaySize({
+			width: box.width,
+			height: box.height
+		}, box.rotation);
+		const world = applyRect(rotateScaleMatrix(box.contentScale, content.width, content.height, box.rotation), rect);
+		return {
+			x: box.x + world.x,
+			y: box.y + world.y,
+			width: world.width,
+			height: world.height
+		};
+	};
+	const fits = (rect, zoom) => {
+		const size = viewport();
+		const inset = padding();
+		const tolerance = .5;
+		return rect.width * zoom <= size.width - 2 * inset + tolerance && rect.height * zoom <= size.height - 2 * inset + tolerance;
+	};
+	const alignFraction = (value) => value === "start" ? 0 : value === "center" ? .5 : value === "end" ? 1 : Math.min(1, Math.max(0, value));
+	const alignPoint = (alignment, size) => {
+		const rtl = state().direction === "rtl";
+		const alignX = rtl && alignment.x === "start" ? "end" : rtl && alignment.x === "end" ? "start" : alignment.x;
+		const inset = padding();
+		return {
+			x: inset + (size.width - 2 * inset) * alignFraction(alignX),
+			y: inset + (size.height - 2 * inset) * alignFraction(alignment.y)
+		};
+	};
+	const anchorPoint = () => alignPoint(state().anchorAlign, viewport());
+	/** The box the zoom intent fits: the whole scene (fit-all), the current
+	*  item (paged: per-page fit), or the document maximum (continuous: a
+	*  document-stable zoom). */
+	const fitBox = (item) => {
+		if (isFitAll()) return buildScene().size;
+		return paged() ? {
+			width: item.width,
+			height: item.height
+		} : buildScene().maxItemSize;
+	};
+	/** The clamp rect for a camera write targeting this item (the scene in continuous flow). */
+	const boundsFor = (item) => paged() ? itemRect(item) : sceneRect();
+	/** The clamp rect for a write that stays put (pan, zoom): the slice item (paged) or the scene. */
+	const stayBounds = () => paged() ? itemRect(buildScene().items[0]) : sceneRect();
+	const constraint = () => ({
+		bounded: state().bounded,
+		padding: padding(),
+		fitAlign: state().fitAlign,
+		direction: state().direction
+	});
+	const anchorAt = (at) => {
+		const scene = buildScene();
+		return scene.itemCount ? anchorFromCamera(camera(), scene, viewport(), at) : {
+			pageIndex: state().cursor,
+			fx: .5,
+			fy: 0
+		};
+	};
+	const currentAnchor = () => anchorAt(anchorPoint());
+	const indexOfPage = (page) => ctx.getPage(page)?.index ?? -1;
+	/**
+	* A page argument (a `PageRef` or a display index) as a display index, or
+	* null when it names no page: a ref not in the document, or a number that
+	* isn't a whole number. An index past either end is kept; arrivals clamp it.
+	*/
+	const indexOfTarget = (page) => {
+		if (typeof page === "number") return Number.isInteger(page) ? page : null;
+		const index = indexOfPage(page);
+		return index >= 0 ? index : null;
+	};
+	return {
+		camera,
+		viewport,
+		dpr,
+		padding,
+		paged,
+		isFitAll,
+		grouping,
+		itemCountFull,
+		itemIndexOfPage,
+		worldPageFrame,
+		buildScene,
+		invalidate,
+		cacheKey,
+		sceneRect,
+		itemRect,
+		pageRectOf,
+		cursorItem,
+		worldRectForContent,
+		fits,
+		alignPoint,
+		anchorPoint,
+		fitBox,
+		boundsFor,
+		stayBounds,
+		constraint,
+		anchorAt,
+		currentAnchor,
+		indexOfPage,
+		indexOfTarget
+	};
+}
+//#endregion
+//#region src/services/index.ts
+function createServices(ctx) {
+	return {
+		events: createEvents(ctx),
+		clock: ctx.clock,
+		placement: createPlacementLatch(),
+		scene: createScene(ctx)
+	};
+}
+//#endregion
+//#region src/settings/settings.ts
+/**
+* The settings bag and its responsive resolution. The base (config plus
+* `updateSettings()` changes) merged with the matching rules' patches is the effective
+* settings the state holds. `applySettings` is the one reactive applier: the
+* strongest effect among the touched settings wins ('reflow' ⊃ 'scene'/'refit'
+* ⊃ 'reclamp' ⊃ 'none'), so a breakpoint crossing gets exactly the invariant a
+* hand-written update would.
+*/
+const EFFECT_RANK = {
+	none: 0,
+	reclamp: 1,
+	refit: 2,
+	scene: 3,
+	reflow: 4
+};
+function createSettings(ctx, { scene }, config, { writeCamera }, { cancelAnimation }, { applyAnchor, reapply, goToTarget }) {
+	const { camera, viewport, alignPoint, anchorAt } = scene;
+	const state = () => ctx.state.get();
+	const snapshotSettings = memo(() => SETTING_KEYS.map((key) => state()[key]), () => pickSettings(state()));
 	/**
-	* 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.
+	* React to a settings change per the registry: the strongest effect among
+	* the touched settings wins. Both the public `updateSettings()` and the
+	* responsive driver land here.
 	*/
 	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" });
+		cancelAnimation();
+		const touched = (effect) => SETTING_KEYS.some((key) => patch[key] !== void 0 && SETTINGS_EFFECT[key] === effect);
+		const align = touched("refit") && !touched("scene") && !touched("reflow") ? state().zoomAlign : state().anchorAlign;
+		const anchor = anchorAt(alignPoint(align, viewport()));
+		ctx.state.update(patchSettings, patch);
+		if (touched("scene")) scene.invalidate();
+		if (touched("reflow")) goToTarget(state().cursor, { behavior: "instant" });
 		else if (touched("scene") || touched("refit")) reapply(anchor, align);
-		else if (touched("reclamp")) setCam(cam());
+		else if (touched("reclamp")) writeCamera(camera());
 	};
 	let base = snapshotSettings();
+	const initialBase = base;
 	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
-		});
+		const current = state().activeRules;
+		if (current.length !== active.length || active.some((name, index) => name !== current[index])) ctx.state.update(setActiveRules, 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.
+	* Re-resolve and apply what changed since the last resolution. `react:
+	* true` routes the patch through `applySettings` (the full
+	* anchor-preserving update); `react: false` (inside `setViewportSize`,
+	* whose caller runs its own reframe) only lands the patch and the 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 { effective, active } = resolveResponsive(base, rules, boxOf(viewport()));
 		const patch = {};
-		for (const k of SETTING_KEYS) if (!eqSetting(effective[k], lastEffective[k])) Object.assign(patch, { [k]: effective[k] });
+		for (const key of SETTING_KEYS) if (!eqSetting(effective[key], lastEffective[key])) Object.assign(patch, { [key]: effective[key] });
 		lastEffective = effective;
 		publishActive(active);
 		const keys = Object.keys(patch);
@@ -1062,631 +1859,227 @@ function createStageCapability(ctx, config = {}) {
 			applySettings(patch);
 			return "none";
 		}
-		ctx.dispatch({
-			type: "PATCH",
-			patch
-		});
-		const rank = {
-			none: 0,
-			reclamp: 1,
-			refit: 2,
-			scene: 3,
-			reflow: 4
-		};
+		ctx.state.update(patchSettings, patch);
 		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;
+		for (const key of keys) if (EFFECT_RANK[SETTINGS_EFFECT[key]] > EFFECT_RANK[strongest]) strongest = SETTINGS_EFFECT[key];
+		if (strongest === "scene" || strongest === "reflow") scene.invalidate();
 		return strongest;
 	};
+	const updateSettings = (changes) => {
+		base = mergeSettings(base, changes);
+		syncResponsive(true);
+	};
+	const applyViewState = (view) => {
+		cancelAnimation();
+		base = mergeSettings(base, pickSettings(view));
+		const { effective, active } = resolveResponsive(base, rules, boxOf(viewport()));
+		lastEffective = effective;
+		publishActive(active);
+		ctx.state.update(patchSettings, effective);
+		ctx.state.update(setCursor, view.cursor ?? 0);
+		scene.invalidate();
+		applyAnchor(view.anchor);
+	};
+	return {
+		snapshotSettings,
+		syncResponsive,
+		updateSettings,
+		applyViewState,
+		api: {
+			getSettings: snapshotSettings,
+			resetSettings: () => {
+				base = mergeSettings(initialBase, {});
+				syncResponsive(true);
+			},
+			updateSettings,
+			setResponsiveRules: (next) => {
+				rules = next;
+				syncResponsive(true);
+			},
+			matchesRule: (name) => state().activeRules.includes(name),
+			listActiveRules: () => state().activeRules,
+			applyViewState
+		}
+	};
+}
+//#endregion
+//#region src/view/lifecycle.ts
+function createViewLifecycle(ctx, { scene, placement }, { cancelAnimation }, arrive, settings) {
+	const { dpr, currentAnchor } = scene;
+	const { goToTarget, reapply } = arrive;
+	const { snapshotSettings, syncResponsive } = settings;
+	const state = () => ctx.state.get();
 	const initialViewProviders = [];
-	const api = {
-		camera: cam,
-		viewport: vp,
-		scrollMetrics: scrollMetricsNow,
-		pageCount: () => ctx.document()?.pageCount ?? 0,
-		visiblePages,
-		currentPage: () => ctx.getState().cursor,
-		currentItemPages: () => {
-			const item = cursorItem();
-			return item ? [...item.pageIndexes] : [];
-		},
-		pages: () => (ctx.document()?.pages ?? []).map((p) => ({
-			index: p.index,
-			pon: p.pageObjectNumber,
-			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;
-			const sc = buildScene();
-			if (!sc.itemCount) return null;
-			const box = sc.items[sc.itemOfPage(index)].pages.find((p) => p.pageIndex === index);
-			return box ? withTransform(box) : null;
-		},
-		pageAt: (screen) => {
-			for (const p of visiblePages()) {
-				const lx = screen.x - p.screenX;
-				const ly = screen.y - p.screenY;
-				if (lx >= 0 && ly >= 0 && lx <= p.transform.viewWidth && ly <= p.transform.viewHeight) return {
-					pon: p.pon,
-					point: p.transform.viewToContent({
-						x: lx,
-						y: ly
-					}),
-					scale: p.transform.viewScale,
-					rotation: p.rotation,
-					zoom: p.transform.zoom
-				};
-			}
-			return null;
-		},
-		pointOnPage: (pon, screen) => {
-			const p = visiblePages().find((v) => v.pon === pon);
-			if (!p) return null;
-			return p.transform.viewToContent({
-				x: screen.x - p.screenX,
-				y: screen.y - p.screenY
-			});
-		},
-		pageToWorld: (pon, pt) => {
-			const pr = api.pageRect(pon);
-			if (!pr) return null;
-			const content = displaySize({
-				width: pr.width,
-				height: pr.height
-			}, pr.rotation);
-			const offset = applyPoint(rotateScaleMatrix(pr.contentScale, content.width, content.height, pr.rotation), pt);
-			return {
-				x: pr.x + offset.x,
-				y: pr.y + offset.y
-			};
-		},
-		pageRectToScreen: (pon, rect) => {
-			const pr = api.pageRect(pon);
-			if (!pr) return null;
-			const content = displaySize({
-				width: pr.width,
-				height: pr.height
-			}, pr.rotation);
-			const wr = applyRect(rotateScaleMatrix(pr.contentScale, content.width, content.height, pr.rotation), rect);
-			const c = cam();
-			const tl = S.toScreen(c, {
-				x: pr.x + wr.x,
-				y: pr.y + wr.y
-			});
-			return {
-				x: tl.x,
-				y: tl.y,
-				width: wr.width * c.zoom,
-				height: wr.height * c.zoom
-			};
-		},
-		toScreen: (w) => S.toScreen(cam(), w),
-		toWorld: (s) => S.toWorld(cam(), s),
-		flow: () => ctx.getState().flow,
-		layout: () => ctx.getState().layout,
-		spread: () => ctx.getState().spread,
-		sizing: () => ctx.getState().sizing,
-		columns: () => ctx.getState().columns,
-		bounded: () => ctx.getState().bounded,
-		padding: () => ctx.getState().padding,
-		gap: () => ctx.getState().gap,
-		pageFrame: () => ctx.getState().pageFrame,
-		fitAlign: () => ctx.getState().fitAlign,
-		arrivalAlign: () => ctx.getState().arrivalAlign,
-		zoomAlign: () => ctx.getState().zoomAlign,
-		anchorAlign: () => ctx.getState().anchorAlign,
-		direction: () => ctx.getState().direction,
-		scrollBehavior: () => ctx.getState().scrollBehavior,
-		viewRotation: () => ctx.getState().viewRotation,
-		zoomLevel: () => cam().zoom,
-		zoomMode: () => {
-			const z = ctx.getState().zoom;
-			return "mode" in z ? z.mode : "custom";
-		},
-		viewpoint: () => ({
-			anchor: currentAnchor(),
-			zoom: ctx.getState().zoom
-		}),
-		settings: snapshotSettings,
-		viewState: () => ({
-			...snapshotSettings(),
-			cursor: ctx.getState().cursor,
-			anchor: currentAnchor()
-		}),
-		setViewport: (v) => {
-			if (!placementStarted) {
-				ctx.dispatch({
-					type: "VP",
-					vp: v
-				});
+	const placeInitial = () => {
+		placement.started = true;
+		const byPriority = [...initialViewProviders].sort((left, right) => right.priority - left.priority);
+		let view = null;
+		for (const provider of byPriority) {
+			view = provider.provide();
+			if (view) break;
+		}
+		if (view) settings.applyViewState(view);
+		else arrive.resetView();
+		const pending = placement.pending;
+		placement.pending = null;
+		pending?.();
+		ctx.state.update(markPlaced);
+	};
+	return { api: {
+		setViewportSize: (size) => {
+			if (!placement.started) {
+				ctx.state.update(setViewport, size);
 				syncResponsive(false);
-				if (v.width > 0 && v.height > 0 && (ctx.document()?.pageCount ?? 0) > 0) api.placeInitial();
+				if (size.width > 0 && size.height > 0 && (ctx.document()?.pageCount ?? 0) > 0) placeInitial();
 				return;
 			}
-			cancelAnim();
+			if (size.width <= 0 || size.height <= 0) return;
+			const current = state().viewport;
+			if (size.width === current.width && size.height === current.height) return;
+			cancelAnimation();
 			const anchor = currentAnchor();
-			ctx.dispatch({
-				type: "VP",
-				vp: v
-			});
-			if (syncResponsive(false) === "reflow") goToTarget(ctx.getState().cursor, { behavior: "instant" });
+			ctx.state.update(setViewport, size);
+			if (syncResponsive(false) === "reflow") goToTarget(state().cursor, { behavior: "instant" });
 			else reapply(anchor);
 		},
 		setDevicePixelRatio: (ratio) => {
-			if (ratio > 0 && ratio !== dpr()) ctx.dispatch({
-				type: "DPR",
-				dpr: ratio
-			});
-		},
-		setCamera: (c) => {
-			markCause("user");
-			cancelAnim();
-			setCam(c);
-			syncCursorFromCamera();
+			if (ratio > 0 && ratio !== dpr()) ctx.state.update(setDpr, ratio);
 		},
-		panBy: (dx, dy) => {
-			markCause("user");
-			cancelAnim();
-			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) => {
-			markCause("user");
-			cancelAnim();
-			if (!buildScene().itemCount) return;
-			const next = S.cameraFromScroll(cam(), stayBounds(), vp(), pad(), opts);
-			if (opts.behavior === "smooth") animateTo(next, stayBounds(), 240, syncCursorFromCamera);
-			else {
-				setCam(next);
-				syncCursorFromCamera();
-			}
-		},
-		scrollBy: ({ left, top, behavior }) => {
-			const m = scrollMetricsNow();
-			api.scrollTo({
-				left: left === void 0 ? void 0 : m.scrollLeft + left,
-				top: top === void 0 ? void 0 : m.scrollTop + top,
-				behavior
-			});
-		},
-		zoomAround: (pt, factor) => {
-			cancelAnim();
-			const before = buildScene();
-			const focal = before.itemCount ? S.anchorAtPoint(before, S.toWorld(cam(), pt)) : null;
-			setCam(S.zoomAround(cam(), pt, factor));
-			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),
-		zoomTo: (spec) => api.update({ zoom: spec }),
-		fitWidth: () => api.update({ zoom: { mode: S.ZoomMode.FitWidth } }),
-		fitPage: () => api.update({ zoom: { mode: S.ZoomMode.FitPage } }),
-		fitAll: () => api.update({ zoom: { mode: S.ZoomMode.FitAll } }),
-		automatic: () => api.update({ zoom: { mode: S.ZoomMode.Automatic } }),
 		refit: () => {
-			if (!placementStarted) return;
-			cancelAnim();
+			if (!placement.started) return;
+			cancelAnimation();
 			reapply(currentAnchor());
 		},
-		goToPage: (pageIndex, opts) => goToTarget(pageIndex, opts),
-		reveal: (pageIndex, opts) => {
-			markCause("programmatic");
-			const doc = ctx.document();
-			if (!doc || doc.pageCount === 0) return;
-			const target = Math.max(0, Math.min(pageIndex, doc.pageCount - 1));
-			if (!(!!opts && (opts.rect != null || opts.anchor !== void 0 || opts.zoom !== void 0 && opts.zoom !== "keep"))) {
-				if (paged()) {
-					goToTarget(target, opts);
-					return;
-				}
-				const sc = buildScene();
-				if (!sc.itemCount) return;
-				const page = pageRectOf(sc.items[itemIndexOfPage(target)], target);
-				const m = worldPageFrame();
-				const box = {
-					x: page.x - m.left,
-					y: page.y - m.top,
-					width: page.width + m.left + m.right,
-					height: page.height + m.top + m.bottom
-				};
-				const camera = S.revealCamera(cam(), box, vp(), pad());
-				const current = cam();
-				if (camera.x === current.x && camera.y === current.y) return;
-				cancelAnim();
-				if ((opts?.behavior ?? ctx.getState().scrollBehavior) === "smooth") animateTo(camera, sceneRect());
-				else setCam(camera, sceneRect());
-				return;
-			}
-			cancelAnim();
-			if (target !== ctx.getState().cursor) ctx.dispatch({
-				type: "CURSOR",
-				cursor: target
-			});
-			const place = () => {
-				const sc = buildScene();
-				if (!sc.itemCount) return null;
-				const item = paged() ? sc.items[0] : sc.items[itemIndexOfPage(target)];
-				const world = opts.rect ? worldRectForContent(item, target, opts.rect) : pageRectOf(item, target);
-				const zd = opts.zoom ?? "keep";
-				const availW = Math.max(1, vp().width - 2 * pad());
-				const availH = Math.max(1, vp().height - 2 * pad());
-				let zoom = typeof zd === "object" ? zd.level : zd === "fit" ? Math.min(availW / world.width, availH / world.height) : zd === "fit-width" ? availW / world.width : zd === "fit-height" ? availH / world.height : cam().zoom;
-				if (!Number.isFinite(zoom) || zoom <= 0) zoom = cam().zoom;
-				const zoomChanged = zd !== "keep";
-				const a = opts.anchor ?? {};
-				return {
-					camera: {
-						x: revealAxis(a.x, cam().x, world.x, world.width, vp().width, zoom, zoomChanged),
-						y: revealAxis(a.y, cam().y, world.y, world.height, vp().height, zoom, zoomChanged),
-						zoom
-					},
-					bounds: boundsFor(item),
-					zoomChanged
-				};
-			};
-			const first = place();
-			if (!first) return;
-			if (first.zoomChanged) ctx.dispatch({
-				type: "PATCH",
-				patch: { zoom: { level: first.camera.zoom } }
-			});
-			if ((opts.behavior ?? ctx.getState().scrollBehavior) === "smooth") {
-				const p = place() ?? first;
-				animateTo(p.camera, p.bounds);
-			} else stabilized(() => {
-				const p = place();
-				if (p) setCam(p.camera, p.bounds);
-			});
-		},
-		next: (opts) => step(1, opts),
-		prev: (opts) => step(-1, opts),
-		lensId: () => ctx.id,
-		update: (patch) => {
-			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 }),
-		setSizing: (sizing) => api.update({ sizing }),
-		setColumns: (columns) => api.update({ columns }),
-		setBounded: (bounded) => api.update({ bounded }),
-		setPadding: (padding) => api.update({ padding }),
-		setGap: (gap) => api.update({ gap }),
-		setPageFrame: (pageFrame) => api.update({ pageFrame }),
-		setFitAlign: (fitAlign) => api.update({ fitAlign }),
-		setArrivalAlign: (arrivalAlign) => api.update({ arrivalAlign }),
-		setZoomAlign: (zoomAlign) => api.update({ zoomAlign }),
-		setAnchorAlign: (anchorAlign) => api.update({ anchorAlign }),
-		setDirection: (direction) => api.update({ direction }),
-		setViewRotation: (viewRotation) => api.update({ viewRotation }),
-		rotateView: (delta) => api.setViewRotation(addRotations(ctx.getState().viewRotation, delta === 90 ? 90 : 270)),
-		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: effective
-			});
-			ctx.dispatch({
-				type: "CURSOR",
-				cursor: view.cursor ?? 0
-			});
-			sceneCache = null;
-			applyAnchor(view.anchor);
-		},
-		provideInitialView: (priority, fn) => {
-			initialViewProviders.push({
+		getViewState: () => ({
+			...snapshotSettings(),
+			cursor: state().cursor,
+			anchor: currentAnchor()
+		}),
+		getLensId: () => ctx.id,
+		provideInitialView: (priority, provide) => {
+			const entry = {
 				priority,
-				fn
-			});
-		},
-		placeInitial: () => {
-			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" });
+				provide
+			};
+			initialViewProviders.push(entry);
+			return () => {
+				const index = initialViewProviders.indexOf(entry);
+				if (index >= 0) initialViewProviders.splice(index, 1);
+			};
 		},
-		resetView: () => goToTarget(0, { behavior: "instant" })
-	};
-	return api;
+		placeInitial
+	} };
 }
 //#endregion
-//#region src/effects.ts
+//#region src/controller.ts
 /**
-* Stage lens effects.
-*
-* 1. Re-fit on page-registry mutations: when rotate/move/delete bump
-*    `DocumentMeta.revision`, the page geometry under this lens changed, so
-*    re-resolve the active zoom intent and re-place against the new
-*    footprint. Steady-state only — it reacts to revision CHANGES, never the
-*    initial value, so it can't race the capability's level-triggered
-*    initial placement.
+* The stage controller: the composition root. It builds the plugin's services
+* once (the events, the timing seam, the scene model), wires each area with
+* the services it declares, and assembles the host capability from the areas'
+* API slices. stage-core is the pure spatial math; the areas are the impure
+* shell that writes state, caches and drives motion, and time enters only
+* through the host's clock (`ctx.clock`).
 *
-* 2. The page-state feed (main lens only, actions plugin present): stage is
-*    AUTHORITATIVE for what page the viewer is on; the action engine's
-*    lifecycle coordinator owns WHEN page-lifecycle triggers fire. This feed
-*    pushes `{ currentPon, visiblePons, placed, cause }` snapshots — pons,
-*    not indexes (reorder-safe) — on placement and on every change; the
-*    coordinator buffers them behind the document-open barrier and diffs
-*    against its last-emitted state, so this side stays a dumb reporter.
+* The camera model: every camera move is defined by what it holds fixed.
+* Gestures (pan, pinch, wheel) hold the page-point under the pointer;
+* navigation lands its target at the arrivalAlign point; positioned reveals
+* and restored viewpoints hold what the call specifies; pointer-less zooms
+* hold the zoomAlign point; reframes (resize, rotation, layout changes) hold
+* the anchorAlign point; and an axis the camera cannot travel rests at fitAlign.
 */
-function registerStageEffects(ctx, token, feedActions = false) {
-	ctx.watch(() => ctx.document()?.revision ?? 0, () => ctx.get(token).refit());
-	if (!feedActions) return;
-	const actions = ctx.tryGet(ActionsToken$1);
-	if (!actions) return;
-	const snapshot = () => {
-		const state = ctx.getState();
-		if (!state.placed) return null;
-		const stage = ctx.get(token);
-		return {
-			currentPon: stage.pages()[state.cursor]?.pon ?? null,
-			visiblePons: stage.visiblePages().map((page) => page.pon),
-			cause: state.motionCause
-		};
-	};
-	ctx.watch(() => {
-		const s = snapshot();
-		return s === null ? "unplaced" : `${s.currentPon ?? -1}|${[...s.visiblePons].sort((a, b) => a - b).join(",")}`;
-	}, () => {
-		const s = snapshot();
-		if (s === null) return;
-		actions.reportPageState({
-			currentPon: s.currentPon,
-			visiblePons: s.visiblePons,
-			placed: true,
-			cause: s.cause
-		});
-	});
-}
-//#endregion
-//#region src/reducer.ts
-const initialStageState = (config) => {
-	const { scheduler: _scheduler, responsive: _responsive, ...overrides } = config;
+function createStageController(ctx, config = {}) {
+	const services = createServices(ctx);
+	const { events } = services;
+	const reads = createPageReads(ctx, services);
+	const write = createCameraWrite(ctx, services);
+	const animation = createAnimation(services, write);
+	const gestures = createGestures(ctx, services, write, animation, reads);
+	const arrive = createArrival(ctx, services, write, animation);
+	const reveal = createReveal(ctx, services, write, animation, arrive);
+	const settings = createSettings(ctx, services, config, write, animation, arrive);
+	const zoom = createZoom(ctx, services, write, animation, gestures.api, settings);
+	const view = createViewLifecycle(ctx, services, animation, arrive, settings);
+	const api = composeApi("stage", [
+		reads.api,
+		animation.api,
+		gestures.api,
+		arrive.api,
+		reveal.api,
+		settings.api,
+		zoom.api,
+		view.api,
+		{
+			onPageChanged: events.pageChanged.on,
+			onZoomChanged: events.zoomChanged.on,
+			onCameraChanged: events.cameraChanged.on,
+			onMotionEnded: events.motionEnded.on,
+			onSettingsChanged: events.settingsChanged.on,
+			onViewportChanged: events.viewportChanged.on
+		}
+	]);
 	return {
-		camera: {
-			x: 0,
-			y: 0,
-			zoom: 1
-		},
-		placed: false,
-		cameraResting: true,
-		vp: {
-			width: 0,
-			height: 0
-		},
-		dpr: 1,
-		cursor: 0,
-		motionCause: "user",
-		activeRules: [],
-		...DEFAULT_SETTINGS,
-		...overrides
+		api,
+		connect: () => connectStage(ctx, api)
 	};
-};
-/** Merge a settings patch, ignoring undefined values (safe for partial restores). */
-const applyPatch = (state, patch) => {
-	const next = { ...state };
-	let key;
-	for (key in patch) {
-		const value = patch[key];
-		if (value !== void 0) Object.assign(next, { [key]: value });
-	}
-	return next;
-};
-/**
-* Pure. Every transition is here; nothing else mutates Stage state. Settings are a
-* flat bag of primitives — one PATCH action sets any subset (the capability decides
-* what camera follow-up, if any, each change needs).
-*/
-const stageReducer = (state, a) => {
-	switch (a.type) {
-		case "CAMERA": return {
-			...state,
-			camera: a.camera
-		};
-		case "CAMERA_REST": return state.cameraResting === a.resting ? state : {
-			...state,
-			cameraResting: a.resting
-		};
-		case "PLACED": return state.placed ? state : {
-			...state,
-			placed: true
-		};
-		case "VP": return {
-			...state,
-			vp: a.vp
-		};
-		case "DPR": return {
-			...state,
-			dpr: a.dpr
-		};
-		case "CURSOR": return {
-			...state,
-			cursor: a.cursor
-		};
-		case "MOTION_CAUSE": return {
-			...state,
-			motionCause: a.cause
-		};
-		case "PATCH": return applyPatch(state, a.patch);
-		case "RESPONSIVE": return {
-			...state,
-			activeRules: a.active
-		};
-		default: return state;
-	}
-};
+}
 //#endregion
 //#region src/stage.plugin.ts
 /**
-* Wires the parts into a kernel plugin. This file is the "manifest": it says what
-* the plugin IS (id, token, state, reducer, capability) — the how lives in the
-* sibling files.
+* The stage plugin: one lens's camera, layout, zoom and navigation over a
+* document. Document-scoped. The actions plugin is optional: with it, the
+* main lens feeds page state to it and interprets GoTo and Named page
+* actions. Pointer input is opted into by the surface binding
+* (`<Stage interaction>` / `createStageSurface`), which both forwards pointer
+* samples and registers this lens's scroll handler.
 */
 const stagePlugin = (options = {}) => {
-	const { id = "stage", token = StageToken, ...config } = options;
+	const { id = DEFAULT_LENS_ID, token = StageToken, ...config } = options;
 	return definePlugin({
 		id,
-		token,
+		token: createHostToken(token),
 		scope: "document",
 		optional: [ActionsToken],
-		initialState: () => initialStageState(config),
-		reduce: stageReducer,
-		capability: (ctx) => createStageCapability(ctx, config),
-		effects: (ctx) => registerStageEffects(ctx, token, id === "stage"),
-		init: (ctx) => {
-			if (id !== "stage") return;
-			const actions = ctx.tryGet(ActionsToken$1);
-			if (!actions) return;
-			ctx.cleanup(actions.registerExecutor("goto", (node) => {
-				if (node.type !== "goto") return {
-					status: "inert",
-					reason: "not a goto node"
-				};
-				const stage = ctx.tryGet(token);
-				const layout = ctx.document()?.pages.find((p) => p.pageObjectNumber === node.destination.pageObjectNumber);
-				if (!stage || !layout) return {
-					status: "failed",
-					error: "no stage or destination page available"
-				};
-				const { pageIndex, options: reveal } = destinationToReveal(node.destination, layout);
-				stage.reveal(pageIndex, {
-					...reveal,
-					behavior: "smooth"
-				});
-				return { status: "executed" };
-			}));
-			ctx.cleanup(actions.registerExecutor("named", (node) => {
-				if (node.type !== "named") return {
-					status: "inert",
-					reason: "not a named node"
-				};
-				const stage = ctx.tryGet(token);
-				if (!stage) return {
-					status: "failed",
-					error: "no stage available"
-				};
-				switch (node.name) {
-					case "NextPage":
-						stage.next({ behavior: "smooth" });
-						return { status: "executed" };
-					case "PrevPage":
-						stage.prev({ behavior: "smooth" });
-						return { status: "executed" };
-					case "FirstPage":
-						stage.goToPage(0, { behavior: "smooth" });
-						return { status: "executed" };
-					case "LastPage":
-						stage.goToPage(Math.max(0, stage.pageCount() - 1), { behavior: "smooth" });
-						return { status: "executed" };
-					default: return {
-						status: "inert",
-						reason: `unknown named action '${node.name}'`
-					};
-				}
-			}));
-		}
+		state: () => initialStageState(config),
+		create: (ctx) => createStageController(ctx, config)
 	});
 };
 //#endregion
+//#region src/state.ts
+/**
+* The Stage page's State table as code: what `useStageState()` returns, and
+* the same fields in every other framework. A second view registered with its
+* own token reads the same fields through its own capability.
+*/
+const stageState = defineState(StageToken, {
+	read: (stage) => ({
+		zoomLevel: stage.getZoomLevel(),
+		zoomMode: stage.getZoomMode(),
+		currentPageIndex: stage.getCurrentPageIndex(),
+		currentPage: stage.getCurrentPage(),
+		pageCount: stage.getPageCount(),
+		viewRotation: stage.getViewRotation(),
+		activeRules: stage.listActiveRules()
+	}),
+	empty: {
+		zoomLevel: 1,
+		zoomMode: ZoomMode.Automatic,
+		currentPageIndex: 0,
+		currentPage: null,
+		pageCount: 0,
+		viewRotation: 0,
+		activeRules: []
+	}
+});
+//#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).
+* (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`)
+* Cursors: 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.
 */
@@ -1696,28 +2089,28 @@ function createScrollHandler(stage, interaction, options = {}) {
 		x: 0,
 		y: 0
 	};
-	const isPanTool = () => interaction.activeTool().enables.has("scroll");
+	const isPanTool = () => interaction.getActiveTool().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);
+		onDown: (sample) => {
+			if (!isPanTool() && sample.page) return false;
+			last = sample.viewport;
+			interaction.claimCursor("stage-grab", "grabbing", 40);
 			return true;
 		},
-		onMove: (s) => {
-			stage.panBy(s.viewport.x - last.x, s.viewport.y - last.y);
-			last = s.viewport;
+		onMove: (sample) => {
+			stage.panBy(sample.viewport.x - last.x, sample.viewport.y - last.y);
+			last = sample.viewport;
 		},
-		onUp: () => interaction.setCursor("stage-grab", null),
-		onHover: (s) => {
-			if (panFallback && !isPanTool()) interaction.setCursor("stage-pan-fallback", s.page ? null : "grab", 5);
+		onUp: () => interaction.claimCursor("stage-grab", null),
+		onHover: (sample) => {
+			if (panFallback && !isPanTool()) interaction.claimCursor("stage-pan-fallback", sample.page ? null : "grab", 5);
 		}
 	};
 }
 //#endregion
-export { DEFAULT_RESPONSIVE, DEFAULT_SETTINGS, StageToken, ZoomMode, boxOf, createScrollHandler, destinationToReveal, matchesQuery, resolveResponsive, settingsEqual, stagePlugin };
+export { DEFAULT_RESPONSIVE, DEFAULT_SETTINGS, StageToken, ZoomMode, boxOf, createScrollHandler, matchesQuery, resolveResponsive, settingsEqual, stagePlugin, stageState };
 
 //# sourceMappingURL=index.js.map