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

package/dist/host-contract-CxrQPcPj.js

@@ -0,0 +1,52 @@
+import { c as AnnotationToken$1 } from "./contract-b2e_LZvu.js";
+import { createHostToken } from "@embedpdf/core";
+//#region src/priorities.ts
+/**
+* The interaction-hub priorities of the annotation plugin's handlers — the
+* public contract a sibling plugin builds on when it needs to sit above or
+* below one of them for the same gesture. Priority only breaks ties between
+* simultaneously-eligible handlers (the tool's tags decide eligibility).
+*
+*    100 annotation-edit    select/move/resize over an existing annotation
+*     95 annotation-place   click-to-place an armed payload on empty page space
+*     55 annotation-draw    drag-create under a draw tool (below text-select)
+*     50 annotation-marquee empty-space selection, the final fallback
+*
+* Hover runs in the same order, so a handler's hover sees the cursor claims
+* of every handler above it: a create handler shows its tool's ghost only
+* where nothing above it claims the pointer (an annotation, text).
+*
+* A handler that must win a click over an existing annotation while a
+* placing tool is active (a signature mark dropped onto a signature field)
+* registers above {@link ANNOTATION_EDIT_PRIORITY}, not merely above place:
+* the edit handler captures first over any annotation, a widget included.
+*/
+const ANNOTATION_EDIT_PRIORITY = 100;
+const ANNOTATION_PLACE_PRIORITY = 95;
+const ANNOTATION_DRAW_PRIORITY = 55;
+const ANNOTATION_MARQUEE_PRIORITY = 50;
+//#endregion
+//#region src/host-contract.ts
+/**
+* @embedpdf/plugin-annotation/contract/host — the host lens: render
+* projections, sync, pointer routing, ghosts, the markup bridge and the
+* extension seams. Same runtime token as the public one, typed wider.
+*/
+/**
+* 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.
+*/
+function previewBucket(devicePixelWidth, maxWidth = 4096) {
+	return Math.min(maxWidth, 2 ** Math.ceil(Math.log2(Math.max(128, Math.ceil(devicePixelWidth)))));
+}
+/**
+* The annotation capability token, typed to the full
+* {@link AnnotationHostCapability} (the package internals and `/contract/host`
+* use this view). The package root exports the same runtime token narrowed to
+* {@link AnnotationCapability}.
+*/
+const AnnotationToken = createHostToken(AnnotationToken$1);
+//#endregion
+export { ANNOTATION_MARQUEE_PRIORITY as a, ANNOTATION_EDIT_PRIORITY as i, previewBucket as n, ANNOTATION_PLACE_PRIORITY as o, ANNOTATION_DRAW_PRIORITY as r, AnnotationToken as t };
+
+//# sourceMappingURL=host-contract-CxrQPcPj.js.map

