@embedpdf/core-annotation 3.0.0-next.12 → 3.0.0-next.14

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { AnnotationDTO, AnnotationFlags, AnnotationFlags as AnnotationFlags$1, AnnotationRef, BlendMode, BlendMode as BlendMode$1, CaretIntent, InkIntent, LineEnding, LineEndings, NO_ANNOTATION_FLAGS, PdfLinkTarget, PdfPoint, PdfRect, StrikeoutIntent } from "@embedpdf/engine-core/runtime";
 import { PageRotation, Point, Rect as Rect$1, Size, TextQuad, TextQuad as TextQuad$1 } from "@embedpdf/core-geometry";
+import { AnnotationDTO, AnnotationFlags, AnnotationFlags as AnnotationFlags$1, AnnotationRef, BlendMode, BlendMode as BlendMode$1, CaretIntent, InkIntent, LineDimensionCaption, LineEnding, LineEndings, LineLeader, NO_ANNOTATION_FLAGS, PdfLinkTarget, PdfMeasurement, PdfPoint, PdfRect, RichTextDocumentInput, RichTextParagraph, RichTextRunStyle, ShapeDimensionCaption, StrikeoutIntent } from "@embedpdf/engine-core/runtime";
 import { PageObjectNumber } from "@embedpdf/core";
 //#region src/flags.d.ts
 /** The `/F` every freshly DRAWN annotation starts with: `print` set (Acrobat
@@ -46,6 +46,92 @@ declare const annotDeletable: (a: FlagBearer) => boolean;
 /** `/Contents` text edits — the contents counterpart of `locked`. */
 declare const annotContentsEditable: (a: FlagBearer) => boolean;
 //#endregion
