@embedpdf/plugin-interaction 3.0.0-next.0

package/LICENSE

@@ -0,0 +1,192 @@
+Copyright 2026 CloudPDF LTD
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use files in this distribution except in compliance with the License.
+You may obtain a copy of the License at
+
+    https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+-----------------------------------------------------------------------
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

package/dist/index.cjs

@@ -0,0 +1,214 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _embedpdf_core = require("@embedpdf/core");
+//#region src/capability.ts
+/**
+* The interaction hub. Tools + handlers + the captured-gesture owner + cursor
+* claims live in this closure (runtime registries, not serializable state); the
+* reducer state holds only the active tool id and the resolved cursor, so the UI
+* can react to them. The router (`dispatch`) is the heart: on down, the first
+* eligible handler (by priority) to return true OWNS the gesture; move/up route
+* to it; with no owner, move is hover (cursor feedback).
+*
+* Cursor arbitration, top to bottom: the highest-priority CLAIM (hover feedback
+* — 'move' over an annotation, 'text' over text) → over a page, the tool's
+* declared cursor → over a gap, the tool's `gapCursor` (default the neutral
+* arrow). The winning KEYWORD (claim or base, never gap) is then restyled
+* through the armed tool's skin when it maps that keyword. One resolver, so an
+* image cursor can never shadow hover feedback or outlive the page under the
+* pointer.
+*/
+function createInteractionCapability(ctx, builtinTools) {
+	const tools = /* @__PURE__ */ new Map();
+	for (const t of builtinTools) tools.set(t.id, t);
+	const handlers = [];
+	const claims = /* @__PURE__ */ new Map();
+	const cursorSkins = /* @__PURE__ */ new Map();
+	const toolCbs = /* @__PURE__ */ new Set();
+	let owner = null;
+	let overPage = false;
+	const toolOf = (id) => tools.get(id) ?? {
+		id,
+		cursor: "default",
+		enables: /* @__PURE__ */ new Set()
+	};
+	const active = () => toolOf(ctx.getState().activeToolId);
+	const resolveCursor = () => {
+		let top = null;
+		for (const c of claims.values()) if (!top || c.priority > top.priority) top = c;
+		const tool = active();
+		const skin = cursorSkins.get(tool.id);
+		if (top) return skin?.[top.cursor] ?? top.cursor;
+		if (!overPage) return tool.gapCursor ?? "default";
+		return skin?.[tool.cursor] ?? tool.cursor;
+	};
+	const syncCursor = () => {
+		const next = resolveCursor();
+		if (next !== ctx.getState().cursor) ctx.dispatch({
+			type: "SET_CURSOR",
+			cursor: next
+		});
+	};
+	const eligible = () => {
+		const tool = active();
+		return handlers.filter((h) => h.enabledFor(tool)).sort((a, b) => b.priority - a.priority);
+	};
+	return {
+		activeTool: active,
+		activeToolId: () => ctx.getState().activeToolId,
+		cursor: () => ctx.getState().cursor,
+		tools: () => [...tools.values()],
+		activateTool: (id) => {
+			if (!tools.has(id)) throw new Error(`[interaction] unknown tool '${id}'`);
+			owner = null;
+			claims.clear();
+			ctx.dispatch({
+				type: "SET_TOOL",
+				toolId: id
+			});
+			syncCursor();
+			toolCbs.forEach((cb) => cb());
+		},
+		onToolChange: (cb) => {
+			toolCbs.add(cb);
+			return () => toolCbs.delete(cb);
+		},
+		registerTool: (tool) => {
+			tools.set(tool.id, tool);
+			return () => {
+				tools.delete(tool.id);
+				cursorSkins.delete(tool.id);
+			};
+		},
+		setToolCursor: (id, skin) => {
+			if (skin === null) cursorSkins.delete(id);
+			else cursorSkins.set(id, skin);
+			syncCursor();
+		},
+		registerHandler: (handler) => {
+			handlers.push(handler);
+			return () => {
+				const i = handlers.indexOf(handler);
+				if (i >= 0) handlers.splice(i, 1);
+				if (owner === handler) owner = null;
+			};
+		},
+		setCursor: (token, cursor, priority = 0) => {
+			if (cursor === null) claims.delete(token);
+			else claims.set(token, {
+				cursor,
+				priority
+			});
+			syncCursor();
+		},
+		dispatch: (sample) => {
+			const nowOverPage = sample.page != null;
+			if (nowOverPage !== overPage) {
+				overPage = nowOverPage;
+				syncCursor();
+			}
+			if (sample.phase === "down") {
+				owner = null;
+				for (const h of eligible()) if (h.onDown(sample)) {
+					owner = h;
+					break;
+				}
+			} else if (sample.phase === "move") if (owner) owner.onMove?.(sample);
+			else for (const h of eligible()) h.onHover?.(sample);
+			else {
+				owner?.onUp?.(sample);
+				owner = null;
+			}
+		}
+	};
+}
+//#endregion
+//#region src/reducer.ts
+const initialInteractionState = (config) => ({
+	activeToolId: config.defaultTool ?? "pointer",
+	cursor: "default"
+});
+const interactionReducer = (state, action) => {
+	switch (action.type) {
+		case "SET_TOOL": return state.activeToolId === action.toolId ? state : {
+			...state,
+			activeToolId: action.toolId
+		};
+		case "SET_CURSOR": return state.cursor === action.cursor ? state : {
+			...state,
+			cursor: action.cursor
+		};
+		default: return state;
+	}
+};
+//#endregion
+//#region src/types.ts
+const InteractionToken = (0, _embedpdf_core.createCapabilityToken)("interaction");
+/**
+* Resolve a sample against a gesture's HOME page. Page-anchored gestures track
+* the page they started on even when the cursor wanders off it — `s.page`
+* re-resolves per event (a foreign page is a DIFFERENT coordinate frame), so
+* prefer the source's unclamped projection and fall back to the page hit only
+* when it is the same page. Null → this sample can't speak for the home page.
+* Shared by every gesture owner (annotation edit/draw, form placement).
+*/
+const samplePointOn = (s, pon) => s.project?.(pon) ?? (s.page?.pon === pon ? s.page.point : null);
+//#endregion
+//#region src/interaction.plugin.ts
+/**
+* The two built-in tools. Features ADD tools via `registerTool` (a draw tool, a
+* redact tool…). `enables` is the composition seam:
+*   pointer → text selection + annotation editing + annotation marquee selection
+*   pan     → scrolling (contributed by Stage) + annotation editing, NO text select
+*
+* Both carry `form-fill`: filling a form is the RESTING state of a viewer
+* (Acrobat's hand tool fills forms too), so widgets are fill-controls under the
+* default tools and only become geometry-editable under a form-design tool.
+* Both carry `link-nav` for the same reason: links navigate under the default
+* tools (Acrobat behaviour) and only become geometry-editable under the link
+* tool. Tags are opaque to the hub — without the form/link plugins they're inert.
+*/
+const builtinTools = () => [{
+	id: "pointer",
+	cursor: "default",
+	enables: /* @__PURE__ */ new Set([
+		"text-select",
+		"annotation-edit",
+		"annotation-marquee",
+		"form-fill",
+		"link-nav"
+	])
+}, {
+	id: "pan",
+	cursor: "grab",
+	gapCursor: "grab",
+	enables: /* @__PURE__ */ new Set([
+		"scroll",
+		"annotation-edit",
+		"form-fill",
+		"link-nav"
+	])
+}];
+/**
+* The interaction hub plugin — document-scoped, depends on nothing. Every feature
+* plugin (selection, annotation, forms, redaction) `requires` this token; Stage
+* `optional`-ly contributes a scroll handler. Works with `<Stage>` or a standalone
+* `<PageView>` — it only routes page-space pointer samples.
+*/
+const interactionPlugin = (config = {}) => (0, _embedpdf_core.definePlugin)({
+	id: "interaction",
+	token: InteractionToken,
+	scope: "document",
+	initialState: () => initialInteractionState(config),
+	reduce: interactionReducer,
+	capability: (ctx) => createInteractionCapability(ctx, builtinTools())
+});
+//#endregion
+exports.InteractionToken = InteractionToken;
+exports.builtinTools = builtinTools;
+exports.createInteractionCapability = createInteractionCapability;
+exports.initialInteractionState = initialInteractionState;
+exports.interactionPlugin = interactionPlugin;
+exports.interactionReducer = interactionReducer;
+exports.samplePointOn = samplePointOn;
+
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":[],"sources":["../src/capability.ts","../src/reducer.ts","../src/types.ts","../src/interaction.plugin.ts"],"sourcesContent":["import type { PluginContext } from '@embedpdf/core';\nimport type {\n  Cursor,\n  InteractionAction,\n  InteractionCapability,\n  InteractionHandler,\n  InteractionState,\n  Tool,\n  ToolCursorSkin,\n  ToolId,\n} from './types';\n\ninterface Claim {\n  cursor: Cursor;\n  priority: number;\n}\n\n/**\n * The interaction hub. Tools + handlers + the captured-gesture owner + cursor\n * claims live in this closure (runtime registries, not serializable state); the\n * reducer state holds only the active tool id and the resolved cursor, so the UI\n * can react to them. The router (`dispatch`) is the heart: on down, the first\n * eligible handler (by priority) to return true OWNS the gesture; move/up route\n * to it; with no owner, move is hover (cursor feedback).\n *\n * Cursor arbitration, top to bottom: the highest-priority CLAIM (hover feedback\n * — 'move' over an annotation, 'text' over text) → over a page, the tool's\n * declared cursor → over a gap, the tool's `gapCursor` (default the neutral\n * arrow). The winning KEYWORD (claim or base, never gap) is then restyled\n * through the armed tool's skin when it maps that keyword. One resolver, so an\n * image cursor can never shadow hover feedback or outlive the page under the\n * pointer.\n */\nexport function createInteractionCapability(\n  ctx: PluginContext<InteractionState, InteractionAction>,\n  builtinTools: Tool[],\n): InteractionCapability {\n  const tools = new Map<ToolId, Tool>();\n  for (const t of builtinTools) tools.set(t.id, t);\n  const handlers: InteractionHandler[] = [];\n  const claims = new Map<string, Claim>();\n  const cursorSkins = new Map<ToolId, ToolCursorSkin>();\n  const toolCbs = new Set<() => void>();\n  let owner: InteractionHandler | null = null;\n  // Whether the last dispatched sample hit a page — the base cursor only\n  // applies where the tool can act; over gaps it falls back to `gapCursor`.\n  let overPage = false;\n\n  const toolOf = (id: ToolId): Tool =>\n    tools.get(id) ?? { id, cursor: 'default', enables: new Set() };\n  const active = (): Tool => toolOf(ctx.getState().activeToolId);\n\n  const resolveCursor = (): Cursor => {\n    let top: Claim | null = null;\n    for (const c of claims.values()) if (!top || c.priority > top.priority) top = c;\n    const tool = active();\n    const skin = cursorSkins.get(tool.id);\n    // The cursor keeps its MEANING (a keyword — the winning claim's, else the\n    // tool's declared base); the skin may restyle that keyword in the armed\n    // tool's identity (an I-beam + tool icon over text). Unmapped keywords\n    // render as-is — a foreign affordance drops the tool identity — and gaps\n    // resolve before the skin: identity only where the action is possible.\n    if (top) return skin?.[top.cursor] ?? top.cursor;\n    if (!overPage) return tool.gapCursor ?? 'default';\n    return skin?.[tool.cursor] ?? tool.cursor;\n  };\n  const syncCursor = (): void => {\n    const next = resolveCursor();\n    if (next !== ctx.getState().cursor) ctx.dispatch({ type: 'SET_CURSOR', cursor: next });\n  };\n\n  const eligible = (): InteractionHandler[] => {\n    const tool = active();\n    return handlers.filter((h) => h.enabledFor(tool)).sort((a, b) => b.priority - a.priority);\n  };\n\n  return {\n    activeTool: active,\n    activeToolId: () => ctx.getState().activeToolId,\n    cursor: () => ctx.getState().cursor,\n    tools: () => [...tools.values()],\n\n    activateTool: (id) => {\n      if (!tools.has(id)) throw new Error(`[interaction] unknown tool '${id}'`);\n      owner = null;\n      claims.clear(); // drop the previous tool's hover claims; handlers re-claim on next hover\n      ctx.dispatch({ type: 'SET_TOOL', toolId: id });\n      syncCursor();\n      toolCbs.forEach((cb) => cb());\n    },\n\n    onToolChange: (cb) => {\n      toolCbs.add(cb);\n      return () => toolCbs.delete(cb);\n    },\n\n    registerTool: (tool) => {\n      tools.set(tool.id, tool);\n      return () => {\n        tools.delete(tool.id);\n        cursorSkins.delete(tool.id);\n      };\n    },\n\n    setToolCursor: (id, skin) => {\n      if (skin === null) cursorSkins.delete(id);\n      else cursorSkins.set(id, skin);\n      syncCursor();\n    },\n\n    registerHandler: (handler) => {\n      handlers.push(handler);\n      return () => {\n        const i = handlers.indexOf(handler);\n        if (i >= 0) handlers.splice(i, 1);\n        if (owner === handler) owner = null;\n      };\n    },\n\n    setCursor: (token, cursor, priority = 0) => {\n      if (cursor === null) claims.delete(token);\n      else claims.set(token, { cursor, priority });\n      syncCursor();\n    },\n\n    dispatch: (sample) => {\n      const nowOverPage = sample.page != null;\n      if (nowOverPage !== overPage) {\n        overPage = nowOverPage;\n        syncCursor(); // crossing a page edge re-resolves the base cursor\n      }\n      if (sample.phase === 'down') {\n        owner = null;\n        for (const h of eligible()) {\n          if (h.onDown(sample)) {\n            owner = h;\n            break;\n          }\n        }\n      } else if (sample.phase === 'move') {\n        if (owner) owner.onMove?.(sample);\n        else for (const h of eligible()) h.onHover?.(sample);\n      } else {\n        owner?.onUp?.(sample);\n        owner = null;\n      }\n    },\n  };\n}\n","import type { InteractionAction, InteractionConfig, InteractionState } from './types';\n\nexport const initialInteractionState = (config: InteractionConfig): InteractionState => ({\n  activeToolId: config.defaultTool ?? 'pointer',\n  cursor: 'default',\n});\n\nexport const interactionReducer = (\n  state: InteractionState,\n  action: InteractionAction,\n): InteractionState => {\n  switch (action.type) {\n    case 'SET_TOOL':\n      return state.activeToolId === action.toolId\n        ? state\n        : { ...state, activeToolId: action.toolId };\n    case 'SET_CURSOR':\n      return state.cursor === action.cursor ? state : { ...state, cursor: action.cursor };\n    default:\n      return state;\n  }\n};\n","import { createCapabilityToken, type PageObjectNumber } from '@embedpdf/core';\nimport type { PageRotation, Point } from '@embedpdf/core-geometry';\n\nexport type ToolId = string;\nexport type Cursor = string;\n\nexport interface Modifiers {\n  shift: boolean;\n  alt: boolean;\n  ctrl: boolean;\n  meta: boolean;\n}\n\n/**\n * The single active arbiter of what the pointer does. `pan` and `pointer` are\n * built in; features add more (`highlight`, `square`, `redact`…) via\n * `registerTool`. A tool carries no behaviour itself — it turns on capability\n * TAGS that handlers opt into (`enables`), so tools compose features without\n * coupling to them.\n */\nexport interface Tool {\n  id: ToolId;\n  cursor: Cursor;\n  /**\n   * Cursor over the viewport's page GAPS. A tool's cursor answers \"what would\n   * a click do here\" — and most tools act only on pages, so gaps fall back to\n   * the neutral arrow (`'default'`). A tool that works anywhere (pan) declares\n   * its own (`'grab'`). Hover claims still outrank both.\n   */\n  gapCursor?: Cursor;\n  enables: ReadonlySet<string>;\n}\n\nexport type Phase = 'down' | 'move' | 'up';\n\n/**\n * One normalized pointer event. `viewport` is the source container's px (the pan\n * handler uses the delta). `page` is the resolved page hit — its `pon` + content\n * point (y-down, PDF units, via the page's transform) — present when the pointer\n * is over a page, absent over gaps. A viewport source (Stage) resolves `page` per\n * event (so a drag can cross pages); a per-page source (PageView) always sets it.\n */\nexport interface PointerSample {\n  phase: Phase;\n  viewport: Point;\n  /** `scale` is the hit page's VIEW px per content unit — handlers use it to\n   *  convert screen-px chrome settings into content-space tolerances, so grab\n   *  zones stay screen-constant across zoom. `rotation` is the hit page's TOTAL\n   *  display rotation (document /Rotate + view rotation) — per-event\n   *  environmental context like `scale`, for placement rules that depend on how\n   *  the page is DISPLAYED (an upright stamp). `zoom` is the page's zoom\n   *  RELATIVE to its 100% baseline (`transform.zoom` — dimensionless, 1 =\n   *  Acrobat's 100%), for zoom-relative policies (the `/F` NoZoom exemption);\n   *  distinct from `scale`, which is a units conversion. Absent when the\n   *  source can't say. */\n  page?: {\n    pon: PageObjectNumber;\n    point: Point;\n    scale?: number;\n    rotation?: PageRotation;\n    zoom?: number;\n  };\n  modifiers: Modifiers;\n  /**\n   * Click count for a `down` (1 = single, 2 = double, 3 = triple), from the\n   * browser's native multi-click detection (`MouseEvent.detail`). Lets handlers\n   * do word/line selection without re-implementing timing. Defaults to 1.\n   */\n  clickCount?: number;\n  /**\n   * Project this event onto a SPECIFIC page's content space, unclamped — valid\n   * (and expected) outside the page's bounds. `page` answers \"what is under the\n   * cursor\" and re-resolves per event; `project` answers \"where is the cursor\n   * in MY page's frame\" for a gesture anchored to the page it started on (an\n   * annotation drag sliding along the page edge). Null when the source can't\n   * project onto that page (not laid out / a per-page source's foreign page).\n   */\n  project?(pon: PageObjectNumber): Point | null;\n}\n\n/**\n * A pointer handler contributed by a feature plugin. The ONE registration\n * mechanism (replacing v2's registerMode / registerHandlers / registerAlways /\n * enableForMode quartet): a handler declares which tools it's live under and a\n * priority; the hub routes each gesture to the first handler that captures it.\n */\nexport interface InteractionHandler {\n  id: string;\n  /** Higher wins the gesture. */\n  priority: number;\n  /** Usually `tool.enables.has('my-tag')`. */\n  enabledFor(tool: Tool): boolean;\n  /** Return true to CAPTURE: subsequent move/up route here until pointer-up. */\n  onDown(sample: PointerSample): boolean;\n  onMove?(sample: PointerSample): void;\n  onUp?(sample: PointerSample): void;\n  /** Pointer moved with no active gesture — cursor feedback only. */\n  onHover?(sample: PointerSample): void;\n}\n\n/**\n * A tool's runtime cursor skin: \"while THIS tool is armed, keyword X looks\n * like Y.\" Everything cursor-shaped in the hub speaks KEYWORDS — a tool\n * declares its base ('crosshair', 'copy'), hover claims name what is under\n * the pointer ('text' over text, 'move' over an annotation) — and the skin\n * restyles those keywords, typically as image cursors carrying the tool's\n * icon. Applied uniformly to the winning claim and to the declared base, so\n * same keyword = same meaning = same look. Unmapped keywords render as-is (a\n * foreign 'move' over an annotation drops the tool identity), and page gaps\n * are never skinned — the identity appears exactly where the action is\n * possible, and the skin can only restyle where the tool already acts.\n */\nexport type ToolCursorSkin = Record<Cursor, Cursor>;\n\nexport interface InteractionState {\n  activeToolId: ToolId;\n  cursor: Cursor;\n}\n\nexport type InteractionAction =\n  | { type: 'SET_TOOL'; toolId: ToolId }\n  | { type: 'SET_CURSOR'; cursor: Cursor };\n\nexport interface InteractionCapability {\n  // ── selectors ──\n  activeTool(): Tool;\n  activeToolId(): ToolId;\n  cursor(): Cursor;\n  tools(): Tool[];\n  // ── tool intents ──\n  activateTool(id: ToolId): void;\n  /** Fires after the active tool changes — lets a feature react (e.g. a markup\n   *  tool taking over the selection visual). Returns an unsubscribe fn. */\n  onToolChange(cb: () => void): () => void;\n  /**\n   * Reskin a tool's cursor keywords at runtime — how an app gives the armed\n   * tool an image cursor built from its own toolbar icon (`Cursor` is any CSS\n   * cursor string, `url(data:…) x y, crosshair` included). See\n   * {@link ToolCursorSkin} for what the map means. `null` removes the skin.\n   */\n  setToolCursor(id: ToolId, skin: ToolCursorSkin | null): void;\n  // ── registries (return an unregister fn) ──\n  registerTool(tool: Tool): () => void;\n  registerHandler(handler: InteractionHandler): () => void;\n  // ── cursor claim stack (highest priority wins; null clears the token) ──\n  setCursor(token: string, cursor: Cursor | null, priority?: number): void;\n  // ── pointer ingress: the adapter calls this for every normalized event ──\n  dispatch(sample: PointerSample): void;\n}\n\nexport const InteractionToken = createCapabilityToken<InteractionCapability>('interaction');\n\n/**\n * Resolve a sample against a gesture's HOME page. Page-anchored gestures track\n * the page they started on even when the cursor wanders off it — `s.page`\n * re-resolves per event (a foreign page is a DIFFERENT coordinate frame), so\n * prefer the source's unclamped projection and fall back to the page hit only\n * when it is the same page. Null → this sample can't speak for the home page.\n * Shared by every gesture owner (annotation edit/draw, form placement).\n */\nexport const samplePointOn = (s: PointerSample, pon: PageObjectNumber): Point | null =>\n  s.project?.(pon) ?? (s.page?.pon === pon ? s.page.point : null);\n\nexport interface InteractionConfig {\n  /** Tool active when a document opens. Default `'pointer'`. */\n  defaultTool?: ToolId;\n}\n","import { definePlugin } from '@embedpdf/core';\nimport { createInteractionCapability } from './capability';\nimport { initialInteractionState, interactionReducer } from './reducer';\nimport { InteractionToken } from './types';\nimport type {\n  InteractionAction,\n  InteractionCapability,\n  InteractionConfig,\n  InteractionState,\n  Tool,\n} from './types';\n\n/**\n * The two built-in tools. Features ADD tools via `registerTool` (a draw tool, a\n * redact tool…). `enables` is the composition seam:\n *   pointer → text selection + annotation editing + annotation marquee selection\n *   pan     → scrolling (contributed by Stage) + annotation editing, NO text select\n *\n * Both carry `form-fill`: filling a form is the RESTING state of a viewer\n * (Acrobat's hand tool fills forms too), so widgets are fill-controls under the\n * default tools and only become geometry-editable under a form-design tool.\n * Both carry `link-nav` for the same reason: links navigate under the default\n * tools (Acrobat behaviour) and only become geometry-editable under the link\n * tool. Tags are opaque to the hub — without the form/link plugins they're inert.\n */\nexport const builtinTools = (): Tool[] => [\n  {\n    id: 'pointer',\n    cursor: 'default',\n    enables: new Set([\n      'text-select',\n      'annotation-edit',\n      'annotation-marquee',\n      'form-fill',\n      'link-nav',\n    ]),\n  },\n  {\n    id: 'pan',\n    cursor: 'grab',\n    gapCursor: 'grab', // pan works anywhere — the open hand doesn't stop at page edges\n    enables: new Set(['scroll', 'annotation-edit', 'form-fill', 'link-nav']),\n  },\n];\n\n/**\n * The interaction hub plugin — document-scoped, depends on nothing. Every feature\n * plugin (selection, annotation, forms, redaction) `requires` this token; Stage\n * `optional`-ly contributes a scroll handler. Works with `<Stage>` or a standalone\n * `<PageView>` — it only routes page-space pointer samples.\n */\nexport const interactionPlugin = (config: InteractionConfig = {}) =>\n  definePlugin<InteractionState, InteractionAction, InteractionCapability>({\n    id: 'interaction',\n    token: InteractionToken,\n    scope: 'document',\n    initialState: () => initialInteractionState(config),\n    reduce: interactionReducer,\n    capability: (ctx) => createInteractionCapability(ctx, builtinTools()),\n  });\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAiCA,SAAgB,4BACd,KACA,cACuB;CACvB,MAAM,wBAAQ,IAAI,IAAkB;CACpC,KAAK,MAAM,KAAK,cAAc,MAAM,IAAI,EAAE,IAAI,CAAC;CAC/C,MAAM,WAAiC,CAAC;CACxC,MAAM,yBAAS,IAAI,IAAmB;CACtC,MAAM,8BAAc,IAAI,IAA4B;CACpD,MAAM,0BAAU,IAAI,IAAgB;CACpC,IAAI,QAAmC;CAGvC,IAAI,WAAW;CAEf,MAAM,UAAU,OACd,MAAM,IAAI,EAAE,KAAK;EAAE;EAAI,QAAQ;EAAW,yBAAS,IAAI,IAAI;CAAE;CAC/D,MAAM,eAAqB,OAAO,IAAI,SAAS,CAAC,CAAC,YAAY;CAE7D,MAAM,sBAA8B;EAClC,IAAI,MAAoB;EACxB,KAAK,MAAM,KAAK,OAAO,OAAO,GAAG,IAAI,CAAC,OAAO,EAAE,WAAW,IAAI,UAAU,MAAM;EAC9E,MAAM,OAAO,OAAO;EACpB,MAAM,OAAO,YAAY,IAAI,KAAK,EAAE;EAMpC,IAAI,KAAK,OAAO,OAAO,IAAI,WAAW,IAAI;EAC1C,IAAI,CAAC,UAAU,OAAO,KAAK,aAAa;EACxC,OAAO,OAAO,KAAK,WAAW,KAAK;CACrC;CACA,MAAM,mBAAyB;EAC7B,MAAM,OAAO,cAAc;EAC3B,IAAI,SAAS,IAAI,SAAS,CAAC,CAAC,QAAQ,IAAI,SAAS;GAAE,MAAM;GAAc,QAAQ;EAAK,CAAC;CACvF;CAEA,MAAM,iBAAuC;EAC3C,MAAM,OAAO,OAAO;EACpB,OAAO,SAAS,QAAQ,MAAM,EAAE,WAAW,IAAI,CAAC,CAAC,CAAC,MAAM,GAAG,MAAM,EAAE,WAAW,EAAE,QAAQ;CAC1F;CAEA,OAAO;EACL,YAAY;EACZ,oBAAoB,IAAI,SAAS,CAAC,CAAC;EACnC,cAAc,IAAI,SAAS,CAAC,CAAC;EAC7B,aAAa,CAAC,GAAG,MAAM,OAAO,CAAC;EAE/B,eAAe,OAAO;GACpB,IAAI,CAAC,MAAM,IAAI,EAAE,GAAG,MAAM,IAAI,MAAM,+BAA+B,GAAG,EAAE;GACxE,QAAQ;GACR,OAAO,MAAM;GACb,IAAI,SAAS;IAAE,MAAM;IAAY,QAAQ;GAAG,CAAC;GAC7C,WAAW;GACX,QAAQ,SAAS,OAAO,GAAG,CAAC;EAC9B;EAEA,eAAe,OAAO;GACpB,QAAQ,IAAI,EAAE;GACd,aAAa,QAAQ,OAAO,EAAE;EAChC;EAEA,eAAe,SAAS;GACtB,MAAM,IAAI,KAAK,IAAI,IAAI;GACvB,aAAa;IACX,MAAM,OAAO,KAAK,EAAE;IACpB,YAAY,OAAO,KAAK,EAAE;GAC5B;EACF;EAEA,gBAAgB,IAAI,SAAS;GAC3B,IAAI,SAAS,MAAM,YAAY,OAAO,EAAE;QACnC,YAAY,IAAI,IAAI,IAAI;GAC7B,WAAW;EACb;EAEA,kBAAkB,YAAY;GAC5B,SAAS,KAAK,OAAO;GACrB,aAAa;IACX,MAAM,IAAI,SAAS,QAAQ,OAAO;IAClC,IAAI,KAAK,GAAG,SAAS,OAAO,GAAG,CAAC;IAChC,IAAI,UAAU,SAAS,QAAQ;GACjC;EACF;EAEA,YAAY,OAAO,QAAQ,WAAW,MAAM;GAC1C,IAAI,WAAW,MAAM,OAAO,OAAO,KAAK;QACnC,OAAO,IAAI,OAAO;IAAE;IAAQ;GAAS,CAAC;GAC3C,WAAW;EACb;EAEA,WAAW,WAAW;GACpB,MAAM,cAAc,OAAO,QAAQ;GACnC,IAAI,gBAAgB,UAAU;IAC5B,WAAW;IACX,WAAW;GACb;GACA,IAAI,OAAO,UAAU,QAAQ;IAC3B,QAAQ;IACR,KAAK,MAAM,KAAK,SAAS,GACvB,IAAI,EAAE,OAAO,MAAM,GAAG;KACpB,QAAQ;KACR;IACF;GAEJ,OAAO,IAAI,OAAO,UAAU,QAC1B,IAAI,OAAO,MAAM,SAAS,MAAM;QAC3B,KAAK,MAAM,KAAK,SAAS,GAAG,EAAE,UAAU,MAAM;QAC9C;IACL,OAAO,OAAO,MAAM;IACpB,QAAQ;GACV;EACF;CACF;AACF;;;AClJA,MAAa,2BAA2B,YAAiD;CACvF,cAAc,OAAO,eAAe;CACpC,QAAQ;AACV;AAEA,MAAa,sBACX,OACA,WACqB;CACrB,QAAQ,OAAO,MAAf;EACE,KAAK,YACH,OAAO,MAAM,iBAAiB,OAAO,SACjC,QACA;GAAE,GAAG;GAAO,cAAc,OAAO;EAAO;EAC9C,KAAK,cACH,OAAO,MAAM,WAAW,OAAO,SAAS,QAAQ;GAAE,GAAG;GAAO,QAAQ,OAAO;EAAO;EACpF,SACE,OAAO;CACX;AACF;;;ACiIA,MAAa,oBAAA,GAAA,eAAA,sBAAA,CAAgE,aAAa;;;;;;;;;AAU1F,MAAa,iBAAiB,GAAkB,QAC9C,EAAE,UAAU,GAAG,MAAM,EAAE,MAAM,QAAQ,MAAM,EAAE,KAAK,QAAQ;;;;;;;;;;;;;;;;ACxI5D,MAAa,qBAA6B,CACxC;CACE,IAAI;CACJ,QAAQ;CACR,yBAAS,IAAI,IAAI;EACf;EACA;EACA;EACA;EACA;CACF,CAAC;AACH,GACA;CACE,IAAI;CACJ,QAAQ;CACR,WAAW;CACX,yBAAS,IAAI,IAAI;EAAC;EAAU;EAAmB;EAAa;CAAU,CAAC;AACzE,CACF;;;;;;;AAQA,MAAa,qBAAqB,SAA4B,CAAC,OAAA,GAAA,eAAA,aAAA,CACY;CACvE,IAAI;CACJ,OAAO;CACP,OAAO;CACP,oBAAoB,wBAAwB,MAAM;CAClD,QAAQ;CACR,aAAa,QAAQ,4BAA4B,KAAK,aAAa,CAAC;AACtE,CAAC"}

package/dist/index.d.cts

@@ -0,0 +1,202 @@
+import { PageObjectNumber, PluginContext } from "@embedpdf/core";
+import { PageRotation, Point } from "@embedpdf/core-geometry";
+//#region src/types.d.ts
+type ToolId = string;
+type Cursor = string;
+interface Modifiers {
+  shift: boolean;
+  alt: boolean;
+  ctrl: boolean;
+  meta: boolean;
+}
+/**
+ * The single active arbiter of what the pointer does. `pan` and `pointer` are
+ * built in; features add more (`highlight`, `square`, `redact`…) via
+ * `registerTool`. A tool carries no behaviour itself — it turns on capability
+ * TAGS that handlers opt into (`enables`), so tools compose features without
+ * coupling to them.
+ */
+interface Tool {
+  id: ToolId;
+  cursor: Cursor;
+  /**
+   * Cursor over the viewport's page GAPS. A tool's cursor answers "what would
+   * a click do here" — and most tools act only on pages, so gaps fall back to
+   * the neutral arrow (`'default'`). A tool that works anywhere (pan) declares
+   * its own (`'grab'`). Hover claims still outrank both.
+   */
+  gapCursor?: Cursor;
+  enables: ReadonlySet<string>;
+}
+type Phase = 'down' | 'move' | 'up';
+/**
+ * One normalized pointer event. `viewport` is the source container's px (the pan
+ * handler uses the delta). `page` is the resolved page hit — its `pon` + content
+ * point (y-down, PDF units, via the page's transform) — present when the pointer
+ * is over a page, absent over gaps. A viewport source (Stage) resolves `page` per
+ * event (so a drag can cross pages); a per-page source (PageView) always sets it.
+ */
+interface PointerSample {
+  phase: Phase;
+  viewport: Point;
+  /** `scale` is the hit page's VIEW px per content unit — handlers use it to
+   *  convert screen-px chrome settings into content-space tolerances, so grab
+   *  zones stay screen-constant across zoom. `rotation` is the hit page's TOTAL
+   *  display rotation (document /Rotate + view rotation) — per-event
+   *  environmental context like `scale`, for placement rules that depend on how
+   *  the page is DISPLAYED (an upright stamp). `zoom` is the page's zoom
+   *  RELATIVE to its 100% baseline (`transform.zoom` — dimensionless, 1 =
+   *  Acrobat's 100%), for zoom-relative policies (the `/F` NoZoom exemption);
+   *  distinct from `scale`, which is a units conversion. Absent when the
+   *  source can't say. */
+  page?: {
+    pon: PageObjectNumber;
+    point: Point;
+    scale?: number;
+    rotation?: PageRotation;
+    zoom?: number;
+  };
+  modifiers: Modifiers;
+  /**
+   * Click count for a `down` (1 = single, 2 = double, 3 = triple), from the
+   * browser's native multi-click detection (`MouseEvent.detail`). Lets handlers
+   * do word/line selection without re-implementing timing. Defaults to 1.
+   */
+  clickCount?: number;
+  /**
+   * Project this event onto a SPECIFIC page's content space, unclamped — valid
+   * (and expected) outside the page's bounds. `page` answers "what is under the
+   * cursor" and re-resolves per event; `project` answers "where is the cursor
+   * in MY page's frame" for a gesture anchored to the page it started on (an
+   * annotation drag sliding along the page edge). Null when the source can't
+   * project onto that page (not laid out / a per-page source's foreign page).
+   */
+  project?(pon: PageObjectNumber): Point | null;
+}
+/**
+ * A pointer handler contributed by a feature plugin. The ONE registration
+ * mechanism (replacing v2's registerMode / registerHandlers / registerAlways /
+ * enableForMode quartet): a handler declares which tools it's live under and a
+ * priority; the hub routes each gesture to the first handler that captures it.
+ */
+interface InteractionHandler {
+  id: string;
+  /** Higher wins the gesture. */
+  priority: number;
+  /** Usually `tool.enables.has('my-tag')`. */
+  enabledFor(tool: Tool): boolean;
+  /** Return true to CAPTURE: subsequent move/up route here until pointer-up. */
+  onDown(sample: PointerSample): boolean;
+  onMove?(sample: PointerSample): void;
+  onUp?(sample: PointerSample): void;
+  /** Pointer moved with no active gesture — cursor feedback only. */
+  onHover?(sample: PointerSample): void;
+}
+/**
+ * A tool's runtime cursor skin: "while THIS tool is armed, keyword X looks
+ * like Y." Everything cursor-shaped in the hub speaks KEYWORDS — a tool
+ * declares its base ('crosshair', 'copy'), hover claims name what is under
+ * the pointer ('text' over text, 'move' over an annotation) — and the skin
+ * restyles those keywords, typically as image cursors carrying the tool's
+ * icon. Applied uniformly to the winning claim and to the declared base, so
+ * same keyword = same meaning = same look. Unmapped keywords render as-is (a
+ * foreign 'move' over an annotation drops the tool identity), and page gaps
+ * are never skinned — the identity appears exactly where the action is
+ * possible, and the skin can only restyle where the tool already acts.
+ */
+type ToolCursorSkin = Record<Cursor, Cursor>;
+interface InteractionState {
+  activeToolId: ToolId;
+  cursor: Cursor;
+}
+type InteractionAction = {
+  type: 'SET_TOOL';
+  toolId: ToolId;
+} | {
+  type: 'SET_CURSOR';
+  cursor: Cursor;
+};
+interface InteractionCapability {
+  activeTool(): Tool;
+  activeToolId(): ToolId;
+  cursor(): Cursor;
+  tools(): Tool[];
+  activateTool(id: ToolId): void;
+  /** Fires after the active tool changes — lets a feature react (e.g. a markup
+   *  tool taking over the selection visual). Returns an unsubscribe fn. */
+  onToolChange(cb: () => void): () => void;
+  /**
+   * Reskin a tool's cursor keywords at runtime — how an app gives the armed
+   * tool an image cursor built from its own toolbar icon (`Cursor` is any CSS
+   * cursor string, `url(data:…) x y, crosshair` included). See
+   * {@link ToolCursorSkin} for what the map means. `null` removes the skin.
+   */
+  setToolCursor(id: ToolId, skin: ToolCursorSkin | null): void;
+  registerTool(tool: Tool): () => void;
+  registerHandler(handler: InteractionHandler): () => void;
+  setCursor(token: string, cursor: Cursor | null, priority?: number): void;
+  dispatch(sample: PointerSample): void;
+}
+declare const InteractionToken: import("@embedpdf/core").CapabilityToken<InteractionCapability>;
+/**
+ * Resolve a sample against a gesture's HOME page. Page-anchored gestures track
+ * the page they started on even when the cursor wanders off it — `s.page`
+ * re-resolves per event (a foreign page is a DIFFERENT coordinate frame), so
+ * prefer the source's unclamped projection and fall back to the page hit only
+ * when it is the same page. Null → this sample can't speak for the home page.
+ * Shared by every gesture owner (annotation edit/draw, form placement).
+ */
+declare const samplePointOn: (s: PointerSample, pon: PageObjectNumber) => Point | null;
+interface InteractionConfig {
+  /** Tool active when a document opens. Default `'pointer'`. */
+  defaultTool?: ToolId;
+}
+//#endregion
+//#region src/interaction.plugin.d.ts
+/**
+ * The two built-in tools. Features ADD tools via `registerTool` (a draw tool, a
+ * redact tool…). `enables` is the composition seam:
+ *   pointer → text selection + annotation editing + annotation marquee selection
+ *   pan     → scrolling (contributed by Stage) + annotation editing, NO text select
+ *
+ * Both carry `form-fill`: filling a form is the RESTING state of a viewer
+ * (Acrobat's hand tool fills forms too), so widgets are fill-controls under the
+ * default tools and only become geometry-editable under a form-design tool.
+ * Both carry `link-nav` for the same reason: links navigate under the default
+ * tools (Acrobat behaviour) and only become geometry-editable under the link
+ * tool. Tags are opaque to the hub — without the form/link plugins they're inert.
+ */
+declare const builtinTools: () => Tool[];
+/**
+ * The interaction hub plugin — document-scoped, depends on nothing. Every feature
+ * plugin (selection, annotation, forms, redaction) `requires` this token; Stage
+ * `optional`-ly contributes a scroll handler. Works with `<Stage>` or a standalone
+ * `<PageView>` — it only routes page-space pointer samples.
+ */
+declare const interactionPlugin: (config?: InteractionConfig) => import("@embedpdf/core").PluginDef<InteractionState, InteractionAction, InteractionCapability>;
+//#endregion
+//#region src/capability.d.ts
+/**
+ * The interaction hub. Tools + handlers + the captured-gesture owner + cursor
+ * claims live in this closure (runtime registries, not serializable state); the
+ * reducer state holds only the active tool id and the resolved cursor, so the UI
+ * can react to them. The router (`dispatch`) is the heart: on down, the first
+ * eligible handler (by priority) to return true OWNS the gesture; move/up route
+ * to it; with no owner, move is hover (cursor feedback).
+ *
+ * Cursor arbitration, top to bottom: the highest-priority CLAIM (hover feedback
+ * — 'move' over an annotation, 'text' over text) → over a page, the tool's
+ * declared cursor → over a gap, the tool's `gapCursor` (default the neutral
+ * arrow). The winning KEYWORD (claim or base, never gap) is then restyled
+ * through the armed tool's skin when it maps that keyword. One resolver, so an
+ * image cursor can never shadow hover feedback or outlive the page under the
+ * pointer.
+ */
+declare function createInteractionCapability(ctx: PluginContext<InteractionState, InteractionAction>, builtinTools: Tool[]): InteractionCapability;
+//#endregion
+//#region src/reducer.d.ts
+declare const initialInteractionState: (config: InteractionConfig) => InteractionState;
+declare const interactionReducer: (state: InteractionState, action: InteractionAction) => InteractionState;
+//#endregion
+export { type Cursor, type InteractionAction, type InteractionCapability, type InteractionConfig, type InteractionHandler, type InteractionState, InteractionToken, type Modifiers, type Phase, type PointerSample, type Tool, type ToolId, builtinTools, createInteractionCapability, initialInteractionState, interactionPlugin, interactionReducer, samplePointOn };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -0,0 +1,202 @@
+import { PageObjectNumber, PluginContext } from "@embedpdf/core";
+import { PageRotation, Point } from "@embedpdf/core-geometry";
+//#region src/types.d.ts
+type ToolId = string;
+type Cursor = string;
+interface Modifiers {
+  shift: boolean;
+  alt: boolean;
+  ctrl: boolean;
+  meta: boolean;
+}
+/**
+ * The single active arbiter of what the pointer does. `pan` and `pointer` are
+ * built in; features add more (`highlight`, `square`, `redact`…) via
+ * `registerTool`. A tool carries no behaviour itself — it turns on capability
+ * TAGS that handlers opt into (`enables`), so tools compose features without
+ * coupling to them.
+ */
+interface Tool {
+  id: ToolId;
+  cursor: Cursor;
+  /**
+   * Cursor over the viewport's page GAPS. A tool's cursor answers "what would
+   * a click do here" — and most tools act only on pages, so gaps fall back to
+   * the neutral arrow (`'default'`). A tool that works anywhere (pan) declares
+   * its own (`'grab'`). Hover claims still outrank both.
+   */
+  gapCursor?: Cursor;
+  enables: ReadonlySet<string>;
+}
+type Phase = 'down' | 'move' | 'up';
+/**
+ * One normalized pointer event. `viewport` is the source container's px (the pan
+ * handler uses the delta). `page` is the resolved page hit — its `pon` + content
+ * point (y-down, PDF units, via the page's transform) — present when the pointer
+ * is over a page, absent over gaps. A viewport source (Stage) resolves `page` per
+ * event (so a drag can cross pages); a per-page source (PageView) always sets it.
+ */
+interface PointerSample {
+  phase: Phase;
+  viewport: Point;
+  /** `scale` is the hit page's VIEW px per content unit — handlers use it to
+   *  convert screen-px chrome settings into content-space tolerances, so grab
+   *  zones stay screen-constant across zoom. `rotation` is the hit page's TOTAL
+   *  display rotation (document /Rotate + view rotation) — per-event
+   *  environmental context like `scale`, for placement rules that depend on how
+   *  the page is DISPLAYED (an upright stamp). `zoom` is the page's zoom
+   *  RELATIVE to its 100% baseline (`transform.zoom` — dimensionless, 1 =
+   *  Acrobat's 100%), for zoom-relative policies (the `/F` NoZoom exemption);
+   *  distinct from `scale`, which is a units conversion. Absent when the
+   *  source can't say. */
+  page?: {
+    pon: PageObjectNumber;
+    point: Point;
+    scale?: number;
+    rotation?: PageRotation;
+    zoom?: number;
+  };
+  modifiers: Modifiers;
+  /**
+   * Click count for a `down` (1 = single, 2 = double, 3 = triple), from the
+   * browser's native multi-click detection (`MouseEvent.detail`). Lets handlers
+   * do word/line selection without re-implementing timing. Defaults to 1.
+   */
+  clickCount?: number;
+  /**
+   * Project this event onto a SPECIFIC page's content space, unclamped — valid
+   * (and expected) outside the page's bounds. `page` answers "what is under the
+   * cursor" and re-resolves per event; `project` answers "where is the cursor
+   * in MY page's frame" for a gesture anchored to the page it started on (an
+   * annotation drag sliding along the page edge). Null when the source can't
+   * project onto that page (not laid out / a per-page source's foreign page).
+   */
+  project?(pon: PageObjectNumber): Point | null;
+}
+/**
+ * A pointer handler contributed by a feature plugin. The ONE registration
+ * mechanism (replacing v2's registerMode / registerHandlers / registerAlways /
+ * enableForMode quartet): a handler declares which tools it's live under and a
+ * priority; the hub routes each gesture to the first handler that captures it.
+ */
+interface InteractionHandler {
+  id: string;
+  /** Higher wins the gesture. */
+  priority: number;
+  /** Usually `tool.enables.has('my-tag')`. */
+  enabledFor(tool: Tool): boolean;
+  /** Return true to CAPTURE: subsequent move/up route here until pointer-up. */
+  onDown(sample: PointerSample): boolean;
+  onMove?(sample: PointerSample): void;
+  onUp?(sample: PointerSample): void;
+  /** Pointer moved with no active gesture — cursor feedback only. */
+  onHover?(sample: PointerSample): void;
+}
+/**
+ * A tool's runtime cursor skin: "while THIS tool is armed, keyword X looks
+ * like Y." Everything cursor-shaped in the hub speaks KEYWORDS — a tool
+ * declares its base ('crosshair', 'copy'), hover claims name what is under
+ * the pointer ('text' over text, 'move' over an annotation) — and the skin
+ * restyles those keywords, typically as image cursors carrying the tool's
+ * icon. Applied uniformly to the winning claim and to the declared base, so
+ * same keyword = same meaning = same look. Unmapped keywords render as-is (a
+ * foreign 'move' over an annotation drops the tool identity), and page gaps
+ * are never skinned — the identity appears exactly where the action is
+ * possible, and the skin can only restyle where the tool already acts.
+ */
+type ToolCursorSkin = Record<Cursor, Cursor>;
+interface InteractionState {
+  activeToolId: ToolId;
+  cursor: Cursor;
+}
+type InteractionAction = {
+  type: 'SET_TOOL';
+  toolId: ToolId;
+} | {
+  type: 'SET_CURSOR';
+  cursor: Cursor;
+};
+interface InteractionCapability {
+  activeTool(): Tool;
+  activeToolId(): ToolId;
+  cursor(): Cursor;
+  tools(): Tool[];
+  activateTool(id: ToolId): void;
+  /** Fires after the active tool changes — lets a feature react (e.g. a markup
+   *  tool taking over the selection visual). Returns an unsubscribe fn. */
+  onToolChange(cb: () => void): () => void;
+  /**
+   * Reskin a tool's cursor keywords at runtime — how an app gives the armed
+   * tool an image cursor built from its own toolbar icon (`Cursor` is any CSS
+   * cursor string, `url(data:…) x y, crosshair` included). See
+   * {@link ToolCursorSkin} for what the map means. `null` removes the skin.
+   */
+  setToolCursor(id: ToolId, skin: ToolCursorSkin | null): void;
+  registerTool(tool: Tool): () => void;
+  registerHandler(handler: InteractionHandler): () => void;
+  setCursor(token: string, cursor: Cursor | null, priority?: number): void;
+  dispatch(sample: PointerSample): void;
+}
+declare const InteractionToken: import("@embedpdf/core").CapabilityToken<InteractionCapability>;
+/**
+ * Resolve a sample against a gesture's HOME page. Page-anchored gestures track
+ * the page they started on even when the cursor wanders off it — `s.page`
+ * re-resolves per event (a foreign page is a DIFFERENT coordinate frame), so
+ * prefer the source's unclamped projection and fall back to the page hit only
+ * when it is the same page. Null → this sample can't speak for the home page.
+ * Shared by every gesture owner (annotation edit/draw, form placement).
+ */
+declare const samplePointOn: (s: PointerSample, pon: PageObjectNumber) => Point | null;
+interface InteractionConfig {
+  /** Tool active when a document opens. Default `'pointer'`. */
+  defaultTool?: ToolId;
+}
+//#endregion
+//#region src/interaction.plugin.d.ts
+/**
+ * The two built-in tools. Features ADD tools via `registerTool` (a draw tool, a
+ * redact tool…). `enables` is the composition seam:
+ *   pointer → text selection + annotation editing + annotation marquee selection
+ *   pan     → scrolling (contributed by Stage) + annotation editing, NO text select
+ *
+ * Both carry `form-fill`: filling a form is the RESTING state of a viewer
+ * (Acrobat's hand tool fills forms too), so widgets are fill-controls under the
+ * default tools and only become geometry-editable under a form-design tool.
+ * Both carry `link-nav` for the same reason: links navigate under the default
+ * tools (Acrobat behaviour) and only become geometry-editable under the link
+ * tool. Tags are opaque to the hub — without the form/link plugins they're inert.
+ */
+declare const builtinTools: () => Tool[];
+/**
+ * The interaction hub plugin — document-scoped, depends on nothing. Every feature
+ * plugin (selection, annotation, forms, redaction) `requires` this token; Stage
+ * `optional`-ly contributes a scroll handler. Works with `<Stage>` or a standalone
+ * `<PageView>` — it only routes page-space pointer samples.
+ */
+declare const interactionPlugin: (config?: InteractionConfig) => import("@embedpdf/core").PluginDef<InteractionState, InteractionAction, InteractionCapability>;
+//#endregion
+//#region src/capability.d.ts
+/**
+ * The interaction hub. Tools + handlers + the captured-gesture owner + cursor
+ * claims live in this closure (runtime registries, not serializable state); the
+ * reducer state holds only the active tool id and the resolved cursor, so the UI
+ * can react to them. The router (`dispatch`) is the heart: on down, the first
+ * eligible handler (by priority) to return true OWNS the gesture; move/up route
+ * to it; with no owner, move is hover (cursor feedback).
+ *
+ * Cursor arbitration, top to bottom: the highest-priority CLAIM (hover feedback
+ * — 'move' over an annotation, 'text' over text) → over a page, the tool's
+ * declared cursor → over a gap, the tool's `gapCursor` (default the neutral
+ * arrow). The winning KEYWORD (claim or base, never gap) is then restyled
+ * through the armed tool's skin when it maps that keyword. One resolver, so an
+ * image cursor can never shadow hover feedback or outlive the page under the
+ * pointer.
+ */
+declare function createInteractionCapability(ctx: PluginContext<InteractionState, InteractionAction>, builtinTools: Tool[]): InteractionCapability;
+//#endregion
+//#region src/reducer.d.ts
+declare const initialInteractionState: (config: InteractionConfig) => InteractionState;
+declare const interactionReducer: (state: InteractionState, action: InteractionAction) => InteractionState;
+//#endregion
+export { type Cursor, type InteractionAction, type InteractionCapability, type InteractionConfig, type InteractionHandler, type InteractionState, InteractionToken, type Modifiers, type Phase, type PointerSample, type Tool, type ToolId, builtinTools, createInteractionCapability, initialInteractionState, interactionPlugin, interactionReducer, samplePointOn };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,207 @@
+import { createCapabilityToken, definePlugin } from "@embedpdf/core";
+//#region src/capability.ts
+/**
+* The interaction hub. Tools + handlers + the captured-gesture owner + cursor
+* claims live in this closure (runtime registries, not serializable state); the
+* reducer state holds only the active tool id and the resolved cursor, so the UI
+* can react to them. The router (`dispatch`) is the heart: on down, the first
+* eligible handler (by priority) to return true OWNS the gesture; move/up route
+* to it; with no owner, move is hover (cursor feedback).
+*
+* Cursor arbitration, top to bottom: the highest-priority CLAIM (hover feedback
+* — 'move' over an annotation, 'text' over text) → over a page, the tool's
+* declared cursor → over a gap, the tool's `gapCursor` (default the neutral
+* arrow). The winning KEYWORD (claim or base, never gap) is then restyled
+* through the armed tool's skin when it maps that keyword. One resolver, so an
+* image cursor can never shadow hover feedback or outlive the page under the
+* pointer.
+*/
+function createInteractionCapability(ctx, builtinTools) {
+	const tools = /* @__PURE__ */ new Map();
+	for (const t of builtinTools) tools.set(t.id, t);
+	const handlers = [];
+	const claims = /* @__PURE__ */ new Map();
+	const cursorSkins = /* @__PURE__ */ new Map();
+	const toolCbs = /* @__PURE__ */ new Set();
+	let owner = null;
+	let overPage = false;
+	const toolOf = (id) => tools.get(id) ?? {
+		id,
+		cursor: "default",
+		enables: /* @__PURE__ */ new Set()
+	};
+	const active = () => toolOf(ctx.getState().activeToolId);
+	const resolveCursor = () => {
+		let top = null;
+		for (const c of claims.values()) if (!top || c.priority > top.priority) top = c;
+		const tool = active();
+		const skin = cursorSkins.get(tool.id);
+		if (top) return skin?.[top.cursor] ?? top.cursor;
+		if (!overPage) return tool.gapCursor ?? "default";
+		return skin?.[tool.cursor] ?? tool.cursor;
+	};
+	const syncCursor = () => {
+		const next = resolveCursor();
+		if (next !== ctx.getState().cursor) ctx.dispatch({
+			type: "SET_CURSOR",
+			cursor: next
+		});
+	};
+	const eligible = () => {
+		const tool = active();
+		return handlers.filter((h) => h.enabledFor(tool)).sort((a, b) => b.priority - a.priority);
+	};
+	return {
+		activeTool: active,
+		activeToolId: () => ctx.getState().activeToolId,
+		cursor: () => ctx.getState().cursor,
+		tools: () => [...tools.values()],
+		activateTool: (id) => {
+			if (!tools.has(id)) throw new Error(`[interaction] unknown tool '${id}'`);
+			owner = null;
+			claims.clear();
+			ctx.dispatch({
+				type: "SET_TOOL",
+				toolId: id
+			});
+			syncCursor();
+			toolCbs.forEach((cb) => cb());
+		},
+		onToolChange: (cb) => {
+			toolCbs.add(cb);
+			return () => toolCbs.delete(cb);
+		},
+		registerTool: (tool) => {
+			tools.set(tool.id, tool);
+			return () => {
+				tools.delete(tool.id);
+				cursorSkins.delete(tool.id);
+			};
+		},
+		setToolCursor: (id, skin) => {
+			if (skin === null) cursorSkins.delete(id);
+			else cursorSkins.set(id, skin);
+			syncCursor();
+		},
+		registerHandler: (handler) => {
+			handlers.push(handler);
+			return () => {
+				const i = handlers.indexOf(handler);
+				if (i >= 0) handlers.splice(i, 1);
+				if (owner === handler) owner = null;
+			};
+		},
+		setCursor: (token, cursor, priority = 0) => {
+			if (cursor === null) claims.delete(token);
+			else claims.set(token, {
+				cursor,
+				priority
+			});
+			syncCursor();
+		},
+		dispatch: (sample) => {
+			const nowOverPage = sample.page != null;
+			if (nowOverPage !== overPage) {
+				overPage = nowOverPage;
+				syncCursor();
+			}
+			if (sample.phase === "down") {
+				owner = null;
+				for (const h of eligible()) if (h.onDown(sample)) {
+					owner = h;
+					break;
+				}
+			} else if (sample.phase === "move") if (owner) owner.onMove?.(sample);
+			else for (const h of eligible()) h.onHover?.(sample);
+			else {
+				owner?.onUp?.(sample);
+				owner = null;
+			}
+		}
+	};
+}
+//#endregion
+//#region src/reducer.ts
+const initialInteractionState = (config) => ({
+	activeToolId: config.defaultTool ?? "pointer",
+	cursor: "default"
+});
+const interactionReducer = (state, action) => {
+	switch (action.type) {
+		case "SET_TOOL": return state.activeToolId === action.toolId ? state : {
+			...state,
+			activeToolId: action.toolId
+		};
+		case "SET_CURSOR": return state.cursor === action.cursor ? state : {
+			...state,
+			cursor: action.cursor
+		};
+		default: return state;
+	}
+};
+//#endregion
+//#region src/types.ts
+const InteractionToken = createCapabilityToken("interaction");
+/**
+* Resolve a sample against a gesture's HOME page. Page-anchored gestures track
+* the page they started on even when the cursor wanders off it — `s.page`
+* re-resolves per event (a foreign page is a DIFFERENT coordinate frame), so
+* prefer the source's unclamped projection and fall back to the page hit only
+* when it is the same page. Null → this sample can't speak for the home page.
+* Shared by every gesture owner (annotation edit/draw, form placement).
+*/
+const samplePointOn = (s, pon) => s.project?.(pon) ?? (s.page?.pon === pon ? s.page.point : null);
+//#endregion
+//#region src/interaction.plugin.ts
+/**
+* The two built-in tools. Features ADD tools via `registerTool` (a draw tool, a
+* redact tool…). `enables` is the composition seam:
+*   pointer → text selection + annotation editing + annotation marquee selection
+*   pan     → scrolling (contributed by Stage) + annotation editing, NO text select
+*
+* Both carry `form-fill`: filling a form is the RESTING state of a viewer
+* (Acrobat's hand tool fills forms too), so widgets are fill-controls under the
+* default tools and only become geometry-editable under a form-design tool.
+* Both carry `link-nav` for the same reason: links navigate under the default
+* tools (Acrobat behaviour) and only become geometry-editable under the link
+* tool. Tags are opaque to the hub — without the form/link plugins they're inert.
+*/
+const builtinTools = () => [{
+	id: "pointer",
+	cursor: "default",
+	enables: /* @__PURE__ */ new Set([
+		"text-select",
+		"annotation-edit",
+		"annotation-marquee",
+		"form-fill",
+		"link-nav"
+	])
+}, {
+	id: "pan",
+	cursor: "grab",
+	gapCursor: "grab",
+	enables: /* @__PURE__ */ new Set([
+		"scroll",
+		"annotation-edit",
+		"form-fill",
+		"link-nav"
+	])
+}];
+/**
+* The interaction hub plugin — document-scoped, depends on nothing. Every feature
+* plugin (selection, annotation, forms, redaction) `requires` this token; Stage
+* `optional`-ly contributes a scroll handler. Works with `<Stage>` or a standalone
+* `<PageView>` — it only routes page-space pointer samples.
+*/
+const interactionPlugin = (config = {}) => definePlugin({
+	id: "interaction",
+	token: InteractionToken,
+	scope: "document",
+	initialState: () => initialInteractionState(config),
+	reduce: interactionReducer,
+	capability: (ctx) => createInteractionCapability(ctx, builtinTools())
+});
+//#endregion
+export { InteractionToken, builtinTools, createInteractionCapability, initialInteractionState, interactionPlugin, interactionReducer, samplePointOn };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/capability.ts","../src/reducer.ts","../src/types.ts","../src/interaction.plugin.ts"],"sourcesContent":["import type { PluginContext } from '@embedpdf/core';\nimport type {\n  Cursor,\n  InteractionAction,\n  InteractionCapability,\n  InteractionHandler,\n  InteractionState,\n  Tool,\n  ToolCursorSkin,\n  ToolId,\n} from './types';\n\ninterface Claim {\n  cursor: Cursor;\n  priority: number;\n}\n\n/**\n * The interaction hub. Tools + handlers + the captured-gesture owner + cursor\n * claims live in this closure (runtime registries, not serializable state); the\n * reducer state holds only the active tool id and the resolved cursor, so the UI\n * can react to them. The router (`dispatch`) is the heart: on down, the first\n * eligible handler (by priority) to return true OWNS the gesture; move/up route\n * to it; with no owner, move is hover (cursor feedback).\n *\n * Cursor arbitration, top to bottom: the highest-priority CLAIM (hover feedback\n * — 'move' over an annotation, 'text' over text) → over a page, the tool's\n * declared cursor → over a gap, the tool's `gapCursor` (default the neutral\n * arrow). The winning KEYWORD (claim or base, never gap) is then restyled\n * through the armed tool's skin when it maps that keyword. One resolver, so an\n * image cursor can never shadow hover feedback or outlive the page under the\n * pointer.\n */\nexport function createInteractionCapability(\n  ctx: PluginContext<InteractionState, InteractionAction>,\n  builtinTools: Tool[],\n): InteractionCapability {\n  const tools = new Map<ToolId, Tool>();\n  for (const t of builtinTools) tools.set(t.id, t);\n  const handlers: InteractionHandler[] = [];\n  const claims = new Map<string, Claim>();\n  const cursorSkins = new Map<ToolId, ToolCursorSkin>();\n  const toolCbs = new Set<() => void>();\n  let owner: InteractionHandler | null = null;\n  // Whether the last dispatched sample hit a page — the base cursor only\n  // applies where the tool can act; over gaps it falls back to `gapCursor`.\n  let overPage = false;\n\n  const toolOf = (id: ToolId): Tool =>\n    tools.get(id) ?? { id, cursor: 'default', enables: new Set() };\n  const active = (): Tool => toolOf(ctx.getState().activeToolId);\n\n  const resolveCursor = (): Cursor => {\n    let top: Claim | null = null;\n    for (const c of claims.values()) if (!top || c.priority > top.priority) top = c;\n    const tool = active();\n    const skin = cursorSkins.get(tool.id);\n    // The cursor keeps its MEANING (a keyword — the winning claim's, else the\n    // tool's declared base); the skin may restyle that keyword in the armed\n    // tool's identity (an I-beam + tool icon over text). Unmapped keywords\n    // render as-is — a foreign affordance drops the tool identity — and gaps\n    // resolve before the skin: identity only where the action is possible.\n    if (top) return skin?.[top.cursor] ?? top.cursor;\n    if (!overPage) return tool.gapCursor ?? 'default';\n    return skin?.[tool.cursor] ?? tool.cursor;\n  };\n  const syncCursor = (): void => {\n    const next = resolveCursor();\n    if (next !== ctx.getState().cursor) ctx.dispatch({ type: 'SET_CURSOR', cursor: next });\n  };\n\n  const eligible = (): InteractionHandler[] => {\n    const tool = active();\n    return handlers.filter((h) => h.enabledFor(tool)).sort((a, b) => b.priority - a.priority);\n  };\n\n  return {\n    activeTool: active,\n    activeToolId: () => ctx.getState().activeToolId,\n    cursor: () => ctx.getState().cursor,\n    tools: () => [...tools.values()],\n\n    activateTool: (id) => {\n      if (!tools.has(id)) throw new Error(`[interaction] unknown tool '${id}'`);\n      owner = null;\n      claims.clear(); // drop the previous tool's hover claims; handlers re-claim on next hover\n      ctx.dispatch({ type: 'SET_TOOL', toolId: id });\n      syncCursor();\n      toolCbs.forEach((cb) => cb());\n    },\n\n    onToolChange: (cb) => {\n      toolCbs.add(cb);\n      return () => toolCbs.delete(cb);\n    },\n\n    registerTool: (tool) => {\n      tools.set(tool.id, tool);\n      return () => {\n        tools.delete(tool.id);\n        cursorSkins.delete(tool.id);\n      };\n    },\n\n    setToolCursor: (id, skin) => {\n      if (skin === null) cursorSkins.delete(id);\n      else cursorSkins.set(id, skin);\n      syncCursor();\n    },\n\n    registerHandler: (handler) => {\n      handlers.push(handler);\n      return () => {\n        const i = handlers.indexOf(handler);\n        if (i >= 0) handlers.splice(i, 1);\n        if (owner === handler) owner = null;\n      };\n    },\n\n    setCursor: (token, cursor, priority = 0) => {\n      if (cursor === null) claims.delete(token);\n      else claims.set(token, { cursor, priority });\n      syncCursor();\n    },\n\n    dispatch: (sample) => {\n      const nowOverPage = sample.page != null;\n      if (nowOverPage !== overPage) {\n        overPage = nowOverPage;\n        syncCursor(); // crossing a page edge re-resolves the base cursor\n      }\n      if (sample.phase === 'down') {\n        owner = null;\n        for (const h of eligible()) {\n          if (h.onDown(sample)) {\n            owner = h;\n            break;\n          }\n        }\n      } else if (sample.phase === 'move') {\n        if (owner) owner.onMove?.(sample);\n        else for (const h of eligible()) h.onHover?.(sample);\n      } else {\n        owner?.onUp?.(sample);\n        owner = null;\n      }\n    },\n  };\n}\n","import type { InteractionAction, InteractionConfig, InteractionState } from './types';\n\nexport const initialInteractionState = (config: InteractionConfig): InteractionState => ({\n  activeToolId: config.defaultTool ?? 'pointer',\n  cursor: 'default',\n});\n\nexport const interactionReducer = (\n  state: InteractionState,\n  action: InteractionAction,\n): InteractionState => {\n  switch (action.type) {\n    case 'SET_TOOL':\n      return state.activeToolId === action.toolId\n        ? state\n        : { ...state, activeToolId: action.toolId };\n    case 'SET_CURSOR':\n      return state.cursor === action.cursor ? state : { ...state, cursor: action.cursor };\n    default:\n      return state;\n  }\n};\n","import { createCapabilityToken, type PageObjectNumber } from '@embedpdf/core';\nimport type { PageRotation, Point } from '@embedpdf/core-geometry';\n\nexport type ToolId = string;\nexport type Cursor = string;\n\nexport interface Modifiers {\n  shift: boolean;\n  alt: boolean;\n  ctrl: boolean;\n  meta: boolean;\n}\n\n/**\n * The single active arbiter of what the pointer does. `pan` and `pointer` are\n * built in; features add more (`highlight`, `square`, `redact`…) via\n * `registerTool`. A tool carries no behaviour itself — it turns on capability\n * TAGS that handlers opt into (`enables`), so tools compose features without\n * coupling to them.\n */\nexport interface Tool {\n  id: ToolId;\n  cursor: Cursor;\n  /**\n   * Cursor over the viewport's page GAPS. A tool's cursor answers \"what would\n   * a click do here\" — and most tools act only on pages, so gaps fall back to\n   * the neutral arrow (`'default'`). A tool that works anywhere (pan) declares\n   * its own (`'grab'`). Hover claims still outrank both.\n   */\n  gapCursor?: Cursor;\n  enables: ReadonlySet<string>;\n}\n\nexport type Phase = 'down' | 'move' | 'up';\n\n/**\n * One normalized pointer event. `viewport` is the source container's px (the pan\n * handler uses the delta). `page` is the resolved page hit — its `pon` + content\n * point (y-down, PDF units, via the page's transform) — present when the pointer\n * is over a page, absent over gaps. A viewport source (Stage) resolves `page` per\n * event (so a drag can cross pages); a per-page source (PageView) always sets it.\n */\nexport interface PointerSample {\n  phase: Phase;\n  viewport: Point;\n  /** `scale` is the hit page's VIEW px per content unit — handlers use it to\n   *  convert screen-px chrome settings into content-space tolerances, so grab\n   *  zones stay screen-constant across zoom. `rotation` is the hit page's TOTAL\n   *  display rotation (document /Rotate + view rotation) — per-event\n   *  environmental context like `scale`, for placement rules that depend on how\n   *  the page is DISPLAYED (an upright stamp). `zoom` is the page's zoom\n   *  RELATIVE to its 100% baseline (`transform.zoom` — dimensionless, 1 =\n   *  Acrobat's 100%), for zoom-relative policies (the `/F` NoZoom exemption);\n   *  distinct from `scale`, which is a units conversion. Absent when the\n   *  source can't say. */\n  page?: {\n    pon: PageObjectNumber;\n    point: Point;\n    scale?: number;\n    rotation?: PageRotation;\n    zoom?: number;\n  };\n  modifiers: Modifiers;\n  /**\n   * Click count for a `down` (1 = single, 2 = double, 3 = triple), from the\n   * browser's native multi-click detection (`MouseEvent.detail`). Lets handlers\n   * do word/line selection without re-implementing timing. Defaults to 1.\n   */\n  clickCount?: number;\n  /**\n   * Project this event onto a SPECIFIC page's content space, unclamped — valid\n   * (and expected) outside the page's bounds. `page` answers \"what is under the\n   * cursor\" and re-resolves per event; `project` answers \"where is the cursor\n   * in MY page's frame\" for a gesture anchored to the page it started on (an\n   * annotation drag sliding along the page edge). Null when the source can't\n   * project onto that page (not laid out / a per-page source's foreign page).\n   */\n  project?(pon: PageObjectNumber): Point | null;\n}\n\n/**\n * A pointer handler contributed by a feature plugin. The ONE registration\n * mechanism (replacing v2's registerMode / registerHandlers / registerAlways /\n * enableForMode quartet): a handler declares which tools it's live under and a\n * priority; the hub routes each gesture to the first handler that captures it.\n */\nexport interface InteractionHandler {\n  id: string;\n  /** Higher wins the gesture. */\n  priority: number;\n  /** Usually `tool.enables.has('my-tag')`. */\n  enabledFor(tool: Tool): boolean;\n  /** Return true to CAPTURE: subsequent move/up route here until pointer-up. */\n  onDown(sample: PointerSample): boolean;\n  onMove?(sample: PointerSample): void;\n  onUp?(sample: PointerSample): void;\n  /** Pointer moved with no active gesture — cursor feedback only. */\n  onHover?(sample: PointerSample): void;\n}\n\n/**\n * A tool's runtime cursor skin: \"while THIS tool is armed, keyword X looks\n * like Y.\" Everything cursor-shaped in the hub speaks KEYWORDS — a tool\n * declares its base ('crosshair', 'copy'), hover claims name what is under\n * the pointer ('text' over text, 'move' over an annotation) — and the skin\n * restyles those keywords, typically as image cursors carrying the tool's\n * icon. Applied uniformly to the winning claim and to the declared base, so\n * same keyword = same meaning = same look. Unmapped keywords render as-is (a\n * foreign 'move' over an annotation drops the tool identity), and page gaps\n * are never skinned — the identity appears exactly where the action is\n * possible, and the skin can only restyle where the tool already acts.\n */\nexport type ToolCursorSkin = Record<Cursor, Cursor>;\n\nexport interface InteractionState {\n  activeToolId: ToolId;\n  cursor: Cursor;\n}\n\nexport type InteractionAction =\n  | { type: 'SET_TOOL'; toolId: ToolId }\n  | { type: 'SET_CURSOR'; cursor: Cursor };\n\nexport interface InteractionCapability {\n  // ── selectors ──\n  activeTool(): Tool;\n  activeToolId(): ToolId;\n  cursor(): Cursor;\n  tools(): Tool[];\n  // ── tool intents ──\n  activateTool(id: ToolId): void;\n  /** Fires after the active tool changes — lets a feature react (e.g. a markup\n   *  tool taking over the selection visual). Returns an unsubscribe fn. */\n  onToolChange(cb: () => void): () => void;\n  /**\n   * Reskin a tool's cursor keywords at runtime — how an app gives the armed\n   * tool an image cursor built from its own toolbar icon (`Cursor` is any CSS\n   * cursor string, `url(data:…) x y, crosshair` included). See\n   * {@link ToolCursorSkin} for what the map means. `null` removes the skin.\n   */\n  setToolCursor(id: ToolId, skin: ToolCursorSkin | null): void;\n  // ── registries (return an unregister fn) ──\n  registerTool(tool: Tool): () => void;\n  registerHandler(handler: InteractionHandler): () => void;\n  // ── cursor claim stack (highest priority wins; null clears the token) ──\n  setCursor(token: string, cursor: Cursor | null, priority?: number): void;\n  // ── pointer ingress: the adapter calls this for every normalized event ──\n  dispatch(sample: PointerSample): void;\n}\n\nexport const InteractionToken = createCapabilityToken<InteractionCapability>('interaction');\n\n/**\n * Resolve a sample against a gesture's HOME page. Page-anchored gestures track\n * the page they started on even when the cursor wanders off it — `s.page`\n * re-resolves per event (a foreign page is a DIFFERENT coordinate frame), so\n * prefer the source's unclamped projection and fall back to the page hit only\n * when it is the same page. Null → this sample can't speak for the home page.\n * Shared by every gesture owner (annotation edit/draw, form placement).\n */\nexport const samplePointOn = (s: PointerSample, pon: PageObjectNumber): Point | null =>\n  s.project?.(pon) ?? (s.page?.pon === pon ? s.page.point : null);\n\nexport interface InteractionConfig {\n  /** Tool active when a document opens. Default `'pointer'`. */\n  defaultTool?: ToolId;\n}\n","import { definePlugin } from '@embedpdf/core';\nimport { createInteractionCapability } from './capability';\nimport { initialInteractionState, interactionReducer } from './reducer';\nimport { InteractionToken } from './types';\nimport type {\n  InteractionAction,\n  InteractionCapability,\n  InteractionConfig,\n  InteractionState,\n  Tool,\n} from './types';\n\n/**\n * The two built-in tools. Features ADD tools via `registerTool` (a draw tool, a\n * redact tool…). `enables` is the composition seam:\n *   pointer → text selection + annotation editing + annotation marquee selection\n *   pan     → scrolling (contributed by Stage) + annotation editing, NO text select\n *\n * Both carry `form-fill`: filling a form is the RESTING state of a viewer\n * (Acrobat's hand tool fills forms too), so widgets are fill-controls under the\n * default tools and only become geometry-editable under a form-design tool.\n * Both carry `link-nav` for the same reason: links navigate under the default\n * tools (Acrobat behaviour) and only become geometry-editable under the link\n * tool. Tags are opaque to the hub — without the form/link plugins they're inert.\n */\nexport const builtinTools = (): Tool[] => [\n  {\n    id: 'pointer',\n    cursor: 'default',\n    enables: new Set([\n      'text-select',\n      'annotation-edit',\n      'annotation-marquee',\n      'form-fill',\n      'link-nav',\n    ]),\n  },\n  {\n    id: 'pan',\n    cursor: 'grab',\n    gapCursor: 'grab', // pan works anywhere — the open hand doesn't stop at page edges\n    enables: new Set(['scroll', 'annotation-edit', 'form-fill', 'link-nav']),\n  },\n];\n\n/**\n * The interaction hub plugin — document-scoped, depends on nothing. Every feature\n * plugin (selection, annotation, forms, redaction) `requires` this token; Stage\n * `optional`-ly contributes a scroll handler. Works with `<Stage>` or a standalone\n * `<PageView>` — it only routes page-space pointer samples.\n */\nexport const interactionPlugin = (config: InteractionConfig = {}) =>\n  definePlugin<InteractionState, InteractionAction, InteractionCapability>({\n    id: 'interaction',\n    token: InteractionToken,\n    scope: 'document',\n    initialState: () => initialInteractionState(config),\n    reduce: interactionReducer,\n    capability: (ctx) => createInteractionCapability(ctx, builtinTools()),\n  });\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@embedpdf/plugin-interaction",
+  "version": "3.0.0-next.0",
+  "private": false,
+  "description": "The interaction hub: the active tool, the cursor, and pointer routing. Pure mechanism — knows nothing about selection/annotations/forms; they contribute tools + handlers.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@embedpdf/core": "3.0.0-next.0",
+    "@embedpdf/core-geometry": "3.0.0-next.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "vitest": "^2.1.9",
+    "@embedpdf/tooling-build": "0.0.0"
+  },
+  "license": "Apache-2.0",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/embedpdf/embed-pdf-viewer.git",
+    "directory": "packages/plugin/interaction"
+  },
+  "scripts": {
+    "build": "epdf-build",
+    "clean": "rimraf dist",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}