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

package/dist/index.d.ts

@@ -1,71 +1,391 @@
-import { AnnotationDTO, AnnotationFlags, AnnotationFlags as AnnotationFlags$1, AnnotationRef, BlendMode, BlendMode as BlendMode$1, CaretIntent, InkIntent, LineEnding, LineEndings, NO_ANNOTATION_FLAGS, PdfLinkTarget, PdfPoint, PdfRect, RichTextDocumentInput, RichTextParagraph, RichTextRunStyle, StrikeoutIntent } from "@embedpdf/engine-core/runtime";
-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
- *  parity — without it the annotation silently disappears when printed). */
-declare const DRAWN_FLAGS: AnnotationFlags;
-/** All ten flags, for iteration/equality — kept in the primitives' order. */
-declare const FLAG_KEYS: ReadonlyArray<keyof AnnotationFlags>;
-declare const flagsEqual: (a: AnnotationFlags, b: AnnotationFlags) => boolean;
-/** Merge a partial write over the current flags. */
-declare const mergeFlags: (base: AnnotationFlags, patch: Partial<AnnotationFlags>) => AnnotationFlags;
+import { Annotation, AnnotationBorderStyle, AnnotationDraft, AnnotationFlags, AnnotationFlags as AnnotationFlags$1, AnnotationPatch, AnnotationRef, AnnotationSubtype, BlendMode, BlendMode as BlendMode$1, Color, FaceRequest, FileAttachmentIcon, FontHandle, InkIntent, LineEnding, LineEnding as LineEnding$1, LineEndings, LineEndings as LineEndings$1, NO_ANNOTATION_FLAGS, NoteIcon, PageRef, PdfLinkTarget, PdfLinkTargetWritable, RichTextBody, RichTextDocument, RichTextDocumentInput, RichTextParagraph, RichTextRunStyle, STANDARD_FACES, WidgetAppearance } from "@embedpdf/engine-core/runtime";
+import { PageRotation, Point, Point as Point$1, Quad, Quad as Quad$1, QuadRing, Rect as Rect$1, Size } from "@embedpdf/core-geometry";
+//#region src/editable.d.ts
+/** The intents a measurement goes by in {@link EditableKinds}. */
+type MeasurementIntent = 'line-dimension' | 'polyline-dimension' | 'polygon-dimension';
+/** What {@link EditableKinds} names an annotation by: {@link editableKindOf}. */
+type EditableKind = AnnotationSubtype | MeasurementIntent;
 /**
- * On-screen visibility. `hidden` beats everything; `noView` hides unless
- * `toggleNoView` and the annotation is ENGAGED — the spec says hover/selection,
- * and v1 uses selection (the model tracks no hover).
+ * Which annotations people may change by hand: `true`, every one; `false`,
+ * none; a list, the annotations of the kinds it names, each by its subtype,
+ * or a measurement by its intent (so measurements and the shapes they're
+ * drawn as are told apart).
  */
-declare const viewable: (f: AnnotationFlags, engaged?: boolean) => boolean;
-/** Any pointer interaction (click-to-select, hover). ReadOnly kills it. */
-declare const interactive: (f: AnnotationFlags) => boolean;
-/** The subset of an Annot these predicates read — keeps them testable bare. */
-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;
+type EditableKinds = boolean | readonly EditableKind[];
+/** The name {@link EditableKinds} knows an annotation by: a measurement's intent, else its subtype. */
+declare function editableKindOf(annotation: Annotation): EditableKind;
+/** Whether the session's rule lets people change this annotation by hand. */
+declare function isEditableByHand(model: Pick<Session, 'editable'>, annotation: Annotation): boolean;
+/** Whether people may move, resize, turn, reshape or restyle the record by hand now. */
+declare const isTransformableByHand: (model: Pick<Session, "editable">, record: ModelAnnotation) => boolean;
+/** Whether people may delete the record by hand now. */
+declare const isDeletableByHand: (model: Pick<Session, "editable">, record: ModelAnnotation) => boolean;
+/** Whether people may edit the record's text in place now. */
+declare const isContentsEditableByHand: (model: Pick<Session, "editable">, record: ModelAnnotation) => boolean;
+//#endregion
+//#region src/painted.d.ts
+/** One piece of what an annotation paints, in page space. */
+type PaintedPiece =
+/** Ink along a path, `halfWidth` either side of it; `closed` runs it back to the first point. */
+{
+  readonly kind: 'stroke';
+  readonly points: readonly Point[];
+  readonly closed: boolean;
+  readonly halfWidth: number;
+} |
+/** A filled polygon (even-odd). A margin doesn't grow it: ink around it does. */
+{
+  readonly kind: 'area';
+  readonly ring: readonly Point[];
+} |
+/**
+ * An ellipse turned `rotation` degrees clockwise about `center`: its ink,
+ * `halfWidth` either side of it, and its inside when `filled`. The ink's
+ * width is measured in radii along the smaller radius, so a long ellipse's
+ * ink is a little wider at its ends.
+ */
+{
+  readonly kind: 'oval';
+  readonly center: Point;
+  readonly rx: number;
+  readonly ry: number;
+  readonly rotation: number;
+  readonly halfWidth: number;
+  readonly filled: boolean;
+};
+/**
+ * A solid body: anything inside the ring, and anything within a margin of
+ * its edge (a rim of ink with no width). A text box, a caret and a
+ * measurement's caption are hit this way.
+ */
+declare const bodyPieces: (ring: readonly Point[]) => PaintedPiece[];
+/** Is `point` within `margin` of what the pieces paint? */
+declare const paintedNear: (pieces: readonly PaintedPiece[], point: Point, margin: number) => boolean;
+/** Does the rect touch what the pieces paint: cross its ink, or lie on its fill? */
+declare const paintedTouches: (pieces: readonly PaintedPiece[], rect: Rect) => boolean;
+//#endregion
+//#region src/measurement-shape.d.ts
+type ShapeAnnotation = Extract<Annotation, {
+  subtype: 'polygon' | 'polyline';
+}>;
+/**
+ * A perimeter's or area's measurement: the engine's own fields for its scale,
+ * whether its caption shows, and its label (`contents`, which the engine
+ * works out). Where the caption sits is the shape's `captionCenter`.
+ */
+type ShapeMeasurementAppearance = {
+  intent: 'polyline-dimension' | 'polygon-dimension';
+} & Pick<ShapeAnnotation, 'measure' | 'captionEnabled' | 'contents'>;
+interface ShapeMeasurementLayout {
+  caption: DistanceCaptionLayout | null;
+  visualBounds: Rect;
+  selectionPoints: Point[];
+}
+declare function shapeMeasurementReadout(geometry: Shape, appearance: ShapeMeasurementAppearance): import("@embedpdf/engine-core/runtime").MeasurementReadout | import("@embedpdf/engine-core/runtime").MeasurementUnavailable;
+declare function shapeMeasurementLabel(geometry: Shape, appearance: ShapeMeasurementAppearance): string;
+/** Match the native shape-caption anchor, including an interior fallback for concave areas. */
+declare function automaticShapeCaptionCenter(points: readonly Point[], closed: boolean): Point;
+declare function shapeMeasurementLayout(geometry: Shape, appearance: ShapeMeasurementAppearance, style: Style): ShapeMeasurementLayout | null;
+declare function measurementLayout(geometry: Shape, appearance: MeasurementAppearance, style: Style): ShapeMeasurementLayout | null;
+declare function measurementSelectionQuad(geometry: Shape, appearance: MeasurementAppearance, style: Style): QuadRing;
+/**
+ * The caption dragged by `delta`: a distance's caption offset changes (its
+ * measurement), a perimeter's or area's caption center (its shape, kept
+ * upright with the vertices).
+ */
+declare function moveMeasurementCaption(geometry: Shape, appearance: MeasurementAppearance, delta: Point, style: Style): {
+  geometry: Shape;
+  measure: MeasurementAppearance;
+};
+//#endregion
+//#region src/measurement.d.ts
+type MeasurementAppearance = DistanceAppearance | ShapeMeasurementAppearance;
+type LineAnnotation = Extract<Annotation, {
+  subtype: 'line';
+}>;
+/**
+ * A distance's measurement: the engine's own fields for its scale, its
+ * caption (on or off, its position, and its offset in the line's own axes),
+ * its leader and its label (`contents`, which the engine works out).
+ */
+type DistanceAppearance = {
+  intent: 'line-dimension';
+} & Pick<LineAnnotation, 'measure' | 'captionEnabled' | 'captionPosition' | 'captionOffset' | 'leader' | 'contents'>;
+/**
+ * The annotation's measurement, when it is one: a line measuring a
+ * distance, a polyline a perimeter, a polygon an area, as its intent says.
+ * Its measurement fields, read off it for drawing and hit-testing.
+ */
+declare function measurementOf(annotation: Annotation): MeasurementAppearance | undefined;
+/**
+ * What a new measurement states beside its points: its intent, its scale
+ * (one the engine can write), its caption and leader as it has them, and its
+ * subject. Its label is the engine's: it works it out from the points and
+ * the scale.
+ */
+declare function measurementDraftFields(appearance: MeasurementAppearance): FieldValues;
+interface DistanceSegment {
+  from: Point;
+  to: Point;
+}
+interface DistanceCaptionLayout {
+  text: string;
+  center: Point;
+  along: Point;
+  normal: Point;
+  width: number;
+  height: number;
+  bounds: QuadRing;
+}
+/** One layout drives the preview, selection, handles, and hit testing. */
+interface DistanceLayout {
+  along: Point;
+  normal: Point;
+  length: number;
+  measuredStart: Point;
+  measuredEnd: Point;
+  dimensionStart: Point;
+  dimensionEnd: Point;
+  dimensionSegments: DistanceSegment[];
+  leaderSegments: DistanceSegment[];
+  captionConnector: DistanceSegment[];
+  caption: DistanceCaptionLayout | null;
+  arrowPlacement: 'inside' | 'outside';
+  endings: RenderNode[];
+  selectionPoints: Point[];
+  visualBounds: Rect;
+}
+declare function distanceLabel(geometry: Shape, appearance: DistanceAppearance): string;
+declare function distanceLayout(geometry: Shape, appearance: DistanceAppearance, strokeWidth: number): DistanceLayout | null;
+declare function expandDistanceBounds(bounds: Rect, padding: number): Rect;
+declare function distanceSelectionQuad(geometry: Shape, appearance: DistanceAppearance, strokeWidth: number): QuadRing;
+declare function distanceHandles(layout: DistanceLayout): Handle[];
+declare function distanceCaptionHit(layout: {
+  caption: DistanceCaptionLayout | null;
+}, point: Point, margin?: number): boolean;
+/** What a measurement's caption paints: its box, grabbed anywhere in it and near its edge. */
+declare const captionPainted: (caption: DistanceCaptionLayout | null) => PaintedPiece[];
+/**
+ * What a distance measurement paints: its caption, the ink of its dimension
+ * line, leaders and caption connector, and its endings.
+ */
+declare function distancePainted(layout: DistanceLayout, strokeWidth: number): PaintedPiece[];
+declare function distanceCaptionAt(geometry: Shape, appearance: DistanceAppearance, width: number): Point | null;
+declare function distanceLeaderLength(geometry: Shape, point: Point): number;
+declare function moveDistanceCaption(geometry: Shape, appearance: DistanceAppearance, delta: Point): DistanceAppearance;
+/**
+ * The upright box around all a distance paints: its dimension line, leader
+ * and connector lines and its endings stroked at `strokeWidth` (what
+ * `distanceScene` draws), and its caption's box.
+ */
+declare function distanceDrawnBounds(layout: DistanceLayout, strokeWidth: number): Rect;
+declare function distanceScene(geometry: Shape, appearance: DistanceAppearance, style: Style): SceneNode[];
+declare function measurementCaptionScene(caption: DistanceCaptionLayout | null, style: Style): SceneNode[];
+//#endregion
+//#region src/shapes/family.d.ts
+/** A box's four corners as the page shows them: nw, ne, se, sw. */
+type Corners = [Point, Point, Point, Point];
+interface ShapeFamily<S extends Shape = Shape> {
+  /** The shape, read off an annotation of a kind in this family. */
+  read(annotation: Annotation): S;
+  /** The engine fields that state `shape` on an annotation of `subtype`. */
+  write(shape: S, subtype: string): FieldValues;
+  /**
+   * The shape a create gesture makes at `placement` (a clicked or dragged box
+   * or segment, `placement.ts`) for `annotation`, what the tool creates before
+   * it has a shape; `null` when this family's kinds aren't made that way.
+   */
+  placed(placement: Placement, annotation: Annotation): S | null;
+  /** The box around its box or points, the stroke left out. */
+  bounds(shape: S): Rect;
+  /**
+   * The box the live drawing is painted into (the stroke, endings, a cloud's
+   * bumps): a box's or caret's own, before its turn (the renderer turns it),
+   * the page's for the rest.
+   */
+  drawnBounds(shape: S, stroke: Stroke): Rect;
+  /** The upright page box around all it paints: the engine's `rect`, as it measures its appearance. */
+  rect(shape: S, stroke: Stroke): Rect;
+  /** The box a selection wraps: where its handles sit, and where a selected shape is grabbed. */
+  selectionBounds(shape: S, stroke: Stroke): Rect;
+  /** Does the shape have a turned box of its own, which a selection outlines turned? */
+  oriented(shape: S): boolean;
+  /** That turned box's corners, or `null` when the shape has none. */
+  turnedCorners(shape: S, stroke: Stroke): Corners | null;
+  /** Where a turn of the shape pivots, as the engine turns it. */
+  pivot(shape: S): Point;
+  /** The shape moved by `delta`. */
+  translate(shape: S, delta: Point): S;
+  /** The shape turned `degrees` clockwise about `pivot`; unchanged when it doesn't turn. */
+  rotateAbout(shape: S, pivot: Point, degrees: number): S;
+  /**
+   * The shape scaled about `anchor` by `(sx, sy)`, exactly. A resize passes
+   * its limit, `minSize`: a box then ends up no smaller than that.
+   */
+  scaleAbout(shape: S, anchor: Point, sx: number, sy: number, minSize?: number): S;
+  /** The shape with its turn cleared, turned back about `pivot` where that matters. */
+  upright(shape: S, pivot?: Point): S;
+  /** Its handles: resize corners and sides, or vertices. */
+  handles(shape: S): Handle[];
+  /** The shape with `handle` dragged to `to`. */
+  drag(shape: S, handle: string, to: Point): S;
+  /**
+   * What it paints (`painted.ts`): its ink, and its inside when `filled`. A
+   * click and the marquee both read these pieces.
+   */
+  painted(shape: S, stroke: Stroke, filled: boolean): PaintedPiece[];
+  /** What it draws, for the live (vector) view. */
+  scene(shape: S, stroke: Stroke): RenderNode[];
+}
+//#endregion
+//#region src/shapes/box.d.ts
+/** A box and its turn, as the engine keeps them. */
+interface TurnedBox {
+  /** The box before any turn: the engine's `box`, or its `rect` for a kind that never turns. */
+  box: Rect;
+  /** Degrees clockwise about the middle of `box`; 0 when upright. */
+  rotation: number;
+}
+/** A box family record's shape: the engine's box and its turn. */
+interface BoxShape extends TurnedBox {
+  kind: 'box';
+  /** Drawn as the ellipse in `box`: a circle. */
+  ellipse: boolean;
+}
+/** The box family: a box and its turn, drawn as a rectangle, an ellipse or a cloud. */
+declare const boxFamily: ShapeFamily<BoxShape>;
+//#endregion
+//#region src/shapes/caret.d.ts
+/** A caret record's shape: the engine's box and its turn. */
+interface CaretShape extends TurnedBox {
+  kind: 'caret';
+}
+/**
+ * The caret box for a text-edit anchor, upright: half the glyph's ink height,
+ * centred on the trailing baseline corner in reading direction (`advance`
+ * decides which end, so a right-to-left caret lands on the visual left),
+ * sitting on the baseline. {@link caretFromAnchor} gives the turned caret.
+ */
+declare function caretRectFromAnchor(anchor: TextEndAnchor): Rect;
+/**
+ * The caret for a text-edit anchor: a box whose middle sits half a caret size
+ * toward the ascent from the trailing baseline corner, turned by the text's
+ * baseline tilt (degrees clockwise), so the mark hugs the turned baseline and
+ * points at its text. For upright text this is exactly
+ * {@link caretRectFromAnchor} with no turn.
+ */
+declare function caretFromAnchor(anchor: TextEndAnchor): CaretShape;
+/**
+ * The caret family: a mark in a turned box that follows its text. It moves
+ * and scales with a selection, but no gesture turns, resizes or drags it.
+ */
+declare const caretFamily: ShapeFamily<CaretShape>;
+//#endregion
+//#region src/shapes/points.d.ts
+/** A line: its two ends upright, and their endings. */
+interface LineShape {
+  kind: 'line';
+  linePoints: {
+    start: Point;
+    end: Point;
   };
+  lineEndings?: LineEndings$1;
+  /** Degrees clockwise about the middle of the box around the upright points; 0 when upright. */
+  rotation: number;
+}
+/** A polygon (`closed`) or polyline: its vertices upright, and a polyline's endings. */
+interface PolyShape {
+  kind: 'poly';
+  vertices: Point[];
+  closed: boolean;
+  lineEndings?: LineEndings$1;
+  /** A measurement's caption center, upright with the vertices; `null` places it automatically. */
+  captionCenter?: Point | null;
+  /** Degrees clockwise about the middle of the box around the upright points; 0 when upright. */
+  rotation: number;
+}
+/** Ink: its strokes upright. */
+interface InkShape {
+  kind: 'ink';
+  inkList: Point[][];
+  /** Degrees clockwise about the middle of the box around the upright points; 0 when upright. */
+  rotation: number;
+}
+/** A points family record's shape. */
+type PointsShape = LineShape | PolyShape | InkShape;
+/** A line's or polyline's endings; none for an annotation that has none. */
+declare const lineEndingsOf: (annotation: Annotation) => LineEndings$1;
+/** Where the points are drawn: the upright ones turned by `rotation`. The same lists for the same shape. */
+declare function drawnStrokesOf(shape: PointsShape): Point[][];
+/** 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). */
+declare const MITER_LIMIT = 10;
+/** The points family: points kept upright and the turn that draws them. */
+declare const pointsFamily: ShapeFamily<PointsShape>;
+//#endregion
+//#region src/shapes/quads.d.ts
+/** A quads family record's shape: its text's quads. */
+interface QuadsShape {
+  kind: 'quads';
+  quadPoints: Quad$1[];
 }
-/** 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 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.
+ * The quads family: marks bound to their text. They move with a selection,
+ * but no gesture turns, scales or drags them, and they have no turned box.
  */
-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;
+declare const quadsFamily: ShapeFamily<QuadsShape>;
 //#endregion
-//#region src/types.d.ts
+//#region src/shapes/text-box.d.ts
+type FreeTextAnnotation = Extract<Annotation, {
+  subtype: 'free-text';
+}>;
+/** A callout's line: its tip, its knee when it bends, and where it meets the box. */
+type CalloutLine = NonNullable<FreeTextAnnotation['calloutLine']>;
+/** A free text's shape: the engine's box, turn, and a callout's line. */
+interface TextBoxShape extends TurnedBox {
+  kind: 'text-box';
+  /** A callout's line; `null` for a plain text box. */
+  calloutLine: CalloutLine | null;
+  /** The ending at a callout's tip. */
+  lineEnding: LineEnding$1 | null;
+}
 /**
- * Content-space point/rect (y-down, PDF points, crop-relative) — the viewer space.
- * These are the shared `@embedpdf/core-geometry` primitives: a `Vec` IS a `Point`
- * and `Rect` IS geometry's `Rect`, so the whole stack speaks one vocabulary and
- * the coordinate math lives in ONE package.
+ * Where a callout's line meets its box: the middle of the side `toward` (the
+ * knee, else the tip) lies beyond, chosen by which way it is farther from the
+ * box's middle, across or up and down. A turned box decides in its own frame,
+ * and the point lands on the turned side, the one the page shows. The
+ * engine's rule, in page space.
  */
