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

package/dist/index.d.ts

@@ -1,229 +1,5 @@
-import { PageObjectNumber, PluginContext } from "@embedpdf/core";
-import { PageRotation, Point } from "@embedpdf/core-geometry";
-//#region src/types.d.ts
-type ToolId = string;
-type Cursor = string;
-interface Modifiers {
-  shift: boolean;
-  alt: boolean;
-  ctrl: boolean;
-  meta: boolean;
-}
-/**
- * The single active arbiter of what the pointer does. `pan` and `pointer` are
- * built in; features add more (`highlight`, `square`, `redact`…) via
- * `registerTool`. A tool carries no behaviour itself — it turns on capability
- * TAGS that handlers opt into (`enables`), so tools compose features without
- * coupling to them.
- */
-interface Tool {
-  id: ToolId;
-  cursor: Cursor;
-  /**
-   * Cursor over the viewport's page GAPS. A tool's cursor answers "what would
-   * a click do here" — and most tools act only on pages, so gaps fall back to
-   * the neutral arrow (`'default'`). A tool that works anywhere (pan) declares
-   * its own (`'grab'`). Hover claims still outrank both.
-   */
-  gapCursor?: Cursor;
-  enables: ReadonlySet<string>;
-  /**
-   * 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' | '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
- * point (y-down, PDF units, via the page's transform) — present when the pointer
- * is over a page, absent over gaps. A viewport source (Stage) resolves `page` per
- * event (so a drag can cross pages); a per-page source (PageView) always sets it.
- */
-interface PointerSample {
-  phase: Phase;
-  viewport: Point;
-  /** `scale` is the hit page's VIEW px per content unit — handlers use it to
-   *  convert screen-px chrome settings into content-space tolerances, so grab
-   *  zones stay screen-constant across zoom. `rotation` is the hit page's TOTAL
-   *  display rotation (document /Rotate + view rotation) — per-event
-   *  environmental context like `scale`, for placement rules that depend on how
-   *  the page is DISPLAYED (an upright stamp). `zoom` is the page's zoom
-   *  RELATIVE to its 100% baseline (`transform.zoom` — dimensionless, 1 =
-   *  Acrobat's 100%), for zoom-relative policies (the `/F` NoZoom exemption);
-   *  distinct from `scale`, which is a units conversion. Absent when the
-   *  source can't say. */
-  page?: {
-    pon: PageObjectNumber;
-    point: Point;
-    scale?: number;
-    rotation?: PageRotation;
-    zoom?: number;
-  };
-  modifiers: Modifiers;
-  /**
-   * Click count for a `down` (1 = single, 2 = double, 3 = triple), from the
-   * browser's native multi-click detection (`MouseEvent.detail`). Lets handlers
-   * do word/line selection without re-implementing timing. Defaults to 1.
-   */
-  clickCount?: number;
-  /** 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
-   * cursor" and re-resolves per event; `project` answers "where is the cursor
-   * in MY page's frame" for a gesture anchored to the page it started on (an
-   * annotation drag sliding along the page edge). Null when the source can't
-   * project onto that page (not laid out / a per-page source's foreign page).
-   */
-  project?(pon: PageObjectNumber): Point | null;
-}
-/**
- * A pointer handler contributed by a feature plugin. The ONE registration
- * mechanism (replacing v2's registerMode / registerHandlers / registerAlways /
- * enableForMode quartet): a handler declares which tools it's live under and a
- * priority; the hub routes each gesture to the first handler that captures it.
- */
-interface InteractionHandler {
-  id: string;
-  /** Higher wins the gesture. */
-  priority: number;
-  /** Usually `tool.enables.has('my-tag')`. */
-  enabledFor(tool: Tool): boolean;
-  /** Return true to CAPTURE: subsequent move/up route here until pointer-up. */
-  onDown(sample: PointerSample): boolean;
-  onMove?(sample: PointerSample): void;
-  onUp?(sample: PointerSample): void;
-  /**
-   * 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
- * like Y." Everything cursor-shaped in the hub speaks KEYWORDS — a tool
- * declares its base ('crosshair', 'copy'), hover claims name what is under
- * the pointer ('text' over text, 'move' over an annotation) — and the skin
- * restyles those keywords, typically as image cursors carrying the tool's
- * icon. Applied uniformly to the winning claim and to the declared base, so
- * same keyword = same meaning = same look. Unmapped keywords render as-is (a
- * foreign 'move' over an annotation drops the tool identity), and page gaps
- * are never skinned — the identity appears exactly where the action is
- * possible, and the skin can only restyle where the tool already acts.
- */
-type ToolCursorSkin = Record<Cursor, Cursor>;
-interface InteractionState {
-  activeToolId: ToolId;
-  cursor: Cursor;
-}
-type InteractionAction = {
-  type: 'SET_TOOL';
-  toolId: ToolId;
-} | {
-  type: 'SET_CURSOR';
-  cursor: Cursor;
-};
-interface InteractionCapability {
-  activeTool(): Tool;
-  activeToolId(): ToolId;
-  cursor(): Cursor;
-  tools(): Tool[];
-  activateTool(id: ToolId): void;
-  /** Fires after the active tool changes — lets a feature react (e.g. a markup
-   *  tool taking over the selection visual). Returns an unsubscribe fn. */
-  onToolChange(cb: () => void): () => void;
-  /**
-   * Reskin a tool's cursor keywords at runtime — how an app gives the armed
-   * tool an image cursor built from its own toolbar icon (`Cursor` is any CSS
-   * cursor string, `url(data:…) x y, crosshair` included). See
-   * {@link ToolCursorSkin} for what the map means. `null` removes the skin.
-   */
-  setToolCursor(id: ToolId, skin: ToolCursorSkin | null): void;
-  registerTool(tool: Tool): () => void;
-  /**
-   * 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>;
-/**
- * Resolve a sample against a gesture's HOME page. Page-anchored gestures track
- * the page they started on even when the cursor wanders off it — `s.page`
- * re-resolves per event (a foreign page is a DIFFERENT coordinate frame), so
- * prefer the source's unclamped projection and fall back to the page hit only
- * when it is the same page. Null → this sample can't speak for the home page.
- * Shared by every gesture owner (annotation edit/draw, form placement).
- */
-declare const samplePointOn: (s: PointerSample, pon: PageObjectNumber) => Point | null;
-interface InteractionConfig {
-  /** Tool active when a document opens. Default `'pointer'`. */
-  defaultTool?: ToolId;
-}
-//#endregion
+import { _ as samplePointOn, a as InteractionAction, c as InteractionHandler, d as Modifiers, f as Phase, g as ToolId, h as Tool, i as Cursor, l as InteractionState, m as PointerSample, n as FeedbackToken, o as InteractionCapability, p as PointerKind, r as PlatformFeedback, s as InteractionConfig, t as FeedbackPluginOptions, u as InteractionToken } from "./contract-F3gsFtSf.js";
+import { PluginContext } from "@embedpdf/core";
 //#region src/interaction.plugin.d.ts
 /**
  * The two built-in tools. Features ADD tools via `registerTool` (a draw tool, a
@@ -271,25 +47,6 @@ declare const initialInteractionState: (config: InteractionConfig) => Interactio
 declare const interactionReducer: (state: InteractionState, action: InteractionAction) => InteractionState;
 //#endregion
 //#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 = {

package/dist/index.js

@@ -1,4 +1,5 @@
-import { createCapabilityToken, definePlugin } from "@embedpdf/core";
+import { n as InteractionToken, r as samplePointOn, t as FeedbackToken } from "./contract-CrM0i9pQ.js";
+import { definePlugin } from "@embedpdf/core";
 //#region src/capability.ts
 /**
 * The interaction hub. Tools + handlers + the captured-gesture owner + cursor
@@ -154,18 +155,6 @@ const interactionReducer = (state, action) => {
 	}
 };
 //#endregion
-//#region src/types.ts
-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`
-* re-resolves per event (a foreign page is a DIFFERENT coordinate frame), so
-* prefer the source's unclamped projection and fall back to the page hit only
-* when it is the same page. Null → this sample can't speak for the home page.
-* Shared by every gesture owner (annotation edit/draw, form placement).
-*/
-const samplePointOn = (s, pon) => s.project?.(pon) ?? (s.page?.pon === pon ? s.page.point : null);
-//#endregion
 //#region src/interaction.plugin.ts
 /**
 * The two built-in tools. Features ADD tools via `registerTool` (a draw tool, a
@@ -237,7 +226,6 @@ const interactionPlugin = (config = {}) => definePlugin({
 * 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() {},

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","../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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"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/capability.ts","../src/reducer.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 { 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 { definePlugin } from '@embedpdf/core';\n\nimport { FeedbackToken } from './feedback.types';\nimport type { FeedbackPluginOptions, PlatformFeedback } from './feedback.types';\n\n/** No provider → every call is a cheap no-op; consumers never branch. */\nconst NOOP: PlatformFeedback = { selection() {}, impact() {}, notify() {} };\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.10",
+  "version": "3.0.0-next.11",
   "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",
@@ -12,14 +12,18 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
+    "./contract": {
+      "import": "./dist/contract.js",
+      "require": "./dist/contract.cjs"
+    },
     "./package.json": "./package.json"
   },
   "files": [
     "dist"
   ],
   "dependencies": {
-    "@embedpdf/core": "3.0.0-next.10",
-    "@embedpdf/core-geometry": "3.0.0-next.10"
+    "@embedpdf/core": "3.0.0-next.11",
+    "@embedpdf/core-geometry": "3.0.0-next.11"
   },
   "devDependencies": {
     "typescript": "^5.0.0",