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

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

@@ -1,8 +1,22 @@
-import { AnnotationFlags, AnnotationProps, AnnotationPropsPatch, ChromeNode, ClickCreate, CreationDraftAnchor, Geom, Id, InkStraightenOptions, Model, PropKey, PropSpec, Rect, RenderItem, SnapSettings, Subtype, TextEndAnchor, TextQuad, Vec, ViewEnv } from "@embedpdf/core-annotation";
-import { AnnotationAppearanceImage, AnnotationDTO, AnnotationDraft, AnnotationPatch, AnnotationRef, AttachmentContent, AttachmentFileSource, BinarySource, CommentThread, InkIntent, PdfActionTree, PdfLinkTarget, PdfRect } from "@embedpdf/engine-core/runtime";
+import { 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 { AnnotationAppearanceImage, AnnotationDTO, AnnotationDraft, AnnotationPatch, AnnotationRef, AttachmentContent, AttachmentFileSource, BinarySource, CommentThread, InkIntent, PdfActionTree, PdfLinkTarget, PdfRect, RichTextParagraph } from "@embedpdf/engine-core/runtime";
 import { DocumentEvent, PageObjectNumber } from "@embedpdf/core";
 import { AnnotCommitEntry, AnnotCommitResult } from "@embedpdf/plugin-actions/contract/host";
 import { PageRotation } from "@embedpdf/core-geometry";
+//#region src/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
@@ -28,6 +42,15 @@ 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';
@@ -69,8 +92,8 @@ declare const TOOL_DEFAULT_KEYS: {
   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", "textAlign", "opacity", "interiorColor", "color", "strokeWidth", "border"];
-  readonly 'free-text-callout': readonly ["fontFamily", "fontSize", "fontColor", "textAlign", "opacity", "interiorColor", "color", "strokeWidth", "border", "lineEndings"];
+  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"];
@@ -84,6 +107,7 @@ declare const TOOL_DEFAULT_KEYS: {
   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];
@@ -351,6 +375,13 @@ interface AnnotationState {
   /** 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 = {
@@ -407,6 +438,9 @@ type AnnotationAction = {
 } | {
   type: 'SET_TOOL_GHOST';
   ghost: ToolGhost | null;
+} | {
+  type: 'SET_TEXT_SELECTION';
+  selection: TextSelection | null;
 } | {
   type: 'STAMP_ARM_CHANGED';
 };
@@ -475,27 +509,38 @@ 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.
+ * 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). */
+    /** 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;
-    lineHeight: 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;
-    /** `/C` box background as a CSS colour, or null for transparent. */
-    background: string | null;
   };
 }
 /**
@@ -623,6 +668,14 @@ interface AnnotationCapability {
    * `{ 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
@@ -724,6 +777,13 @@ interface AnnotationCapability {
   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
@@ -772,14 +832,18 @@ interface StampToolInput {
   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;
   /**
-   * A browser-paintable render of `source` for the hover ghost (PNG/JPEG).
-   * Required for the ghost when `source` is PDF bytes — the browser cannot
-   * paint those; the caller (e.g. a stamp library) supplies its cached page
-   * render. Raster sources default to the source itself; omit everywhere
-   * else and the tool simply shows no ghost.
+   * 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;
+  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 —
@@ -797,6 +861,33 @@ 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
@@ -925,6 +1016,24 @@ interface AnnotationHostCapability extends AnnotationCapability {
   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.
@@ -1040,8 +1149,13 @@ interface AnnotationHostCapability extends AnnotationCapability {
    *  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 bytes, or null (no ghost to show). */
-  armedStampPreview(): ArmedStampPreview | 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;
   /**
@@ -1082,5 +1196,5 @@ interface AnnotationHostCapability extends AnnotationCapability {
  */
 declare const AnnotationToken: import("@embedpdf/core").CapabilityToken<AnnotationHostCapability>;
 //#endregion
-export { StampSourceSpec as A, AnnotationToolInput as C, PromptSourceSpec as D, InkAuthoringOptions as E, ToolDefaultsFor as M, buildToolRegistry as N, ResolvedTool as O, AnnotationToolDef as S, GhostPolicy as T, SelectionProps as _, AnnotationHydration as a, ThreadDeleteResult as b, Behavior as c, CommentPermissions as d, CommentsApi as f, SelectionFlags as g, LinkNavItem as h, AnnotationHostCapability as i, ToolAuthoringKind as j, SelectionAuthoring as k, ChromeSettings as l, FilePromptRequest as m, AnnotationCapability as n, AnnotationState as o, FilePickerProvider as p, AnnotationConfig as r, AnnotationToken as s, AnnotationAction as t, ChromeSettingsPatch as u, StampToolInput as v, DEFAULT_TOOLS as w, ToolGhost as x, TextItem as y };
-//# sourceMappingURL=types-eLTpocXz.d.cts.map
+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-ObcPYc3-.d.cts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@embedpdf/plugin-annotation",
-  "version": "3.0.0-next.11",
+  "version": "3.0.0-next.13",
   "private": false,
   "description": "Annotation feature plugin: the pure annotation-core wired to the engine repository (optimistic create/patch/delete) + the interaction hub (ambient edit + draw tools). Behaviors (forms) plug in here.",
   "type": "module",
@@ -34,14 +34,14 @@
     "dist"
   ],
   "dependencies": {
-    "@embedpdf/core-annotation": "3.0.0-next.11",
-    "@embedpdf/core-geometry": "3.0.0-next.11",
-    "@embedpdf/core": "3.0.0-next.11",
-    "@embedpdf/plugin-selection": "3.0.0-next.11",
-    "@embedpdf/plugin-interaction": "3.0.0-next.11",
-    "@embedpdf/engine-core": "3.0.0-next.11",
-    "@embedpdf/core-acrojs": "3.0.0-next.11",
-    "@embedpdf/plugin-actions": "3.0.0-next.11"
+    "@embedpdf/core": "3.0.0-next.13",
+    "@embedpdf/core-annotation": "3.0.0-next.13",
+    "@embedpdf/plugin-interaction": "3.0.0-next.13",
+    "@embedpdf/core-geometry": "3.0.0-next.13",
+    "@embedpdf/plugin-selection": "3.0.0-next.13",
+    "@embedpdf/engine-core": "3.0.0-next.13",
+    "@embedpdf/core-acrojs": "3.0.0-next.13",
+    "@embedpdf/plugin-actions": "3.0.0-next.13"
   },
   "devDependencies": {
     "typescript": "^5.0.0",