-type Vec = Point;
+declare function calloutEnd(box: Rect, toward: Point, rotation?: number): Point;
+/**
+ * The text box family: a free text's box and turn, and a callout's line.
+ * Only a plain box turns; a callout's box keeps the turn it was made with,
+ * and a selection outlines everything it paints, upright.
+ */
+declare const textBoxFamily: ShapeFamily<TextBoxShape>;
+/**
+ * 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; 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;
+//#endregion
+//#region src/types.d.ts
 type Rect = Rect$1;
-/** 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).
+ * glyph's oriented cell plus the reading direction along its baseline
+ * (+1 = toward the right end, −1 = toward the left end — sequence-derived,
+ * never inferred from geometry).
  */
 interface TextEndAnchor {
-  glyphQuad: TextQuad$1;
+  glyphQuad: Quad$1;
   advance: 1 | -1;
 }
 type Id = string;
@@ -73,128 +393,80 @@ type Cursor = string;
 type PolySubtype = 'polygon' | 'polyline';
 /**
  * The per-page view environment the screen-anchor projection consumes:
- * `zoom` — the page's zoom RELATIVE to its 100% baseline (dimensionless;
+ * `zoom` — the page's zoom relative to its 100% baseline (dimensionless;
  * 1 = Acrobat's 100% = `viewUnitsPerPoint × userUnit` view px per point) —
- * and the TOTAL display rotation (document /Rotate + view rotation).
- * Deliberately NOT a px-per-point scale: `noZoom` means "hold the body at its
- * 100%-zoom size", a statement about zoom, so feeding it a units conversion
- * (the old mistake) shrank bodies at 100%. Per-event / per-call context (the
+ * and the total display rotation (document /Rotate + view rotation).
+ * Deliberately not a px-per-point scale: `noZoom` means "hold the body at its
+ * 100%-zoom size", a statement about zoom; a units conversion here would
+ * shrink bodies at 100%. Per-event / per-call context (the
  * `pageBox` pattern) — never stored on the model; the pointer drafts capture
- * it at DOWN so anchored gestures project and commit with the view they
+ * it at down so anchored gestures project and commit with the view they
  * started under. See anchor.ts.
  */
 interface ViewEnv {
   zoom: number;
   rotation: PageRotation;
 }
-type Subtype = 'highlight' | 'underline' | 'squiggly' | 'strikeout' | 'square' | 'circle' | 'line' | 'polygon' | 'polyline' | 'caret' | 'ink' | 'stamp' | 'text' | 'file-attachment' | 'redact' | 'link' | (string & {});
-/**
- * Content-space geometry — the ONE thing hit-testing, editing, and rendering work
- * on. A small closed union covers every kind: shapes (rect/ellipse), line,
- * polygon/polyline (poly), text markup (quads), and caret.
- */
 /**
- * A free-text callout's leader: the `/CL` line + `/LE` arrow. `tip` is the
- * called-out point (the arrow is drawn here); `knee` is the optional elbow. The
- * point where the leader meets the text box (the third `/CL` point) is NEVER
- * stored — it is DERIVED from the box + the knee (see `calloutConnection`), so it
- * can't drift when the box or knee moves. Content space (y-down).
+ * An annotation kind's name (`kinds/`): its PDF subtype, a widget's field
+ * family (`widget-text`…), or a free text's callout (`free-text-callout`).
  */
-interface Callout {
-  tip: Vec;
-  knee?: Vec;
-  ending: LineEnding;
-}
+type KindName = 'highlight' | 'underline' | 'squiggly' | 'strikeout' | 'square' | 'circle' | 'line' | 'polygon' | 'polyline' | 'caret' | 'ink' | 'stamp' | 'text' | 'file-attachment' | 'redact' | 'link' | (string & {});
 /**
- * Rotation (degrees, clockwise in content space, normalized `[0,360)`) carried by
- * the rotatable `Geom` variants. The semantics differ by family, which is exactly
- * the box-vs-vertex split:
+ * An annotation's shape: what hit-testing, gestures and drawing work on, read
+ * off the annotation by its kind's family (`shapeOf`). One arm per family,
+ * each the engine's own fields
+ * ({@link BoxShape}, {@link TextBoxShape}, {@link PointsShape},
+ * {@link QuadsShape}, {@link CaretShape}).
  *
- * - **Box** (`rect`, `text`): `rect` is the UNROTATED local box and `rot` is the
- *   applied tilt — together they reconstruct the visual. The repository emits
- *   `rect` as `unrotatedRect`, `rot` as the rendered `/EMBD_Metadata/Rotation`,
- *   and the rotated visual AABB as `/Rect`, so PDFium bakes a portable `/AP`.
- * - **Vertex** (`line`, `poly`, `ink`): the points are ALREADY rotated (they are
- *   the portable visual), so `rot` is an ADVISORY scalar — the cumulative tilt the
- *   user applied since authoring. It lets EmbedPDF reconstruct an oriented
- *   selection box (`obbFromTheta`) and offer reset-to-0; it is inert for
- *   rendering (PDFium ignores a lone `Rotation` with no `UnrotatedRect`).
- */
-type Geom = {
-  t: 'rect';
-  rect: Rect;
-  ellipse: boolean;
-  rot?: number;
-} | {
-  t: 'line';
-  a: Vec;
-  b: Vec;
-  ends?: LineEndings;
-  rot?: number;
-} | {
-  t: 'poly';
-  points: Vec[];
-  closed: boolean;
-  ends?: LineEndings;
-  rot?: number;
-} | {
-  t: 'quads';
-  quads: TextQuad$1[];
-} | {
-  t: 'caret';
-  rect: Rect;
-  rot?: number;
-} | {
-  t: 'ink';
-  strokes: Vec[][];
-  rot?: number;
-} | {
-  t: 'text';
-  rect: Rect;
-  callout?: Callout;
-  rot?: number;
-};
+ * Rotation is degrees clockwise in page space, normalized `[0,360)`, and
+ * works the same way for every family that turns: the shape is kept upright
+ * (a box, or points), and `rotation` turns it about its middle. The engine
+ * works out `/Rect` around the turned drawing, so PDFium bakes a portable `/AP`.
+ */
+type Shape = BoxShape | PointsShape | QuadsShape | CaretShape | TextBoxShape;
 /**
- * How a shape's outline is stroked. A discriminated union so illegal combinations
- * — a dash array on a cloudy border, an intensity on a dashed one — are simply
- * unrepresentable. Maps onto the engine's `/BS /S` (`borderStyle`), `/BS /D`
- * (`dashArray`), and `/BE /I` (`cloudyIntensity`) wire fields. Cloudy is only
- * honoured for shapes (square/circle); other kinds treat it as solid.
+ * How an annotation is drawn, by the engine's field names: its colours, its
+ * stroke and its border, with its kind's fill-ins (a highlight strokes
+ * nothing, a caret draws 1 pt). A view its kind works out from the
+ * annotation (`styleOf`, `kinds/styles.ts`) for drawing, bounding and
+ * hit-testing: nothing is written back through it.
  */
