@embedpdf/plugin-annotation 3.0.0-next.1 → 3.0.0-next.11

package/dist/{types-Da6JRmhw.d.ts → types-eLTpocXz.d.cts}

@@ -1,6 +1,7 @@
-import { PageObjectNumber } from "@embedpdf/core";
-import { AnnotationAppearanceImage, AnnotationDTO, AnnotationDraft, AnnotationPatch, AnnotationRef, AttachmentContent, AttachmentFileSource, BinarySource, InkIntent, PdfLinkTarget, PdfRect } from "@embedpdf/engine-core/runtime";
-import { AnnotationFlags, AnnotationProps, AnnotationPropsPatch, ChromeNode, ClickCreate, CreationDraftAnchor, Geom, Id, InkStraightenOptions, Model, PropKey, PropSpec, Rect, RenderItem, SnapSettings, Subtype, Vec, ViewEnv } from "@embedpdf/core-annotation";
+import { AnnotationFlags, AnnotationProps, AnnotationPropsPatch, ChromeNode, ClickCreate, CreationDraftAnchor, Geom, Id, InkStraightenOptions, Model, PropKey, PropSpec, Rect, RenderItem, SnapSettings, Subtype, TextEndAnchor, TextQuad, Vec, ViewEnv } from "@embedpdf/core-annotation";
+import { AnnotationAppearanceImage, AnnotationDTO, AnnotationDraft, AnnotationPatch, AnnotationRef, AttachmentContent, AttachmentFileSource, BinarySource, CommentThread, InkIntent, PdfActionTree, PdfLinkTarget, PdfRect } from "@embedpdf/engine-core/runtime";
+import { DocumentEvent, PageObjectNumber } from "@embedpdf/core";
+import { AnnotCommitEntry, AnnotCommitResult } from "@embedpdf/plugin-actions/contract/host";
 import { PageRotation } from "@embedpdf/core-geometry";
 //#region src/tools.d.ts
 /**
@@ -315,8 +316,28 @@ interface ChromeSettingsPatch {
   knob?: Partial<ChromeSettings['knob']>;
   guides?: Partial<ChromeSettings['guides']>;
 }
+/**
+ * Whole-document annotation hydration. The plugin always hydrates ALL
+ * pages through `doc.annotations.listRawAll()` (one bulk request on
+ * cloud, one worker job locally) — a comments sidebar needs every page,
+ * and per-page lazy loading could never truthfully claim completeness.
+ * `loading` covers the initial ingest AND a desync re-ingest; `error`
+ * means live events still apply but the whole-document view is
+ * incomplete until a rehydrate succeeds.
+ */
+type AnnotationHydration = {
+  status: 'loading';
+} | {
+  status: 'complete';
+} | {
+  status: 'error';
+  error: unknown;
+} | {
+  status: 'forbidden';
+};
 interface AnnotationState {
   model: Model;
+  hydration: AnnotationHydration;
   chrome: ChromeSettings;
   /**
    * The armed tool's FOOTPRINT ghost: where (and what) the NEXT click would
@@ -377,6 +398,9 @@ interface AnnotationConfig {
 type AnnotationAction = {
   type: 'SET_MODEL';
   model: Model;
+} | {
+  type: 'SET_HYDRATION';
+  hydration: AnnotationHydration;
 } | {
   type: 'SET_CHROME';
   patch: ChromeSettingsPatch;
@@ -398,6 +422,27 @@ interface LinkNavItem {
   id: string;
   rect: Rect;
   target: PdfLinkTarget;
+  /**
+   * True for a link CHILD riding an editable annotation (an `/RT /Group`
+   * subordinate) — a PROPERTY of its parent while authoring, a nav behavior
+   * only while reading. The nav layer stands its anchors down for attached
+   * items whenever the active tool enables `annotation-edit`, so the parent
+   * stays selectable/movable; standalone document links navigate regardless.
+   */
+  attached: boolean;
+  /** The full payload-carrying `/A` tree, when one exists — the action
+   *  engine's dispatch input. `target` remains its root projection. */
+  activate?: PdfActionTree;
+  /** The annotation ref, carried for ActionSource context. */
+  ref?: AnnotationRef;
+  /** Which `/AA` hover trees this link carries — the nav layer's pump flags
+   *  (tree-less hover must cost zero dispatches). Links are behavior-inert
+   *  to the annotation plane's hover feed while navigable, so THEIR
+   *  cursorEnter/cursorExit can only fire from the LinkLayer anchors. */
+  hoverEvents?: {
+    enter: boolean;
+    exit: boolean;
+  };
 }
 interface Behavior {
   id: string;
@@ -459,11 +504,91 @@ interface TextItem {
  * package root (`@embedpdf/plugin-annotation`).
  *
  * Framework-only plumbing (render projection, pointer gestures, behavior
- * registration) lives on {@link AnnotationHostCapability}, reachable only through
- * the `@embedpdf/plugin-annotation/internal` entry. Both are the SAME runtime
+ * registration) lives on {@link AnnotationHostCapability}, reachable through
+ * `@embedpdf/plugin-annotation/contract/host` (and the framework's `/internal`
+ * entry). Both are the SAME runtime
  * object — two typed lenses on one token — so app code simply can't see the host
  * methods.
  */
+/**
+ * Per-thread action gates, composed from two axes: authority (the
+ * engine's collab-resolver mirrors — `allowsAnnotationCreate` for
+ * reply/status, `allowsAnnotationMutation` against each target's
+ * stamped owner for edit/delete) and PDF state (the two lock flags
+ * gate DIFFERENT aspects, ISO 32000 Table 167: `lockedContents` blocks
+ * text edits, `locked` blocks deletion). A courtesy, not the guard — the
+ * engine independently enforces every write.
+ */
+interface CommentPermissions {
+  /** A reply is an annotation CREATE. */
+  canReply: boolean;
+  /** Editing this comment's text (`contents`) — gated by `lockedContents`. */
+  canEditText: boolean;
+  /** Deleting this one annotation — gated by `locked`. */
+  canDelete: boolean;
+  /** A status change is a NEW hidden annotation — create authority only,
+   *  never edit rights on someone else's comment. */
+  canSetStatus: boolean;
+  /** `canDelete` over EVERY thread member (root, replies, grouped parts,
+   *  state annotations) — the whole-thread preflight. */
+  canDeleteThread: boolean;
+}
+interface ThreadDeleteResult {
+  deleted: AnnotationRef[];
+  failed: Array<{
+    ref: AnnotationRef;
+    error: unknown;
+  }>;
+}
+/**
+ * The conversation plane's surface: a derived, memoized threads index over
+ * the annotation substrate, plus the ISO-native verbs. Every verb compiles
+ * down to plain annotation creates/patches/deletes — one optimistic
+ * pipeline, no second write path — so remote SSE events, own edits, and
+ * hydration all update `threads()` for free.
+ *
+ * Threads carry `pageObjectNumber` (identity is PON, like everything
+ * else); DISPLAY order is a behavior of `threads()` (sorted against the
+ * live layout at computation time), and display labels (`pageIndex`) are a
+ * framework-hook enrichment — the layer that watches both stores.
+ */
+interface CommentsApi {
+  /** Every comment thread in the document, display-ordered, memoized. */
+  threads(): CommentThread[];
+  /** The thread containing ANY member ref (root, reply, grouped part, or
+   *  state annotation), or null. */
+  thread(ref: AnnotationRef): CommentThread | null;
+  /** Whole-document hydration status (the sidebar's honest loading state). */
+  hydration(): AnnotationHydration;
+  /** Re-run whole-document hydration (desync recovery / manual refresh). */
+  rehydrate(): Promise<void>;
+  /** Reply to a thread. Writes FLAT (`/IRT` → the thread root, ISO reply
+   *  type), whatever member was passed — presentation stays one level. */
+  reply(ref: AnnotationRef, text: string): Promise<AnnotationRef>;
+  /** Edit a comment's text. Appearance-inert for every kind except
+   *  free-text and redaction (whose `/AP` paints `/Contents`). */
+  edit(ref: AnnotationRef, text: string): Promise<void>;
+  /**
+   * Set this session's review status on the thread (ISO 32000 §12.5.6.3):
+   * creates a hidden state annotation chained to the caller's previous
+   * status when one exists, else to the root. The target annotation is
+   * never modified. Known states: accepted / rejected / cancelled /
+   * completed / none (custom vocabularies ride the raw create API).
+   */
+  setStatus(ref: AnnotationRef, state: string): Promise<void>;
+  /** Toggle this session's Marked-model checkmark on the thread. */
+  setMarked(ref: AnnotationRef, marked: boolean): Promise<void>;
+  /** Delete exactly ONE annotation (a reply, a status, or a bare root). */
+  remove(ref: AnnotationRef): Promise<void>;
+  /**
+   * Delete a WHOLE thread, children first. Preflighted: when any member
+   * fails the delete gate the call returns every blocked ref as `failed`
+   * and deletes nothing; mid-flight races surface the same way.
+   */
+  removeThread(ref: AnnotationRef): Promise<ThreadDeleteResult>;
+  /** Truthful per-thread action gates for the ref's thread. */
+  permissionsFor(ref: AnnotationRef): CommentPermissions;
+}
 interface AnnotationCapability {
   /**
    * Create an annotation on a page. `draft` is the engine-core draft for its
@@ -515,9 +640,27 @@ interface AnnotationCapability {
    *  free-text kind). Drives the same sidebar when nothing is selected, paired
    *  with {@link currentDefaults}/{@link setDefaults}. */
   propsForTool(toolId: string): PropSpec[];
+  canRead(): boolean;
   canCreate(): boolean;
   canEdit(ref: AnnotationRef): boolean;
   canDelete(ref: AnnotationRef): boolean;
+  /** The conversation plane's read/write surface — see {@link CommentsApi}. */
+  comments: CommentsApi;
+  /**
+   * The attached-link lens: an annotation's link is a `/Link` CHILD grouped
+   * under it in the document (ISO-native, Acrobat-interoperable) — a
+   * PROPERTY while authoring, a nav BEHAVIOR while reading. `of` derives
+   * from the committed children (the one source of truth); `set`/`clear`
+   * resolve when the children are committed, after which `of` reflects the
+   * change. `updateSelection({ link })` remains the props-pipeline alias.
+   * On the link KIND itself, `of` reads the annotation's own `/A` target
+   * (retarget standalone links via `updateSelection`).
+   */
+  links: {
+    of(ref: AnnotationRef): PdfLinkTarget | null;
+    set(ref: AnnotationRef, target: PdfLinkTarget): Promise<void>;
+    clear(ref: AnnotationRef): Promise<void>;
+  };
   /** The annotation for a ref, or null if unknown / not yet committed. */
   get(ref: AnnotationRef): AnnotationDTO | null;
   /** Every committed annotation on a page, in z-order. */
@@ -604,6 +747,21 @@ interface AnnotationCapability {
    * (`extends`, per-tool `defaults`, …). Returns an unregister fn.
    */
   registerTool(def: AnnotationToolInput): () => void;
+  /**
+   * Turn the CURRENT text selection into markup annotations — one per
+   * selected page, from the selection's oriented per-line quads — then clear
+   * the selection. The one-call form of what the markup tools do on
+   * commit, made for selection-menu buttons ("Highlight") and automation.
+   * `preset` is a tool id whose defaults style the markup (e.g.
+   * `'highlight'`); defaults to the subtype's own. Returns false (and does
+   * nothing) when no selection plugin is installed or nothing is selected.
+   */
+  markupFromSelection(subtype: Subtype, preset?: string): boolean;
+  /** Commit the in-progress multi-click creation draft (no-op when there is
+   *  none, or it can't finish yet — see `creationDraftAnchor().canFinish`). */
+  finishCreationDraft(): void;
+  /** Discard the in-progress multi-click creation draft. */
+  cancelCreationDraft(): void;
   deleteSelection(): void;
   deselect(): void;
   cancel(): void;
@@ -675,8 +833,9 @@ type FilePickerProvider = (req: FilePromptRequest) => Promise<AttachmentFileSour
 /**
  * The HOST (framework) surface: everything the render layer, the interaction hub,
  * and sibling plugins need, on top of the public {@link AnnotationCapability}.
- * Internal — import the token from `@embedpdf/plugin-annotation/internal`, never
- * from application code.
+ * Host-only — sibling plugins import the token from
+ * `@embedpdf/plugin-annotation/contract/host`; framework implementation code may
+ * use `/internal`. Never use either from application code.
  */
 interface AnnotationHostCapability extends AnnotationCapability {
   /** `view` (the page's scale + total display rotation, from its transform)
@@ -723,6 +882,9 @@ interface AnnotationHostCapability extends AnnotationCapability {
    *  the renderer places the baked bitmap by its OWN `/Rect` without touching the
    *  PDF↔content seam. Null if the page's crop box is unknown. */
   toContentBox(pon: PageObjectNumber, rect: PdfRect): Rect | null;
+  /** No-op since whole-document hydration: the model is seeded by
+   *  `listRawAll()` at document open. Kept as API for layers that call it
+   *  on page mount. */
   ensurePage(pon: PageObjectNumber): void;
   /**
    * Drop and RE-READ one page's annotations from the engine — the hook for
@@ -732,6 +894,21 @@ interface AnnotationHostCapability extends AnnotationCapability {
    * created.
    */
   reloadPage(pon: PageObjectNumber): Promise<void>;
+  /** Live hydration status — `loading` covers initial ingest AND a desync
+   *  re-ingest. */
+  hydration(): AnnotationHydration;
+  /** Kick hydration exactly once per document; the effects layer calls
+   *  this at registration. Subsequent calls no-op. */
+  ensureHydrated(): void;
+  /** Re-run whole-document hydration (desync recovery). Safe to call while
+   *  one is in flight — the fresh run is chained after it. */
+  rehydrate(): Promise<void>;
+  /**
+   * The effects layer hands every REMOTE `annotation.*` event here: during
+   * a hydration window it queues (replayed by audit cursor after ingest —
+   * the delete-resurrection guard); otherwise it applies immediately.
+   */
+  deliverRemoteAnnotationEvent(event: DocumentEvent): void;
   /** The free-text boxes on a page, ready to render as editable elements.
    *  `view` as in {@link pageItems}. */
   textItems(pon: PageObjectNumber, view?: ViewEnv): TextItem[];
@@ -741,8 +918,11 @@ interface AnnotationHostCapability extends AnnotationCapability {
   /** Enter text-edit on a free-text annotation (focus its editable element). */
   beginTextEdit(ref: AnnotationRef): void;
   /** Enter text-edit on whatever free-text box is under a content point — wired
-   *  to a double-click by the interaction edit handler. */
-  beginTextEditAt(pon: PageObjectNumber, point: Vec, scale?: number, rotation?: PageRotation, zoom?: number): void;
+   *  to a double-click / long-press by the interaction edit handler. Returns
+   *  whether an editable free-text was actually found and opened; false lets
+   *  the caller fall through to a normal press (so a long-press on a highlight
+   *  selects it instead of being swallowed by a no-op edit attempt). */
+  beginTextEditAt(pon: PageObjectNumber, point: Vec, scale?: number, rotation?: PageRotation, zoom?: number): boolean;
   /** Apply the editor's plain text — optimistic locally, debounced to the engine. */
   setContents(ref: AnnotationRef, text: string): void;
   /** Leave text-edit (flush any pending write). */
@@ -752,7 +932,19 @@ interface AnnotationHostCapability extends AnnotationCapability {
    *  screen-constant; `rotation` + `zoom` (relative, `transform.zoom`)
    *  complete the view env for screen-anchored bodies. Pass all three from
    *  the pointer sample. */
-  hitKind(pon: PageObjectNumber, point: Vec, scale?: number, rotation?: PageRotation, zoom?: number): 'handle' | 'rotate' | 'group-handle' | 'annot' | 'empty';
+  hitKind(pon: PageObjectNumber, point: Vec, scale?: number, rotation?: PageRotation, zoom?: number,
+  /** Widen grab zones to finger-sized targets (pass `pointerType === 'touch'`). */
+  touch?: boolean): 'handle' | 'rotate' | 'group-handle' | 'annot' | 'empty';
+  /**
+   * TOUCH CONSENT (the interaction hub's `claimsTouch` predicate): should a
+   * finger landing here own a TOOL gesture instead of navigating? True over
+   * the selection's chrome (resize handles, rotate knob, group box) and over
+   * the body of an already-SELECTED, transformable annotation — never over an
+   * unselected one, so annotation-dense pages still scroll; tap-select first
+   * is the platform convention (Apple Markup). Uses finger-sized grab zones.
+   * Pure read.
+   */
+  claimsTouchAt(pon: PageObjectNumber, point: Vec, scale?: number, rotation?: PageRotation, zoom?: number): boolean;
   /** The cursor to show at a content point (resize over a handle, move/pointer over a body, else null). */
   cursorAt(pon: PageObjectNumber, point: Vec, scale?: number, rotation?: PageRotation, zoom?: number): string | null;
   /**
@@ -786,27 +978,30 @@ interface AnnotationHostCapability extends AnnotationCapability {
    *  things cannot stay selected. Call after anything that flips engagement
    *  (the plugin wires it to tool changes). */
   pruneEngagedSelection(): void;
-  editPointer(phase: 'down' | 'move' | 'up', pon: PageObjectNumber, point: Vec, shift: boolean, scale?: number, rotation?: PageRotation, zoom?: number): void;
+  editPointer(phase: 'down' | 'move' | 'up', pon: PageObjectNumber, point: Vec, shift: boolean, scale?: number, rotation?: PageRotation, zoom?: number,
+  /** Finger-sized grab zones for the gesture's own hit resolution — pass the
+   *  sample's `pointerType === 'touch'` so the gesture grabs exactly what
+   *  {@link claimsTouchAt} claimed. */
+  touch?: boolean): void;
   marqueePointer(phase: 'down' | 'move' | 'up', pon: PageObjectNumber, point: Vec, shift: boolean, scale?: number, rotation?: PageRotation, zoom?: number): void;
   /** Run the draw gesture for an authoring TOOL (by id). The plugin resolves it
    *  to a routing subtype + defaults preset; a bare subtype also works (headless).
    *  `displayRotation` (the DOWN sample's page rotation: /Rotate + view rotation)
    *  feeds the tool's `upright` policy — omit it and upright is a no-op. */
   createPointer(tool: string, phase: 'down' | 'move' | 'up', pon: PageObjectNumber, point: Vec, finish?: boolean, displayRotation?: PageRotation): void;
-  finishCreationDraft(): void;
   /** Commit the strokes currently buffered by an ink tool's grouping window. */
   finishInkDraft(): void;
-  cancelCreationDraft(): void;
-  /** Create one text-markup annotation on a page from the selected text's per-line
-   *  rects (content space) — the `text-selection` create gesture. */
-  createMarkup(subtype: Subtype, pon: PageObjectNumber, rects: Rect[], preset?: string): void;
-  /** Create a caret annotation from the final line rect of a text selection. */
-  createCaret(pon: PageObjectNumber, textEndRect: Rect): void;
+  /** Create one text-markup annotation on a page from the selected text's
+   *  per-line oriented quads (content space) — the `text-selection` create
+   *  gesture. Axis-aligned callers build quads with `textQuadFromRect`. */
+  createMarkup(subtype: Subtype, pon: PageObjectNumber, quads: TextQuad[], preset?: string): void;
+  /** Create a caret annotation at a text-selection end anchor. */
+  createCaret(pon: PageObjectNumber, anchor: TextEndAnchor): void;
   /** Create one Adobe-compatible Caret + StrikeOut replace-text group. */
-  createReplaceText(pon: PageObjectNumber, rects: Rect[], textEndRect: Rect, preset?: string): void;
-  /** Set the live markup preview from the selection's per-page rects (renders a
+  createReplaceText(pon: PageObjectNumber, quads: TextQuad[], anchor: TextEndAnchor, preset?: string): void;
+  /** Set the live markup preview from the selection's per-page quads (renders a
    *  ghost that looks like the markup it will become). */
-  previewMarkup(subtype: Subtype, rectsByPage: Record<number, Rect[]>, preset?: string): void;
+  previewMarkup(subtype: Subtype, quadsByPage: Record<number, TextQuad[]>, preset?: string): void;
   clearMarkupPreview(): void;
   /** Place the armed stamp centred on a content point. Returns false (no
    *  capture) when nothing is armed. `displayRotation` (the click sample's page
@@ -867,13 +1062,25 @@ interface AnnotationHostCapability extends AnnotationCapability {
    *  gesture and the created annotation's PDF kind. Falls back to the id. */
   toolSubtype(id: string): Subtype;
   registerBehavior(b: Behavior): () => void;
+  /**
+   * The actions plane's session-visibility write (Hide actions, script
+   * `annot.hidden`): resolve annotation OBJECT NUMBERS to loaded model ids
+   * (the `obj:` refKey seam) and merge session-hidden overrides. Returns how
+   * many resolved — unresolved numbers (unloaded pages, nm/index refs) are
+   * the caller's diagnostics. Session state only; never an engine write.
+   */
+  /** The script/Hide DOCUMENT-commit door (full ISO): engine updates +
+   *  model reconciliation, per entry, stop-on-failure. Never enqueues,
+   *  never touches the script host — the D2 sink contract. */
+  commitScriptEffects(entries: AnnotCommitEntry[]): Promise<AnnotCommitResult>;
 }
 /**
  * The annotation capability token. Typed to the full {@link AnnotationHostCapability}
- * here (the package internals + the `/internal` entry use this view). The package
- * root re-exports the SAME token narrowed to {@link AnnotationCapability}.
+ * here (the package internals, `/contract/host`, and `/internal` use this view).
+ * The package root re-exports the SAME token narrowed to
+ * {@link AnnotationCapability}.
  */
 declare const AnnotationToken: import("@embedpdf/core").CapabilityToken<AnnotationHostCapability>;
 //#endregion
-export { PromptSourceSpec as C, ToolAuthoringKind as D, StampSourceSpec as E, ToolDefaultsFor as O, InkAuthoringOptions as S, SelectionAuthoring as T, ToolGhost as _, AnnotationState as a, DEFAULT_TOOLS as b, ChromeSettings as c, FilePromptRequest as d, LinkNavItem as f, TextItem as g, StampToolInput as h, AnnotationHostCapability as i, buildToolRegistry as k, ChromeSettingsPatch as l, SelectionProps as m, AnnotationCapability as n, AnnotationToken as o, SelectionFlags as p, AnnotationConfig as r, Behavior as s, AnnotationAction as t, FilePickerProvider as u, AnnotationToolDef as v, ResolvedTool as w, GhostPolicy as x, AnnotationToolInput as y };
-//# sourceMappingURL=types-Da6JRmhw.d.ts.map
+export { StampSourceSpec as A, AnnotationToolInput as C, PromptSourceSpec as D, InkAuthoringOptions as E, ToolDefaultsFor as M, buildToolRegistry as N, ResolvedTool as O, AnnotationToolDef as S, GhostPolicy as T, SelectionProps as _, AnnotationHydration as a, ThreadDeleteResult as b, Behavior as c, CommentPermissions as d, CommentsApi as f, SelectionFlags as g, LinkNavItem as h, AnnotationHostCapability as i, ToolAuthoringKind as j, SelectionAuthoring as k, ChromeSettings as l, FilePromptRequest as m, AnnotationCapability as n, AnnotationState as o, FilePickerProvider as p, AnnotationConfig as r, AnnotationToken as s, AnnotationAction as t, ChromeSettingsPatch as u, StampToolInput as v, DEFAULT_TOOLS as w, ToolGhost as x, TextItem as y };
+//# sourceMappingURL=types-eLTpocXz.d.cts.map