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

package/dist/contract-B8bEMeH8.d.ts

@@ -0,0 +1,92 @@
+import { PageObjectNumber } from "@embedpdf/core";
+import { ActionDispatchResult } from "@embedpdf/plugin-actions/contract";
+import { LinkNavItem } from "@embedpdf/plugin-annotation/contract";
+import { AnnotationRef, PdfActionTree, PdfDestination, PdfLinkTarget } from "@embedpdf/engine-core/runtime";
+//#region src/types.d.ts
+/**
+ * What one activation did. `revealed` = the stage moved the camera;
+ * `destination` = no stage plugin — the embedder gets the explicit
+ * destination to handle; `uri` = opening is the FRAMEWORK layer's job (the
+ * plugin is DOM-free); `named` = a viewer verb (NextPage…) reported until
+ * stage verbs land; `reported` = read-only/executable-shaped targets
+ * (javascript / goto-remote / launch / unsupported) — surfaced, NEVER
+ * executed here (javascript belongs to the scripting orchestrator).
+ */
+type LinkActivation = {
+  outcome: 'revealed';
+} | {
+  outcome: 'destination';
+  destination: PdfDestination;
+} | {
+  outcome: 'uri';
+  uri: string;
+} | {
+  outcome: 'named';
+  name: string;
+} | {
+  outcome: 'reported';
+  target: PdfLinkTarget;
+} |
+/** The action engine took the activation (full payload tree, mixed /Next
+ *  chains included). `dispatch` is the in-flight result; the framework
+ *  opener must do NOTHING for this outcome — the actions UI adapter owns
+ *  any URI open (the no-double-open rule). */
+{
+  outcome: 'dispatched';
+  dispatch: Promise<ActionDispatchResult>;
+} | {
+  outcome: 'none';
+};
+/** Optional activation context: the payload-carrying /A tree (and its
+ *  annotation identity) from the LinkNavItem, enabling action-engine
+ *  delegation. Without it — or without the actions plugin — activation
+ *  follows the classic root-projection path. */
+interface LinkActivateContext {
+  activate?: PdfActionTree;
+  ref?: AnnotationRef;
+  pon?: PageObjectNumber;
+}
+interface LinkActivateEvent {
+  target: PdfLinkTarget;
+  activation: LinkActivation;
+}
+interface LinkPluginConfig {
+  /** Every activation (navigations AND reported targets) — analytics /
+   *  custom handling. Called after the built-in handling ran. */
+  onActivate?: (event: LinkActivateEvent) => void;
+}
+/**
+ * The navigation plane of link annotations. Data comes from ONE of two
+ * sources, picked at init: the annotation plugin's folded model when that
+ * plugin is present (zero extra engine reads — it already lists every
+ * page), or the plugin's own engine reads in viewer-only deployments.
+ */
+interface LinkCapability {
+  /** The clickable link areas of a page (content space, y-down). */
+  linksOn(pon: PageObjectNumber): LinkNavItem[];
+  /** Lazy-load a page's links (no-op when the annotation plugin owns the data). */
+  ensurePage(pon: PageObjectNumber): void;
+  /** Whether the navigation plane currently owns links: the active tool
+   *  enables `link-nav` (pointer/pan/form-fill by default). While false —
+   *  the link tool or any authoring tool is active — the annotation plane
+   *  owns them and the LinkLayer stands down. */
+  engaged(): boolean;
+  /** THE one activation entry point (framework layers call it on click). */
+  activate(target: PdfLinkTarget, context?: LinkActivateContext): LinkActivation;
+}
+/** Engine-backed page cache (viewer-only deployments). */
+interface LinkState {
+  pages: Record<number, LinkNavItem[]>;
+}
+type LinkAction = {
+  type: 'SET_PAGE';
+  pon: number;
+  items: LinkNavItem[];
+} | {
+  type: 'DROP_PAGE';
+  pon: number;
+};
+declare const LinkToken: import("@embedpdf/core").CapabilityToken<LinkCapability>;
+//#endregion
+export { LinkCapability as a, LinkState as c, PdfLinkTarget as d, LinkActivation as i, LinkToken as l, LinkActivateContext as n, LinkNavItem as o, LinkActivateEvent as r, LinkPluginConfig as s, LinkAction as t, PdfDestination as u };
+//# sourceMappingURL=contract-B8bEMeH8.d.ts.map

package/dist/contract-DGKEPl11.cjs

@@ -0,0 +1,11 @@
+//#region src/types.ts
+const LinkToken = (0, require("@embedpdf/core").createCapabilityToken)("link");
+//#endregion
+Object.defineProperty(exports, "LinkToken", {
+	enumerable: true,
+	get: function() {
+		return LinkToken;
+	}
+});
+
+//# sourceMappingURL=contract-DGKEPl11.cjs.map

package/dist/contract-DGKEPl11.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-DGKEPl11.cjs","names":[],"sources":["../src/types.ts"],"sourcesContent":["import { createCapabilityToken, type PageObjectNumber } from '@embedpdf/core';\nimport type {\n  AnnotationRef,\n  PdfActionTree,\n  PdfDestination,\n  PdfLinkTarget,\n} from '@embedpdf/engine-core/runtime';\nimport type { ActionDispatchResult } from '@embedpdf/plugin-actions/contract';\nimport type { LinkNavItem } from '@embedpdf/plugin-annotation/contract';\n\nexport type { LinkNavItem };\n// The wire target vocabulary, re-exported so app code building link editors\n// needs only this package (the annotation-props precedent).\nexport type { PdfDestination, PdfLinkTarget };\n\n/**\n * What one activation did. `revealed` = the stage moved the camera;\n * `destination` = no stage plugin — the embedder gets the explicit\n * destination to handle; `uri` = opening is the FRAMEWORK layer's job (the\n * plugin is DOM-free); `named` = a viewer verb (NextPage…) reported until\n * stage verbs land; `reported` = read-only/executable-shaped targets\n * (javascript / goto-remote / launch / unsupported) — surfaced, NEVER\n * executed here (javascript belongs to the scripting orchestrator).\n */\nexport type LinkActivation =\n  | { outcome: 'revealed' }\n  | { outcome: 'destination'; destination: PdfDestination }\n  | { outcome: 'uri'; uri: string }\n  | { outcome: 'named'; name: string }\n  | { outcome: 'reported'; target: PdfLinkTarget }\n  /** The action engine took the activation (full payload tree, mixed /Next\n   *  chains included). `dispatch` is the in-flight result; the framework\n   *  opener must do NOTHING for this outcome — the actions UI adapter owns\n   *  any URI open (the no-double-open rule). */\n  | { outcome: 'dispatched'; dispatch: Promise<ActionDispatchResult> }\n  | { outcome: 'none' };\n\n/** Optional activation context: the payload-carrying /A tree (and its\n *  annotation identity) from the LinkNavItem, enabling action-engine\n *  delegation. Without it — or without the actions plugin — activation\n *  follows the classic root-projection path. */\nexport interface LinkActivateContext {\n  activate?: PdfActionTree;\n  ref?: AnnotationRef;\n  pon?: PageObjectNumber;\n}\n\nexport interface LinkActivateEvent {\n  target: PdfLinkTarget;\n  activation: LinkActivation;\n}\n\nexport interface LinkPluginConfig {\n  /** Every activation (navigations AND reported targets) — analytics /\n   *  custom handling. Called after the built-in handling ran. */\n  onActivate?: (event: LinkActivateEvent) => void;\n}\n\n/**\n * The navigation plane of link annotations. Data comes from ONE of two\n * sources, picked at init: the annotation plugin's folded model when that\n * plugin is present (zero extra engine reads — it already lists every\n * page), or the plugin's own engine reads in viewer-only deployments.\n */\nexport interface LinkCapability {\n  /** The clickable link areas of a page (content space, y-down). */\n  linksOn(pon: PageObjectNumber): LinkNavItem[];\n  /** Lazy-load a page's links (no-op when the annotation plugin owns the data). */\n  ensurePage(pon: PageObjectNumber): void;\n  /** Whether the navigation plane currently owns links: the active tool\n   *  enables `link-nav` (pointer/pan/form-fill by default). While false —\n   *  the link tool or any authoring tool is active — the annotation plane\n   *  owns them and the LinkLayer stands down. */\n  engaged(): boolean;\n  /** THE one activation entry point (framework layers call it on click). */\n  activate(target: PdfLinkTarget, context?: LinkActivateContext): LinkActivation;\n}\n\n/** Engine-backed page cache (viewer-only deployments). */\nexport interface LinkState {\n  pages: Record<number, LinkNavItem[]>;\n}\n\nexport type LinkAction =\n  | { type: 'SET_PAGE'; pon: number; items: LinkNavItem[] }\n  | { type: 'DROP_PAGE'; pon: number };\n\nexport const LinkToken = createCapabilityToken<LinkCapability>('link');\n"],"mappings":";AAuFA,MAAa,aAAA,2BAAA,CAAA,CAAA,sBAAA,CAAkD,MAAM"}

package/dist/contract-DO3vDsAV.d.cts

@@ -0,0 +1,92 @@
+import { PageObjectNumber } from "@embedpdf/core";
+import { AnnotationRef, PdfActionTree, PdfDestination, PdfLinkTarget } from "@embedpdf/engine-core/runtime";
+import { ActionDispatchResult } from "@embedpdf/plugin-actions/contract";
+import { LinkNavItem } from "@embedpdf/plugin-annotation/contract";
+//#region src/types.d.ts
+/**
+ * What one activation did. `revealed` = the stage moved the camera;
+ * `destination` = no stage plugin — the embedder gets the explicit
+ * destination to handle; `uri` = opening is the FRAMEWORK layer's job (the
+ * plugin is DOM-free); `named` = a viewer verb (NextPage…) reported until
+ * stage verbs land; `reported` = read-only/executable-shaped targets
+ * (javascript / goto-remote / launch / unsupported) — surfaced, NEVER
+ * executed here (javascript belongs to the scripting orchestrator).
+ */
+type LinkActivation = {
+  outcome: 'revealed';
+} | {
+  outcome: 'destination';
+  destination: PdfDestination;
+} | {
+  outcome: 'uri';
+  uri: string;
+} | {
+  outcome: 'named';
+  name: string;
+} | {
+  outcome: 'reported';
+  target: PdfLinkTarget;
+} |
+/** The action engine took the activation (full payload tree, mixed /Next
+ *  chains included). `dispatch` is the in-flight result; the framework
+ *  opener must do NOTHING for this outcome — the actions UI adapter owns
+ *  any URI open (the no-double-open rule). */
+{
+  outcome: 'dispatched';
+  dispatch: Promise<ActionDispatchResult>;
+} | {
+  outcome: 'none';
+};
+/** Optional activation context: the payload-carrying /A tree (and its
+ *  annotation identity) from the LinkNavItem, enabling action-engine
+ *  delegation. Without it — or without the actions plugin — activation
+ *  follows the classic root-projection path. */
+interface LinkActivateContext {
+  activate?: PdfActionTree;
+  ref?: AnnotationRef;
+  pon?: PageObjectNumber;
+}
+interface LinkActivateEvent {
+  target: PdfLinkTarget;
+  activation: LinkActivation;
+}
+interface LinkPluginConfig {
+  /** Every activation (navigations AND reported targets) — analytics /
+   *  custom handling. Called after the built-in handling ran. */
+  onActivate?: (event: LinkActivateEvent) => void;
+}
+/**
+ * The navigation plane of link annotations. Data comes from ONE of two
+ * sources, picked at init: the annotation plugin's folded model when that
+ * plugin is present (zero extra engine reads — it already lists every
+ * page), or the plugin's own engine reads in viewer-only deployments.
+ */
+interface LinkCapability {
+  /** The clickable link areas of a page (content space, y-down). */
+  linksOn(pon: PageObjectNumber): LinkNavItem[];
+  /** Lazy-load a page's links (no-op when the annotation plugin owns the data). */
+  ensurePage(pon: PageObjectNumber): void;
+  /** Whether the navigation plane currently owns links: the active tool
+   *  enables `link-nav` (pointer/pan/form-fill by default). While false —
+   *  the link tool or any authoring tool is active — the annotation plane
+   *  owns them and the LinkLayer stands down. */
+  engaged(): boolean;
+  /** THE one activation entry point (framework layers call it on click). */
+  activate(target: PdfLinkTarget, context?: LinkActivateContext): LinkActivation;
+}
+/** Engine-backed page cache (viewer-only deployments). */
+interface LinkState {
+  pages: Record<number, LinkNavItem[]>;
+}
+type LinkAction = {
+  type: 'SET_PAGE';
+  pon: number;
+  items: LinkNavItem[];
+} | {
+  type: 'DROP_PAGE';
+  pon: number;
+};
+declare const LinkToken: import("@embedpdf/core").CapabilityToken<LinkCapability>;
+//#endregion
+export { LinkCapability as a, LinkState as c, PdfLinkTarget as d, LinkActivation as i, LinkToken as l, LinkActivateContext as n, LinkNavItem as o, LinkActivateEvent as r, LinkPluginConfig as s, LinkAction as t, PdfDestination as u };
+//# sourceMappingURL=contract-DO3vDsAV.d.cts.map

