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

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 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 { PageObjectNumber } from "@embedpdf/core";
-import { PageRotation, Point, Rect as Rect$1, Size } from "@embedpdf/core-geometry";
+import { PageRotation, Point, Rect as Rect$1, Size, TextQuad, TextQuad as TextQuad$1 } from "@embedpdf/core-geometry";
 //#region src/flags.d.ts
 /** The `/F` every freshly DRAWN annotation starts with: `print` set (Acrobat
  *  parity — without it the annotation silently disappears when printed). */
@@ -22,14 +22,27 @@ declare const interactive: (f: AnnotationFlags) => boolean;
 interface FlagBearer {
   subtype: string;
   flags: AnnotationFlags;
+  /** Session authority projected at ingest (permissions.md). Absent =
+   *  unstamped (drafts, wildcard local engines, tests) = allowed. */
+  authority?: {
+    update: boolean;
+    delete: boolean;
+  };
 }
 /** Interaction gate for a concrete annotation: widget kinds ignore `readOnly`
  *  (ISO 32000 — a ReadOnly form field must still be movable by a form designer;
  *  the form-filling layer enforces field ReadOnly itself). */
 declare const annotInteractive: (a: FlagBearer) => boolean;
-/** Geometry/style/delete mutations — `locked` freezes the OBJECT, not its
- *  contents (that's `lockedContents`). */
+/**
+ * Geometry/style mutations — `locked` freezes the OBJECT, not its contents
+ * (that's `lockedContents`), AND the session must hold update authority over
+ * the record. One predicate for hit-test, chrome, and props alike, so a
+ * record you may not edit renders and behaves exactly like a locked one.
+ */
 declare const annotTransformable: (a: FlagBearer) => boolean;
+/** Deletion — the delete half of the authority split (a narrowed grant can
+ *  allow update but not delete, or vice versa). Flags gate like transforms. */
+declare const annotDeletable: (a: FlagBearer) => boolean;
 /** `/Contents` text edits — the contents counterpart of `locked`. */
 declare const annotContentsEditable: (a: FlagBearer) => boolean;
 //#endregion
@@ -42,8 +55,19 @@ declare const annotContentsEditable: (a: FlagBearer) => boolean;
  */
 type Vec = Point;
 type Rect = Rect$1;
-/** Four content-space points (a /QuadPoints quad). */
+/** Four POSITIONAL content-space points — selection chrome / OBB corners.
+ *  Text-markup geometry uses the corner-NAMED {@link TextQuad} instead. */
 type Quad = [Vec, Vec, Vec, Vec];
+/**
+ * Where a text-edit annotation (caret / replace-text) anchors: the boundary
+ * glyph's oriented cell plus the READING direction along its baseline
+ * (+1 = toward `end`, −1 = toward `start` — sequence-derived, never inferred
+ * from geometry).
+ */
+interface TextEndAnchor {
+  glyphQuad: TextQuad$1;
+  advance: 1 | -1;
+}
 type Id = string;
 type Cursor = string;
 type PolySubtype = 'polygon' | 'polyline';
