@embedpdf/plugin-interaction 3.0.0-next.5 → 3.0.0-next.7

package/dist/index.cjs

@@ -48,9 +48,13 @@ function createInteractionCapability(ctx, builtinTools) {
 			cursor: next
 		});
 	};
-	const eligible = () => {
+	const handlerSources = /* @__PURE__ */ new Map();
+	const eligible = (source) => {
 		const tool = active();
-		return handlers.filter((h) => h.enabledFor(tool)).sort((a, b) => b.priority - a.priority);
+		return handlers.filter((h) => {
+			const hs = handlerSources.get(h);
+			return hs === void 0 || source === void 0 || hs === source;
+		}).filter((h) => h.enabledFor(tool)).sort((a, b) => b.priority - a.priority);
 	};
 	return {
 		activeTool: active,
@@ -84,11 +88,13 @@ function createInteractionCapability(ctx, builtinTools) {
 			else cursorSkins.set(id, skin);
 			syncCursor();
 		},
-		registerHandler: (handler) => {
+		registerHandler: (handler, options) => {
 			handlers.push(handler);
+			if (options?.source !== void 0) handlerSources.set(handler, options.source);
 			return () => {
 				const i = handlers.indexOf(handler);
 				if (i >= 0) handlers.splice(i, 1);
+				handlerSources.delete(handler);
 				if (owner === handler) owner = null;
 			};
 		},
@@ -100,6 +106,10 @@ function createInteractionCapability(ctx, builtinTools) {
 			});
 			syncCursor();
 		},
+		wouldClaimTouch: (sample) => {
+			for (const h of eligible(sample.source)) if (h.claimsTouch?.(sample)) return true;
+			return false;
+		},
 		dispatch: (sample) => {
 			const nowOverPage = sample.page != null;
 			if (nowOverPage !== overPage) {
@@ -108,13 +118,17 @@ function createInteractionCapability(ctx, builtinTools) {
 			}
 			if (sample.phase === "down") {
 				owner = null;
-				for (const h of eligible()) if (h.onDown(sample)) {
+				for (const h of eligible(sample.source)) 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 {
+			else for (const h of eligible(sample.source)) h.onHover?.(sample);
+			else if (sample.phase === "cancel") {
+				const o = owner;
+				owner = null;
+				if (o) (o.onCancel ?? o.onUp)?.call(o, sample);
+			} else {
 				owner?.onUp?.(sample);
 				owner = null;
 			}
@@ -142,7 +156,7 @@ const interactionReducer = (state, action) => {
 };
 //#endregion
 //#region src/types.ts
-const InteractionToken = (0, _embedpdf_core.createCapabilityToken)("interaction");
+const InteractionToken = (0, _embedpdf_core.createCapabilityToken)("interaction", { hint: `add interactionPlugin() from '@embedpdf/plugin-interaction' to your plugins list` });
 /**
 * 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`
@@ -203,9 +217,52 @@ const interactionPlugin = (config = {}) => (0, _embedpdf_core.definePlugin)({
 	capability: (ctx) => createInteractionCapability(ctx, builtinTools())
 });
 //#endregion
+//#region src/feedback.ts
+/**
+* Platform feedback (haptics) — the OUTPUT half of the interaction seam:
+* pointers come in, feedback goes back out to the device.
+*
+* ONE workspace-scoped provider, MANY consumers: any plugin lists
+* {@link FeedbackToken} as an optional dependency and calls the capability at
+* its semantic moments (the selection handler on a long-press word-select; an
+* annotation pickup or a snap later). The plugin itself stays DOM-free — the
+* PROVIDER is injected from outside (`@embedpdf/web` ships `vibrationFeedback`
+* and a WKWebView bridge; native shells bring their own), exactly like the
+* stage's Scheduler seam: host dependencies enter through explicit injection,
+* never a hidden global.
+*
+* The vocabulary is deliberately the PLATFORM's haptic taxonomy — iOS's three
+* generator families, which Android mirrors in `HapticFeedbackConstants` and
+* the web approximates with vibration patterns — not app vocabulary. A verb
+* belongs here only if a provider would map it to a physically different
+* output; call-site semantics ("word selected", "annotation picked up") pick a
+* family, they never add one.
+*/
+const FeedbackToken = (0, _embedpdf_core.createCapabilityToken)("feedback");
+/** No provider → every call is a cheap no-op; consumers never branch. */
+const NOOP = {
+	selection() {},
+	impact() {},
+	notify() {}
+};
+/**
+* Register the workspace's ONE feedback provider. Stateless: the capability IS
+* the provider (or the no-op).
+*/
+const feedbackPlugin = (options = {}) => (0, _embedpdf_core.definePlugin)({
+	id: "feedback",
+	scope: "workspace",
+	token: FeedbackToken,
+	initialState: () => ({}),
+	reduce: (state) => state,
+	capability: () => options.provider ?? NOOP
+});
+//#endregion
+exports.FeedbackToken = FeedbackToken;
 exports.InteractionToken = InteractionToken;
 exports.builtinTools = builtinTools;
 exports.createInteractionCapability = createInteractionCapability;
+exports.feedbackPlugin = feedbackPlugin;
 exports.initialInteractionState = initialInteractionState;
 exports.interactionPlugin = interactionPlugin;
 exports.interactionReducer = interactionReducer;

package/dist/index.cjs.map

@@ -1 +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"}
+{"version":3,"file":"index.cjs","names":[],"sources":["../src/capability.ts","../src/reducer.ts","../src/types.ts","../src/interaction.plugin.ts","../src/feedback.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  // Lens scoping: a handler registered with a `source` only sees samples\n  // stamped with it. Filtering is on DEFINITE mismatch only — an unstamped\n  // sample (custom dispatcher, single-lens embed) still routes everywhere.\n  const handlerSources = new Map<InteractionHandler, string>();\n  const eligible = (source?: string): InteractionHandler[] => {\n    const tool = active();\n    return handlers\n      .filter((h) => {\n        const hs = handlerSources.get(h);\n        return hs === undefined || source === undefined || hs === source;\n      })\n      .filter((h) => h.enabledFor(tool))\n      .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, options) => {\n      handlers.push(handler);\n      if (options?.source !== undefined) handlerSources.set(handler, options.source);\n      return () => {\n        const i = handlers.indexOf(handler);\n        if (i >= 0) handlers.splice(i, 1);\n        handlerSources.delete(handler);\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    wouldClaimTouch: (sample) => {\n      for (const h of eligible(sample.source)) if (h.claimsTouch?.(sample)) return true;\n      return false;\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(sample.source)) {\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(sample.source)) h.onHover?.(sample);\n      } else if (sample.phase === 'cancel') {\n        // Abort, don't commit: navigation took the pointer (second finger →\n        // pinch) or the system cancelled it. onUp is the fallback for handlers\n        // that predate cancel — committing beats a stuck gesture.\n        const o = owner;\n        owner = null;\n        if (o) (o.onCancel ?? o.onUp)?.call(o, 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   * TOUCH CONSENT, rung 1 — \"arming this tool is consent to create with a\n   * finger\": while it is active, single-finger touch routes to the hub\n   * wholesale (draw/markup/redact tools), and navigation moves to two\n   * fingers — the drawing-app convention. Default false: a finger navigates\n   * first, and only per-point claims ({@link InteractionHandler.claimsTouch})\n   * carve out tool gestures.\n   */\n  touchDirect?: boolean;\n}\n\nexport type Phase = 'down' | 'move' | 'up' | 'cancel';\n\n/** The physical device class behind a sample — `PointerEvent.pointerType`.\n *  Adapters fill it so handlers (and arbitration above the hub) can apply\n *  modality policy: touch navigates first, pen/mouse are tool-first. */\nexport type PointerKind = 'mouse' | 'pen' | 'touch';\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  /** The device class that produced this sample (see {@link PointerKind}).\n   *  Absent when the source can't say — treat as 'mouse'. */\n  pointerType?: PointerKind;\n  /**\n   * Present when the sample was SYNTHESIZED from a recognized gesture rather\n   * than a raw press. 'long-press': a touch contact held still — the gesture\n   * controller forwards it as a down (with `clickCount: 2`, so word-selection\n   * keeps working unchanged), and this marker is the honest signal for\n   * handlers that must tell a long-press from a genuine double-click\n   * (haptics, pickup affordances). Absent on every raw pointer sample.\n   */\n  gesture?: 'long-press';\n  /**\n   * The LENS this sample came from — the stage plugin id the emitting surface\n   * binding was attached to (a document may be viewed through several stage\n   * lenses at once). Handlers registered with a matching `source` scope only\n   * see their own lens's input, so one lens's drag can never be captured by\n   * another lens's handler. Absent when the source doesn't say (custom\n   * dispatchers, single-lens embeds) — such samples route to every handler.\n   */\n  source?: string;\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  /**\n   * The gesture was ABORTED, not completed — the pointer was cancelled by the\n   * system, or navigation took it over (a second finger converted the drag\n   * into a pinch). Discard the in-flight work instead of committing it (a\n   * half-drawn shape, a mid-drag selection). Falls back to {@link onUp} when\n   * absent, since committing is the lesser evil to a stuck gesture.\n   */\n  onCancel?(sample: PointerSample): void;\n  /** Pointer moved with no active gesture — cursor feedback only. */\n  onHover?(sample: PointerSample): void;\n  /**\n   * TOUCH CONSENT, rung 2 — \"the selected thing owns its drags\". Touch\n   * navigation asks this BEFORE a contact is classified: return true and the\n   * whole contact routes to the hub as a tool gesture (down/move/up) instead\n   * of pan/pinch/tap. Implement it ONLY where the user has already narrowed\n   * intent to this point — the annotation handler claims the selected\n   * annotation's body and its handles, nothing else. A pure read: it must\n   * not mutate anything (the down that follows does the mutating). Handlers\n   * without it never claim, so plain surfaces keep navigating.\n   */\n  claimsTouch?(sample: PointerSample): boolean;\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  /**\n   * Register a pointer handler. `source` scopes it to ONE lens: the handler\n   * then only sees samples stamped with that source (see\n   * {@link PointerSample.source}) — mandatory for per-lens handlers like the\n   * stage's pan-scroll, or two stages on one document would capture each\n   * other's drags. UNSTAMPED samples still route everywhere (only a definite\n   * mismatch filters), so custom dispatchers keep working.\n   */\n  registerHandler(handler: InteractionHandler, options?: { source?: string }): () => 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   * The touch-arbitration pre-flight: would any eligible handler claim a\n   * contact at this sample ({@link InteractionHandler.claimsTouch})? Walked\n   * in the same priority order `dispatch` uses, first claim wins. Pure —\n   * nothing is captured or mutated; the gesture controller calls it at\n   * touch-down to route the contact (tool vs navigation), then dispatches\n   * normally.\n   */\n  wouldClaimTouch(sample: PointerSample): boolean;\n}\n\nexport const InteractionToken = createCapabilityToken<InteractionCapability>('interaction', {\n  hint: `add interactionPlugin() from '@embedpdf/plugin-interaction' to your plugins list`,\n});\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","/**\n * Platform feedback (haptics) — the OUTPUT half of the interaction seam:\n * pointers come in, feedback goes back out to the device.\n *\n * ONE workspace-scoped provider, MANY consumers: any plugin lists\n * {@link FeedbackToken} as an optional dependency and calls the capability at\n * its semantic moments (the selection handler on a long-press word-select; an\n * annotation pickup or a snap later). The plugin itself stays DOM-free — the\n * PROVIDER is injected from outside (`@embedpdf/web` ships `vibrationFeedback`\n * and a WKWebView bridge; native shells bring their own), exactly like the\n * stage's Scheduler seam: host dependencies enter through explicit injection,\n * never a hidden global.\n *\n * The vocabulary is deliberately the PLATFORM's haptic taxonomy — iOS's three\n * generator families, which Android mirrors in `HapticFeedbackConstants` and\n * the web approximates with vibration patterns — not app vocabulary. A verb\n * belongs here only if a provider would map it to a physically different\n * output; call-site semantics (\"word selected\", \"annotation picked up\") pick a\n * family, they never add one.\n */\nimport { createCapabilityToken, definePlugin } from '@embedpdf/core';\n\nexport interface PlatformFeedback {\n  /**\n   * The featherweight \"selection is changing\" tick\n   * (`UISelectionFeedbackGenerator`) — tuned for rapid repetition: a\n   * long-press engaging a word, a handle drag ticking across boundaries.\n   */\n  selection(): void;\n  /** A physical-collision bump (`UIImpactFeedbackGenerator`): something was\n   *  picked up, snapped, or docked. Default weight 'light'. */\n  impact(weight?: 'light' | 'medium' | 'heavy'): void;\n  /** An outcome announcement (`UINotificationFeedbackGenerator`). */\n  notify(kind: 'success' | 'warning' | 'error'): void;\n}\n\nexport const FeedbackToken = createCapabilityToken<PlatformFeedback>('feedback');\n\n/** No provider → every call is a cheap no-op; consumers never branch. */\nconst NOOP: PlatformFeedback = { selection() {}, impact() {}, notify() {} };\n\nexport interface FeedbackPluginOptions {\n  /** The platform's feedback implementation. Omit for silence (headless,\n   *  tests, or a \"haptics off\" preference) — consumers keep working. */\n  provider?: PlatformFeedback;\n}\n\n/** The plugin is stateless; the action type exists only to satisfy the\n *  reducer contract (nothing ever dispatches it). */\ntype FeedbackAction = { type: 'feedback/noop' };\n\n/**\n * Register the workspace's ONE feedback provider. Stateless: the capability IS\n * the provider (or the no-op).\n */\nexport const feedbackPlugin = (options: FeedbackPluginOptions = {}) =>\n  definePlugin<Record<string, never>, FeedbackAction, PlatformFeedback>({\n    id: 'feedback',\n    scope: 'workspace',\n    token: FeedbackToken,\n    initialState: () => ({}),\n    reduce: (state) => state,\n    capability: () => options.provider ?? NOOP,\n  });\n"],"mappings":"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"}

package/dist/index.d.cts

@@ -27,8 +27,21 @@ interface Tool {
    */
   gapCursor?: Cursor;
   enables: ReadonlySet<string>;
+  /**
+   * TOUCH CONSENT, rung 1 — "arming this tool is consent to create with a
+   * finger": while it is active, single-finger touch routes to the hub
+   * wholesale (draw/markup/redact tools), and navigation moves to two
+   * fingers — the drawing-app convention. Default false: a finger navigates
+   * first, and only per-point claims ({@link InteractionHandler.claimsTouch})
+   * carve out tool gestures.
+   */
+  touchDirect?: boolean;
 }
-type Phase = 'down' | 'move' | 'up';
+type Phase = 'down' | 'move' | 'up' | 'cancel';
+/** The physical device class behind a sample — `PointerEvent.pointerType`.
+ *  Adapters fill it so handlers (and arbitration above the hub) can apply
+ *  modality policy: touch navigates first, pen/mouse are tool-first. */
+type PointerKind = 'mouse' | 'pen' | 'touch';
 /**
  * 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
@@ -63,6 +76,27 @@ interface PointerSample {
    * do word/line selection without re-implementing timing. Defaults to 1.
    */
   clickCount?: number;
+  /** The device class that produced this sample (see {@link PointerKind}).
+   *  Absent when the source can't say — treat as 'mouse'. */
+  pointerType?: PointerKind;
+  /**
+   * Present when the sample was SYNTHESIZED from a recognized gesture rather
+   * than a raw press. 'long-press': a touch contact held still — the gesture
+   * controller forwards it as a down (with `clickCount: 2`, so word-selection
+   * keeps working unchanged), and this marker is the honest signal for
+   * handlers that must tell a long-press from a genuine double-click
+   * (haptics, pickup affordances). Absent on every raw pointer sample.
+   */
+  gesture?: 'long-press';
+  /**
+   * The LENS this sample came from — the stage plugin id the emitting surface
+   * binding was attached to (a document may be viewed through several stage
+   * lenses at once). Handlers registered with a matching `source` scope only
+   * see their own lens's input, so one lens's drag can never be captured by
+   * another lens's handler. Absent when the source doesn't say (custom
+   * dispatchers, single-lens embeds) — such samples route to every handler.
+   */
+  source?: string;
   /**
    * 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
@@ -89,8 +123,27 @@ interface InteractionHandler {
   onDown(sample: PointerSample): boolean;
   onMove?(sample: PointerSample): void;
   onUp?(sample: PointerSample): void;
+  /**
+   * The gesture was ABORTED, not completed — the pointer was cancelled by the
+   * system, or navigation took it over (a second finger converted the drag
+   * into a pinch). Discard the in-flight work instead of committing it (a
+   * half-drawn shape, a mid-drag selection). Falls back to {@link onUp} when
+   * absent, since committing is the lesser evil to a stuck gesture.
+   */
+  onCancel?(sample: PointerSample): void;
   /** Pointer moved with no active gesture — cursor feedback only. */
   onHover?(sample: PointerSample): void;
+  /**
+   * TOUCH CONSENT, rung 2 — "the selected thing owns its drags". Touch
+   * navigation asks this BEFORE a contact is classified: return true and the
+   * whole contact routes to the hub as a tool gesture (down/move/up) instead
+   * of pan/pinch/tap. Implement it ONLY where the user has already narrowed
+   * intent to this point — the annotation handler claims the selected
+   * annotation's body and its handles, nothing else. A pure read: it must
+   * not mutate anything (the down that follows does the mutating). Handlers
+   * without it never claim, so plain surfaces keep navigating.
+   */
+  claimsTouch?(sample: PointerSample): boolean;
 }
 /**
  * A tool's runtime cursor skin: "while THIS tool is armed, keyword X looks
@@ -133,9 +186,28 @@ interface InteractionCapability {
    */
   setToolCursor(id: ToolId, skin: ToolCursorSkin | null): void;
   registerTool(tool: Tool): () => void;
-  registerHandler(handler: InteractionHandler): () => void;
+  /**
+   * Register a pointer handler. `source` scopes it to ONE lens: the handler
+   * then only sees samples stamped with that source (see
+   * {@link PointerSample.source}) — mandatory for per-lens handlers like the
+   * stage's pan-scroll, or two stages on one document would capture each
+   * other's drags. UNSTAMPED samples still route everywhere (only a definite
+   * mismatch filters), so custom dispatchers keep working.
+   */
+  registerHandler(handler: InteractionHandler, options?: {
+    source?: string;
+  }): () => void;
   setCursor(token: string, cursor: Cursor | null, priority?: number): void;
   dispatch(sample: PointerSample): void;
+  /**
+   * The touch-arbitration pre-flight: would any eligible handler claim a
+   * contact at this sample ({@link InteractionHandler.claimsTouch})? Walked
+   * in the same priority order `dispatch` uses, first claim wins. Pure —
+   * nothing is captured or mutated; the gesture controller calls it at
+   * touch-down to route the contact (tool vs navigation), then dispatches
+   * normally.
+   */
+  wouldClaimTouch(sample: PointerSample): boolean;
 }
 declare const InteractionToken: import("@embedpdf/core").CapabilityToken<InteractionCapability>;
 /**
@@ -198,5 +270,36 @@ declare function createInteractionCapability(ctx: PluginContext<InteractionState
 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 };
+//#region src/feedback.d.ts
+interface PlatformFeedback {
+  /**
+   * The featherweight "selection is changing" tick
+   * (`UISelectionFeedbackGenerator`) — tuned for rapid repetition: a
+   * long-press engaging a word, a handle drag ticking across boundaries.
+   */
+  selection(): void;
+  /** A physical-collision bump (`UIImpactFeedbackGenerator`): something was
+   *  picked up, snapped, or docked. Default weight 'light'. */
+  impact(weight?: 'light' | 'medium' | 'heavy'): void;
+  /** An outcome announcement (`UINotificationFeedbackGenerator`). */
+  notify(kind: 'success' | 'warning' | 'error'): void;
+}
+declare const FeedbackToken: import("@embedpdf/core").CapabilityToken<PlatformFeedback>;
+interface FeedbackPluginOptions {
+  /** The platform's feedback implementation. Omit for silence (headless,
+   *  tests, or a "haptics off" preference) — consumers keep working. */
+  provider?: PlatformFeedback;
+}
+/** The plugin is stateless; the action type exists only to satisfy the
+ *  reducer contract (nothing ever dispatches it). */
+type FeedbackAction = {
+  type: 'feedback/noop';
+};
+/**
+ * Register the workspace's ONE feedback provider. Stateless: the capability IS
+ * the provider (or the no-op).
+ */
+declare const feedbackPlugin: (options?: FeedbackPluginOptions) => import("@embedpdf/core").PluginDef<Record<string, never>, FeedbackAction, PlatformFeedback>;
+//#endregion
+export { type Cursor, type FeedbackPluginOptions, FeedbackToken, type InteractionAction, type InteractionCapability, type InteractionConfig, type InteractionHandler, type InteractionState, InteractionToken, type Modifiers, type Phase, type PlatformFeedback, type PointerKind, type PointerSample, type Tool, type ToolId, builtinTools, createInteractionCapability, feedbackPlugin, initialInteractionState, interactionPlugin, interactionReducer, samplePointOn };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -27,8 +27,21 @@ interface Tool {
    */
   gapCursor?: Cursor;
   enables: ReadonlySet<string>;
+  /**
+   * TOUCH CONSENT, rung 1 — "arming this tool is consent to create with a
+   * finger": while it is active, single-finger touch routes to the hub
+   * wholesale (draw/markup/redact tools), and navigation moves to two
+   * fingers — the drawing-app convention. Default false: a finger navigates
+   * first, and only per-point claims ({@link InteractionHandler.claimsTouch})
+   * carve out tool gestures.
+   */
+  touchDirect?: boolean;
 }
-type Phase = 'down' | 'move' | 'up';
+type Phase = 'down' | 'move' | 'up' | 'cancel';
+/** The physical device class behind a sample — `PointerEvent.pointerType`.
+ *  Adapters fill it so handlers (and arbitration above the hub) can apply
+ *  modality policy: touch navigates first, pen/mouse are tool-first. */
+type PointerKind = 'mouse' | 'pen' | 'touch';
 /**
  * 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
@@ -63,6 +76,27 @@ interface PointerSample {
    * do word/line selection without re-implementing timing. Defaults to 1.
    */
   clickCount?: number;
+  /** The device class that produced this sample (see {@link PointerKind}).
+   *  Absent when the source can't say — treat as 'mouse'. */
+  pointerType?: PointerKind;
+  /**
+   * Present when the sample was SYNTHESIZED from a recognized gesture rather
+   * than a raw press. 'long-press': a touch contact held still — the gesture
+   * controller forwards it as a down (with `clickCount: 2`, so word-selection
+   * keeps working unchanged), and this marker is the honest signal for
+   * handlers that must tell a long-press from a genuine double-click
+   * (haptics, pickup affordances). Absent on every raw pointer sample.
+   */
+  gesture?: 'long-press';
+  /**
+   * The LENS this sample came from — the stage plugin id the emitting surface
+   * binding was attached to (a document may be viewed through several stage
+   * lenses at once). Handlers registered with a matching `source` scope only
+   * see their own lens's input, so one lens's drag can never be captured by
+   * another lens's handler. Absent when the source doesn't say (custom
+   * dispatchers, single-lens embeds) — such samples route to every handler.
+   */
+  source?: string;
   /**
    * 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
@@ -89,8 +123,27 @@ interface InteractionHandler {
   onDown(sample: PointerSample): boolean;
   onMove?(sample: PointerSample): void;
   onUp?(sample: PointerSample): void;
+  /**
+   * The gesture was ABORTED, not completed — the pointer was cancelled by the
+   * system, or navigation took it over (a second finger converted the drag
+   * into a pinch). Discard the in-flight work instead of committing it (a
+   * half-drawn shape, a mid-drag selection). Falls back to {@link onUp} when
+   * absent, since committing is the lesser evil to a stuck gesture.
+   */
+  onCancel?(sample: PointerSample): void;
   /** Pointer moved with no active gesture — cursor feedback only. */
   onHover?(sample: PointerSample): void;
+  /**
+   * TOUCH CONSENT, rung 2 — "the selected thing owns its drags". Touch
+   * navigation asks this BEFORE a contact is classified: return true and the
+   * whole contact routes to the hub as a tool gesture (down/move/up) instead
+   * of pan/pinch/tap. Implement it ONLY where the user has already narrowed
+   * intent to this point — the annotation handler claims the selected
+   * annotation's body and its handles, nothing else. A pure read: it must
+   * not mutate anything (the down that follows does the mutating). Handlers
+   * without it never claim, so plain surfaces keep navigating.
+   */
+  claimsTouch?(sample: PointerSample): boolean;
 }
 /**
  * A tool's runtime cursor skin: "while THIS tool is armed, keyword X looks
@@ -133,9 +186,28 @@ interface InteractionCapability {
    */
   setToolCursor(id: ToolId, skin: ToolCursorSkin | null): void;
   registerTool(tool: Tool): () => void;
-  registerHandler(handler: InteractionHandler): () => void;
+  /**
+   * Register a pointer handler. `source` scopes it to ONE lens: the handler
+   * then only sees samples stamped with that source (see
+   * {@link PointerSample.source}) — mandatory for per-lens handlers like the
+   * stage's pan-scroll, or two stages on one document would capture each
+   * other's drags. UNSTAMPED samples still route everywhere (only a definite
+   * mismatch filters), so custom dispatchers keep working.
+   */
+  registerHandler(handler: InteractionHandler, options?: {
+    source?: string;
+  }): () => void;
   setCursor(token: string, cursor: Cursor | null, priority?: number): void;
   dispatch(sample: PointerSample): void;
+  /**
+   * The touch-arbitration pre-flight: would any eligible handler claim a
+   * contact at this sample ({@link InteractionHandler.claimsTouch})? Walked
+   * in the same priority order `dispatch` uses, first claim wins. Pure —
+   * nothing is captured or mutated; the gesture controller calls it at
+   * touch-down to route the contact (tool vs navigation), then dispatches
+   * normally.
+   */
+  wouldClaimTouch(sample: PointerSample): boolean;
 }
 declare const InteractionToken: import("@embedpdf/core").CapabilityToken<InteractionCapability>;
 /**
@@ -198,5 +270,36 @@ declare function createInteractionCapability(ctx: PluginContext<InteractionState
 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 };
+//#region src/feedback.d.ts
+interface PlatformFeedback {
+  /**
+   * The featherweight "selection is changing" tick
+   * (`UISelectionFeedbackGenerator`) — tuned for rapid repetition: a
+   * long-press engaging a word, a handle drag ticking across boundaries.
+   */
+  selection(): void;
+  /** A physical-collision bump (`UIImpactFeedbackGenerator`): something was
+   *  picked up, snapped, or docked. Default weight 'light'. */
+  impact(weight?: 'light' | 'medium' | 'heavy'): void;
+  /** An outcome announcement (`UINotificationFeedbackGenerator`). */
+  notify(kind: 'success' | 'warning' | 'error'): void;
+}
+declare const FeedbackToken: import("@embedpdf/core").CapabilityToken<PlatformFeedback>;
+interface FeedbackPluginOptions {
+  /** The platform's feedback implementation. Omit for silence (headless,
+   *  tests, or a "haptics off" preference) — consumers keep working. */
+  provider?: PlatformFeedback;
+}
+/** The plugin is stateless; the action type exists only to satisfy the
+ *  reducer contract (nothing ever dispatches it). */
+type FeedbackAction = {
+  type: 'feedback/noop';
+};
+/**
+ * Register the workspace's ONE feedback provider. Stateless: the capability IS
+ * the provider (or the no-op).
+ */
+declare const feedbackPlugin: (options?: FeedbackPluginOptions) => import("@embedpdf/core").PluginDef<Record<string, never>, FeedbackAction, PlatformFeedback>;
+//#endregion
+export { type Cursor, type FeedbackPluginOptions, FeedbackToken, type InteractionAction, type InteractionCapability, type InteractionConfig, type InteractionHandler, type InteractionState, InteractionToken, type Modifiers, type Phase, type PlatformFeedback, type PointerKind, type PointerSample, type Tool, type ToolId, builtinTools, createInteractionCapability, feedbackPlugin, initialInteractionState, interactionPlugin, interactionReducer, samplePointOn };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -47,9 +47,13 @@ function createInteractionCapability(ctx, builtinTools) {
 			cursor: next
 		});
 	};
