@embedpdf/plugin-stage 3.0.0-next.10 → 3.0.0-next.11

package/dist/index.cjs

@@ -21,7 +21,11 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	enumerable: true
 }) : target, mod));
 //#endregion
+const require_destination = require("./destination.cjs");
+const require_contract = require("./contract-BU33R4oL.cjs");
 let _embedpdf_core = require("@embedpdf/core");
+let _embedpdf_plugin_actions_contract = require("@embedpdf/plugin-actions/contract");
+let _embedpdf_plugin_actions_contract_host = require("@embedpdf/plugin-actions/contract/host");
 let _embedpdf_core_stage = require("@embedpdf/core-stage");
 _embedpdf_core_stage = __toESM(_embedpdf_core_stage, 1);
 let _embedpdf_core_geometry = require("@embedpdf/core-geometry");
@@ -854,7 +858,16 @@ function createStageCapability(ctx, config = {}) {
 		if (isFitAll()) goToTarget(ctx.getState().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) => {
+		markCause("programmatic");
 		cancelAnim();
 		const doc = ctx.document();
 		if (!doc || doc.pageCount === 0) return;
@@ -1232,11 +1245,13 @@ function createStageCapability(ctx, config = {}) {
 			});
 		},
 		setCamera: (c) => {
+			markCause("user");
 			cancelAnim();
 			setCam(c);
 			syncCursorFromCamera();
 		},
 		panBy: (dx, dy) => {
+			markCause("user");
 			cancelAnim();
 			if (gestureDepth > 0 && gestureElastic) {
 				gestureRaw = _embedpdf_core_stage.panByScreen(gestureRaw ?? unrubberize(cam()), dx, dy);
@@ -1245,6 +1260,7 @@ function createStageCapability(ctx, config = {}) {
 			syncCursorFromCamera();
 		},
 		scrollTo: (opts) => {
+			markCause("user");
 			cancelAnim();
 			if (!buildScene().itemCount) return;
 			const next = _embedpdf_core_stage.cameraFromScroll(cam(), stayBounds(), vp(), pad(), opts);
@@ -1347,6 +1363,7 @@ function createStageCapability(ctx, config = {}) {
 		},
 		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));
@@ -1488,22 +1505,51 @@ function createStageCapability(ctx, config = {}) {
 //#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.
+* Stage lens effects.
 *
-* 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.
+* 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.
 *
-* 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).
+* 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.
 */
-function registerStageEffects(ctx, token) {
+function registerStageEffects(ctx, token, feedActions = false) {
 	ctx.watch(() => ctx.document()?.revision ?? 0, () => ctx.get(token).refit());
+	if (!feedActions) return;
+	const actions = ctx.tryGet(_embedpdf_plugin_actions_contract_host.ActionsToken);
+	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
@@ -1523,6 +1569,7 @@ const initialStageState = (config) => {
 		},
 		dpr: 1,
 		cursor: 0,
+		motionCause: "user",
 		activeRules: [],
 		...DEFAULT_SETTINGS,
 		...overrides
@@ -1569,6 +1616,10 @@ const stageReducer = (state, a) => {
 			...state,
 			cursor: a.cursor
 		};
+		case "MOTION_CAUSE": return {
+			...state,
+			motionCause: a.cause
+		};
 		case "PATCH": return applyPatch(state, a.patch);
 		case "RESPONSIVE": return {
 			...state,
@@ -1578,9 +1629,6 @@ const stageReducer = (state, a) => {
 	}
 };
 //#endregion
-//#region src/types.ts
-const StageToken = (0, _embedpdf_core.createCapabilityToken)("stage");
-//#endregion
 //#region src/stage.plugin.ts
 /**
 * Wires the parts into a kernel plugin. This file is the "manifest": it says what
@@ -1588,159 +1636,70 @@ const StageToken = (0, _embedpdf_core.createCapabilityToken)("stage");
 * sibling files.
 */
 const stagePlugin = (options = {}) => {
-	const { id = "stage", token = StageToken, ...config } = options;
+	const { id = "stage", token = require_contract.StageToken, ...config } = options;
 	return (0, _embedpdf_core.definePlugin)({
 		id,
 		token,
 		scope: "document",
+		optional: [_embedpdf_plugin_actions_contract.ActionsToken],
 		initialState: () => initialStageState(config),
 		reduce: stageReducer,
 		capability: (ctx) => createStageCapability(ctx, config),
-		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 = (0, _embedpdf_core_geometry.pageGeometry)({
-		crop: layout.boxes.crop,
-		rotation: layout.rotation,
-		userUnit: layout.userUnit
-	}, 1);
-	const crop = layout.boxes.crop;
-	const toContent = (x, y) => (0, _embedpdf_core_geometry.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"
+		effects: (ctx) => registerStageEffects(ctx, token, id === "stage"),
+		init: (ctx) => {
+			if (id !== "stage") return;
+			const actions = ctx.tryGet(_embedpdf_plugin_actions_contract_host.ActionsToken);
+			if (!actions) return;
+			ctx.cleanup(actions.registerExecutor("goto", (node) => {
+				if (node.type !== "goto") return {
+					status: "inert",
+					reason: "not a goto node"
 				};
-			}
-			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" }
+				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"
 				};
-			}
-			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" }
+				const { pageIndex, options: reveal } = require_destination.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"
 				};
-			}
-			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" }
+				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}'`
+					};
+				}
+			}));
 		}
-	})();
-	return {
-		pageIndex: layout.index,
-		options
-	};
-}
+	});
+};
 //#endregion
 //#region src/scroll-handler.ts
 /**
@@ -1784,7 +1743,7 @@ function createScrollHandler(stage, interaction, options = {}) {
 //#endregion
 exports.DEFAULT_RESPONSIVE = DEFAULT_RESPONSIVE;
 exports.DEFAULT_SETTINGS = DEFAULT_SETTINGS;
-exports.StageToken = StageToken;
+exports.StageToken = require_contract.StageToken;
 Object.defineProperty(exports, "ZoomMode", {
 	enumerable: true,
 	get: function() {
@@ -1793,7 +1752,7 @@ Object.defineProperty(exports, "ZoomMode", {
 });
 exports.boxOf = boxOf;
 exports.createScrollHandler = createScrollHandler;
-exports.destinationToReveal = destinationToReveal;
+exports.destinationToReveal = require_destination.destinationToReveal;
 exports.matchesQuery = matchesQuery;
 exports.resolveResponsive = resolveResponsive;
 exports.settingsEqual = settingsEqual;