@@ -115,10 +139,11 @@ type Geom = {
   rot?: number;
 } | {
   t: 'quads';
-  quads: Quad[];
+  quads: TextQuad$1[];
 } | {
   t: 'caret';
   rect: Rect;
+  rot?: number;
 } | {
   t: 'ink';
   strokes: Vec[][];
@@ -274,6 +299,20 @@ interface Annot {
    * is still pixel-exact, so those cost zero re-renders.
    */
   apVersion?: number;
+  /**
+   * This SESSION's authority over this record, projected from the security
+   * service's collab mirrors at ingest (see permissions.md) — model-owned
+   * derived state like `apVersion`, never DTO-derived. Fused into
+   * `annotTransformable`/`annotDeletable`, so a record the session may not
+   * edit renders and behaves exactly like a `locked` one (bare outline, no
+   * handles, no drag). Absent = unstamped (a local draft, a wildcard local
+   * engine, tests) and treated as allowed — the client gate is a COURTESY
+   * that keeps the UI truthful; the engine independently enforces.
+   */
+  authority?: {
+    update: boolean;
+    delete: boolean;
+  };
   /**
    * The canonical engine DTO this annotation was derived from (PDF-space, sRGB)
    * — the single source of truth for its data. `geom` and `style` are
@@ -285,20 +324,13 @@ interface Annot {
   /** Normalized PDF `/IT` for intent-bearing annotations authored before a DTO exists. */
   intent?: CaretIntent | StrikeoutIntent | InkIntent;
   /**
-   * The `link` prop's value (see {@link AnnotationProps.link}): the link
-   * kind's own target, or — on other linkable kinds — the folded attached
-   * link's target. Editable via `setProps`.
+   * The link KIND's own `/A` target (see {@link AnnotationProps.link}) —
+   * present only on `subtype: 'link'`. Every OTHER kind's link is an
+   * attached child annotation in the substrate, read through the `linkOf`
+   * lens and materialized by the shell's `syncLink` reconciler; parents
+   * store nothing.
    */
   link?: PdfLinkTarget | null;
-  /**
-   * INTERNAL join keys, never a prop: the engine refs of the attached link
-   * child annotation(s) this parent's `link` value is materialized as (one
-   * per visual segment for markup). Maintained by the repository fold and
-   * consumed by the shell's `syncLink` reconciler + delete expansion — the
-   * ONLY code allowed to touch those children. Absent on the link kind
-   * itself and on anything without an attached link.
-   */
-  linkRefs?: AnnotationRef[];
   /**
    * Relationship to another annotation. `irt` ("in reply to") links a child to a
    * parent — a reply in a comment thread, or a caret bound to its strikeout in a
@@ -454,7 +486,7 @@ interface MarkupPreview {
   subtype: Subtype;
   /** Defaults key, distinct from subtype for presets such as replace-text. */
   preset: string;
-  byPage: Record<number, Quad[]>;
+  byPage: Record<number, TextQuad$1[]>;
 }
 /** Anchor + affordance state for UI that controls an in-progress creation draft. */
 interface CreationDraftAnchor {
@@ -613,26 +645,26 @@ type Msg = {
 } | {
   t: 'createCaret';
   pon: PageObjectNumber;
-  rect: Rect;
+  anchor: TextEndAnchor;
   flags?: Partial<AnnotationFlags$1>;
 } | {
   t: 'createReplaceText';
   pon: PageObjectNumber;
-  rects: Rect[];
-  endRect: Rect;
+  quads: TextQuad$1[];
+  anchor: TextEndAnchor;
   preset?: string;
 } | {
   t: 'createMarkup';
   subtype: Subtype;
   pon: PageObjectNumber;
-  rects: Rect[];
+  quads: TextQuad$1[];
   preset?: string;
   /** The tool's `/F` seed — merged over {@link DRAWN_FLAGS} at commit. */
   flags?: Partial<AnnotationFlags$1>;
 } | {
   t: 'setMarkupPreview';
   subtype: Subtype;
-  rectsByPage: Record<number, Rect[]>;
+  quadsByPage: Record<number, TextQuad$1[]>;
   preset?: string;
 } | {
   t: 'clearMarkupPreview';
@@ -644,7 +676,12 @@ type Msg = {
 {
   t: 'hover';
   id: Id | null;
-} | {
+} |
+/** Force/clear session visibility for specific annotations (the actions
+ *  plane's Hide sink). Hiding also clears transient engagement (selection,
+ *  editing, hover) for the hidden ids. Unknown ids no-op. Zero effects. */
+/** Drop overrides for truly DELETED annotations (never for reloads). */
+{
   t: 'select';
   ids: Id[];
   add?: boolean;
@@ -673,6 +710,21 @@ type Msg = {
 } | {
   t: 'loaded';
   annots: Annot[];
+} |
+/**
+ * Whole-document hydration ingest (and desync re-ingest): the snapshot is
+ * the committed TRUTH. Incoming annots overwrite by id (gesture-locked ids
+ * excepted, as in `upsert`); committed model entries ABSENT from the
+ * snapshot are reaped — they were deleted while we could not watch.
+ * Uncommitted `tmp:` drafts and gesture-locked ids are never reaped, and
+ * an in-progress draft survives (unlike `remove`). `bumpAp` marks a
+ * desync re-ingest: rasters may have changed invisibly during the gap,
+ * so every replaced annotation re-fetches once.
+ */
+{
+  t: 'hydrated';
+  annots: Annot[];
+  bumpAp?: boolean;
 } | {
   t: 'created';
   tempId: Id;
@@ -739,6 +791,7 @@ type Effect = {
 {
   fx: 'syncLink';
   id: Id;
+  target: PdfLinkTarget | null;
 } | {
   fx: 'delete';
   ref: AnnotationRef;
@@ -1198,6 +1251,36 @@ declare function groupMembers(m: Model, id: Id): Id[];
 /** Union of every id's full group — the selection seen as whole groups. */
 declare function expandGroups(m: Model, ids: Id[]): Id[];
 //#endregion
+//#region src/plane.d.ts
+/** True when this annotation belongs to the conversation plane only —
+ *  never painted, hit, marquee-selected, or counted into a page's
+ *  appearance epoch. */
+declare function isConversationOnly(a: Pick<Annot, 'irt' | 'group' | 'subtype' | 'data'>): boolean;
+/**
+ * A link CHILD attached to another annotation — a `/Link` grouped
+ * (`/IRT` + `/RT /Group`) under a non-link parent. Pure substrate: it is
+ * the parent's `link` PROPERTY while authoring (derived via `linkOf`) and
+ * the navigation plane's anchor while reading — never painted, never hit
+ * as itself. Its rect is RECONCILED from the parent's geometry, so direct
+ * manipulation would be overwritten anyway.
+ */
+declare function isAttachedLink(a: Pick<Annot, 'subtype' | 'group'>): boolean;
+/**
+ * The ONE page-surface cull: everything that lives in the substrate but is
+ * not a page visual of its own — conversation members (replies, review
+ * states) and attached link children. Paint order, hit-testing, marquee
+ * and the appearance epoch all filter through THIS, never the parts.
+ */
+declare function isSubstrateOnly(a: Pick<Annot, 'irt' | 'group' | 'subtype' | 'data'>): boolean;
+//#endregion
+//#region src/links.d.ts
+/** Every attached link child of `parentId`, in z-order (multi-segment
+ *  markup parents carry several children with one shared target). */
+declare function linkChildrenOf(m: Model, parentId: Id): Annot[];
+/** The parent's link target, derived from its first attached child — the
+ *  read side of the `syncLink` reconciler. Null when no child exists. */
+declare function linkOf(m: Model, parentId: Id): PdfLinkTarget | null;
+//#endregion
 //#region src/kinds.d.ts
 /**
  * One editable property of a kind, as a UI contract: which {@link AnnotationProps}
@@ -1386,7 +1469,10 @@ declare const DEFAULT_CHROME_GEOM: {
 };
 /** Normalize degrees into `[0, 360)`. */
 declare const normalizeDeg: (d: number) => number;
-/** A geom's applied rotation (deg), or 0 for the non-rotatable kinds. */
+/** A geom's applied rotation (deg), or 0 for the non-rotatable kinds. A
+ *  caret's `rot` is AUTHORING metadata (its text's baseline tilt): reported
+ *  here so the renderer and selection chrome follow it, while the caret's
+ *  caps (not movable/resizable) keep every rotate gesture away from it. */
 declare function geomRotation(g: Geom): number;
 /**
  * The rotation PIVOT for a single shape: a box turns about its own `rect`
@@ -1395,7 +1481,10 @@ declare function geomRotation(g: Geom): number;
  * stays cleanly additive across gestures and reset is exact.
  */
 declare function centroidOf(g: Geom): Vec;
-/** Is this kind rotatable (the geometry carries a meaningful `rot`)? */
+/** Does the geometry carry a meaningful `rot` (an oriented local box exists)?
+ *  ORIENTATION is a geometry fact; whether the USER may rotate is the separate
+ *  `caps.rotatable` gate — a caret is oriented (it rides its text's tilt) yet
+ *  offers no rotate gesture. */
 declare function isRotatableGeom(g: Geom): boolean;
 /**
  * Rotate a geom by `deltaDeg` (clockwise) about `pivot`.
@@ -1404,7 +1493,10 @@ declare function isRotatableGeom(g: Geom): boolean;
  *    pivot IS the box centre this is a pure `rot += delta`.
  *  - VERTEX (`line`/`poly`/`ink`): map every point through the rotation AND bump
  *    the advisory `rot` (the points stay the authoritative visual).
- * Non-rotatable kinds (caret/quads, callouts) are returned unchanged.
+ * Kinds without a rotate VERB are returned unchanged: quads and callouts, and
+ * also the caret — oriented (`isRotatableGeom`) but text-anchored, so its tilt
+ * is authoring metadata that no gesture edits (`geomResetRotation` still
+ * clears it).
  */
 declare function geomRotateAbout(g: Geom, pivot: Vec, deltaDeg: number): Geom;
 /** The AABB of `rect` rotated `deg` about its own centre. */
@@ -1520,6 +1612,26 @@ declare function calloutLinePoints(g: Extract<Geom, {
  */
 declare function shapeRectFor(dragged: Rect, ellipse: boolean, style: Style): Rect;
 declare function caretRectFromTextEnd(lineRect: Rect): Rect;
+/**
+ * Caret box for a text-edit anchor: half the glyph's ink height, centered on
+ * the TRAILING baseline corner in READING direction (`advance` decides which
+ * end — RTL carets land on the visual left), sitting on the baseline. The box
+ * stays axis-aligned; use {@link caretGeomFromAnchor} for the tilt-carrying
+ * geometry.
+ */
+declare function caretRectFromAnchor(anchor: TextEndAnchor): Rect;
+/**
+ * Caret GEOMETRY for a text-edit anchor: the box-family pair — an UNROTATED
+ * box whose centre sits half a caret-size ascent-ward of the trailing
+ * baseline corner, plus `rot` = the text's baseline tilt (deg, CW in y-down
+ * content space). Rotating the box about its centre by `rot` lands it
+ * hugging the rotated baseline, symbol pointing at its text. For upright
+ * anchors this degenerates EXACTLY to {@link caretRectFromAnchor} with no
+ * `rot` key — the dominant case is byte-identical.
+ */
+declare function caretGeomFromAnchor(anchor: TextEndAnchor): Extract<Geom, {
+  t: 'caret';
+}>;
 /** Miter limit shared by the bounds math AND the SVG renderer (`stroke-miterlimit`),
  *  so the computed box and the drawn stroke always agree on where a sharp join
  *  bevels instead of spiking. 10 = the PDF default (also what the baked /AP uses). */
@@ -1632,5 +1744,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 TextStyle, type Vec, type ViewEnv, anchorModeOf, anchorOf, anchoredBox, anchoredGeom, anchoredStrokeWidth, annotContentsEditable, annotInteractive, annotTransformable, applyProps, calloutConnection, calloutLinePoints, canMove, capsFor, 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, isRotatableGeom, isSelectable, 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, 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 };
 //# sourceMappingURL=index.d.cts.map

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 } from "@embedpdf/core-geometry";
+import { PageRotation, Point, Rect as Rect$1, Size, TextQuad, TextQuad as TextQuad$1 } from "@embedpdf/core-geometry";
 import { PageObjectNumber } from "@embedpdf/core";
 //#region src/flags.d.ts
 /** The `/F` every freshly DRAWN annotation starts with: `print` set (Acrobat
@@ -22,14 +22,27 @@ declare const interactive: (f: AnnotationFlags) => boolean;
 interface FlagBearer {
   subtype: string;
   flags: AnnotationFlags;
+  /** Session authority projected at ingest (permissions.md). Absent =
+   *  unstamped (drafts, wildcard local engines, tests) = allowed. */
+  authority?: {
+    update: boolean;
+    delete: boolean;
+  };
 }
 /** Interaction gate for a concrete annotation: widget kinds ignore `readOnly`
  *  (ISO 32000 — a ReadOnly form field must still be movable by a form designer;
  *  the form-filling layer enforces field ReadOnly itself). */
 declare const annotInteractive: (a: FlagBearer) => boolean;
-/** Geometry/style/delete mutations — `locked` freezes the OBJECT, not its
- *  contents (that's `lockedContents`). */
+/**
+ * Geometry/style mutations — `locked` freezes the OBJECT, not its contents
+ * (that's `lockedContents`), AND the session must hold update authority over
+ * the record. One predicate for hit-test, chrome, and props alike, so a
+ * record you may not edit renders and behaves exactly like a locked one.
+ */
 declare const annotTransformable: (a: FlagBearer) => boolean;
+/** Deletion — the delete half of the authority split (a narrowed grant can
+ *  allow update but not delete, or vice versa). Flags gate like transforms. */
+declare const annotDeletable: (a: FlagBearer) => boolean;
 /** `/Contents` text edits — the contents counterpart of `locked`. */
 declare const annotContentsEditable: (a: FlagBearer) => boolean;
 //#endregion
@@ -42,8 +55,19 @@ declare const annotContentsEditable: (a: FlagBearer) => boolean;
  */
 type Vec = Point;
 type Rect = Rect$1;
-/** Four content-space points (a /QuadPoints quad). */
+/** Four POSITIONAL content-space points — selection chrome / OBB corners.
+ *  Text-markup geometry uses the corner-NAMED {@link TextQuad} instead. */
 type Quad = [Vec, Vec, Vec, Vec];
+/**
+ * Where a text-edit annotation (caret / replace-text) anchors: the boundary
+ * glyph's oriented cell plus the READING direction along its baseline
+ * (+1 = toward `end`, −1 = toward `start` — sequence-derived, never inferred
+ * from geometry).
+ */
+interface TextEndAnchor {
+  glyphQuad: TextQuad$1;
+  advance: 1 | -1;
+}
 type Id = string;
 type Cursor = string;
 type PolySubtype = 'polygon' | 'polyline';
@@ -115,10 +139,11 @@ type Geom = {
   rot?: number;
 } | {
   t: 'quads';
-  quads: Quad[];
+  quads: TextQuad$1[];
 } | {
   t: 'caret';
   rect: Rect;
+  rot?: number;
 } | {
   t: 'ink';
   strokes: Vec[][];
@@ -274,6 +299,20 @@ interface Annot {
    * is still pixel-exact, so those cost zero re-renders.
    */
   apVersion?: number;
+  /**
+   * This SESSION's authority over this record, projected from the security
+   * service's collab mirrors at ingest (see permissions.md) — model-owned
+   * derived state like `apVersion`, never DTO-derived. Fused into
+   * `annotTransformable`/`annotDeletable`, so a record the session may not
+   * edit renders and behaves exactly like a `locked` one (bare outline, no
+   * handles, no drag). Absent = unstamped (a local draft, a wildcard local
+   * engine, tests) and treated as allowed — the client gate is a COURTESY
+   * that keeps the UI truthful; the engine independently enforces.
+   */
+  authority?: {
+    update: boolean;
+    delete: boolean;
+  };
   /**
    * The canonical engine DTO this annotation was derived from (PDF-space, sRGB)
    * — the single source of truth for its data. `geom` and `style` are
@@ -285,20 +324,13 @@ interface Annot {
   /** Normalized PDF `/IT` for intent-bearing annotations authored before a DTO exists. */
   intent?: CaretIntent | StrikeoutIntent | InkIntent;
   /**
-   * The `link` prop's value (see {@link AnnotationProps.link}): the link
-   * kind's own target, or — on other linkable kinds — the folded attached
-   * link's target. Editable via `setProps`.
+   * The link KIND's own `/A` target (see {@link AnnotationProps.link}) —
+   * present only on `subtype: 'link'`. Every OTHER kind's link is an
+   * attached child annotation in the substrate, read through the `linkOf`
+   * lens and materialized by the shell's `syncLink` reconciler; parents
+   * store nothing.
    */
   link?: PdfLinkTarget | null;
-  /**
-   * INTERNAL join keys, never a prop: the engine refs of the attached link
-   * child annotation(s) this parent's `link` value is materialized as (one
-   * per visual segment for markup). Maintained by the repository fold and
-   * consumed by the shell's `syncLink` reconciler + delete expansion — the
-   * ONLY code allowed to touch those children. Absent on the link kind
-   * itself and on anything without an attached link.
-   */
-  linkRefs?: AnnotationRef[];
   /**
    * Relationship to another annotation. `irt` ("in reply to") links a child to a
    * parent — a reply in a comment thread, or a caret bound to its strikeout in a
@@ -454,7 +486,7 @@ interface MarkupPreview {
   subtype: Subtype;
   /** Defaults key, distinct from subtype for presets such as replace-text. */
   preset: string;
-  byPage: Record<number, Quad[]>;
+  byPage: Record<number, TextQuad$1[]>;
 }
 /** Anchor + affordance state for UI that controls an in-progress creation draft. */
 interface CreationDraftAnchor {
@@ -613,26 +645,26 @@ type Msg = {
 } | {
   t: 'createCaret';
   pon: PageObjectNumber;
-  rect: Rect;
+  anchor: TextEndAnchor;
   flags?: Partial<AnnotationFlags$1>;
 } | {
   t: 'createReplaceText';
   pon: PageObjectNumber;
-  rects: Rect[];
-  endRect: Rect;
+  quads: TextQuad$1[];
+  anchor: TextEndAnchor;
   preset?: string;
 } | {
   t: 'createMarkup';
   subtype: Subtype;
   pon: PageObjectNumber;
-  rects: Rect[];
+  quads: TextQuad$1[];
   preset?: string;
   /** The tool's `/F` seed — merged over {@link DRAWN_FLAGS} at commit. */
   flags?: Partial<AnnotationFlags$1>;
 } | {
   t: 'setMarkupPreview';
   subtype: Subtype;
-  rectsByPage: Record<number, Rect[]>;
+  quadsByPage: Record<number, TextQuad$1[]>;
   preset?: string;
 } | {
   t: 'clearMarkupPreview';
@@ -644,7 +676,12 @@ type Msg = {
 {
   t: 'hover';
   id: Id | null;
-} | {
+} |
+/** Force/clear session visibility for specific annotations (the actions
+ *  plane's Hide sink). Hiding also clears transient engagement (selection,
+ *  editing, hover) for the hidden ids. Unknown ids no-op. Zero effects. */
+/** Drop overrides for truly DELETED annotations (never for reloads). */
+{
   t: 'select';
   ids: Id[];
   add?: boolean;
@@ -673,6 +710,21 @@ type Msg = {
 } | {
   t: 'loaded';
   annots: Annot[];
+} |
+/**
+ * Whole-document hydration ingest (and desync re-ingest): the snapshot is
+ * the committed TRUTH. Incoming annots overwrite by id (gesture-locked ids
+ * excepted, as in `upsert`); committed model entries ABSENT from the
+ * snapshot are reaped — they were deleted while we could not watch.
+ * Uncommitted `tmp:` drafts and gesture-locked ids are never reaped, and
+ * an in-progress draft survives (unlike `remove`). `bumpAp` marks a
+ * desync re-ingest: rasters may have changed invisibly during the gap,
+ * so every replaced annotation re-fetches once.
+ */
+{
+  t: 'hydrated';
+  annots: Annot[];
+  bumpAp?: boolean;
 } | {
   t: 'created';
   tempId: Id;
@@ -739,6 +791,7 @@ type Effect = {
 {
   fx: 'syncLink';
   id: Id;
+  target: PdfLinkTarget | null;
 } | {
   fx: 'delete';
   ref: AnnotationRef;
@@ -1198,6 +1251,36 @@ declare function groupMembers(m: Model, id: Id): Id[];
 /** Union of every id's full group — the selection seen as whole groups. */
 declare function expandGroups(m: Model, ids: Id[]): Id[];
 //#endregion
+//#region src/plane.d.ts
+/** True when this annotation belongs to the conversation plane only —
+ *  never painted, hit, marquee-selected, or counted into a page's
+ *  appearance epoch. */
+declare function isConversationOnly(a: Pick<Annot, 'irt' | 'group' | 'subtype' | 'data'>): boolean;
+/**
+ * A link CHILD attached to another annotation — a `/Link` grouped
+ * (`/IRT` + `/RT /Group`) under a non-link parent. Pure substrate: it is
+ * the parent's `link` PROPERTY while authoring (derived via `linkOf`) and
+ * the navigation plane's anchor while reading — never painted, never hit
+ * as itself. Its rect is RECONCILED from the parent's geometry, so direct
+ * manipulation would be overwritten anyway.
+ */
+declare function isAttachedLink(a: Pick<Annot, 'subtype' | 'group'>): boolean;
+/**
+ * The ONE page-surface cull: everything that lives in the substrate but is
+ * not a page visual of its own — conversation members (replies, review
+ * states) and attached link children. Paint order, hit-testing, marquee
+ * and the appearance epoch all filter through THIS, never the parts.
+ */
+declare function isSubstrateOnly(a: Pick<Annot, 'irt' | 'group' | 'subtype' | 'data'>): boolean;
+//#endregion
+//#region src/links.d.ts
+/** Every attached link child of `parentId`, in z-order (multi-segment
+ *  markup parents carry several children with one shared target). */
+declare function linkChildrenOf(m: Model, parentId: Id): Annot[];
+/** The parent's link target, derived from its first attached child — the
+ *  read side of the `syncLink` reconciler. Null when no child exists. */
+declare function linkOf(m: Model, parentId: Id): PdfLinkTarget | null;
+//#endregion
 //#region src/kinds.d.ts
 /**
  * One editable property of a kind, as a UI contract: which {@link AnnotationProps}
@@ -1386,7 +1469,10 @@ declare const DEFAULT_CHROME_GEOM: {
 };
 /** Normalize degrees into `[0, 360)`. */
 declare const normalizeDeg: (d: number) => number;
-/** A geom's applied rotation (deg), or 0 for the non-rotatable kinds. */
+/** A geom's applied rotation (deg), or 0 for the non-rotatable kinds. A
+ *  caret's `rot` is AUTHORING metadata (its text's baseline tilt): reported
+ *  here so the renderer and selection chrome follow it, while the caret's
+ *  caps (not movable/resizable) keep every rotate gesture away from it. */
 declare function geomRotation(g: Geom): number;
 /**
  * The rotation PIVOT for a single shape: a box turns about its own `rect`
@@ -1395,7 +1481,10 @@ declare function geomRotation(g: Geom): number;
  * stays cleanly additive across gestures and reset is exact.
  */
 declare function centroidOf(g: Geom): Vec;
-/** Is this kind rotatable (the geometry carries a meaningful `rot`)? */
+/** Does the geometry carry a meaningful `rot` (an oriented local box exists)?
+ *  ORIENTATION is a geometry fact; whether the USER may rotate is the separate
+ *  `caps.rotatable` gate — a caret is oriented (it rides its text's tilt) yet
+ *  offers no rotate gesture. */
 declare function isRotatableGeom(g: Geom): boolean;
 /**
  * Rotate a geom by `deltaDeg` (clockwise) about `pivot`.
@@ -1404,7 +1493,10 @@ declare function isRotatableGeom(g: Geom): boolean;
  *    pivot IS the box centre this is a pure `rot += delta`.
  *  - VERTEX (`line`/`poly`/`ink`): map every point through the rotation AND bump
  *    the advisory `rot` (the points stay the authoritative visual).
- * Non-rotatable kinds (caret/quads, callouts) are returned unchanged.
+ * Kinds without a rotate VERB are returned unchanged: quads and callouts, and
+ * also the caret — oriented (`isRotatableGeom`) but text-anchored, so its tilt
+ * is authoring metadata that no gesture edits (`geomResetRotation` still
+ * clears it).
  */
 declare function geomRotateAbout(g: Geom, pivot: Vec, deltaDeg: number): Geom;
 /** The AABB of `rect` rotated `deg` about its own centre. */
@@ -1520,6 +1612,26 @@ declare function calloutLinePoints(g: Extract<Geom, {
  */
 declare function shapeRectFor(dragged: Rect, ellipse: boolean, style: Style): Rect;
 declare function caretRectFromTextEnd(lineRect: Rect): Rect;
+/**
+ * Caret box for a text-edit anchor: half the glyph's ink height, centered on
+ * the TRAILING baseline corner in READING direction (`advance` decides which
+ * end — RTL carets land on the visual left), sitting on the baseline. The box
+ * stays axis-aligned; use {@link caretGeomFromAnchor} for the tilt-carrying
+ * geometry.
+ */
+declare function caretRectFromAnchor(anchor: TextEndAnchor): Rect;
+/**
+ * Caret GEOMETRY for a text-edit anchor: the box-family pair — an UNROTATED
+ * box whose centre sits half a caret-size ascent-ward of the trailing
+ * baseline corner, plus `rot` = the text's baseline tilt (deg, CW in y-down
+ * content space). Rotating the box about its centre by `rot` lands it
+ * hugging the rotated baseline, symbol pointing at its text. For upright
+ * anchors this degenerates EXACTLY to {@link caretRectFromAnchor} with no
+ * `rot` key — the dominant case is byte-identical.
+ */
+declare function caretGeomFromAnchor(anchor: TextEndAnchor): Extract<Geom, {
+  t: 'caret';
+}>;
 /** Miter limit shared by the bounds math AND the SVG renderer (`stroke-miterlimit`),
  *  so the computed box and the drawn stroke always agree on where a sharp join
  *  bevels instead of spiking. 10 = the PDF default (also what the baked /AP uses). */
@@ -1632,5 +1744,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 TextStyle, type Vec, type ViewEnv, anchorModeOf, anchorOf, anchoredBox, anchoredGeom, anchoredStrokeWidth, annotContentsEditable, annotInteractive, annotTransformable, applyProps, calloutConnection, calloutLinePoints, canMove, capsFor, 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, isRotatableGeom, isSelectable, 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, 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 };
 //# sourceMappingURL=index.d.ts.map