package/dist/contract-HRggERzU.js

@@ -0,0 +1,7 @@
+import { createCapabilityToken } from "@embedpdf/core";
+//#region src/types.ts
+const LinkToken = createCapabilityToken("link");
+//#endregion
+export { LinkToken as t };
+
+//# sourceMappingURL=contract-HRggERzU.js.map

package/dist/contract-HRggERzU.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-HRggERzU.js","names":[],"sources":["../src/types.ts"],"sourcesContent":["import { createCapabilityToken, type PageObjectNumber } from '@embedpdf/core';\nimport type {\n  AnnotationRef,\n  PdfActionTree,\n  PdfDestination,\n  PdfLinkTarget,\n} from '@embedpdf/engine-core/runtime';\nimport type { ActionDispatchResult } from '@embedpdf/plugin-actions/contract';\nimport type { LinkNavItem } from '@embedpdf/plugin-annotation/contract';\n\nexport type { LinkNavItem };\n// The wire target vocabulary, re-exported so app code building link editors\n// needs only this package (the annotation-props precedent).\nexport type { PdfDestination, PdfLinkTarget };\n\n/**\n * What one activation did. `revealed` = the stage moved the camera;\n * `destination` = no stage plugin — the embedder gets the explicit\n * destination to handle; `uri` = opening is the FRAMEWORK layer's job (the\n * plugin is DOM-free); `named` = a viewer verb (NextPage…) reported until\n * stage verbs land; `reported` = read-only/executable-shaped targets\n * (javascript / goto-remote / launch / unsupported) — surfaced, NEVER\n * executed here (javascript belongs to the scripting orchestrator).\n */\nexport type LinkActivation =\n  | { outcome: 'revealed' }\n  | { outcome: 'destination'; destination: PdfDestination }\n  | { outcome: 'uri'; uri: string }\n  | { outcome: 'named'; name: string }\n  | { outcome: 'reported'; target: PdfLinkTarget }\n  /** The action engine took the activation (full payload tree, mixed /Next\n   *  chains included). `dispatch` is the in-flight result; the framework\n   *  opener must do NOTHING for this outcome — the actions UI adapter owns\n   *  any URI open (the no-double-open rule). */\n  | { outcome: 'dispatched'; dispatch: Promise<ActionDispatchResult> }\n  | { outcome: 'none' };\n\n/** Optional activation context: the payload-carrying /A tree (and its\n *  annotation identity) from the LinkNavItem, enabling action-engine\n *  delegation. Without it — or without the actions plugin — activation\n *  follows the classic root-projection path. */\nexport interface LinkActivateContext {\n  activate?: PdfActionTree;\n  ref?: AnnotationRef;\n  pon?: PageObjectNumber;\n}\n\nexport interface LinkActivateEvent {\n  target: PdfLinkTarget;\n  activation: LinkActivation;\n}\n\nexport interface LinkPluginConfig {\n  /** Every activation (navigations AND reported targets) — analytics /\n   *  custom handling. Called after the built-in handling ran. */\n  onActivate?: (event: LinkActivateEvent) => void;\n}\n\n/**\n * The navigation plane of link annotations. Data comes from ONE of two\n * sources, picked at init: the annotation plugin's folded model when that\n * plugin is present (zero extra engine reads — it already lists every\n * page), or the plugin's own engine reads in viewer-only deployments.\n */\nexport interface LinkCapability {\n  /** The clickable link areas of a page (content space, y-down). */\n  linksOn(pon: PageObjectNumber): LinkNavItem[];\n  /** Lazy-load a page's links (no-op when the annotation plugin owns the data). */\n  ensurePage(pon: PageObjectNumber): void;\n  /** Whether the navigation plane currently owns links: the active tool\n   *  enables `link-nav` (pointer/pan/form-fill by default). While false —\n   *  the link tool or any authoring tool is active — the annotation plane\n   *  owns them and the LinkLayer stands down. */\n  engaged(): boolean;\n  /** THE one activation entry point (framework layers call it on click). */\n  activate(target: PdfLinkTarget, context?: LinkActivateContext): LinkActivation;\n}\n\n/** Engine-backed page cache (viewer-only deployments). */\nexport interface LinkState {\n  pages: Record<number, LinkNavItem[]>;\n}\n\nexport type LinkAction =\n  | { type: 'SET_PAGE'; pon: number; items: LinkNavItem[] }\n  | { type: 'DROP_PAGE'; pon: number };\n\nexport const LinkToken = createCapabilityToken<LinkCapability>('link');\n"],"mappings":";;AAuFA,MAAa,YAAY,sBAAsC,MAAM"}

package/dist/contract.cjs

@@ -0,0 +1,3 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_contract = require("./contract-DGKEPl11.cjs");
+exports.LinkToken = require_contract.LinkToken;

package/dist/contract.d.cts

@@ -0,0 +1,2 @@
+import { a as LinkCapability, c as LinkState, d as PdfLinkTarget, i as LinkActivation, l as LinkToken, n as LinkActivateContext, o as LinkNavItem, r as LinkActivateEvent, s as LinkPluginConfig, u as PdfDestination } from "./contract-DO3vDsAV.cjs";
+export { type LinkActivateContext, type LinkActivateEvent, type LinkActivation, type LinkCapability, type LinkNavItem, type LinkPluginConfig, type LinkState, LinkToken, type PdfDestination, type PdfLinkTarget };

package/dist/contract.d.ts

@@ -0,0 +1,2 @@
+import { a as LinkCapability, c as LinkState, d as PdfLinkTarget, i as LinkActivation, l as LinkToken, n as LinkActivateContext, o as LinkNavItem, r as LinkActivateEvent, s as LinkPluginConfig, u as PdfDestination } from "./contract-B8bEMeH8.js";
+export { type LinkActivateContext, type LinkActivateEvent, type LinkActivation, type LinkCapability, type LinkNavItem, type LinkPluginConfig, type LinkState, LinkToken, type PdfDestination, type PdfLinkTarget };

package/dist/contract.js

@@ -0,0 +1,2 @@
+import { t as LinkToken } from "./contract-HRggERzU.js";
+export { LinkToken };

package/dist/index.cjs

@@ -1,9 +1,12 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_contract = require("./contract-DGKEPl11.cjs");
 let _embedpdf_core = require("@embedpdf/core");
-let _embedpdf_plugin_interaction = require("@embedpdf/plugin-interaction");
-let _embedpdf_plugin_stage = require("@embedpdf/plugin-stage");
-let _embedpdf_plugin_annotation = require("@embedpdf/plugin-annotation");
-let _embedpdf_plugin_annotation_internal = require("@embedpdf/plugin-annotation/internal");
+let _embedpdf_plugin_actions_contract = require("@embedpdf/plugin-actions/contract");
+let _embedpdf_plugin_annotation_contract = require("@embedpdf/plugin-annotation/contract");
+let _embedpdf_plugin_annotation_contract_host = require("@embedpdf/plugin-annotation/contract/host");
+let _embedpdf_plugin_interaction_contract = require("@embedpdf/plugin-interaction/contract");
+let _embedpdf_plugin_stage_contract = require("@embedpdf/plugin-stage/contract");
+let _embedpdf_plugin_stage_destination = require("@embedpdf/plugin-stage/destination");
 let _embedpdf_core_annotation = require("@embedpdf/core-annotation");
 //#region src/source.ts
 function loadLinksPage(io, pon) {
@@ -19,6 +22,12 @@ function loadLinksPage(io, pon) {
 				id: dto.ref.kind === "objectNumber" ? `obj:${dto.ref.annotObjectNumber}` : `idx:${pon}:${dto.index}`,
 				rect: (0, _embedpdf_core_annotation.pdfToContentRect)(dto.rect, crop),
 				target: dto.target,
+				...dto.actions?.activate ? { activate: dto.actions.activate } : {},
+				...dto.actions?.cursorEnter?.root || dto.actions?.cursorExit?.root ? { hoverEvents: {
+					enter: Boolean(dto.actions?.cursorEnter?.root),
+					exit: Boolean(dto.actions?.cursorExit?.root)
+				} } : {},
+				ref: dto.ref,
 				attached: dto.replyType === "group" && dto.inReplyTo != null
 			});
 		}
