@embedpdf/plugin-annotation 3.0.0-next.13 → 3.0.0-next.15

package/dist/types-D5V0TIwk.d.ts

@@ -1,1200 +0,0 @@
-import { DocumentEvent, PageObjectNumber } from "@embedpdf/core";
-import { AnnotCommitEntry, AnnotCommitResult } from "@embedpdf/plugin-actions/contract/host";
-import { AnnotationAppearanceImage, AnnotationDTO, AnnotationDraft, AnnotationPatch, AnnotationRef, AttachmentContent, AttachmentFileSource, BinarySource, CommentThread, InkIntent, PdfActionTree, PdfLinkTarget, PdfRect, RichTextParagraph } from "@embedpdf/engine-core/runtime";
-import { Annot, AnnotationFlags, AnnotationProps, AnnotationPropsPatch, ChromeNode, ClickCreate, CreationDraftAnchor, Geom, Id, InkStraightenOptions, Model, PropKey, PropSpec, Rect, RenderItem, RichTextRange, SnapSettings, Subtype, TextEndAnchor, TextQuad, Vec, ViewEnv } from "@embedpdf/core-annotation";
-import { PageRotation } from "@embedpdf/core-geometry";
-//#region src/rich-text.d.ts
-type TextFormat = 'bold' | 'italic' | 'underline';
-/** The editor's selection inside one free-text annotation: flat offsets over
- *  the plain projection (paragraphs joined by `\r`). */
-interface TextSelection extends RichTextRange {
-  id: string;
-}
-/** The face a run or a body names. */
-interface Face {
-  family: string;
-  weight?: number;
-  italic?: boolean;
-}
-//#endregion
-//#region src/tools.d.ts
-/**
- * How a stamp-family tool resolves the image bytes it places — pure DATA, so a
- * tool table stays JSON-serializable (config can come from a file, a DB, or the
- * server). Evaluated at CLICK time, so the user picks the spot first, then the
- * source:
- *   - `{ kind: 'bytes' }` — fixed bytes: a company rubber-stamp.
- *   - `{ kind: 'prompt' }` — ask the environment for bytes. The plugin does NOT
- *     know how (a file dialog is DOM); the file-picker port (`FilePickerProvider`),
- *     installed by the framework adapter, fulfils it. Resolve `null` there to cancel.
- */
-type StampSourceSpec = {
-  kind: 'bytes';
-  source: BinarySource;
-} | PromptSourceSpec;
-/**
- * The ask-the-environment resolution, shared by every click-then-pick tool
- * (a stamp's `'prompt'` source, the file-attachment tool). `accept` is the
- * file-dialog filter the picker request carries — a UX hint only, the engine
- * sniffs/validates the bytes for real. Unset = any file.
- */
-interface PromptSourceSpec {
-  kind: 'prompt';
-  accept?: string;
-}
-/**
- * The tool `armStamp` activates — and the only tool an armed payload survives
- * onto (plus the legacy `annotation-stamp` tag, honoured for embedder configs
- * written before the tags were unified). Placement consults the armed payload
- * BEFORE the active tool's own `source` spec, so a payload must not outlive
- * its tool onto a sibling stamp preset: an `image` preset's click has to open
- * its own picker, not silently place whatever the stamp panel last armed.
- */
-declare const ARMED_STAMP_TOOL_ID = "stamp";
-/** Declarative result of committing a text selection while a tool is active. */
-type SelectionAuthoring = {
-  kind: 'markup';
-} | {
-  kind: 'text-edit';
-  operation: 'insert' | 'replace';
-};
-/**
- * The armed tool's IN-PAGE preview:
- *   - `footprint` — the EXACT box a click would place, in the page (content
- *     space, page-clamped, WYSIWYG). Meaningful only when the box is
- *     determinable: an armed stamp payload, or a `clickCreate` size.
- *   - `false` — no preview.
- * WHICH tool is armed is the CURSOR's job, not a ghost's: give the tool an
- * image cursor built from your toolbar icon (the hub's `setToolCursor` + the
- * web package's `svgCursor`), and the hub's claim/gap arbitration keeps it
- * honest over annotations, form fields, and page gaps.
- */
-type GhostPolicy = false | {
-  mode: 'footprint';
-};
-/** Time/geometry policy for freehand ink authoring. */
-interface InkAuthoringOptions {
-  /** Group strokes made within this interval into one `/InkList`; 0 commits immediately. */
-  groupStrokesMs?: number;
-  /** Optional pure straight-line recognition applied to each completed stroke. */
-  straighten?: InkStraightenOptions;
-}
-/**
- * The creation properties each known authoring kind actually consumes. This is
- * deliberately separate from the flat internal patch vocabulary: it gives tool
- * configuration precise compile-time and runtime validation while mixed-selection
- * edits can keep using `AnnotationPropsPatch`.
- */
-declare const TOOL_DEFAULT_KEYS: {
-  readonly square: readonly ["color", "interiorColor", "opacity", "strokeWidth", "border"];
-  readonly circle: readonly ["color", "interiorColor", "opacity", "strokeWidth", "border"];
-  readonly line: readonly ["color", "interiorColor", "opacity", "strokeWidth", "border", "lineEndings"];
-  readonly polygon: readonly ["color", "interiorColor", "opacity", "strokeWidth", "border"];
-  readonly polyline: readonly ["color", "interiorColor", "opacity", "strokeWidth", "border", "lineEndings"];
-  readonly ink: readonly ["color", "opacity", "strokeWidth", "blendMode"];
-  readonly 'free-text': readonly ["fontFamily", "fontSize", "fontColor", "bold", "italic", "underline", "textAlign", "opacity", "interiorColor", "color", "strokeWidth", "border"];
-  readonly 'free-text-callout': readonly ["fontFamily", "fontSize", "fontColor", "bold", "italic", "underline", "textAlign", "opacity", "interiorColor", "color", "strokeWidth", "border", "lineEndings"];
-  readonly highlight: readonly ["color", "opacity", "blendMode"];
-  readonly underline: readonly ["color", "opacity", "blendMode"];
-  readonly strikeout: readonly ["color", "opacity", "blendMode"];
-  readonly squiggly: readonly ["color", "opacity", "blendMode"];
-  readonly caret: readonly ["color", "opacity"];
-  readonly redact: readonly ["color", "interiorColor", "opacity", "fontFamily", "fontSize", "fontColor", "textAlign"];
-  readonly stamp: readonly [];
-  readonly link: readonly ["link"];
-  readonly text: readonly ["icon", "color", "opacity"];
-  readonly 'file-attachment': readonly ["icon", "color", "opacity"];
-  readonly 'widget-text': readonly ["color", "interiorColor", "strokeWidth", "border", "fontFamily", "fontSize", "fontColor", "textAlign"];
-  readonly 'widget-choice': readonly ["color", "interiorColor", "strokeWidth", "border", "fontFamily", "fontSize", "fontColor", "textAlign"];
-  readonly 'widget-toggle': readonly ["color", "interiorColor", "strokeWidth", "border"];
-  readonly 'widget-box': readonly ["color", "interiorColor", "strokeWidth", "border"];
-};
-type ToolAuthoringKind = keyof typeof TOOL_DEFAULT_KEYS;
-type ToolDefaultKey<K extends ToolAuthoringKind> = (typeof TOOL_DEFAULT_KEYS)[K][number];
-type ToolDefaultsFor<K extends ToolAuthoringKind> = [ToolDefaultKey<K>] extends [never] ? never : Pick<AnnotationPropsPatch, ToolDefaultKey<K>>;
-/**
- * A tool definition — the public config vocabulary. Every field except `id` is
- * optional: the common cases are "configure a built-in" (`{ id, defaults }`) and
- * "add a preset" (`{ id, extends, defaults }`).
- */
-interface AnnotationToolDef<K extends ToolAuthoringKind = ToolAuthoringKind> {
-  /** Stable tool id — the value passed to `activateTool` and the `defaults` key. */
-  id: string;
-  /** Inherit `subtype` / `propsKind` / `cursor` / `enables` / `source` /
-   *  `selection` / `intent` / `ink` / `meta`
-   *  from an existing tool id (a built-in or another entry). Own fields win. */
-  extends?: string;
-  /** The ROUTING KIND this tool authors — the core's client kind (the geometry
-   *  it draws + the props key). Usually the PDF subtype, but not always:
-   *  `free-text-callout` routes the callout gesture onto a free-text
-   *  annotation, and `widget-text`/`widget-choice`/`widget-toggle` are client
-   *  views of the ONE PDF `widget` subtype (a form tool's commit goes through
-   *  `doc.forms`, never this plugin — see the form plugin's tool table).
-   *  Defaults to the inherited kind, or the id when neither is given. */
-  subtype?: Subtype;
-  /** The kind whose editable-property specs a style panel shows for this tool.
-   *  Defaults to `subtype` (a callout authors `free-text` props, for example). */
-  propsKind?: string;
-  /** ADVANCED: the `defaults` key this tool reads/writes. Defaults to the id, and
-   *  that is almost always right — override it only to alias a shared defaults bag
-   *  (the built-in insert-caret tool points its preset at the `caret` key). */
-  preset?: string;
-  /** Seed defaults for newly drawn annotations — the flat AnnotationProps patch,
-   *  merged over any inherited defaults (line endings merge per side). */
-  defaults?: ToolDefaultsFor<K>;
-  /**
-   * `/F` annotation flags seeded on everything this tool creates, merged over
-   * the drawn default (`print` set — Acrobat parity) and any inherited seed.
-   * A note tool passes `{ noZoom: true, noRotate: true }` so its icons stay
-   * screen-sized and upright (the spec's rule for Text annotations).
-   */
-  flags?: Partial<AnnotationFlags>;
-  /** The pointer cursor while this tool is active. Defaults inherited / `crosshair`. */
-  cursor?: string;
-  /** Interaction capability tags this tool enables (which handlers wake up). */
-  enables?: string[];
-  /**
-   * How the click-to-place payload resolves. Stamps take the full spec
-   * ({@link StampSourceSpec}: fixed bytes or prompt); file attachments are
-   * prompt-only ({@link PromptSourceSpec} — the file always comes from the
-   * environment). Other kinds carry no payload.
-   */
-  source?: K extends 'stamp' ? StampSourceSpec : K extends 'file-attachment' ? PromptSourceSpec : never;
-  /** What a committed text selection authors. Omit for pointer/click tools. */
-  selection?: SelectionAuthoring;
-  /** PDF `/IT` authored by an intent-bearing ink preset. */
-  intent?: K extends 'ink' ? InkIntent : never;
-  /** Ink-only stroke grouping and straightening policy. */
-  ink?: K extends 'ink' ? InkAuthoringOptions : never;
-  /**
-   * Place annotations UPRIGHT: counter-rotate what this tool creates against the
-   * page's TOTAL display rotation (document /Rotate + any stage view rotation),
-   * so it reads horizontally exactly as the author saw it — Adobe's behaviour
-   * for stamps and text on rotated pages. WYSIWYG at authoring time: the
-   * rotation is baked into the annotation, so a save keeps what the author saw
-   * (other viewers apply only /Rotate — document that when view rotation is in
-   * play). Box kinds only (stamp / free-text, where reading orientation is
-   * meaningful); ignored by vertex kinds and callouts. Default: on for the
-   * built-in `stamp` and `free-text` tools, off elsewhere.
-   */
-  upright?: boolean;
-  /**
-   * What a bare CLICK creates (v2's `clickBehavior`): a default-size shape
-   * centred on the point / a default-length line from it / free-text's
-   * type-here box — page-clamped, in PDF pt. `false` = drag-only. Defaults:
-   * on for the built-in square/circle/line/free-text, off elsewhere.
-   */
-  clickCreate?: ClickCreate | false;
-  /**
-   * The armed-tool in-page preview ({@link GhostPolicy}). Defaults: inherited,
-   * else off (the built-in stamp declares `footprint`).
-   */
-  ghost?: GhostPolicy;
-  /** Opaque presentation hints (label/icon…) for a toolbar or cursor that builds
-   *  itself from the tool table. Never read by the plugin or the interaction hub. */
-  meta?: Record<string, unknown>;
-}
-interface BuiltinToolKindMap {
-  square: 'square';
-  circle: 'circle';
-  line: 'line';
-  polygon: 'polygon';
-  polyline: 'polyline';
-  ink: 'ink';
-  'ink-highlight': 'ink';
-  'free-text': 'free-text';
-  'free-text-callout': 'free-text-callout';
-  highlight: 'highlight';
-  underline: 'underline';
-  strikeout: 'strikeout';
-  squiggly: 'squiggly';
-  'insert-text': 'caret';
-  'replace-text': 'strikeout';
-  redact: 'redact';
-  stamp: 'stamp';
-  note: 'text';
-  attachment: 'file-attachment';
-  link: 'link';
-}
-type DirectToolDef = { [K in ToolAuthoringKind]: Omit<AnnotationToolDef<K>, 'subtype'> & {
-  subtype: K;
-}; }[ToolAuthoringKind];
-type BuiltinToolOverride = { [I in keyof BuiltinToolKindMap]: Omit<AnnotationToolDef<BuiltinToolKindMap[I]>, 'id' | 'extends' | 'subtype'> & {
-  id: I;
-  extends?: never;
-  subtype?: never;
-}; }[keyof BuiltinToolKindMap];
-type ExtendedBuiltinToolDef = { [I in keyof BuiltinToolKindMap]: Omit<AnnotationToolDef<BuiltinToolKindMap[I]>, 'extends' | 'subtype'> & {
-  extends: I;
-  subtype?: never;
-}; }[keyof BuiltinToolKindMap];
-/** Public tool input: known overrides, known-base presets, or an explicit subtype. */
-type AnnotationToolInput = DirectToolDef | BuiltinToolOverride | ExtendedBuiltinToolDef;
-/** A fully-resolved tool — what the plugin, handlers, and registration loop read. */
-interface ResolvedTool {
-  id: string;
-  /** Routing token for the draw core + the created annotation's PDF subtype. */
-  subtype: Subtype;
-  /** The `defaults` key (always the tool id) — keeps same-subtype tools apart. */
-  preset: string;
-  /** The `propsFor` key for the style panel. */
-  propsKind: string;
-  cursor: string;
-  enables: ReadonlySet<string>;
-  defaults?: AnnotationPropsPatch;
-  /** `/F` seed for created annotations (see {@link AnnotationToolDef.flags}). */
-  flags?: Partial<AnnotationFlags>;
-  source?: StampSourceSpec;
-  selection?: SelectionAuthoring;
-  intent?: InkIntent;
-  ink?: InkAuthoringOptions;
-  /** Counter-rotate creations against the page's display rotation (see
-   *  {@link AnnotationToolDef.upright}). */
-  upright: boolean;
-  /** What a bare click creates, or `false` for drag-only. */
-  clickCreate: ClickCreate | false;
-  /** The armed-tool in-page preview ({@link GhostPolicy}). */
-  ghost: GhostPolicy;
-  meta?: Record<string, unknown>;
-}
-/**
- * The built-in tools — a data mirror of v2's registrations (shapes + lines + ink
- * + free text in the draw channel, text markup + caret behind text selection, and
- * the click-to-place stamp). Order is display-neutral; the toolbar owns layout.
- */
-declare const DEFAULT_TOOLS: AnnotationToolInput[];
-/**
- * Resolve {@link DEFAULT_TOOLS} + embedder overrides into the ready-to-use table.
- * A same-id override merges over the built-in; a new id adds a tool; `extends`
- * inherits from an already-defined tool. Keyed by id, so lookups are O(1).
- */
-declare function buildToolRegistry(overrides?: AnnotationToolInput[]): Map<string, ResolvedTool>;
-//#endregion
-//#region src/types.d.ts
-/**
- * Selection-chrome settings: the outline, resize/vertex handles, and the rotate
- * knob. ONE unit story — every length is CSS px, screen-constant across zoom
- * (the plugin converts to content units per event/page via the view scale).
- * Every color falls back to `accent`, so the common case is one line:
- * `annotationPlugin({ chrome: { accent: '#e91e63' } })`. Deep-partial merged
- * over {@link DEFAULT_CHROME}; live-adjustable via
- * {@link AnnotationCapability.setChrome}.
- */
-interface ChromeSettings {
-  /** The one color every chrome piece derives from unless overridden. */
-  accent: string;
-  outline: {
-    /** ONE style at rest AND while rotated — the box never flips style mid-gesture. */
-    style: 'solid' | 'dashed';
-    /** Stroke width, px. */
-    width: number;
-    /** Overrides `accent`. */
-    color?: string;
-  };
-  /** Resize + vertex handles (independent of the knob — size them apart). */
-  handles: {
-    /** Visual square side, px. */
-    size: number;
-    /** Grab-zone square side, px — keep ≥ 24 for touch. */
-    hitSize: number;
-    fill: string;
-    /** Overrides `accent`. */
-    stroke?: string;
-  };
-  /** The rotate handle. Page-bound placement (flip/clamp) always applies. */
-  knob: {
-    /** Grab-dot diameter, px. */
-    size: number;
-    /** Grab-zone square side, px — keep ≥ 24 for touch. */
-    hitSize: number;
-    /** Stalk length, px — selection edge to dot centre. */
-    offset: number;
-    /** Draw the connector stalk. */
-    stalk: boolean;
-    fill: string;
-    /** Overrides `accent` (dot outline + stalk). */
-    stroke?: string;
-  };
-  /** The rotation guides shown while a rotate gesture runs: a fixed 0°/90°
-   *  reference cross + a live indicator line, drawn as full-bleed chords of the
-   *  page through the pivot. */
-  guides: {
-    /** Show the guides at all. Default true. */
-    enabled: boolean;
-    style: 'solid' | 'dashed';
-    /** Stroke width, px. */
-    width: number;
-    /** The fixed reference cross. Color overrides `accent`. */
-    axisColor?: string;
-    axisOpacity: number;
-    /** The line riding the live angle. Color overrides `accent`. */
-    indicatorColor?: string;
-    indicatorOpacity: number;
-  };
-}
-/** Deep-partial patch for {@link ChromeSettings} — config + `setChrome` input. */
-interface ChromeSettingsPatch {
-  accent?: string;
-  outline?: Partial<ChromeSettings['outline']>;
-  handles?: Partial<ChromeSettings['handles']>;
-  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
-   * place — the stamp's fitted image box, or a click-create tool's default
-   * geometry — computed by the same rules the placement uses (WYSIWYG). In the
-   * store (not the capability closure) because it is RENDERED — vector ghosts
-   * ride `pageItems`, image ghosts (stamp) render via the framework's
-   * `ToolGhost`. The armed bytes stay out of the store.
-   */
-  toolGhost: ToolGhost | null;
-  /** Bumps on every arm/disarm — the render layer's cue to rebuild (or drop)
-   *  the ghost preview object URL. Never rendered itself. */
-  stampArmEpoch: number;
-  /**
-   * The text editor's selection inside the annotation being edited (flat
-   * offsets over its plain projection), or null. In the store because it is
-   * READ by the property surface: while a range is held, the range keys
-   * (`getSelectionProps`) report and take the RUNS, not the body.
-   */
-  textSelection: TextSelection | null;
-}
-/** The armed tool's would-be placement under the cursor (content space). */
-type ToolGhost = {
-  pon: PageObjectNumber;
-  /** The exact box the click's placement would use. */
-  box: Rect;
-  /** The tool's upright counter-rotation at this hover (deg, CW). */
-  rot: number;
-} & ({
-  kind: 'image';
-} | {
-  kind: 'vector';
-  toolId: string;
-  geom: Geom;
-});
-/** Registration options for {@link annotationPlugin} — the initial values of the
- *  live-adjustable {@link AnnotationCapability.setSnap} /
- *  {@link AnnotationCapability.setChrome} settings. */
-interface AnnotationConfig {
-  snap?: {
-    /** Alignment guides while moving (snap to other annotations + the page).
-     *  Default true. */
-    guides?: boolean;
-    /** Guide snap tolerance, content units (PDF pt). Default 5. */
-    guideThreshold?: number;
-    /** Snap the rotate gesture onto `rotationAngles`. Default true. */
-    rotation?: boolean;
-    /** Default `[0, 90, 180, 270]`. */
-    rotationAngles?: number[];
-    /** Rotation snap tolerance, degrees. Default 4. */
-    rotationThreshold?: number;
-  };
-  /** Selection-chrome styling + grab geometry (all lengths CSS px). */
-  chrome?: ChromeSettingsPatch;
-  /**
-   * Add or configure authoring tools at load. Entries MERGE over the built-ins by
-   * id (configure one — `{ id: 'ink', defaults: { strokeWidth: 6 } }`), ADD a new
-   * tool (a fresh id), or make a preset with `extends`
-   * (`{ id: 'arrow', extends: 'line', defaults: { lineEndings: { end: 'open-arrow' } } }`).
-   * See {@link AnnotationToolDef}. The runtime equivalent is
-   * {@link AnnotationCapability.registerTool}.
-   */
-  tools?: AnnotationToolInput[];
-}
-type AnnotationAction = {
-  type: 'SET_MODEL';
-  model: Model;
-} | {
-  type: 'SET_HYDRATION';
-  hydration: AnnotationHydration;
-} | {
-  type: 'SET_CHROME';
-  patch: ChromeSettingsPatch;
-} | {
-  type: 'SET_TOOL_GHOST';
-  ghost: ToolGhost | null;
-} | {
-  type: 'SET_TEXT_SELECTION';
-  selection: TextSelection | null;
-} | {
-  type: 'STAMP_ARM_CHANGED';
-};
-/** A plugin (forms, links) marks some annotations as interactive: while engaged,
- *  they render their own DOM and are NOT geometry-editable. Suspend → editable. */
-/**
- * One clickable link area on a page (content space): a standalone link
- * annotation, or one segment of a parent's ATTACHED link. See
- * {@link AnnotationHostCapability.linkItemsOn}.
- */
-interface LinkNavItem {
-  /** Stable per-page key: the annot id, `#n`-suffixed for attached segments. */
-  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;
-  matches(a: {
-    subtype: Subtype;
-    ref: AnnotationRef | null;
-  }): boolean;
-  engaged(): boolean;
-}
-/**
- * The current selection's editable properties, ready to render: the ordered
- * {@link PropSpec}s EVERY selected kind declares (a mixed selection shows the
- * shared subset, in the first kind's order), the first member's `values`, and
- * which keys differ across members (`mixed` — render an indeterminate control).
- * Empty `specs` = nothing selected / nothing editable.
- */
-interface SelectionProps {
-  specs: PropSpec[];
-  values: Partial<AnnotationProps>;
-  mixed: PropKey[];
-}
-/**
- * The selection's `/F` flag state, ready for a menu/sidebar: one value per
- * flag — `true`/`false` when every selected annotation agrees, `null` when
- * they differ (render an indeterminate control). The read half of
- * {@link AnnotationCapability.updateSelectionFlags}.
- */
-type SelectionFlags = { [K in keyof AnnotationFlags]: boolean | null; };
-/**
- * A free-text annotation projected for the framework: the box (content space,
- * live gesture applied) + the plain text + an `editing` flag + a ready-to-spread
- * CSS style. The framework renders ONE editable element from this and nothing
- * more — all the mapping (fonts, colours, alignment) is done here, once. The
- * element paints the TEXT only: the box's fill and border are the vector
- * scene's (`pageItems`), the same for a plain box and a callout, so the live
- * view matches the baked appearance.
- */
-interface TextItem {
-  id: Id;
-  ref: AnnotationRef | null;
-  box: Rect;
-  contents: string;
-  /** The rich paragraphs the editor renders and edits (run deltas over the
-   *  body, which `css` carries). `contents` is their plain projection. */
-  richText: {
-    paragraphs: RichTextParagraph[];
-  };
-  editing: boolean;
-  /** Applied rotation (deg, CW). `box` is the UNROTATED text box; the framework
-   *  rotates the editable element about its centre by this. 0/undefined = none. */
-  rot?: number;
-  css: {
-    fontFamily: string;
-    /** Content units (the framework multiplies by the page scale). The line
-     *  height is NOT here: the editor binding states the engine's line model
-     *  per face on the element itself (`@embedpdf/web`, `lineModelFor`). */
-    fontSize: number;
-    color: string;
-    /** The body's formatting (runs override it as inline spans). */
-    fontWeight: number;
-    fontStyle: 'normal' | 'italic';
-    textDecoration: 'none' | 'underline';
-    align: 'left' | 'center' | 'right';
-    padding: number;
-  };
-}
-/**
- * The PUBLIC annotation API — the documented, stable surface for application code
- * (toolbars, sidebars, app logic). Resolve it with the token re-exported from the
- * package root (`@embedpdf/plugin-annotation`).
- *
- * Framework-only plumbing (render projection, pointer gestures, behavior
- * 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
-   * subtype (PDF-space, sRGB). Resolves to the new annotation's durable `ref`.
-   * The same path the draw tools use, so programmatic and interactive creation
-   * share one optimistic flow + one event stream.
-   */
-  create(pon: PageObjectNumber, draft: AnnotationDraft): Promise<AnnotationRef>;
-  /**
-   * Patch an existing annotation. `patch` is the engine-core patch for the
-   * annotation's subtype — style, endings, contents, geometry are ALL just
-   * fields here (there is no separate "set style"). Attribution is automatic
-   * from the session identity.
-   */
-  update(ref: AnnotationRef, patch: AnnotationPatch): Promise<void>;
-  /** Delete an annotation by ref. */
-  delete(ref: AnnotationRef): Promise<void>;
-  /**
-   * Restyle the current selection with ONE flat property patch — the write half
-   * of {@link getSelectionProps}. Each selected annotation takes the keys its
-   * kind declares (`propsFor`) and ignores the rest, so a single patch restyles
-   * a mixed selection. Optimistic: the model updates immediately; one engine
-   * write per changed member re-syncs from the authoritative DTO.
-   */
-  updateSelection(patch: AnnotationPropsPatch): void;
-  /**
-   * Merge a `/F` flags patch into the current selection — the write half of
-   * {@link getSelectionFlags}. Optimistic; one flags-only engine write per
-   * changed member, which never re-bakes an appearance. Deliberately NOT
-   * blocked by `locked`: this is how you unlock (Acrobat's Locked checkbox
-   * stays live on a locked annotation). E.g. `{ locked: true }`,
-   * `{ print: false }`, `{ hidden: true }`.
-   */
-  updateSelectionFlags(patch: Partial<AnnotationFlags>): void;
-  /**
-   * Flip a rich-text format on the selection — the editor's Cmd/Ctrl+B/I/U
-   * and a toolbar toggle: the text range's runs while the editor holds one,
-   * else the selected free-text bodies. Reads the current state the way
-   * {@link getSelectionProps} reports it and writes its inverse through
-   * {@link updateSelection}.
-   */
-  toggleTextFormat(format: TextFormat): void;
-  /**
-   * The selection's `/F` flag state: per-flag `true`/`false`, or `null` when
-   * the selected annotations disagree (indeterminate). `null` overall when
-   * nothing is selected. Stable reference between model changes.
-   */
-  getSelectionFlags(): SelectionFlags | null;
-  /**
-   * The selection's editable properties: ordered specs shared by every selected
-   * kind + current values + which keys are mixed. THE way to build a property
-   * sidebar/toolbar — render `specs` in order, write back via
-   * {@link updateSelection}. Stable reference between model changes.
-   */
-  getSelectionProps(): SelectionProps;
-  /** The ordered property specs a TOOL's target kind declares (callout → the
-   *  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. */
-  list(pon: PageObjectNumber): AnnotationDTO[];
-  /** The selected annotations as DTOs (skips not-yet-committed drafts). */
-  getSelected(): AnnotationDTO[];
-  selection(): Id[];
-  /** The current selection as durable annotation refs (skips not-yet-committed drafts). */
-  getSelection(): AnnotationRef[];
-  /**
-   * Select an annotation by ref programmatically — e.g. auto-selecting a
-   * freshly placed form widget. Selecting a group member takes the whole
-   * group, exactly like a click. Unknown/unselectable refs no-op. `add`
-   * extends the current selection instead of replacing it.
-   */
-  select(ref: AnnotationRef, options?: {
-    add?: boolean;
-  }): void;
-  /** Group the current selection into one unit (the bottom-most member is the
-   *  primary; the rest become `/RT /Group` subordinates). Page-local: no-op
-   *  unless 2+ committed annotations on a single page are selected. */
-  group(): Promise<void>;
-  /** Ungroup the group(s) the current selection touches — every subordinate
-   *  becomes top-level again. */
-  ungroup(): Promise<void>;
-  /** Whether {@link group} would do something for the current selection. */
-  canGroup(): boolean;
-  /** Whether {@link ungroup} would do something for the current selection. */
-  canUngroup(): boolean;
-  /** Patch a tool's defaults for newly drawn annotations — the SAME flat
-   *  vocabulary {@link updateSelection} writes. */
-  setDefaults(subtype: Subtype, patch: AnnotationPropsPatch): void;
-  /** The RESOLVED full props bag a tool will use for new annotations. */
-  currentDefaults(subtype: Subtype): AnnotationProps;
-  /** Live-adjust snapping — wire a UI toggle here (e.g.
-   *  `setSnap({ guides: false })`). Initial values come from the plugin's
-   *  registration config ({@link AnnotationConfig}). */
-  setSnap(patch: Partial<SnapSettings>): void;
-  /** The current snap settings. */
-  snapSettings(): SnapSettings;
-  /** Live-adjust the selection chrome — wire theming here (e.g.
-   *  `setChrome({ accent: '#e91e63' })`). Deep-partial merge; initial values
-   *  come from the plugin's registration config ({@link AnnotationConfig}). */
-  setChrome(patch: ChromeSettingsPatch): void;
-  /** The current (fully resolved) chrome settings. */
-  chromeSettings(): ChromeSettings;
-  /** Rotate the current selection a quarter-turn clockwise about its centre
-   *  (a single shape's own centre / the union-box centre for a group). */
-  rotateSelection90(): void;
-  /** Reset the current selection to its as-authored orientation (rotation → 0). */
-  resetSelectionRotation(): void;
-  /**
-   * Arm the stamp tool: `source` (PNG, JPEG, or single-page PDF bytes —
-   * format sniffed, never trusted) becomes the content of the next stamp(s)
-   * placed by clicking a page. The placement rect is sized from the image's
-   * intrinsic aspect ratio around `targetWidth` (PDF points, default 150)
-   * and centred on the click. Also activates the `'stamp'` interaction tool;
-   * the payload stays armed for repeat placement until the tool changes or
-   * {@link disarmStamp} is called. Resolves once the payload is validated.
-   */
-  armStamp(input: StampToolInput): Promise<void>;
-  /** Drop the armed stamp payload (a tool change away from 'stamp' does this too). */
-  disarmStamp(): void;
-  /**
-   * Place a stamp WITHOUT the pointer: the same validation, fit, page clamp,
-   * `/Name`, and `/Subj` a click after {@link armStamp} produces — the one
-   * placement law, exposed for code. Resolves to the created annotation's
-   * ref; the placement is selected like a click's.
-   */
-  placeStamp(input: StampToolInput, placement: StampPlacement): Promise<AnnotationRef>;
-  /**
-   * Install the ONE file-picker port every click-then-pick tool resolves
-   * through (see {@link FilePickerProvider}) — the stamp `'prompt'` source and
-   * the file-attachment tool today. The framework adapter installs a
-   * file-dialog provider by default; pass your own (asset library, cloud
-   * drive — switch on `req.subtype` / `req.toolId`), or `null` to make
-   * click-then-pick tools inert. One slot; last write wins.
-   */
-  setFilePickerProvider(provider: FilePickerProvider | null): void;
-  /**
-   * Decode and return the file embedded in a FileAttachment annotation —
-   * bytes plus the name/mime needed to hand it to the user. Listings carry
-   * only metadata (`FileAttachmentAnnotationDTO.file`); this is the explicit
-   * bytes-out call. Throws when the engine transport has not shipped
-   * attachment download (feature-detected).
-   */
-  downloadAttachment(ref: AnnotationRef): Promise<AttachmentContent>;
-  /**
-   * Register (or replace, by id) an authoring tool at runtime — the imperative
-   * mirror of the `tools` config. Same {@link AnnotationToolDef} vocabulary
-   * (`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;
-}
-/** Payload for {@link AnnotationCapability.armStamp}. */
-interface StampToolInput {
-  /** PNG, JPEG, or single-page PDF bytes (`Blob | Uint8Array | BinaryPayload`). */
-  source: BinarySource;
-  /** Placed width in PDF points (height follows the intrinsic aspect). Default 150. */
-  targetWidth?: number;
-  /** The placed annotation's `/Name` — the stamp identifier (standard or custom). */
-  name?: string;
-  /** The placed annotation's `/Subj`. */
-  subject?: string;
-  /**
-   * The hover ghost's image. Either fixed bytes (PNG/JPEG) or — for vector
-   * sources, which are only ever right at ONE on-screen size — a
-   * {@link StampPreviewProvider} the ghost asks for a render at the device
-   * pixel width it is displayed at. Raster sources default to themselves;
-   * omit and the tool simply shows no ghost.
-   */
-  preview?: BinarySource | StampPreviewProvider;
-  /**
-   * The source's intrinsic size in PDF points. Raster sources are measured
-   * from their own header, but PDF bytes carry no sniffable dimensions —
-   * callers that know the page size (a stamp library does, from import)
-   * pass it here so placement honours the true aspect instead of falling
-   * back to a square.
-   */
-  intrinsicSize?: {
-    width: number;
-    height: number;
-  };
-}
-/** The armed stamp's paintable preview, for the render layer's ghost `<img>`. */
-interface ArmedStampPreview {
-  bytes: Uint8Array;
-  mimeType?: string;
-}
-/**
- * Resolution-aware ghost preview: "give me this stamp at `devicePixelWidth`
- * pixels wide". The annotation plugin buckets the request (see
- * {@link previewBucket}) and caches per bucket for the arm's lifetime, so a
- * zoom gesture never renders per frame and one render serves a zoom range.
- * A stamp library renders its page lazily through its asset engine; a raster
- * returns itself (it cannot get sharper than its pixels).
- */
-type StampPreviewProvider = (devicePixelWidth: number) => Promise<ArmedStampPreview | null>;
-/**
- * Ghost render buckets: powers of two from 128 px up to `cap`. The same policy
- * the page renderer uses — one bitmap per size class, never per zoom step.
- */
-declare function previewBucket(devicePixelWidth: number, cap?: number): number;
-/**
- * Where a programmatic stamp placement lands — the inputs a click supplies.
- * The box is fitted and clamped exactly as the click path does it.
- */
-interface StampPlacement {
-  pageObjectNumber: PageObjectNumber;
-  /** Anchor in page points (content space): the placement is centred here. */
-  at: Vec;
-  /** Placed width in PDF points; default the payload's intrinsic size. */
-  targetWidth?: number;
-  /** Content rotation, degrees clockwise. Default 0. */
-  rotation?: number;
-}
-/**
- * What the {@link FilePickerProvider} is asked for: which tool clicked (id +
- * the kind it creates), the tool's `accept` filter, and the page-space point
- * the click landed on — enough to route per tool (asset library for stamps,
- * cloud drive for attachments) or position a picker near the click. Pure
- * data — the request crosses the plugin↔adapter boundary as a message.
- */
-interface FilePromptRequest {
-  toolId: string;
-  /** The kind the placement creates — the routing key for per-tool pickers. */
-  subtype: Subtype;
-  /** The tool's file-dialog filter hint (from the tool def). UX only —
-   *  the engine sniffs/validates the bytes for real. */
-  accept?: string;
-  pon: PageObjectNumber;
-  /** The content-space point the placement is centred on. */
-  point: Vec;
-}
-/**
- * The ONE environment port behind every click-then-pick tool — the stamp
- * `'prompt'` source and the file-attachment tool (the file is picked AFTER
- * the spot): given a click, produce the file to place, `null` to cancel. The
- * plugin declares this contract but never implements it — "get bytes from the
- * environment" is a DOM concern (a file dialog), so the framework adapter
- * installs the implementation via
- * {@link AnnotationCapability.setFilePickerProvider}. This keeps the plugin
- * DOM-free (Rust-portable) while the zero-config file dialog works out of the
- * box. The return shape is the engine's file vocabulary: a stamp consumes
- * only `data`; an attachment embeds the whole thing. A picked `File` carries
- * its own name and mime — a provider returning raw bytes for an attachment
- * must supply `name` itself.
- */
-type FilePickerProvider = (req: FilePromptRequest) => Promise<AttachmentFileSource | null>;
-/**
- * The HOST (framework) surface: everything the render layer, the interaction hub,
- * and sibling plugins need, on top of the public {@link AnnotationCapability}.
- * 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)
-   *  projects screen-anchored (`noZoom`/`noRotate`) bodies to their effective
-   *  footprint. Pass it from the page context; absent → stored geometry. */
-  pageItems(pon: PageObjectNumber, view?: ViewEnv): RenderItem[];
-  /** `scale` (view px per content unit, from the page's transform) converts the
-   *  px chrome settings into content units — pass it so the knob stalk and grab
-   *  zones are screen-constant. `rotation` (the page's total display rotation)
-   *  and `zoom` (the page's zoom RELATIVE to its 100% baseline —
-   *  `transform.zoom`, NOT `viewScale`) complete the view env for
-   *  screen-anchored bodies. Absent scale → settings are read as content
-   *  units. */
-  chrome(pon: PageObjectNumber, scale?: number, rotation?: PageRotation, zoom?: number): ChromeNode[];
-  /** The anchor for a selection-aware floating menu: the primary page + the
-   *  selection's union box on that page (content space), or null when nothing
-   *  selectable is selected. One anchor regardless of cross-page selection.
-   *  `scale`/`rotation`/`zoom` as in {@link chrome} (the anchor page's view). */
-  selectionAnchor(scale?: number, rotation?: PageRotation, zoom?: number): {
-    pon: PageObjectNumber;
-    bounds: Rect;
-    knob?: Vec;
-  } | null;
-  /** The anchor + action state for a live multi-click creation draft, or null. */
-  creationDraftAnchor(): CreationDraftAnchor | null;
-  /** Cache key for a page's baked appearances: the COMMITTED id + AP box of every
-   *  baked annotation (gesture previews excluded). Changes exactly once per
-   *  committed create/geometry-edit, so the render layer refetches rasters then —
-   *  and only then (a stamp resize re-fits its AP engine-side, for example). */
-  appearanceEpoch(pon: PageObjectNumber): string;
-  /**
-   * The scale a baked appearance should render at for a desired device
-   * scale — `snapAppearanceScale` over the document's `renderPolicy` (the
-   * kernel-materialized fact; identity under `continuous`). THE identity a
-   * render layer keys its bake effect on: inside an appearance-lattice rung,
-   * zoom ticks produce the same value → no re-bake; crossing a rung re-bakes
-   * once. This plugin owns its raster product end to end — the policy is a
-   * document fact, not another plugin's possession.
-   */
-  bakeScale(renderScale: number): number;
-  /** The engine's rendered /AP appearance images for a page — the `baked` visual. */
-  appearances(pon: PageObjectNumber, scale: number, signal?: AbortSignal): Promise<AnnotationAppearanceImage[]>;
-  /** Convert an engine appearance rect (PDF user space) to a content-space box, so
-   *  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
-   * cross-plane mutations (e.g. `doc.forms.createField`/`deleteField`
-   * changing the page's widget population underneath this plugin). Resolves
-   * when the fresh page is in the model, so a caller can select what it just
-   * 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[];
-  /** The id of the annotation currently being text-edited, or null. Read live (not
-   *  from a stale render) so the editor can tell a real exit from a focus-steal. */
-  currentEditing(): Id | null;
-  /** 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 / 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;
-  /** Apply the editor's rich paragraphs (run deltas over the body) —
-   *  optimistic locally, debounced to the engine. The commit is plain
-   *  `contents` while nothing overrides the body on a plain annotation, else
-   *  `richText`. */
-  setRichText(ref: AnnotationRef, doc: {
-    paragraphs: RichTextParagraph[];
-  }): void;
-  /** The editor's selection inside the annotation (flat offsets over the
-   *  plain projection), or null when the editor holds none. While a RANGE is
-   *  held, `updateSelection`'s font/size/colour/format keys restyle the
-   *  range's runs instead of the body. */
-  setTextSelection(ref: AnnotationRef, range: {
-    start: number;
-    end: number;
-  } | null): void;
-  /** The CSS family list for a face family a run names ("Helvetica" → a web
-   *  stack, a registered family → its key, mounted by `mountWebFont`). */
-  cssFontFamily(family: string): string;
-  /** Leave text-edit (flush any pending write). */
-  endTextEdit(): void;
-  /** What's under a content point — for the edit handler's capture decision.
-   *  `scale` (the page's view px per content unit) keeps grab zones
-   *  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,
-  /** 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;
-  /**
-   * Report the pointer's position for hover state (`null` = off every page).
-   * Diffs the topmost hit against the model and dispatches only on CHANGE
-   * (enter/leave cadence) — drives scene-level hover affordances like the
-   * redaction mark's applied-look preview. Called from the edit handler's
-   * onHover, which already samples every move for cursor claims.
-   */
-  hoverAt(at: {
-    pon: PageObjectNumber;
-    point: Vec;
-    scale?: number;
-    rotation?: PageRotation;
-    zoom?: number;
-  } | null): void;
-  behaviorFor(a: {
-    subtype: Subtype;
-    ref: AnnotationRef | null;
-  }): Behavior | null;
-  /**
-   * The clickable link areas of a page (content space): standalone link
-   * annotations plus every ATTACHED-link segment (folded children — their
-   * rects derived by the SAME rule the reconciler writes, so the clickable
-   * area and the written `/Rect`s can't disagree). Hidden annotations are
-   * excluded. THE data feed for the navigation plane (plugin-link);
-   * memoized by model identity for selector use.
-   */
-  linkItemsOn(pon: PageObjectNumber): LinkNavItem[];
-  /** Drop selected annotations whose Behavior is currently ENGAGED — inert
-   *  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,
-  /** 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;
-  /** Commit the strokes currently buffered by an ink tool's grouping window. */
-  finishInkDraft(): 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, 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, 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
-   *  rotation) feeds the active tool's `upright` policy. */
-  placeArmedStamp(pon: PageObjectNumber, point: Vec, displayRotation?: PageRotation): boolean;
-  /**
-   * The one click-to-place entry for every payload-carrying tool (stamp /
-   * note / file attachment) — the place handler forwards each down here.
-   * Armed payload first, then the active tool's kind routes; returns whether
-   * the click was consumed.
-   */
-  placeAt(pon: PageObjectNumber, point: Vec, displayRotation?: PageRotation): boolean;
-  /** Whether a stamp payload is armed — the hover handler's cheap pre-check. */
-  hasArmedStamp(): boolean;
-  /**
-   * Update the armed tool's FOOTPRINT ghost to a content point — the stamp's
-   * fitted image box (same fit + clamp as placement), or a click-create tool's
-   * default geometry (same anchor + clamp as the click commit). The ghost IS
-   * the placement, never an approximation. Tools without a determinable
-   * footprint (or with a `false` ghost policy) clear instead.
-   */
-  ghostHoverAt(toolId: string, pon: PageObjectNumber, point: Vec, displayRotation?: PageRotation): void;
-  /** Drop the hover ghost (pointer left the pages / a gesture started). */
-  clearGhost(): void;
-  /**
-   * Drive the transient placement preview during an EXTERNALLY-owned creation
-   * gesture (the form plugin's drag-to-place): the box the commit would use,
-   * page-clamped, styled from the TOOL's defaults, painted through the same
-   * ghost pipeline as every footprint. Sibling plugins call THIS — never the
-   * annotation store directly.
-   */
-  setPlacementPreview(toolId: string, pon: PageObjectNumber, box: Rect): void;
-  /** Drop the placement preview (gesture ended — commit, cancel, or error). */
-  clearPlacementPreview(): void;
-  /** The armed tool's footprint ghost on a page (content space), or null.
-   *  Vector ghosts also ride {@link pageItems}; only `kind: 'image'` ghosts
-   *  need the framework's blit. */
-  toolGhost(pon: PageObjectNumber): ToolGhost | null;
-  /**
-   * The armed stamp's paintable preview at (roughly) `devicePixelWidth`
-   * pixels wide — bucketed and cached per bucket for the arm's lifetime —
-   * or null when there is no ghost to show. Omit the width for the
-   * smallest bucket.
-   */
-  armedStampPreview(devicePixelWidth?: number): Promise<ArmedStampPreview | null>;
-  /** Bumps on arm/disarm — keys the render layer's preview object-URL lifetime. */
-  stampArmEpoch(): number;
-  /**
-   * Resolve the ACTIVE tool's {@link StampSourceSpec} for a click and place a
-   * stamp centred on `point`: fixed `bytes` land immediately; a `'prompt'` source
-   * asks the installed {@link FilePickerProvider} (placement is dropped if it
-   * cancels, or if the tool/document changed while it was open). Returns false
-   * (no capture) when the active tool has no source. The click-then-pick
-   * counterpart of {@link placeArmedStamp}. `displayRotation` as on
-   * {@link placeArmedStamp}.
-   */
-  requestStampAt(pon: PageObjectNumber, point: Vec, displayRotation?: PageRotation): boolean;
-  /** Every resolved tool (built-ins + config `tools`), for the registration loop. */
-  tools(): ResolvedTool[];
-  /** One resolved tool by id, or null when it is not registered. */
-  tool(id: string): ResolvedTool | null;
-  /** A tool's routing subtype (arrow → `line`) — how the draw handler picks the
-   *  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, `/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 { InkAuthoringOptions as A, TextSelection as B, ToolGhost as C, AnnotationToolInput as D, AnnotationToolDef as E, ToolAuthoringKind as F, ToolDefaultsFor as I, buildToolRegistry as L, ResolvedTool as M, SelectionAuthoring as N, DEFAULT_TOOLS as O, StampSourceSpec as P, Face as R, ThreadDeleteResult as S, ARMED_STAMP_TOOL_ID as T, SelectionProps as _, AnnotationHydration as a, StampToolInput as b, Behavior as c, CommentPermissions as d, CommentsApi as f, SelectionFlags as g, LinkNavItem as h, AnnotationHostCapability as i, PromptSourceSpec as j, GhostPolicy 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, StampPlacement as v, previewBucket as w, TextItem as x, StampPreviewProvider as y, TextFormat as z };
-//# sourceMappingURL=types-D5V0TIwk.d.ts.map