@embedpdf/plugin-stage 3.0.0-next.0

package/dist/index.js

@@ -0,0 +1,1266 @@
+import { createCapabilityToken, definePlugin } from "@embedpdf/core";
+import { InteractionToken } from "@embedpdf/plugin-interaction";
+import * as S from "@embedpdf/core-stage";
+import { ZoomMode, ZoomMode as ZoomMode$1 } from "@embedpdf/core-stage";
+import { addRotations, applyPoint, applyRect, displaySize, intersectRects, pageGeometry, pageTransform, rotateScaleMatrix, snapToDevice } from "@embedpdf/core-geometry";
+//#region src/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.
+*/
+const DEFAULT_SETTINGS = {
+	flow: "continuous",
+	layout: "vertical",
+	spread: "none",
+	sizing: "intrinsic",
+	columns: "square",
+	bounded: true,
+	padding: 24,
+	gap: 16,
+	pageFrame: {
+		top: 0,
+		right: 0,
+		bottom: 0,
+		left: 0
+	},
+	direction: "ltr",
+	fitAlign: {
+		x: "center",
+		y: "center"
+	},
+	arrivalAlign: {
+		x: "start",
+		y: "start"
+	},
+	zoomAlign: {
+		x: "center",
+		y: "center"
+	},
+	anchorAlign: {
+		x: "start",
+		y: "start"
+	},
+	viewRotation: 0,
+	zoom: { mode: ZoomMode$1.Automatic },
+	scrollBehavior: "smooth",
+	viewUnitsPerPoint: 96 / 72
+};
+const SETTINGS_EFFECT = {
+	flow: "reflow",
+	layout: "scene",
+	spread: "scene",
+	sizing: "scene",
+	columns: "scene",
+	bounded: "reclamp",
+	padding: "reclamp",
+	gap: "scene",
+	pageFrame: "scene",
+	direction: "scene",
+	fitAlign: "reclamp",
+	arrivalAlign: "none",
+	zoomAlign: "none",
+	anchorAlign: "none",
+	viewRotation: "scene",
+	zoom: "refit",
+	scrollBehavior: "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 — 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
+/**
+* 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; the one host dependency it has (frame
+*     timing) enters through an injected Scheduler, never a hidden global.
+*
+* 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.
+*/
+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;
+		}
+		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;
+	};
+	const gapKey = () => {
+		const g = ctx.getState().gap;
+		return typeof g === "number" ? String(g) : `px:${Math.round(worldGap())}`;
+	};
+	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 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 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
+		};
+		return scene;
+	};
+	const sceneRect = () => {
+		const { width, height } = buildScene().size;
+		return {
+			x: 0,
+			y: 0,
+			width,
+			height
+		};
+	};
+	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 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
+		};
+	};
+	/**
+	* 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
+	});
+	const setCam = (next, bounds = stayBounds()) => {
+		ctx.dispatch({
+			type: "CAMERA",
+			camera: S.clampCamera(next, bounds, vp(), constraint())
+		});
+	};
+	/**
+	* 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.
+	*/
+	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();
+		const ease = (t) => 1 - Math.pow(1 - t, 3);
+		let started = false;
+		let t0 = 0;
+		const tick = (now) => {
+			if (!started) {
+				started = true;
+				t0 = now;
+			}
+			const k = ease(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 anchorAt = (at) => {
+		const sc = buildScene();
+		return sc.itemCount ? S.anchorFromCamera(cam(), sc, vp(), at) : {
+			pageIndex: ctx.getState().cursor,
+			fx: .5,
+			fy: 0
+		};
+	};
+	const currentAnchor = () => anchorAt(anchorPoint());
+	/**
+	* 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).
+	*/
+	const stabilized = (place) => {
+		for (let attempt = 0; attempt < 3; attempt++) {
+			const scene = buildScene();
+			place();
+			if (buildScene() === scene) 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));
+		});
+	};
+	/**
+	* 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).
+	*/
+	const reapply = (anchor, align) => {
+		if (isFitAll()) goToTarget(ctx.getState().cursor, { behavior: "instant" });
+		else applyAnchor(anchor, align);
+	};
+	const goToTarget = (pageIndex, opts) => {
+		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);
+			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 subject = isFitAll() ? sceneRect() : fits(itemRect(item), zoom) ? itemRect(item) : pageRectOf(item, target);
+			const want = {
+				...ctx.getState().arrivalAlign,
+				...opts?.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 bounds = boundsFor(item);
+			const settled = S.clampCamera(placed, bounds, vp(), {
+				...constraint(),
+				bounded: true
+			});
+			return {
+				camera: {
+					zoom,
+					x: want.x === "keep" ? cam().x : settled.x,
+					y: want.y === "keep" ? cam().y : settled.y
+				},
+				bounds
+			};
+		};
+		if ((opts?.behavior ?? ctx.getState().scrollBehavior) === "smooth") {
+			const p = placement();
+			if (p) animateTo(p.camera, p.bounds);
+		} else stabilized(() => {
+			const p = placement();
+			if (p) setCam(p.camera, p.bounds);
+		});
+	};
+	/** Step by the navigation unit: the ITEM when it fits the viewport, else the PAGE. */
+	const step = (direction, opts) => {
+		const st = ctx.getState();
+		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 ponForIndex = (index) => ctx.document()?.pages[index]?.pageObjectNumber ?? index + 1;
+	const unrotatedPoints = (box) => {
+		const content = displaySize({
+			width: box.width,
+			height: box.height
+		}, box.rotation);
+		return {
+			width: content.width / box.contentScale,
+			height: content.height / box.contentScale
+		};
+	};
+	const withTransform = (box) => {
+		const reg = ctx.document()?.pages[box.pageIndex];
+		const pageSize = reg ? {
+			width: reg.size.width,
+			height: reg.size.height
+		} : unrotatedPoints(box);
+		const c = cam();
+		const ratio = dpr();
+		const screenX = snapToDevice((box.x - c.x) * c.zoom, ratio);
+		const screenY = snapToDevice((box.y - c.y) * c.zoom, ratio);
+		const transform = pageTransform({
+			pageSize,
+			rotation: box.rotation,
+			scale: box.contentScale * c.zoom,
+			baseScale: ctx.getState().viewUnitsPerPoint * (reg?.userUnit ?? 1),
+			dpr: ratio
+		});
+		const v = vp();
+		const onScreen = intersectRects({
+			x: -screenX,
+			y: -screenY,
+			width: v.width,
+			height: v.height
+		}, {
+			x: 0,
+			y: 0,
+			width: transform.viewWidth,
+			height: transform.viewHeight
+		});
+		const visibleRect = onScreen.width > 0 && onScreen.height > 0 ? transform.viewToPageRect(onScreen) : {
+			x: 0,
+			y: 0,
+			width: 0,
+			height: 0
+		};
+		return {
+			...box,
+			pon: ponForIndex(box.pageIndex),
+			screenX,
+			screenY,
+			transform,
+			visibleRect
+		};
+	};
+	let scrollMemo = null;
+	const scrollMetricsNow = () => {
+		const sc = buildScene();
+		const m = S.scrollMetrics(cam(), sc.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;
+	};
+	let visSig = "";
+	let vis = [];
+	const visiblePages = () => {
+		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()}`;
+		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());
+	const initialViewProviders = [];
+	let hasPlaced = false;
+	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) => {
+			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.viewToPage({
+						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.viewToPage({
+				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 (!hasPlaced) {
+				ctx.dispatch({
+					type: "VP",
+					vp: v
+				});
+				if (v.width > 0 && v.height > 0 && (ctx.document()?.pageCount ?? 0) > 0) api.placeInitial();
+				return;
+			}
+			cancelAnim();
+			const anchor = currentAnchor();
+			ctx.dispatch({
+				type: "VP",
+				vp: v
+			});
+			reapply(anchor);
+		},
+		setDevicePixelRatio: (ratio) => {
+			if (ratio > 0 && ratio !== dpr()) ctx.dispatch({
+				type: "DPR",
+				dpr: ratio
+			});
+		},
+		setCamera: (c) => {
+			cancelAnim();
+			setCam(c);
+			syncCursorFromCamera();
+		},
+		panBy: (dx, dy) => {
+			cancelAnim();
+			setCam(S.panByScreen(cam(), dx, dy));
+			syncCursorFromCamera();
+		},
+		scrollTo: (opts) => {
+			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));
+			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));
+			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 (!hasPlaced) return;
+			cancelAnim();
+			reapply(currentAnchor());
+		},
+		goToPage: (pageIndex, opts) => goToTarget(pageIndex, opts),
+		reveal: (pageIndex, opts) => {
+			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 !== void 0 || 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),
+		update: (patch) => {
+			cancelAnim();
+			const touched = (effect) => SETTING_KEYS.some((k) => patch[k] !== void 0 && SETTINGS_EFFECT[k] === effect);
+			const align = touched("refit") && !touched("scene") && !touched("reflow") ? ctx.getState().zoomAlign : ctx.getState().anchorAlign;
+			const anchor = anchorAt(alignPoint(align, vp()));
+			ctx.dispatch({
+				type: "PATCH",
+				patch
+			});
+			if (touched("scene")) sceneCache = null;
+			if (touched("reflow")) goToTarget(ctx.getState().cursor, { behavior: "instant" });
+			else if (touched("scene") || touched("refit")) reapply(anchor, align);
+			else if (touched("reclamp")) setCam(cam());
+		},
+		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();
+			ctx.dispatch({
+				type: "PATCH",
+				patch: pickSettings(view)
+			});
+			ctx.dispatch({
+				type: "CURSOR",
+				cursor: view.cursor ?? 0
+			});
+			sceneCache = null;
+			applyAnchor(view.anchor);
+		},
+		provideInitialView: (priority, fn) => {
+			initialViewProviders.push({
+				priority,
+				fn
+			});
+		},
+		placeInitial: () => {
+			hasPlaced = 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);
+					return;
+				}
+			}
+			api.resetView();
+		},
+		resetView: () => goToTarget(0, { behavior: "instant" })
+	};
+	return api;
+}
+//#endregion
+//#region src/scroll-handler.ts
+/**
+* Pan-the-camera as an interaction handler. Live under the built-in `pan` tool
+* (the `scroll` tag) and — with `panFallback` — under every tool, where it then
+* captures ONLY page-gap drags (on-page downs belong to the active tool, which
+* claims them first at higher priority). It uses the sample's viewport delta, so
+* it pans over the whole viewport (pages and gaps).
+*
+* Cursor feel: a closed hand (`grabbing`) while dragging; an open hand (`grab`)
+* hovering a gap under a non-pan tool. The pan tool's own resting `grab` comes
+* from its `Tool.cursor`, so hovering it needs no claim here.
+*/
+function createScrollHandler(stage, interaction, options = {}) {
+	const panFallback = options.panFallback ?? true;
+	let last = {
+		x: 0,
+		y: 0
+	};
+	const isPanTool = () => interaction.activeTool().enables.has("scroll");
+	return {
+		id: "stage-scroll",
+		priority: 10,
+		enabledFor: (tool) => tool.enables.has("scroll") || panFallback,
+		onDown: (s) => {
+			if (!isPanTool() && s.page) return false;
+			last = s.viewport;
+			interaction.setCursor("stage-grab", "grabbing", 40);
+			return true;
+		},
+		onMove: (s) => {
+			stage.panBy(s.viewport.x - last.x, s.viewport.y - last.y);
+			last = s.viewport;
+		},
+		onUp: () => interaction.setCursor("stage-grab", null),
+		onHover: (s) => {
+			if (panFallback && !isPanTool()) interaction.setCursor("stage-pan-fallback", s.page ? null : "grab", 5);
+		}
+	};
+}
+//#endregion
+//#region src/effects.ts
+/**
+* The one effect a stage lens needs: when the document's page registry changes
+* (rotate/move/delete bump `DocumentMeta.revision`), the page geometry under
+* this lens just changed, so re-fit — re-resolve the active zoom intent and
+* re-place against the new footprint.
+*
+* Without it, fit/pixel zoom modes stay anchored to the pre-mutation dimensions:
+* `pageWidth: 110` renders wider after a 90° rotation (width↔height swap), and
+* `fitPage` over- or under-fills. The scene already re-keys on the revision, so
+* only the resolved `cam.zoom` was stale; `refit()` recomputes it.
+*
+* Steady-state only: this reacts to revision CHANGES, never the initial value,
+* so it can't race the capability's level-triggered initial placement (the
+* reason the rest of the plugin is effect-free).
+*/
+function registerStageEffects(ctx, token) {
+	ctx.watch(() => ctx.document()?.revision ?? 0, () => ctx.get(token).refit());
+}
+//#endregion
+//#region src/reducer.ts
+const initialStageState = (config) => {
+	const { scheduler: _scheduler, ...overrides } = config;
+	return {
+		camera: {
+			x: 0,
+			y: 0,
+			zoom: 1
+		},
+		vp: {
+			width: 0,
+			height: 0
+		},
+		dpr: 1,
+		cursor: 0,
+		...DEFAULT_SETTINGS,
+		...overrides
+	};
+};
+/** 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 "VP": return {
+			...state,
+			vp: a.vp
+		};
+		case "DPR": return {
+			...state,
+			dpr: a.dpr
+		};
+		case "CURSOR": return {
+			...state,
+			cursor: a.cursor
+		};
+		case "PATCH": return applyPatch(state, a.patch);
+		default: return state;
+	}
+};
+//#endregion
+//#region src/types.ts
+const StageToken = createCapabilityToken("stage");
+//#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.
+*/
+const stagePlugin = (options = {}) => {
+	const { id = "stage", token = StageToken, interaction = false, panFallback = true, ...config } = options;
+	return definePlugin({
+		id,
+		token,
+		scope: "document",
+		optional: interaction ? [InteractionToken] : void 0,
+		initialState: () => initialStageState(config),
+		reduce: stageReducer,
+		capability: (ctx) => createStageCapability(ctx, config),
+		init: interaction ? (ctx) => {
+			const ix = ctx.tryGet(InteractionToken);
+			if (ix) ix.registerHandler(createScrollHandler(ctx.get(token), ix, { panFallback }));
+		} : void 0,
+		effects: (ctx) => registerStageEffects(ctx, token)
+	});
+};
+//#endregion
+//#region src/destination.ts
+/**
+* PDF destination → reveal: the pure translator between the PDF protocol's
+* navigation vocabulary (ISO 32000-1 §12.3.2.2) and the Stage's arrival
+* primitive. Outline clicks, link annotations, and `/OpenAction` all
+* resolve (engine-side) to an explicit `PdfDestination`; this maps it onto
+* ONE `reveal(pageIndex, options)` call — no destination-specific camera
+* code exists anywhere else.
+*
+* The whole protocol collapses onto three knobs:
+*   rect   — what to look at (a point for /XYZ, a rect for /FitR, the
+*            page for /Fit, the content bounding box for /FitB*)
+*   zoom   — 'keep' | {level} | 'fit' | 'fit-width' | 'fit-height'
+*   anchor — where it lands; 'keep' encodes the spec's null-means-retain
+*
+* Coordinates convert PDF user space (y-up, absolute) → content space
+* (y-down, crop-relative) through the SAME `pdfToContent` matrix selection
+* and search use, so a destination and an overlay can never disagree.
+*/
+/**
+* Translate one explicit destination against its target page's layout.
+* `bbox` is the page's content BOUNDING box in CONTENT space, for the
+* `/FitB*` kinds — pass it when known; the crop box is the spec-tolerated
+* fallback until the engine exposes it.
+*/
+function destinationToReveal(dest, layout, bbox) {
+	const geo = pageGeometry({
+		crop: layout.boxes.crop,
+		rotation: layout.rotation,
+		userUnit: layout.userUnit
+	}, 1);
+	const crop = layout.boxes.crop;
+	const toContent = (x, y) => applyPoint(geo.pdfToContent, {
+		x,
+		y
+	});
+	const page = {
+		x: 0,
+		y: 0,
+		width: layout.size.width,
+		height: layout.size.height
+	};
+	const box = bbox ?? page;
+	const options = (() => {
+		switch (dest.kind) {
+			case "xyz": {
+				const hasLeft = dest.left != null;
+				const hasTop = dest.top != null;
+				const p = toContent(dest.left ?? crop.left, dest.top ?? crop.top);
+				return {
+					rect: {
+						x: p.x,
+						y: p.y,
+						width: 0,
+						height: 0
+					},
+					anchor: {
+						x: hasLeft ? "start" : "keep",
+						y: hasTop ? "start" : "keep"
+					},
+					zoom: dest.zoom != null && dest.zoom !== 0 ? { level: dest.zoom } : "keep"
+				};
+			}
+			case "fit": return { zoom: "fit" };
+			case "fitH": {
+				const hasTop = dest.top != null;
+				return {
+					rect: {
+						x: 0,
+						y: hasTop ? toContent(crop.left, dest.top).y : 0,
+						width: page.width,
+						height: 0
+					},
+					zoom: "fit-width",
+					anchor: { y: hasTop ? "start" : "keep" }
+				};
+			}
+			case "fitV": {
+				const hasLeft = dest.left != null;
+				return {
+					rect: {
+						x: hasLeft ? toContent(dest.left, crop.top).x : 0,
+						y: 0,
+						width: 0,
+						height: page.height
+					},
+					zoom: "fit-height",
+					anchor: { x: hasLeft ? "start" : "keep" }
+				};
+			}
+			case "fitR": {
+				const tl = toContent(dest.left, dest.top);
+				const br = toContent(dest.right, dest.bottom);
+				return {
+					rect: {
+						x: Math.min(tl.x, br.x),
+						y: Math.min(tl.y, br.y),
+						width: Math.abs(br.x - tl.x),
+						height: Math.abs(br.y - tl.y)
+					},
+					zoom: "fit"
+				};
+			}
+			case "fitB": return {
+				rect: box,
+				zoom: "fit"
+			};
+			case "fitBH": {
+				const hasTop = dest.top != null;
+				const y = hasTop ? toContent(crop.left, dest.top).y : box.y;
+				return {
+					rect: {
+						x: box.x,
+						y,
+						width: box.width,
+						height: 0
+					},
+					zoom: "fit-width",
+					anchor: { y: hasTop ? "start" : "keep" }
+				};
+			}
+			case "fitBV": {
+				const hasLeft = dest.left != null;
+				return {
+					rect: {
+						x: hasLeft ? toContent(dest.left, crop.top).x : box.x,
+						y: box.y,
+						width: 0,
+						height: box.height
+					},
+					zoom: "fit-height",
+					anchor: { x: hasLeft ? "start" : "keep" }
+				};
+			}
+		}
+	})();
+	return {
+		pageIndex: layout.index,
+		options
+	};
+}
+//#endregion
+//#region src/wheel.ts
+/** The per-notch step for discrete wheels — the zoom buttons' ratio. */
+const NOTCH = 1.2;
+/** Zoom factor for a ctrl/cmd wheel event (the caller decides zoom vs pan). */
+function wheelZoomFactor(e) {
+	if (e.deltaMode !== 0) return Math.pow(NOTCH, -Math.sign(e.deltaY));
+	if (e.ctrlKey) {
+		if (Math.abs(e.deltaY) >= 100) return Math.pow(NOTCH, -Math.sign(e.deltaY));
+		return Math.exp(-e.deltaY / 100);
+	}
+	return Math.exp(-e.deltaY * .0015);
+}
+//#endregion
+export { DEFAULT_SETTINGS, StageToken, ZoomMode, destinationToReveal, settingsEqual, stagePlugin, wheelZoomFactor };
+
+//# sourceMappingURL=index.js.map