@@ -40,18 +49,31 @@ const EMPTY = [];
 * engine-backed page cache (see source.ts).
 */
 function createLinkCapability(ctx, config = {}) {
-	const anno = () => ctx.tryGet(_embedpdf_plugin_annotation_internal.AnnotationToken);
-	const activate = (target) => {
+	const anno = () => ctx.tryGet(_embedpdf_plugin_annotation_contract_host.AnnotationToken);
+	const activate = (target, context) => {
 		const activation = (() => {
+			const actions = ctx.tryGet(_embedpdf_plugin_actions_contract.ActionsToken);
+			if (actions && context?.activate) return {
+				outcome: "dispatched",
+				dispatch: actions.execute(context.activate, {
+					origin: "user",
+					source: {
+						kind: "link",
+						annotation: context.ref,
+						pon: context.pon
+					},
+					event: { scope: "activate" }
+				})
+			};
 			switch (target.kind) {
 				case "goto": {
-					const stage = ctx.tryGet(_embedpdf_plugin_stage.StageToken);
+					const stage = ctx.tryGet(_embedpdf_plugin_stage_contract.StageToken);
 					const layout = ctx.document()?.pages.find((p) => p.pageObjectNumber === target.destination.pageObjectNumber);
 					if (!stage || !layout) return {
 						outcome: "destination",
 						destination: target.destination
 					};
-					const { pageIndex, options } = (0, _embedpdf_plugin_stage.destinationToReveal)(target.destination, layout);
+					const { pageIndex, options } = (0, _embedpdf_plugin_stage_destination.destinationToReveal)(target.destination, layout);
 					stage.reveal(pageIndex, {
 						...options,
 						behavior: "smooth"
@@ -92,7 +114,7 @@ function createLinkCapability(ctx, config = {}) {
 			}
 			if (!(pon in ctx.getState().pages)) loadLinksPage(ctx, pon);
 		},
-		engaged: () => ctx.tryGet(_embedpdf_plugin_interaction.InteractionToken)?.activeTool()?.enables.has("link-nav") ?? false,
+		engaged: () => ctx.tryGet(_embedpdf_plugin_interaction_contract.InteractionToken)?.activeTool()?.enables.has("link-nav") ?? false,
 		activate
 	};
 }
@@ -109,7 +131,7 @@ function registerLinkEffects(ctx) {
 	const doc = ctx.doc;
 	if (!doc) return;
 	const refetch = (pon) => {
-		if (ctx.tryGet(_embedpdf_plugin_annotation_internal.AnnotationToken)) return;
+		if (ctx.tryGet(_embedpdf_plugin_annotation_contract_host.AnnotationToken)) return;
 		if (pon in ctx.getState().pages) loadLinksPage(ctx, pon);
 	};
 	const unsubscribe = doc.events.subscribe((event) => {
@@ -157,9 +179,6 @@ function linkReducer(state, a) {
 	}
 }
 //#endregion
-//#region src/types.ts
-const LinkToken = (0, _embedpdf_core.createCapabilityToken)("link");
-//#endregion
 //#region src/link.plugin.ts
 /**
 * The link plugin: the NAVIGATION plane. Document-scoped; requires only the
@@ -172,17 +191,21 @@ const LinkToken = (0, _embedpdf_core.createCapabilityToken)("link");
 */
 const linkPlugin = (config) => (0, _embedpdf_core.definePlugin)({
 	id: "link",
-	token: LinkToken,
+	token: require_contract.LinkToken,
 	scope: "document",
-	requires: [_embedpdf_plugin_interaction.InteractionToken],
-	optional: [_embedpdf_plugin_stage.StageToken, _embedpdf_plugin_annotation.AnnotationToken],
+	requires: [_embedpdf_plugin_interaction_contract.InteractionToken],
+	optional: [
+		_embedpdf_plugin_stage_contract.StageToken,
+		_embedpdf_plugin_annotation_contract.AnnotationToken,
+		_embedpdf_plugin_actions_contract.ActionsToken
+	],
 	initialState: initialLinkState,
 	reduce: linkReducer,
 	capability: (ctx) => createLinkCapability(ctx, config),
 	effects: registerLinkEffects,
 	init: (ctx) => {
-		const interaction = ctx.get(_embedpdf_plugin_interaction.InteractionToken);
-		const annotation = ctx.tryGet(_embedpdf_plugin_annotation_internal.AnnotationToken);
+		const interaction = ctx.get(_embedpdf_plugin_interaction_contract.InteractionToken);
+		const annotation = ctx.tryGet(_embedpdf_plugin_annotation_contract_host.AnnotationToken);
 		if (annotation) annotation.registerBehavior({
 			id: "link-nav",
 			matches: (a) => a.subtype === "link",
@@ -191,7 +214,7 @@ const linkPlugin = (config) => (0, _embedpdf_core.definePlugin)({
 	}
 });
 //#endregion
-exports.LinkToken = LinkToken;
+exports.LinkToken = require_contract.LinkToken;
 exports.linkPlugin = linkPlugin;
 
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":["AnnotationHostToken","StageToken","InteractionToken","AnnotationHostToken","InteractionToken","StageToken","AnnotationToken","AnnotationHostToken"],"sources":["../src/source.ts","../src/capability.ts","../src/effects.ts","../src/reducer.ts","../src/types.ts","../src/link.plugin.ts"],"sourcesContent":["import type { DocumentHandle, PageLayout } from '@embedpdf/core';\nimport { pdfToContentRect } from '@embedpdf/core-annotation';\nimport type { LinkAction, LinkNavItem } from './types';\n\n/**\n * The ENGINE-BACKED link source, for viewer-only deployments (no annotation\n * plugin): read a page's annotation list and keep just the navigable links —\n * standalone AND attached children alike (both are raw link DTOs here).\n * Shared by the capability's lazy `ensurePage` and the effects module's\n * event-driven refetch; both PluginContext and EffectContext satisfy the\n * structural `io` slice.\n */\nexport interface LinkSourceIO {\n  doc: DocumentHandle | null;\n  document(): { pages: readonly PageLayout[] } | null;\n  dispatch(action: LinkAction): void;\n}\n\nexport function loadLinksPage(io: LinkSourceIO, pon: number): void {\n  const doc = io.doc;\n  const crop = io.document()?.pages.find((p) => p.pageObjectNumber === pon)?.boxes.crop;\n  if (!doc || !crop) return;\n  doc\n    .page(pon)\n    .annotations.list()\n    .then(\n      (snap) => {\n        const items: LinkNavItem[] = [];\n        for (const dto of snap.annotations) {\n          if (dto.subtype !== 'link' || dto.target == null) continue;\n          if (dto.flags.hidden || dto.flags.noView) continue;\n          items.push({\n            id:\n              dto.ref.kind === 'objectNumber'\n                ? `obj:${dto.ref.annotObjectNumber}`\n                : `idx:${pon}:${dto.index}`,\n            rect: pdfToContentRect(dto.rect, crop),\n            target: dto.target,\n            // A `/RT /Group` child riding another annotation — labeled so the\n            // nav layer can defer to editing (moot in viewer-only deployments,\n            // but the item contract stays truthful either way).\n            attached: dto.replyType === 'group' && dto.inReplyTo != null,\n          });\n        }\n        io.dispatch({ type: 'SET_PAGE', pon, items });\n      },\n      () => {},\n    );\n}\n","import type { PluginContext } from '@embedpdf/core';\nimport type { PdfLinkTarget } from '@embedpdf/engine-core/runtime';\nimport { InteractionToken } from '@embedpdf/plugin-interaction';\nimport { destinationToReveal, StageToken } from '@embedpdf/plugin-stage';\n// The host lens (linkItemsOn) — same runtime token as the public one.\nimport { AnnotationToken as AnnotationHostToken } from '@embedpdf/plugin-annotation/internal';\nimport { loadLinksPage } from './source';\nimport type {\n  LinkAction,\n  LinkActivation,\n  LinkCapability,\n  LinkNavItem,\n  LinkPluginConfig,\n  LinkState,\n} from './types';\n\nconst EMPTY: LinkNavItem[] = [];\n\n/**\n * The navigation plane's surface. Data source is decided PER CALL (lazily,\n * so plugin registration order can't matter): the annotation plugin's\n * folded model when present — its `linkItemsOn` lens is memoized by model\n * identity and already excludes hidden links — else this plugin's own\n * engine-backed page cache (see source.ts).\n */\nexport function createLinkCapability(\n  ctx: PluginContext<LinkState, LinkAction>,\n  config: LinkPluginConfig = {},\n): LinkCapability {\n  const anno = () => ctx.tryGet(AnnotationHostToken);\n\n  const activate = (target: PdfLinkTarget): LinkActivation => {\n    const activation = ((): LinkActivation => {\n      switch (target.kind) {\n        case 'goto': {\n          const stage = ctx.tryGet(StageToken);\n          const layout = ctx\n            .document()\n            ?.pages.find((p) => p.pageObjectNumber === target.destination.pageObjectNumber);\n          if (!stage || !layout) {\n            // No camera to drive — hand the embedder the explicit destination.\n            return { outcome: 'destination', destination: target.destination };\n          }\n          const { pageIndex, options } = destinationToReveal(target.destination, layout);\n          stage.reveal(pageIndex, { ...options, behavior: 'smooth' });\n          return { outcome: 'revealed' };\n        }\n        case 'uri':\n          // Opening is the FRAMEWORK layer's job (a real <a href> after\n          // sanitizing) — this plugin never touches the DOM.\n          return { outcome: 'uri', uri: target.uri };\n        case 'named':\n          return { outcome: 'named', name: target.name };\n        default:\n          // javascript / goto-remote / launch / unsupported: reported, never\n          // executed here. JavaScript activation belongs to the scripting\n          // orchestrator once it lands — the chain already rides the\n          // annotation's base `actions`.\n          return { outcome: 'reported', target };\n      }\n    })();\n    config.onActivate?.({ target, activation });\n    return activation;\n  };\n\n  return {\n    linksOn: (pon) => {\n      const host = anno();\n      if (host) return host.linkItemsOn(pon);\n      return ctx.getState().pages[pon] ?? EMPTY;\n    },\n    ensurePage: (pon) => {\n      const host = anno();\n      if (host) {\n        host.ensurePage(pon); // the folded model is the source; it lazy-loads\n        return;\n      }\n      if (!(pon in ctx.getState().pages)) loadLinksPage(ctx, pon);\n    },\n    engaged: () => ctx.tryGet(InteractionToken)?.activeTool()?.enables.has('link-nav') ?? false,\n    activate,\n  };\n}\n","import type { DocumentEvent, EffectContext } from '@embedpdf/core';\nimport { AnnotationToken as AnnotationHostToken } from '@embedpdf/plugin-annotation/internal';\nimport { loadLinksPage } from './source';\nimport type { LinkAction, LinkState } from './types';\n\n/**\n * Keeps the ENGINE-BACKED page cache honest in viewer-only deployments:\n * any annotation mutation on a cached page (own or remote — the cache has\n * no other refresh path, unlike the annotation plugin's optimistic model)\n * refetches that page's links. With the annotation plugin present the\n * folded model is the source and this effect never fires a fetch.\n */\nexport function registerLinkEffects(ctx: EffectContext<LinkState, LinkAction>): void {\n  const doc = ctx.doc;\n  if (!doc) return;\n\n  const refetch = (pon: number): void => {\n    if (ctx.tryGet(AnnotationHostToken)) return; // annotation model owns the data\n    if (pon in ctx.getState().pages) loadLinksPage(ctx, pon);\n  };\n\n  const unsubscribe = doc.events.subscribe((event: DocumentEvent) => {\n    switch (event.type) {\n      case 'annotation.created':\n        refetch(event.created.pageObjectNumber);\n        break;\n      case 'annotation.updated':\n        refetch(event.updated.pageObjectNumber);\n        break;\n      case 'annotation.moved':\n        if (event.moved.length) refetch(event.moved[0].pageObjectNumber);\n        break;\n      case 'annotation.deleted':\n        refetch(event.pageObjectNumber);\n        break;\n      default:\n        break;\n    }\n  });\n  ctx.cleanup(unsubscribe);\n}\n","import type { LinkAction, LinkState } from './types';\n\nexport const initialLinkState = (): LinkState => ({ pages: {} });\n\n/** Pure. Engine-backed page cache only — the annotation-backed mode reads the\n *  annotation plugin's model and never touches this state. */\nexport function linkReducer(state: LinkState, a: LinkAction): LinkState {\n  switch (a.type) {\n    case 'SET_PAGE':\n      return { ...state, pages: { ...state.pages, [a.pon]: a.items } };\n    case 'DROP_PAGE': {\n      if (!(a.pon in state.pages)) return state;\n      const pages = { ...state.pages };\n      delete pages[a.pon];\n      return { ...state, pages };\n    }\n  }\n}\n","import { createCapabilityToken, type PageObjectNumber } from '@embedpdf/core';\nimport type { PdfDestination, PdfLinkTarget } from '@embedpdf/engine-core/runtime';\nimport type { LinkNavItem } from '@embedpdf/plugin-annotation';\n\nexport type { LinkNavItem };\n// The wire target vocabulary, re-exported so app code building link editors\n// needs only this package (the annotation-props precedent).\nexport type { PdfDestination, PdfLinkTarget };\n\n/**\n * What one activation did. `revealed` = the stage moved the camera;\n * `destination` = no stage plugin — the embedder gets the explicit\n * destination to handle; `uri` = opening is the FRAMEWORK layer's job (the\n * plugin is DOM-free); `named` = a viewer verb (NextPage…) reported until\n * stage verbs land; `reported` = read-only/executable-shaped targets\n * (javascript / goto-remote / launch / unsupported) — surfaced, NEVER\n * executed here (javascript belongs to the scripting orchestrator).\n */\nexport type LinkActivation =\n  | { outcome: 'revealed' }\n  | { outcome: 'destination'; destination: PdfDestination }\n  | { outcome: 'uri'; uri: string }\n  | { outcome: 'named'; name: string }\n  | { outcome: 'reported'; target: PdfLinkTarget }\n  | { outcome: 'none' };\n\nexport interface LinkActivateEvent {\n  target: PdfLinkTarget;\n  activation: LinkActivation;\n}\n\nexport interface LinkPluginConfig {\n  /** Every activation (navigations AND reported targets) — analytics /\n   *  custom handling. Called after the built-in handling ran. */\n  onActivate?: (event: LinkActivateEvent) => void;\n}\n\n/**\n * The navigation plane of link annotations. Data comes from ONE of two\n * sources, picked at init: the annotation plugin's folded model when that\n * plugin is present (zero extra engine reads — it already lists every\n * page), or the plugin's own engine reads in viewer-only deployments.\n */\nexport interface LinkCapability {\n  /** The clickable link areas of a page (content space, y-down). */\n  linksOn(pon: PageObjectNumber): LinkNavItem[];\n  /** Lazy-load a page's links (no-op when the annotation plugin owns the data). */\n  ensurePage(pon: PageObjectNumber): void;\n  /** Whether the navigation plane currently owns links: the active tool\n   *  enables `link-nav` (pointer/pan/form-fill by default). While false —\n   *  the link tool or any authoring tool is active — the annotation plane\n   *  owns them and the LinkLayer stands down. */\n  engaged(): boolean;\n  /** THE one activation entry point (framework layers call it on click). */\n  activate(target: PdfLinkTarget): LinkActivation;\n}\n\n/** Engine-backed page cache (viewer-only deployments). */\nexport interface LinkState {\n  pages: Record<number, LinkNavItem[]>;\n}\n\nexport type LinkAction =\n  | { type: 'SET_PAGE'; pon: number; items: LinkNavItem[] }\n  | { type: 'DROP_PAGE'; pon: number };\n\nexport const LinkToken = createCapabilityToken<LinkCapability>('link');\n","import { definePlugin } from '@embedpdf/core';\nimport { InteractionToken } from '@embedpdf/plugin-interaction';\nimport { StageToken } from '@embedpdf/plugin-stage';\nimport { AnnotationToken } from '@embedpdf/plugin-annotation';\n// Behavior registration lives on the HOST capability (framework/plugin\n// surface) — same runtime token, wider type. The form plugin's precedent.\nimport { AnnotationToken as AnnotationHostToken } from '@embedpdf/plugin-annotation/internal';\n\nimport { createLinkCapability } from './capability';\nimport { registerLinkEffects } from './effects';\nimport { initialLinkState, linkReducer } from './reducer';\nimport { LinkToken } from './types';\nimport type { LinkAction, LinkCapability, LinkPluginConfig, LinkState } from './types';\n\n/**\n * The link plugin: the NAVIGATION plane. Document-scoped; requires only the\n * interaction hub. Navigation works with no annotation plugin at all —\n * links are read from the engine's link DTOs. When the annotation plugin IS\n * present, its folded model becomes the data source (no double fetch) and a\n * Behavior keeps links navigation-owned while a `link-nav` tool is active\n * (pointer/pan/form-fill by default) — the single-active-tool hub IS the\n * mode switch: grab the link tool and every link becomes an editable rect.\n */\nexport const linkPlugin = (config?: LinkPluginConfig) =>\n  definePlugin<LinkState, LinkAction, LinkCapability>({\n    id: 'link',\n    token: LinkToken,\n    scope: 'document',\n    requires: [InteractionToken],\n    optional: [StageToken, AnnotationToken],\n    initialState: initialLinkState,\n    reduce: linkReducer,\n    capability: (ctx) => createLinkCapability(ctx, config),\n    effects: registerLinkEffects,\n    init: (ctx) => {\n      const interaction = ctx.get(InteractionToken);\n      const annotation = ctx.tryGet(AnnotationHostToken);\n      if (annotation) {\n        annotation.registerBehavior({\n          id: 'link-nav',\n          matches: (a) => a.subtype === 'link',\n          engaged: () => interaction.activeTool()?.enables.has('link-nav') ?? false,\n        });\n      }\n    },\n  });\n"],"mappings":"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"}
+{"version":3,"file":"index.cjs","names":["AnnotationHostToken","ActionsToken","StageToken","InteractionToken","AnnotationHostToken","LinkToken","InteractionToken","StageToken","AnnotationToken","ActionsToken","AnnotationHostToken"],"sources":["../src/source.ts","../src/capability.ts","../src/effects.ts","../src/reducer.ts","../src/link.plugin.ts"],"sourcesContent":["import type { DocumentHandle, PageLayout } from '@embedpdf/core';\nimport { pdfToContentRect } from '@embedpdf/core-annotation';\nimport type { LinkAction, LinkNavItem } from './types';\n\n/**\n * The ENGINE-BACKED link source, for viewer-only deployments (no annotation\n * plugin): read a page's annotation list and keep just the navigable links —\n * standalone AND attached children alike (both are raw link DTOs here).\n * Shared by the capability's lazy `ensurePage` and the effects module's\n * event-driven refetch; both PluginContext and EffectContext satisfy the\n * structural `io` slice.\n */\nexport interface LinkSourceIO {\n  doc: DocumentHandle | null;\n  document(): { pages: readonly PageLayout[] } | null;\n  dispatch(action: LinkAction): void;\n}\n\nexport function loadLinksPage(io: LinkSourceIO, pon: number): void {\n  const doc = io.doc;\n  const crop = io.document()?.pages.find((p) => p.pageObjectNumber === pon)?.boxes.crop;\n  if (!doc || !crop) return;\n  doc\n    .page(pon)\n    .annotations.list()\n    .then(\n      (snap) => {\n        const items: LinkNavItem[] = [];\n        for (const dto of snap.annotations) {\n          if (dto.subtype !== 'link' || dto.target == null) continue;\n          if (dto.flags.hidden || dto.flags.noView) continue;\n          items.push({\n            id:\n              dto.ref.kind === 'objectNumber'\n                ? `obj:${dto.ref.annotObjectNumber}`\n                : `idx:${pon}:${dto.index}`,\n            rect: pdfToContentRect(dto.rect, crop),\n            target: dto.target,\n            ...(dto.actions?.activate ? { activate: dto.actions.activate } : {}),\n            ...(dto.actions?.cursorEnter?.root || dto.actions?.cursorExit?.root\n              ? {\n                  hoverEvents: {\n                    enter: Boolean(dto.actions?.cursorEnter?.root),\n                    exit: Boolean(dto.actions?.cursorExit?.root),\n                  },\n                }\n              : {}),\n            ref: dto.ref,\n            // A `/RT /Group` child riding another annotation — labeled so the\n            // nav layer can defer to editing (moot in viewer-only deployments,\n            // but the item contract stays truthful either way).\n            attached: dto.replyType === 'group' && dto.inReplyTo != null,\n          });\n        }\n        io.dispatch({ type: 'SET_PAGE', pon, items });\n      },\n      () => {},\n    );\n}\n","import type { PluginContext } from '@embedpdf/core';\nimport type { PdfLinkTarget } from '@embedpdf/engine-core/runtime';\nimport { ActionsToken } from '@embedpdf/plugin-actions/contract';\n// The host lens (linkItemsOn) — same runtime token as the public one.\nimport { AnnotationToken as AnnotationHostToken } from '@embedpdf/plugin-annotation/contract/host';\nimport { InteractionToken } from '@embedpdf/plugin-interaction/contract';\nimport { StageToken } from '@embedpdf/plugin-stage/contract';\nimport { destinationToReveal } from '@embedpdf/plugin-stage/destination';\nimport { loadLinksPage } from './source';\nimport type {\n  LinkAction,\n  LinkActivateContext,\n  LinkActivation,\n  LinkCapability,\n  LinkNavItem,\n  LinkPluginConfig,\n  LinkState,\n} from './types';\n\nconst EMPTY: LinkNavItem[] = [];\n\n/**\n * The navigation plane's surface. Data source is decided PER CALL (lazily,\n * so plugin registration order can't matter): the annotation plugin's\n * folded model when present — its `linkItemsOn` lens is memoized by model\n * identity and already excludes hidden links — else this plugin's own\n * engine-backed page cache (see source.ts).\n */\nexport function createLinkCapability(\n  ctx: PluginContext<LinkState, LinkAction>,\n  config: LinkPluginConfig = {},\n): LinkCapability {\n  const anno = () => ctx.tryGet(AnnotationHostToken);\n\n  const activate = (target: PdfLinkTarget, context?: LinkActivateContext): LinkActivation => {\n    const activation = ((): LinkActivation => {\n      // The action engine takes precedence when it is installed and the item\n      // carries its payload tree: named verbs execute, mixed /Next chains\n      // run, and the dispatcher enforces policy + the incomplete-tree law.\n      // Without it, the classic root-projection path below is the fallback.\n      const actions = ctx.tryGet(ActionsToken);\n      if (actions && context?.activate) {\n        const dispatch = actions.execute(context.activate, {\n          origin: 'user',\n          source: { kind: 'link', annotation: context.ref, pon: context.pon },\n          event: { scope: 'activate' },\n        });\n        return { outcome: 'dispatched', dispatch };\n      }\n      switch (target.kind) {\n        case 'goto': {\n          const stage = ctx.tryGet(StageToken);\n          const layout = ctx\n            .document()\n            ?.pages.find((p) => p.pageObjectNumber === target.destination.pageObjectNumber);\n          if (!stage || !layout) {\n            // No camera to drive — hand the embedder the explicit destination.\n            return { outcome: 'destination', destination: target.destination };\n          }\n          const { pageIndex, options } = destinationToReveal(target.destination, layout);\n          stage.reveal(pageIndex, { ...options, behavior: 'smooth' });\n          return { outcome: 'revealed' };\n        }\n        case 'uri':\n          // Opening is the FRAMEWORK layer's job (a real <a href> after\n          // sanitizing) — this plugin never touches the DOM.\n          return { outcome: 'uri', uri: target.uri };\n        case 'named':\n          return { outcome: 'named', name: target.name };\n        default:\n          // javascript / goto-remote / launch / unsupported: reported, never\n          // executed here. JavaScript activation belongs to the scripting\n          // orchestrator once it lands — the chain already rides the\n          // annotation's base `actions`.\n          return { outcome: 'reported', target };\n      }\n    })();\n    config.onActivate?.({ target, activation });\n    return activation;\n  };\n\n  return {\n    linksOn: (pon) => {\n      const host = anno();\n      if (host) return host.linkItemsOn(pon);\n      return ctx.getState().pages[pon] ?? EMPTY;\n    },\n    ensurePage: (pon) => {\n      const host = anno();\n      if (host) {\n        host.ensurePage(pon); // the folded model is the source; it lazy-loads\n        return;\n      }\n      if (!(pon in ctx.getState().pages)) loadLinksPage(ctx, pon);\n    },\n    engaged: () => ctx.tryGet(InteractionToken)?.activeTool()?.enables.has('link-nav') ?? false,\n    activate,\n  };\n}\n","import type { DocumentEvent, EffectContext } from '@embedpdf/core';\nimport { AnnotationToken as AnnotationHostToken } from '@embedpdf/plugin-annotation/contract/host';\nimport { loadLinksPage } from './source';\nimport type { LinkAction, LinkState } from './types';\n\n/**\n * Keeps the ENGINE-BACKED page cache honest in viewer-only deployments:\n * any annotation mutation on a cached page (own or remote — the cache has\n * no other refresh path, unlike the annotation plugin's optimistic model)\n * refetches that page's links. With the annotation plugin present the\n * folded model is the source and this effect never fires a fetch.\n */\nexport function registerLinkEffects(ctx: EffectContext<LinkState, LinkAction>): void {\n  const doc = ctx.doc;\n  if (!doc) return;\n\n  const refetch = (pon: number): void => {\n    if (ctx.tryGet(AnnotationHostToken)) return; // annotation model owns the data\n    if (pon in ctx.getState().pages) loadLinksPage(ctx, pon);\n  };\n\n  const unsubscribe = doc.events.subscribe((event: DocumentEvent) => {\n    switch (event.type) {\n      case 'annotation.created':\n        refetch(event.created.pageObjectNumber);\n        break;\n      case 'annotation.updated':\n        refetch(event.updated.pageObjectNumber);\n        break;\n      case 'annotation.moved':\n        if (event.moved.length) refetch(event.moved[0].pageObjectNumber);\n        break;\n      case 'annotation.deleted':\n        refetch(event.pageObjectNumber);\n        break;\n      default:\n        break;\n    }\n  });\n  ctx.cleanup(unsubscribe);\n}\n","import type { LinkAction, LinkState } from './types';\n\nexport const initialLinkState = (): LinkState => ({ pages: {} });\n\n/** Pure. Engine-backed page cache only — the annotation-backed mode reads the\n *  annotation plugin's model and never touches this state. */\nexport function linkReducer(state: LinkState, a: LinkAction): LinkState {\n  switch (a.type) {\n    case 'SET_PAGE':\n      return { ...state, pages: { ...state.pages, [a.pon]: a.items } };\n    case 'DROP_PAGE': {\n      if (!(a.pon in state.pages)) return state;\n      const pages = { ...state.pages };\n      delete pages[a.pon];\n      return { ...state, pages };\n    }\n  }\n}\n","import { definePlugin } from '@embedpdf/core';\nimport { ActionsToken } from '@embedpdf/plugin-actions/contract';\nimport { AnnotationToken } from '@embedpdf/plugin-annotation/contract';\n// Behavior registration lives on the HOST capability (framework/plugin\n// surface) — same runtime token, wider type. The form plugin's precedent.\nimport { AnnotationToken as AnnotationHostToken } from '@embedpdf/plugin-annotation/contract/host';\nimport { InteractionToken } from '@embedpdf/plugin-interaction/contract';\nimport { StageToken } from '@embedpdf/plugin-stage/contract';\n\nimport { createLinkCapability } from './capability';\nimport { registerLinkEffects } from './effects';\nimport { initialLinkState, linkReducer } from './reducer';\nimport { LinkToken } from './types';\nimport type { LinkAction, LinkCapability, LinkPluginConfig, LinkState } from './types';\n\n/**\n * The link plugin: the NAVIGATION plane. Document-scoped; requires only the\n * interaction hub. Navigation works with no annotation plugin at all —\n * links are read from the engine's link DTOs. When the annotation plugin IS\n * present, its folded model becomes the data source (no double fetch) and a\n * Behavior keeps links navigation-owned while a `link-nav` tool is active\n * (pointer/pan/form-fill by default) — the single-active-tool hub IS the\n * mode switch: grab the link tool and every link becomes an editable rect.\n */\nexport const linkPlugin = (config?: LinkPluginConfig) =>\n  definePlugin<LinkState, LinkAction, LinkCapability>({\n    id: 'link',\n    token: LinkToken,\n    scope: 'document',\n    requires: [InteractionToken],\n    optional: [StageToken, AnnotationToken, ActionsToken],\n    initialState: initialLinkState,\n    reduce: linkReducer,\n    capability: (ctx) => createLinkCapability(ctx, config),\n    effects: registerLinkEffects,\n    init: (ctx) => {\n      const interaction = ctx.get(InteractionToken);\n      const annotation = ctx.tryGet(AnnotationHostToken);\n      if (annotation) {\n        annotation.registerBehavior({\n          id: 'link-nav',\n          matches: (a) => a.subtype === 'link',\n          engaged: () => interaction.activeTool()?.enables.has('link-nav') ?? false,\n        });\n      }\n    },\n  });\n"],"mappings":"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"}

package/dist/index.d.cts

@@ -1,75 +1,4 @@
-import { PageObjectNumber } from "@embedpdf/core";
-import { PdfDestination, PdfLinkTarget } from "@embedpdf/engine-core/runtime";
-import { LinkNavItem } from "@embedpdf/plugin-annotation";
-//#region src/types.d.ts
-/**
- * What one activation did. `revealed` = the stage moved the camera;
- * `destination` = no stage plugin — the embedder gets the explicit
- * destination to handle; `uri` = opening is the FRAMEWORK layer's job (the
- * plugin is DOM-free); `named` = a viewer verb (NextPage…) reported until
- * stage verbs land; `reported` = read-only/executable-shaped targets
- * (javascript / goto-remote / launch / unsupported) — surfaced, NEVER
- * executed here (javascript belongs to the scripting orchestrator).
- */
-type LinkActivation = {
-  outcome: 'revealed';
-} | {
-  outcome: 'destination';
-  destination: PdfDestination;
-} | {
-  outcome: 'uri';
-  uri: string;
-} | {
-  outcome: 'named';
-  name: string;
-} | {
-  outcome: 'reported';
-  target: PdfLinkTarget;
-} | {
-  outcome: 'none';
-};
-interface LinkActivateEvent {
-  target: PdfLinkTarget;
-  activation: LinkActivation;
-}
-interface LinkPluginConfig {
-  /** Every activation (navigations AND reported targets) — analytics /
-   *  custom handling. Called after the built-in handling ran. */
-  onActivate?: (event: LinkActivateEvent) => void;
-}
-/**
- * The navigation plane of link annotations. Data comes from ONE of two
- * sources, picked at init: the annotation plugin's folded model when that
- * plugin is present (zero extra engine reads — it already lists every
- * page), or the plugin's own engine reads in viewer-only deployments.
- */
-interface LinkCapability {
-  /** The clickable link areas of a page (content space, y-down). */
-  linksOn(pon: PageObjectNumber): LinkNavItem[];
-  /** Lazy-load a page's links (no-op when the annotation plugin owns the data). */
-  ensurePage(pon: PageObjectNumber): void;
-  /** Whether the navigation plane currently owns links: the active tool
-   *  enables `link-nav` (pointer/pan/form-fill by default). While false —
-   *  the link tool or any authoring tool is active — the annotation plane
-   *  owns them and the LinkLayer stands down. */
-  engaged(): boolean;
-  /** THE one activation entry point (framework layers call it on click). */
-  activate(target: PdfLinkTarget): LinkActivation;
-}
-/** Engine-backed page cache (viewer-only deployments). */
-interface LinkState {
-  pages: Record<number, LinkNavItem[]>;
-}
-type LinkAction = {
-  type: 'SET_PAGE';
-  pon: number;
-  items: LinkNavItem[];
-} | {
-  type: 'DROP_PAGE';
-  pon: number;
-};
-declare const LinkToken: import("@embedpdf/core").CapabilityToken<LinkCapability>;
-//#endregion
+import { a as LinkCapability, c as LinkState, d as PdfLinkTarget, i as LinkActivation, l as LinkToken, n as LinkActivateContext, o as LinkNavItem, r as LinkActivateEvent, s as LinkPluginConfig, t as LinkAction, u as PdfDestination } from "./contract-DO3vDsAV.cjs";
 //#region src/link.plugin.d.ts
 /**
  * The link plugin: the NAVIGATION plane. Document-scoped; requires only the
@@ -82,5 +11,5 @@ declare const LinkToken: import("@embedpdf/core").CapabilityToken<LinkCapability
  */
 declare const linkPlugin: (config?: LinkPluginConfig) => import("@embedpdf/core").PluginDef<LinkState, LinkAction, LinkCapability>;
 //#endregion
-export { type LinkActivateEvent, type LinkActivation, type LinkCapability, type LinkNavItem, type LinkPluginConfig, type LinkState, LinkToken, type PdfDestination, type PdfLinkTarget, linkPlugin };
+export { type LinkActivateContext, type LinkActivateEvent, type LinkActivation, type LinkCapability, type LinkNavItem, type LinkPluginConfig, type LinkState, LinkToken, type PdfDestination, type PdfLinkTarget, linkPlugin };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -1,75 +1,4 @@
-import { PageObjectNumber } from "@embedpdf/core";
-import { LinkNavItem } from "@embedpdf/plugin-annotation";
-import { PdfDestination, PdfLinkTarget } from "@embedpdf/engine-core/runtime";
-//#region src/types.d.ts
-/**
- * What one activation did. `revealed` = the stage moved the camera;
- * `destination` = no stage plugin — the embedder gets the explicit
- * destination to handle; `uri` = opening is the FRAMEWORK layer's job (the
- * plugin is DOM-free); `named` = a viewer verb (NextPage…) reported until
- * stage verbs land; `reported` = read-only/executable-shaped targets
- * (javascript / goto-remote / launch / unsupported) — surfaced, NEVER
- * executed here (javascript belongs to the scripting orchestrator).
- */
-type LinkActivation = {
-  outcome: 'revealed';
-} | {
-  outcome: 'destination';
-  destination: PdfDestination;
-} | {
-  outcome: 'uri';
-  uri: string;
-} | {
-  outcome: 'named';
-  name: string;
-} | {
-  outcome: 'reported';
-  target: PdfLinkTarget;
-} | {
-  outcome: 'none';
-};
-interface LinkActivateEvent {
-  target: PdfLinkTarget;
-  activation: LinkActivation;
-}
-interface LinkPluginConfig {
-  /** Every activation (navigations AND reported targets) — analytics /
-   *  custom handling. Called after the built-in handling ran. */
-  onActivate?: (event: LinkActivateEvent) => void;
-}
-/**
- * The navigation plane of link annotations. Data comes from ONE of two
- * sources, picked at init: the annotation plugin's folded model when that
- * plugin is present (zero extra engine reads — it already lists every
- * page), or the plugin's own engine reads in viewer-only deployments.
- */
-interface LinkCapability {
-  /** The clickable link areas of a page (content space, y-down). */
-  linksOn(pon: PageObjectNumber): LinkNavItem[];
-  /** Lazy-load a page's links (no-op when the annotation plugin owns the data). */
-  ensurePage(pon: PageObjectNumber): void;
-  /** Whether the navigation plane currently owns links: the active tool
-   *  enables `link-nav` (pointer/pan/form-fill by default). While false —
-   *  the link tool or any authoring tool is active — the annotation plane
-   *  owns them and the LinkLayer stands down. */
-  engaged(): boolean;
-  /** THE one activation entry point (framework layers call it on click). */
-  activate(target: PdfLinkTarget): LinkActivation;
-}
-/** Engine-backed page cache (viewer-only deployments). */
-interface LinkState {
-  pages: Record<number, LinkNavItem[]>;
-}
-type LinkAction = {
-  type: 'SET_PAGE';
-  pon: number;
-  items: LinkNavItem[];
-} | {
-  type: 'DROP_PAGE';
-  pon: number;
-};
-declare const LinkToken: import("@embedpdf/core").CapabilityToken<LinkCapability>;
-//#endregion
+import { a as LinkCapability, c as LinkState, d as PdfLinkTarget, i as LinkActivation, l as LinkToken, n as LinkActivateContext, o as LinkNavItem, r as LinkActivateEvent, s as LinkPluginConfig, t as LinkAction, u as PdfDestination } from "./contract-B8bEMeH8.js";
 //#region src/link.plugin.d.ts
 /**
  * The link plugin: the NAVIGATION plane. Document-scoped; requires only the
@@ -82,5 +11,5 @@ declare const LinkToken: import("@embedpdf/core").CapabilityToken<LinkCapability
  */
 declare const linkPlugin: (config?: LinkPluginConfig) => import("@embedpdf/core").PluginDef<LinkState, LinkAction, LinkCapability>;
 //#endregion
-export { type LinkActivateEvent, type LinkActivation, type LinkCapability, type LinkNavItem, type LinkPluginConfig, type LinkState, LinkToken, type PdfDestination, type PdfLinkTarget, linkPlugin };
+export { type LinkActivateContext, type LinkActivateEvent, type LinkActivation, type LinkCapability, type LinkNavItem, type LinkPluginConfig, type LinkState, LinkToken, type PdfDestination, type PdfLinkTarget, linkPlugin };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,8 +1,11 @@
-import { createCapabilityToken, definePlugin } from "@embedpdf/core";
-import { InteractionToken } from "@embedpdf/plugin-interaction";
-import { StageToken, destinationToReveal } from "@embedpdf/plugin-stage";
-import { AnnotationToken } from "@embedpdf/plugin-annotation";
-import { AnnotationToken as AnnotationToken$1 } from "@embedpdf/plugin-annotation/internal";
+import { t as LinkToken } from "./contract-HRggERzU.js";
+import { definePlugin } from "@embedpdf/core";
+import { ActionsToken } from "@embedpdf/plugin-actions/contract";
+import { AnnotationToken } from "@embedpdf/plugin-annotation/contract";
+import { AnnotationToken as AnnotationToken$1 } from "@embedpdf/plugin-annotation/contract/host";
+import { InteractionToken } from "@embedpdf/plugin-interaction/contract";
+import { StageToken } from "@embedpdf/plugin-stage/contract";
+import { destinationToReveal } from "@embedpdf/plugin-stage/destination";
 import { pdfToContentRect } from "@embedpdf/core-annotation";
 //#region src/source.ts
 function loadLinksPage(io, pon) {
@@ -18,6 +21,12 @@ function loadLinksPage(io, pon) {
 				id: dto.ref.kind === "objectNumber" ? `obj:${dto.ref.annotObjectNumber}` : `idx:${pon}:${dto.index}`,
 				rect: pdfToContentRect(dto.rect, crop),
 				target: dto.target,
+				...dto.actions?.activate ? { activate: dto.actions.activate } : {},
+				...dto.actions?.cursorEnter?.root || dto.actions?.cursorExit?.root ? { hoverEvents: {
+					enter: Boolean(dto.actions?.cursorEnter?.root),
+					exit: Boolean(dto.actions?.cursorExit?.root)
+				} } : {},
+				ref: dto.ref,
 				attached: dto.replyType === "group" && dto.inReplyTo != null
 			});
 		}
@@ -40,8 +49,21 @@ const EMPTY = [];
 */
 function createLinkCapability(ctx, config = {}) {
 	const anno = () => ctx.tryGet(AnnotationToken$1);
-	const activate = (target) => {
+	const activate = (target, context) => {
 		const activation = (() => {
+			const actions = ctx.tryGet(ActionsToken);
+			if (actions && context?.activate) return {
+				outcome: "dispatched",
+				dispatch: actions.execute(context.activate, {
+					origin: "user",
+					source: {
+						kind: "link",
+						annotation: context.ref,
+						pon: context.pon
+					},
+					event: { scope: "activate" }
+				})
+			};
 			switch (target.kind) {
 				case "goto": {
 					const stage = ctx.tryGet(StageToken);
@@ -156,9 +178,6 @@ function linkReducer(state, a) {
 	}
 }
 //#endregion
-//#region src/types.ts
-const LinkToken = createCapabilityToken("link");
-//#endregion
 //#region src/link.plugin.ts
 /**
 * The link plugin: the NAVIGATION plane. Document-scoped; requires only the
@@ -174,7 +193,11 @@ const linkPlugin = (config) => definePlugin({
 	token: LinkToken,
 	scope: "document",
 	requires: [InteractionToken],
-	optional: [StageToken, AnnotationToken],
+	optional: [
+		StageToken,
+		AnnotationToken,
+		ActionsToken
+	],
 	initialState: initialLinkState,
 	reduce: linkReducer,
 	capability: (ctx) => createLinkCapability(ctx, config),

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["AnnotationHostToken","AnnotationHostToken","AnnotationHostToken"],"sources":["../src/source.ts","../src/capability.ts","../src/effects.ts","../src/reducer.ts","../src/types.ts","../src/link.plugin.ts"],"sourcesContent":["import type { DocumentHandle, PageLayout } from '@embedpdf/core';\nimport { pdfToContentRect } from '@embedpdf/core-annotation';\nimport type { LinkAction, LinkNavItem } from './types';\n\n/**\n * The ENGINE-BACKED link source, for viewer-only deployments (no annotation\n * plugin): read a page's annotation list and keep just the navigable links —\n * standalone AND attached children alike (both are raw link DTOs here).\n * Shared by the capability's lazy `ensurePage` and the effects module's\n * event-driven refetch; both PluginContext and EffectContext satisfy the\n * structural `io` slice.\n */\nexport interface LinkSourceIO {\n  doc: DocumentHandle | null;\n  document(): { pages: readonly PageLayout[] } | null;\n  dispatch(action: LinkAction): void;\n}\n\nexport function loadLinksPage(io: LinkSourceIO, pon: number): void {\n  const doc = io.doc;\n  const crop = io.document()?.pages.find((p) => p.pageObjectNumber === pon)?.boxes.crop;\n  if (!doc || !crop) return;\n  doc\n    .page(pon)\n    .annotations.list()\n    .then(\n      (snap) => {\n        const items: LinkNavItem[] = [];\n        for (const dto of snap.annotations) {\n          if (dto.subtype !== 'link' || dto.target == null) continue;\n          if (dto.flags.hidden || dto.flags.noView) continue;\n          items.push({\n            id:\n              dto.ref.kind === 'objectNumber'\n                ? `obj:${dto.ref.annotObjectNumber}`\n                : `idx:${pon}:${dto.index}`,\n            rect: pdfToContentRect(dto.rect, crop),\n            target: dto.target,\n            // A `/RT /Group` child riding another annotation — labeled so the\n            // nav layer can defer to editing (moot in viewer-only deployments,\n            // but the item contract stays truthful either way).\n            attached: dto.replyType === 'group' && dto.inReplyTo != null,\n          });\n        }\n        io.dispatch({ type: 'SET_PAGE', pon, items });\n      },\n      () => {},\n    );\n}\n","import type { PluginContext } from '@embedpdf/core';\nimport type { PdfLinkTarget } from '@embedpdf/engine-core/runtime';\nimport { InteractionToken } from '@embedpdf/plugin-interaction';\nimport { destinationToReveal, StageToken } from '@embedpdf/plugin-stage';\n// The host lens (linkItemsOn) — same runtime token as the public one.\nimport { AnnotationToken as AnnotationHostToken } from '@embedpdf/plugin-annotation/internal';\nimport { loadLinksPage } from './source';\nimport type {\n  LinkAction,\n  LinkActivation,\n  LinkCapability,\n  LinkNavItem,\n  LinkPluginConfig,\n  LinkState,\n} from './types';\n\nconst EMPTY: LinkNavItem[] = [];\n\n/**\n * The navigation plane's surface. Data source is decided PER CALL (lazily,\n * so plugin registration order can't matter): the annotation plugin's\n * folded model when present — its `linkItemsOn` lens is memoized by model\n * identity and already excludes hidden links — else this plugin's own\n * engine-backed page cache (see source.ts).\n */\nexport function createLinkCapability(\n  ctx: PluginContext<LinkState, LinkAction>,\n  config: LinkPluginConfig = {},\n): LinkCapability {\n  const anno = () => ctx.tryGet(AnnotationHostToken);\n\n  const activate = (target: PdfLinkTarget): LinkActivation => {\n    const activation = ((): LinkActivation => {\n      switch (target.kind) {\n        case 'goto': {\n          const stage = ctx.tryGet(StageToken);\n          const layout = ctx\n            .document()\n            ?.pages.find((p) => p.pageObjectNumber === target.destination.pageObjectNumber);\n          if (!stage || !layout) {\n            // No camera to drive — hand the embedder the explicit destination.\n            return { outcome: 'destination', destination: target.destination };\n          }\n          const { pageIndex, options } = destinationToReveal(target.destination, layout);\n          stage.reveal(pageIndex, { ...options, behavior: 'smooth' });\n          return { outcome: 'revealed' };\n        }\n        case 'uri':\n          // Opening is the FRAMEWORK layer's job (a real <a href> after\n          // sanitizing) — this plugin never touches the DOM.\n          return { outcome: 'uri', uri: target.uri };\n        case 'named':\n          return { outcome: 'named', name: target.name };\n        default:\n          // javascript / goto-remote / launch / unsupported: reported, never\n          // executed here. JavaScript activation belongs to the scripting\n          // orchestrator once it lands — the chain already rides the\n          // annotation's base `actions`.\n          return { outcome: 'reported', target };\n      }\n    })();\n    config.onActivate?.({ target, activation });\n    return activation;\n  };\n\n  return {\n    linksOn: (pon) => {\n      const host = anno();\n      if (host) return host.linkItemsOn(pon);\n      return ctx.getState().pages[pon] ?? EMPTY;\n    },\n    ensurePage: (pon) => {\n      const host = anno();\n      if (host) {\n        host.ensurePage(pon); // the folded model is the source; it lazy-loads\n        return;\n      }\n      if (!(pon in ctx.getState().pages)) loadLinksPage(ctx, pon);\n    },\n    engaged: () => ctx.tryGet(InteractionToken)?.activeTool()?.enables.has('link-nav') ?? false,\n    activate,\n  };\n}\n","import type { DocumentEvent, EffectContext } from '@embedpdf/core';\nimport { AnnotationToken as AnnotationHostToken } from '@embedpdf/plugin-annotation/internal';\nimport { loadLinksPage } from './source';\nimport type { LinkAction, LinkState } from './types';\n\n/**\n * Keeps the ENGINE-BACKED page cache honest in viewer-only deployments:\n * any annotation mutation on a cached page (own or remote — the cache has\n * no other refresh path, unlike the annotation plugin's optimistic model)\n * refetches that page's links. With the annotation plugin present the\n * folded model is the source and this effect never fires a fetch.\n */\nexport function registerLinkEffects(ctx: EffectContext<LinkState, LinkAction>): void {\n  const doc = ctx.doc;\n  if (!doc) return;\n\n  const refetch = (pon: number): void => {\n    if (ctx.tryGet(AnnotationHostToken)) return; // annotation model owns the data\n    if (pon in ctx.getState().pages) loadLinksPage(ctx, pon);\n  };\n\n  const unsubscribe = doc.events.subscribe((event: DocumentEvent) => {\n    switch (event.type) {\n      case 'annotation.created':\n        refetch(event.created.pageObjectNumber);\n        break;\n      case 'annotation.updated':\n        refetch(event.updated.pageObjectNumber);\n        break;\n      case 'annotation.moved':\n        if (event.moved.length) refetch(event.moved[0].pageObjectNumber);\n        break;\n      case 'annotation.deleted':\n        refetch(event.pageObjectNumber);\n        break;\n      default:\n        break;\n    }\n  });\n  ctx.cleanup(unsubscribe);\n}\n","import type { LinkAction, LinkState } from './types';\n\nexport const initialLinkState = (): LinkState => ({ pages: {} });\n\n/** Pure. Engine-backed page cache only — the annotation-backed mode reads the\n *  annotation plugin's model and never touches this state. */\nexport function linkReducer(state: LinkState, a: LinkAction): LinkState {\n  switch (a.type) {\n    case 'SET_PAGE':\n      return { ...state, pages: { ...state.pages, [a.pon]: a.items } };\n    case 'DROP_PAGE': {\n      if (!(a.pon in state.pages)) return state;\n      const pages = { ...state.pages };\n      delete pages[a.pon];\n      return { ...state, pages };\n    }\n  }\n}\n","import { createCapabilityToken, type PageObjectNumber } from '@embedpdf/core';\nimport type { PdfDestination, PdfLinkTarget } from '@embedpdf/engine-core/runtime';\nimport type { LinkNavItem } from '@embedpdf/plugin-annotation';\n\nexport type { LinkNavItem };\n// The wire target vocabulary, re-exported so app code building link editors\n// needs only this package (the annotation-props precedent).\nexport type { PdfDestination, PdfLinkTarget };\n\n/**\n * What one activation did. `revealed` = the stage moved the camera;\n * `destination` = no stage plugin — the embedder gets the explicit\n * destination to handle; `uri` = opening is the FRAMEWORK layer's job (the\n * plugin is DOM-free); `named` = a viewer verb (NextPage…) reported until\n * stage verbs land; `reported` = read-only/executable-shaped targets\n * (javascript / goto-remote / launch / unsupported) — surfaced, NEVER\n * executed here (javascript belongs to the scripting orchestrator).\n */\nexport type LinkActivation =\n  | { outcome: 'revealed' }\n  | { outcome: 'destination'; destination: PdfDestination }\n  | { outcome: 'uri'; uri: string }\n  | { outcome: 'named'; name: string }\n  | { outcome: 'reported'; target: PdfLinkTarget }\n  | { outcome: 'none' };\n\nexport interface LinkActivateEvent {\n  target: PdfLinkTarget;\n  activation: LinkActivation;\n}\n\nexport interface LinkPluginConfig {\n  /** Every activation (navigations AND reported targets) — analytics /\n   *  custom handling. Called after the built-in handling ran. */\n  onActivate?: (event: LinkActivateEvent) => void;\n}\n\n/**\n * The navigation plane of link annotations. Data comes from ONE of two\n * sources, picked at init: the annotation plugin's folded model when that\n * plugin is present (zero extra engine reads — it already lists every\n * page), or the plugin's own engine reads in viewer-only deployments.\n */\nexport interface LinkCapability {\n  /** The clickable link areas of a page (content space, y-down). */\n  linksOn(pon: PageObjectNumber): LinkNavItem[];\n  /** Lazy-load a page's links (no-op when the annotation plugin owns the data). */\n  ensurePage(pon: PageObjectNumber): void;\n  /** Whether the navigation plane currently owns links: the active tool\n   *  enables `link-nav` (pointer/pan/form-fill by default). While false —\n   *  the link tool or any authoring tool is active — the annotation plane\n   *  owns them and the LinkLayer stands down. */\n  engaged(): boolean;\n  /** THE one activation entry point (framework layers call it on click). */\n  activate(target: PdfLinkTarget): LinkActivation;\n}\n\n/** Engine-backed page cache (viewer-only deployments). */\nexport interface LinkState {\n  pages: Record<number, LinkNavItem[]>;\n}\n\nexport type LinkAction =\n  | { type: 'SET_PAGE'; pon: number; items: LinkNavItem[] }\n  | { type: 'DROP_PAGE'; pon: number };\n\nexport const LinkToken = createCapabilityToken<LinkCapability>('link');\n","import { definePlugin } from '@embedpdf/core';\nimport { InteractionToken } from '@embedpdf/plugin-interaction';\nimport { StageToken } from '@embedpdf/plugin-stage';\nimport { AnnotationToken } from '@embedpdf/plugin-annotation';\n// Behavior registration lives on the HOST capability (framework/plugin\n// surface) — same runtime token, wider type. The form plugin's precedent.\nimport { AnnotationToken as AnnotationHostToken } from '@embedpdf/plugin-annotation/internal';\n\nimport { createLinkCapability } from './capability';\nimport { registerLinkEffects } from './effects';\nimport { initialLinkState, linkReducer } from './reducer';\nimport { LinkToken } from './types';\nimport type { LinkAction, LinkCapability, LinkPluginConfig, LinkState } from './types';\n\n/**\n * The link plugin: the NAVIGATION plane. Document-scoped; requires only the\n * interaction hub. Navigation works with no annotation plugin at all —\n * links are read from the engine's link DTOs. When the annotation plugin IS\n * present, its folded model becomes the data source (no double fetch) and a\n * Behavior keeps links navigation-owned while a `link-nav` tool is active\n * (pointer/pan/form-fill by default) — the single-active-tool hub IS the\n * mode switch: grab the link tool and every link becomes an editable rect.\n */\nexport const linkPlugin = (config?: LinkPluginConfig) =>\n  definePlugin<LinkState, LinkAction, LinkCapability>({\n    id: 'link',\n    token: LinkToken,\n    scope: 'document',\n    requires: [InteractionToken],\n    optional: [StageToken, AnnotationToken],\n    initialState: initialLinkState,\n    reduce: linkReducer,\n    capability: (ctx) => createLinkCapability(ctx, config),\n    effects: registerLinkEffects,\n    init: (ctx) => {\n      const interaction = ctx.get(InteractionToken);\n      const annotation = ctx.tryGet(AnnotationHostToken);\n      if (annotation) {\n        annotation.registerBehavior({\n          id: 'link-nav',\n          matches: (a) => a.subtype === 'link',\n          engaged: () => interaction.activeTool()?.enables.has('link-nav') ?? false,\n        });\n      }\n    },\n  });\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":["AnnotationHostToken","AnnotationHostToken","AnnotationHostToken"],"sources":["../src/source.ts","../src/capability.ts","../src/effects.ts","../src/reducer.ts","../src/link.plugin.ts"],"sourcesContent":["import type { DocumentHandle, PageLayout } from '@embedpdf/core';\nimport { pdfToContentRect } from '@embedpdf/core-annotation';\nimport type { LinkAction, LinkNavItem } from './types';\n\n/**\n * The ENGINE-BACKED link source, for viewer-only deployments (no annotation\n * plugin): read a page's annotation list and keep just the navigable links —\n * standalone AND attached children alike (both are raw link DTOs here).\n * Shared by the capability's lazy `ensurePage` and the effects module's\n * event-driven refetch; both PluginContext and EffectContext satisfy the\n * structural `io` slice.\n */\nexport interface LinkSourceIO {\n  doc: DocumentHandle | null;\n  document(): { pages: readonly PageLayout[] } | null;\n  dispatch(action: LinkAction): void;\n}\n\nexport function loadLinksPage(io: LinkSourceIO, pon: number): void {\n  const doc = io.doc;\n  const crop = io.document()?.pages.find((p) => p.pageObjectNumber === pon)?.boxes.crop;\n  if (!doc || !crop) return;\n  doc\n    .page(pon)\n    .annotations.list()\n    .then(\n      (snap) => {\n        const items: LinkNavItem[] = [];\n        for (const dto of snap.annotations) {\n          if (dto.subtype !== 'link' || dto.target == null) continue;\n          if (dto.flags.hidden || dto.flags.noView) continue;\n          items.push({\n            id:\n              dto.ref.kind === 'objectNumber'\n                ? `obj:${dto.ref.annotObjectNumber}`\n                : `idx:${pon}:${dto.index}`,\n            rect: pdfToContentRect(dto.rect, crop),\n            target: dto.target,\n            ...(dto.actions?.activate ? { activate: dto.actions.activate } : {}),\n            ...(dto.actions?.cursorEnter?.root || dto.actions?.cursorExit?.root\n              ? {\n                  hoverEvents: {\n                    enter: Boolean(dto.actions?.cursorEnter?.root),\n                    exit: Boolean(dto.actions?.cursorExit?.root),\n                  },\n                }\n              : {}),\n            ref: dto.ref,\n            // A `/RT /Group` child riding another annotation — labeled so the\n            // nav layer can defer to editing (moot in viewer-only deployments,\n            // but the item contract stays truthful either way).\n            attached: dto.replyType === 'group' && dto.inReplyTo != null,\n          });\n        }\n        io.dispatch({ type: 'SET_PAGE', pon, items });\n      },\n      () => {},\n    );\n}\n","import type { PluginContext } from '@embedpdf/core';\nimport type { PdfLinkTarget } from '@embedpdf/engine-core/runtime';\nimport { ActionsToken } from '@embedpdf/plugin-actions/contract';\n// The host lens (linkItemsOn) — same runtime token as the public one.\nimport { AnnotationToken as AnnotationHostToken } from '@embedpdf/plugin-annotation/contract/host';\nimport { InteractionToken } from '@embedpdf/plugin-interaction/contract';\nimport { StageToken } from '@embedpdf/plugin-stage/contract';\nimport { destinationToReveal } from '@embedpdf/plugin-stage/destination';\nimport { loadLinksPage } from './source';\nimport type {\n  LinkAction,\n  LinkActivateContext,\n  LinkActivation,\n  LinkCapability,\n  LinkNavItem,\n  LinkPluginConfig,\n  LinkState,\n} from './types';\n\nconst EMPTY: LinkNavItem[] = [];\n\n/**\n * The navigation plane's surface. Data source is decided PER CALL (lazily,\n * so plugin registration order can't matter): the annotation plugin's\n * folded model when present — its `linkItemsOn` lens is memoized by model\n * identity and already excludes hidden links — else this plugin's own\n * engine-backed page cache (see source.ts).\n */\nexport function createLinkCapability(\n  ctx: PluginContext<LinkState, LinkAction>,\n  config: LinkPluginConfig = {},\n): LinkCapability {\n  const anno = () => ctx.tryGet(AnnotationHostToken);\n\n  const activate = (target: PdfLinkTarget, context?: LinkActivateContext): LinkActivation => {\n    const activation = ((): LinkActivation => {\n      // The action engine takes precedence when it is installed and the item\n      // carries its payload tree: named verbs execute, mixed /Next chains\n      // run, and the dispatcher enforces policy + the incomplete-tree law.\n      // Without it, the classic root-projection path below is the fallback.\n      const actions = ctx.tryGet(ActionsToken);\n      if (actions && context?.activate) {\n        const dispatch = actions.execute(context.activate, {\n          origin: 'user',\n          source: { kind: 'link', annotation: context.ref, pon: context.pon },\n          event: { scope: 'activate' },\n        });\n        return { outcome: 'dispatched', dispatch };\n      }\n      switch (target.kind) {\n        case 'goto': {\n          const stage = ctx.tryGet(StageToken);\n          const layout = ctx\n            .document()\n            ?.pages.find((p) => p.pageObjectNumber === target.destination.pageObjectNumber);\n          if (!stage || !layout) {\n            // No camera to drive — hand the embedder the explicit destination.\n            return { outcome: 'destination', destination: target.destination };\n          }\n          const { pageIndex, options } = destinationToReveal(target.destination, layout);\n          stage.reveal(pageIndex, { ...options, behavior: 'smooth' });\n          return { outcome: 'revealed' };\n        }\n        case 'uri':\n          // Opening is the FRAMEWORK layer's job (a real <a href> after\n          // sanitizing) — this plugin never touches the DOM.\n          return { outcome: 'uri', uri: target.uri };\n        case 'named':\n          return { outcome: 'named', name: target.name };\n        default:\n          // javascript / goto-remote / launch / unsupported: reported, never\n          // executed here. JavaScript activation belongs to the scripting\n          // orchestrator once it lands — the chain already rides the\n          // annotation's base `actions`.\n          return { outcome: 'reported', target };\n      }\n    })();\n    config.onActivate?.({ target, activation });\n    return activation;\n  };\n\n  return {\n    linksOn: (pon) => {\n      const host = anno();\n      if (host) return host.linkItemsOn(pon);\n      return ctx.getState().pages[pon] ?? EMPTY;\n    },\n    ensurePage: (pon) => {\n      const host = anno();\n      if (host) {\n        host.ensurePage(pon); // the folded model is the source; it lazy-loads\n        return;\n      }\n      if (!(pon in ctx.getState().pages)) loadLinksPage(ctx, pon);\n    },\n    engaged: () => ctx.tryGet(InteractionToken)?.activeTool()?.enables.has('link-nav') ?? false,\n    activate,\n  };\n}\n","import type { DocumentEvent, EffectContext } from '@embedpdf/core';\nimport { AnnotationToken as AnnotationHostToken } from '@embedpdf/plugin-annotation/contract/host';\nimport { loadLinksPage } from './source';\nimport type { LinkAction, LinkState } from './types';\n\n/**\n * Keeps the ENGINE-BACKED page cache honest in viewer-only deployments:\n * any annotation mutation on a cached page (own or remote — the cache has\n * no other refresh path, unlike the annotation plugin's optimistic model)\n * refetches that page's links. With the annotation plugin present the\n * folded model is the source and this effect never fires a fetch.\n */\nexport function registerLinkEffects(ctx: EffectContext<LinkState, LinkAction>): void {\n  const doc = ctx.doc;\n  if (!doc) return;\n\n  const refetch = (pon: number): void => {\n    if (ctx.tryGet(AnnotationHostToken)) return; // annotation model owns the data\n    if (pon in ctx.getState().pages) loadLinksPage(ctx, pon);\n  };\n\n  const unsubscribe = doc.events.subscribe((event: DocumentEvent) => {\n    switch (event.type) {\n      case 'annotation.created':\n        refetch(event.created.pageObjectNumber);\n        break;\n      case 'annotation.updated':\n        refetch(event.updated.pageObjectNumber);\n        break;\n      case 'annotation.moved':\n        if (event.moved.length) refetch(event.moved[0].pageObjectNumber);\n        break;\n      case 'annotation.deleted':\n        refetch(event.pageObjectNumber);\n        break;\n      default:\n        break;\n    }\n  });\n  ctx.cleanup(unsubscribe);\n}\n","import type { LinkAction, LinkState } from './types';\n\nexport const initialLinkState = (): LinkState => ({ pages: {} });\n\n/** Pure. Engine-backed page cache only — the annotation-backed mode reads the\n *  annotation plugin's model and never touches this state. */\nexport function linkReducer(state: LinkState, a: LinkAction): LinkState {\n  switch (a.type) {\n    case 'SET_PAGE':\n      return { ...state, pages: { ...state.pages, [a.pon]: a.items } };\n    case 'DROP_PAGE': {\n      if (!(a.pon in state.pages)) return state;\n      const pages = { ...state.pages };\n      delete pages[a.pon];\n      return { ...state, pages };\n    }\n  }\n}\n","import { definePlugin } from '@embedpdf/core';\nimport { ActionsToken } from '@embedpdf/plugin-actions/contract';\nimport { AnnotationToken } from '@embedpdf/plugin-annotation/contract';\n// Behavior registration lives on the HOST capability (framework/plugin\n// surface) — same runtime token, wider type. The form plugin's precedent.\nimport { AnnotationToken as AnnotationHostToken } from '@embedpdf/plugin-annotation/contract/host';\nimport { InteractionToken } from '@embedpdf/plugin-interaction/contract';\nimport { StageToken } from '@embedpdf/plugin-stage/contract';\n\nimport { createLinkCapability } from './capability';\nimport { registerLinkEffects } from './effects';\nimport { initialLinkState, linkReducer } from './reducer';\nimport { LinkToken } from './types';\nimport type { LinkAction, LinkCapability, LinkPluginConfig, LinkState } from './types';\n\n/**\n * The link plugin: the NAVIGATION plane. Document-scoped; requires only the\n * interaction hub. Navigation works with no annotation plugin at all —\n * links are read from the engine's link DTOs. When the annotation plugin IS\n * present, its folded model becomes the data source (no double fetch) and a\n * Behavior keeps links navigation-owned while a `link-nav` tool is active\n * (pointer/pan/form-fill by default) — the single-active-tool hub IS the\n * mode switch: grab the link tool and every link becomes an editable rect.\n */\nexport const linkPlugin = (config?: LinkPluginConfig) =>\n  definePlugin<LinkState, LinkAction, LinkCapability>({\n    id: 'link',\n    token: LinkToken,\n    scope: 'document',\n    requires: [InteractionToken],\n    optional: [StageToken, AnnotationToken, ActionsToken],\n    initialState: initialLinkState,\n    reduce: linkReducer,\n    capability: (ctx) => createLinkCapability(ctx, config),\n    effects: registerLinkEffects,\n    init: (ctx) => {\n      const interaction = ctx.get(InteractionToken);\n      const annotation = ctx.tryGet(AnnotationHostToken);\n      if (annotation) {\n        annotation.registerBehavior({\n          id: 'link-nav',\n          matches: (a) => a.subtype === 'link',\n          engaged: () => interaction.activeTool()?.enables.has('link-nav') ?? false,\n        });\n      }\n    },\n  });\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@embedpdf/plugin-link",
-  "version": "3.0.0-next.10",
+  "version": "3.0.0-next.11",
   "private": false,
   "description": "The navigation plane for PDF link annotations: per-page clickable link areas + one activate() entry point (GoTo → stage reveal, URI → framework opener). Works standalone in viewer deployments; with the annotation plugin present it reads the folded model (no double fetch) and a Behavior hands links to the editing plane when the link tool is active.",
   "type": "module",
@@ -12,19 +12,24 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
+    "./contract": {
+      "import": "./dist/contract.js",
+      "require": "./dist/contract.cjs"
+    },
     "./package.json": "./package.json"
   },
   "files": [
     "dist"
   ],
   "dependencies": {
-    "@embedpdf/core-annotation": "3.0.0-next.10",
-    "@embedpdf/core": "3.0.0-next.10",
-    "@embedpdf/plugin-interaction": "3.0.0-next.10",
-    "@embedpdf/core-geometry": "3.0.0-next.10",
-    "@embedpdf/plugin-stage": "3.0.0-next.10",
-    "@embedpdf/engine-core": "3.0.0-next.10",
-    "@embedpdf/plugin-annotation": "3.0.0-next.10"
+    "@embedpdf/core-annotation": "3.0.0-next.11",
+    "@embedpdf/core": "3.0.0-next.11",
+    "@embedpdf/plugin-annotation": "3.0.0-next.11",
+    "@embedpdf/core-geometry": "3.0.0-next.11",
+    "@embedpdf/plugin-interaction": "3.0.0-next.11",
+    "@embedpdf/engine-core": "3.0.0-next.11",
+    "@embedpdf/plugin-stage": "3.0.0-next.11",
+    "@embedpdf/plugin-actions": "3.0.0-next.11"
   },
   "devDependencies": {
     "typescript": "^5.0.0",