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

package/dist/index.js

@@ -1,5 +1,5 @@
 import { NO_ANNOTATION_FLAGS } from "@embedpdf/engine-core/runtime";
-import { applyPoint, applyRect, invert, isQuarterTurn, pdfToContentMatrix, rotateAbout } from "@embedpdf/core-geometry";
+import { applyPoint, applyRect, invert, isQuarterTurn, pdfToContentMatrix, rotateAbout, textQuadBounds, textQuadPoints, textQuadRing } from "@embedpdf/core-geometry";
 //#region src/kinds.ts
 const OPACITY = {
 	key: "opacity",
@@ -635,11 +635,51 @@ const interactive = (f) => !f.hidden && !f.noView && !f.readOnly;
 *  (ISO 32000 — a ReadOnly form field must still be movable by a form designer;
 *  the form-filling layer enforces field ReadOnly itself). */
 const annotInteractive = (a) => capsFor(a.subtype).ignoresReadOnly ? !a.flags.hidden && !a.flags.noView : interactive(a.flags);
-/** Geometry/style/delete mutations — `locked` freezes the OBJECT, not its
-*  contents (that's `lockedContents`). */
-const annotTransformable = (a) => annotInteractive(a) && !a.flags.locked;
+/**
+* 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.
+*/
+const annotTransformable = (a) => annotInteractive(a) && !a.flags.locked && (a.authority?.update ?? true);
+/** Deletion — the delete half of the authority split (a narrowed grant can
+*  allow update but not delete, or vice versa). Flags gate like transforms. */
+const annotDeletable = (a) => annotInteractive(a) && !a.flags.locked && (a.authority?.delete ?? true);
 /** `/Contents` text edits — the contents counterpart of `locked`. */
-const annotContentsEditable = (a) => annotInteractive(a) && !a.flags.lockedContents;
+const annotContentsEditable = (a) => annotInteractive(a) && !a.flags.lockedContents && (a.authority?.update ?? true);
+//#endregion
+//#region src/plane.ts
+const nonEmpty = (v) => typeof v === "string" && v !== "";
+/** True when this annotation belongs to the conversation plane only —
+*  never painted, hit, marquee-selected, or counted into a page's
+*  appearance epoch. */
+function isConversationOnly(a) {
+	if (a.irt !== void 0 && a.group === void 0) return true;
+	if (a.subtype === "text" && a.data?.subtype === "text") {
+		if (nonEmpty(a.data.state) || nonEmpty(a.data.stateModel)) return true;
+	}
+	return false;
+}
+/**
+* A link CHILD attached to another annotation — a `/Link` grouped
+* (`/IRT` + `/RT /Group`) under a non-link parent. Pure substrate: it is
+* the parent's `link` PROPERTY while authoring (derived via `linkOf`) and
+* the navigation plane's anchor while reading — never painted, never hit
+* as itself. Its rect is RECONCILED from the parent's geometry, so direct
+* manipulation would be overwritten anyway.
+*/
+function isAttachedLink(a) {
+	return a.subtype === "link" && a.group !== void 0;
+}
+/**
+* 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.
+*/
+function isSubstrateOnly(a) {
+	return isConversationOnly(a) || isAttachedLink(a);
+}
 //#endregion
 //#region src/group.ts
 /**
@@ -650,7 +690,16 @@ const annotContentsEditable = (a) => annotInteractive(a) && !a.flags.lockedConte
 * carries `group = <primary's id>` (its `refKey`). The primary is NOT stamped —
 * it is simply the annotation whose `id` equals the group key, so membership is
 * the set of annotations pointing at it plus the primary itself.
+*
+* ATTACHED LINK CHILDREN are the exception: they ride the same `/RT /Group`
+* wire mechanism but are NOT part of the composite visual — they're substrate
+* plumbing (the parent's link property). They never count as members here, so
+* a linked square still selects as a SINGLE annotation with handles, never
+* shows Ungroup, and the ungroup verb can never strip an attached link's
+* `/IRT` (which would orphan it into an unmanaged standalone document link).
 */
+/** A subordinate that counts toward a VISUAL group (not link plumbing). */
+const visualMember = (a) => !!a && !isAttachedLink(a);
 function groupCaps(m, ids) {
 	const members = ids.map((id) => m.byId[id]).filter((a) => !!a);
 	if (members.length === 0) return {
@@ -674,8 +723,11 @@ function groupCaps(m, ids) {
 function groupKeyOf(m, id) {
 	const a = m.byId[id];
 	if (!a) return null;
-	if (a.group) return a.group;
-	for (const other of m.order) if (m.byId[other]?.group === id) return id;
+	if (a.group) return isAttachedLink(a) ? null : a.group;
+	for (const other of m.order) {
+		const sub = m.byId[other];
+		if (sub?.group === id && visualMember(sub)) return id;
+	}
 	return null;
 }
 /**
@@ -688,7 +740,10 @@ function groupMembers(m, id) {
 	if (key == null) return [id];
 	const members = [];
 	if (m.byId[key]) members.push(key);
-	for (const other of m.order) if (other !== key && m.byId[other]?.group === key) members.push(other);
+	for (const other of m.order) {
+		const sub = m.byId[other];
+		if (other !== key && sub?.group === key && visualMember(sub)) members.push(other);
+	}
 	return members;
 }
 /** Union of every id's full group — the selection seen as whole groups. */
@@ -1463,9 +1518,12 @@ const DEFAULT_CHROME_GEOM = {
 };
 /** Normalize degrees into `[0, 360)`. */
 const normalizeDeg = (d) => (d % 360 + 360) % 360;
-/** A geom's applied rotation (deg), or 0 for the non-rotatable kinds. */
+/** A geom's applied rotation (deg), or 0 for the non-rotatable kinds. A
+*  caret's `rot` is AUTHORING metadata (its text's baseline tilt): reported
+*  here so the renderer and selection chrome follow it, while the caret's
+*  caps (not movable/resizable) keep every rotate gesture away from it. */
 function geomRotation(g) {
-	if (g.t === "rect" || g.t === "line" || g.t === "poly" || g.t === "ink" || g.t === "text") return g.rot ?? 0;
+	if (g.t === "rect" || g.t === "line" || g.t === "poly" || g.t === "ink" || g.t === "text" || g.t === "caret") return g.rot ?? 0;
 	return 0;
 }
 const rectCenter = (r) => ({
@@ -1487,7 +1545,7 @@ function centroidOf(g) {
 		x: (g.a.x + g.b.x) / 2,
 		y: (g.a.y + g.b.y) / 2
 	};
-	const pts = g.t === "poly" ? g.points : g.t === "ink" ? g.strokes.flat() : g.quads.flat();
+	const pts = g.t === "poly" ? g.points : g.t === "ink" ? g.strokes.flat() : g.quads.flatMap(textQuadPoints);
 	let sx = 0;
 	let sy = 0;
 	for (const p of pts) {
@@ -1500,9 +1558,12 @@ function centroidOf(g) {
 		y: sy / n
 	};
 }
-/** Is this kind rotatable (the geometry carries a meaningful `rot`)? */
+/** Does the geometry carry a meaningful `rot` (an oriented local box exists)?
+*  ORIENTATION is a geometry fact; whether the USER may rotate is the separate
+*  `caps.rotatable` gate — a caret is oriented (it rides its text's tilt) yet
+*  offers no rotate gesture. */
 function isRotatableGeom(g) {
-	return g.t === "rect" || g.t === "line" || g.t === "poly" || g.t === "ink" || g.t === "text" && !g.callout;
+	return g.t === "rect" || g.t === "line" || g.t === "poly" || g.t === "ink" || g.t === "caret" || g.t === "text" && !g.callout;
 }
 /**
 * Rotate a geom by `deltaDeg` (clockwise) about `pivot`.
@@ -1511,7 +1572,10 @@ function isRotatableGeom(g) {
 *    pivot IS the box centre this is a pure `rot += delta`.
 *  - VERTEX (`line`/`poly`/`ink`): map every point through the rotation AND bump
 *    the advisory `rot` (the points stay the authoritative visual).
-* Non-rotatable kinds (caret/quads, callouts) are returned unchanged.
+* Kinds without a rotate VERB are returned unchanged: quads and callouts, and
+* also the caret — oriented (`isRotatableGeom`) but text-anchored, so its tilt
+* is authoring metadata that no gesture edits (`geomResetRotation` still
+* clears it).
 */
 function geomRotateAbout(g, pivot, deltaDeg) {
 	if (deltaDeg === 0) return g;
@@ -1571,7 +1635,7 @@ function apFrameSize(g) {
 		width: g.rect.width,
 		height: g.rect.height
 	};
-	const b = unionRect(g.t === "line" ? [g.a, g.b] : g.t === "poly" ? g.points : g.t === "ink" ? g.strokes.flat() : g.quads.flat());
+	const b = unionRect(g.t === "line" ? [g.a, g.b] : g.t === "poly" ? g.points : g.t === "ink" ? g.strokes.flat() : g.quads.flatMap(textQuadPoints));
 	return {
 		width: b.width,
 		height: b.height
@@ -1680,7 +1744,7 @@ function fitStampBox(center, desired, page, rotCW) {
 function geomResetRotation(g) {
 	const rot = geomRotation(g);
 	if (!rot) return g;
-	if (g.t === "rect" || g.t === "text") return {
+	if (g.t === "rect" || g.t === "text" || g.t === "caret") return {
 		...g,
 		rot: 0
 	};
@@ -1697,7 +1761,7 @@ function geomResetRotation(g) {
 function obbFromGeom(g, strokeWidth, border) {
 	if (!isRotatableGeom(g)) return null;
 	const rot = geomRotation(g);
-	if (g.t === "rect" || g.t === "text") {
+	if (g.t === "rect" || g.t === "text" || g.t === "caret") {
 		const c = rectCenter(g.rect);
 		return {
 			corners: rectCornerPoints(g.rect).map((p) => rotatePoint(p, c, rot)),
@@ -2002,6 +2066,77 @@ function caretRectFromTextEnd(lineRect) {
 		height
 	};
 }
+/**
+* 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.
+*/
+function caretRectFromAnchor(anchor) {
+	const q = anchor.glyphQuad;
+	const ink = Math.hypot(q.lowerStart.x - q.upperStart.x, q.lowerStart.y - q.upperStart.y);
+	const size = Math.max(ink / 2, 1);
+	const corner = anchor.advance > 0 ? q.lowerEnd : q.lowerStart;
+	return {
+		x: corner.x - size / 2,
+		y: corner.y - size,
+		width: size,
+		height: size
+	};
+}
+/** Rotations closer than ~0.05° to upright stay upright (float noise guard). */
+const CARET_ROT_EPSILON = .05;
+/**
+* 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.
+*/
+function caretGeomFromAnchor(anchor) {
+	const q = anchor.glyphQuad;
+	const ink = Math.hypot(q.lowerStart.x - q.upperStart.x, q.lowerStart.y - q.upperStart.y);
+	const size = Math.max(ink / 2, 1);
+	const corner = anchor.advance > 0 ? q.lowerEnd : q.lowerStart;
+	const bx = q.lowerEnd.x - q.lowerStart.x;
+	const by = q.lowerEnd.y - q.lowerStart.y;
+	const rot = Math.hypot(bx, by) > 0 ? normalizeDeg(Math.atan2(by, bx) * 180 / Math.PI) : 0;
+	if (rot < CARET_ROT_EPSILON || rot > 360 - CARET_ROT_EPSILON) return {
+		t: "caret",
+		rect: {
+			x: corner.x - size / 2,
+			y: corner.y - size,
+			width: size,
+			height: size
+		}
+	};
+	const ux = (q.upperStart.x - q.lowerStart.x) / ink;
+	const uy = (q.upperStart.y - q.lowerStart.y) / ink;
+	const cx = corner.x + ux * size / 2;
+	const cy = corner.y + uy * size / 2;
+	return {
+		t: "caret",
+		rect: {
+			x: cx - size / 2,
+			y: cy - size / 2,
+			width: size,
+			height: size
+		},
+		rot
+	};
+}
+/** Map a TextQuad's corners through a point function (names ride along). */
+function mapTextQuad(q, f) {
+	return {
+		upperStart: f(q.upperStart),
+		upperEnd: f(q.upperEnd),
+		lowerStart: f(q.lowerStart),
+		lowerEnd: f(q.lowerEnd)
+	};
+}
 /** 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). */
@@ -2150,7 +2285,7 @@ function geomVisualBounds(g, strokeWidth, border) {
 		return expandRect(unionRect(all), strokeWidth / 2);
 	}
 	if (g.t === "rect" || g.t === "text" || g.t === "caret") return g.rect;
-	if (g.t === "quads") return expandRect(unionRect(g.quads.flat()), strokeWidth / 2);
+	if (g.t === "quads") return expandRect(unionRect(g.quads.flatMap(textQuadPoints)), strokeWidth / 2);
 	if (g.t === "ink") return expandRect(unionRect(g.strokes.flat()), strokeWidth / 2);
 	const pts = strokeOutlinePoints(g.t === "line" ? [g.a, g.b] : g.points, g.t === "poly" && g.closed, strokeWidth);
 	for (const seg of endingSegs(g)) for (const node of endingNodes(seg.tip, seg.angle, seg.ending, strokeWidth)) if (node.kind === "poly") pts.push(...strokeOutlinePoints(node.points, node.closed, strokeWidth));
@@ -2286,7 +2421,7 @@ function geomBounds(g) {
 	if (g.t === "line") return rectFromPoints(g.a, g.b);
 	if (g.t === "poly") return unionRect(g.points);
 	if (g.t === "ink") return unionRect(g.strokes.flat());
-	return unionRect(g.quads.flat());
+	return unionRect(g.quads.flatMap(textQuadPoints));
 }
 /**
 * Is the content point ON the annotation: within `margin` of the stroke, or
@@ -2299,7 +2434,7 @@ function geomBounds(g) {
 */
 function geomHit(g, p, margin, filled, strokeWidth) {
 	const tol = margin + strokeWidth / 2;
-	if ((g.t === "rect" || g.t === "text" && !g.callout) && (g.rot ?? 0) !== 0) p = rotatePoint(p, rectCenter(g.rect), -(g.rot ?? 0));
+	if ((g.t === "rect" || g.t === "caret" || g.t === "text" && !g.callout) && (g.rot ?? 0) !== 0) p = rotatePoint(p, rectCenter(g.rect), -(g.rot ?? 0));
 	if (g.t === "caret") return rectContains(expandRect(g.rect, margin), p);
 	if (g.t === "text") {
 		const rot = g.callout ? g.rot ?? 0 : 0;
@@ -2374,7 +2509,7 @@ function geomHit(g, p, margin, filled, strokeWidth) {
 		for (const stroke of g.strokes) for (let i = 0; i < stroke.length - 1; i++) if (segDist(p, stroke[i], stroke[i + 1]) <= tol) return true;
 		return false;
 	}
-	return g.quads.some((q) => rectContains(unionRect(q), p));
+	return g.quads.some((q) => pointInQuad(p, textQuadRing(q)));
 }
 function geomHandles(g) {
 	if (g.t === "rect" || g.t === "text") {
@@ -2463,7 +2598,7 @@ function geomTranslate(g, d) {
 	};
 	return {
 		...g,
-		quads: g.quads.map((q) => q.map(mv))
+		quads: g.quads.map((q) => mapTextQuad(q, mv))
 	};
 }
 const OPPOSITE_HANDLE = {
@@ -2554,7 +2689,18 @@ function geomDragHandle(g, handle, to) {
 function geomScene(g, strokeWidth = 0, border) {
 	if (g.t === "text") {
 		if (!g.callout) return [];
-		const pts = calloutLinePoints(g);
+		const pts = [...calloutLinePoints(g)];
+		if (strokeWidth > 0 && pts.length >= 2) {
+			const last = pts[pts.length - 1];
+			const prev = pts[pts.length - 2];
+			const dx = last.x - prev.x;
+			const dy = last.y - prev.y;
+			const len = Math.hypot(dx, dy);
+			if (len > 0) pts[pts.length - 1] = {
+				x: last.x + dx / len * (strokeWidth / 2),
+				y: last.y + dy / len * (strokeWidth / 2)
+			};
+		}
 		const nodes = [{
 			kind: "poly",
 			points: pts,
@@ -2563,15 +2709,16 @@ function geomScene(g, strokeWidth = 0, border) {
 		const seg = calloutEndingSeg(pts, g.callout.ending);
 		if (seg) nodes.push(...endingNodes(seg.tip, seg.angle, seg.ending, strokeWidth));
 		if (strokeWidth > 0) {
+			const r = insetRect(g.rect, strokeWidth / 2);
 			const rot = g.rot ?? 0;
 			const c = rectCenter(g.rect);
 			nodes.push(rot ? {
 				kind: "poly",
-				points: rectCornerPoints(g.rect).map((p) => rotatePoint(p, c, rot)),
+				points: rectCornerPoints(r).map((p) => rotatePoint(p, c, rot)),
 				closed: true
 			} : {
 				kind: "rect",
-				rect: g.rect
+				rect: r
 			});
 		}
 		return nodes;
@@ -2636,12 +2783,7 @@ function geomScene(g, strokeWidth = 0, border) {
 	}));
 	return g.quads.map((q) => ({
 		kind: "poly",
-		points: [
-			q[0],
-			q[1],
-			q[3],
-			q[2]
-		],
+		points: textQuadRing(q),
 		closed: true
 	}));
 }
@@ -2841,7 +2983,9 @@ function anchoredBox(box, anchor, mode, view) {
 *  (always beneath), then every other kind, each group preserving creation
 *  z-order. The ONE z-order shared by rendering (`pageItems`) and hit-testing —
 *  and the ONE visibility cull: what `/F` hides (hidden / un-engaged noView)
-*  neither paints nor hits, so an invisible annotation can never eat a click. */
+*  neither paints nor hits, so an invisible annotation can never eat a click.
+*  Conversation-plane annotations (replies, review-status states) are culled
+*  here too — dialogue lives in the comments UI, never on the page. */
 function paintOrder(m, pon) {
 	const markup = [];
 	const other = [];
@@ -2849,6 +2993,7 @@ function paintOrder(m, pon) {
 		const a = m.byId[id];
 		if (!a || a.pon !== pon) continue;
 		if (!viewable(a.flags, m.selected.includes(id))) continue;
+		if (isSubstrateOnly(a)) continue;
 		(isMarkup(a.subtype) ? markup : other).push(id);
 	}
 	return [...markup, ...other];
@@ -2875,7 +3020,7 @@ const canMove = (m, id) => {
 *  `locked` (and inert `/F` states) suppress them at runtime — a
 *  screen-anchored body keeps its handles: `noZoom`/`noRotate` exempt it from
 *  the display transform, they don't freeze its size or vertices. */
-const hasHandles = (a) => {
+const hasHandles = (m, a) => {
 	if (!annotTransformable(a) || textBound(a)) return false;
 	const c = capsFor(a.subtype);
 	return c.resizable || c.vertexEditable;
@@ -2942,7 +3087,7 @@ function hitTest(m, pon, p, geom, strokeMargin, pageBox, inert, view) {
 					};
 				}
 			}
-			if (hasHandles(a)) {
+			if (hasHandles(m, a)) {
 				for (const h of geomHandles(hitGeomOf(a, view))) if (Math.abs(h.at.x - p.x) <= geom.handleTol && Math.abs(h.at.y - p.y) <= geom.handleTol) return {
 					t: "handle",
 					id: a.id,
@@ -3029,6 +3174,24 @@ function cursorAt(m, pon, p, geom, strokeMargin, pageBox, inert, view) {
 	return null;
 }
 //#endregion
+//#region src/links.ts
+/** Every attached link child of `parentId`, in z-order (multi-segment
+*  markup parents carry several children with one shared target). */
+function linkChildrenOf(m, parentId) {
+	const out = [];
+	for (const id of m.order) {
+		const a = m.byId[id];
+		if (a && isAttachedLink(a) && a.group === parentId) out.push(a);
+	}
+	return out;
+}
+/** The parent's link target, derived from its first attached child — the
+*  read side of the `syncLink` reconciler. Null when no child exists. */
+function linkOf(m, parentId) {
+	const d = linkChildrenOf(m, parentId)[0]?.data;
+	return d?.subtype === "link" ? d.target ?? null : null;
+}
+//#endregion
 //#region src/props.ts
 /**
 * The flat property vocabulary over the model: read and apply
@@ -3065,6 +3228,9 @@ const textStyleFromProps = (p) => ({
 	fontColor: p.fontColor,
 	textAlign: p.textAlign
 });
+/** Does this kind's prop table declare `link` (attachable link)? The link
+*  KIND itself also declares it, but stores its own `/A` instead. */
+const kindTakesLink = (subtype) => propsFor(subtype).some((s) => s.key === "link");
 /** A geom that carries `/LE` endings: a line, or an OPEN poly (polyline). */
 const endingsGeom = (g) => g.t === "line" || g.t === "poly" && !g.closed;
 /**
@@ -3150,7 +3316,7 @@ function applyProps(a, patch) {
 		...next,
 		icon: patch.icon
 	};
-	if (patch.link !== void 0 && takes.has("link")) next = {
+	if (patch.link !== void 0 && takes.has("link") && a.subtype === "link") next = {
 		...next,
 		link: patch.link
 	};
@@ -3664,10 +3830,10 @@ function update(m, msg) {
 		case "createPointer": return createPointer(m, msg.phase, msg.subtype, msg.in, msg.preset, msg.intent, msg.deferInkCommit, msg.straightenInk, msg.clickCreate, msg.flags);
 		case "finishInkDraft": return finishInkCreate(m);
 		case "finishCreationDraft": return finishPolyCreate(m);
-		case "createCaret": return createCaret(m, msg.pon, msg.rect, msg.flags);
-		case "createReplaceText": return createReplaceText(m, msg.pon, msg.rects, msg.endRect, msg.preset);
-		case "createMarkup": return createMarkup(m, msg.subtype, msg.pon, msg.rects, msg.preset, msg.flags);
-		case "setMarkupPreview": return setMarkupPreview(m, msg.subtype, msg.rectsByPage, msg.preset);
+		case "createCaret": return createCaret(m, msg.pon, msg.anchor, msg.flags);
+		case "createReplaceText": return createReplaceText(m, msg.pon, msg.quads, msg.anchor, msg.preset);
+		case "createMarkup": return createMarkup(m, msg.subtype, msg.pon, msg.quads, msg.preset, msg.flags);
+		case "setMarkupPreview": return setMarkupPreview(m, msg.subtype, msg.quadsByPage, msg.preset);
 		case "clearMarkupPreview": return m.preview ? [{
 			...m,
 			preview: null
@@ -3712,6 +3878,7 @@ function update(m, msg) {
 			draft: null
 		}, []];
 		case "loaded": return [mergeLoaded(m, msg.annots), []];
+		case "hydrated": return [hydrateAnnots(m, msg.annots, msg.bumpAp ?? false), []];
 		case "created": return [reconcile(m, msg.tempId, msg.id, msg.ref), []];
 		case "createFailed": return [removeAnnots(m, [msg.tempId]), []];
 		case "upsert": return [upsertAnnots(m, msg.annots, msg.bumpAp), []];
@@ -4468,33 +4635,22 @@ function finishPolyCreate(m) {
 		id
 	}]];
 }
-/** Per-line selection rects → /QuadPoints quads (content space, y-down: UL, UR,
-*  LL, LR). Shared by markup creation and the live preview. */
-const rectsToQuads = (rects) => rects.filter((r) => r.width > 0 && r.height > 0).map((r) => [
-	{
-		x: r.x,
-		y: r.y
-	},
-	{
-		x: r.x + r.width,
-		y: r.y
-	},
-	{
-		x: r.x,
-		y: r.y + r.height
-	},
-	{
-		x: r.x + r.width,
-		y: r.y + r.height
-	}
-]);
+/** Drop degenerate segment quads (zero-length baseline or ink extent). Area is
+*  the cross product of the two edge vectors — orientation-safe. */
+const usableQuads = (quads) => quads.filter((q) => {
+	const ux = q.upperEnd.x - q.upperStart.x;
+	const uy = q.upperEnd.y - q.upperStart.y;
+	const sx = q.lowerStart.x - q.upperStart.x;
+	const sy = q.lowerStart.y - q.upperStart.y;
+	return Math.abs(ux * sy - uy * sx) > 0;
+});
 /**
 * Build a text-markup annotation from the selection's per-line rects. The new
 * annotation is `vector` (rendered live by the overlay) and selected, mirroring
 * `createPointer`. One call per page the selection spans. Clears any live preview.
 */
-function createMarkup(m, subtype, pon, rects, preset = subtype, flags) {
-	const quads = rectsToQuads(rects);
+function createMarkup(m, subtype, pon, segmentQuads, preset = subtype, flags) {
+	const quads = usableQuads(segmentQuads);
 	if (!quads.length) return [m, []];
 	const id = `tmp:${m.seq + 1}`;
 	const annot = {
@@ -4535,9 +4691,9 @@ function createMarkup(m, subtype, pon, rects, preset = subtype, flags) {
 * (`/IT /StrikeOutTextEdit`, `/IRT` caret, `/RT /Group`). Persistence performs
 * the two ordered writes and rolls the primary back if the subordinate fails.
 */
-function createReplaceText(m, pon, rects, textEndRect, preset = "replace-text") {
-	const quads = rectsToQuads(rects);
-	if (!quads.length || textEndRect.width <= 0 || textEndRect.height <= 0) return [m, []];
+function createReplaceText(m, pon, segmentQuads, anchor, preset = "replace-text") {
+	const quads = usableQuads(segmentQuads);
+	if (!quads.length) return [m, []];
 	const primaryId = `tmp:${m.seq + 1}`;
 	const strikeoutId = `tmp:${m.seq + 2}`;
 	const style = styleFromProps(defaultsFor(m, preset));
@@ -4547,10 +4703,7 @@ function createReplaceText(m, pon, rects, textEndRect, preset = "replace-text")
 		pon,
 		subtype: "caret",
 		intent: "replace",
-		geom: {
-			t: "caret",
-			rect: caretRectFromTextEnd(textEndRect)
-		},
+		geom: caretGeomFromAnchor(anchor),
 		style,
 		flags: DRAWN_FLAGS,
 		source: "vector"
@@ -4593,20 +4746,17 @@ function createReplaceText(m, pon, rects, textEndRect, preset = "replace-text")
 		members: [strikeoutId]
 	}]];
 }
-function createCaret(m, pon, textEndRect, flags) {
-	if (textEndRect.width <= 0 || textEndRect.height <= 0) return [m, []];
+function createCaret(m, pon, anchor, flags) {
+	const caretGeom = caretGeomFromAnchor(anchor);
+	if (caretGeom.rect.width <= 0 || caretGeom.rect.height <= 0) return [m, []];
 	const id = `tmp:${m.seq + 1}`;
-	const def = defaultsFor(m, "caret");
 	const annot = {
 		id,
 		ref: null,
 		pon,
 		subtype: "caret",
-		geom: {
-			t: "caret",
-			rect: caretRectFromTextEnd(textEndRect)
-		},
-		style: styleFromProps(def),
+		geom: caretGeom,
+		style: styleFromProps(defaultsFor(m, "caret")),
 		flags: {
 			...DRAWN_FLAGS,
 			...flags
@@ -4629,11 +4779,11 @@ function createCaret(m, pon, textEndRect, flags) {
 		id
 	}]];
 }
-/** Set / replace the live markup preview from the selection's per-page rects. */
-function setMarkupPreview(m, subtype, rectsByPage, preset = subtype) {
+/** Set / replace the live markup preview from the selection's per-page quads. */
+function setMarkupPreview(m, subtype, quadsByPage, preset = subtype) {
 	const byPage = {};
-	for (const k in rectsByPage) {
-		const quads = rectsToQuads(rectsByPage[k]);
+	for (const k in quadsByPage) {
+		const quads = usableQuads(quadsByPage[k]);
 		if (quads.length) byPage[Number(k)] = quads;
 	}
 	return [{
@@ -4661,8 +4811,16 @@ function setProps(m, patch) {
 	for (const id of m.selected) {
 		const a = byId[id];
 		if (!a) continue;
+		const linkIntent = patch.link !== void 0 && a.subtype !== "link" && kindTakesLink(a.subtype) && annotTransformable(a);
 		const next = applyProps(a, patch);
-		if (!next) continue;
+		if (!next) {
+			if (linkIntent) fx.push({
+				fx: "syncLink",
+				id,
+				target: patch.link ?? null
+			});
+			continue;
+		}
 		const linkChanged = next.link !== a.link;
 		const otherChanged = next.style !== a.style || next.geom !== a.geom || next.text !== a.text || next.icon !== a.icon;
 		byId[id] = capsFor(a.subtype).opaqueBody || !otherChanged ? next : toVector(next);
@@ -4674,9 +4832,10 @@ function setProps(m, patch) {
 				keys
 			}
 		});
-		if (linkChanged && a.subtype !== "link") fx.push({
+		if (linkIntent) fx.push({
 			fx: "syncLink",
-			id
+			id,
+			target: patch.link ?? null
 		});
 	}
 	return fx.length ? [{
@@ -4693,6 +4852,14 @@ function setProps(m, patch) {
 * COMMITTED member; uncommitted drafts just merge (their create draft carries
 * the flags when it commits).
 */
+/**
+* The actions plane's session-visibility write (Hide actions, script
+* `annot.hidden`): merge per-id hidden overrides into the session overlay.
+* Pure session state — ZERO effects, no engine write, no authority. Hiding
+* clears transient engagement so no orphaned selection chrome or text editor
+* survives on an invisible annotation. Identity-preserving no-op when nothing
+* changes (plugin memo caches key on model identity).
+*/
 function setFlags(m, patch, ids) {
 	const targets = ids ?? m.selected;
 	if (!targets.length) return [m, []];
@@ -4803,28 +4970,26 @@ function resetRotation(m) {
 function deleteSelection(m) {
 	const deletable = m.selected.filter((id) => {
 		const a = m.byId[id];
-		return !!a && annotTransformable(a);
+		return !!a && annotDeletable(a);
 	});
 	if (!deletable.length) return [m, []];
+	const withChildren = [...deletable, ...deletable.flatMap((id) => linkChildrenOf(m, id).map((c) => c.id))];
 	const fx = [];
-	for (const id of deletable) {
+	for (const id of withChildren) {
 		const a = m.byId[id];
 		if (a?.ref) fx.push({
 			fx: "delete",
 			ref: a.ref
 		});
-		for (const childRef of a?.linkRefs ?? []) fx.push({
-			fx: "delete",
-			ref: childRef
-		});
 	}
-	return [removeAnnots(m, deletable), fx];
+	return [removeAnnots(m, withChildren), fx];
 }
 function annotsInBox(m, pon, a, b, inert, view) {
 	const box = rectFromPoints(a, b);
 	return m.order.filter((id) => {
 		const annot = m.byId[id];
 		if (annot?.pon !== pon || inert?.has(id) || !isSelectable(m, id)) return false;
+		if (isSubstrateOnly(annot)) return false;
 		return quadIntersectsRect(selectionQuad(anchoredGeom(annot.geom, anchorModeOf(annot), view), annot.style.strokeWidth, annot.style.border), box);
 	});
 }
@@ -4843,6 +5008,39 @@ function mergeLoaded(m, annots) {
 	};
 }
 /**
+* Whole-document hydration ingest: the snapshot is the committed truth.
+* Overwrites by id via `upsertAnnots` (gesture protection included), then
+* reaps committed entries the snapshot no longer contains — deletions that
+* happened before we subscribed (initial load) or inside a desync gap.
+* Gentler than `removeAnnots`: `tmp:` drafts and gesture-locked ids
+* survive, and an in-progress draft is NOT cancelled — reaped ids can
+* never be part of it (locked ids are excluded from reaping).
+*/
+function hydrateAnnots(m, annots, bumpApFlag) {
+	const incoming = new Set(annots.map((a) => a.id));
+	const locked = draftIds(m.draft);
+	const reaped = m.order.filter((id) => {
+		if (incoming.has(id) || locked.has(id)) return false;
+		const a = m.byId[id];
+		return a !== void 0 && a.ref !== null;
+	});
+	let next = m;
+	if (reaped.length > 0) {
+		const gone = new Set(reaped);
+		const byId = { ...m.byId };
+		for (const id of reaped) delete byId[id];
+		next = {
+			...m,
+			byId,
+			order: m.order.filter((id) => !gone.has(id)),
+			selected: m.selected.filter((id) => !gone.has(id)),
+			hovered: m.hovered && gone.has(m.hovered) ? null : m.hovered,
+			editing: m.editing && gone.has(m.editing) ? null : m.editing
+		};
+	}
+	return upsertAnnots(next, annots, bumpApFlag);
+}
+/**
 * Add-or-replace by id. Unlike `mergeLoaded` (which skips ids it already has,
 * for the bulk page read), this OVERWRITES — it's how the data API re-syncs an
 * annotation from the authoritative engine DTO and how a remote edit lands.
@@ -4858,13 +5056,8 @@ function upsertAnnots(m, annots, bumpAp = false) {
 		if (dragging.has(a.id)) continue;
 		if (!byId[a.id]) order.push(a.id);
 		const prev = byId[a.id];
-		const fold = a.linkRefs === void 0 && prev?.linkRefs?.length && a.subtype !== "link" ? {
-			link: a.link !== void 0 ? a.link : prev.link,
-			linkRefs: prev.linkRefs
-		} : {};
 		byId[a.id] = {
 			...a,
-			...fold,
 			apVersion: (prev?.apVersion ?? 0) + (bumpAp ? 1 : 0)
 		};
 	}
@@ -4972,70 +5165,99 @@ function shapePaint(style, closed) {
 		...style.border.kind === "cloudy" ? { join: "round" } : {}
 	};
 }
-/** A smooth squiggle (quadratic-bezier wave) along a baseline, adapted from v2's
-*  tile: one `Q` hump then reflected `T` segments alternate up/down across the run. */
-function squigglePath(x, y, w, amp) {
+/** A smooth squiggle (quadratic-bezier wave) along an ARBITRARY baseline,
+*  generated in the (û, n̂) basis: one `Q` hump then reflected `T` segments
+*  alternate across the run. Reflection is affine-invariant, so an upright
+*  quad reproduces the old axis-aligned wave byte-for-byte. `n̂` points from
+*  the baseline toward the ascent side; humps rise toward the text. */
+function squigglePath(start, u, n, w, amp) {
 	const half = Math.max(2, amp * 1.5);
-	let d = `M ${num(x)} ${num(y)} Q ${num(x + half / 2)} ${num(y - amp)} ${num(x + half)} ${num(y)}`;
-	for (let px = x + half; px + half <= x + w + .5; px += half) d += ` T ${num(px + half)} ${num(y)}`;
+	const at = (t, off) => ({
+		x: start.x + u.x * t + n.x * off,
+		y: start.y + u.y * t + n.y * off
+	});
+	const p = (v) => `${num(v.x)} ${num(v.y)}`;
+	const hump = at(half / 2, amp);
+	let d = `M ${p(at(0, 0))} Q ${p(hump)} ${p(at(half, 0))}`;
+	for (let t = half; t + half <= w + .5; t += half) d += ` T ${p(at(t + half, 0))}`;
 	return d;
 }
-/** Per-subtype markup nodes. Quads are axis-aligned per-line rects (UL,UR,LL,LR);
-*  the colour is the markup `/C` (our model keeps stroke==fill). */
+/** Per-subtype markup nodes on the quads' own edges (corner-NAMED TextQuads:
+*  upper = ascent side, lower = baseline side, start → end along the frame).
+*  The colour is the markup `/C` (our model keeps stroke==fill). Rotated and
+*  sheared cells draw along their true baselines; upright output is identical
+*  to the old axis-aligned math. */
 function markupScene(subtype, quads, style) {
 	const color = style.color;
 	const opacity = style.opacity;
 	const nodes = [];
 	for (const q of quads) {
-		const x = q[0].x;
-		const y = q[0].y;
-		const w = q[1].x - q[0].x;
-		const h = q[2].y - q[0].y;
+		const down = {
+			x: q.lowerStart.x - q.upperStart.x,
+			y: q.lowerStart.y - q.upperStart.y
+		};
+		const h = Math.hypot(down.x, down.y);
+		const wVec = {
+			x: q.lowerEnd.x - q.lowerStart.x,
+			y: q.lowerEnd.y - q.lowerStart.y
+		};
+		const w = Math.hypot(wVec.x, wVec.y);
 		if (w <= 0 || h <= 0) continue;
+		const n = {
+			x: down.x / h,
+			y: down.y / h
+		};
 		const lw = Math.min(2.5, Math.max(.75, h * .06));
-		if (subtype === "underline") {
-			const yy = y + h - lw;
-			nodes.push({
-				kind: "line",
-				a: {
-					x,
-					y: yy
-				},
-				b: {
-					x: x + w,
-					y: yy
-				},
-				paint: {
-					stroke: color,
-					width: lw,
-					opacity,
-					blend: blendFor(style)
-				}
-			});
-		} else if (subtype === "strikeout") {
-			const yy = y + h / 2;
-			nodes.push({
-				kind: "line",
-				a: {
-					x,
-					y: yy
-				},
-				b: {
-					x: x + w,
-					y: yy
-				},
-				paint: {
-					stroke: color,
-					width: lw,
-					opacity,
-					blend: blendFor(style)
-				}
-			});
-		} else if (subtype === "squiggly") {
+		if (subtype === "underline") nodes.push({
+			kind: "line",
+			a: {
+				x: q.lowerStart.x - n.x * lw,
+				y: q.lowerStart.y - n.y * lw
+			},
+			b: {
+				x: q.lowerEnd.x - n.x * lw,
+				y: q.lowerEnd.y - n.y * lw
+			},
+			paint: {
+				stroke: color,
+				width: lw,
+				opacity,
+				blend: blendFor(style)
+			}
+		});
+		else if (subtype === "strikeout") nodes.push({
+			kind: "line",
+			a: {
+				x: (q.upperStart.x + q.lowerStart.x) / 2,
+				y: (q.upperStart.y + q.lowerStart.y) / 2
+			},
+			b: {
+				x: (q.upperEnd.x + q.lowerEnd.x) / 2,
+				y: (q.upperEnd.y + q.lowerEnd.y) / 2
+			},
+			paint: {
+				stroke: color,
+				width: lw,
+				opacity,
+				blend: blendFor(style)
+			}
+		});
+		else if (subtype === "squiggly") {
 			const amp = Math.min(2, Math.max(1, h * .08));
+			const u = {
+				x: wVec.x / w,
+				y: wVec.y / w
+			};
+			const start = {
+				x: q.lowerStart.x - n.x * amp,
+				y: q.lowerStart.y - n.y * amp
+			};
 			nodes.push({
 				kind: "path",
-				d: squigglePath(x, y + h - amp, w, amp),
+				d: squigglePath(start, u, {
+					x: -n.x,
+					y: -n.y
+				}, w, amp),
 				paint: {
 					stroke: color,
 					width: lw,
@@ -5044,13 +5266,9 @@ function markupScene(subtype, quads, style) {
 				}
 			});
 		} else nodes.push({
-			kind: "rect",
-			rect: {
-				x,
-				y,
-				width: w,
-				height: h
-			},
+			kind: "poly",
+			points: textQuadRing(q),
+			closed: true,
 			paint: {
 				fill: color,
 				opacity,
@@ -5060,23 +5278,40 @@ function markupScene(subtype, quads, style) {
 	}
 	return nodes;
 }
-/** A redact mark's regions: per-quad boxes (text marks) or the rect (area). */
+const rectRing = (r) => [
+	{
+		x: r.x,
+		y: r.y
+	},
+	{
+		x: r.x + r.width,
+		y: r.y
+	},
+	{
+		x: r.x + r.width,
+		y: r.y + r.height
+	},
+	{
+		x: r.x,
+		y: r.y + r.height
+	}
+];
 function redactRegions(geom) {
 	if (geom.t === "quads") {
 		const out = [];
 		for (const q of geom.quads) {
-			const w = q[1].x - q[0].x;
-			const h = q[2].y - q[0].y;
-			if (w > 0 && h > 0) out.push({
-				x: q[0].x,
-				y: q[0].y,
-				width: w,
-				height: h
+			const bounds = textQuadBounds(q);
+			if (bounds.width > 0 && bounds.height > 0) out.push({
+				ring: textQuadRing(q),
+				bounds
 			});
 		}
 		return out;
 	}
-	if (geom.t === "rect") return [geom.rect];
+	if (geom.t === "rect") return [{
+		ring: rectRing(geom.rect),
+		bounds: geom.rect
+	}];
 	return [];
 }
 /**
@@ -5142,9 +5377,10 @@ function redactScene(item) {
 			width: item.style.strokeWidth || 1.5,
 			opacity: item.style.opacity
 		};
-		return regions.map((rect) => ({
-			kind: "rect",
-			rect,
+		return regions.map((region) => ({
+			kind: "poly",
+			points: region.ring,
+			closed: true,
 			paint
 		}));
 	}
@@ -5154,13 +5390,14 @@ function redactScene(item) {
 			fill: item.style.interiorColor,
 			opacity: 1
 		};
-		for (const rect of regions) nodes.push({
-			kind: "rect",
-			rect,
+		for (const region of regions) nodes.push({
+			kind: "poly",
+			points: region.ring,
+			closed: true,
 			paint: fill
 		});
 	}
-	if (item.label) for (const region of regions) nodes.push(...layoutRedactLabel(region, item.label, item.text));
+	if (item.label) for (const region of regions) nodes.push(...layoutRedactLabel(region.bounds, item.label, item.text));
 	return nodes;
 }
 /** The full painted scene for one annotation. */
@@ -5284,6 +5521,7 @@ function effAp(m, id, view) {
 function effSource(m, id) {
 	const a = m.byId[id];
 	if (capsFor(a.subtype).opaqueBody) return a.source;
+	if (m.editing === id && a.geom.t === "text" && a.geom.callout) return "vector";
 	const d = m.draft;
 	if (d?.g === "handle" && d.id === id) return "vector";
 	if ((d?.g === "rotate" || d?.g === "group") && d.ids.includes(id)) return "vector";
@@ -5584,7 +5822,7 @@ function chrome(m, pon, pageBox, knobOffset = 24, view) {
 		const style = effStyle(a, view);
 		const caps = capsFor(a.subtype);
 		const rot = geomRotation(g);
-		const obb = caps.rotatable ? obbFromGeom(g, style.strokeWidth, a.style.border) : null;
+		const obb = obbFromGeom(g, style.strokeWidth, a.style.border);
 		if (obb && rot !== 0) nodes.push({
 			kind: "obb",
 			corners: obb.corners,
@@ -5675,6 +5913,6 @@ function creationDraftAnchor(m) {
 	};
 }
 //#endregion
-export { DEFAULT_CHROME_GEOM, DRAWN_FLAGS, FLAG_KEYS, KINDS, MIN_DRAG, MITER_LIMIT, NO_ANNOTATION_FLAGS, RECT_HANDLES, ROTATE_KNOB_OFFSET, anchorModeOf, anchorOf, anchoredBox, anchoredGeom, anchoredStrokeWidth, annotContentsEditable, annotInteractive, annotTransformable, applyProps, calloutConnection, calloutLinePoints, canMove, capsFor, caretRectFromTextEnd, centroidOf, chrome, clampRectToBox, clickCreateGeom, cloudyBorderExtent, cloudyPath, computeMoveSnap, contentToPdfPoint, contentToPdfRect, creationDraftAnchor, cursorAt, defaultsFor, expandGroups, fitStampBox, flagsEqual, geomBounds, geomDragHandle, geomHandles, geomHit, geomPdfBounds, geomResetRotation, geomRotateAbout, geomRotation, geomScaleAbout, geomScene, geomTranslate, geomVisualBounds, groupCaps, groupKeyOf, groupMembers, groupResizeAnchor, groupResizeBox, groupResizeFactors, hitTest, initialModel, initialStyle, initialTextStyle, interactive, isRotatableGeom, isSelectable, mergeFlags, normalizeDeg, obbFromGeom, pageItems, pdfToContentPoint, pdfToContentRect, placeRotateKnob, pointInQuad, propsFor, quadIntersectsRect, readProp, rectFromPoints, resolveClickPlacement, rotateDraftDelta, rotateKnob, rotatedAabb, rotatedHandleCursor, scene, selectedItems, selectionAnchor, selectionBounds, selectionBoundsOnPage, selectionCenter, selectionKnob, selectionQuad, shapeRectFor, sharedProps, straightenInkStroke, styleFromProps, textBoxes, textStyleFromProps, transposedAboutCenter, unanchoredGeom, unionRect, update, uprightAnchoredRect, uprightRotation, viewable };
+export { DEFAULT_CHROME_GEOM, DRAWN_FLAGS, FLAG_KEYS, KINDS, MIN_DRAG, MITER_LIMIT, NO_ANNOTATION_FLAGS, RECT_HANDLES, ROTATE_KNOB_OFFSET, anchorModeOf, anchorOf, anchoredBox, anchoredGeom, anchoredStrokeWidth, annotContentsEditable, annotDeletable, annotInteractive, annotTransformable, applyProps, calloutConnection, calloutLinePoints, canMove, capsFor, caretGeomFromAnchor, caretRectFromAnchor, caretRectFromTextEnd, centroidOf, chrome, clampRectToBox, clickCreateGeom, cloudyBorderExtent, cloudyPath, computeMoveSnap, contentToPdfPoint, contentToPdfRect, creationDraftAnchor, cursorAt, defaultsFor, expandGroups, fitStampBox, flagsEqual, geomBounds, geomDragHandle, geomHandles, geomHit, geomPdfBounds, geomResetRotation, geomRotateAbout, geomRotation, geomScaleAbout, geomScene, geomTranslate, geomVisualBounds, groupCaps, groupKeyOf, groupMembers, groupResizeAnchor, groupResizeBox, groupResizeFactors, hitTest, initialModel, initialStyle, initialTextStyle, interactive, isAttachedLink, isConversationOnly, isRotatableGeom, isSelectable, isSubstrateOnly, linkChildrenOf, linkOf, mergeFlags, normalizeDeg, obbFromGeom, pageItems, pdfToContentPoint, pdfToContentRect, placeRotateKnob, pointInQuad, propsFor, quadIntersectsRect, readProp, rectFromPoints, resolveClickPlacement, rotateDraftDelta, rotateKnob, rotatedAabb, rotatedHandleCursor, scene, selectedItems, selectionAnchor, selectionBounds, selectionBoundsOnPage, selectionCenter, selectionKnob, selectionQuad, shapeRectFor, sharedProps, straightenInkStroke, styleFromProps, textBoxes, textStyleFromProps, transposedAboutCenter, unanchoredGeom, unionRect, update, uprightAnchoredRect, uprightRotation, viewable };
 
 //# sourceMappingURL=index.js.map