-	const eligible = () => {
+	const handlerSources = /* @__PURE__ */ new Map();
+	const eligible = (source) => {
 		const tool = active();
-		return handlers.filter((h) => h.enabledFor(tool)).sort((a, b) => b.priority - a.priority);
+		return handlers.filter((h) => {
+			const hs = handlerSources.get(h);
+			return hs === void 0 || source === void 0 || hs === source;
+		}).filter((h) => h.enabledFor(tool)).sort((a, b) => b.priority - a.priority);
 	};
 	return {
 		activeTool: active,
@@ -83,11 +87,13 @@ function createInteractionCapability(ctx, builtinTools) {
 			else cursorSkins.set(id, skin);
 			syncCursor();
 		},
-		registerHandler: (handler) => {
+		registerHandler: (handler, options) => {
 			handlers.push(handler);
+			if (options?.source !== void 0) handlerSources.set(handler, options.source);
 			return () => {
 				const i = handlers.indexOf(handler);
 				if (i >= 0) handlers.splice(i, 1);
+				handlerSources.delete(handler);
 				if (owner === handler) owner = null;
 			};
 		},
@@ -99,6 +105,10 @@ function createInteractionCapability(ctx, builtinTools) {
 			});
 			syncCursor();
 		},
+		wouldClaimTouch: (sample) => {
+			for (const h of eligible(sample.source)) if (h.claimsTouch?.(sample)) return true;
+			return false;
+		},
 		dispatch: (sample) => {
 			const nowOverPage = sample.page != null;
 			if (nowOverPage !== overPage) {
@@ -107,13 +117,17 @@ function createInteractionCapability(ctx, builtinTools) {
 			}
 			if (sample.phase === "down") {
 				owner = null;
-				for (const h of eligible()) if (h.onDown(sample)) {
+				for (const h of eligible(sample.source)) 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 {
+			else for (const h of eligible(sample.source)) h.onHover?.(sample);
+			else if (sample.phase === "cancel") {
+				const o = owner;
+				owner = null;
+				if (o) (o.onCancel ?? o.onUp)?.call(o, sample);
+			} else {
 				owner?.onUp?.(sample);
 				owner = null;
 			}
@@ -141,7 +155,7 @@ const interactionReducer = (state, action) => {
 };
 //#endregion
 //#region src/types.ts
-const InteractionToken = createCapabilityToken("interaction");
+const InteractionToken = createCapabilityToken("interaction", { hint: `add interactionPlugin() from '@embedpdf/plugin-interaction' to your plugins list` });
 /**
 * 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`
@@ -202,6 +216,47 @@ const interactionPlugin = (config = {}) => definePlugin({
 	capability: (ctx) => createInteractionCapability(ctx, builtinTools())
 });
 //#endregion
-export { InteractionToken, builtinTools, createInteractionCapability, initialInteractionState, interactionPlugin, interactionReducer, samplePointOn };
+//#region src/feedback.ts
+/**
+* Platform feedback (haptics) — the OUTPUT half of the interaction seam:
+* pointers come in, feedback goes back out to the device.
+*
+* ONE workspace-scoped provider, MANY consumers: any plugin lists
+* {@link FeedbackToken} as an optional dependency and calls the capability at
+* its semantic moments (the selection handler on a long-press word-select; an
+* annotation pickup or a snap later). The plugin itself stays DOM-free — the
+* PROVIDER is injected from outside (`@embedpdf/web` ships `vibrationFeedback`
+* and a WKWebView bridge; native shells bring their own), exactly like the
+* stage's Scheduler seam: host dependencies enter through explicit injection,
+* never a hidden global.
+*
+* The vocabulary is deliberately the PLATFORM's haptic taxonomy — iOS's three
+* generator families, which Android mirrors in `HapticFeedbackConstants` and
+* the web approximates with vibration patterns — not app vocabulary. A verb
+* belongs here only if a provider would map it to a physically different
+* output; call-site semantics ("word selected", "annotation picked up") pick a
+* family, they never add one.
+*/
+const FeedbackToken = createCapabilityToken("feedback");
+/** No provider → every call is a cheap no-op; consumers never branch. */
+const NOOP = {
+	selection() {},
+	impact() {},
+	notify() {}
+};
+/**
+* Register the workspace's ONE feedback provider. Stateless: the capability IS
+* the provider (or the no-op).
+*/
+const feedbackPlugin = (options = {}) => definePlugin({
+	id: "feedback",
+	scope: "workspace",
+	token: FeedbackToken,
+	initialState: () => ({}),
+	reduce: (state) => state,
+	capability: () => options.provider ?? NOOP
+});
+//#endregion
+export { FeedbackToken, InteractionToken, builtinTools, createInteractionCapability, feedbackPlugin, initialInteractionState, interactionPlugin, interactionReducer, samplePointOn };
 
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +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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"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/capability.ts","../src/reducer.ts","../src/types.ts","../src/interaction.plugin.ts","../src/feedback.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  // Lens scoping: a handler registered with a `source` only sees samples\n  // stamped with it. Filtering is on DEFINITE mismatch only — an unstamped\n  // sample (custom dispatcher, single-lens embed) still routes everywhere.\n  const handlerSources = new Map<InteractionHandler, string>();\n  const eligible = (source?: string): InteractionHandler[] => {\n    const tool = active();\n    return handlers\n      .filter((h) => {\n        const hs = handlerSources.get(h);\n        return hs === undefined || source === undefined || hs === source;\n      })\n      .filter((h) => h.enabledFor(tool))\n      .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, options) => {\n      handlers.push(handler);\n      if (options?.source !== undefined) handlerSources.set(handler, options.source);\n      return () => {\n        const i = handlers.indexOf(handler);\n        if (i >= 0) handlers.splice(i, 1);\n        handlerSources.delete(handler);\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    wouldClaimTouch: (sample) => {\n      for (const h of eligible(sample.source)) if (h.claimsTouch?.(sample)) return true;\n      return false;\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(sample.source)) {\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(sample.source)) h.onHover?.(sample);\n      } else if (sample.phase === 'cancel') {\n        // Abort, don't commit: navigation took the pointer (second finger →\n        // pinch) or the system cancelled it. onUp is the fallback for handlers\n        // that predate cancel — committing beats a stuck gesture.\n        const o = owner;\n        owner = null;\n        if (o) (o.onCancel ?? o.onUp)?.call(o, 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   * TOUCH CONSENT, rung 1 — \"arming this tool is consent to create with a\n   * finger\": while it is active, single-finger touch routes to the hub\n   * wholesale (draw/markup/redact tools), and navigation moves to two\n   * fingers — the drawing-app convention. Default false: a finger navigates\n   * first, and only per-point claims ({@link InteractionHandler.claimsTouch})\n   * carve out tool gestures.\n   */\n  touchDirect?: boolean;\n}\n\nexport type Phase = 'down' | 'move' | 'up' | 'cancel';\n\n/** The physical device class behind a sample — `PointerEvent.pointerType`.\n *  Adapters fill it so handlers (and arbitration above the hub) can apply\n *  modality policy: touch navigates first, pen/mouse are tool-first. */\nexport type PointerKind = 'mouse' | 'pen' | 'touch';\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  /** The device class that produced this sample (see {@link PointerKind}).\n   *  Absent when the source can't say — treat as 'mouse'. */\n  pointerType?: PointerKind;\n  /**\n   * Present when the sample was SYNTHESIZED from a recognized gesture rather\n   * than a raw press. 'long-press': a touch contact held still — the gesture\n   * controller forwards it as a down (with `clickCount: 2`, so word-selection\n   * keeps working unchanged), and this marker is the honest signal for\n   * handlers that must tell a long-press from a genuine double-click\n   * (haptics, pickup affordances). Absent on every raw pointer sample.\n   */\n  gesture?: 'long-press';\n  /**\n   * The LENS this sample came from — the stage plugin id the emitting surface\n   * binding was attached to (a document may be viewed through several stage\n   * lenses at once). Handlers registered with a matching `source` scope only\n   * see their own lens's input, so one lens's drag can never be captured by\n   * another lens's handler. Absent when the source doesn't say (custom\n   * dispatchers, single-lens embeds) — such samples route to every handler.\n   */\n  source?: string;\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  /**\n   * The gesture was ABORTED, not completed — the pointer was cancelled by the\n   * system, or navigation took it over (a second finger converted the drag\n   * into a pinch). Discard the in-flight work instead of committing it (a\n   * half-drawn shape, a mid-drag selection). Falls back to {@link onUp} when\n   * absent, since committing is the lesser evil to a stuck gesture.\n   */\n  onCancel?(sample: PointerSample): void;\n  /** Pointer moved with no active gesture — cursor feedback only. */\n  onHover?(sample: PointerSample): void;\n  /**\n   * TOUCH CONSENT, rung 2 — \"the selected thing owns its drags\". Touch\n   * navigation asks this BEFORE a contact is classified: return true and the\n   * whole contact routes to the hub as a tool gesture (down/move/up) instead\n   * of pan/pinch/tap. Implement it ONLY where the user has already narrowed\n   * intent to this point — the annotation handler claims the selected\n   * annotation's body and its handles, nothing else. A pure read: it must\n   * not mutate anything (the down that follows does the mutating). Handlers\n   * without it never claim, so plain surfaces keep navigating.\n   */\n  claimsTouch?(sample: PointerSample): boolean;\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  /**\n   * Register a pointer handler. `source` scopes it to ONE lens: the handler\n   * then only sees samples stamped with that source (see\n   * {@link PointerSample.source}) — mandatory for per-lens handlers like the\n   * stage's pan-scroll, or two stages on one document would capture each\n   * other's drags. UNSTAMPED samples still route everywhere (only a definite\n   * mismatch filters), so custom dispatchers keep working.\n   */\n  registerHandler(handler: InteractionHandler, options?: { source?: string }): () => 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   * The touch-arbitration pre-flight: would any eligible handler claim a\n   * contact at this sample ({@link InteractionHandler.claimsTouch})? Walked\n   * in the same priority order `dispatch` uses, first claim wins. Pure —\n   * nothing is captured or mutated; the gesture controller calls it at\n   * touch-down to route the contact (tool vs navigation), then dispatches\n   * normally.\n   */\n  wouldClaimTouch(sample: PointerSample): boolean;\n}\n\nexport const InteractionToken = createCapabilityToken<InteractionCapability>('interaction', {\n  hint: `add interactionPlugin() from '@embedpdf/plugin-interaction' to your plugins list`,\n});\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","/**\n * Platform feedback (haptics) — the OUTPUT half of the interaction seam:\n * pointers come in, feedback goes back out to the device.\n *\n * ONE workspace-scoped provider, MANY consumers: any plugin lists\n * {@link FeedbackToken} as an optional dependency and calls the capability at\n * its semantic moments (the selection handler on a long-press word-select; an\n * annotation pickup or a snap later). The plugin itself stays DOM-free — the\n * PROVIDER is injected from outside (`@embedpdf/web` ships `vibrationFeedback`\n * and a WKWebView bridge; native shells bring their own), exactly like the\n * stage's Scheduler seam: host dependencies enter through explicit injection,\n * never a hidden global.\n *\n * The vocabulary is deliberately the PLATFORM's haptic taxonomy — iOS's three\n * generator families, which Android mirrors in `HapticFeedbackConstants` and\n * the web approximates with vibration patterns — not app vocabulary. A verb\n * belongs here only if a provider would map it to a physically different\n * output; call-site semantics (\"word selected\", \"annotation picked up\") pick a\n * family, they never add one.\n */\nimport { createCapabilityToken, definePlugin } from '@embedpdf/core';\n\nexport interface PlatformFeedback {\n  /**\n   * The featherweight \"selection is changing\" tick\n   * (`UISelectionFeedbackGenerator`) — tuned for rapid repetition: a\n   * long-press engaging a word, a handle drag ticking across boundaries.\n   */\n  selection(): void;\n  /** A physical-collision bump (`UIImpactFeedbackGenerator`): something was\n   *  picked up, snapped, or docked. Default weight 'light'. */\n  impact(weight?: 'light' | 'medium' | 'heavy'): void;\n  /** An outcome announcement (`UINotificationFeedbackGenerator`). */\n  notify(kind: 'success' | 'warning' | 'error'): void;\n}\n\nexport const FeedbackToken = createCapabilityToken<PlatformFeedback>('feedback');\n\n/** No provider → every call is a cheap no-op; consumers never branch. */\nconst NOOP: PlatformFeedback = { selection() {}, impact() {}, notify() {} };\n\nexport interface FeedbackPluginOptions {\n  /** The platform's feedback implementation. Omit for silence (headless,\n   *  tests, or a \"haptics off\" preference) — consumers keep working. */\n  provider?: PlatformFeedback;\n}\n\n/** The plugin is stateless; the action type exists only to satisfy the\n *  reducer contract (nothing ever dispatches it). */\ntype FeedbackAction = { type: 'feedback/noop' };\n\n/**\n * Register the workspace's ONE feedback provider. Stateless: the capability IS\n * the provider (or the no-op).\n */\nexport const feedbackPlugin = (options: FeedbackPluginOptions = {}) =>\n  definePlugin<Record<string, never>, FeedbackAction, PlatformFeedback>({\n    id: 'feedback',\n    scope: 'workspace',\n    token: FeedbackToken,\n    initialState: () => ({}),\n    reduce: (state) => state,\n    capability: () => options.provider ?? NOOP,\n  });\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@embedpdf/plugin-interaction",
-  "version": "3.0.0-next.5",
+  "version": "3.0.0-next.7",
   "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",
@@ -18,8 +18,8 @@
     "dist"
   ],
   "dependencies": {
-    "@embedpdf/core": "3.0.0-next.5",
-    "@embedpdf/core-geometry": "3.0.0-next.5"
+    "@embedpdf/core": "3.0.0-next.7",
+    "@embedpdf/core-geometry": "3.0.0-next.7"
   },
   "devDependencies": {
     "typescript": "^5.0.0",