+//#region src/measurement-shape.d.ts
+interface ShapeMeasurementAppearance {
+  intent: 'PolyLineDimension' | 'PolygonDimension';
+  measure: PdfMeasurement | null;
+  caption: ShapeDimensionCaption;
+  crop: PdfRect;
+  text: string;
+}
+interface ShapeMeasurementLayout {
+  caption: DistanceCaptionLayout | null;
+  visualBounds: Rect;
+  selectionPoints: Vec[];
+}
+/** The public caption center stays in PDF space; the editor draws in content space. */
+declare function shapeCaptionPoint(appearance: ShapeMeasurementAppearance): Vec | undefined;
+declare function withShapeCaptionPoint(appearance: ShapeMeasurementAppearance, center: Vec): ShapeMeasurementAppearance;
+declare function transformMeasurementCaption(appearance: MeasurementAppearance | undefined, transform: (point: Vec) => Vec): MeasurementAppearance | undefined;
+declare function shapeMeasurementReadout(geom: Geom, appearance: ShapeMeasurementAppearance): import("@embedpdf/engine-core/runtime").MeasurementReadout | import("@embedpdf/engine-core/runtime").MeasurementUnavailable;
+declare function shapeMeasurementLabel(geom: Geom, appearance: ShapeMeasurementAppearance): string;
+/** Match the native shape-caption anchor, including an interior fallback for concave areas. */
+declare function automaticShapeCaptionCenter(points: readonly Vec[], closed: boolean): Vec;
+declare function shapeMeasurementLayout(geom: Geom, appearance: ShapeMeasurementAppearance, style: Style): ShapeMeasurementLayout | null;
+declare function measurementLayout(geom: Geom, appearance: MeasurementAppearance, style: Style): ShapeMeasurementLayout | null;
+declare function measurementSelectionQuad(geom: Geom, appearance: MeasurementAppearance, style: Style): Quad;
+declare function moveMeasurementCaption(geom: Geom, appearance: MeasurementAppearance, delta: Vec, style: Style): MeasurementAppearance;
+//#endregion
+//#region src/measurement.d.ts
+type MeasurementAppearance = DistanceAppearance | ShapeMeasurementAppearance;
+/**
+ * A distance annotation's render projection. Offsets stay in directed PDF line
+ * axes. The crop keeps numeric rounding in the original PDF coordinate frame.
+ */
+interface DistanceAppearance {
+  intent: 'LineDimension';
+  measure: PdfMeasurement | null;
+  caption: LineDimensionCaption;
+  leader?: LineLeader;
+  crop: PdfRect;
+  text: string;
+}
+interface DistanceSegment {
+  from: Vec;
+  to: Vec;
+}
+interface DistanceCaptionLayout {
+  text: string;
+  center: Vec;
+  along: Vec;
+  normal: Vec;
+  width: number;
+  height: number;
+  bounds: Quad;
+}
+/** One layout drives the preview, selection, handles, and hit testing. */
+interface DistanceLayout {
+  along: Vec;
+  normal: Vec;
+  length: number;
+  measuredStart: Vec;
+  measuredEnd: Vec;
+  dimensionStart: Vec;
+  dimensionEnd: Vec;
+  dimensionSegments: DistanceSegment[];
+  leaderSegments: DistanceSegment[];
+  captionConnector: DistanceSegment[];
+  caption: DistanceCaptionLayout | null;
+  arrowPlacement: 'inside' | 'outside';
+  endings: RenderNode[];
+  selectionPoints: Vec[];
+  visualBounds: Rect;
+}
+declare function distanceLabel(geom: Geom, appearance: DistanceAppearance): string;
+declare function distanceLayout(geom: Geom, appearance: DistanceAppearance, strokeWidth: number): DistanceLayout | null;
+declare function expandDistanceBounds(bounds: Rect, padding: number): Rect;
+declare function distanceSelectionQuad(geom: Geom, appearance: DistanceAppearance, strokeWidth: number): Quad;
+declare function distanceHandles(layout: DistanceLayout): Handle[];
+declare function distanceCaptionHit(layout: {
+  caption: DistanceCaptionLayout | null;
+}, point: Vec, margin?: number): boolean;
+declare function distanceHit(layout: DistanceLayout, point: Vec, strokeWidth: number, margin: number): boolean;
+declare function distanceCaptionAt(geom: Geom, appearance: DistanceAppearance, width: number): Vec | null;
+declare function distanceLeaderLength(geom: Geom, point: Vec): number;
+declare function moveDistanceCaption(geom: Geom, appearance: DistanceAppearance, delta: Vec): DistanceAppearance;
+declare function distanceScene(geom: Geom, appearance: DistanceAppearance, style: Style): SceneNode[];
+declare function measurementCaptionScene(caption: DistanceCaptionLayout | null, style: Style): SceneNode[];
+//#endregion
 //#region src/types.d.ts
 /**
  * Content-space point/rect (y-down, PDF points, crop-relative) — the viewer space.
@@ -196,6 +282,15 @@ interface TextStyle {
   fontSize: number;
   fontColor: string;
   textAlign: TextAlign;
+  /**
+   * The rich body's formatting (free text only): bold = body weight ≥ 600,
+   * italic = the body face's italic, underline = the body's decoration.
+   * Absent = off. Runs override these as deltas (a bold word in a regular
+   * box), which the plugin routes to the editor's text selection instead.
+   */
+  bold?: boolean;
+  italic?: boolean;
+  underline?: boolean;
 }
 /**
  * The ONE flat vocabulary for editable appearance properties — what property
@@ -236,6 +331,10 @@ type PropKey = keyof AnnotationProps;
  */
 type PatchScope = {
   kind: 'geometry';
+} | {
+  kind: 'caption';
+} | {
+  kind: 'leader';
 } | {
   kind: 'props';
   keys: PropKey[];
@@ -259,6 +358,7 @@ interface Annot {
     text: string;
     repeat: boolean;
   };
+  measure?: MeasurementAppearance;
   /** `/Name` icon — present only for icon kinds (text note, file attachment).
    *  Like `style`, a projection of `data`, editable via `setProps`. */
   icon?: string;
@@ -395,8 +495,20 @@ type Draft = {
   /** The tool's `/F` seed, captured at DOWN like `upright` — merged over
    *  {@link DRAWN_FLAGS} at commit (a note tool sets noZoom/noRotate). */
   flags?: Partial<AnnotationFlags$1>;
+} | {
+  g: 'create-distance';
+  step: 'endpoints' | 'offset';
+  subtype: 'line';
+  preset: string;
+  pon: PageObjectNumber;
+  from: Vec;
+  to: Vec;
+  measure: DistanceAppearance;
+  flags?: Partial<AnnotationFlags$1>;
 } | {
   g: 'create-line';
+  measure?: MeasurementAppearance;
+  capture?: string;
   subtype: Subtype;
   preset?: string;
   pon: PageObjectNumber;
@@ -408,6 +520,7 @@ type Draft = {
   flags?: Partial<AnnotationFlags$1>;
 } | {
   g: 'create-poly';
+  measure?: ShapeMeasurementAppearance;
   subtype: Subtype;
   preset?: string;
   pon: PageObjectNumber;
@@ -474,6 +587,16 @@ type Draft = {
   base: Rect;
   cur: Rect;
   view?: ViewEnv;
+} | {
+  g: 'caption';
+  id: Id;
+  start: Vec;
+  delta: Vec;
+} | {
+  g: 'leader';
+  id: Id;
+  start: Vec;
+  delta: number;
 } | {
   g: 'marquee';
   pon: PageObjectNumber;
@@ -622,6 +745,8 @@ type Msg = {
   in: PointerInput;
 } | {
   t: 'createPointer';
+  measure?: MeasurementAppearance;
+  capture?: string;
   phase: 'down' | 'move' | 'up';
   subtype: Subtype;
   /** The authoring tool's `defaults` key (see {@link Draft}). Defaults to `subtype`. */
@@ -750,10 +875,19 @@ type Msg = {
   t: 'setText';
   id: Id;
   text: string;
+} | {
+  t: 'setRichText';
+  id: Id;
+  doc: RichTextDocumentInput;
 } | {
   t: 'endTextEdit';
 };
 type Effect = {
+  fx: 'captured';
+  tool: string;
+  pon: number;
+  geom: Geom;
+} | {
   fx: 'create';
   id: Id;
 } | {
@@ -837,6 +971,7 @@ interface RenderItem {
     text: string;
     repeat: boolean;
   };
+  measure?: MeasurementAppearance;
   /**
    * Applied rotation (deg, CW), or 0/undefined. For BOX kinds (`rect`/`text`)
    * `box` is the UNROTATED visual box and the renderer applies this rotation
@@ -927,6 +1062,7 @@ type SceneNode = {
   text: string;
   fontSize: number;
   fontFamily?: string;
+  rotation?: number;
   paint: Paint;
 };
 /** Pure geometry settings for recognising and axis-snapping a freehand stroke. */
@@ -1220,6 +1356,70 @@ declare function hitTest(m: Model, pon: number, p: Vec, geom: ChromeGeom, stroke
 /** The cursor to show on hover: a resize cursor over a handle, move/pointer over a body. */
 declare function cursorAt(m: Model, pon: number, p: Vec, geom: ChromeGeom, strokeMargin: number, pageBox?: Rect, inert?: ReadonlySet<Id>, view?: ViewEnv): Cursor | null;
 //#endregion
+//#region src/richtext.d.ts
+type RichTextStyleDelta = Partial<RichTextRunStyle>;
+/** A range of the plain projection, `start <= end`, end exclusive. */
+interface RichTextRange {
+  start: number;
+  end: number;
+}
+/** Length of the plain projection. */
+declare function richTextLength(doc: {
+  paragraphs: readonly RichTextParagraph[];
+}): number;
+/** Two deltas override the same properties with the same values. */
+declare function sameStyleDelta(a: RichTextStyleDelta | undefined, b: RichTextStyleDelta | undefined): boolean;
+/**
+ * Merge adjacent runs whose deltas agree, drop empty runs, strip empty
+ * deltas. A paragraph with no text keeps a single empty run so the editor
+ * has somewhere to put the caret.
+ */
+declare function normalizeRuns<T extends {
+  paragraphs: RichTextParagraph[];
+}>(doc: T): T;
+/** Where a flat offset falls: paragraph index and offset within it (the
+ *  separator between paragraphs belongs to the end of the earlier one). */
+declare function locateOffset(doc: {
+  paragraphs: readonly RichTextParagraph[];
+}, offset: number): {
+  paragraph: number;
+  offset: number;
+};
+/** The paragraph with a run boundary guaranteed at a local offset. */
+declare function splitRunsAt(paragraph: RichTextParagraph, offset: number): RichTextParagraph;
+/**
+ * Apply a style delta to every character of a range: the runs it touches are
+ * split at its boundaries, the covered pieces take the delta on top of what
+ * they already override (`clear` names properties to stop overriding, so
+ * they follow the body again), and the result is normalised. An empty range
+ * is a no-op.
+ */
+declare function applyStyleToRange<T extends {
+  paragraphs: RichTextParagraph[];
+}>(doc: T, range: RichTextRange, delta: RichTextStyleDelta, clear?: readonly (keyof RichTextRunStyle)[]): T;
+/**
+ * The delta in force at a caret: the run the offset falls in, or, at a run
+ * boundary, the run before it (what typing there would inherit). Undefined
+ * for an empty document.
+ */
+declare function styleAt(doc: {
+  paragraphs: readonly RichTextParagraph[];
+}, offset: number): RichTextStyleDelta | undefined;
+/** Every run overlapping the range satisfies `predicate` (an empty range
+ *  tests the caret's style). */
+declare function rangeHasStyle(doc: {
+  paragraphs: readonly RichTextParagraph[];
+}, range: RichTextRange, predicate: (delta: RichTextStyleDelta) => boolean): boolean;
+/** Plain paragraphs from text: one per line break, one unstyled run each. */
+declare function paragraphsFromPlainText(text: string): RichTextParagraph[];
+/** The plain projection: paragraphs joined by `\r`, runs concatenated. */
+declare function plainTextOf(doc: {
+  paragraphs: readonly RichTextParagraph[];
+}): string;
+/** True when nothing in the document overrides the body: no run delta, no
+ *  paragraph property. Such a document commits as plain `contents`. */
+declare function isPlainRichText(doc: RichTextDocumentInput): boolean;
+//#endregion
 //#region src/group.d.ts
 /**
  * The transform capabilities of a multi-target (group) selection: a group can
@@ -1334,6 +1534,18 @@ type PropSpec = {
 } | {
   key: 'textAlign';
   label: string;
+} |
+/** Rich-text formatting toggles (free text): the body's formatting, or —
+ *  while the text editor has a range — that range's runs. */
+{
+  key: 'bold';
+  label: string;
+} | {
+  key: 'italic';
+  label: string;
+} | {
+  key: 'underline';
+  label: string;
 } | {
   key: 'blendMode';
   label: string;
@@ -1534,9 +1746,9 @@ declare function uprightAnchoredRect(anchor: Vec, width: number, height: number,
  */
 declare function fitStampBox(center: Vec, desired: Size, page: Size, rotCW: number): Rect;
 /** Reset a geom to its as-authored orientation (`rot → 0`). Box: drop `rot`.
- *  Vertex: spin the points by `-rot` about their centroid so they return to the
- *  orientation they were drawn at, in place. */
-declare function geomResetRotation(g: Geom): Geom;
+ *  Vertex: spin the points by `-rot` about the supplied selection center.
+ *  Geometry-only callers retain the centroid default. */
+declare function geomResetRotation(g: Geom, pivot?: Vec): Geom;
 /**
  * The oriented selection box (OBB) of a rotatable geom: four corners (in order
  * nw, ne, se, sw of the LOCAL box, transformed) + the angle. For a box this is
@@ -1708,6 +1920,17 @@ declare function geomHit(g: Geom, p: Vec, margin: number, filled: boolean, strok
 declare function geomHandles(g: Geom): Handle[];
 declare function geomTranslate(g: Geom, d: Vec): Geom;
 declare function geomDragHandle(g: Geom, handle: string, to: Vec): Geom;
+/**
+ * The text PLATE inset of a free-text box: twice the border width. The plate
+ * — where text lays out, clips and scrolls — is the box deflated by this on
+ * every side: the ink band and an equal breathing band, so the text never
+ * touches the stroke. Acrobat's rule, measured 1–12 pt on plain boxes and
+ * 1–7 pt on callouts (plan `2026-09-15-free-text-plate-inset.md`); the
+ * engine's `FreeTextPlate` is the same formula, so the live editor sits
+ * exactly where the baked text lands. Acrobat's thinnest border is 1 pt; a
+ * width of 0 is ours alone and gives no inset (the plate is the box).
+ */
+declare function textPlateInset(strokeWidth: number): number;
 declare function geomScene(g: Geom, strokeWidth?: number, border?: Border): RenderNode[];
 declare const pdfToContentPoint: (p: PdfPoint, crop: PdfRect) => Vec;
 declare const contentToPdfPoint: (p: Vec, crop: PdfRect) => PdfPoint;
@@ -1732,6 +1955,14 @@ declare function cloudyBorderExtent(intensity: number, strokeWidth: number, elli
  */
 declare function cloudyPath(box: Rect, ellipse: boolean, intensity: number, strokeWidth: number): string;
 //#endregion
+//#region src/selection.d.ts
+interface SelectionFrame {
+  corners: Quad;
+  center: Vec;
+  angle: number;
+}
+declare function annotationSelectionFrame(annotation: Annot, view?: ViewEnv): SelectionFrame;
+//#endregion
 //#region src/scene.d.ts
 /** The full painted scene for one annotation. */
 declare function scene(item: RenderItem): SceneNode[];
@@ -1744,5 +1975,5 @@ declare function scene(item: RenderItem): SceneNode[];
  */
 declare function straightenInkStroke(points: readonly Vec[], options: InkStraightenOptions): Vec[];
 //#endregion
-export { type AnchorMode, type Annot, type AnnotationFlags, type AnnotationKind, type AnnotationProps, type AnnotationPropsPatch, type BlendMode, type Border, type Callout, type ChromeGeom, type ChromeNode, type ClickCreate, type ClickPlacement, type CreationDraftAnchor, type Cursor, DEFAULT_CHROME_GEOM, DRAWN_FLAGS, type Draft, type Effect, FLAG_KEYS, type FlagBearer, type Geom, type GroupCaps, type Guide, type Handle, type Id, type InkStraightenOptions, KINDS, type KindCaps, type LineEnding, type LineEndings, MIN_DRAG, MITER_LIMIT, type Model, type Msg, NO_ANNOTATION_FLAGS, type Paint, type PatchScope, type PointerInput, type PropKey, type PropSpec, type Quad, RECT_HANDLES, ROTATE_KNOB_OFFSET, type Rect, type RectHandle, type RenderItem, type RenderNode, type SceneNode, type SnapResult, type SnapSettings, type Style, type Subtype, type Target, type TextAlign, type TextBox, type TextEndAnchor, type TextQuad, type TextStyle, type Vec, type ViewEnv, anchorModeOf, anchorOf, anchoredBox, anchoredGeom, anchoredStrokeWidth, annotContentsEditable, annotDeletable, annotInteractive, annotTransformable, applyProps, calloutConnection, calloutLinePoints, canMove, capsFor, caretGeomFromAnchor, caretRectFromAnchor, caretRectFromTextEnd, centroidOf, chrome, clampRectToBox, clickCreateGeom, cloudyBorderExtent, cloudyPath, computeMoveSnap, contentToPdfPoint, contentToPdfRect, creationDraftAnchor, cursorAt, defaultsFor, expandGroups, fitStampBox, flagsEqual, geomBounds, geomDragHandle, geomHandles, geomHit, geomPdfBounds, geomResetRotation, geomRotateAbout, geomRotation, geomScaleAbout, geomScene, geomTranslate, geomVisualBounds, groupCaps, groupKeyOf, groupMembers, groupResizeAnchor, groupResizeBox, groupResizeFactors, hitTest, initialModel, initialStyle, initialTextStyle, interactive, isAttachedLink, isConversationOnly, isRotatableGeom, isSelectable, isSubstrateOnly, linkChildrenOf, linkOf, mergeFlags, normalizeDeg, obbFromGeom, pageItems, pdfToContentPoint, pdfToContentRect, placeRotateKnob, pointInQuad, propsFor, quadIntersectsRect, readProp, rectFromPoints, resolveClickPlacement, rotateDraftDelta, rotateKnob, rotatedAabb, rotatedHandleCursor, scene, selectedItems, selectionAnchor, selectionBounds, selectionBoundsOnPage, selectionCenter, selectionKnob, selectionQuad, shapeRectFor, sharedProps, straightenInkStroke, styleFromProps, textBoxes, textStyleFromProps, transposedAboutCenter, unanchoredGeom, unionRect, update, uprightAnchoredRect, uprightRotation, viewable };
+export { type AnchorMode, type Annot, type AnnotationFlags, type AnnotationKind, type AnnotationProps, type AnnotationPropsPatch, type BlendMode, type Border, type Callout, type ChromeGeom, type ChromeNode, type ClickCreate, type ClickPlacement, type CreationDraftAnchor, type Cursor, DEFAULT_CHROME_GEOM, DRAWN_FLAGS, DistanceAppearance, DistanceCaptionLayout, DistanceLayout, DistanceSegment, type Draft, type Effect, FLAG_KEYS, type FlagBearer, type Geom, type GroupCaps, type Guide, type Handle, type Id, type InkStraightenOptions, KINDS, type KindCaps, type LineEnding, type LineEndings, MIN_DRAG, MITER_LIMIT, MeasurementAppearance, type Model, type Msg, NO_ANNOTATION_FLAGS, type Paint, type PatchScope, type PointerInput, type PropKey, type PropSpec, type Quad, RECT_HANDLES, ROTATE_KNOB_OFFSET, type Rect, type RectHandle, type RenderItem, type RenderNode, type RichTextRange, type RichTextStyleDelta, type SceneNode, type SelectionFrame, ShapeMeasurementAppearance, ShapeMeasurementLayout, type SnapResult, type SnapSettings, type Style, type Subtype, type Target, type TextAlign, type TextBox, type TextEndAnchor, type TextQuad, type TextStyle, type Vec, type ViewEnv, anchorModeOf, anchorOf, anchoredBox, anchoredGeom, anchoredStrokeWidth, annotContentsEditable, annotDeletable, annotInteractive, annotTransformable, annotationSelectionFrame, applyProps, applyStyleToRange, automaticShapeCaptionCenter, calloutConnection, calloutLinePoints, canMove, capsFor, caretGeomFromAnchor, caretRectFromAnchor, caretRectFromTextEnd, centroidOf, chrome, clampRectToBox, clickCreateGeom, cloudyBorderExtent, cloudyPath, computeMoveSnap, contentToPdfPoint, contentToPdfRect, creationDraftAnchor, cursorAt, defaultsFor, distanceCaptionAt, distanceCaptionHit, distanceHandles, distanceHit, distanceLabel, distanceLayout, distanceLeaderLength, distanceScene, distanceSelectionQuad, expandDistanceBounds, expandGroups, fitStampBox, flagsEqual, geomBounds, geomDragHandle, geomHandles, geomHit, geomPdfBounds, geomResetRotation, geomRotateAbout, geomRotation, geomScaleAbout, geomScene, geomTranslate, geomVisualBounds, groupCaps, groupKeyOf, groupMembers, groupResizeAnchor, groupResizeBox, groupResizeFactors, hitTest, initialModel, initialStyle, initialTextStyle, interactive, isAttachedLink, isConversationOnly, isPlainRichText, isRotatableGeom, isSelectable, isSubstrateOnly, linkChildrenOf, linkOf, locateOffset, measurementCaptionScene, measurementLayout, measurementSelectionQuad, mergeFlags, moveDistanceCaption, moveMeasurementCaption, normalizeDeg, normalizeRuns, obbFromGeom, pageItems, paragraphsFromPlainText, pdfToContentPoint, pdfToContentRect, placeRotateKnob, plainTextOf, pointInQuad, propsFor, quadIntersectsRect, rangeHasStyle, readProp, rectFromPoints, resolveClickPlacement, richTextLength, rotateDraftDelta, rotateKnob, rotatedAabb, rotatedHandleCursor, sameStyleDelta, scene, selectedItems, selectionAnchor, selectionBounds, selectionBoundsOnPage, selectionCenter, selectionKnob, selectionQuad, shapeCaptionPoint, shapeMeasurementLabel, shapeMeasurementLayout, shapeMeasurementReadout, shapeRectFor, sharedProps, splitRunsAt, straightenInkStroke, styleAt, styleFromProps, textBoxes, textPlateInset, textStyleFromProps, transformMeasurementCaption, transposedAboutCenter, unanchoredGeom, unionRect, update, uprightAnchoredRect, uprightRotation, viewable, withShapeCaptionPoint };
 //# sourceMappingURL=index.d.ts.map