-type Border = {
-  kind: 'solid';
-} | {
-  kind: 'dashed';
-  dash: number[];
-} | {
-  kind: 'cloudy';
-  intensity: number;
-};
 interface Style {
-  /** `/C` colour — stroke for geometric kinds, highlight colour for markup. */
-  color: string;
-  /** `/IC` interior (fill) colour. `null` when the annotation has no fill. */
-  interiorColor: string | null;
+  /** The stroke for a drawn kind, a markup's colour, a free text's border. */
+  color: Color;
+  /** The fill; `null` when the annotation has none. */
+  interiorColor: Color | null;
   strokeWidth: number;
   opacity: number;
-  /** Effective blend mode of the annotation's normal appearance. */
   blendMode: BlendMode$1;
-  /** Outline style — defaults to `{ kind: 'solid' }`. */
-  border: Border;
+  borderStyle: AnnotationBorderStyle;
+  /** A dashed border's pattern; `null` draws the engine's default dash. */
+  dashArray: number[] | null;
+  /** A cloudy border's intensity; `null` without a cloud. A cloud wins over a dash. */
+  cloudyIntensity: number | null;
+}
+/**
+ * What a shape's bounds, hit test and drawing depend on besides the shape:
+ * how wide its stroke is, and a cloud's intensity. A {@link Style} is one.
+ */
+interface Stroke {
+  strokeWidth: number;
+  cloudyIntensity?: number | null;
 }
 type TextAlign = 'left' | 'center' | 'right';
 /**
- * Content-space text styling for a text-editable kind (free text) — the text
- * counterpart of {@link Style}, projected from the DTO's `/DA` fields the same
- * way `style` is projected from `/C`/`/CA`/`/BS`. CSS colour string; the engine
- * `Color` seam is crossed only in the plugin repository.
+ * How an annotation's text is set, by the engine's field names: its font,
+ * size, colour and alignment, and a free text's bold, italic and underline.
+ * A view its kind works out from the annotation (`textOf`,
+ * `kinds/texts.ts`): nothing is written back through it.
  */
 interface TextStyle {
   /** A PDF standard font name or a registered font key. */
   fontFamily: string;
-  /** Content units (PDF points). */
+  /** Page units (PDF points); 0 fits a form field's or a redaction label's box. */
   fontSize: number;
-  fontColor: string;
+  fontColor: Color;
   textAlign: TextAlign;
   /**
    * The rich body's formatting (free text only): bold = body weight ≥ 600,
@@ -207,81 +479,40 @@ interface TextStyle {
   underline?: boolean;
 }
 /**
- * The ONE flat vocabulary for editable appearance properties — what property
- * sidebars/toolbars read and write, regardless of where each property is stored
- * internally (`style`, `geom.ends`, or `text`). Which keys apply to a kind, and
- * in what UI order, is declared per kind in the KIND table (`propsFor`).
+ * Engine fields by name, as a create or an update states them: a tool's
+ * defaults (a draft without its shape), or what a selection edit writes to
+ * each member. The kind table's {@link AnnotationProperty} lists say which a style panel edits.
+ */
+type FieldValues = Readonly<Record<string, unknown>>;
+/**
+ * One annotation as the core works on it: the engine's record, and how it is
+ * drawn right now. The record is the only data: its ref, page, kind and
+ * relationships are read off it (`refOf`, `kindOf`, `irtOf`, `groupOf`), so
+ * is its shape (`shapeOf`), and an edit writes engine fields back
+ * (`withShape`, `withValues`; record/).
  */
-interface AnnotationProps extends Style, TextStyle {
-  /** `/LE` endings (line / polyline). */
-  lineEndings: LineEndings;
+interface ModelAnnotation {
   /**
-   * `/Name` icon of an icon kind (text note, file attachment). Optional in
-   * the bag — each kind falls back to its own spec default ('comment',
-   * 'paperclip') at creation, so one flat vocabulary needs no per-kind base
-   * value. Valid values are the `options` of the kind's `icon` PropSpec.
+   * The record's key: `annotationKey(annotation.ref)`, for life. A record
+   * this session creates has its final ref from the start: the object number
+   * its create names.
    */
-  icon?: string;
+  id: Id;
   /**
-   * Where this annotation LINKS to, or `null` for none. Optional in the bag
-   * like `icon`. One key, two storages (the props.ts routing rule): on the
-   * link kind it is the annotation's OWN target (`/A`); on every other
-   * linkable kind it is the target of the ATTACHED link child(ren) —
-   * grouped `/Link` annotations the model folds into their parent (the
-   * serialization the PDF spec forces, since only Link annotations are
-   * clickable). Writing it creates/retargets/deletes those children through
-   * the ONE `syncLink` seam.
+   * A record this session created that the engine hasn't written yet: it
+   * has its ref, but no raster of its appearance.
    */
-  link?: PdfLinkTarget | null;
-}
-type PropKey = keyof AnnotationProps;
-/**
- * What a committed edit CHANGED — carried on the `patch` effect so the shell
- * emits exactly that intent (repository `toScopedPatch`) instead of
- * reconstructing a full projection. `geometry` covers every gesture commit
- * (move/resize/rotate/vertex edit); `props` forwards the user's patch keys
- * verbatim. Text content never rides this effect (the debounced text-edit
- * write owns `contents`).
- */
-type PatchScope = {
-  kind: 'geometry';
-} | {
-  kind: 'props';
-  keys: PropKey[];
-};
-/** A partial property write. `lineEndings` merges per side (set just `end`
- *  without knowing `start`); every other key overwrites. */
-type AnnotationPropsPatch = { [K in PropKey]?: K extends 'lineEndings' ? Partial<LineEndings> : AnnotationProps[K]; };
-interface Annot {
-  id: Id;
-  ref: AnnotationRef | null;
-  pon: PageObjectNumber;
-  subtype: Subtype;
-  geom: Geom;
-  style: Style;
-  /** Text styling — present only for text-editable kinds (free text). Like
-   *  `style`, a content-space projection of `data`, editable via `setProps`. */
-  text?: TextStyle;
-  /** Redaction label (`/OverlayText` + `/Repeat`) — redact kind only. A
-   *  projection of `data` like `text`; the hover preview scene draws it. */
-  label?: {
-    text: string;
-    repeat: boolean;
-  };
-  /** `/Name` icon — present only for icon kinds (text note, file attachment).
-   *  Like `style`, a projection of `data`, editable via `setProps`. */
-  icon?: string;
+  unconfirmed?: true;
   /**
-   * The `/F` annotation flags, verbatim from the DTO (freshly drawn annotations
-   * start at {@link DRAWN_FLAGS} — `print` set). NEVER read individual keys to
-   * gate behavior — the predicates in `flags.ts` (`annotInteractive`,
-   * `annotTransformable`, `annotContentsEditable`, `viewable`) are the one
-   * interpretation of the spec, and `anchorModeOf` owns `noZoom`/`noRotate`.
+   * How the record renders: `baked` blits the engine's appearance raster,
+   * `vector` draws it live from its geometry and style. The core sets
+   * `vector` when an edit makes the raster stale (a resize, a restyle,
+   * typing); a move keeps the raster. The plugin decides it for confirmed
+   * records: this session's edits stay live, another session's are baked.
    */
-  flags: AnnotationFlags$1;
   source: 'baked' | 'vector';
   /**
-   * Content-space box of the engine appearance raster (the AP `/Rect`), set when
+   * Page-space box of the engine appearance raster (the AP `/Rect`), set when
    * the annotation is derived from a DTO. While `source === 'baked'` the renderer
    * blits the engine bitmap into this box; a move translates it (a rigid shift
    * keeps the raster valid), so the bitmap rides along without re-rendering.
@@ -289,72 +520,58 @@ interface Annot {
    */
   apBox?: Rect;
   /**
-   * Rotation (deg, CW) that was STRIPPED from the baked raster — present only
-   * when the engine rendered this appearance rotation-free (a box-family kind
-   * whose DTO carries BOTH `rotation` and `unrotatedRect`; `apBox` is then the
-   * unrotated box). The blit re-applies it as a view transform about the box
-   * centre. Vertex kinds pre-rotate their geometry, so this stays unset there
-   * and their rasters blit untransformed.
+   * Rotation (deg, CW) that was stripped from the baked raster — present only
+   * when the engine rendered this appearance rotation-free (`appearanceTurnOf`:
+   * a box kind drawn turned, inside its turned box; `apBox` is then its `box`).
+   * The blit re-applies it as a view transform about the box centre. Vertex
+   * kinds pre-rotate their geometry, so this stays unset there and their
+   * rasters blit untransformed.
    */
   apRot?: number;
   /**
-   * Revision of the engine-baked `/AP` CONTENT (absent ≡ 0). The raster a baked
+   * The version of the engine's picture of it (absent ≡ 0). The picture a baked
    * annotation shows depends on exactly this and the render scale — never on
    * position (`apBox` translates the blit) or rotation (`apRot` transforms it) —
-   * so the shell re-fetches appearances precisely when it changes. Bumped by the
-   * `upsert` that confirms an engine re-bake with new content: a geometry patch
-   * that changed the authoring frame's SIZE resolving (`Effect.apChanged`), or a
-   * remote edit folding in. A move or rotate leaves it untouched: the old raster
-   * is still pixel-exact, so those cost zero re-renders.
+   * so the shell re-fetches pictures precisely when it changes. Owned by the
+   * plugin's confirmed records, which advance it when the engine reports a
+   * re-baked appearance; the core only reads it.
    */
-  apVersion?: number;
+  pictureVersion?: 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
+   * A lent record's live drawing, from its lender (a form widget, drawn by the
+   * form's painter): the record drawn upright in `box`, in page space. It
+   * gives a kind with no live drawing of its own one (`drawsLive`), so the
+   * record draws live while a gesture reshapes it, as a square does.
+   */
+  painter?: (box: Rect) => readonly SceneNode[];
+  /**
+   * This session's authority over this record (see permissions.md), set by the
+   * plugin from the security service; the core only reads it. 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.
+   * handles, no drag). Absent = unstamped (a record created in this session,
+   * 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
-   * content-space RENDER PROJECTIONS of it, recomputed (never edited directly)
-   * whenever `data` changes, so the two can't drift. Absent only for a vector
-   * draft that hasn't been committed to the engine yet (no DTO exists).
-   */
-  data?: AnnotationDTO;
-  /** Normalized PDF `/IT` for intent-bearing annotations authored before a DTO exists. */
-  intent?: CaretIntent | StrikeoutIntent | InkIntent;
-  /**
-   * 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.
+   * The annotation's data in the engine's shape: what the engine will read
+   * back once this session's writes land. A confirmed record's is the
+   * engine's own read; a record this session created reads as its create
+   * writes it (`newRecord`); an edit merges the fields it changed, and
+   * `update` applies them as the engine will, a drawn kind's `rect`
+   * included (`record/written.ts`). Its attribution waits for the engine's
+   * answer.
    */
-  link?: PdfLinkTarget | null;
-  /**
-   * 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
-   * replace-text pair. `group` ties a set into one composite unit (created and,
-   * typically, deleted together). Both are unused until comments / replace-text
-   * land, but the field lives here from the start so select/delete/persistence
-   * never have to be retrofitted around it.
-   */
-  irt?: Id;
-  group?: string;
+  annotation: Annotation;
 }
 /** A draggable handle: a resize corner/edge (rect) or a vertex (line/poly). */
 interface Handle {
   id: string;
-  at: Vec;
+  at: Point$1;
   cursor: Cursor;
 }
 /** An alignment guide produced by move-snapping: a vertical (`axis: 'x'`) or
@@ -365,198 +582,297 @@ interface Guide {
   lo: number;
   hi: number;
 }
-/** Snapping behaviour — seeded from the plugin config, live-adjustable via the
- *  `setSnap` msg (so an app can wire a UI toggle). */
+/**
+ * Snapping: to other annotations and the page while moving, and to angles
+ * while turning. The plugin keeps it in its settings and hands it in with
+ * `setSnap`.
+ */
 interface SnapSettings {
-  /** Alignment guides while moving (snap to other annotations + the page). */
-  guides: boolean;
-  /** Guide snap tolerance, content units (PDF pt) — the `hitMargin` convention. */
-  guideThreshold: number;
-  /** Snap the rotate gesture onto `rotationAngles`. */
-  rotation: boolean;
-  rotationAngles: number[];
-  /** Rotation snap tolerance, degrees. */
-  rotationThreshold: number;
+  /** Snap to the edges and centres of other annotations and of the page while moving. */
+  readonly alignment: boolean;
+  /**
+   * How close a move comes before it snaps, in screen pixels: each pointer
+   * sample converts it by its `scale`. Without one it is in page units.
+   */
+  readonly alignmentThreshold: number;
+  /** Snap a turn onto `rotationAngles`. */
+  readonly rotation: boolean;
+  /** The angles a turn snaps to, in degrees clockwise. */
+  readonly rotationAngles: readonly number[];
+  /** How close a turn comes before it snaps, in degrees. */
+  readonly rotationThreshold: number;
 }
 /**
  * The `defaults` key a creation draft resolves its props from — the authoring
- * TOOL that started it, which may differ from the PDF `subtype`. Two tools can
+ * tool that started it, which may differ from the PDF `subtype`. Two tools can
  * share a subtype but carry distinct defaults (an "arrow" is a `line` with an
  * arrowhead default); the preset keeps them apart. Absent → fall back to
  * `subtype` (a headless / programmatic caller that isn't tool-driven), so the
- * built-in tools where preset === subtype behave exactly as before.
+ * built-in tools where preset === subtype resolve from their subtype.
  */
 type Draft = {
-  g: 'create-rect';
-  subtype: Subtype;
+  kind: 'create-rect';
+  subtype: KindName;
   preset?: string;
-  pon: PageObjectNumber;
-  from: Vec;
-  to: Vec;
-  ellipse: boolean;
-  /** Display rotation + upright policy captured at DOWN (the gesture's home
-   *  page), so the commit counter-rotates against what the author SAW even
+  page: PageRef;
+  from: Point$1;
+  to: Point$1;
+  /** Display rotation + upright policy captured at down (the gesture's home
+   *  page), so the commit counter-rotates against what the author saw even
    *  if the up sample resolves elsewhere. See {@link PointerInput}. */
   displayRotation?: PageRotation;
   upright?: boolean;
-  /** The tool's click-create policy, captured at DOWN like `upright`. */
+  /** The tool's click-create policy, captured at down like `upright`. */
   clickCreate?: ClickCreate | false;
-  /** The tool's `/F` seed, captured at DOWN like `upright` — merged over
+  /** 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-line';
-  subtype: Subtype;
+  kind: 'create-distance';
+  step: 'endpoints' | 'offset';
+  subtype: 'line';
+  preset: string;
+  page: PageRef;
+  from: Point$1;
+  to: Point$1;
+  measure: DistanceAppearance;
+  flags?: Partial<AnnotationFlags$1>;
+} | {
+  kind: 'create-line';
+  measure?: MeasurementAppearance;
+  capture?: string;
+  subtype: KindName;
   preset?: string;
-  pon: PageObjectNumber;
-  from: Vec;
-  to: Vec;
-  /** The tool's click-create policy, captured at DOWN like `upright`. */
+  page: PageRef;
+  from: Point$1;
+  to: Point$1;
+  /** Display rotation + upright policy captured at down (see the rect
+   *  draft): an upright tool's click lays its line as the author saw the page. */
+  displayRotation?: PageRotation;
+  upright?: boolean;
+  /** The tool's click-create policy, captured at down like `upright`. */
   clickCreate?: ClickCreate | false;
-  /** The tool's `/F` seed, captured at DOWN (see the rect draft). */
+  /** The tool's `/F` seed, captured at down (see the rect draft). */
   flags?: Partial<AnnotationFlags$1>;
 } | {
-  g: 'create-poly';
-  subtype: Subtype;
+  kind: 'create-poly';
+  measure?: ShapeMeasurementAppearance;
+  subtype: KindName;
   preset?: string;
-  pon: PageObjectNumber;
-  points: Vec[];
-  cur: Vec;
+  page: PageRef;
+  points: Point$1[];
+  current: Point$1;
   closed: boolean;
-  /** The tool's `/F` seed, captured at DOWN (see the rect draft). */
+  /** The tool's `/F` seed, captured at down (see the rect draft). */
   flags?: Partial<AnnotationFlags$1>;
 } | {
-  g: 'create-ink';
-  subtype: Subtype;
+  kind: 'create-ink';
+  subtype: KindName;
   preset?: string;
-  pon: PageObjectNumber;
-  strokes: Vec[][];
+  page: PageRef;
+  strokes: Point$1[][];
   intent?: InkIntent;
-  /** The tool's `/F` seed, captured at DOWN (see the rect draft). */
+  /** The tool's `/F` seed, captured at down (see the rect draft). */
   flags?: Partial<AnnotationFlags$1>;
 } | {
-  g: 'create-callout';
-  subtype: Subtype;
+  kind: 'create-callout';
+  subtype: KindName;
   preset?: string;
-  pon: PageObjectNumber;
+  page: PageRef;
   step: 'knee' | 'box';
-  tip: Vec;
-  knee?: Vec;
-  cur: Vec;
-  boxFrom?: Vec;
-  boxTo?: Vec;
-  /** Display rotation + upright policy captured at the TIP click (the
-   *  gesture's home page) — the text BOX commits counter-rotated so it
+  tip: Point$1;
+  knee?: Point$1;
+  current: Point$1;
+  boxFrom?: Point$1;
+  boxTo?: Point$1;
+  /** Home-page box captured at the tip click. The default text box slides
+   *  fully inside it; a drag is already point-clamped and ignores this. */
+  pageBox?: Rect;
+  /** Display rotation + upright policy captured at the tip click (the
+   *  gesture's home page) — the text box commits counter-rotated so it
    *  reads upright; the leader (tip/knee) is page-space and never turns.
    *  Same capture rule as the rect draft. */
   displayRotation?: PageRotation;
   upright?: boolean;
-  /** The tool's `/F` seed, captured at DOWN (see the rect draft). */
+  /** The tool's `/F` seed, captured at down (see the rect draft). */
   flags?: Partial<AnnotationFlags$1>;
 } | {
-  g: 'move';
+  kind: 'move';
   ids: Id[];
-  start: Vec;
-  delta: Vec;
+  start: Point$1;
+  delta: Point$1;
   guides: Guide[];
 } | {
-  g: 'handle';
+  kind: 'handle';
   id: Id;
   handle: string;
-  base: Geom;
-  cur: Geom;
+  base: Shape;
+  current: Shape;
   view?: ViewEnv;
 } | {
-  g: 'rotate';
+  kind: 'rotate';
   ids: Id[];
-  pivot: Vec;
-  start: Vec;
-  cur: Vec;
+  pivot: Point$1;
+  start: Point$1;
+  current: Point$1;
   free?: boolean;
   view?: ViewEnv;
 } | {
-  g: 'group';
+  kind: 'group';
   op: 'resize';
   ids: Id[];
   handle: string;
-  anchor: Vec;
+  anchor: Point$1;
   base: Rect;
-  cur: Rect;
+  current: Rect;
   view?: ViewEnv;
 } | {
-  g: 'marquee';
-  pon: PageObjectNumber;
-  from: Vec;
-  to: Vec;
+  kind: 'caption';
+  id: Id;
+  start: Point$1;
+  delta: Point$1;
+} | {
+  kind: 'leader';
+  id: Id;
+  start: Point$1;
+  delta: number;
+} | {
+  kind: 'marquee';
+  page: PageRef;
+  from: Point$1;
+  to: Point$1;
 };
 /** A live text-markup preview (the in-progress selection rendered as the markup it
  *  will become). Per page, since a selection can span pages. */
 interface MarkupPreview {
-  subtype: Subtype;
+  subtype: KindName;
   /** Defaults key, distinct from subtype for presets such as replace-text. */
   preset: string;
-  byPage: Record<number, TextQuad$1[]>;
+  /** Keyed by `page.pageObjectNumber` (an internal lookup, not an address). */
+  byPage: Record<number, Quad$1[]>;
 }
 /** Anchor + affordance state for UI that controls an in-progress creation draft. */
+/**
+ * A rotation in progress, for the badge that follows the pointer: the page
+ * it runs on, the pointer there (page space) and the selection's angle as the
+ * commit will apply it (degrees clockwise, whole degrees).
+ */
+interface RotationAnchor {
+  page: PageRef;
+  at: Point$1;
+  angle: number;
+}
 interface CreationDraftAnchor {
   kind: 'poly';
   subtype: PolySubtype;
-  pon: PageObjectNumber;
+  page: PageRef;
   bounds: Rect;
   pointCount: number;
   minPoints: number;
   canFinish: boolean;
 }
-interface Model {
-  byId: Record<Id, Annot>;
-  order: Id[];
+/**
+ * What the core owns: everything about the user's session that is not a
+ * record. `update` returns the next session; the plugin stores it.
+ */
+interface Session {
   selected: Id[];
   /** The annotation under the pointer (topmost hit), or null. View-model
    *  state like `selected` — drives hover affordances (a redaction mark's
-   *  applied-look preview) purely from the scene. Updated on CHANGE only
+   *  applied-look preview) purely from the scene. Updated on change only
    *  (enter/leave cadence, never per-move). */
   hovered: Id | null;
+  /** The gesture in progress (a move, a resize, a shape being drawn), or null. */
   draft: Draft | null;
   /** Transient ghost of an in-progress markup selection (null when idle). */
   preview: MarkupPreview | null;
-  seq: number;
-  /** The base style new annotations inherit (per-tool `defaults` layer on top). */
-  style: Style;
-  /** Per-tool (keyed by subtype / tool id) property overrides for newly drawn
-   *  annotations — the SAME flat vocabulary `setProps` uses. `lineEndings` is
-   *  stored fully resolved (merged at `setDefaults` time). */
-  defaults: Record<string, AnnotationPropsPatch>;
-  /** Extra clickable margin (content units) around a stroke — bump it for touch. */
+  /**
+   * The object numbers this session holds for the records it creates next: a
+   * message's first new record takes the first, and so on. The plugin hands
+   * the session numbers from the document's pool before a message that may
+   * create (`newRecordsAtMost`).
+   */
+  objectNumbers: readonly number[];
+  /**
+   * Each tool's defaults for the annotations it draws, keyed by the tool's
+   * preset: the engine fields its creates state. The engine's own defaults
+   * fill in what they leave out.
+   */
+  defaults: Record<string, FieldValues>;
+  /**
+   * Extra clickable margin around what an annotation paints, in screen
+   * pixels: converted by the page's view scale, so a click reaches as far at
+   * every zoom. Bump it for touch.
+   */
   hitMargin: number;
-  /** The free-text annotation currently in TEXT-EDIT mode (its `contentEditable`
+  /** The free-text annotation currently in text-edit mode (its `contentEditable`
    *  is focused), or null. Distinct from `selected`: you select to move/resize,
    *  you edit to type. */
   editing: Id | null;
   /** Snapping behaviour (alignment guides + rotation). */
   snap: SnapSettings;
+  /** Which annotations people may change by hand (editable.ts): the plugin sets it from its settings. */
+  editable: EditableKinds;
+}
+/**
+ * The records a gesture works on, read-only: what the engine confirmed with
+ * this session's pending changes on top. The plugin builds it; the core never
+ * stores a record.
+ */
+interface AnnotationView {
+  byId: Record<Id, ModelAnnotation>;
+  /** Paint order: the document's order, then records created in this session. */
+  order: Id[];
 }
+/** What every transition and read takes: the session composed with the records it works on. */
+type Model = Session & AnnotationView;
 /**
- * Selection-chrome geometry in CONTENT units — the grab zones and the knob
+ * What one message changed in the records. `put` holds new or changed records
+ * as the user produced them; `drop` holds the ids the user deleted. The plugin
+ * shows them until the engine writes that carry them settle.
+ */
+interface ChangeSet {
+  readonly put: readonly ModelAnnotation[];
+  readonly drop: readonly Id[];
+  /**
+   * What each changed record's change means to the engine, by id: the fields
+   * it changed, as `update` takes them. None for a new record (its create
+   * writes it) or for a change the engine keeps nothing of (a record handed
+   * to live rendering, a value set to what it was).
+   */
+  readonly patches: Readonly<Record<Id, AnnotationPatch>>;
+}
+/** The result of one message: the next session, the records it changed, and the engine work to do. */
+interface UpdateResult {
+  readonly session: Session;
+  readonly change: ChangeSet;
+  readonly effects: readonly Effect[];
+}
+/**
+ * Selection-chrome geometry in content units — the grab zones and the knob
  * stalk. The core is unit-agnostic and zoom-free: callers own the px→content
  * conversion (settings are CSS px; divide by the page's view scale), so grab
  * zones stay screen-constant across zoom.
  */
-interface ChromeGeom {
+interface ChromeGeometry {
   /** Half-side of a resize/vertex handle's square grab zone. */
   handleTol: number;
   /** Half-side of the rotate knob's square grab zone. */
   knobTol: number;
   /** How far the rotate knob hangs off the selection edge. */
   knobOffset: number;
+  /** `false`: the selection has no rotation handle to grab (it isn't drawn either). */
+  rotationHandle?: boolean;
 }
 interface PointerInput {
-  pon: PageObjectNumber;
-  point: Vec;
+  /** The page the sample resolved against (its own page-space frame). */
+  page: PageRef;
+  point: Point$1;
   shift: boolean;
   finish?: boolean;
   /**
    * The page's content box (`{0, 0, crop.width, crop.height}`) — when present,
-   * gestures are CLAMPED to it: a move keeps the selection's bounds inside the
+   * gestures are clamped to it: a move keeps the selection's bounds inside the
    * page (sliding along the edge when the pointer overshoots), resize/create
    * points pin to the edge. Annotations are page-bound; the pointer isn't.
    */
@@ -566,34 +882,41 @@ interface PointerInput {
    * exactly like `pageBox` (the caller converts its CSS-px settings by the
    * page's view scale at dispatch). Absent → `DEFAULT_CHROME_GEOM`.
    */
-  chrome?: ChromeGeom;
+  chrome?: ChromeGeometry;
   /**
-   * The page's TOTAL display rotation (document /Rotate + view rotation) at the
-   * gesture — per-event environmental context like `pageBox`. A creation DOWN
+   * The page's total display rotation (document /Rotate + view rotation) at the
+   * gesture — per-event environmental context like `pageBox`. A creation down
    * captures it on the draft (an `upright` commit counter-rotates against how
-   * the page was DISPLAYED); edit gestures read it per sample, paired with
+   * the page was displayed); edit gestures read it per sample, paired with
    * `scale`, so screen-anchored (`noZoom`/`noRotate`) annotations hit-test and
-   * clamp at their EFFECTIVE geometry. Content space itself never rotates.
+   * clamp at their effective geometry. Page space itself never rotates.
    */
   displayRotation?: PageRotation;
   /**
-   * The page's zoom RELATIVE to its 100% baseline at the event — the other
+   * Screen pixels per page unit at the event: the page's view scale. A
+   * setting in screen pixels (`snap.alignmentThreshold`) is converted by it,
+   * so snapping feels the same at every zoom. Absent → 1.
+   */
+  scale?: number;
+  /**
+   * The page's zoom relative to its 100% baseline at the event — the other
    * half of the {@link ViewEnv} pair with `displayRotation` (dimensionless,
-   * `transform.zoom`; NOT the px-per-point scale the caller uses for its
+   * `transform.zoom`; not the px-per-point scale the caller uses for its
    * CSS-px chrome conversion). Absent → 1 (headless callers; screen-anchored
    * bodies then hit-test at rect size).
    */
   zoom?: number;
   /**
-   * Counter-rotate the created annotation so it reads upright at
-   * `displayRotation` — the authoring TOOL's `upright` policy, resolved by the
-   * caller (the core knows subtypes, not tools). Box kinds only (free-text /
-   * stamp are the ones with a natural reading orientation); vertex kinds and
-   * callouts ignore it.
+   * Lay the created annotation out as the author sees the page at
+   * `displayRotation` — the authoring tool's `upright` policy, resolved by the
+   * caller (the core knows subtypes, not tools). A box counter-rotates so it
+   * reads upright (free text, stamps); a clicked line points the way its
+   * `ClickCreate` says on screen. A dragged line and a callout's leader
+   * follow the pointer and ignore it.
    */
   upright?: boolean;
   /**
-   * Ids invisible to hit-testing and marquee for THIS event — per-event
+   * Ids invisible to hit-testing and marquee for this event — per-event
    * environmental context like `pageBox`. The caller (plugin shell) resolves
    * its engaged Behaviors (form widgets under a fill tool render their own
    * DOM and must not select/move), so the core stays behavior-agnostic.
@@ -601,17 +924,19 @@ interface PointerInput {
   inert?: ReadonlySet<Id>;
 }
 /**
- * What a bare CLICK (a press-release under the drag threshold) creates for a
- * tool: a default-size box with an EXPLICIT anchor (`center` unless stated —
- * free text declares `top-left` so the box hangs where you'll type,
- * display-frame-aware under `upright`), or a default-length line from the
- * point (`angleDeg` 0 = rightward, CW-positive in y-down space). Resolved
- * from the TOOL by the caller and passed on the message — the core knows
- * subtypes, not tools (the `upright` pattern). `false` suppresses a kind's
- * own click fallback (free text always click-creates by default).
- * Anchoring is policy DATA, never inferred from the kind — the same policy
- * drives annotation commits, footprint ghosts, and form-field placement
- * (see `resolveClickPlacement`).
+ * What a bare click (a press-release under the drag threshold) creates for a
+ * tool, in PDF points:
+ *   - a box, `width` × `height`, whose `anchor` sits on the click: its middle
+ *     (`center`, the default) or its top-left corner (`top-left`: free text
+ *     hangs where you'll type);
+ *   - a line, `length` long, pointing `rotation` degrees clockwise from
+ *     rightward, whose `anchor` sits on the click: its middle (`center`, the
+ *     default), its start, or its end (an arrow's tip).
+ * Under an `upright` tool the anchor, the box's sides and the line's
+ * direction are as the person sees the turned page. Resolved from the tool
+ * by the caller and passed on the message: the core knows kinds, not tools.
+ * The same policy drives the commit, the tool's ghost and a form field's
+ * placement (see `resolveClickPlacement`).
  */
 type ClickCreate = {
   width: number;
@@ -619,20 +944,40 @@ type ClickCreate = {
   anchor?: 'center' | 'top-left';
 } | {
   length: number;
-  angleDeg?: number;
+  rotation?: number;
+  anchor?: 'center' | 'start' | 'end';
 };
-type Msg = {
-  t: 'editPointer';
+/**
+ * Where a create gesture puts what it makes, on the page and slid inside it:
+ * a box and the turn an `upright` tool gives it (degrees clockwise, 0 for
+ * none), or a segment from `a` to `b`. A click's comes from the tool's
+ * {@link ClickCreate}, a drag's from the dragged points. It says nothing of
+ * what is drawn there: each shape family turns it into its shape
+ * (`ShapeFamily.placed`), and a form field takes the box as its bounds.
+ */
+type Placement = {
+  kind: 'box';
+  rect: Rect;
+  rot: number;
+} | {
+  kind: 'segment';
+  a: Point$1;
+  b: Point$1;
+};
+type Message = {
+  type: 'editPointer';
   phase: 'down' | 'move' | 'up';
   in: PointerInput;
 } | {
-  t: 'marqueePointer';
+  type: 'marqueePointer';
   phase: 'down' | 'move' | 'up';
   in: PointerInput;
 } | {
-  t: 'createPointer';
+  type: 'createPointer';
+  measure?: MeasurementAppearance;
+  capture?: string;
   phase: 'down' | 'move' | 'up';
-  subtype: Subtype;
+  subtype: KindName;
   /** The authoring tool's `defaults` key (see {@link Draft}). Defaults to `subtype`. */
   preset?: string;
   /** PDF intent carried by an ink authoring preset. */
@@ -648,190 +993,171 @@ type Msg = {
   straightenInk?: InkStraightenOptions;
   in: PointerInput;
 } | {
-  t: 'finishInkDraft';
+  type: 'finishInkDraft';
 } | {
-  t: 'finishCreationDraft';
+  type: 'finishCreationDraft';
 } | {
-  t: 'createCaret';
-  pon: PageObjectNumber;
+  type: 'createCaret';
+  page: PageRef;
   anchor: TextEndAnchor;
   flags?: Partial<AnnotationFlags$1>;
 } | {
-  t: 'createReplaceText';
-  pon: PageObjectNumber;
-  quads: TextQuad$1[];
+  type: 'createReplaceText';
+  page: PageRef;
+  quads: Quad$1[];
   anchor: TextEndAnchor;
   preset?: string;
 } | {
-  t: 'createMarkup';
-  subtype: Subtype;
-  pon: PageObjectNumber;
-  quads: TextQuad$1[];
+  type: 'createMarkup';
+  subtype: KindName;
+  page: PageRef;
+  quads: Quad$1[];
   preset?: string;
   /** The tool's `/F` seed — merged over {@link DRAWN_FLAGS} at commit. */
   flags?: Partial<AnnotationFlags$1>;
 } | {
-  t: 'setMarkupPreview';
-  subtype: Subtype;
-  quadsByPage: Record<number, TextQuad$1[]>;
+  type: 'setMarkupPreview';
+  subtype: KindName;
+  /** Per-page quads keyed by `page.pageObjectNumber` (a lookup, not an address). */
+  quadsByPage: Record<number, Quad$1[]>;
   preset?: string;
 } | {
-  t: 'clearMarkupPreview';
+  type: 'clearMarkupPreview';
 } | {
-  t: 'deselect';
+  type: 'deselect';
   ids?: Id[];
 } |
 /** Pointer entered/left an annotation (topmost hit id, or null). Pure state. */
 {
-  t: 'hover';
+  type: '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';
+} | {
+  type: 'select';
   ids: Id[];
   add?: boolean;
 } | {
-  t: 'setProps';
-  patch: AnnotationPropsPatch;
+  type: 'setFields';
+  patches: Readonly<Record<Id, FieldValues>>;
+} | {
+  type: 'setTextFormat';
+  format: 'bold' | 'italic' | 'underline';
+  on: boolean;
+} | {
+  type: 'setLink';
+  target: PdfLinkTarget | null;
 } | {
-  t: 'setFlags';
+  type: 'setFlags';
   patch: Partial<AnnotationFlags$1>;
   ids?: Id[];
 } | {
-  t: 'setDefaults';
-  subtype: Subtype;
-  patch: AnnotationPropsPatch;
+  type: 'setDefaults';
+  preset: string;
+  patch: FieldValues;
 } | {
-  t: 'setSnap';
+  type: 'setSnap';
   patch: Partial<SnapSettings>;
 } | {
-  t: 'rotate90';
-} | {
-  t: 'resetRotation';
+  type: 'rotateSelection';
+  degrees: 90 | -90;
 } | {
-  t: 'delete';
+  type: 'resetRotation';
 } | {
-  t: 'cancel';
+  type: 'delete';
 } | {
-  t: 'loaded';
-  annots: Annot[];
+  type: 'cancel';
 } |
-/**
- * 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.
- */
+/** These records left the view (deleted elsewhere, a refused create): drop every reference to them. */
 {
-  t: 'hydrated';
-  annots: Annot[];
-  bumpAp?: boolean;
-} | {
-  t: 'created';
-  tempId: Id;
-  id: Id;
-  ref: AnnotationRef;
-} | {
-  t: 'createFailed';
-  tempId: Id;
-} | {
-  t: 'upsert';
-  annots: Annot[];
-  bumpAp?: boolean;
-} | {
-  t: 'bumpAp';
-  ids: Id[];
-} | {
-  t: 'remove';
+  type: 'forget';
   ids: Id[];
 } | {
-  t: 'beginTextEdit';
+  type: 'beginTextEdit';
   id: Id;
 } | {
-  t: 'setText';
+  type: 'setText';
   id: Id;
   text: string;
 } | {
-  t: 'setRichText';
+  type: 'setRichText';
   id: Id;
   doc: RichTextDocumentInput;
 } | {
-  t: 'endTextEdit';
+  type: 'endTextEdit';
 };
 type Effect = {
-  fx: 'create';
+  type: 'captured';
+  tool: string;
+  page: PageRef;
+  geometry: Shape;
+} |
+/** Write a new record: the draft its annotation was read from. Its ref names the object number it takes. */
+{
+  type: 'create';
   id: Id;
-} | {
-  fx: 'createGroup';
-  primary: Id;
-  members: Id[];
+  draft: AnnotationDraft;
 } |
-/** `apChanged` is set (to `true`) ONLY when this patch INVALIDATED a baked
- *  raster — the annotation stayed `baked` (an opaque-body kind) and the edit
- *  resized its `/AP` frame, so the engine's re-bake produces new content (in
- *  practice: a stamp resize). The shell's resolve handler then turns it into
- *  an `upsert` with `bumpAp`. Absent for everything else — moves/rotations
- *  (the blit repositions the same pixels) and any kind that flipped to
- *  `vector` (it renders live; the raster stops mattering) — so those keep the
- *  bare `{ fx, id }` shape and trigger no appearance re-fetch. */
+/** Write one record's change: its entry in the change set's `patches`. `update`
+ *  asks for it for every changed record that has one, except typed text, which
+ *  its `text` effect writes. Whether the engine's re-baked appearance differs
+ *  is the engine's answer, not the core's guess. */
 {
-  fx: 'patch';
+  type: 'patch';
   id: Id;
-  scope: PatchScope;
-  apChanged?: true;
+  patch: AnnotationPatch;
 } |
-/** A `/F`-only engine write for one committed annotation: the shell emits a
- *  flags-only patch (the model already holds the merged flags) and re-syncs
- *  PRESERVING the render source — flags never re-bake an appearance. */
+/** Write the edited text of one free-text record. While the user types, the
+ *  plugin keeps amending one change with the latest text, and sends it after
+ *  a pause. */
 {
-  fx: 'flags';
+  type: 'text';
   id: Id;
 } |
-/** The parent's `link` prop changed on a NON-link kind: reconcile its
- *  attached link children (create / retarget / delete) against the desired
- *  state derived from `link` + the parent's geometry. Declarative — the
- *  shell's reconciler is the only code that spells out child operations.
- *  (Geometry commits don't emit this; the shell re-runs the reconciler on
- *  any `patch` of an annotation that has `linkRefs`.) */
+/** The parent's `link` prop changed on a non-link kind: reconcile its
+ *  attached link children (create / retarget / delete) toward `target`
+ *  (null = remove them). Declarative — the plugin's reconciler is the only
+ *  code that spells out child operations; parents store no link value, the
+ *  committed children are the truth (`linkOf` reads them back). Geometry
+ *  commits don't emit this: the plugin's write of a `patch` brings an
+ *  annotation's attached children along. */
 {
-  fx: 'syncLink';
+  type: 'syncLink';
   id: Id;
   target: PdfLinkTarget | null;
-} | {
-  fx: 'delete';
-  ref: AnnotationRef;
+} |
+/** Delete one record from the document. */
+{
+  type: 'delete';
+  id: Id;
 };
 /** Per-annotation render data — its content geometry + style + live state. */
 interface RenderItem {
   id: Id;
   ref: AnnotationRef | null;
-  subtype: Subtype;
-  geom: Geom;
   /**
-   * The VISUAL box (geometry + stroke + line endings) in content space — the SAME
-   * `geomVisualBounds` that feeds the engine `/Rect`. The renderer paints into THIS
-   * box and does no bounds math of its own, so the on-screen box and the baked
-   * appearance can never drift (the v2 "patch computes the rect" rule).
+   * The annotation it draws, as the user sees it (the record's, a gesture
+   * in progress aside: that is in `geometry` and `box`). Absent for what isn't
+   * made yet: a drawing in progress or a tool's ghost.
+   */
+  annotation?: Annotation;
+  subtype: KindName;
+  geometry: Shape;
+  /**
+   * The box the live drawing is painted into (its family's `drawnBounds`:
+   * geometry, stroke, endings, cloud): a box's or caret's own, before its
+   * turn (`rot`), the page's for the rest. The renderer paints into this box
+   * and does no bounds math of its own.
    */
   box: Rect;
   /**
-   * Content-space box the engine appearance raster occupies (the AP `/Rect`),
+   * Page-space box the engine appearance raster occupies (the AP `/Rect`),
    * with the live move gesture applied — so a baked annotation's bitmap follows
    * a drag. Only meaningful when `source === 'baked'`; absent otherwise.
    */
   apBox?: Rect;
   /**
    * Rotation (deg, CW) to apply to the baked raster as a view transform —
-   * exactly the rotation the engine STRIPPED from it (see `Annot.apRot`).
-   * Live for `opaqueBody` kinds (a stamp spins with the rotate gesture);
+   * exactly the rotation the engine stripped from it (see `ModelAnnotation.apRot`).
+   * Live for `rasterOnly` kinds (a stamp spins with the rotate gesture);
    * absent when the raster already contains its rotation (vertex kinds).
    */
   apRot?: number;
@@ -840,21 +1166,67 @@ interface RenderItem {
    *  text, text/choice widgets). Lets a behavior renderer's focused editor
    *  match the baked appearance's font. */
   text?: TextStyle;
-  source: 'baked' | 'vector' | 'ghost';
+  /**
+   * How it paints: the engine's raster (`baked`), live from its description
+   * (`vector`), or an annotation not made yet, drawn as it will be: a drawing
+   * in progress (`draft`, solid) or the tool's ghost, what a click would
+   * place (`ghost`, see-through by `ghostOpacity`).
+   */
+  source: 'baked' | 'vector' | 'draft' | 'ghost';
+  /**
+   * The version of the record's engine picture (`ModelAnnotation.pictureVersion`):
+   * a picture drawn at another version shows another look of it. Absent for
+   * what isn't made yet.
+   */
+  pictureVersion?: number;
+  /**
+   * A lent record's live drawing, by its lender (`ModelAnnotation.painter`),
+   * upright in `box` (where a gesture has it): `scene(item)` draws it in place
+   * of the kind's own. Made when it's first asked for, not before.
+   */
+  lentScene?: () => readonly SceneNode[];
+  /** How opaque a ghost paints (0–1); a painter lets `--epdf-ghost-opacity` win over it. */
+  ghostOpacity?: number;
   selected: boolean;
   /** The pointer is over this annotation — scene-level hover affordances
    *  (e.g. a redaction mark previews its applied look). */
   hovered?: boolean;
-  /** Redaction label projection (redact kind only) — see {@link Annot.label}. */
+  /** Redaction label projection (redact kind only) — see {@link ModelAnnotation.label}. */
   label?: {
     text: string;
     repeat: boolean;
   };
   /**
-   * Applied rotation (deg, CW), or 0/undefined. For BOX kinds (`rect`/`text`)
-   * `box` is the UNROTATED visual box and the renderer applies this rotation
-   * about its centre (CSS/SVG transform). For VERTEX kinds the geometry is
-   * already rotated, so this is advisory only — the renderer must NOT re-apply it.
+   * The box a painter draws into: `box` before its turn, and that turn,
+   * degrees clockwise about the box's middle. Everything the item draws sits
+   * upright inside it: its scene, a custom look, or its raster (`raster`).
+   * `scale` is how large the page draws the item relative to its own size:
+   * 1, except for a body that keeps its size on screen (`noZoom`), drawn
+   * smaller on the page as people zoom in. Made from `box` and `rot` by the
+   * core; painters read this, not `rot`.
+   */
+  frame: {
+    box: Rect;
+    rotation: number;
+    scale: number;
+  };
+  /**
+   * The engine's raster inside the frame, for an item that has one: its box
+   * relative to the frame's top-left before the frame's turn, and its own turn
+   * about its middle. Made from `apBox` and `apRot`; null without a raster box.
+   */
+  raster: {
+    box: Rect;
+    rotation: number;
+  } | null;
+  /** A note's or file attachment's icon (`/Name`), which its live drawing draws. */
+  icon?: NoteIcon | FileAttachmentIcon;
+  measure?: MeasurementAppearance;
+  /**
+   * Applied rotation (deg, CW), or 0/undefined. For box kinds (`box`/`text-box`)
+   * `box` is the unrotated visual box and the renderer applies this rotation
+   * about its centre (CSS/SVG transform). For vertex kinds the geometry is
+   * already rotated, so this is advisory only — the renderer must not re-apply it.
    */
   rot?: number;
   /**
@@ -864,8 +1236,8 @@ interface RenderItem {
    */
   blend?: Exclude<BlendMode$1, 'normal'>;
 }
-/** The dumb draw vocabulary the framework renderer maps to SVG (content space).
- *  A CLOSED node (rect, ellipse, closed poly) takes the annotation's FILL colour;
+/** The dumb draw vocabulary the framework renderer maps to SVG (page space).
+ *  A closed node (rect, ellipse, closed poly) takes the annotation's fill colour;
  *  an open node (line, open poly — open arrows, butt, slash) is stroke-only. The
  *  stroke colour applies to every node. Closed-ness is the only fill signal. */
 type RenderNode = {
@@ -876,11 +1248,11 @@ type RenderNode = {
   rect: Rect;
 } | {
   kind: 'line';
-  a: Vec;
-  b: Vec;
+  a: Point$1;
+  b: Point$1;
 } | {
   kind: 'poly';
-  points: Vec[];
+  points: Point$1[];
   closed: boolean;
 } | {
   kind: 'path';
@@ -888,7 +1260,7 @@ type RenderNode = {
 };
 /**
  * How to paint one node. The pure core fills this in (per kind/subtype), and a
- * framework renderer applies it verbatim — so ALL appearance logic (markup fill vs
+ * framework renderer applies it verbatim — so all appearance logic (markup fill vs
  * stroke, blend, dash, derived widths) lives once, in the portable core, not in
  * every framework. Omitted `fill`/`stroke` mean none.
  */
@@ -899,16 +1271,17 @@ interface Paint {
   opacity?: number;
   dash?: number[];
   blend?: Exclude<BlendMode$1, 'normal'>;
-  cap?: 'round';
+  lineCap?: 'round';
   join?: 'round';
+  fillRule?: 'evenodd';
 }
 /**
  * A fully-painted draw node: geometry + paint. `scene(item)` returns these and a
- * per-framework painter maps each to ONE element, applying `paint` — the entire
+ * per-framework painter maps each to one element, applying `paint` — the entire
  * surface a new framework renderer must implement. Supersedes the geometry-only
  * `RenderNode` for rendering; `geomScene` stays the internal geometry helper.
  */
-type SceneNode = {
+type SceneNode = ({
   kind: 'rect';
   rect: Rect;
   paint: Paint;
@@ -918,12 +1291,12 @@ type SceneNode = {
   paint: Paint;
 } | {
   kind: 'line';
-  a: Vec;
-  b: Vec;
+  a: Point$1;
+  b: Point$1;
   paint: Paint;
 } | {
   kind: 'poly';
-  points: Vec[];
+  points: Point$1[];
   closed: boolean;
   paint: Paint;
 } | {
@@ -931,17 +1304,49 @@ type SceneNode = {
   d: string;
   paint: Paint;
 } |
-/** Painted (non-interactive) text — `at` is the BASELINE start point in
+/** Painted (non-interactive) text — `at` is the baseline start point in
  *  content units. Editable text (free text) stays a framework element;
  *  this is for pure pixels, e.g. a redaction label preview. */
 {
   kind: 'text';
-  at: Vec;
+  at: Point$1;
   text: string;
   fontSize: number;
   fontFamily?: string;
+  rotation?: number;
+  paint: Paint;
+} |
+/** Painted text placed character by character: `offsets[i]` is how far
+ *  along the baseline from `at` character `i` starts, so each glyph lands
+ *  where the PDF puts it (a form widget's painted text). `rotation` turns
+ *  the run about `at`, degrees clockwise. `program` is the face it draws
+ *  in, for whatever draws it to mount (`fontFamily` names it first). */
+{
+  kind: 'glyphs';
+  at: Point$1;
+  text: string;
+  offsets: number[];
+  fontSize: number;
+  fontFamily: string;
+  fontWeight?: number;
+  fontStyle?: 'normal' | 'italic';
+  rotation?: number;
+  program?: SceneFontProgram;
   paint: Paint;
+}) & {
+  /** Drawn only inside this upright rectangle (a widget's text box). */
+  clip?: Rect;
 };
+/**
+ * A font program a scene's text draws in: mounted under its own family, in
+ * its own weight and style, so the browser takes it as it is.
+ */
+interface SceneFontProgram {
+  readonly family: string;
+  readonly weight: number;
+  readonly style: 'normal' | 'italic';
+  load(): Promise<Uint8Array>;
+}
 /** Pure geometry settings for recognising and axis-snapping a freehand stroke. */
 interface InkStraightenOptions {
   /** Maximum `max perpendicular deviation / endpoint distance`. */
@@ -949,39 +1354,39 @@ interface InkStraightenOptions {
   /** Degrees from horizontal/vertical within which the line snaps to that axis. */
   axisSnapDegrees: number;
 }
+/** What a selection handle reshapes: a box's corner or side, or one point of a line or a polygon. */
+type HandleRole = 'corner' | 'side' | 'point';
 type ChromeNode = {
   kind: 'outline';
   rect: Rect;
 } | {
   kind: 'obb';
-  corners: [Vec, Vec, Vec, Vec];
+  corners: [Point$1, Point$1, Point$1, Point$1];
   angle: number;
 } | {
   kind: 'handle';
-  at: Vec;
+  at: Point$1;
   cursor: Cursor;
   rot?: number;
+  role: HandleRole;
+  active: boolean;
 } | {
   kind: 'rotate-knob';
-  at: Vec;
-  from: Vec;
+  at: Point$1;
+  from: Point$1;
 } | {
   kind: 'guide';
   axis: 'x' | 'y';
   at: number;
   lo: number;
   hi: number;
-} | {
-  kind: 'angle-chip';
-  at: Vec;
-  angle: number;
 } | {
   kind: 'rotate-guides';
-  center: Vec;
+  center: Point$1;
   angle: number;
   lines: Array<{
-    a: Vec;
-    b: Vec;
+    a: Point$1;
+    b: Point$1;
     role: 'axis' | 'indicator';
   }>;
 } | {
@@ -989,6 +1394,79 @@ type ChromeNode = {
   rect: Rect;
 };
 //#endregion
+//#region src/update/session.d.ts
+declare const initialSession: Session;
+/** A tool's defaults, by its preset: the engine fields its creates state. */
+declare const defaultsFor: (model: Model, preset: string) => FieldValues;
+/**
+ * What a create from a tool starts from, before it has a shape: the tool's
+ * defaults (by its preset) over the engine's for its `kind`, read as an
+ * annotation. A ghost is drawn with its style (`styleOf`).
+ */
+declare const toolAnnotation: (model: Model, kind: string, preset?: string) => Annotation;
+//#endregion
+//#region src/update/edit.d.ts
+/**
+ * The live rotation of a rotate draft, snapping applied — the one angle rule
+ * shared by the preview (`effGeom`), the commit (`editUp`) and the angle chip,
+ * so they can never disagree. The selection's absolute angle (a single member's
+ * `rot` + the raw pointer delta; a group's raw delta from 0) locks onto the
+ * configured angles within the threshold; `free` (shift held) bypasses.
+ * `delta` is what `geomRotateAbout` applies; `angle` is what the chip shows.
+ */
+declare function rotateDraftDelta(model: Model, draft: Extract<Draft, {
+  kind: 'rotate';
+}>): {
+  delta: number;
+  angle: number;
+  snapped: boolean;
+};
+//#endregion
+//#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). */
+declare const DRAWN_FLAGS: AnnotationFlags;
+/** All ten flags, for iteration/equality — kept in the primitives' order. */
+declare const FLAG_KEYS: ReadonlyArray<keyof AnnotationFlags>;
+declare const flagsEqual: (left: AnnotationFlags, right: AnnotationFlags) => boolean;
+/** Merge a partial write over the current flags. */
+declare const mergeFlags: (base: AnnotationFlags, patch: Partial<AnnotationFlags>) => AnnotationFlags;
+/**
+ * On-screen visibility. `hidden` beats everything; `noView` hides unless
+ * `toggleNoView` and the annotation is engaged — the spec says hover/selection,
+ * and v1 uses selection (the model tracks no hover).
+ */
+declare const viewable: (flags: AnnotationFlags, engaged?: boolean) => boolean;
+/** Any pointer interaction (click-to-select, hover). ReadOnly kills it. */
+declare const interactive: (flags: AnnotationFlags) => boolean;
+/** The part of a ModelAnnotation these predicates read. */
+interface FlagBearer {
+  /** The record's annotation: its kind and `/F` flags are read off it. */
+  annotation: Annotation;
+  /** 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: (record: FlagBearer) => boolean;
+/**
+ * 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: (record: 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: (record: FlagBearer) => boolean;
+/** `/Contents` text edits — the contents counterpart of `locked`. */
+declare const annotContentsEditable: (record: FlagBearer) => boolean;
+//#endregion
 //#region src/anchor.d.ts
 /** Which display factors this annotation is exempt from: `zoom` =
  *  screen-constant size, `upright` = screen-constant orientation. */
@@ -997,46 +1475,46 @@ interface AnchorMode {
   upright: boolean;
 }
 /**
- * The anchor behaviors of one annotation: its `/F` flags OR'd with the kind's
+ * The anchor behaviors of one annotation: its `/F` flags or'd with the kind's
  * statics — the spec's "Text (note) annotations behave as if NoZoom and
- * NoRotate are ALWAYS set", expressed as kind caps. Null when not anchored.
+ * NoRotate are always set", expressed as kind caps. Null when not anchored.
  */
-declare function anchorModeOf(a: FlagBearer): AnchorMode | null;
-/** The fixed page point: the geometry's bounds top-left in content space
- *  (y-down) — which IS the spec's "upper-left corner of the annotation
+declare function anchorModeOf(record: FlagBearer): AnchorMode | null;
+/** The fixed page point: the geometry's bounds top-left in page space
+ *  (y-down) — which is the spec's "upper-left corner of the annotation
  *  rectangle", since `/Rect` is emitted from these bounds. */
-declare const anchorOf: (g: Geom) => Vec;
+declare const anchorOf: (geometry: Shape) => Point;
 /**
- * THE effective content-space geometry of a screen-anchored body at `view`:
+ * The effective page-space geometry of a screen-anchored body at `view`:
  * the stored geometry scaled by `1/max(zoom, 1)` about the anchor (`zoom`
  * exemption, Adobe-clamped) and counter-rotated by `-rotation` about it
  * (`upright`), so that after the page's own display transform the body reads
  * at its 100%-zoom size and its authored tilt, hanging from the fixed anchor.
- * Returns `g` unchanged when there is nothing to do — callers apply it
+ * Returns `geometry` unchanged when there is nothing to do — callers apply it
  * unconditionally.
  */
-declare function anchoredGeom(g: Geom, mode: AnchorMode | null, view: ViewEnv | undefined): Geom;
+declare function anchoredGeom(geometry: Shape, mode: AnchorMode | null, view: ViewEnv | undefined): Shape;
 /**
- * The exact inverse of {@link anchoredGeom} for a VIEW-space geometry a
- * gesture produced: the stored geometry whose OWN projection is `target`.
+ * The exact inverse of {@link anchoredGeom} for a view-space geometry a
+ * gesture produced: the stored geometry whose own projection is `target`.
  *
  * Solving `anchoredGeom(stored) = target` where the projection anchors at
  * `stored`'s (unknown) bounds top-left `a` gives a closed form: map `target`
  * through the pure linear part (scale `s` + rotate `r` about the origin),
  * then translate so the result's bounds top-left `b` lands where the
  * projection needs it — at `a = R(-r)·b / s`, the unique fixed point. This is
- * what makes a released gesture commit EXACTLY what its preview showed.
+ * what makes a released gesture commit exactly what its preview showed.
  */
-declare function unanchoredGeom(target: Geom, mode: AnchorMode | null, view: ViewEnv | undefined): Geom;
+declare function unanchoredGeom(target: Shape, mode: AnchorMode | null, view: ViewEnv | undefined): Shape;
 /** Stroke width in the projected (view) space: a `noZoom` body's line weight
- *  scales with its geometry so it stays screen-constant — through the SAME
+ *  scales with its geometry so it stays screen-constant — through the same
  *  factors (incl. the ≤100% clamp) the geometry projects with. */
 declare const anchoredStrokeWidth: (width: number, mode: AnchorMode | null, view: ViewEnv | undefined) => number;
 /**
  * The similarity image of an axis-aligned box (a baked raster's AP `/Rect`)
  * under the anchor projection, as the blit vocabulary expects it: an
- * UNROTATED box (the projected centre + scaled size) plus the rotation to
- * re-apply about its centre. `anchor` is the OWNING GEOMETRY's anchor — the
+ * unrotated box (the projected centre + scaled size) plus the rotation to
+ * re-apply about its centre. `anchor` is the owning geometry's anchor — the
  * raster rides its annotation's projection, it doesn't anchor itself. Null
  * when the projection is the identity.
  */
@@ -1045,7 +1523,7 @@ declare function anchoredBox(box: {
   y: number;
   width: number;
   height: number;
-}, anchor: Vec, mode: AnchorMode | null, view: ViewEnv | undefined): {
+}, anchor: Point, mode: AnchorMode | null, view: ViewEnv | undefined): {
   box: {
     x: number;
     y: number;
@@ -1055,75 +1533,84 @@ declare function anchoredBox(box: {
   rot: number;
 } | null;
 //#endregion
-//#region src/update.d.ts
-/** The click ↔ drag threshold (content units): a press-release whose width AND
- *  height both stay under it is a CLICK. Exported so every gesture owner (the
- *  draw handler, the form plugin's place handler) shares ONE definition. */
-declare const MIN_DRAG = 3;
-declare const initialStyle: Style;
+//#region src/update/marquee.d.ts
+/**
+ * What a box on `page` selects: every annotation it touches
+ * ({@link annotsInBox}), and the rest of the group of each. The marquee and
+ * the capability's `selectInRect` both select this.
+ */
+declare function selectionInBox(model: Model, page: PageRef, box: Rect, inert?: ReadonlySet<Id>, view?: ViewEnv): Id[];
+//#endregion
+//#region src/update/index.d.ts
+/** The model before any record or gesture: an empty view over the initial session. */
 declare const initialModel: Model;
 /**
- * Resolve a tool's effective defaults as a FULL flat props bag: the base `style`
- * + the font/endings base, with the per-tool override layered on top. This is
- * what a defaults-editing UI reads, and what creation projects `style`/`text`
- * from (`styleFromProps` / `textStyleFromProps`).
+ * Run one message. The session is returned whole; the records are returned
+ * as the difference the message made, so the caller decides where they live.
  */
-declare function defaultsFor(m: Model, subtype: Subtype): AnnotationProps;
+declare function update(model: Model, message: Message): UpdateResult;
 /**
- * The live rotation of a rotate draft, snapping applied — the ONE angle rule
- * shared by the preview (`effGeom`), the commit (`editUp`) and the angle chip,
- * so they can never disagree. The selection's ABSOLUTE angle (a single member's
- * `rot` + the raw pointer delta; a group's raw delta from 0) locks onto the
- * configured angles within the threshold; `free` (shift held) bypasses.
- * `delta` is what `geomRotateAbout` applies; `angle` is what the chip shows.
+ * The most records `message` can create: how many object numbers the session
+ * must hold before it runs (`Session.objectNumbers`). A pointer press or
+ * release of a creating tool can finish a drawing; a move never does.
  */
-declare function rotateDraftDelta(m: Model, d: Extract<Draft, {
-  g: 'rotate';
-}>): {
-  delta: number;
-  angle: number;
-  snapped: boolean;
-};
-declare function update(m: Model, msg: Msg): [Model, Effect[]];
+declare function newRecordsAtMost(message: Message): number;
+/** True when every session field is the same value: a message that changed nothing. */
+declare const sameSession: (left: Session, right: Session) => boolean;
+/** The change set of a message that changed no record. */
+declare const EMPTY_CHANGE: ChangeSet;
 //#endregion
 //#region src/placement.d.ts
-/** A resolved click placement: what the click will occupy, page-clamped. */
-type ClickPlacement = {
-  kind: 'box';
-  rect: Rect;
-  /** Upright counter-rotation captured for the commit (deg CW; 0 = none). */
-  rot: number;
-} | {
-  kind: 'segment';
-  a: Vec;
-  b: Vec;
-};
+/** The click ↔ drag threshold (content units): a press-release that stays
+ *  under it is a click. Every gesture owner (the draw handler, the form
+ *  plugin's place handler) shares this one definition. */
+declare const MIN_DRAG = 3;
+/** What a create gesture lays: a box (shapes, text boxes, form fields) or a segment (lines). */
+type GestureForm = 'box' | 'segment';
+/** The page a placement is made on, and how the person sees it. */
+interface PlacementFrame {
+  /** The page's content box: a placement slides inside it. */
+  pageBox?: Rect;
+  /** Lay it out as the person sees the page: the tool's `upright`. */
+  upright?: boolean;
+  /** How far the page shows turned (document /Rotate + view rotation, degrees clockwise). */
+  displayRotation?: PageRotation;
+}
 /** Slide a rect (as a unit) to sit inside `box`; pins at the origin edge when
  *  it doesn't fit. Placements are page-bound; the pointer isn't. */
-declare const clampRectToBox: (r: Rect, box: Rect | undefined) => Rect;
+declare const clampRectToBox: (rect: Rect, box: Rect | undefined) => Rect;
+/** Whether a gesture from `from` to `to` is a drag: a segment once it is
+ *  `MIN_DRAG` long, a box once either side is. */
+declare function isDrag(form: GestureForm, from: Point, to: Point): boolean;
 /**
- * Resolve a click-create POLICY at a content point. `anchor` defaults to
- * `center`; under `upright` a box counter-rotates against the page's display
- * rotation exactly as the drag commit would (centre-anchored boxes transpose
- * about their centre, top-left boxes anchor in the DISPLAY frame).
+ * Where a create gesture from `from` to `to` puts what it makes: the dragged
+ * box or segment once it is a drag, else the tool's click default at `from`
+ * (`null` when a click makes nothing). A drag stays on the page: its points
+ * pin to the edge. An upright drag keeps the region the author dragged: under
+ * a quarter turn the box before its turn is the dragged one with its sides
+ * swapped about its middle, so the turn lands it back on that region.
  */
-declare function resolveClickPlacement(point: Vec, policy: ClickCreate, opts?: {
-  pageBox?: Rect;
-  upright?: boolean;
-  displayRotation?: PageRotation;
-}): ClickPlacement;
+declare function gesturePlacement(form: GestureForm, from: Point, to: Point, clickCreate: ClickCreate | false | undefined, frame?: PlacementFrame): Placement | null;
+/**
+ * Where a bare click at `point` puts what the tool makes (see
+ * {@link ClickCreate}), slid inside the page. Under `upright` it is laid out
+ * as the person sees the page: a line's direction and a box's top-left corner
+ * are the screen's, and a box turns to read upright, showing `width` ×
+ * `height` as configured.
+ */
+declare function resolveClickPlacement(point: Point, policy: ClickCreate, frame?: PlacementFrame): Placement;
 /**
- * ANNOTATION-ONLY: convert a placement into the `Geom` the commit stores and
- * the ghost paints, for a routing kind. This is where annotation VISUAL
- * semantics live — ellipse for circles, the cloudy outer-box via
- * `shapeRectFor`. Forms never call this; a field box is the placement rect
- * itself. Null for kinds a click cannot author.
+ * What a create from a tool makes at `placement`: its kind's shape there, as
+ * the kind's shape family lays it (`ShapeFamily.placed`), or `null` when the
+ * kind can't be made that way (a line from a box). `annotation` is what the
+ * tool creates before it has a shape (`toolAnnotation`): its kind, and what
+ * the shape takes from it (a line's endings, a circle's roundness).
  */
-declare function clickCreateGeom(subtype: Subtype, placement: ClickPlacement, def: AnnotationProps): Geom | null;
+declare function placedShape(annotation: Annotation, placement: Placement): Shape | null;
 //#endregion
 //#region src/snap.d.ts
 interface SnapResult {
-  delta: Vec;
+  delta: Point;
   guides: Guide[];
 }
 /**
@@ -1132,10 +1619,20 @@ interface SnapResult {
  * closest in-threshold pair per axis as an adjustment. Targets are the page box
  * (edges + center) and every non-moving annotation on the page.
  */
-declare function computeMoveSnap(m: Model, ids: Id[], pon: number, raw: Vec, threshold: number, pageBox: Rect | undefined): SnapResult;
+declare function computeMoveSnap(model: Model, ids: Id[], page: PageRef, raw: Point, threshold: number, pageBox: Rect | undefined): SnapResult;
 //#endregion
 //#region src/view.d.ts
-declare function pageItems(m: Model, pon: number, view?: ViewEnv): RenderItem[];
+/** A note's or file attachment's icon: what its live drawing draws. */
+declare const iconOf: (annotation: Annotation) => Pick<RenderItem, "icon">;
+/**
+ * How an annotation not made yet paints, drawn as it will be once made: a
+ * drawing in progress (`draft`) or the tool's ghost (`ghost`, what a click
+ * would place). `annotation` is what the tool creates, its defaults and
+ * flags; `shape` is where it goes, as the made one will store it, so a
+ * screen-anchored icon shows at its size on screen, as a made one does.
+ */
+declare function unmadeItem(id: Id, annotation: Annotation, shape: Shape, source: 'draft' | 'ghost', view?: ViewEnv, measure?: MeasurementAppearance): RenderItem;
+declare function pageItems(model: Model, page: PageRef, view?: ViewEnv): RenderItem[];
 /** One free-text box, geometry only (the live move/resize gesture applied), with
  *  its edit flag. The framework renders an editable element here; the plugin
  *  layers the DTO-derived text style on top. */
@@ -1143,95 +1640,125 @@ interface TextBox {
   id: Id;
   box: Rect;
   editing: boolean;
-  /** Applied rotation (deg, CW). `box` is the UNROTATED text box; the framework
+  /** 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;
 }
 /** The free-text boxes on a page — the text counterpart of `pageItems`. */
-declare function textBoxes(m: Model, pon: number, view?: ViewEnv): TextBox[];
+declare function textBoxes(model: Model, page: PageRef, view?: ViewEnv): TextBox[];
 /** The currently selected annotations as render items (live gesture applied) —
  *  cross-page, for selection-aware toolbars (style + line-ending editing). */
-declare function selectedItems(m: Model, view?: ViewEnv): RenderItem[];
+declare function selectedItems(model: Model, view?: ViewEnv): RenderItem[];
 /**
- * The rotate knob for the current selection on `pon` — the SAME knob `chrome`
+ * The rotate knob for the current selection on `page` — the same knob `chrome`
  * draws — or null when the selection has none (non-rotatable single, or a group
  * whose caps aren't rotatable). A single shape's knob hangs off its OBB top edge;
- * a group's off the union box. With `pageBox` the knob is placed PAGE-BOUND
+ * a group's off the union box. With `pageBox` the knob is placed page-bound
  * (`placeRotateKnob`: flip below / clamp inside) — off-page it would be visible
  * but unreachable, since pointer dispatch resolves pages by containment. Shared
  * by `chrome` (to draw) and `selectionAnchor` (to push the menu clear of it), so
  * the two can never disagree on where it is.
  *
- * The placement DECISION is made at rest; a gesture never re-decides — it RIDES.
+ * The placement decision is made at rest; a gesture never re-decides — it rides.
  * During a live rotate the knob starts exactly where it was grabbed (the rest
- * placement on the COMMITTED geometry) and turns rigidly about the pivot by the
+ * placement on the committed geometry) and turns rigidly about the pivot by the
  * same snapped delta the shape uses; the policy re-evaluates only on release.
  * Re-deciding per frame would jump at grab and side-switch mid-spin.
  */
-declare function selectionKnob(m: Model, pon: number, pageBox?: Rect, knobOffset?: number, view?: ViewEnv): {
-  at: Vec;
-  from: Vec;
+declare function selectionKnob(model: Model, page: PageRef, pageBox?: Rect, knobOffset?: number, view?: ViewEnv): {
+  at: Point;
+  from: Point;
 } | null;
-declare function chrome(m: Model, pon: number, pageBox?: Rect, knobOffset?: number, view?: ViewEnv): ChromeNode[];
-/** The content-space union of the selectable selected items on `pon`, or null if
- *  the page holds none. This is the SAME box the chrome outline draws, so a
+declare function chrome(model: Model, page: PageRef, pageBox?: Rect, knobOffset?: number, view?: ViewEnv): ChromeNode[];
+/** The page-space union of the selectable selected items on `page`, or null if
+ *  the page holds none. This is the same box the chrome outline draws, so a
  *  floating menu sits exactly on the selection. */
-declare function selectionBoundsOnPage(m: Model, pon: number, view?: ViewEnv): Rect | null;
-/** The anchor for a selection-aware floating menu: the PRIMARY page (the first
+declare function selectionBoundsOnPage(model: Model, page: PageRef, view?: ViewEnv): Rect | null;
+/** The anchor for a selection-aware floating menu: the primary page (the first
  *  selectable selected id) + the union box of the selection on that page (content
  *  space). Null when nothing selectable is selected. A cross-page selection
  *  anchors to its primary page, so there is exactly one menu. `pageBoxOf` is a
  *  lookup (the anchor resolves its own page) feeding the page-bound knob
- *  placement — the menu then dodges the knob where it ACTUALLY sits. */
-declare function selectionAnchor(m: Model, pageBoxOf?: (pon: number) => Rect | undefined, knobOffsetOf?: (pon: number) => number | undefined, viewOf?: (pon: number) => ViewEnv | undefined): {
-  pon: number;
+ *  placement — the menu then dodges the knob where it actually sits. */
+declare function selectionAnchor(model: Model, pageBoxOf?: (page: PageRef) => Rect | undefined, knobOffsetOf?: (page: PageRef) => number | undefined, viewOf?: (page: PageRef) => ViewEnv | undefined): {
+  page: PageRef;
   bounds: Rect;
-  knob?: Vec;
+  knob?: Point;
 } | null;
 /** Anchor for controls that finish/cancel an active multi-click creation draft.
  *  It is rect-based like selectionAnchor, using the committed vertices only so
  *  the menu remains stable while the hover preview follows the pointer. */
-declare function creationDraftAnchor(m: Model): CreationDraftAnchor | null;
+/**
+ * The rotation in progress, for the badge that follows the pointer: `null`
+ * when nothing is being turned. The badge is a screen overlay, so it stays
+ * upright however the page is shown.
+ */
+declare function rotationAnchor(model: Model): RotationAnchor | null;
+declare function creationDraftAnchor(model: Model): CreationDraftAnchor | null;
+/**
+ * Where UI attaches to one annotation: its page and the box around what it
+ * shows, a gesture in progress included, so an overlay follows a drag. `null`
+ * for a record the model doesn't have.
+ */
+declare function annotationAnchor(model: Model, id: Id, view?: ViewEnv): {
+  page: PageRef;
+  bounds: Rect;
+} | null;
 //#endregion
 //#region src/hit.d.ts
 type Target = {
-  t: 'handle';
+  kind: 'handle';
   id: Id;
   handle: string;
   cursor: Cursor;
 } | {
-  t: 'rotate';
+  kind: 'rotate';
   ids: Id[];
-  pivot: Vec;
+  pivot: Point;
 } | {
-  t: 'group-handle';
+  kind: 'group-handle';
   ids: Id[];
   handle: string;
   cursor: Cursor;
   box: Rect;
 } | {
-  t: 'annot';
+  kind: 'annot';
   id: Id;
 } | {
-  t: 'empty';
+  kind: 'empty';
 };
 /** Can this annotation be clicked to select? (`/F` interaction flags override
- *  all caps — hidden/noView/readOnly are inert; LOCKED stays selectable, it
+ *  all caps — hidden/noView/readOnly are inert; locked stays selectable, it
  *  just won't transform.) */
-declare const isSelectable: (m: Model, id: Id) => boolean;
-/** Can this annotation be dragged by its body to move? (`locked` freezes it.) */
-declare const canMove: (m: Model, id: Id) => boolean;
+declare const isSelectable: (model: Model, id: Id) => boolean;
+/** Can this annotation be dragged by its body to move? (`locked` and the
+ *  session's `editable` rule freeze it.) */
+declare const canMove: (model: Model, id: Id) => boolean;
+/**
+ * What an annotation paints where the pointer meets it (`painted.ts`): its
+ * shape's pieces, projected as a screen-anchored body shows at `view`, and a
+ * measurement's caption, dimension line and leaders. A click and the marquee
+ * both read this.
+ */
+declare function paintedOf(record: ModelAnnotation, view?: ViewEnv): readonly PaintedPiece[];
 /**
- * What's under the content point.
+ * Is `point` on a text box's own box, where its text is? Not on a callout's
+ * line, and not in the empty rest of its frame. `margin` reaches the resize
+ * handles on its border. The box is tested where the page shows it, as a
+ * click tests it.
+ */
+declare function isOnTextBox(record: ModelAnnotation, point: Point, margin: number, view?: ViewEnv): boolean;
+/**
+ * What's under the page point.
  *  1. a resize/vertex handle of the single selection,
- *  2. an editable annotation body — a SELECTED one anywhere in its bounds (so you
- *     can drag to move it), an UNSELECTED one only on its stroke/fill (margin-aware,
+ *  2. an editable annotation body — a selected one anywhere in its bounds (so you
+ *     can drag to move it), an unselected one only on its stroke/fill (margin-aware,
  *     so an unfilled circle is grabbed only on its outline),
  *  3. else empty.
  */
-declare function hitTest(m: Model, pon: number, p: Vec, geom: ChromeGeom, strokeMargin: number, pageBox?: Rect, inert?: ReadonlySet<Id>, view?: ViewEnv): Target;
+declare function hitTest(model: Model, page: PageRef, point: Point, chromeGeometry: ChromeGeometry, strokeMargin: number, pageBox?: Rect, inert?: ReadonlySet<Id>, view?: ViewEnv): Target;
 /** 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;
+declare function cursorAt(model: Model, page: PageRef, point: Point, geometry: ChromeGeometry, strokeMargin: number, pageBox?: Rect, inert?: ReadonlySet<Id>, view?: ViewEnv): Cursor | null;
 //#endregion
 //#region src/richtext.d.ts
 type RichTextStyleDelta = Partial<RichTextRunStyle>;
@@ -1245,7 +1772,7 @@ 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;
+declare function sameStyleDelta(left: RichTextStyleDelta | undefined, right: 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
@@ -1296,13 +1823,38 @@ declare function plainTextOf(doc: {
 /** 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;
+/** The registered fonts an engine knows (the local engine's `fonts.list()`;
+ *  none on the cloud engine). */
+type FontLookup = () => readonly FontHandle[];
+/** The face a DTO font names: a standard font's family, weight and italic, a
+ *  registered key's identity, else the string itself as a family. */
+declare const faceForFont: (font: string, fonts?: FontLookup) => FaceRequest;
+/** The rich body the `/DA` text style describes (a draft's body before its
+ *  DTO exists; also the fallback for a DTO without `richText`). */
+declare function bodyFromTextStyle(style: TextStyle, fonts?: FontLookup): RichTextBody;
+/** The annotation's rich document: a free text's own, else one made from
+ *  its plain text and how its text is set. */
+declare function richDocOf(annotation: Annotation, fonts?: FontLookup): RichTextDocument;
+//#endregion
+//#region src/font-css.d.ts
+type StandardFamily = (typeof STANDARD_FACES)[keyof typeof STANDARD_FACES]['family'];
+/** Web stacks with the standard families' metrics. */
+declare const STANDARD_FONT_STACKS: Readonly<Record<StandardFamily, string>>;
+/**
+ * The family `mountWebFont` (`@embedpdf/web`) mounts a registered font's key
+ * under: namespaced, so a page's own family of the same name never stands in
+ * for it.
+ */
+declare const mountedFontFamily: (key: string) => string;
+/** The CSS family list for a DTO font: a standard kebab name or a registered key. */
+declare function cssFontFamilyForFont(font: string): string;
 //#endregion
 //#region src/group.d.ts
 /**
  * The transform capabilities of a multi-target (group) selection: a group can
- * move/resize/rotate only if EVERY member's kind allows that group op AND no
- * member is locked. This is the SINGLE resolver every adapter consumes (v2
- * duplicated the `.every(...)` across three framework components). The iso-vs-
+ * move/resize/rotate only if every member's kind allows that group op and no
+ * member is locked or frozen by the session's `editable` rule. This is the single resolver every adapter consumes, so no
+ * framework component re-derives the rule. The iso-vs-
  * aniso resize choice is computed separately, per-gesture, since it depends on
  * the live `rot` of the members, not the static caps.
  */
@@ -1311,135 +1863,162 @@ interface GroupCaps {
   resizable: boolean;
   rotatable: boolean;
 }
-declare function groupCaps(m: Model, ids: Id[]): GroupCaps;
+declare function groupCaps(model: Model, ids: Id[]): GroupCaps;
 /**
  * The key of the group `id` belongs to, or `null` when it is ungrouped. A
- * subordinate's key is its `group` field; a primary's key is its own id (it is
- * the target of at least one member's `group`). An annotation that is neither a
+ * subordinate's key is its `groupOf`; a primary's key is its own id (it is the
+ * target of at least one member's `groupOf`). An annotation that is neither a
  * subordinate nor the target of any subordinate is ungrouped.
  */
-declare function groupKeyOf(m: Model, id: Id): Id | null;
+declare function groupKeyOf(model: Model, id: Id): Id | null;
 /**
  * Every member of the group containing `id` (primary first), or just `[id]`
  * when it is ungrouped. The primary is the annotation whose id is the key; the
- * rest are everything whose `group` equals the key, in `order`.
+ * rest are everything whose `groupOf` equals the key, in `order`.
  */
-declare function groupMembers(m: Model, id: Id): Id[];
+declare function groupMembers(model: 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[];
+declare function expandGroups(model: 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;
+declare function isConversationOnly(record: Pick<ModelAnnotation, 'annotation'>): boolean;
 /**
- * A link CHILD attached to another annotation — a `/Link` grouped
+ * 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 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
+ * 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;
+declare function isAttachedLink(record: Pick<ModelAnnotation, 'annotation'>): boolean;
 /**
- * The ONE page-surface cull: everything that lives in the substrate but is
+ * 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.
+ * and the appearance epoch all filter through this, never the parts.
  */
-declare function isSubstrateOnly(a: Pick<Annot, 'irt' | 'group' | 'subtype' | 'data'>): boolean;
+declare function isSubstrateOnly(record: Pick<ModelAnnotation, 'annotation'>): 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[];
+declare function linkChildrenOf(model: Model, parentId: Id): ModelAnnotation[];
 /** 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;
+declare function linkOf(model: Model, parentId: Id): PdfLinkTarget | null;
+//#endregion
+//#region src/shapes/index.d.ts
+/**
+ * The family that answers for `shape`. Each family works on its own shapes
+ * only; looking it up by the shape's `kind` is what hands it one.
+ */
+declare const familyOf: (shape: Shape) => ShapeFamily;
+/**
+ * The family of a kind whose annotation says which shape it has: `pick`
+ * names the family that reads it, and the shape's own family does the rest.
+ */
+declare function familyChosenBy(pick: (annotation: Annotation) => ShapeFamily): ShapeFamily;
 //#endregion
-//#region src/kinds.d.ts
+//#region src/kinds/define.d.ts
+/** The flags an annotation carries, each a `flag` property of every kind. */
+type FlagKey = 'invisible' | 'hidden' | 'print' | 'noZoom' | 'noRotate' | 'noView' | 'readOnly' | 'locked' | 'toggleNoView' | 'lockedContents';
+/**
+ * One choice of a `choice` property, as a picker shows it: the value it
+ * writes, and its name, `label` in English and `labelKey` to translate it
+ * (`annotation.lineEndings.openArrow`).
+ */
+interface AnnotationOption {
+  readonly value: string;
+  readonly label: string;
+  readonly labelKey: string;
+}
 /**
- * One editable property of a kind, as a UI contract: which {@link AnnotationProps}
- * key, rendered how (the union arm fixes the control + its constraints), labelled
- * what by default. A property sidebar is a `switch (spec.key)` over these — the
- * per-kind lists below are the v2 snippet's hand-rolled `TOOL_PROPERTIES` schema,
- * promoted into the library so every consumer gets it for free.
+ * One property a style panel edits, as a UI contract: which field, edited
+ * with which control, labelled what. A panel switches on `control` (or on
+ * `key`, for a richer editor of its own), reads `values[property.key]` and
+ * writes `{ [property.key]: value }`, so each kind's list is its property
+ * schema, kept in the library so every consumer gets it for free.
  *
- * `label` is a default (English) display name — apps with i18n map `key`s to
- * their own strings and ignore it. Array ORDER is display order.
+ * `key` is the engine's field name, with three exceptions: the border's
+ * `borderStyle` reads and writes `borderStyle`, `dashArray` and
+ * `cloudyIntensity` together; `bold`, `italic` and `underline` are the rich
+ * body's formatting; and `link` is an attached link, not a field of the
+ * annotation.
+ *
+ * `label` is the English name and `labelKey` its translation key: a panel
+ * shows `t(property.labelKey, { fallback: property.label })`, as a command's
+ * label reads. The key names the wording, not the field, since one field is
+ * called different things by different kinds: `color` is
+ * `annotation.style.stroke` on a shape and `annotation.style.outline` on a
+ * redaction mark. A `choice` property's options carry the same pair. Array
+ * order is display order.
  */
-type PropSpec = {
-  key: 'color';
-  label: string;
-} | {
-  key: 'interiorColor';
-  label: string;
-} | {
-  key: 'fontColor';
-  label: string;
-} | {
-  key: 'opacity';
-  label: string;
-  min: number;
-  max: number;
-  step: number;
-} | {
-  key: 'strokeWidth';
-  label: string;
-  min: number;
-  max: number;
-  step: number;
-} | {
-  key: 'fontSize';
-  label: string;
-  min: number;
-  max: number;
-  step: number;
+type AnnotationProperty = {
+  readonly key: 'color' | 'interiorColor' | 'fontColor';
+  readonly control: 'color';
+  readonly label: string;
+  readonly labelKey: string;
+} | {
+  readonly key: 'opacity' | 'strokeWidth' | 'fontSize';
+  readonly control: 'number';
+  readonly label: string;
+  readonly labelKey: string;
+  readonly min: number;
+  readonly max: number;
+  readonly step: number;
 } |
-/** Border style picker; `cloudy` says whether this kind honours a cloudy border. */
+/** The border over `borderStyle`, `dashArray` and `cloudyIntensity`;
+ *  `cloudy` says whether this kind takes a cloudy border. */
 {
-  key: 'border';
-  label: string;
-  cloudy: boolean;
-} | {
-  key: 'lineEndings';
-  label: string;
-} | {
-  key: 'fontFamily';
-  label: string;
-} | {
-  key: 'textAlign';
-  label: string;
+  readonly key: 'borderStyle';
+  readonly control: 'choice';
+  readonly label: string;
+  readonly labelKey: string;
+  readonly options: readonly AnnotationOption[];
+  readonly cloudy: boolean;
 } |
-/** Rich-text formatting toggles (free text): the body's formatting, or —
- *  while the text editor has a range — that range's runs. */
+/** A value from a list: line endings, a font, an alignment, a blend mode, an icon. */
 {
-  key: 'bold';
-  label: string;
-} | {
-  key: 'italic';
-  label: string;
-} | {
-  key: 'underline';
-  label: string;
-} | {
-  key: 'blendMode';
-  label: string;
+  readonly key: 'lineEndings' | 'fontFamily' | 'textAlign' | 'blendMode' | 'icon';
+  readonly control: 'choice';
+  readonly label: string;
+  readonly labelKey: string;
+  readonly options: readonly AnnotationOption[];
+} |
+/** One of the annotation's flags, on or off. */
+{
+  readonly key: FlagKey;
+  readonly control: 'flag';
+  readonly label: string;
+  readonly labelKey: string;
+} |
+/** Free text, such as a redaction's label. */
+{
+  readonly key: 'overlayText';
+  readonly control: 'text';
+  readonly label: string;
+  readonly labelKey: string;
 } |
-/** `/Name` icon picker for icon kinds; `options` are the legal names. */
+/** Bold, italic or underline of a text box: the body's formatting, or,
+ *  while the text editor has a range, that range's runs. */
 {
-  key: 'icon';
-  label: string;
-  options: readonly string[];
+  readonly key: 'bold' | 'italic' | 'underline';
+  readonly control: 'textFormat';
+  readonly label: string;
+  readonly labelKey: string;
+  readonly format: 'bold' | 'italic' | 'underline';
 } |
-/** Link-target editor (URL / page destination). Declared by the link kind
- *  (its own target) and by every kind that may carry an ATTACHED link;
- *  kinds that omit it (widgets, caret, redact…) simply cannot be links —
- *  `applyProps` drops the key and menus never show the control. */
+/** Where it links to (a website or a page). Declared by the link kind (its
+ *  own target) and by every kind that may carry an attached link; kinds
+ *  that omit it (widgets, caret, redaction…) can't be links. */
 {
-  key: 'link';
-  label: string;
+  readonly key: 'link';
+  readonly control: 'link';
+  readonly label: string;
+  readonly labelKey: string;
 };
 /** Orthogonal capability flags. Static data — the annotation's `/F` flags are
  *  the runtime overrides (a locked annotation is never transformable, a hidden
@@ -1455,13 +2034,13 @@ interface KindCaps {
   vertexEditable: boolean;
   /** Can be rotated (shapes, free text, lines/polys/ink). */
   rotatable: boolean;
-  /** Can be MOVED as part of a multi-target (group) transform. */
+  /** Can be moved as part of a multi-target (group) transform. */
   groupMovable: boolean;
-  /** Can be uniformly SCALED as part of a multi-target (group) transform — ON
+  /** Can be uniformly scaled as part of a multi-target (group) transform — on
    *  even for vertex kinds that have no single-shape box resize (their handles
-   *  ARE the vertices; in a group they scale fine). */
+   *  are the vertices; in a group they scale fine). */
   groupResizable: boolean;
-  /** Can be ROTATED as part of a multi-target (group) transform. */
+  /** Can be rotated as part of a multi-target (group) transform. */
   groupRotatable: boolean;
   /** Carries editable text content (free text, the comment popup). */
   textEditable: boolean;
@@ -1471,6 +2050,8 @@ interface KindCaps {
   hasPopup: boolean;
   /** Bound to underlying text (markup, caret) — never freely moved/resized. */
   anchored: boolean;
+  /** Paints with the page's text, beneath every other kind (text markup, redaction marks). */
+  paintsBeneath: boolean;
   /** Has an interior fill (`/IC`). */
   hasFill: boolean;
   /** Has line endings (`/LE` — line, polyline). */
@@ -1478,10 +2059,15 @@ interface KindCaps {
   /** Can take a cloudy border effect (`/BE` — shapes). */
   hasCloudy: boolean;
   /** The whole body is visible content, so hit-testing grabs anywhere inside
-   *  the box (stamp images) — NOT just the stroke/fill like outline shapes. */
+   *  the box (stamp images, note icons) — not just the stroke/fill like
+   *  outline shapes. */
   opaqueBody: boolean;
-  /** The `/F` ReadOnly flag is IGNORED for this kind (ISO 32000: widgets — a
-   *  ReadOnly form FIELD must still be movable by a form designer; the
+  /** Its raster is its drawing, drawn where its shape is: the kind draws none
+   *  of it live (a stamp's image, a form widget, a link's border). A lent
+   *  record can still draw live with its lender's painter (`drawsLive`). */
+  rasterOnly: boolean;
+  /** The `/F` ReadOnly flag is ignored for this kind (ISO 32000: widgets — a
+   *  ReadOnly form field must still be movable by a form designer; the
    *  form-filling layer enforces field ReadOnly itself). */
   ignoresReadOnly: boolean;
   /** Behaves as if `/F` NoZoom is always set (screen-constant size — the
@@ -1491,270 +2077,240 @@ interface KindCaps {
    *  rule for Text/note icons). See anchor.ts. */
   noRotate: boolean;
 }
+/** No capability at all: a kind spreads this and turns on what it can do. */
+declare const NO_CAPS: KindCaps;
+/** One annotation kind: what it is, and what a user can do to it. */
 interface AnnotationKind {
-  subtype: Subtype;
-  /** Future: PDF `/IT` intent (free-text vs callout, caret insert vs replace). */
-  intent?: string;
-  variant: Geom['t'];
-  caps: KindCaps;
-  /** The kind's editable properties, in DISPLAY ORDER — the contract a property
-   *  sidebar renders from (see {@link PropSpec}). Empty = nothing to edit. */
-  props: PropSpec[];
+  /** Its name: the PDF subtype, or a widget's field family (`widget-text`…). */
+  readonly name: string;
+  /**
+   * The shape family that reads its shape off the annotation (`shapes/`).
+   * The shape's family then hits, handles, moves and draws it.
+   */
+  readonly family: ShapeFamily;
+  /**
+   * How it is drawn: its colours, stroke and border, read off the annotation
+   * with its kind's fill-ins (`styles.ts`).
+   */
+  readonly style: (annotation: Annotation) => Style;
+  /**
+   * How its text is set, for a kind with text: its font, size, colour and
+   * alignment, read off the annotation (`texts.ts`).
+   */
+  readonly text?: (annotation: Annotation) => TextStyle;
+  /** What a user can do to it. The annotation's `/F` flags override these at runtime (flags.ts). */
+  readonly caps: KindCaps;
+  /**
+   * What a style panel edits, in display order, keyed by the engine's field
+   * names. The flags every kind has are added by `propertiesOf`.
+   */
+  readonly properties: readonly AnnotationProperty[];
 }
-/** The built-in kinds. Shapes resize, lines/polys vertex-edit, markup is anchored
- *  (selectable + recolor/delete, never move/resize). */
-declare const KINDS: Record<string, AnnotationKind>;
-/** The capabilities of a subtype, or the read-only default for unknown kinds. */
-declare const capsFor: (subtype: string) => KindCaps;
-/** A kind's editable properties in display order — empty for unknown kinds.
- *  Stable references, so selectors can compare by identity. */
-declare const propsFor: (subtype: string) => PropSpec[];
+/**
+ * Declares a kind. It returns the kind exactly as written: nothing is
+ * registered and nothing is filled in. `index.ts` lists every kind.
+ */
+declare const defineKind: <const Kind extends AnnotationKind>(kind: Kind) => Kind;
+//#endregion
+//#region src/kinds/index.d.ts
+/** The kinds, by name. */
+declare const KINDS: Readonly<Record<string, AnnotationKind>>;
+/** The kind named `name`; a name no kind has reads as one that is only shown. */
+declare function kindNamed(name: string): AnnotationKind;
 //#endregion
 //#region src/props.d.ts
 /** Base text styling for kinds/tools with no explicit defaults. */
 declare const initialTextStyle: TextStyle;
-/** The `Style` slice of a resolved props bag (the create-time projection). */
-declare const styleFromProps: (p: AnnotationProps) => Style;
-/** The `TextStyle` slice of a resolved props bag (the create-time projection). */
-declare const textStyleFromProps: (p: AnnotationProps) => TextStyle;
+/** Does this kind's property table declare `link` (attachable link)? The link
+ *  kind itself also declares it, but stores its own `/A` instead. */
+declare const kindTakesLink: (kind: AnnotationKind) => boolean;
+/**
+ * Everything a style panel edits for one kind: its own properties, then the
+ * flags every kind has. The same array for a kind on every call.
+ */
+declare function propertiesOf(kind: AnnotationKind): readonly AnnotationProperty[];
 /**
- * Read one property off an annotation — from wherever it lives — or `undefined`
- * when the annotation's kind doesn't carry it (a `fontSize` on a square, endings
- * on a polygon). The read side of `applyProps`.
+ * The ordered properties every given kind has: the schema for a mixed
+ * selection, in the first kind's display order. One kind: its own list
+ * (`propertiesOf`), the same array every time.
  */
-declare function readProp<K extends PropKey>(a: Annot, key: K): AnnotationProps[K] | undefined;
+declare function sharedProperties(kinds: readonly AnnotationKind[]): readonly AnnotationProperty[];
+//#endregion
+//#region src/kinds/fields.d.ts
+/** Every line ending the engine draws. */
+declare const LINE_ENDING_NAMES: readonly ["none", "square", "circle", "diamond", "open-arrow", "closed-arrow", "butt", "r-open-arrow", "r-closed-arrow", "slash"];
+/** The flags every kind has, in the order a panel lists them. */
+declare const FLAG_PROPERTIES: readonly AnnotationProperty[];
+//#endregion
+//#region src/record/defaults.d.ts
+/** The engine subtype a client kind creates: a callout is a free text, a form tool's kind a widget. */
+declare const engineSubtypeOf: (kind: string) => AnnotationSubtype;
 /**
- * Apply a property patch to one annotation, honouring its kind's declared keys.
- * Returns the changed annotation, or `null` when nothing applied (locked /
- * read-only per its `/F` flags, or no declared key in the patch) — so the
- * caller emits no spurious engine write. Flags themselves are NOT props: they
- * write through the `setFlags` message, which is deliberately not gated here
- * (unlocking must work on a locked annotation).
+ * A tool's `defaults` over the engine's defaults for `kind`: what a create
+ * from the tool starts from. A form tool's reads as a widget of its field
+ * family, so it reads as the tool's own kind (a radio tool's is round).
  */
-declare function applyProps(a: Annot, patch: AnnotationPropsPatch): Annot | null;
+declare function readOfDefaults(kind: string, defaults: FieldValues): Annotation;
 /**
- * The ordered property specs EVERY given kind declares — the schema for a mixed
- * selection, in the FIRST kind's display order. One kind → its own list, verbatim.
+ * A form tool's defaults as the engine's widget appearance for `doc.forms`
+ * authoring: the widget's style fields among them, as they are. Absent fields
+ * stay absent (the engine writes nothing for them).
  */
-declare function sharedProps(subtypes: readonly string[]): PropSpec[];
+declare function widgetAppearanceOf(defaults: FieldValues): WidgetAppearance;
 //#endregion
 //#region src/geometry.d.ts
-type RectHandle = 'nw' | 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w';
-declare const RECT_HANDLES: RectHandle[];
-/** The resize cursor for a handle on a box tilted by `rot` deg: rotate the
- *  handle's compass direction with the box and pick the nearest 45° sector.
- *  At `rot = 0` this reproduces {@link RECT_CURSOR} exactly. */
-declare const rotatedHandleCursor: (h: RectHandle, rot: number) => Cursor;
-declare const rectFromPoints: (a: Vec, b: Vec) => Rect;
-declare function unionRect(pts: Vec[]): Rect;
 /** How far (content units) the rotate knob hangs off the top edge of the box. */
 declare const ROTATE_KNOB_OFFSET = 24;
 /** Fallback chrome geometry (content units) when the caller supplies none —
  *  the pre-settings behavior, so bare-core callers and tests stay stable. */
-declare const DEFAULT_CHROME_GEOM: {
+declare const DEFAULT_CHROME_GEOMETRY: {
   readonly handleTol: 6;
   readonly knobTol: 6;
   readonly knobOffset: 24;
 };
-/** 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
- *  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`
- * centre; a vertex shape about the CENTROID of its points (the mean). Rotating a
- * point set about its centroid leaves the centroid fixed, so the advisory `rot`
- * stays cleanly additive across gestures and reset is exact.
- */
-declare function centroidOf(g: Geom): Vec;
+/** A geom's applied rotation (deg), or 0 for text markup. A caret's turn is
+ *  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(geometry: Shape): number;
+/**
+ * Where a turn of a single shape pivots, as the engine turns it: a box about
+ * its own `rect` centre; a line, polygon, polyline or ink about the middle of
+ * the box around its points upright. A turn then changes only the angle, never
+ * where the upright points are, and a caption or an arrowhead never moves the
+ * pivot.
+ */
+declare const turnPivotOf: (geometry: Shape) => Point;
 /** 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
+ *  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`.
- *  - BOX (`rect`/plain `text`): orbit the box centre about the pivot (a rigid
- *    translation of the unrotated `rect`) and add the angle to `rot`. When the
- *    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).
- * 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. */
-declare function rotatedAabb(rect: Rect, deg: number): Rect;
+declare const isRotatableGeom: (geometry: Shape) => boolean;
+/**
+ * Rotate a geom by `deltaDeg` (clockwise) about `pivot`: a box's middle
+ * orbits the pivot and its turn grows, and so does a points shape's. A shape
+ * without a rotate verb comes back unchanged: quads, a callout, and the
+ * caret (oriented, but it follows its text; `geomResetRotation` still clears
+ * its turn).
+ */
+declare function geomRotateAbout(geometry: Shape, pivot: Point, deltaDeg: number): Shape;
 /**
  * The counter-rotation (CW content degrees) that makes an annotation read
  * upright at `displayRotation`: on screen the two compose to 0.
  */
 declare const uprightRotation: (displayRotation: number) => number;
-/** `rect` with width↔height swapped about its own centre — the unrotated box
- *  whose quarter-turn AABB is exactly `rect` again. */
-declare function transposedAboutCenter(rect: Rect): Rect;
 /**
- * The unrotated content rect for a DEFAULT-SIZE upright box "placed at" a
+ * The unrotated content rect for a default-size upright box "placed at" a
  * point: positioned so that, after the upright counter-rotation, the box shows
- * `width`×`height` with its TOP-LEFT at `anchor` in the ROTATED view — the
+ * `width`×`height` with its top-left at `anchor` in the rotated view — the
  * same on-screen feel as the rotation-0 `{ x: anchor.x, y: anchor.y }` box at
  * every quarter-turn (a click-created free-text box always opens down-right of
  * the cursor as the author sees it). Derived by placing the box in the display
  * frame and pulling its AABB back through the quarter-turn; the page dims
  * cancel, so no page box is needed.
  */
-declare function uprightAnchoredRect(anchor: Vec, width: number, height: number, displayRotation: number): Rect;
+declare function uprightAnchoredRect(anchor: Point, width: number, height: number, displayRotation: number): Rect;
 /**
- * The LOGICAL (unrotated) content-space box for a stamp placed at `center`,
+ * The logical (unrotated) page-space box for a stamp placed at `center`,
  * sized `desired` (points), fit onto the page and clamped fully within it —
- * the v2 rubber-stamp rule: keep the image's own size unless it would overflow
+ * the rubber-stamp rule: keep the image's own size unless it would overflow
  * the page, then scale down (aspect preserved, never up) so it just fits.
  *
- * Under an upright quarter-turn the on-page FOOTPRINT is the box transposed
- * (w↔h), so BOTH the fit and the edge clamp use that footprint — a landscape
+ * Under an upright quarter-turn the on-page footprint is the box transposed
+ * (w↔h), so both the fit and the edge clamp use that footprint — a landscape
  * stamp uprighted onto a portrait page fits by its rotated silhouette, not its
  * logical box. The box centre and its footprint AABB centre coincide (rotation
  * is about the centre), so clamping one clamps the other.
  */
-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;
+declare function fitStampBox(center: Point, desired: Size, page: Size, rotCW: number): Rect;
+/** Reset a geom to its as-authored orientation (turn → 0). Box: drop the turn.
+ *  Points: turn back about `pivot` (the middle of the upright points by
+ *  default, which only clears the turn). */
+declare function geomResetRotation(geometry: Shape, pivot?: Point): Shape;
 /**
  * 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
- * the `rect` rotated about its centre; for a vertex shape it is reconstructed
- * from the advisory `rot` — un-rotate the points to recover the as-authored
- * shape, take that tight local box, then rotate it back — giving the snug tilted
+ * nw, ne, se, sw of the local box, transformed) + the angle. For a box this is
+ * the box rotated about its centre; for a points shape it is the drawn bounds
+ * of its upright points, turned about their middle — the snug tilted
  * rectangle. Returns null for non-rotatable kinds.
  */
-declare function obbFromGeom(g: Geom, strokeWidth: number, border?: Border): {
-  corners: [Vec, Vec, Vec, Vec];
+declare function obbFromGeom(geometry: Shape, stroke: Stroke): {
+  corners: [Point, Point, Point, Point];
   angle: number;
 } | null;
-/** The fixed point of a group resize: the OPPOSITE handle's point on the box. */
-declare function groupResizeAnchor(base: Rect, handle: string): Vec;
+/** The fixed point of a group resize: the opposite handle's point on the box. */
+declare function groupResizeAnchor(base: Rect, handle: string): Point;
 /**
  * The live group resize box for a drag. Anisotropic = the plain axis-aligned
  * `resizeRect`; isotropic = a uniform scale of `base` about the anchor by the
  * larger of the two drag ratios (so the preview matches the committed scale and
  * never shears a rotated member).
  */
-declare function groupResizeBox(base: Rect, handle: string, to: Vec, isotropic: boolean): Rect;
+declare function groupResizeBox(base: Rect, handle: string, to: Point, isotropic: boolean): Rect;
 /** The (sx, sy) factors a `base`→`cur` group resize applied about its anchor. */
-declare function groupResizeFactors(base: Rect, cur: Rect): {
+declare function groupResizeFactors(base: Rect, current: Rect): {
   sx: number;
   sy: number;
 };
 /**
- * Scale a geom about `anchor` by `(sx, sy)`. For a rotated box (iso scale, so
- * `sx === sy`) the unrotated `rect` is scaled about the anchor and `rot` is
- * preserved (a uniform scale commutes with rotation). For unrotated members
- * (the anisotropic case) every point/extent scales directly.
+ * Scale a geom about `anchor` by `(sx, sy)`, exactly. For a rotated box (iso
+ * scale, so `sx === sy`) the unrotated box is scaled about the anchor and its
+ * turn is preserved (a uniform scale commutes with rotation). For unrotated
+ * members (the anisotropic case) every point/extent scales directly. A resize
+ * passes `minSize`, the smallest a box may end up.
  */
-declare function geomScaleAbout(g: Geom, anchor: Vec, sx: number, sy: number): Geom;
+declare function geomScaleAbout(geometry: Shape, anchor: Point, sx: number, sy: number, minSize?: number): Shape;
 /** Where the rotate knob sits, given the OBB corners (nw, ne, se, sw) and the
  *  outward offset (content units). `from` is the top-edge midpoint the connector
  *  stalk anchors to; `at` is the grab dot, offset along the outward normal. */
-declare function rotateKnob(corners: [Vec, Vec, Vec, Vec], offset: number): {
-  at: Vec;
-  from: Vec;
+declare function rotateKnob(corners: [Point, Point, Point, Point], offset: number): {
+  at: Point;
+  from: Point;
 };
 /**
- * `rotateKnob` with a TOTAL page-bound placement policy: annotations, gestures
+ * `rotateKnob` with a total page-bound placement policy: annotations, gestures
  * and chrome are all page-bound, so the grab dot must land inside `pageBox` —
  * off-page it is unreachable (the pointer dispatch resolves pages by
- * containment). Policy: top edge (the default) → FLIP to the bottom edge when
- * the stalk exits the page → CLAMP the top candidate inside (degenerate: the
+ * containment). Policy: top edge (the default) → flip to the bottom edge when
+ * the stalk exits the page → clamp the top candidate inside (degenerate: the
  * selection spans ~the whole page; the knob may then overlap the shape, and
  * hit-testing checks it first so it stays grabbable). Both render (`chrome`)
- * and hit-test (`hitTest`) place the knob through THIS function, so what you
+ * and hit-test (`hitTest`) place the knob through this function, so what you
  * see is what you can grab — by construction. No `pageBox` → the raw knob.
  */
-declare function placeRotateKnob(corners: [Vec, Vec, Vec, Vec], offset: number, pageBox?: Rect): {
-  at: Vec;
-  from: Vec;
+declare function placeRotateKnob(corners: [Point, Point, Point, Point], offset: number, pageBox?: Rect): {
+  at: Point;
+  from: Point;
 };
-/** The box-edge midpoint the leader connects to: the side `ref` (the knee, else
- *  the tip) points toward, by horizontal/vertical dominance vs the box centre.
- *  With `rot` (a callout box tilted by the upright policy) the decision runs in
- *  the box's LOCAL frame and the midpoint lands back on the ROTATED edge — the
- *  edge the user actually sees. Mirror of v2's `computeCalloutConnectionPoint`. */
-declare function calloutConnection(box: Rect, ref: Vec, rot?: number): Vec;
-/** The leader polyline `[tip, knee?, conn]`, with `conn` derived from the box
- *  (its ROTATED footprint when the box carries `rot`). */
-declare function calloutLinePoints(g: Extract<Geom, {
-  t: 'text';
-}>): Vec[];
-/**
- * The stored `rect` for a freshly-drawn shape, given the box the user dragged. A
- * cloudy border stores the OUTER box (dragged + cloud extent), so the dragged box
- * is its inner edge and the scallops bulge out to the stored box — just like a
- * solid shape, whose /Rect is the dragged box. So `g.rect` is ALWAYS the outer box;
- * the cloud-vs-solid difference lives only here, at creation.
- */
-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). */
-declare const MITER_LIMIT = 10;
-/**
- * A geom's VISUAL bounds: the rect that encloses the drawn appearance, so the
- * baked /AP is never clipped and the selection outline wraps exactly what's drawn.
+ * A geom's visual bounds: the rect that encloses the drawn appearance, so the
+ * baked /AP is never clipped.
  *
- * A shape's `rect` IS its visual box (the PDF /Rect): solid/dashed strokes draw
- * inside it, and a cloudy border's scallops also inset back into it (the dragged
- * inner edge sits `/RD` in from it — see `shapeRectFor`). So growing the stroke or
- * the cloud thickens inward, never spilling past the handles. Lines / polylines /
- * ink have no box, so they expand by the stroke (+ endings) — the SAME math feeds
- * `geomScene`, so the visual box and what's drawn always agree.
+ * A box's strokes draw inside it; a cloudy border's bumps reach out from it,
+ * so its bounds grow by the cloud's reach (`boxDrawnBounds`), before its
+ * turn. Lines / polylines / ink have no box, so they expand by the stroke
+ * (+ endings) — the same math feeds `geomScene`, so the visual box and what's
+ * drawn always agree.
  *
- * `border` matters for ONE case: a CLOSED poly with a cloudy border, whose curls
- * are centred on the vertex path and reach OUTWARD (there is no outer box to
- * inset into) — the bounds grow by the cloud extent, and the engine `/Rect`
- * (via `geomPdfBounds`) grows with them so the baked scallops are never clipped.
+ * The stroke's cloud matters too: a box's, and a closed poly's, whose curls
+ * are centred on the vertex path and reach outward — the bounds grow by the
+ * cloud extent, and the engine's `rect` grows with them so the baked scallops
+ * are never clipped.
  */
-declare function geomVisualBounds(g: Geom, strokeWidth: number, border?: Border): Rect;
+declare const geomVisualBounds: (geometry: Shape, stroke: Stroke) => Rect;
 /**
- * The rect the SELECTION wraps — and the region a SELECTED annotation can be grabbed
+ * The rect the selection wraps — and the region a selected annotation can be grabbed
  * from. Centre-line geometries (line / polyline / polygon / ink) straddle their path,
- * so this is their VISUAL bounds (the join-aware stroke outline + endings) — a
+ * so this is their visual bounds (the join-aware stroke outline + endings) — a
  * polygon's outline wraps its stroke exactly like a polyline. Box kinds (square /
- * circle / free-text) sit tight on their `rect` (their stroke draws INSIDE the box,
- * so the 8 resize handles land on the corners). The chrome outline AND the selected
+ * circle / free-text) sit tight on their box (a stroke draws inside it, and a
+ * cloud's bumps reach past it), so the 8 resize handles land on its corners. The chrome outline and the selected
  * hit-test both call this, so what you see highlighted is exactly what you can grab —
  * they can never drift.
  */
-declare function selectionBounds(g: Geom, strokeWidth: number, border?: Border): Rect;
+declare const selectionBounds: (geometry: Shape, stroke: Stroke) => Rect;
 /**
- * The four corners of the ORIENTED selection box — the SAME quad `chrome` draws.
+ * The four corners of the oriented selection box — the same quad `chrome` draws.
  * For a rotatable kind this is the OBB (the tilted box, from `obbFromGeom`); at
  * `rot == 0` those are just the axis-aligned corners of `selectionBounds`, and
  * for non-rotatable kinds (markup quads, callouts) it falls back to the rect
@@ -1762,77 +2318,227 @@ declare function selectionBounds(g: Geom, strokeWidth: number, border?: Border):
  * all consume this, so what you can grab / where the menu sits never drifts from
  * the outline you see.
  */
-declare function selectionQuad(g: Geom, strokeWidth: number, border?: Border): [Vec, Vec, Vec, Vec];
+declare function selectionQuad(geometry: Shape, stroke: Stroke): [Point, Point, Point, Point];
 /** Is the point inside the (convex) selection quad? Even-odd ring test. */
-declare const pointInQuad: (p: Vec, quad: [Vec, Vec, Vec, Vec]) => boolean;
+declare const pointInQuad: (point: Point, quad: [Point, Point, Point, Point]) => boolean;
+/** The box around the shape's own box or points, the stroke left out. */
+declare const geomBounds: (geometry: Shape) => Rect;
+/**
+ * Is the page point on what the shape paints ({@link geomPainted}): within
+ * `margin` of its ink, which widens with the stroke width, or inside it when
+ * `filled`. A cloudy border is hit on its curves.
+ */
+declare function geomHit(geometry: Shape, point: Point, margin: number, filled: boolean, stroke: Stroke): boolean;
+/**
+ * What the shape paints (`painted.ts`): its ink for `stroke`, and its inside
+ * when `filled`. Kept per shape object for the stroke and fill last asked
+ * about, since a hover asks again on every pointer move.
+ */
+declare function geomPainted(geometry: Shape, stroke: Stroke, filled: boolean): readonly PaintedPiece[];
+/** The shape's handles: resize corners and sides, a callout's tip and knee, or vertices. */
+declare const geomHandles: (geometry: Shape) => Handle[];
+declare const geomTranslate: (geometry: Shape, delta: Point) => Shape;
+declare const geomDragHandle: (geometry: Shape, handle: string, to: Point) => Shape;
+/**
+ * What the shape draws for the live view. A text box's box — its fill and
+ * its border — is the scene's, plain box and callout alike, so the live view
+ * paints exactly what the AP generator bakes; the framework's editable
+ * element owns only the text.
+ */
+declare const geomScene: (geometry: Shape, stroke: Stroke) => RenderNode[];
+//#endregion
+//#region src/rect.d.ts
+type RectHandle = 'nw' | 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w';
+declare const RECT_HANDLES: RectHandle[];
+/** The resize cursor for a handle on a box tilted by `rot` deg: rotate the
+ *  handle's compass direction with the box and pick the nearest 45° sector.
+ *  At `rot = 0` this reproduces {@link RECT_CURSOR} exactly. */
+declare const rotatedHandleCursor: (handle: RectHandle, rot: number) => Cursor;
+declare const rectFromPoints: (from: Point, to: Point) => Rect;
+declare function unionRect(points: Point[]): Rect;
+/** Normalize degrees into `[0, 360)`. */
+declare const normalizeDeg: (degrees: number) => number;
+/** `rect` with width↔height swapped about its own centre — the unrotated box
+ *  whose quarter-turn AABB is exactly `rect` again. */
+declare function transposedAboutCenter(rect: Rect): Rect;
+/** The AABB of `rect` rotated `deg` about `pivot` (its own centre unless given). */
+declare function rotatedAabb(rect: Rect, deg: number, pivot?: Point): Rect;
+//#endregion
+//#region src/record/identity.d.ts
+/**
+ * An annotation's kind (`kinds/`): the one its subtype names; for a widget,
+ * the one its field family picks (`widget-text`…); for a free text with the
+ * callout intent, the callout.
+ */
+declare function kindOf(annotation: Annotation): AnnotationKind;
+/**
+ * A record's engine ref, a new one's included (it names the object number
+ * its create takes); `null` for a record the view doesn't hold.
+ */
+declare const refOf: (record: ModelAnnotation | undefined) => AnnotationRef | null;
+/**
+ * The key of the annotation an annotation answers (`/IRT`): a comment reply's
+ * parent, or a group member's primary.
+ */
+declare const irtOf: (annotation: Annotation) => Id | undefined;
 /**
- * Does the (convex) selection quad intersect an axis-aligned rect? Separating
- * axis test on the only four candidate axes — the rect's x/y plus the quad's
- * two edge normals; a gap on any axis proves disjoint, otherwise they overlap
- * (touching counts). This is the marquee's predicate: it must catch a tilted
- * shape by the ORIENTED box that is actually drawn — the AABB of that quad has
- * empty corners covering most of the unrotated footprint, so testing it selects
- * shapes the marquee never touched. At `rot 0` the quad is axis-aligned and
- * this degenerates to exactly `rectsIntersect`.
+ * The key of the group an annotation belongs to: its primary's, for a
+ * `/RT /Group` member only (a visual group acts as a unit; a comment reply
+ * answers its parent but is not part of it).
  */
-declare function quadIntersectsRect(quad: [Vec, Vec, Vec, Vec], r: Rect): boolean;
+declare const groupOf: (annotation: Annotation) => Id | undefined;
+//#endregion
+//#region src/record/shape.d.ts
 /**
- * The centre of the ORIENTED selection box — the middle of the rect you see.
- * For box kinds this is the rect centre (so squares/circles are unchanged); for
- * vertex kinds it is the OBB centre, so rotation spins the shape in place rather
- * than swinging it about the off-centre vertex mean (`centroidOf`).
+ * The annotation's shape (`shapes/`), read by its kind's family. The same
+ * shape for the same annotation, so what is worked out from a shape once
+ * (where its points are drawn) is kept.
  */
-declare function selectionCenter(g: Geom, strokeWidth: number): Vec;
-declare function geomBounds(g: Geom): Rect;
+declare function shapeOf(annotation: Annotation): Shape;
 /**
- * Is the content point ON the annotation: within `margin` of the stroke, or
- * inside the fill (when `filled`). The stroke band widens with the stroke width.
+ * The record with its shape changed: the engine fields that state `shape`,
+ * written through `withValues`. The same record when the shape is the one
+ * it has, or when the record may not change now.
+ */
+declare const withShape: (record: ModelAnnotation, shape: Shape) => ModelAnnotation;
+//#endregion
+//#region src/record/style.d.ts
+/**
+ * How the annotation is drawn: its colours, stroke and border, by the
+ * engine's names, with its kind's fill-ins. A view: nothing is written back
+ * through it. The same style for the same annotation.
+ */
+declare function styleOf(annotation: Annotation): Style;
+//#endregion
+//#region src/record/text.d.ts
+/**
+ * How the annotation's text is set: its font, size, colour and alignment by
+ * the engine's names, and a free text's bold, italic and underline. A view:
+ * nothing is written back through it. `undefined` for a kind without text.
+ * The same value for the same annotation.
+ */
+declare function textOf(annotation: Annotation): TextStyle | undefined;
+//#endregion
+//#region src/record/values.d.ts
+/**
+ * The record with engine `values` written, as far as it takes them:
  *
- * A shape's stroke is drawn INSIDE its box, centred on `insetRect(rect, sw/2)`
- * (see `geomScene`), so the clickable band follows that inset centre-line — not
- * the box edge. The fill still reaches the box. (Cloudy scallops aren't modelled
- * here; with their typically thin stroke the inset is sub-pixel, so this matches.)
+ * 1. Only the fields its kind has and this session may change now
+ *    (`mayWrite`). The rest are ignored, so one set of values restyles a
+ *    mixed selection.
+ * 2. A `rect` is a command, resolved as the engine resolves it
+ *    (`resolveRectCommand`): it becomes the shape that puts the drawing
+ *    there, and one the engine would refuse throws.
+ * 3. Merged into its annotation as given. The engine's follow rules (a
+ *    measurement's label, a callout's end) run once, where the change is
+ *    applied (`applyChange`).
+ *
+ * A value set to what it was is no change: the same record comes back.
  */
-declare function geomHit(g: Geom, p: Vec, margin: number, filled: boolean, strokeWidth: number): boolean;
-declare function geomHandles(g: Geom): Handle[];
-declare function geomTranslate(g: Geom, d: Vec): Geom;
-declare function geomDragHandle(g: Geom, handle: string, to: Vec): Geom;
+declare function withValues(record: ModelAnnotation, values: FieldValues): ModelAnnotation;
+//#endregion
+//#region src/record/links.d.ts
 /**
- * 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).
+ * The desired hit rects (page space) of a parent's attached link
+ * children — derived fresh from the parent's committed geometry, never
+ * tracked: markup gets one child per quad (per-line hit areas), a text box
+ * one child over its box, every other kind one child over its visual bounds.
+ * The reconciler and the navigation lens both read this, so the clickable
+ * area and the written `/Rect`s can never disagree.
+ *
+ * A link's `/Rect` is axis-aligned by spec (no rotation exists for links),
+ * so a rotated parent gets the AABB of its rotated footprint — the
+ * `selectionQuad` corners (rotation + stroke included), the same envelope
+ * the selection chrome outlines. A text box's link covers only its turned
+ * box: a callout's frame also takes in its line, and a link that size
+ * would make the empty space around the line clickable. Exact rotated hit
+ * regions need `/QuadPoints` (tier 2).
  */
-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;
-declare const pdfToContentRect: (pdf: PdfRect, crop: PdfRect) => Rect;
-declare const contentToPdfRect: (r: Rect, crop: PdfRect) => PdfRect;
-/** A geom's VISUAL bounding box (geometry + stroke + line endings) as a PdfRect —
- *  the engine requires an explicit `rect` that encloses the baked /AP. */
-declare const geomPdfBounds: (g: Geom, strokeWidth: number, crop: PdfRect, border?: Border) => PdfRect;
+declare function linkChildRects(shape: Shape, style: Style): Rect[];
+/** The writable projection of a `link` value: `goto`/`uri` pass through,
+ *  read-only arms (`javascript`, `named`, `goto-remote`, `launch`,
+ *  `unsupported`) yield `null` — they can be carried, never (re)written. */
+declare function writableTarget(target: PdfLinkTarget | null | undefined): PdfLinkTargetWritable | null;
 //#endregion
-//#region src/cloudy.d.ts
+//#region src/record/written.d.ts
 /**
- * The per-side inset (content units) from a shape's outer box to the cloud's
- * inner boundary — the scallop radius plus half the stroke. This IS the `/RD`
- * the engine stores, and it's sized so the scallop peaks reach back out to the
- * box edge: the box remains the annotation's outer boundary.
+ * The annotation `draft` creates, as the engine reads it back: the draft's
+ * fields as the engine states them, and a drawn kind's `rect` the box around
+ * its drawing. `at` names the ref it will have.
  */
-declare function cloudyBorderExtent(intensity: number, strokeWidth: number, ellipse: boolean): number;
+declare function annotationOfNew(draft: AnnotationDraft, at: {
+  readonly ref: AnnotationRef;
+}): Annotation;
 /**
- * SVG path data for a cloudy square (rect) or circle (ellipse), in ABSOLUTE
- * content coordinates. The scallops are generated on the box inset by
- * `cloudyBorderExtent` and bulge back out to `box`'s edge.
+ * `annotation` after `patch`, as the engine reads it back: the patch applied
+ * by the engine's own rules, and the fields the engine works out as its
+ * verdict on the change says (the table at the top of this file). Throws, as
+ * the engine does, for a patch its rules refuse without its schemas
+ * (`resolveAnnotationPatch`); values only the schemas refuse are applied, and
+ * the engine refuses them when the patch reaches it.
+ */
+declare function annotationAfter(annotation: Annotation, patch: AnnotationPatch): Annotation;
+//#endregion
+//#region src/record/index.d.ts
+/**
+ * The record an engine annotation reads as: keyed by its ref, drawn from the
+ * engine's appearance raster (`source: 'baked'`, placed by `apBox`). Whether
+ * this session draws it live instead is the appearance rule's
+ * (appearance.ts).
+ */
+declare function fromDTO(dto: Annotation): ModelAnnotation;
+//#endregion
+//#region src/cloudy.d.ts
+/**
+ * SVG path data for a cloudy square (rect) or circle (ellipse), in absolute
+ * content coordinates. The scallops are generated on `box` and bulge out
+ * from it.
  */
 declare function cloudyPath(box: Rect, ellipse: boolean, intensity: number, strokeWidth: number): string;
 //#endregion
+//#region src/appearance.d.ts
+/** The part of a record that says how it is drawn. */
+type DrawState = Pick<ModelAnnotation, 'source' | 'apBox'>;
+/** How a record this session creates is drawn at first. */
+declare const sourceOfNew: (annotation: Annotation) => ModelAnnotation["source"];
+/**
+ * How a record the engine reports is drawn: live when this session drew it
+ * live (`vector`, the plugin's preference) or when the file holds no
+ * appearance for it; otherwise from the engine's raster.
+ */
+declare const sourceOfConfirmed: (annotation: Annotation, vector: boolean) => ModelAnnotation["source"];
+/**
+ * What changes in how `record` is drawn once `patch` is written: the rule at
+ * the top of this file. Only the fields that change. The engine judges the
+ * patch as it will write it: a `rect` command is the shape it moves to by
+ * then.
+ */
+declare function drawnAfter(record: ModelAnnotation, patch: AnnotationPatch): Partial<DrawState>;
+//#endregion
+//#region src/selection.d.ts
+interface SelectionFrame {
+  corners: QuadRing;
+  center: Point;
+  angle: number;
+}
+/**
+ * The frame of `record` as it is drawn, or with `live` fields laid over its
+ * own (a gesture's geometry, a screen-anchored stroke).
+ */
+declare function annotationSelectionFrame(record: ModelAnnotation, view?: ViewEnv, live?: {
+  geometry?: Shape;
+  style?: Style;
+  measure?: MeasurementAppearance;
+}): SelectionFrame;
+//#endregion
 //#region src/scene.d.ts
+/**
+ * Whether the item can be drawn live now (`scene(item)`): anything not
+ * drawn from the engine's picture, a kind with a live drawing, and a lent
+ * record its lender draws. A stamp or a link can't: its picture is its
+ * drawing.
+ */
+declare const hasLiveDrawing: (item: RenderItem) => boolean;
 /** The full painted scene for one annotation. */
 declare function scene(item: RenderItem): SceneNode[];
 //#endregion
@@ -1842,7 +2548,7 @@ declare function scene(item: RenderItem): SceneNode[];
  * close to horizontal or vertical. Diagonal strokes remain untouched: this is
  * a highlighter aid, not a general line simplifier.
  */
-declare function straightenInkStroke(points: readonly Vec[], options: InkStraightenOptions): Vec[];
+declare function straightenInkStroke(points: readonly Point[], options: InkStraightenOptions): Point[];
 //#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 RichTextRange, type RichTextStyleDelta, 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, applyStyleToRange, 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, isPlainRichText, isRotatableGeom, isSelectable, isSubstrateOnly, linkChildrenOf, linkOf, locateOffset, mergeFlags, 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, shapeRectFor, sharedProps, splitRunsAt, straightenInkStroke, styleAt, styleFromProps, textBoxes, textPlateInset, textStyleFromProps, transposedAboutCenter, unanchoredGeom, unionRect, update, uprightAnchoredRect, uprightRotation, viewable };
+export { type AnchorMode, type AnnotationFlags, type AnnotationKind, type AnnotationOption, type AnnotationProperty, type AnnotationView, type BlendMode, type BoxShape, type CalloutLine, type CaretShape, type ChangeSet, type ChromeGeometry, type ChromeNode, type ClickCreate, type Corners, type CreationDraftAnchor, type Cursor, DEFAULT_CHROME_GEOMETRY, DRAWN_FLAGS, DistanceAppearance, DistanceCaptionLayout, DistanceLayout, DistanceSegment, type Draft, type DrawState, EMPTY_CHANGE, type EditableKind, type EditableKinds, type Effect, FLAG_KEYS, FLAG_PROPERTIES, type FieldValues, type FlagBearer, type FlagKey, type FontLookup, type GestureForm, type GroupCaps, type Guide, type Handle, type HandleRole, type Id, type InkShape, type InkStraightenOptions, KINDS, type KindCaps, type KindName, LINE_ENDING_NAMES, type LineEnding, type LineEndings, type LineShape, MIN_DRAG, MITER_LIMIT, MeasurementAppearance, type MeasurementIntent, type Message, type Model, type ModelAnnotation, NO_ANNOTATION_FLAGS, NO_CAPS, type Paint, type PaintedPiece, type Placement, type PlacementFrame, type Point, type PointerInput, type PointsShape, type PolyShape, type Quad, type QuadRing, type QuadsShape, RECT_HANDLES, ROTATE_KNOB_OFFSET, type Rect, type RectHandle, type RenderItem, type RenderNode, type RichTextRange, type RichTextStyleDelta, type RotationAnchor, STANDARD_FONT_STACKS, type SceneFontProgram, type SceneNode, type SelectionFrame, type Session, type Shape, type ShapeFamily, ShapeMeasurementAppearance, ShapeMeasurementLayout, type SnapResult, type SnapSettings, type Stroke, type Style, type Target, type TextAlign, type TextBox, type TextBoxShape, type TextEndAnchor, type TextStyle, type TurnedBox, type UpdateResult, type ViewEnv, anchorModeOf, anchorOf, anchoredBox, anchoredGeom, anchoredStrokeWidth, annotContentsEditable, annotDeletable, annotInteractive, annotTransformable, annotationAfter, annotationAnchor, annotationOfNew, annotationSelectionFrame, applyStyleToRange, automaticShapeCaptionCenter, bodyFromTextStyle, bodyPieces, boxFamily, calloutEnd, canMove, captionPainted, caretFamily, caretFromAnchor, caretRectFromAnchor, chrome, clampRectToBox, cloudyPath, computeMoveSnap, creationDraftAnchor, cssFontFamilyForFont, cursorAt, defaultsFor, defineKind, distanceCaptionAt, distanceCaptionHit, distanceDrawnBounds, distanceHandles, distanceLabel, distanceLayout, distanceLeaderLength, distancePainted, distanceScene, distanceSelectionQuad, drawnAfter, drawnStrokesOf, editableKindOf, engineSubtypeOf, expandDistanceBounds, expandGroups, faceForFont, familyChosenBy, familyOf, fitStampBox, flagsEqual, fromDTO, geomBounds, geomDragHandle, geomHandles, geomHit, geomPainted, geomResetRotation, geomRotateAbout, geomRotation, geomScaleAbout, geomScene, geomTranslate, geomVisualBounds, gesturePlacement, groupCaps, groupKeyOf, groupMembers, groupOf, groupResizeAnchor, groupResizeBox, groupResizeFactors, hasLiveDrawing, hitTest, iconOf, initialModel, initialSession, initialTextStyle, interactive, irtOf, isAttachedLink, isContentsEditableByHand, isConversationOnly, isDeletableByHand, isDrag, isEditableByHand, isOnTextBox, isPlainRichText, isRotatableGeom, isSelectable, isSubstrateOnly, isTransformableByHand, kindNamed, kindOf, kindTakesLink, lineEndingsOf, linkChildRects, linkChildrenOf, linkOf, locateOffset, measurementCaptionScene, measurementDraftFields, measurementLayout, measurementOf, measurementSelectionQuad, mergeFlags, mountedFontFamily, moveDistanceCaption, moveMeasurementCaption, newRecordsAtMost, normalizeDeg, normalizeRuns, obbFromGeom, pageItems, paintedNear, paintedOf, paintedTouches, paragraphsFromPlainText, placeRotateKnob, placedShape, plainTextOf, pointInQuad, pointsFamily, propertiesOf, quadsFamily, rangeHasStyle, readOfDefaults, rectFromPoints, refOf, resolveClickPlacement, richDocOf, richTextLength, rotateDraftDelta, rotateKnob, rotatedAabb, rotatedHandleCursor, rotationAnchor, sameSession, sameStyleDelta, scene, selectedItems, selectionAnchor, selectionBounds, selectionBoundsOnPage, selectionInBox, selectionKnob, selectionQuad, shapeMeasurementLabel, shapeMeasurementLayout, shapeMeasurementReadout, shapeOf, sharedProperties, sourceOfConfirmed, sourceOfNew, splitRunsAt, straightenInkStroke, styleAt, styleOf, textBoxFamily, textBoxes, textOf, textPlateInset, toolAnnotation, transposedAboutCenter, turnPivotOf, unanchoredGeom, unionRect, unmadeItem, update, uprightAnchoredRect, uprightRotation, viewable, widgetAppearanceOf, withShape, withValues, writableTarget };
 //# sourceMappingURL=index.d.ts.map