package/dist/host-contract-CxrQPcPj.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-contract-CxrQPcPj.js","names":["PublicAnnotationToken"],"sources":["../src/priorities.ts","../src/host-contract.ts"],"sourcesContent":["/**\n * The interaction-hub priorities of the annotation plugin's handlers — the\n * public contract a sibling plugin builds on when it needs to sit above or\n * below one of them for the same gesture. Priority only breaks ties between\n * simultaneously-eligible handlers (the tool's tags decide eligibility).\n *\n *    100 annotation-edit    select/move/resize over an existing annotation\n *     95 annotation-place   click-to-place an armed payload on empty page space\n *     55 annotation-draw    drag-create under a draw tool (below text-select)\n *     50 annotation-marquee empty-space selection, the final fallback\n *\n * Hover runs in the same order, so a handler's hover sees the cursor claims\n * of every handler above it: a create handler shows its tool's ghost only\n * where nothing above it claims the pointer (an annotation, text).\n *\n * A handler that must win a click over an existing annotation while a\n * placing tool is active (a signature mark dropped onto a signature field)\n * registers above {@link ANNOTATION_EDIT_PRIORITY}, not merely above place:\n * the edit handler captures first over any annotation, a widget included.\n */\nexport const ANNOTATION_EDIT_PRIORITY = 100;\nexport const ANNOTATION_PLACE_PRIORITY = 95;\nexport const ANNOTATION_DRAW_PRIORITY = 55;\nexport const ANNOTATION_MARQUEE_PRIORITY = 50;\n","/**\n * @embedpdf/plugin-annotation/contract/host — the host lens: render\n * projections, sync, pointer routing, ghosts, the markup bridge and the\n * extension seams. Same runtime token as the public one, typed wider.\n */\nimport { createHostToken } from '@embedpdf/core';\nimport type { DocumentEvent, EventHook, PredictedOp, Unsubscribe } from '@embedpdf/core';\nimport type {\n  ChromeNode,\n  Effect,\n  Id,\n  Model,\n  Rect,\n  RenderItem,\n  SceneNode,\n  KindName,\n  TextEndAnchor,\n  Quad,\n  Point,\n  ViewEnv,\n} from '@embedpdf/core-annotation';\nimport type { PageRotation } from '@embedpdf/core-geometry';\nimport type {\n  AnnotationAppearanceImage,\n  AnnotationPosition,\n  AnnotationRef,\n  ChangeOp,\n  ImageSource,\n  PageMeasurementViewport,\n  PageRef,\n  PdfMeasure,\n  RichTextParagraph,\n  SerializedEngineError,\n} from '@embedpdf/engine-core/runtime';\nimport type { AnnotCommitEntry, AnnotCommitResult } from '@embedpdf/plugin-actions/contract/host';\nimport type { AppearancePicture } from '@embedpdf/plugin-render/contract/host';\n\nimport type {\n  Annotation,\n  AnnotationAnchor,\n  AnnotationCapability,\n  AnnotationSelectionAnchor,\n  ArmedStampInfo,\n  ArmedStampPreview,\n  Behavior,\n  LinkNavItem,\n  TextItem,\n  ImageGhost,\n} from './contract';\nimport { AnnotationToken as PublicAnnotationToken } from './token';\nimport type { ResolvedTool } from './tools/definitions';\n\nexport * from './contract';\nexport type { AnnotationState } from './model';\nexport {\n  ANNOTATION_DRAW_PRIORITY,\n  ANNOTATION_EDIT_PRIORITY,\n  ANNOTATION_MARQUEE_PRIORITY,\n  ANNOTATION_PLACE_PRIORITY,\n} from './priorities';\n\n/**\n * One annotation's look at rest in one of its states, as the render layer\n * paints it: the engine's picture, or, while the annotation's create is on\n * its way, the one this device made (a placed stamp's preview), which the\n * engine's replaces. `version` is the record's picture version it shows\n * (`RenderItem.pictureVersion`): one drawn at another version shows another look.\n */\nexport interface AnnotationAppearancePicture extends Pick<\n  AnnotationAppearanceImage,\n  'ref' | 'mode' | 'state' | 'rect'\n> {\n  readonly image: ImageSource;\n  readonly version: number;\n}\n\n/**\n * A sibling plugin that lends this plugin records it owns (the form plugin's\n * widgets), so they are selected, moved, resized, restyled and deleted with\n * the annotation tools. This plugin never stores them: it shows them as the\n * lender says, and an edit of one becomes the lender's ops, in the same change\n * as the rest of the edit.\n */\nexport interface AnnotationLender {\n  /** Who owns the records, for a refusal that sends you there (`'form'`). */\n  readonly owner: string;\n  /**\n   * Its records as the engine confirmed them and as they show, each list the\n   * same object until it changes; `null` while it lends none.\n   */\n  records(): {\n    readonly confirmed: readonly Annotation[];\n    readonly shown: readonly Annotation[];\n  } | null;\n  /**\n   * The ops that write a message's effects on its records, all at once:\n   * `model` is the model the message left, `before` the one it started from\n   * (a record it deleted is there).\n   */\n  opsOf(effects: readonly Effect[], model: Model, before: Model): readonly ChangeOp[];\n  /** What undoing these ops looks like. */\n  undoOf(ops: readonly ChangeOp[]): readonly PredictedOp[];\n  /** The ops that move these records of one page to `position` in its drawing order. */\n  reorderOps(\n    page: PageRef,\n    refs: readonly AnnotationRef[],\n    position: AnnotationPosition,\n  ): readonly ChangeOp[];\n  /** Whether this session may change and delete the record. */\n  authority(record: Annotation): { readonly update: boolean; readonly delete: boolean };\n  /** What its records' pictures on a page depend on: a new value means new pictures. */\n  pictureEpoch(page: PageRef): string;\n  /** A record's confirmed picture version; kept for one that went, so an undo brings it back with it. */\n  pictureVersion(record: AnnotationRef): number;\n  /**\n   * The record's look as it shows isn't its confirmed look yet, whatever changed it (a restyle,\n   * a resize, one just placed, a change the lender made itself): it draws live, by its\n   * {@link painter}, until the engine's picture of it is there.\n   */\n  pending(record: AnnotationRef): boolean;\n  /**\n   * How the lender draws the record live: the record upright in `box` (its box, or where a\n   * gesture has it), in page space; `null` for one it doesn't draw. A record with a painter\n   * draws live while a gesture reshapes it, as a square does.\n   */\n  painter(record: Annotation): ((box: Rect) => readonly SceneNode[]) | null;\n  /** Its records' pictures on a page, at rest, in every state, each with its record's picture version. */\n  renderAppearances(\n    page: PageRef,\n    scale: number,\n    signal?: AbortSignal,\n  ): Promise<readonly AppearancePicture[]>;\n}\n\nexport interface RecalibrationReport {\n  page: PageRef;\n  scale: PdfMeasure;\n  /** Page-wide read failure: no complete annotation set was available to recalculate. */\n  error?: SerializedEngineError;\n  updated: AnnotationRef[];\n  skipped: {\n    ref: AnnotationRef;\n    reason: 'no-authority' | 'locked' | 'foreign-measure' | 'unavailable';\n  }[];\n  failed: { ref: AnnotationRef; error: SerializedEngineError }[];\n}\n\nexport interface CapturedAnnotationDraft {\n  tool: string;\n  page: PageRef;\n  from: Point;\n  to: Point;\n}\n\n/**\n * Ghost render buckets: powers of two from 128 px up to `cap`. The same policy\n * the page renderer uses — one bitmap per size class, never per zoom step.\n */\nexport function previewBucket(devicePixelWidth: number, maxWidth = 4096): number {\n  const px = Math.max(128, Math.ceil(devicePixelWidth));\n  return Math.min(maxWidth, 2 ** Math.ceil(Math.log2(px)));\n}\n\n/**\n * The host (framework) surface: everything the render layer, the interaction hub,\n * and sibling plugins need, on top of the public {@link AnnotationCapability}.\n * Host-only: sibling plugins and framework adapters import the token from\n * `@embedpdf/plugin-annotation/contract/host`. Never use it from application code.\n */\nexport interface AnnotationHostCapability extends AnnotationCapability {\n  // ── measurement seam ──\n  setPageViewports(\n    page: PageRef,\n    viewports: PageMeasurementViewport[] | undefined,\n    fallback: PdfMeasure,\n  ): void;\n  remeasurePage(page: PageRef, scale: PdfMeasure): Promise<RecalibrationReport>;\n  /** A distance draft was captured (the measurement plugin turns it into a calibration). */\n  readonly onDraftCaptured: EventHook<CapturedAnnotationDraft>;\n  distanceCreationPage(): PageRef | null;\n\n  // ── render projections (page space; a view env projects for a rotated / zoomed view) ──\n  /**\n   * The selection's anchor as a page shows it: its rotation handle where the\n   * page's view puts it (screen-sized, so it depends on the zoom), for a menu\n   * that stays clear of it. `selection.getAnchor()` is the same without a view.\n   */\n  getSelectionAnchorIn(view: {\n    scale?: number;\n    rotation?: PageRotation;\n    zoom?: number;\n  }): AnnotationSelectionAnchor | null;\n  /**\n   * Where UI attaches to one annotation (its page and the box around what it\n   * shows, a drag in progress included), or `null` for one that isn't here.\n   * Without a view, an annotation that keeps its size on screen carries\n   * `boundsIn` for the view it's shown in.\n   */\n  getAnnotationAnchor(ref: AnnotationRef, view?: ViewEnv): AnnotationAnchor | null;\n  listPageItems(page: PageRef, view?: ViewEnv): RenderItem[];\n  listTextItems(page: PageRef, view?: ViewEnv): TextItem[];\n  listChromeNodes(\n    page: PageRef,\n    scale?: number,\n    rotation?: PageRotation,\n    zoom?: number,\n  ): ChromeNode[];\n  listLinkItems(page: PageRef): LinkNavItem[];\n  /**\n   * What a page's pictures depend on: its baked records at their picture\n   * versions, the stamps this session placed, the pictures kept for an undone\n   * delete and the lender's widgets. Load the pictures again when it changes,\n   * or when the appearance scale (`render.getAppearanceScale`) does.\n   */\n  getAppearanceEpoch(page: PageRef): string;\n  /**\n   * Every picture a page's annotations show at rest, in every state, each\n   * with its record's picture version: the engine's (through the render\n   * plugin; none without it), the lender's, and this session's placed stamps.\n   */\n  renderAppearances(\n    page: PageRef,\n    scale: number,\n    signal?: AbortSignal,\n  ): Promise<AnnotationAppearancePicture[]>;\n\n  // ── sync ──\n  /**\n   * Resolves once the annotations mirror has applied every confirmed change\n   * it knows of, including page re-reads that events started.\n   */\n  whenSynced(): Promise<void>;\n\n  // ── text editing (the editor's draft path: shown at once, written after a pause) ──\n  getEditingId(): Id | null;\n  beginTextEditAt(\n    page: PageRef,\n    point: Point,\n    scale?: number,\n    rotation?: PageRotation,\n    zoom?: number,\n  ): boolean;\n  draftContents(ref: AnnotationRef, text: string): void;\n  draftRichText(ref: AnnotationRef, doc: { paragraphs: RichTextParagraph[] }): void;\n  setTextSelection(ref: AnnotationRef, range: { start: number; end: number } | null): void;\n  getCssFontFamily(family: string): string;\n\n  // ── pointer routing ──\n  getHitKind(\n    page: PageRef,\n    point: Point,\n    scale?: number,\n    rotation?: PageRotation,\n    zoom?: number,\n    touch?: boolean,\n  ): 'handle' | 'rotate' | 'group-handle' | 'annot' | 'empty';\n  claimsTouchAt(\n    page: PageRef,\n    point: Point,\n    scale?: number,\n    rotation?: PageRotation,\n    zoom?: number,\n  ): boolean;\n  getCursorAt(\n    page: PageRef,\n    point: Point,\n    scale?: number,\n    rotation?: PageRotation,\n    zoom?: number,\n  ): string | null;\n  hoverAt(\n    at: {\n      page: PageRef;\n      point: Point;\n      scale?: number;\n      rotation?: PageRotation;\n      zoom?: number;\n    } | null,\n  ): void;\n  editPointer(\n    phase: 'down' | 'move' | 'up',\n    page: PageRef,\n    point: Point,\n    shift: boolean,\n    scale?: number,\n    rotation?: PageRotation,\n    zoom?: number,\n    touch?: boolean,\n  ): void;\n  marqueePointer(\n    phase: 'down' | 'move' | 'up',\n    page: PageRef,\n    point: Point,\n    shift: boolean,\n    scale?: number,\n    rotation?: PageRotation,\n    zoom?: number,\n  ): void;\n  createPointer(\n    tool: string,\n    phase: 'down' | 'move' | 'up',\n    page: PageRef,\n    point: Point,\n    finish?: boolean,\n    displayRotation?: PageRotation,\n  ): void;\n  finishInkDraft(): void;\n  /** Place with the active tool at a click; `displayRotation` and `zoom` are the page's view there. */\n  placeAt(page: PageRef, point: Point, displayRotation?: PageRotation, zoom?: number): boolean;\n  placeArmedStamp(page: PageRef, point: Point, displayRotation?: PageRotation): boolean;\n  requestStampAt(page: PageRef, point: Point, displayRotation?: PageRotation): boolean;\n\n  // ── markup bridge (the selection plugin meets the text tools) ──\n  /**\n   * Turn the text selection into what the tool makes of it (markup, a caret,\n   * a replace-text pair) and clear the selection; `false`, and nothing, for a\n   * tool that makes nothing of a selection, without create authority, or\n   * without a selection.\n   */\n  applyToolToSelection(toolId: string): boolean;\n  createMarkup(subtype: KindName, page: PageRef, quads: Quad[], preset?: string): void;\n  createCaret(page: PageRef, anchor: TextEndAnchor): void;\n  createReplaceText(page: PageRef, quads: Quad[], anchor: TextEndAnchor, preset?: string): void;\n  previewMarkup(subtype: KindName, quadsByPage: Record<number, Quad[]>, preset?: string): void;\n  clearMarkupPreview(): void;\n\n  // ── ghosts and previews (tools/ghost.ts) ──\n  /**\n   * Put the tool's ghost at a hover, what a click there would make;\n   * `displayRotation` and `zoom` are the page's view there. The handler that\n   * would take the click calls it, only where the click would reach it and\n   * the user may create; a tool without a ghost clears it.\n   */\n  hoverGhostAt(\n    toolId: string,\n    page: PageRef,\n    point: Point,\n    displayRotation?: PageRotation,\n    zoom?: number,\n  ): void;\n  clearGhost(): void;\n  /**\n   * A sibling plugin's placement gesture with one of this plugin's tools (the\n   * form palette's drag-to-place): its press and the pointer now. Once it is a\n   * drag, the page paints what releasing places; under that the tool's ghost\n   * still shows the click.\n   */\n  previewPlacement(toolId: string, page: PageRef, from: Point, to: Point): void;\n  clearPlacementPreview(): void;\n  /** The armed stamp's ghost on a page, for the render layer's `<img>`. */\n  getImageGhost(page: PageRef): ImageGhost | null;\n  /** The armed stamp: a new object on every arm, null when nothing is armed. */\n  getArmedStamp(): ArmedStampInfo | null;\n  /** Render the armed stamp's ghost preview for a device pixel width (cached per size bucket). */\n  renderArmedStampPreview(devicePixelWidth?: number): Promise<ArmedStampPreview | null>;\n\n  // ── extension ──\n  /**\n   * Show a sibling's records with the annotations and edit them with the same\n   * tools (see {@link AnnotationLender}). One lender at a time; returns the\n   * release.\n   */\n  lend(lender: AnnotationLender): Unsubscribe;\n  listResolvedTools(): ResolvedTool[];\n  getResolvedTool(id: string): ResolvedTool | null;\n  getToolSubtype(id: string): KindName;\n  registerBehavior(behavior: Behavior): Unsubscribe;\n  /** The engaged behavior that owns this annotation now, or `null`. */\n  getBehaviorFor(annotation: Annotation): Behavior | null;\n  pruneEngagedSelection(): void;\n  commitScriptEffects(entries: AnnotCommitEntry[]): Promise<AnnotCommitResult>;\n}\n\n/**\n * The annotation capability token, typed to the full\n * {@link AnnotationHostCapability} (the package internals and `/contract/host`\n * use this view). The package root exports the same runtime token narrowed to\n * {@link AnnotationCapability}.\n */\nexport const AnnotationToken = createHostToken<AnnotationHostCapability>(PublicAnnotationToken);\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAoBA,MAAa,2BAA2B;AACxC,MAAa,4BAA4B;AACzC,MAAa,2BAA2B;AACxC,MAAa,8BAA8B;;;;;;;;;;;;ACuI3C,SAAgB,cAAc,kBAA0B,WAAW,MAAc;CAE/E,OAAO,KAAK,IAAI,UAAU,KAAK,KAAK,KAAK,KAAK,KADnC,KAAK,IAAI,KAAK,KAAK,KAAK,gBAAgB,CACC,CAAC,CAAC,CAAC;AACzD;;;;;;;AA0NA,MAAa,kBAAkB,gBAA0CA,iBAAqB"}

package/dist/{contract-a4eaQWga.cjs → host-contract-DY9jFPPF.cjs}

@@ -1,31 +1,51 @@
-const require_types = require("./types-Dlhdw2k_.cjs");
+const require_contract = require("./contract-CPzpRG3h.cjs");
+let _embedpdf_core = require("@embedpdf/core");
 //#region src/priorities.ts
 /**
 * The interaction-hub priorities of the annotation plugin's handlers — the
-* public contract a sibling plugin builds on when it needs to sit ABOVE or
-* BELOW one of them for the same gesture. Priority only breaks ties between
-* simultaneously-ELIGIBLE handlers (the tool's tags decide eligibility).
+* public contract a sibling plugin builds on when it needs to sit above or
+* below one of them for the same gesture. Priority only breaks ties between
+* simultaneously-eligible handlers (the tool's tags decide eligibility).
 *
-*   1000 annotation-ghost   never captures; hides the footprint ghost on every down
 *    100 annotation-edit    select/move/resize over an existing annotation
 *     95 annotation-place   click-to-place an armed payload on empty page space
 *     55 annotation-draw    drag-create under a draw tool (below text-select)
 *     50 annotation-marquee empty-space selection, the final fallback
 *
+* Hover runs in the same order, so a handler's hover sees the cursor claims
+* of every handler above it: a create handler shows its tool's ghost only
+* where nothing above it claims the pointer (an annotation, text).
+*
 * A handler that must win a click over an existing annotation while a
 * placing tool is active (a signature mark dropped onto a signature field)
 * registers above {@link ANNOTATION_EDIT_PRIORITY}, not merely above place:
 * the edit handler captures first over any annotation, a widget included.
 */
-const ANNOTATION_GHOST_PRIORITY = 1e3;
 const ANNOTATION_EDIT_PRIORITY = 100;
 const ANNOTATION_PLACE_PRIORITY = 95;
 const ANNOTATION_DRAW_PRIORITY = 55;
 const ANNOTATION_MARQUEE_PRIORITY = 50;
 //#endregion
-//#region src/contract.ts
-/** The public lens over the host capability's one runtime token. */
-const AnnotationToken = require_types.AnnotationToken;
+//#region src/host-contract.ts
+/**
+* @embedpdf/plugin-annotation/contract/host — the host lens: render
+* projections, sync, pointer routing, ghosts, the markup bridge and the
+* extension seams. Same runtime token as the public one, typed wider.
+*/
+/**
+* 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.
+*/
+function previewBucket(devicePixelWidth, maxWidth = 4096) {
+	return Math.min(maxWidth, 2 ** Math.ceil(Math.log2(Math.max(128, Math.ceil(devicePixelWidth)))));
+}
+/**
+* The annotation capability token, typed to the full
+* {@link AnnotationHostCapability} (the package internals and `/contract/host`
+* use this view). The package root exports the same runtime token narrowed to
+* {@link AnnotationCapability}.
+*/
+const AnnotationToken = (0, _embedpdf_core.createHostToken)(require_contract.AnnotationToken);
 //#endregion
 Object.defineProperty(exports, "ANNOTATION_DRAW_PRIORITY", {
 	enumerable: true,
@@ -39,12 +59,6 @@ Object.defineProperty(exports, "ANNOTATION_EDIT_PRIORITY", {
 		return ANNOTATION_EDIT_PRIORITY;
 	}
 });
-Object.defineProperty(exports, "ANNOTATION_GHOST_PRIORITY", {
-	enumerable: true,
-	get: function() {
-		return ANNOTATION_GHOST_PRIORITY;
-	}
-});
 Object.defineProperty(exports, "ANNOTATION_MARQUEE_PRIORITY", {
 	enumerable: true,
 	get: function() {
@@ -63,5 +77,11 @@ Object.defineProperty(exports, "AnnotationToken", {
 		return AnnotationToken;
 	}
 });
+Object.defineProperty(exports, "previewBucket", {
+	enumerable: true,
+	get: function() {
+		return previewBucket;
+	}
+});
 
-//# sourceMappingURL=contract-a4eaQWga.cjs.map
+//# sourceMappingURL=host-contract-DY9jFPPF.cjs.map

package/dist/host-contract-DY9jFPPF.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-contract-DY9jFPPF.cjs","names":["PublicAnnotationToken"],"sources":["../src/priorities.ts","../src/host-contract.ts"],"sourcesContent":["/**\n * The interaction-hub priorities of the annotation plugin's handlers — the\n * public contract a sibling plugin builds on when it needs to sit above or\n * below one of them for the same gesture. Priority only breaks ties between\n * simultaneously-eligible handlers (the tool's tags decide eligibility).\n *\n *    100 annotation-edit    select/move/resize over an existing annotation\n *     95 annotation-place   click-to-place an armed payload on empty page space\n *     55 annotation-draw    drag-create under a draw tool (below text-select)\n *     50 annotation-marquee empty-space selection, the final fallback\n *\n * Hover runs in the same order, so a handler's hover sees the cursor claims\n * of every handler above it: a create handler shows its tool's ghost only\n * where nothing above it claims the pointer (an annotation, text).\n *\n * A handler that must win a click over an existing annotation while a\n * placing tool is active (a signature mark dropped onto a signature field)\n * registers above {@link ANNOTATION_EDIT_PRIORITY}, not merely above place:\n * the edit handler captures first over any annotation, a widget included.\n */\nexport const ANNOTATION_EDIT_PRIORITY = 100;\nexport const ANNOTATION_PLACE_PRIORITY = 95;\nexport const ANNOTATION_DRAW_PRIORITY = 55;\nexport const ANNOTATION_MARQUEE_PRIORITY = 50;\n","/**\n * @embedpdf/plugin-annotation/contract/host — the host lens: render\n * projections, sync, pointer routing, ghosts, the markup bridge and the\n * extension seams. Same runtime token as the public one, typed wider.\n */\nimport { createHostToken } from '@embedpdf/core';\nimport type { DocumentEvent, EventHook, PredictedOp, Unsubscribe } from '@embedpdf/core';\nimport type {\n  ChromeNode,\n  Effect,\n  Id,\n  Model,\n  Rect,\n  RenderItem,\n  SceneNode,\n  KindName,\n  TextEndAnchor,\n  Quad,\n  Point,\n  ViewEnv,\n} from '@embedpdf/core-annotation';\nimport type { PageRotation } from '@embedpdf/core-geometry';\nimport type {\n  AnnotationAppearanceImage,\n  AnnotationPosition,\n  AnnotationRef,\n  ChangeOp,\n  ImageSource,\n  PageMeasurementViewport,\n  PageRef,\n  PdfMeasure,\n  RichTextParagraph,\n  SerializedEngineError,\n} from '@embedpdf/engine-core/runtime';\nimport type { AnnotCommitEntry, AnnotCommitResult } from '@embedpdf/plugin-actions/contract/host';\nimport type { AppearancePicture } from '@embedpdf/plugin-render/contract/host';\n\nimport type {\n  Annotation,\n  AnnotationAnchor,\n  AnnotationCapability,\n  AnnotationSelectionAnchor,\n  ArmedStampInfo,\n  ArmedStampPreview,\n  Behavior,\n  LinkNavItem,\n  TextItem,\n  ImageGhost,\n} from './contract';\nimport { AnnotationToken as PublicAnnotationToken } from './token';\nimport type { ResolvedTool } from './tools/definitions';\n\nexport * from './contract';\nexport type { AnnotationState } from './model';\nexport {\n  ANNOTATION_DRAW_PRIORITY,\n  ANNOTATION_EDIT_PRIORITY,\n  ANNOTATION_MARQUEE_PRIORITY,\n  ANNOTATION_PLACE_PRIORITY,\n} from './priorities';\n\n/**\n * One annotation's look at rest in one of its states, as the render layer\n * paints it: the engine's picture, or, while the annotation's create is on\n * its way, the one this device made (a placed stamp's preview), which the\n * engine's replaces. `version` is the record's picture version it shows\n * (`RenderItem.pictureVersion`): one drawn at another version shows another look.\n */\nexport interface AnnotationAppearancePicture extends Pick<\n  AnnotationAppearanceImage,\n  'ref' | 'mode' | 'state' | 'rect'\n> {\n  readonly image: ImageSource;\n  readonly version: number;\n}\n\n/**\n * A sibling plugin that lends this plugin records it owns (the form plugin's\n * widgets), so they are selected, moved, resized, restyled and deleted with\n * the annotation tools. This plugin never stores them: it shows them as the\n * lender says, and an edit of one becomes the lender's ops, in the same change\n * as the rest of the edit.\n */\nexport interface AnnotationLender {\n  /** Who owns the records, for a refusal that sends you there (`'form'`). */\n  readonly owner: string;\n  /**\n   * Its records as the engine confirmed them and as they show, each list the\n   * same object until it changes; `null` while it lends none.\n   */\n  records(): {\n    readonly confirmed: readonly Annotation[];\n    readonly shown: readonly Annotation[];\n  } | null;\n  /**\n   * The ops that write a message's effects on its records, all at once:\n   * `model` is the model the message left, `before` the one it started from\n   * (a record it deleted is there).\n   */\n  opsOf(effects: readonly Effect[], model: Model, before: Model): readonly ChangeOp[];\n  /** What undoing these ops looks like. */\n  undoOf(ops: readonly ChangeOp[]): readonly PredictedOp[];\n  /** The ops that move these records of one page to `position` in its drawing order. */\n  reorderOps(\n    page: PageRef,\n    refs: readonly AnnotationRef[],\n    position: AnnotationPosition,\n  ): readonly ChangeOp[];\n  /** Whether this session may change and delete the record. */\n  authority(record: Annotation): { readonly update: boolean; readonly delete: boolean };\n  /** What its records' pictures on a page depend on: a new value means new pictures. */\n  pictureEpoch(page: PageRef): string;\n  /** A record's confirmed picture version; kept for one that went, so an undo brings it back with it. */\n  pictureVersion(record: AnnotationRef): number;\n  /**\n   * The record's look as it shows isn't its confirmed look yet, whatever changed it (a restyle,\n   * a resize, one just placed, a change the lender made itself): it draws live, by its\n   * {@link painter}, until the engine's picture of it is there.\n   */\n  pending(record: AnnotationRef): boolean;\n  /**\n   * How the lender draws the record live: the record upright in `box` (its box, or where a\n   * gesture has it), in page space; `null` for one it doesn't draw. A record with a painter\n   * draws live while a gesture reshapes it, as a square does.\n   */\n  painter(record: Annotation): ((box: Rect) => readonly SceneNode[]) | null;\n  /** Its records' pictures on a page, at rest, in every state, each with its record's picture version. */\n  renderAppearances(\n    page: PageRef,\n    scale: number,\n    signal?: AbortSignal,\n  ): Promise<readonly AppearancePicture[]>;\n}\n\nexport interface RecalibrationReport {\n  page: PageRef;\n  scale: PdfMeasure;\n  /** Page-wide read failure: no complete annotation set was available to recalculate. */\n  error?: SerializedEngineError;\n  updated: AnnotationRef[];\n  skipped: {\n    ref: AnnotationRef;\n    reason: 'no-authority' | 'locked' | 'foreign-measure' | 'unavailable';\n  }[];\n  failed: { ref: AnnotationRef; error: SerializedEngineError }[];\n}\n\nexport interface CapturedAnnotationDraft {\n  tool: string;\n  page: PageRef;\n  from: Point;\n  to: Point;\n}\n\n/**\n * Ghost render buckets: powers of two from 128 px up to `cap`. The same policy\n * the page renderer uses — one bitmap per size class, never per zoom step.\n */\nexport function previewBucket(devicePixelWidth: number, maxWidth = 4096): number {\n  const px = Math.max(128, Math.ceil(devicePixelWidth));\n  return Math.min(maxWidth, 2 ** Math.ceil(Math.log2(px)));\n}\n\n/**\n * The host (framework) surface: everything the render layer, the interaction hub,\n * and sibling plugins need, on top of the public {@link AnnotationCapability}.\n * Host-only: sibling plugins and framework adapters import the token from\n * `@embedpdf/plugin-annotation/contract/host`. Never use it from application code.\n */\nexport interface AnnotationHostCapability extends AnnotationCapability {\n  // ── measurement seam ──\n  setPageViewports(\n    page: PageRef,\n    viewports: PageMeasurementViewport[] | undefined,\n    fallback: PdfMeasure,\n  ): void;\n  remeasurePage(page: PageRef, scale: PdfMeasure): Promise<RecalibrationReport>;\n  /** A distance draft was captured (the measurement plugin turns it into a calibration). */\n  readonly onDraftCaptured: EventHook<CapturedAnnotationDraft>;\n  distanceCreationPage(): PageRef | null;\n\n  // ── render projections (page space; a view env projects for a rotated / zoomed view) ──\n  /**\n   * The selection's anchor as a page shows it: its rotation handle where the\n   * page's view puts it (screen-sized, so it depends on the zoom), for a menu\n   * that stays clear of it. `selection.getAnchor()` is the same without a view.\n   */\n  getSelectionAnchorIn(view: {\n    scale?: number;\n    rotation?: PageRotation;\n    zoom?: number;\n  }): AnnotationSelectionAnchor | null;\n  /**\n   * Where UI attaches to one annotation (its page and the box around what it\n   * shows, a drag in progress included), or `null` for one that isn't here.\n   * Without a view, an annotation that keeps its size on screen carries\n   * `boundsIn` for the view it's shown in.\n   */\n  getAnnotationAnchor(ref: AnnotationRef, view?: ViewEnv): AnnotationAnchor | null;\n  listPageItems(page: PageRef, view?: ViewEnv): RenderItem[];\n  listTextItems(page: PageRef, view?: ViewEnv): TextItem[];\n  listChromeNodes(\n    page: PageRef,\n    scale?: number,\n    rotation?: PageRotation,\n    zoom?: number,\n  ): ChromeNode[];\n  listLinkItems(page: PageRef): LinkNavItem[];\n  /**\n   * What a page's pictures depend on: its baked records at their picture\n   * versions, the stamps this session placed, the pictures kept for an undone\n   * delete and the lender's widgets. Load the pictures again when it changes,\n   * or when the appearance scale (`render.getAppearanceScale`) does.\n   */\n  getAppearanceEpoch(page: PageRef): string;\n  /**\n   * Every picture a page's annotations show at rest, in every state, each\n   * with its record's picture version: the engine's (through the render\n   * plugin; none without it), the lender's, and this session's placed stamps.\n   */\n  renderAppearances(\n    page: PageRef,\n    scale: number,\n    signal?: AbortSignal,\n  ): Promise<AnnotationAppearancePicture[]>;\n\n  // ── sync ──\n  /**\n   * Resolves once the annotations mirror has applied every confirmed change\n   * it knows of, including page re-reads that events started.\n   */\n  whenSynced(): Promise<void>;\n\n  // ── text editing (the editor's draft path: shown at once, written after a pause) ──\n  getEditingId(): Id | null;\n  beginTextEditAt(\n    page: PageRef,\n    point: Point,\n    scale?: number,\n    rotation?: PageRotation,\n    zoom?: number,\n  ): boolean;\n  draftContents(ref: AnnotationRef, text: string): void;\n  draftRichText(ref: AnnotationRef, doc: { paragraphs: RichTextParagraph[] }): void;\n  setTextSelection(ref: AnnotationRef, range: { start: number; end: number } | null): void;\n  getCssFontFamily(family: string): string;\n\n  // ── pointer routing ──\n  getHitKind(\n    page: PageRef,\n    point: Point,\n    scale?: number,\n    rotation?: PageRotation,\n    zoom?: number,\n    touch?: boolean,\n  ): 'handle' | 'rotate' | 'group-handle' | 'annot' | 'empty';\n  claimsTouchAt(\n    page: PageRef,\n    point: Point,\n    scale?: number,\n    rotation?: PageRotation,\n    zoom?: number,\n  ): boolean;\n  getCursorAt(\n    page: PageRef,\n    point: Point,\n    scale?: number,\n    rotation?: PageRotation,\n    zoom?: number,\n  ): string | null;\n  hoverAt(\n    at: {\n      page: PageRef;\n      point: Point;\n      scale?: number;\n      rotation?: PageRotation;\n      zoom?: number;\n    } | null,\n  ): void;\n  editPointer(\n    phase: 'down' | 'move' | 'up',\n    page: PageRef,\n    point: Point,\n    shift: boolean,\n    scale?: number,\n    rotation?: PageRotation,\n    zoom?: number,\n    touch?: boolean,\n  ): void;\n  marqueePointer(\n    phase: 'down' | 'move' | 'up',\n    page: PageRef,\n    point: Point,\n    shift: boolean,\n    scale?: number,\n    rotation?: PageRotation,\n    zoom?: number,\n  ): void;\n  createPointer(\n    tool: string,\n    phase: 'down' | 'move' | 'up',\n    page: PageRef,\n    point: Point,\n    finish?: boolean,\n    displayRotation?: PageRotation,\n  ): void;\n  finishInkDraft(): void;\n  /** Place with the active tool at a click; `displayRotation` and `zoom` are the page's view there. */\n  placeAt(page: PageRef, point: Point, displayRotation?: PageRotation, zoom?: number): boolean;\n  placeArmedStamp(page: PageRef, point: Point, displayRotation?: PageRotation): boolean;\n  requestStampAt(page: PageRef, point: Point, displayRotation?: PageRotation): boolean;\n\n  // ── markup bridge (the selection plugin meets the text tools) ──\n  /**\n   * Turn the text selection into what the tool makes of it (markup, a caret,\n   * a replace-text pair) and clear the selection; `false`, and nothing, for a\n   * tool that makes nothing of a selection, without create authority, or\n   * without a selection.\n   */\n  applyToolToSelection(toolId: string): boolean;\n  createMarkup(subtype: KindName, page: PageRef, quads: Quad[], preset?: string): void;\n  createCaret(page: PageRef, anchor: TextEndAnchor): void;\n  createReplaceText(page: PageRef, quads: Quad[], anchor: TextEndAnchor, preset?: string): void;\n  previewMarkup(subtype: KindName, quadsByPage: Record<number, Quad[]>, preset?: string): void;\n  clearMarkupPreview(): void;\n\n  // ── ghosts and previews (tools/ghost.ts) ──\n  /**\n   * Put the tool's ghost at a hover, what a click there would make;\n   * `displayRotation` and `zoom` are the page's view there. The handler that\n   * would take the click calls it, only where the click would reach it and\n   * the user may create; a tool without a ghost clears it.\n   */\n  hoverGhostAt(\n    toolId: string,\n    page: PageRef,\n    point: Point,\n    displayRotation?: PageRotation,\n    zoom?: number,\n  ): void;\n  clearGhost(): void;\n  /**\n   * A sibling plugin's placement gesture with one of this plugin's tools (the\n   * form palette's drag-to-place): its press and the pointer now. Once it is a\n   * drag, the page paints what releasing places; under that the tool's ghost\n   * still shows the click.\n   */\n  previewPlacement(toolId: string, page: PageRef, from: Point, to: Point): void;\n  clearPlacementPreview(): void;\n  /** The armed stamp's ghost on a page, for the render layer's `<img>`. */\n  getImageGhost(page: PageRef): ImageGhost | null;\n  /** The armed stamp: a new object on every arm, null when nothing is armed. */\n  getArmedStamp(): ArmedStampInfo | null;\n  /** Render the armed stamp's ghost preview for a device pixel width (cached per size bucket). */\n  renderArmedStampPreview(devicePixelWidth?: number): Promise<ArmedStampPreview | null>;\n\n  // ── extension ──\n  /**\n   * Show a sibling's records with the annotations and edit them with the same\n   * tools (see {@link AnnotationLender}). One lender at a time; returns the\n   * release.\n   */\n  lend(lender: AnnotationLender): Unsubscribe;\n  listResolvedTools(): ResolvedTool[];\n  getResolvedTool(id: string): ResolvedTool | null;\n  getToolSubtype(id: string): KindName;\n  registerBehavior(behavior: Behavior): Unsubscribe;\n  /** The engaged behavior that owns this annotation now, or `null`. */\n  getBehaviorFor(annotation: Annotation): Behavior | null;\n  pruneEngagedSelection(): void;\n  commitScriptEffects(entries: AnnotCommitEntry[]): Promise<AnnotCommitResult>;\n}\n\n/**\n * The annotation capability token, typed to the full\n * {@link AnnotationHostCapability} (the package internals and `/contract/host`\n * use this view). The package root exports the same runtime token narrowed to\n * {@link AnnotationCapability}.\n */\nexport const AnnotationToken = createHostToken<AnnotationHostCapability>(PublicAnnotationToken);\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAoBA,MAAa,2BAA2B;AACxC,MAAa,4BAA4B;AACzC,MAAa,2BAA2B;AACxC,MAAa,8BAA8B;;;;;;;;;;;;ACuI3C,SAAgB,cAAc,kBAA0B,WAAW,MAAc;CAE/E,OAAO,KAAK,IAAI,UAAU,KAAK,KAAK,KAAK,KAAK,KADnC,KAAK,IAAI,KAAK,KAAK,KAAK,gBAAgB,CACC,CAAC,CAAC,CAAC;AACzD;;;;;;;AA0NA,MAAa,mBAAA,GAAA,eAAA,gBAAA,CAA4DA,iBAAAA,eAAqB"}

package/dist/host-contract-Nzxwh0XS.d.cts

@@ -0,0 +1,310 @@
+import { Bt as ResolvedTool, Et as TextItem, G as ArmedStampInfo, K as ArmedStampPreview, N as AnnotationSelectionAnchor, Y as Behavior, ft as ImageGhost, gt as LinkNavItem, i as AnnotationAnchor, o as AnnotationCapability, qt as TextSelection, r as Annotation$1 } from "./contract-BK4LHe9v.cjs";
+import { ChromeNode, EditableKinds, Effect, Id, KindName, Model, Point, Quad, Rect, RenderItem, SceneNode, Session, SnapSettings, TextEndAnchor, ViewEnv } from "@embedpdf/core-annotation";
+import { EventHook, PredictedOp, Unsubscribe } from "@embedpdf/core";
+import { PageRotation } from "@embedpdf/core-geometry";
+import { AnnotationAppearanceImage, AnnotationPosition, AnnotationRef, ChangeOp, ImageSource, PageMeasurementViewport, PageRef, PdfMeasure, RichTextParagraph, SerializedEngineError } from "@embedpdf/engine-core/runtime";
+import { AnnotCommitEntry, AnnotCommitResult } from "@embedpdf/plugin-actions/contract/host";
+import { AppearancePicture } from "@embedpdf/plugin-render/contract/host";
+//#region src/model.d.ts
+/** Where the active tool's ghost is: the pointer on a page, and how that page shows there. */
+interface GhostPointer {
+  readonly toolId: string;
+  readonly page: PageRef;
+  readonly point: Point;
+  /** The page's display rotation at the pointer (an upright tool lays its click out as seen). */
+  readonly displayRotation?: PageRotation;
+  /** The page's zoom at the pointer (a screen-sized icon's size depends on it). */
+  readonly zoom?: number;
+}
+/** A sibling plugin's placement gesture with one of this plugin's tools: its press, and the pointer now. */
+interface ForeignPlacement {
+  readonly toolId: string;
+  readonly page: PageRef;
+  readonly from: Point;
+  readonly to: Point;
+}
+interface AnnotationState {
+  /** The core's session: selection, hover, the gesture in progress, tool settings. */
+  readonly session: Session;
+  /**
+   * Records this session renders from their description instead of the
+   * engine's raster: the ones it edited or created. Another session's edit
+   * hands a record back to the raster (see sync/confirmed.ts).
+   */
+  readonly vector: Readonly<Record<Id, true>>;
+  /**
+   * Where the active tool's ghost is: the pointer, while a click there would
+   * make something. Only the pointer is state; what the ghost paints is
+   * derived from it and the tool's live defaults (tools/ghost.ts).
+   */
+  readonly ghostAt: GhostPointer | null;
+  /**
+   * A placement a sibling plugin's gesture is making with one of this
+   * plugin's tools (the form palette's drag-to-place). Once it is a drag it
+   * paints as a drawing in progress (tools/ghost.ts).
+   */
+  readonly placing: ForeignPlacement | null;
+  /**
+   * The text editor's selection inside the annotation being edited (flat
+   * offsets over its plain text), or null. It is state because the property
+   * surface reads it: while a range is held, the text style keys report and
+   * change the runs, not the whole body.
+   */
+  readonly textSelection: TextSelection | null;
+}
+//#endregion
+//#region src/priorities.d.ts
+/**
+ * The interaction-hub priorities of the annotation plugin's handlers — the
+ * public contract a sibling plugin builds on when it needs to sit above or
+ * below one of them for the same gesture. Priority only breaks ties between
+ * simultaneously-eligible handlers (the tool's tags decide eligibility).
+ *
+ *    100 annotation-edit    select/move/resize over an existing annotation
+ *     95 annotation-place   click-to-place an armed payload on empty page space
+ *     55 annotation-draw    drag-create under a draw tool (below text-select)
+ *     50 annotation-marquee empty-space selection, the final fallback
+ *
+ * Hover runs in the same order, so a handler's hover sees the cursor claims
+ * of every handler above it: a create handler shows its tool's ghost only
+ * where nothing above it claims the pointer (an annotation, text).
+ *
+ * A handler that must win a click over an existing annotation while a
+ * placing tool is active (a signature mark dropped onto a signature field)
+ * registers above {@link ANNOTATION_EDIT_PRIORITY}, not merely above place:
+ * the edit handler captures first over any annotation, a widget included.
+ */
+declare const ANNOTATION_EDIT_PRIORITY = 100;
+declare const ANNOTATION_PLACE_PRIORITY = 95;
+declare const ANNOTATION_DRAW_PRIORITY = 55;
+declare const ANNOTATION_MARQUEE_PRIORITY = 50;
+//#endregion
+//#region src/host-contract.d.ts
+/**
+ * One annotation's look at rest in one of its states, as the render layer
+ * paints it: the engine's picture, or, while the annotation's create is on
+ * its way, the one this device made (a placed stamp's preview), which the
+ * engine's replaces. `version` is the record's picture version it shows
+ * (`RenderItem.pictureVersion`): one drawn at another version shows another look.
+ */
+interface AnnotationAppearancePicture extends Pick<AnnotationAppearanceImage, 'ref' | 'mode' | 'state' | 'rect'> {
+  readonly image: ImageSource;
+  readonly version: number;
+}
+/**
+ * A sibling plugin that lends this plugin records it owns (the form plugin's
+ * widgets), so they are selected, moved, resized, restyled and deleted with
+ * the annotation tools. This plugin never stores them: it shows them as the
+ * lender says, and an edit of one becomes the lender's ops, in the same change
+ * as the rest of the edit.
+ */
+interface AnnotationLender {
+  /** Who owns the records, for a refusal that sends you there (`'form'`). */
+  readonly owner: string;
+  /**
+   * Its records as the engine confirmed them and as they show, each list the
+   * same object until it changes; `null` while it lends none.
+   */
+  records(): {
+    readonly confirmed: readonly Annotation$1[];
+    readonly shown: readonly Annotation$1[];
+  } | null;
+  /**
+   * The ops that write a message's effects on its records, all at once:
+   * `model` is the model the message left, `before` the one it started from
+   * (a record it deleted is there).
+   */
+  opsOf(effects: readonly Effect[], model: Model, before: Model): readonly ChangeOp[];
+  /** What undoing these ops looks like. */
+  undoOf(ops: readonly ChangeOp[]): readonly PredictedOp[];
+  /** The ops that move these records of one page to `position` in its drawing order. */
+  reorderOps(page: PageRef, refs: readonly AnnotationRef[], position: AnnotationPosition): readonly ChangeOp[];
+  /** Whether this session may change and delete the record. */
+  authority(record: Annotation$1): {
+    readonly update: boolean;
+    readonly delete: boolean;
+  };
+  /** What its records' pictures on a page depend on: a new value means new pictures. */
+  pictureEpoch(page: PageRef): string;
+  /** A record's confirmed picture version; kept for one that went, so an undo brings it back with it. */
+  pictureVersion(record: AnnotationRef): number;
+  /**
+   * The record's look as it shows isn't its confirmed look yet, whatever changed it (a restyle,
+   * a resize, one just placed, a change the lender made itself): it draws live, by its
+   * {@link painter}, until the engine's picture of it is there.
+   */
+  pending(record: AnnotationRef): boolean;
+  /**
+   * How the lender draws the record live: the record upright in `box` (its box, or where a
+   * gesture has it), in page space; `null` for one it doesn't draw. A record with a painter
+   * draws live while a gesture reshapes it, as a square does.
+   */
+  painter(record: Annotation$1): ((box: Rect) => readonly SceneNode[]) | null;
+  /** Its records' pictures on a page, at rest, in every state, each with its record's picture version. */
+  renderAppearances(page: PageRef, scale: number, signal?: AbortSignal): Promise<readonly AppearancePicture[]>;
+}
+interface RecalibrationReport {
+  page: PageRef;
+  scale: PdfMeasure;
+  /** Page-wide read failure: no complete annotation set was available to recalculate. */
+  error?: SerializedEngineError;
+  updated: AnnotationRef[];
+  skipped: {
+    ref: AnnotationRef;
+    reason: 'no-authority' | 'locked' | 'foreign-measure' | 'unavailable';
+  }[];
+  failed: {
+    ref: AnnotationRef;
+    error: SerializedEngineError;
+  }[];
+}
+interface CapturedAnnotationDraft {
+  tool: string;
+  page: PageRef;
+  from: Point;
+  to: Point;
+}
+/**
+ * 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, maxWidth?: number): number;
+/**
+ * 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 and framework adapters import the token from
+ * `@embedpdf/plugin-annotation/contract/host`. Never use it from application code.
+ */
+interface AnnotationHostCapability extends AnnotationCapability {
+  setPageViewports(page: PageRef, viewports: PageMeasurementViewport[] | undefined, fallback: PdfMeasure): void;
+  remeasurePage(page: PageRef, scale: PdfMeasure): Promise<RecalibrationReport>;
+  /** A distance draft was captured (the measurement plugin turns it into a calibration). */
+  readonly onDraftCaptured: EventHook<CapturedAnnotationDraft>;
+  distanceCreationPage(): PageRef | null;
+  /**
+   * The selection's anchor as a page shows it: its rotation handle where the
+   * page's view puts it (screen-sized, so it depends on the zoom), for a menu
+   * that stays clear of it. `selection.getAnchor()` is the same without a view.
+   */
+  getSelectionAnchorIn(view: {
+    scale?: number;
+    rotation?: PageRotation;
+    zoom?: number;
+  }): AnnotationSelectionAnchor | null;
+  /**
+   * Where UI attaches to one annotation (its page and the box around what it
+   * shows, a drag in progress included), or `null` for one that isn't here.
+   * Without a view, an annotation that keeps its size on screen carries
+   * `boundsIn` for the view it's shown in.
+   */
+  getAnnotationAnchor(ref: AnnotationRef, view?: ViewEnv): AnnotationAnchor | null;
+  listPageItems(page: PageRef, view?: ViewEnv): RenderItem[];
+  listTextItems(page: PageRef, view?: ViewEnv): TextItem[];
+  listChromeNodes(page: PageRef, scale?: number, rotation?: PageRotation, zoom?: number): ChromeNode[];
+  listLinkItems(page: PageRef): LinkNavItem[];
+  /**
+   * What a page's pictures depend on: its baked records at their picture
+   * versions, the stamps this session placed, the pictures kept for an undone
+   * delete and the lender's widgets. Load the pictures again when it changes,
+   * or when the appearance scale (`render.getAppearanceScale`) does.
+   */
+  getAppearanceEpoch(page: PageRef): string;
+  /**
+   * Every picture a page's annotations show at rest, in every state, each
+   * with its record's picture version: the engine's (through the render
+   * plugin; none without it), the lender's, and this session's placed stamps.
+   */
+  renderAppearances(page: PageRef, scale: number, signal?: AbortSignal): Promise<AnnotationAppearancePicture[]>;
+  /**
+   * Resolves once the annotations mirror has applied every confirmed change
+   * it knows of, including page re-reads that events started.
+   */
+  whenSynced(): Promise<void>;
+  getEditingId(): Id | null;
+  beginTextEditAt(page: PageRef, point: Point, scale?: number, rotation?: PageRotation, zoom?: number): boolean;
+  draftContents(ref: AnnotationRef, text: string): void;
+  draftRichText(ref: AnnotationRef, doc: {
+    paragraphs: RichTextParagraph[];
+  }): void;
+  setTextSelection(ref: AnnotationRef, range: {
+    start: number;
+    end: number;
+  } | null): void;
+  getCssFontFamily(family: string): string;
+  getHitKind(page: PageRef, point: Point, scale?: number, rotation?: PageRotation, zoom?: number, touch?: boolean): 'handle' | 'rotate' | 'group-handle' | 'annot' | 'empty';
+  claimsTouchAt(page: PageRef, point: Point, scale?: number, rotation?: PageRotation, zoom?: number): boolean;
+  getCursorAt(page: PageRef, point: Point, scale?: number, rotation?: PageRotation, zoom?: number): string | null;
+  hoverAt(at: {
+    page: PageRef;
+    point: Point;
+    scale?: number;
+    rotation?: PageRotation;
+    zoom?: number;
+  } | null): void;
+  editPointer(phase: 'down' | 'move' | 'up', page: PageRef, point: Point, shift: boolean, scale?: number, rotation?: PageRotation, zoom?: number, touch?: boolean): void;
+  marqueePointer(phase: 'down' | 'move' | 'up', page: PageRef, point: Point, shift: boolean, scale?: number, rotation?: PageRotation, zoom?: number): void;
+  createPointer(tool: string, phase: 'down' | 'move' | 'up', page: PageRef, point: Point, finish?: boolean, displayRotation?: PageRotation): void;
+  finishInkDraft(): void;
+  /** Place with the active tool at a click; `displayRotation` and `zoom` are the page's view there. */
+  placeAt(page: PageRef, point: Point, displayRotation?: PageRotation, zoom?: number): boolean;
+  placeArmedStamp(page: PageRef, point: Point, displayRotation?: PageRotation): boolean;
+  requestStampAt(page: PageRef, point: Point, displayRotation?: PageRotation): boolean;
+  /**
+   * Turn the text selection into what the tool makes of it (markup, a caret,
+   * a replace-text pair) and clear the selection; `false`, and nothing, for a
+   * tool that makes nothing of a selection, without create authority, or
+   * without a selection.
+   */
+  applyToolToSelection(toolId: string): boolean;
+  createMarkup(subtype: KindName, page: PageRef, quads: Quad[], preset?: string): void;
+  createCaret(page: PageRef, anchor: TextEndAnchor): void;
+  createReplaceText(page: PageRef, quads: Quad[], anchor: TextEndAnchor, preset?: string): void;
+  previewMarkup(subtype: KindName, quadsByPage: Record<number, Quad[]>, preset?: string): void;
+  clearMarkupPreview(): void;
+  /**
+   * Put the tool's ghost at a hover, what a click there would make;
+   * `displayRotation` and `zoom` are the page's view there. The handler that
+   * would take the click calls it, only where the click would reach it and
+   * the user may create; a tool without a ghost clears it.
+   */
+  hoverGhostAt(toolId: string, page: PageRef, point: Point, displayRotation?: PageRotation, zoom?: number): void;
+  clearGhost(): void;
+  /**
+   * A sibling plugin's placement gesture with one of this plugin's tools (the
+   * form palette's drag-to-place): its press and the pointer now. Once it is a
+   * drag, the page paints what releasing places; under that the tool's ghost
+   * still shows the click.
+   */
+  previewPlacement(toolId: string, page: PageRef, from: Point, to: Point): void;
+  clearPlacementPreview(): void;
+  /** The armed stamp's ghost on a page, for the render layer's `<img>`. */
+  getImageGhost(page: PageRef): ImageGhost | null;
+  /** The armed stamp: a new object on every arm, null when nothing is armed. */
+  getArmedStamp(): ArmedStampInfo | null;
+  /** Render the armed stamp's ghost preview for a device pixel width (cached per size bucket). */
+  renderArmedStampPreview(devicePixelWidth?: number): Promise<ArmedStampPreview | null>;
+  /**
+   * Show a sibling's records with the annotations and edit them with the same
+   * tools (see {@link AnnotationLender}). One lender at a time; returns the
+   * release.
+   */
+  lend(lender: AnnotationLender): Unsubscribe;
+  listResolvedTools(): ResolvedTool[];
+  getResolvedTool(id: string): ResolvedTool | null;
+  getToolSubtype(id: string): KindName;
+  registerBehavior(behavior: Behavior): Unsubscribe;
+  /** The engaged behavior that owns this annotation now, or `null`. */
+  getBehaviorFor(annotation: Annotation$1): Behavior | null;
+  pruneEngagedSelection(): void;
+  commitScriptEffects(entries: AnnotCommitEntry[]): Promise<AnnotCommitResult>;
+}
+/**
+ * The annotation capability token, typed to the full
+ * {@link AnnotationHostCapability} (the package internals and `/contract/host`
+ * use this view). The package root exports the same runtime token narrowed to
+ * {@link AnnotationCapability}.
+ */
+declare const AnnotationToken: import("@embedpdf/core").CapabilityToken<AnnotationHostCapability>;
+//#endregion
+export { CapturedAnnotationDraft as a, ANNOTATION_DRAW_PRIORITY as c, ANNOTATION_PLACE_PRIORITY as d, AnnotationState as f, AnnotationToken as i, ANNOTATION_EDIT_PRIORITY as l, AnnotationHostCapability as n, RecalibrationReport as o, AnnotationLender as r, previewBucket as s, AnnotationAppearancePicture as t, ANNOTATION_MARQUEE_PRIORITY as u };
+//# sourceMappingURL=host-contract-Nzxwh0XS.d.cts.map