@embedpdf/react 3.0.0-next.10 → 3.0.0-next.12

package/dist/annotation-BCED_p9H.d.cts

@@ -0,0 +1,160 @@
+import { d as runtime_d_exports, o as PageContextValue } from "./runtime-umHA_xHt.cjs";
+import * as React from "react";
+import { AnnotationFlags, AnnotationProps, AnnotationProps as AnnotationProps$1, AnnotationPropsPatch, Border, CreationDraftAnchor, CreationDraftAnchor as CreationDraftAnchor$1, Geom, LineEnding, LineEndings, PropKey, PropSpec, Rect, RenderItem, RenderItem as RenderItem$1, Style, TextAlign, TextStyle, Vec } from "@embedpdf/core-annotation";
+import { AnnotationHydration, AnnotationRef, Behavior, CommentThread, CommentsApi, FilePickerProvider, SelectionFlags, SelectionFlags as SelectionFlags$1, SelectionProps, SelectionProps as SelectionProps$1 } from "@embedpdf/plugin-annotation";
+//#region src/annotation-anchors.d.ts
+/** The selection's menu anchor on its primary page, in content space. */
+type SelectionAnchor = {
+  pon: number;
+  bounds: Rect;
+  knob?: Vec;
+};
+declare function sameAnchor(a: SelectionAnchor | null, b: SelectionAnchor | null): boolean;
+declare function sameCreationDraftAnchor(a: CreationDraftAnchor | null, b: CreationDraftAnchor | null): boolean;
+//#endregion
+//#region src/annotation-hooks.d.ts
+/** The selected annotations as engine DTOs — for selection-aware toolbars/sidebars. */
+declare function useAnnotationSelected(): import("@embedpdf/plugin-annotation").AnnotationDTO[];
+//#endregion
+//#region src/annotation.d.ts
+/**
+ * What an annotation renderer receives: the projected item (its `box` is LIVE —
+ * it follows drags), the page context, the engine's baked /AP raster (the
+ * "picture"), the default visual (`native` — wrap it or ignore it), and
+ * whether this entry currently OWNS the pointer (`interactive`). While not
+ * interactive the layer renders your component pointer-locked: the annotation
+ * stays a first-class citizen of the annotation plane (select/move/resize).
+ */
+interface AnnotationRendererProps {
+  item: RenderItem;
+  page: PageContextValue;
+  appearance: {
+    url: string;
+    box: Rect;
+  } | null;
+  native: React.ReactNode;
+  interactive: boolean;
+}
+/**
+ * ONE rule: "for THESE annotations, render THIS component, and it owns the
+ * pointer WHEN …". The two shapes:
+ *
+ *   - `{ for, component, interactive? }` — your own rule. Without
+ *     `interactive` it is a pure SKIN: pixels only, mechanically
+ *     pointer-locked, the annotation plane keeps selection/move/resize. With
+ *     `interactive` (boolean or live predicate) the layer registers a plugin
+ *     Behavior for you: while it holds, the annotation plane stands down
+ *     (hit-test-inert) and your component owns the input.
+ *   - `{ behavior, component }` — the renderer for a PLUGIN-registered
+ *     behavior (the form plugin's fill controls via `formWidgetRenderer`);
+ *     the plugin decides engagement, never the app.
+ *
+ * Resolution: ownership beats skin — an ENGAGED behavior's component is
+ * authoritative; `for` rules apply only to plane-owned annotations, first
+ * match wins. Define entries OUTSIDE render (module scope or useMemo): entry
+ * identity keys the behavior registration.
+ */
+type AnnotationRenderer = {
+  behavior: string;
+  component: React.ComponentType<AnnotationRendererProps>;
+} | {
+  /** Stable id for the auto-registered behavior (optional; generated). */
+  id?: string;
+  for: Behavior['matches'];
+  component: React.ComponentType<AnnotationRendererProps>;
+  interactive?: boolean | (() => boolean);
+};
+interface AnnotationLayerProps {
+  /** Annotation renderers — skins and interactive takeovers ({@link AnnotationRenderer}). */
+  renderers?: AnnotationRenderer[];
+}
+declare function AnnotationLayer({ renderers }?: AnnotationLayerProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * The default file-picker provider: the built-in file dialog (from
+ * `@embedpdf/web`), honouring the tool's `accept` filter. This is the ADAPTER
+ * fulfilling the plugin's DOM-free port — the dialog lives here, in the
+ * framework layer, never in the plugin. A picked `File` carries its own name
+ * and mime, so it goes straight through as the engine's file source.
+ */
+declare const filePickerProvider: FilePickerProvider;
+/**
+ * Install the file-picker provider for the active document — the ONE port
+ * behind every click-then-pick tool (a stamp `'prompt'` source, the file-
+ * attachment tool). Call ONCE at a document-scoped spot (not inside
+ * `<AnnotationLayer>`, which is per page). Defaults to
+ * {@link filePickerProvider}, so a bare `useFilePickerProvider()` makes all of
+ * them work out of the box; pass a custom provider (asset library, cloud
+ * drive — switch on `req.subtype` / `req.toolId`) or `null` to make
+ * click-then-pick tools inert. Cleared on unmount.
+ */
+declare function useFilePickerProvider(provider?: FilePickerProvider | null): void;
+declare function useAnnotation(): import("@embedpdf/plugin-annotation").AnnotationCapability;
+declare function useAnnotationSelection(): string[];
+/**
+ * A tool's RESOLVED defaults (base + per-tool override) as a full flat props
+ * bag, subscribed so a `setDefaults` re-renders the consumer. Use this — not the
+ * imperative `useAnnotation().currentDefaults(id)` — to drive default-editing
+ * controls, so they reflect changes live. Pair with `propsForTool(id)` for the
+ * specs to render.
+ */
+declare function useAnnotationDefaults(toolId: string): AnnotationProps;
+/**
+ * The selection's editable properties — ordered specs shared by every selected
+ * kind, current values, and which keys are mixed. THE hook a property sidebar
+ * renders from; write back with `useAnnotation().updateSelection({ [key]: v })`.
+ * Reference-stable between model changes (the capability memoizes by model
+ * identity), so the default equality is enough.
+ */
+declare function useSelectionProps(): SelectionProps;
+/**
+ * The selection's `/F` annotation flags — per-flag `true`/`false`, `null` where
+ * the selected annotations disagree (render an indeterminate control), `null`
+ * overall when nothing is selected. Write back with
+ * `useAnnotation().updateSelectionFlags({ locked: true })`. Reference-stable
+ * between model changes, like {@link useSelectionProps}.
+ */
+declare function useSelectionFlags(): SelectionFlags | null;
+/**
+ * A {@link CommentThread} enriched with its page's live display position —
+ * the framework-layer join. Identity stays `pageObjectNumber` (like every
+ * annotation surface); these two fields are PRESENTATION, tracking page
+ * moves and deletes.
+ */
+interface CommentThreadView extends CommentThread {
+  /** Current 0-based display index of the thread's page; `-1` when the page
+   *  is no longer in the document (one-frame teardown race on delete). */
+  pageIndex: number;
+  /** The page's `/PageLabels` label when the PDF declares one ("iv", "A-2"),
+   *  else the 1-based position as a string — print it verbatim. */
+  pageLabel: string;
+  /**
+   * The root annotation's rect in CONTENT space (y-down, crop-relative,
+   * unscaled points) — the space `StageCapability.reveal` takes, so a
+   * "jump to this comment" is `stage.reveal(pageIndex, { rect: contentRect })`.
+   * Null when the page is gone. Identity still travels as `pageObjectNumber`;
+   * this, like `pageIndex`, is presentation.
+   */
+  contentRect: Rect | null;
+}
+/** Pure join behind {@link useCommentThreads} — exported for tests. */
+declare function enrichCommentThreads(threads: readonly CommentThread[], pages: readonly runtime_d_exports.PageLayout[]): CommentThreadView[];
+/** The comments surface (verbs + `permissionsFor`) — imperative; pair with
+ *  {@link useCommentThreads} for the subscribed view. */
+declare function useComments(): CommentsApi;
+/**
+ * Every comment thread in the document, display-ordered (page position →
+ * top of page → creation date) and enriched with `pageIndex`/`pageLabel`.
+ * Subscribed to BOTH stores: annotation writes (own, remote, hydration)
+ * recompute the threads; page moves/deletes re-run the join. Reference-
+ * stable between changes — safe to memo child renders on the array.
+ */
+declare function useCommentThreads(): CommentThreadView[];
+/** The enriched thread containing ANY member ref (root, reply, grouped part,
+ *  state annotation), or null. */
+declare function useCommentThread(ref: AnnotationRef | null): CommentThreadView | null;
+/** Whole-document hydration status — the comments sidebar's honest loading
+ *  state (`loading` until `listRawAll` lands, then `complete`/`error`). */
+declare function useCommentsHydration(): AnnotationHydration;
+//#endregion
+export { useCommentsHydration as A, filePickerProvider as C, useCommentThread as D, useAnnotationSelection as E, SelectionAnchor as F, sameAnchor as I, sameCreationDraftAnchor as L, useSelectionFlags as M, useSelectionProps as N, useCommentThreads as O, useAnnotationSelected as P, enrichCommentThreads as S, useAnnotationDefaults as T, SelectionFlags$1 as _, AnnotationPropsPatch as a, TextAlign as b, Border as c, Geom as d, LineEnding as f, RenderItem$1 as g, PropSpec as h, AnnotationProps$1 as i, useFilePickerProvider as j, useComments as k, CommentThreadView as l, PropKey as m, AnnotationLayer as n, AnnotationRenderer as o, LineEndings as p, AnnotationLayerProps as r, AnnotationRendererProps as s, AnnotationFlags as t, CreationDraftAnchor$1 as u, SelectionProps$1 as v, useAnnotation as w, TextStyle as x, Style as y };
+//# sourceMappingURL=annotation-BCED_p9H.d.cts.map

package/dist/annotation-anchors-CetwM1g7.js

@@ -0,0 +1,15 @@
+//#region src/annotation-anchors.ts
+function sameAnchor(a, b) {
+	if (a === b) return true;
+	if (!a || !b) return false;
+	return a.pon === b.pon && a.bounds.x === b.bounds.x && a.bounds.y === b.bounds.y && a.bounds.width === b.bounds.width && a.bounds.height === b.bounds.height && a.knob?.x === b.knob?.x && a.knob?.y === b.knob?.y;
+}
+function sameCreationDraftAnchor(a, b) {
+	if (a === b) return true;
+	if (!a || !b) return false;
+	return a.kind === b.kind && a.subtype === b.subtype && a.pon === b.pon && a.pointCount === b.pointCount && a.minPoints === b.minPoints && a.canFinish === b.canFinish && a.bounds.x === b.bounds.x && a.bounds.y === b.bounds.y && a.bounds.width === b.bounds.width && a.bounds.height === b.bounds.height;
+}
+//#endregion
+export { sameCreationDraftAnchor as n, sameAnchor as t };
+
+//# sourceMappingURL=annotation-anchors-CetwM1g7.js.map

package/dist/annotation-anchors-CetwM1g7.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotation-anchors-CetwM1g7.js","names":[],"sources":["../src/annotation-anchors.ts"],"sourcesContent":["import type { CreationDraftAnchor, Rect, Vec } from '@embedpdf/core-annotation';\n\n/** The selection's menu anchor on its primary page, in content space. */\nexport type SelectionAnchor = { pon: number; bounds: Rect; knob?: Vec };\n\nexport function sameAnchor(a: SelectionAnchor | null, b: SelectionAnchor | null): boolean {\n  if (a === b) return true;\n  if (!a || !b) return false;\n  return (\n    a.pon === b.pon &&\n    a.bounds.x === b.bounds.x &&\n    a.bounds.y === b.bounds.y &&\n    a.bounds.width === b.bounds.width &&\n    a.bounds.height === b.bounds.height &&\n    a.knob?.x === b.knob?.x &&\n    a.knob?.y === b.knob?.y\n  );\n}\n\nexport function sameCreationDraftAnchor(\n  a: CreationDraftAnchor | null,\n  b: CreationDraftAnchor | null,\n): boolean {\n  if (a === b) return true;\n  if (!a || !b) return false;\n  return (\n    a.kind === b.kind &&\n    a.subtype === b.subtype &&\n    a.pon === b.pon &&\n    a.pointCount === b.pointCount &&\n    a.minPoints === b.minPoints &&\n    a.canFinish === b.canFinish &&\n    a.bounds.x === b.bounds.x &&\n    a.bounds.y === b.bounds.y &&\n    a.bounds.width === b.bounds.width &&\n    a.bounds.height === b.bounds.height\n  );\n}\n"],"mappings":";AAKA,SAAgB,WAAW,GAA2B,GAAoC;CACxF,IAAI,MAAM,GAAG,OAAO;CACpB,IAAI,CAAC,KAAK,CAAC,GAAG,OAAO;CACrB,OACE,EAAE,QAAQ,EAAE,OACZ,EAAE,OAAO,MAAM,EAAE,OAAO,KACxB,EAAE,OAAO,MAAM,EAAE,OAAO,KACxB,EAAE,OAAO,UAAU,EAAE,OAAO,SAC5B,EAAE,OAAO,WAAW,EAAE,OAAO,UAC7B,EAAE,MAAM,MAAM,EAAE,MAAM,KACtB,EAAE,MAAM,MAAM,EAAE,MAAM;AAE1B;AAEA,SAAgB,wBACd,GACA,GACS;CACT,IAAI,MAAM,GAAG,OAAO;CACpB,IAAI,CAAC,KAAK,CAAC,GAAG,OAAO;CACrB,OACE,EAAE,SAAS,EAAE,QACb,EAAE,YAAY,EAAE,WAChB,EAAE,QAAQ,EAAE,OACZ,EAAE,eAAe,EAAE,cACnB,EAAE,cAAc,EAAE,aAClB,EAAE,cAAc,EAAE,aAClB,EAAE,OAAO,MAAM,EAAE,OAAO,KACxB,EAAE,OAAO,MAAM,EAAE,OAAO,KACxB,EAAE,OAAO,UAAU,EAAE,OAAO,SAC5B,EAAE,OAAO,WAAW,EAAE,OAAO;AAEjC"}

package/dist/annotation-anchors-DuYRBJLl.cjs

@@ -0,0 +1,26 @@
+//#region src/annotation-anchors.ts
+function sameAnchor(a, b) {
+	if (a === b) return true;
+	if (!a || !b) return false;
+	return a.pon === b.pon && a.bounds.x === b.bounds.x && a.bounds.y === b.bounds.y && a.bounds.width === b.bounds.width && a.bounds.height === b.bounds.height && a.knob?.x === b.knob?.x && a.knob?.y === b.knob?.y;
+}
+function sameCreationDraftAnchor(a, b) {
+	if (a === b) return true;
+	if (!a || !b) return false;
+	return a.kind === b.kind && a.subtype === b.subtype && a.pon === b.pon && a.pointCount === b.pointCount && a.minPoints === b.minPoints && a.canFinish === b.canFinish && a.bounds.x === b.bounds.x && a.bounds.y === b.bounds.y && a.bounds.width === b.bounds.width && a.bounds.height === b.bounds.height;
+}
+//#endregion
+Object.defineProperty(exports, "sameAnchor", {
+	enumerable: true,
+	get: function() {
+		return sameAnchor;
+	}
+});
+Object.defineProperty(exports, "sameCreationDraftAnchor", {
+	enumerable: true,
+	get: function() {
+		return sameCreationDraftAnchor;
+	}
+});
+
+//# sourceMappingURL=annotation-anchors-DuYRBJLl.cjs.map

package/dist/annotation-anchors-DuYRBJLl.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotation-anchors-DuYRBJLl.cjs","names":[],"sources":["../src/annotation-anchors.ts"],"sourcesContent":["import type { CreationDraftAnchor, Rect, Vec } from '@embedpdf/core-annotation';\n\n/** The selection's menu anchor on its primary page, in content space. */\nexport type SelectionAnchor = { pon: number; bounds: Rect; knob?: Vec };\n\nexport function sameAnchor(a: SelectionAnchor | null, b: SelectionAnchor | null): boolean {\n  if (a === b) return true;\n  if (!a || !b) return false;\n  return (\n    a.pon === b.pon &&\n    a.bounds.x === b.bounds.x &&\n    a.bounds.y === b.bounds.y &&\n    a.bounds.width === b.bounds.width &&\n    a.bounds.height === b.bounds.height &&\n    a.knob?.x === b.knob?.x &&\n    a.knob?.y === b.knob?.y\n  );\n}\n\nexport function sameCreationDraftAnchor(\n  a: CreationDraftAnchor | null,\n  b: CreationDraftAnchor | null,\n): boolean {\n  if (a === b) return true;\n  if (!a || !b) return false;\n  return (\n    a.kind === b.kind &&\n    a.subtype === b.subtype &&\n    a.pon === b.pon &&\n    a.pointCount === b.pointCount &&\n    a.minPoints === b.minPoints &&\n    a.canFinish === b.canFinish &&\n    a.bounds.x === b.bounds.x &&\n    a.bounds.y === b.bounds.y &&\n    a.bounds.width === b.bounds.width &&\n    a.bounds.height === b.bounds.height\n  );\n}\n"],"mappings":";AAKA,SAAgB,WAAW,GAA2B,GAAoC;CACxF,IAAI,MAAM,GAAG,OAAO;CACpB,IAAI,CAAC,KAAK,CAAC,GAAG,OAAO;CACrB,OACE,EAAE,QAAQ,EAAE,OACZ,EAAE,OAAO,MAAM,EAAE,OAAO,KACxB,EAAE,OAAO,MAAM,EAAE,OAAO,KACxB,EAAE,OAAO,UAAU,EAAE,OAAO,SAC5B,EAAE,OAAO,WAAW,EAAE,OAAO,UAC7B,EAAE,MAAM,MAAM,EAAE,MAAM,KACtB,EAAE,MAAM,MAAM,EAAE,MAAM;AAE1B;AAEA,SAAgB,wBACd,GACA,GACS;CACT,IAAI,MAAM,GAAG,OAAO;CACpB,IAAI,CAAC,KAAK,CAAC,GAAG,OAAO;CACrB,OACE,EAAE,SAAS,EAAE,QACb,EAAE,YAAY,EAAE,WAChB,EAAE,QAAQ,EAAE,OACZ,EAAE,eAAe,EAAE,cACnB,EAAE,cAAc,EAAE,aAClB,EAAE,cAAc,EAAE,aAClB,EAAE,OAAO,MAAM,EAAE,OAAO,KACxB,EAAE,OAAO,MAAM,EAAE,OAAO,KACxB,EAAE,OAAO,UAAU,EAAE,OAAO,SAC5B,EAAE,OAAO,WAAW,EAAE,OAAO;AAEjC"}

package/dist/annotation-hooks-BB5ZhPpf.cjs

@@ -0,0 +1,16 @@
+const require_runtime = require("./runtime.cjs");
+let _embedpdf_plugin_annotation_contract = require("@embedpdf/plugin-annotation/contract");
+//#region src/annotation-hooks.ts
+/** The selected annotations as engine DTOs — for selection-aware toolbars/sidebars. */
+function useAnnotationSelected() {
+	return require_runtime.useSelector(_embedpdf_plugin_annotation_contract.AnnotationToken, (c) => c.getSelected(), require_runtime.shallowArray);
+}
+//#endregion
+Object.defineProperty(exports, "useAnnotationSelected", {
+	enumerable: true,
+	get: function() {
+		return useAnnotationSelected;
+	}
+});
+
+//# sourceMappingURL=annotation-hooks-BB5ZhPpf.cjs.map

package/dist/annotation-hooks-BB5ZhPpf.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotation-hooks-BB5ZhPpf.cjs","names":["useSelector","AnnotationToken","shallowArray"],"sources":["../src/annotation-hooks.ts"],"sourcesContent":["import { AnnotationToken } from '@embedpdf/plugin-annotation/contract';\n\nimport { shallowArray, useSelector } from './runtime';\n\n/** The selected annotations as engine DTOs — for selection-aware toolbars/sidebars. */\nexport function useAnnotationSelected() {\n  return useSelector(AnnotationToken, (c) => c.getSelected(), shallowArray);\n}\n"],"mappings":";;;;AAKA,SAAgB,wBAAwB;CACtC,OAAOA,gBAAAA,YAAYC,qCAAAA,kBAAkB,MAAM,EAAE,YAAY,GAAGC,gBAAAA,YAAY;AAC1E"}

package/dist/annotation-hooks-Df8EmzDO.js

@@ -0,0 +1,11 @@
+import { shallowArray, useSelector } from "./runtime.js";
+import { AnnotationToken } from "@embedpdf/plugin-annotation/contract";
+//#region src/annotation-hooks.ts
+/** The selected annotations as engine DTOs — for selection-aware toolbars/sidebars. */
+function useAnnotationSelected() {
+	return useSelector(AnnotationToken, (c) => c.getSelected(), shallowArray);
+}
+//#endregion
+export { useAnnotationSelected as t };
+
+//# sourceMappingURL=annotation-hooks-Df8EmzDO.js.map

package/dist/annotation-hooks-Df8EmzDO.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotation-hooks-Df8EmzDO.js","names":[],"sources":["../src/annotation-hooks.ts"],"sourcesContent":["import { AnnotationToken } from '@embedpdf/plugin-annotation/contract';\n\nimport { shallowArray, useSelector } from './runtime';\n\n/** The selected annotations as engine DTOs — for selection-aware toolbars/sidebars. */\nexport function useAnnotationSelected() {\n  return useSelector(AnnotationToken, (c) => c.getSelected(), shallowArray);\n}\n"],"mappings":";;;;AAKA,SAAgB,wBAAwB;CACtC,OAAO,YAAY,kBAAkB,MAAM,EAAE,YAAY,GAAG,YAAY;AAC1E"}

package/dist/annotation-k38KDlIZ.d.ts

@@ -0,0 +1,160 @@
+import { d as runtime_d_exports, o as PageContextValue } from "./runtime-DE76hlnl.js";
+import * as React from "react";
+import { AnnotationHydration, AnnotationRef, Behavior, CommentThread, CommentsApi, FilePickerProvider, SelectionFlags, SelectionFlags as SelectionFlags$1, SelectionProps, SelectionProps as SelectionProps$1 } from "@embedpdf/plugin-annotation";
+import { AnnotationFlags, AnnotationProps, AnnotationProps as AnnotationProps$1, AnnotationPropsPatch, Border, CreationDraftAnchor, CreationDraftAnchor as CreationDraftAnchor$1, Geom, LineEnding, LineEndings, PropKey, PropSpec, Rect, RenderItem, RenderItem as RenderItem$1, Style, TextAlign, TextStyle, Vec } from "@embedpdf/core-annotation";
+//#region src/annotation-anchors.d.ts
+/** The selection's menu anchor on its primary page, in content space. */
+type SelectionAnchor = {
+  pon: number;
+  bounds: Rect;
+  knob?: Vec;
+};
+declare function sameAnchor(a: SelectionAnchor | null, b: SelectionAnchor | null): boolean;
+declare function sameCreationDraftAnchor(a: CreationDraftAnchor | null, b: CreationDraftAnchor | null): boolean;
+//#endregion
+//#region src/annotation-hooks.d.ts
+/** The selected annotations as engine DTOs — for selection-aware toolbars/sidebars. */
+declare function useAnnotationSelected(): import("@embedpdf/plugin-annotation").AnnotationDTO[];
+//#endregion
+//#region src/annotation.d.ts
+/**
+ * What an annotation renderer receives: the projected item (its `box` is LIVE —
+ * it follows drags), the page context, the engine's baked /AP raster (the
+ * "picture"), the default visual (`native` — wrap it or ignore it), and
+ * whether this entry currently OWNS the pointer (`interactive`). While not
+ * interactive the layer renders your component pointer-locked: the annotation
+ * stays a first-class citizen of the annotation plane (select/move/resize).
+ */
+interface AnnotationRendererProps {
+  item: RenderItem;
+  page: PageContextValue;
+  appearance: {
+    url: string;
+    box: Rect;
+  } | null;
+  native: React.ReactNode;
+  interactive: boolean;
+}
+/**
+ * ONE rule: "for THESE annotations, render THIS component, and it owns the
+ * pointer WHEN …". The two shapes:
+ *
+ *   - `{ for, component, interactive? }` — your own rule. Without
+ *     `interactive` it is a pure SKIN: pixels only, mechanically
+ *     pointer-locked, the annotation plane keeps selection/move/resize. With
+ *     `interactive` (boolean or live predicate) the layer registers a plugin
+ *     Behavior for you: while it holds, the annotation plane stands down
+ *     (hit-test-inert) and your component owns the input.
+ *   - `{ behavior, component }` — the renderer for a PLUGIN-registered
+ *     behavior (the form plugin's fill controls via `formWidgetRenderer`);
+ *     the plugin decides engagement, never the app.
+ *
+ * Resolution: ownership beats skin — an ENGAGED behavior's component is
+ * authoritative; `for` rules apply only to plane-owned annotations, first
+ * match wins. Define entries OUTSIDE render (module scope or useMemo): entry
+ * identity keys the behavior registration.
+ */
+type AnnotationRenderer = {
+  behavior: string;
+  component: React.ComponentType<AnnotationRendererProps>;
+} | {
+  /** Stable id for the auto-registered behavior (optional; generated). */
+  id?: string;
+  for: Behavior['matches'];
+  component: React.ComponentType<AnnotationRendererProps>;
+  interactive?: boolean | (() => boolean);
+};
+interface AnnotationLayerProps {
+  /** Annotation renderers — skins and interactive takeovers ({@link AnnotationRenderer}). */
+  renderers?: AnnotationRenderer[];
+}
+declare function AnnotationLayer({ renderers }?: AnnotationLayerProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * The default file-picker provider: the built-in file dialog (from
+ * `@embedpdf/web`), honouring the tool's `accept` filter. This is the ADAPTER
+ * fulfilling the plugin's DOM-free port — the dialog lives here, in the
+ * framework layer, never in the plugin. A picked `File` carries its own name
+ * and mime, so it goes straight through as the engine's file source.
+ */
+declare const filePickerProvider: FilePickerProvider;
+/**
+ * Install the file-picker provider for the active document — the ONE port
+ * behind every click-then-pick tool (a stamp `'prompt'` source, the file-
+ * attachment tool). Call ONCE at a document-scoped spot (not inside
+ * `<AnnotationLayer>`, which is per page). Defaults to
+ * {@link filePickerProvider}, so a bare `useFilePickerProvider()` makes all of
+ * them work out of the box; pass a custom provider (asset library, cloud
+ * drive — switch on `req.subtype` / `req.toolId`) or `null` to make
+ * click-then-pick tools inert. Cleared on unmount.
+ */
+declare function useFilePickerProvider(provider?: FilePickerProvider | null): void;
+declare function useAnnotation(): import("@embedpdf/plugin-annotation").AnnotationCapability;
+declare function useAnnotationSelection(): string[];
+/**
+ * A tool's RESOLVED defaults (base + per-tool override) as a full flat props
+ * bag, subscribed so a `setDefaults` re-renders the consumer. Use this — not the
+ * imperative `useAnnotation().currentDefaults(id)` — to drive default-editing
+ * controls, so they reflect changes live. Pair with `propsForTool(id)` for the
+ * specs to render.
+ */
+declare function useAnnotationDefaults(toolId: string): AnnotationProps;
+/**
+ * The selection's editable properties — ordered specs shared by every selected
+ * kind, current values, and which keys are mixed. THE hook a property sidebar
+ * renders from; write back with `useAnnotation().updateSelection({ [key]: v })`.
+ * Reference-stable between model changes (the capability memoizes by model
+ * identity), so the default equality is enough.
+ */
+declare function useSelectionProps(): SelectionProps;
+/**
+ * The selection's `/F` annotation flags — per-flag `true`/`false`, `null` where
+ * the selected annotations disagree (render an indeterminate control), `null`
+ * overall when nothing is selected. Write back with
+ * `useAnnotation().updateSelectionFlags({ locked: true })`. Reference-stable
+ * between model changes, like {@link useSelectionProps}.
+ */
+declare function useSelectionFlags(): SelectionFlags | null;
+/**
+ * A {@link CommentThread} enriched with its page's live display position —
+ * the framework-layer join. Identity stays `pageObjectNumber` (like every
+ * annotation surface); these two fields are PRESENTATION, tracking page
+ * moves and deletes.
+ */
+interface CommentThreadView extends CommentThread {
+  /** Current 0-based display index of the thread's page; `-1` when the page
+   *  is no longer in the document (one-frame teardown race on delete). */
+  pageIndex: number;
+  /** The page's `/PageLabels` label when the PDF declares one ("iv", "A-2"),
+   *  else the 1-based position as a string — print it verbatim. */
+  pageLabel: string;
+  /**
+   * The root annotation's rect in CONTENT space (y-down, crop-relative,
+   * unscaled points) — the space `StageCapability.reveal` takes, so a
+   * "jump to this comment" is `stage.reveal(pageIndex, { rect: contentRect })`.
+   * Null when the page is gone. Identity still travels as `pageObjectNumber`;
+   * this, like `pageIndex`, is presentation.
+   */
+  contentRect: Rect | null;
+}
+/** Pure join behind {@link useCommentThreads} — exported for tests. */
+declare function enrichCommentThreads(threads: readonly CommentThread[], pages: readonly runtime_d_exports.PageLayout[]): CommentThreadView[];
+/** The comments surface (verbs + `permissionsFor`) — imperative; pair with
+ *  {@link useCommentThreads} for the subscribed view. */
+declare function useComments(): CommentsApi;
+/**
+ * Every comment thread in the document, display-ordered (page position →
+ * top of page → creation date) and enriched with `pageIndex`/`pageLabel`.
+ * Subscribed to BOTH stores: annotation writes (own, remote, hydration)
+ * recompute the threads; page moves/deletes re-run the join. Reference-
+ * stable between changes — safe to memo child renders on the array.
+ */
+declare function useCommentThreads(): CommentThreadView[];
+/** The enriched thread containing ANY member ref (root, reply, grouped part,
+ *  state annotation), or null. */
+declare function useCommentThread(ref: AnnotationRef | null): CommentThreadView | null;
+/** Whole-document hydration status — the comments sidebar's honest loading
+ *  state (`loading` until `listRawAll` lands, then `complete`/`error`). */
+declare function useCommentsHydration(): AnnotationHydration;
+//#endregion
+export { useCommentsHydration as A, filePickerProvider as C, useCommentThread as D, useAnnotationSelection as E, SelectionAnchor as F, sameAnchor as I, sameCreationDraftAnchor as L, useSelectionFlags as M, useSelectionProps as N, useCommentThreads as O, useAnnotationSelected as P, enrichCommentThreads as S, useAnnotationDefaults as T, SelectionFlags$1 as _, AnnotationPropsPatch as a, TextAlign as b, Border as c, Geom as d, LineEnding as f, RenderItem$1 as g, PropSpec as h, AnnotationProps$1 as i, useFilePickerProvider as j, useComments as k, CommentThreadView as l, PropKey as m, AnnotationLayer as n, AnnotationRenderer as o, LineEndings as p, AnnotationLayerProps as r, AnnotationRendererProps as s, AnnotationFlags as t, CreationDraftAnchor$1 as u, SelectionProps$1 as v, useAnnotation as w, TextStyle as x, Style as y };
+//# sourceMappingURL=annotation-k38KDlIZ.d.ts.map

package/dist/annotation-menu.cjs

@@ -2,11 +2,11 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_rolldown_runtime = require("./rolldown-runtime-DDXJien1.cjs");
 const require_runtime = require("./runtime.cjs");
 const require_anchored = require("./anchored.cjs");
-const require_annotation = require("./annotation.cjs");
+const require_annotation_anchors = require("./annotation-anchors-DuYRBJLl.cjs");
 let react_jsx_runtime = require("react/jsx-runtime");
 let react = require("react");
 react = require_rolldown_runtime.__toESM(react, 1);
-let _embedpdf_plugin_annotation_internal = require("@embedpdf/plugin-annotation/internal");
+let _embedpdf_plugin_annotation_contract_host = require("@embedpdf/plugin-annotation/contract/host");
 //#region src/annotation-menu.tsx
 /**
 * Annotation menus — thin anchor plumbing over the ONE `<Anchored>` primitive.
@@ -28,12 +28,12 @@ let _embedpdf_plugin_annotation_internal = require("@embedpdf/plugin-annotation/
 */
 function AnnotationMenu({ children, gap = 15, placement = "top" }) {
 	const { projector } = require_anchored.useProjectorBinding();
-	const anchor = require_runtime.useSelector(_embedpdf_plugin_annotation_internal.AnnotationToken, (c) => {
+	const anchor = require_runtime.useSelector(_embedpdf_plugin_annotation_contract_host.AnnotationToken, (c) => {
 		const a = c.selectionAnchor();
 		if (!a) return null;
 		const env = projector.viewEnv(a.pon);
 		return env ? c.selectionAnchor(env.scale, env.rotation, env.zoom) : a;
-	}, require_annotation.sameAnchor);
+	}, require_annotation_anchors.sameAnchor);
 	if (!anchor) return null;
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(require_anchored.Anchored, {
 		anchor: {
@@ -48,7 +48,7 @@ function AnnotationMenu({ children, gap = 15, placement = "top" }) {
 }
 /** Floats over a live multi-click creation draft (polygon, polyline, …). */
 function AnnotationDraftMenu({ children, gap = 8, placement = "top" }) {
-	const anchor = require_runtime.useSelector(_embedpdf_plugin_annotation_internal.AnnotationToken, (c) => c.creationDraftAnchor(), require_annotation.sameCreationDraftAnchor);
+	const anchor = require_runtime.useSelector(_embedpdf_plugin_annotation_contract_host.AnnotationToken, (c) => c.creationDraftAnchor(), require_annotation_anchors.sameCreationDraftAnchor);
 	if (!anchor) return null;
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(require_anchored.Anchored, {
 		anchor,

package/dist/annotation-menu.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"annotation-menu.cjs","names":["useProjectorBinding","useSelector","AnnotationHostToken","sameAnchor","Anchored","sameCreationDraftAnchor"],"sources":["../src/annotation-menu.tsx"],"sourcesContent":["/**\n * Annotation menus — thin anchor plumbing over the ONE `<Anchored>` primitive.\n *\n * These work identically under `<Stage>` (mount in the overlay slot; the\n * camera projects, no DOM reads) and `<PageView>` (measured + portalled) —\n * the SURFACE provides the projector, the menu doesn't care.\n *\n * No action bags: actions come from the capability hooks (`useAnnotation()`,\n * `useAnnotationSelected()`, …), which subscribe properly and compose across\n * plugins. Render props carry only the ANCHOR'S DATA (the draft menu's\n * progress facts); the annotation-selection menu takes plain children.\n */\nimport * as React from 'react';\nimport { AnnotationToken as AnnotationHostToken } from '@embedpdf/plugin-annotation/internal';\nimport type { CreationDraftAnchor } from '@embedpdf/core-annotation';\nimport { Anchored, useProjectorBinding, type AnchoredPlacement } from './anchored';\nimport { useSelector } from './runtime';\nimport { sameAnchor, sameCreationDraftAnchor } from './annotation';\n\nexport interface AnnotationMenuProps {\n  children: React.ReactNode;\n  /** Gap in screen px between the selection box and the menu (default 15). */\n  gap?: number;\n  /** Where to place the menu relative to the selection box. Default 'top'. */\n  placement?: AnchoredPlacement;\n}\n\n/**\n * Floats over the current annotation selection (one anchor regardless of\n * cross-page selection), dodging the rotate knob. Compose the contents from\n * hooks: `useAnnotation()` for the verbs, `useAnnotationSelected()` /\n * `useSelectionProps()` for the data.\n */\nexport function AnnotationMenu({ children, gap = 15, placement = 'top' }: AnnotationMenuProps) {\n  // Reading the binding subscribes this component to projection changes\n  // (its identity IS the revision), so the anchor read below re-runs with\n  // fresh view facts in the SAME commit as the surface — the knob offset is\n  // screen-constant, so its content-space position depends on the page's\n  // live view scale.\n  const { projector } = useProjectorBinding();\n  const anchor = useSelector(\n    AnnotationHostToken,\n    (c) => {\n      const a = c.selectionAnchor();\n      if (!a) return null;\n      const env = projector.viewEnv(a.pon);\n      return env ? c.selectionAnchor(env.scale, env.rotation, env.zoom) : a;\n    },\n    sameAnchor,\n  );\n  if (!anchor) return null;\n  return (\n    <Anchored\n      anchor={{\n        pon: anchor.pon,\n        bounds: anchor.bounds,\n        ...(anchor.knob ? { avoid: [anchor.knob] } : {}),\n      }}\n      placement={placement}\n      gap={gap}\n    >\n      {children}\n    </Anchored>\n  );\n}\n\nexport interface AnnotationDraftMenuProps {\n  /** Render prop receiving the DRAFT ANCHOR'S DATA (subtype, pointCount,\n   *  minPoints, canFinish, …). The verbs are capability calls:\n   *  `useAnnotation().finishCreationDraft()` / `.cancelCreationDraft()`. */\n  children: (anchor: CreationDraftAnchor) => React.ReactNode;\n  /** Gap in screen px between the draft anchor and the menu (default 8). */\n  gap?: number;\n  /** Where to place the menu relative to the draft anchor. Default 'top'. */\n  placement?: AnchoredPlacement;\n}\n\n/** Floats over a live multi-click creation draft (polygon, polyline, …). */\nexport function AnnotationDraftMenu({\n  children,\n  gap = 8,\n  placement = 'top',\n}: AnnotationDraftMenuProps) {\n  const anchor = useSelector(\n    AnnotationHostToken,\n    (c) => c.creationDraftAnchor(),\n    sameCreationDraftAnchor,\n  );\n  if (!anchor) return null;\n  return (\n    <Anchored anchor={anchor} placement={placement} gap={gap}>\n      {children(anchor)}\n    </Anchored>\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCA,SAAgB,eAAe,EAAE,UAAU,MAAM,IAAI,YAAY,SAA8B;CAM7F,MAAM,EAAE,cAAcA,iBAAAA,oBAAoB;CAC1C,MAAM,SAASC,gBAAAA,YACbC,qCAAAA,kBACC,MAAM;EACL,MAAM,IAAI,EAAE,gBAAgB;EAC5B,IAAI,CAAC,GAAG,OAAO;EACf,MAAM,MAAM,UAAU,QAAQ,EAAE,GAAG;EACnC,OAAO,MAAM,EAAE,gBAAgB,IAAI,OAAO,IAAI,UAAU,IAAI,IAAI,IAAI;CACtE,GACAC,mBAAAA,UACF;CACA,IAAI,CAAC,QAAQ,OAAO;CACpB,OACE,iBAAA,GAAA,kBAAA,IAAA,CAACC,iBAAAA,UAAD;EACE,QAAQ;GACN,KAAK,OAAO;GACZ,QAAQ,OAAO;GACf,GAAI,OAAO,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,EAAE,IAAI,CAAC;EAChD;EACW;EACN;EAEJ;CACO,CAAA;AAEd;;AAcA,SAAgB,oBAAoB,EAClC,UACA,MAAM,GACN,YAAY,SACe;CAC3B,MAAM,SAASH,gBAAAA,YACbC,qCAAAA,kBACC,MAAM,EAAE,oBAAoB,GAC7BG,mBAAAA,uBACF;CACA,IAAI,CAAC,QAAQ,OAAO;CACpB,OACE,iBAAA,GAAA,kBAAA,IAAA,CAACD,iBAAAA,UAAD;EAAkB;EAAmB;EAAgB;EAClD,UAAA,SAAS,MAAM;CACR,CAAA;AAEd"}
+{"version":3,"file":"annotation-menu.cjs","names":["useProjectorBinding","useSelector","AnnotationHostToken","sameAnchor","Anchored","sameCreationDraftAnchor"],"sources":["../src/annotation-menu.tsx"],"sourcesContent":["/**\n * Annotation menus — thin anchor plumbing over the ONE `<Anchored>` primitive.\n *\n * These work identically under `<Stage>` (mount in the overlay slot; the\n * camera projects, no DOM reads) and `<PageView>` (measured + portalled) —\n * the SURFACE provides the projector, the menu doesn't care.\n *\n * No action bags: actions come from the capability hooks (`useAnnotation()`,\n * `useAnnotationSelected()`, …), which subscribe properly and compose across\n * plugins. Render props carry only the ANCHOR'S DATA (the draft menu's\n * progress facts); the annotation-selection menu takes plain children.\n */\nimport * as React from 'react';\nimport { AnnotationToken as AnnotationHostToken } from '@embedpdf/plugin-annotation/contract/host';\nimport type { CreationDraftAnchor } from '@embedpdf/core-annotation';\nimport { Anchored, useProjectorBinding, type AnchoredPlacement } from './anchored';\nimport { useSelector } from './runtime';\nimport { sameAnchor, sameCreationDraftAnchor } from './annotation-anchors';\n\nexport interface AnnotationMenuProps {\n  children: React.ReactNode;\n  /** Gap in screen px between the selection box and the menu (default 15). */\n  gap?: number;\n  /** Where to place the menu relative to the selection box. Default 'top'. */\n  placement?: AnchoredPlacement;\n}\n\n/**\n * Floats over the current annotation selection (one anchor regardless of\n * cross-page selection), dodging the rotate knob. Compose the contents from\n * hooks: `useAnnotation()` for the verbs, `useAnnotationSelected()` /\n * `useSelectionProps()` for the data.\n */\nexport function AnnotationMenu({ children, gap = 15, placement = 'top' }: AnnotationMenuProps) {\n  // Reading the binding subscribes this component to projection changes\n  // (its identity IS the revision), so the anchor read below re-runs with\n  // fresh view facts in the SAME commit as the surface — the knob offset is\n  // screen-constant, so its content-space position depends on the page's\n  // live view scale.\n  const { projector } = useProjectorBinding();\n  const anchor = useSelector(\n    AnnotationHostToken,\n    (c) => {\n      const a = c.selectionAnchor();\n      if (!a) return null;\n      const env = projector.viewEnv(a.pon);\n      return env ? c.selectionAnchor(env.scale, env.rotation, env.zoom) : a;\n    },\n    sameAnchor,\n  );\n  if (!anchor) return null;\n  return (\n    <Anchored\n      anchor={{\n        pon: anchor.pon,\n        bounds: anchor.bounds,\n        ...(anchor.knob ? { avoid: [anchor.knob] } : {}),\n      }}\n      placement={placement}\n      gap={gap}\n    >\n      {children}\n    </Anchored>\n  );\n}\n\nexport interface AnnotationDraftMenuProps {\n  /** Render prop receiving the DRAFT ANCHOR'S DATA (subtype, pointCount,\n   *  minPoints, canFinish, …). The verbs are capability calls:\n   *  `useAnnotation().finishCreationDraft()` / `.cancelCreationDraft()`. */\n  children: (anchor: CreationDraftAnchor) => React.ReactNode;\n  /** Gap in screen px between the draft anchor and the menu (default 8). */\n  gap?: number;\n  /** Where to place the menu relative to the draft anchor. Default 'top'. */\n  placement?: AnchoredPlacement;\n}\n\n/** Floats over a live multi-click creation draft (polygon, polyline, …). */\nexport function AnnotationDraftMenu({\n  children,\n  gap = 8,\n  placement = 'top',\n}: AnnotationDraftMenuProps) {\n  const anchor = useSelector(\n    AnnotationHostToken,\n    (c) => c.creationDraftAnchor(),\n    sameCreationDraftAnchor,\n  );\n  if (!anchor) return null;\n  return (\n    <Anchored anchor={anchor} placement={placement} gap={gap}>\n      {children(anchor)}\n    </Anchored>\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCA,SAAgB,eAAe,EAAE,UAAU,MAAM,IAAI,YAAY,SAA8B;CAM7F,MAAM,EAAE,cAAcA,iBAAAA,oBAAoB;CAC1C,MAAM,SAASC,gBAAAA,YACbC,0CAAAA,kBACC,MAAM;EACL,MAAM,IAAI,EAAE,gBAAgB;EAC5B,IAAI,CAAC,GAAG,OAAO;EACf,MAAM,MAAM,UAAU,QAAQ,EAAE,GAAG;EACnC,OAAO,MAAM,EAAE,gBAAgB,IAAI,OAAO,IAAI,UAAU,IAAI,IAAI,IAAI;CACtE,GACAC,2BAAAA,UACF;CACA,IAAI,CAAC,QAAQ,OAAO;CACpB,OACE,iBAAA,GAAA,kBAAA,IAAA,CAACC,iBAAAA,UAAD;EACE,QAAQ;GACN,KAAK,OAAO;GACZ,QAAQ,OAAO;GACf,GAAI,OAAO,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,EAAE,IAAI,CAAC;EAChD;EACW;EACN;EAEJ;CACO,CAAA;AAEd;;AAcA,SAAgB,oBAAoB,EAClC,UACA,MAAM,GACN,YAAY,SACe;CAC3B,MAAM,SAASH,gBAAAA,YACbC,0CAAAA,kBACC,MAAM,EAAE,oBAAoB,GAC7BG,2BAAAA,uBACF;CACA,IAAI,CAAC,QAAQ,OAAO;CACpB,OACE,iBAAA,GAAA,kBAAA,IAAA,CAACD,iBAAAA,UAAD;EAAkB;EAAmB;EAAgB;EAClD,UAAA,SAAS,MAAM;CACR,CAAA;AAEd"}

package/dist/annotation-menu.js

@@ -1,9 +1,9 @@
 import { useSelector } from "./runtime.js";
 import { Anchored, useProjectorBinding } from "./anchored.js";
-import { sameAnchor, sameCreationDraftAnchor } from "./annotation.js";
+import { n as sameCreationDraftAnchor, t as sameAnchor } from "./annotation-anchors-CetwM1g7.js";
 import { jsx } from "react/jsx-runtime";
 import "react";
-import { AnnotationToken } from "@embedpdf/plugin-annotation/internal";
+import { AnnotationToken } from "@embedpdf/plugin-annotation/contract/host";
 //#region src/annotation-menu.tsx
 /**
 * Floats over the current annotation selection (one anchor regardless of

package/dist/annotation-menu.js.map

@@ -1 +1 @@
-{"version":3,"file":"annotation-menu.js","names":["AnnotationHostToken"],"sources":["../src/annotation-menu.tsx"],"sourcesContent":["/**\n * Annotation menus — thin anchor plumbing over the ONE `<Anchored>` primitive.\n *\n * These work identically under `<Stage>` (mount in the overlay slot; the\n * camera projects, no DOM reads) and `<PageView>` (measured + portalled) —\n * the SURFACE provides the projector, the menu doesn't care.\n *\n * No action bags: actions come from the capability hooks (`useAnnotation()`,\n * `useAnnotationSelected()`, …), which subscribe properly and compose across\n * plugins. Render props carry only the ANCHOR'S DATA (the draft menu's\n * progress facts); the annotation-selection menu takes plain children.\n */\nimport * as React from 'react';\nimport { AnnotationToken as AnnotationHostToken } from '@embedpdf/plugin-annotation/internal';\nimport type { CreationDraftAnchor } from '@embedpdf/core-annotation';\nimport { Anchored, useProjectorBinding, type AnchoredPlacement } from './anchored';\nimport { useSelector } from './runtime';\nimport { sameAnchor, sameCreationDraftAnchor } from './annotation';\n\nexport interface AnnotationMenuProps {\n  children: React.ReactNode;\n  /** Gap in screen px between the selection box and the menu (default 15). */\n  gap?: number;\n  /** Where to place the menu relative to the selection box. Default 'top'. */\n  placement?: AnchoredPlacement;\n}\n\n/**\n * Floats over the current annotation selection (one anchor regardless of\n * cross-page selection), dodging the rotate knob. Compose the contents from\n * hooks: `useAnnotation()` for the verbs, `useAnnotationSelected()` /\n * `useSelectionProps()` for the data.\n */\nexport function AnnotationMenu({ children, gap = 15, placement = 'top' }: AnnotationMenuProps) {\n  // Reading the binding subscribes this component to projection changes\n  // (its identity IS the revision), so the anchor read below re-runs with\n  // fresh view facts in the SAME commit as the surface — the knob offset is\n  // screen-constant, so its content-space position depends on the page's\n  // live view scale.\n  const { projector } = useProjectorBinding();\n  const anchor = useSelector(\n    AnnotationHostToken,\n    (c) => {\n      const a = c.selectionAnchor();\n      if (!a) return null;\n      const env = projector.viewEnv(a.pon);\n      return env ? c.selectionAnchor(env.scale, env.rotation, env.zoom) : a;\n    },\n    sameAnchor,\n  );\n  if (!anchor) return null;\n  return (\n    <Anchored\n      anchor={{\n        pon: anchor.pon,\n        bounds: anchor.bounds,\n        ...(anchor.knob ? { avoid: [anchor.knob] } : {}),\n      }}\n      placement={placement}\n      gap={gap}\n    >\n      {children}\n    </Anchored>\n  );\n}\n\nexport interface AnnotationDraftMenuProps {\n  /** Render prop receiving the DRAFT ANCHOR'S DATA (subtype, pointCount,\n   *  minPoints, canFinish, …). The verbs are capability calls:\n   *  `useAnnotation().finishCreationDraft()` / `.cancelCreationDraft()`. */\n  children: (anchor: CreationDraftAnchor) => React.ReactNode;\n  /** Gap in screen px between the draft anchor and the menu (default 8). */\n  gap?: number;\n  /** Where to place the menu relative to the draft anchor. Default 'top'. */\n  placement?: AnchoredPlacement;\n}\n\n/** Floats over a live multi-click creation draft (polygon, polyline, …). */\nexport function AnnotationDraftMenu({\n  children,\n  gap = 8,\n  placement = 'top',\n}: AnnotationDraftMenuProps) {\n  const anchor = useSelector(\n    AnnotationHostToken,\n    (c) => c.creationDraftAnchor(),\n    sameCreationDraftAnchor,\n  );\n  if (!anchor) return null;\n  return (\n    <Anchored anchor={anchor} placement={placement} gap={gap}>\n      {children(anchor)}\n    </Anchored>\n  );\n}\n"],"mappings":";;;;;;;;;;;;;AAiCA,SAAgB,eAAe,EAAE,UAAU,MAAM,IAAI,YAAY,SAA8B;CAM7F,MAAM,EAAE,cAAc,oBAAoB;CAC1C,MAAM,SAAS,YACbA,kBACC,MAAM;EACL,MAAM,IAAI,EAAE,gBAAgB;EAC5B,IAAI,CAAC,GAAG,OAAO;EACf,MAAM,MAAM,UAAU,QAAQ,EAAE,GAAG;EACnC,OAAO,MAAM,EAAE,gBAAgB,IAAI,OAAO,IAAI,UAAU,IAAI,IAAI,IAAI;CACtE,GACA,UACF;CACA,IAAI,CAAC,QAAQ,OAAO;CACpB,OACE,oBAAC,UAAD;EACE,QAAQ;GACN,KAAK,OAAO;GACZ,QAAQ,OAAO;GACf,GAAI,OAAO,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,EAAE,IAAI,CAAC;EAChD;EACW;EACN;EAEJ;CACO,CAAA;AAEd;;AAcA,SAAgB,oBAAoB,EAClC,UACA,MAAM,GACN,YAAY,SACe;CAC3B,MAAM,SAAS,YACbA,kBACC,MAAM,EAAE,oBAAoB,GAC7B,uBACF;CACA,IAAI,CAAC,QAAQ,OAAO;CACpB,OACE,oBAAC,UAAD;EAAkB;EAAmB;EAAgB;EAClD,UAAA,SAAS,MAAM;CACR,CAAA;AAEd"}
+{"version":3,"file":"annotation-menu.js","names":["AnnotationHostToken"],"sources":["../src/annotation-menu.tsx"],"sourcesContent":["/**\n * Annotation menus — thin anchor plumbing over the ONE `<Anchored>` primitive.\n *\n * These work identically under `<Stage>` (mount in the overlay slot; the\n * camera projects, no DOM reads) and `<PageView>` (measured + portalled) —\n * the SURFACE provides the projector, the menu doesn't care.\n *\n * No action bags: actions come from the capability hooks (`useAnnotation()`,\n * `useAnnotationSelected()`, …), which subscribe properly and compose across\n * plugins. Render props carry only the ANCHOR'S DATA (the draft menu's\n * progress facts); the annotation-selection menu takes plain children.\n */\nimport * as React from 'react';\nimport { AnnotationToken as AnnotationHostToken } from '@embedpdf/plugin-annotation/contract/host';\nimport type { CreationDraftAnchor } from '@embedpdf/core-annotation';\nimport { Anchored, useProjectorBinding, type AnchoredPlacement } from './anchored';\nimport { useSelector } from './runtime';\nimport { sameAnchor, sameCreationDraftAnchor } from './annotation-anchors';\n\nexport interface AnnotationMenuProps {\n  children: React.ReactNode;\n  /** Gap in screen px between the selection box and the menu (default 15). */\n  gap?: number;\n  /** Where to place the menu relative to the selection box. Default 'top'. */\n  placement?: AnchoredPlacement;\n}\n\n/**\n * Floats over the current annotation selection (one anchor regardless of\n * cross-page selection), dodging the rotate knob. Compose the contents from\n * hooks: `useAnnotation()` for the verbs, `useAnnotationSelected()` /\n * `useSelectionProps()` for the data.\n */\nexport function AnnotationMenu({ children, gap = 15, placement = 'top' }: AnnotationMenuProps) {\n  // Reading the binding subscribes this component to projection changes\n  // (its identity IS the revision), so the anchor read below re-runs with\n  // fresh view facts in the SAME commit as the surface — the knob offset is\n  // screen-constant, so its content-space position depends on the page's\n  // live view scale.\n  const { projector } = useProjectorBinding();\n  const anchor = useSelector(\n    AnnotationHostToken,\n    (c) => {\n      const a = c.selectionAnchor();\n      if (!a) return null;\n      const env = projector.viewEnv(a.pon);\n      return env ? c.selectionAnchor(env.scale, env.rotation, env.zoom) : a;\n    },\n    sameAnchor,\n  );\n  if (!anchor) return null;\n  return (\n    <Anchored\n      anchor={{\n        pon: anchor.pon,\n        bounds: anchor.bounds,\n        ...(anchor.knob ? { avoid: [anchor.knob] } : {}),\n      }}\n      placement={placement}\n      gap={gap}\n    >\n      {children}\n    </Anchored>\n  );\n}\n\nexport interface AnnotationDraftMenuProps {\n  /** Render prop receiving the DRAFT ANCHOR'S DATA (subtype, pointCount,\n   *  minPoints, canFinish, …). The verbs are capability calls:\n   *  `useAnnotation().finishCreationDraft()` / `.cancelCreationDraft()`. */\n  children: (anchor: CreationDraftAnchor) => React.ReactNode;\n  /** Gap in screen px between the draft anchor and the menu (default 8). */\n  gap?: number;\n  /** Where to place the menu relative to the draft anchor. Default 'top'. */\n  placement?: AnchoredPlacement;\n}\n\n/** Floats over a live multi-click creation draft (polygon, polyline, …). */\nexport function AnnotationDraftMenu({\n  children,\n  gap = 8,\n  placement = 'top',\n}: AnnotationDraftMenuProps) {\n  const anchor = useSelector(\n    AnnotationHostToken,\n    (c) => c.creationDraftAnchor(),\n    sameCreationDraftAnchor,\n  );\n  if (!anchor) return null;\n  return (\n    <Anchored anchor={anchor} placement={placement} gap={gap}>\n      {children(anchor)}\n    </Anchored>\n  );\n}\n"],"mappings":";;;;;;;;;;;;;AAiCA,SAAgB,eAAe,EAAE,UAAU,MAAM,IAAI,YAAY,SAA8B;CAM7F,MAAM,EAAE,cAAc,oBAAoB;CAC1C,MAAM,SAAS,YACbA,kBACC,MAAM;EACL,MAAM,IAAI,EAAE,gBAAgB;EAC5B,IAAI,CAAC,GAAG,OAAO;EACf,MAAM,MAAM,UAAU,QAAQ,EAAE,GAAG;EACnC,OAAO,MAAM,EAAE,gBAAgB,IAAI,OAAO,IAAI,UAAU,IAAI,IAAI,IAAI;CACtE,GACA,UACF;CACA,IAAI,CAAC,QAAQ,OAAO;CACpB,OACE,oBAAC,UAAD;EACE,QAAQ;GACN,KAAK,OAAO;GACZ,QAAQ,OAAO;GACf,GAAI,OAAO,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,EAAE,IAAI,CAAC;EAChD;EACW;EACN;EAEJ;CACO,CAAA;AAEd;;AAcA,SAAgB,oBAAoB,EAClC,UACA,MAAM,GACN,YAAY,SACe;CAC3B,MAAM,SAAS,YACbA,kBACC,MAAM,EAAE,oBAAoB,GAC7B,uBACF;CACA,IAAI,CAAC,QAAQ,OAAO;CACpB,OACE,oBAAC,UAAD;EAAkB;EAAmB;EAAgB;EAClD,UAAA,SAAS,MAAM;CACR,CAAA;AAEd"}

package/dist/annotation.cjs

@@ -1,6 +1,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_rolldown_runtime = require("./rolldown-runtime-DDXJien1.cjs");
 const require_runtime = require("./runtime.cjs");
+const require_annotation_anchors = require("./annotation-anchors-DuYRBJLl.cjs");
+const require_annotation_hooks = require("./annotation-hooks-BB5ZhPpf.cjs");
 let react_jsx_runtime = require("react/jsx-runtime");
 let react = require("react");
 react = require_rolldown_runtime.__toESM(react, 1);
@@ -163,22 +165,31 @@ function ToolGhostImage({ page }) {
 	const ghost = require_runtime.useSelector(_embedpdf_plugin_annotation_internal.AnnotationToken, (c) => c.toolGhost(page.pon));
 	const epoch = require_runtime.useSelector(_embedpdf_plugin_annotation_internal.AnnotationToken, (c) => c.stampArmEpoch());
 	const [url, setUrl] = (0, react.useState)(null);
+	const bucket = ghost?.kind === "image" ? (0, _embedpdf_plugin_annotation.previewBucket)(ghost.box.width * page.transform.renderScale) : 0;
 	(0, react.useEffect)(() => {
-		const preview = anno.armedStampPreview();
-		if (!preview) {
+		if (!bucket) {
 			setUrl(null);
 			return;
 		}
-		const body = new ArrayBuffer(preview.bytes.byteLength);
-		new Uint8Array(body).set(preview.bytes);
-		const blob = new Blob([body], preview.mimeType ? { type: preview.mimeType } : {});
-		const obj = URL.createObjectURL(blob);
-		setUrl(obj);
+		let cancelled = false;
+		let obj = null;
+		anno.armedStampPreview(bucket).then((preview) => {
+			if (cancelled || !preview) return;
+			const body = new ArrayBuffer(preview.bytes.byteLength);
+			new Uint8Array(body).set(preview.bytes);
+			const blob = new Blob([body], preview.mimeType ? { type: preview.mimeType } : {});
+			obj = URL.createObjectURL(blob);
+			setUrl(obj);
+		});
 		return () => {
-			URL.revokeObjectURL(obj);
-			setUrl(null);
+			cancelled = true;
+			if (obj) URL.revokeObjectURL(obj);
 		};
-	}, [anno, epoch]);
+	}, [
+		anno,
+		epoch,
+		bucket
+	]);
 	if (!ghost || ghost.kind !== "image" || !url) return null;
 	const b = boxOf(ghost.box, page);
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("img", {
@@ -635,10 +646,6 @@ function useAnnotation() {
 function useAnnotationSelection() {
 	return require_runtime.useSelector(_embedpdf_plugin_annotation.AnnotationToken, (c) => c.selection(), require_runtime.shallowArray);
 }
-/** The selected annotations as engine DTOs — for selection-aware toolbars/sidebars. */
-function useAnnotationSelected() {
-	return require_runtime.useSelector(_embedpdf_plugin_annotation.AnnotationToken, (c) => c.getSelected(), require_runtime.shallowArray);
-}
 /** Structural equality for a resolved props bag — keeps the subscription from
 *  re-rendering on unrelated dispatches, since `currentDefaults` returns a fresh
 *  object each call. Small flat objects; JSON compare is exact and cheap here. */
@@ -720,27 +727,15 @@ function useCommentThread(ref) {
 function useCommentsHydration() {
 	return require_runtime.useSelector(_embedpdf_plugin_annotation.AnnotationToken, (c) => c.comments.hydration());
 }
-/** Structural equality for the selection anchor — keeps the menu from re-rendering
-*  on unrelated dispatches (the capability returns a fresh object each call). */
-function sameAnchor(a, b) {
-	if (a === b) return true;
-	if (!a || !b) return false;
-	return a.pon === b.pon && a.bounds.x === b.bounds.x && a.bounds.y === b.bounds.y && a.bounds.width === b.bounds.width && a.bounds.height === b.bounds.height && a.knob?.x === b.knob?.x && a.knob?.y === b.knob?.y;
-}
-function sameCreationDraftAnchor(a, b) {
-	if (a === b) return true;
-	if (!a || !b) return false;
-	return a.kind === b.kind && a.subtype === b.subtype && a.pon === b.pon && a.pointCount === b.pointCount && a.minPoints === b.minPoints && a.canFinish === b.canFinish && a.bounds.x === b.bounds.x && a.bounds.y === b.bounds.y && a.bounds.width === b.bounds.width && a.bounds.height === b.bounds.height;
-}
 //#endregion
 exports.AnnotationLayer = AnnotationLayer;
 exports.enrichCommentThreads = enrichCommentThreads;
 exports.filePickerProvider = filePickerProvider;
-exports.sameAnchor = sameAnchor;
-exports.sameCreationDraftAnchor = sameCreationDraftAnchor;
+exports.sameAnchor = require_annotation_anchors.sameAnchor;
+exports.sameCreationDraftAnchor = require_annotation_anchors.sameCreationDraftAnchor;
 exports.useAnnotation = useAnnotation;
 exports.useAnnotationDefaults = useAnnotationDefaults;
-exports.useAnnotationSelected = useAnnotationSelected;
+exports.useAnnotationSelected = require_annotation_hooks.useAnnotationSelected;
 exports.useAnnotationSelection = useAnnotationSelection;
 exports.useCommentThread = useCommentThread;
 exports.useCommentThreads = useCommentThreads;