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

package/dist/capability-B_dkoB1K.js

@@ -1,3041 +0,0 @@
-import { a as contentToPdfRect$1, c as insetPdfRectByRD, d as refKey, f as rotFromDTO, g as writableTarget, i as contentToPdfPoint, l as pdfToContentPoint$1, m as toPdfRotation, n as boxGeomFromDTO, o as cssToColor, p as styleFromDTO, r as colorToCss, s as fromPdfRotation, t as boxGeomFields, u as pdfToContentRect$1 } from "./seam-C4L_7rDt.js";
-import { i as isTouchDirect, r as buildToolRegistry, t as ARMED_STAMP_TOOL_ID } from "./tools-DBEYx3-c.js";
-import { n as previewBucket } from "./types-BvB1vUKb.js";
-import { CONTINUOUS_RENDER_POLICY, snapAppearanceScale } from "@embedpdf/core";
-import { ActionsToken, createHoverPump } from "@embedpdf/plugin-actions/contract";
-import { InteractionToken } from "@embedpdf/plugin-interaction/contract";
-import { buildCommentThreads, encodeStableIdKey, resolveBinarySource, sniffBinaryMetadata } from "@embedpdf/engine-core/runtime";
-import { scriptColorToRgb } from "@embedpdf/core-acrojs";
-import { SelectionToken } from "@embedpdf/plugin-selection/contract";
-import { FLAG_KEYS, annotContentsEditable, annotDeletable, annotTransformable, applyStyleToRange, calloutLinePoints, canMove, chrome, clickCreateGeom, cloudyBorderExtent, contentToPdfRect, creationDraftAnchor, cursorAt, defaultsFor, expandGroups, fitStampBox, geomPdfBounds, geomRotation, geomVisualBounds, groupKeyOf, hitTest, initialTextStyle, isSubstrateOnly, linkChildrenOf, linkOf, locateOffset, pageItems, paragraphsFromPlainText, pdfToContentPoint, pdfToContentRect, propsFor, readProp, resolveClickPlacement, rotatedAabb, selectionAnchor, selectionQuad, sharedProps, styleFromProps, textBoxes, textPlateInset, unionRect, update, uprightRotation, viewable } from "@embedpdf/core-annotation";
-import { normalizeQuad, textQuadBounds } from "@embedpdf/core-geometry";
-//#region src/repository/props.ts
-/**
-* GENERIC per-key prop lowerings — the 1:1 mappings from the flat props
-* vocabulary to wire fields that hold for every kind that declares the key.
-* Kind modules override ONLY their exceptions (a coupling lives in its
-* owner's file: cloudy `/RD` in shape.ts, visual-bounds `/Rect` in stroke.ts,
-* the link target in link.ts).
-*/
-/** /BS slice of the style — a cloudy border keeps a solid underlying stroke
-*  (the scallops are the /BE effect, layered on by the shape kinds). */
-const borderSlice = (style) => ({
-	borderStyle: style.border.kind === "dashed" ? "dashed" : "solid",
-	...style.border.kind === "dashed" ? { dashArray: style.border.dash } : {}
-});
-/** The `/DA`-styled text slice falls back to the draw-time seed exactly like
-*  the old projections did (a fresh draft may not carry `text` yet). */
-const textOf = (a) => a.text ?? initialTextStyle;
-const GENERIC_PROPS = {
-	color: (a) => ({ color: cssToColor(a.style.color) }),
-	opacity: (a) => ({ opacity: a.style.opacity }),
-	blendMode: (a) => ({ blendMode: a.style.blendMode }),
-	interiorColor: (a) => ({ interiorColor: a.style.interiorColor ? cssToColor(a.style.interiorColor) : null }),
-	strokeWidth: (a) => ({ strokeWidth: a.style.strokeWidth }),
-	border: (a) => borderSlice(a.style),
-	fontFamily: (a) => ({ fontFamily: textOf(a).fontFamily }),
-	fontSize: (a) => ({ fontSize: textOf(a).fontSize }),
-	fontColor: (a) => ({ fontColor: cssToColor(textOf(a).fontColor) }),
-	textAlign: (a) => ({ textAlign: textOf(a).textAlign }),
-	icon: (a) => a.icon !== void 0 ? { icon: a.icon } : {},
-	link: () => ({})
-};
-//#endregion
-//#region src/repository/projection.ts
-/** Box-kind geometry emission: the model's unrotated `rect` + applied tilt →
-*  `/Rect`(+`unrotatedRect`+`rotation`), total (nulls state the clears). */
-const boxEmit = (a, crop) => {
-	const g = a.geom;
-	return boxGeomFields(g.rect, geomRotation(a.geom), crop);
-};
-//#endregion
-//#region src/repository/kinds/shape.ts
-/** Cloudy `/BE` + `/RD` for a rect shape — TOTAL: the non-cloudy state is
-*  stated as `null` (tri-state remove), never omitted, so toggling cloudy OFF
-*  removes the stale inset (the Adobe phantom-padding bug). */
-function cloudyExtras(a) {
-	if (a.geom.t !== "rect") return {};
-	if (a.style.border.kind === "cloudy") {
-		const inset = cloudyBorderExtent(a.style.border.intensity, a.style.strokeWidth, a.geom.ellipse);
-		return {
-			cloudyIntensity: a.style.border.intensity,
-			rectDifferences: {
-				left: inset,
-				top: inset,
-				right: inset,
-				bottom: inset
-			}
-		};
-	}
-	return {
-		cloudyIntensity: null,
-		rectDifferences: null
-	};
-}
-const ingest = (dto, crop, ellipse) => {
-	const d = dto;
-	return { geom: boxGeomFromDTO(d, d.rotation, d.unrotatedRect, crop, ellipse) };
-};
-const projection = (ellipse) => ({
-	ingest: (dto, crop) => ingest(dto, crop, ellipse),
-	geometry: (a, crop) => boxEmit(a, crop),
-	prop: {
-		strokeWidth: (a) => ({
-			strokeWidth: a.style.strokeWidth,
-			...cloudyExtras(a)
-		}),
-		border: (a) => ({
-			...borderSlice(a.style),
-			...cloudyExtras(a)
-		})
-	}
-});
-const square = projection(false);
-const circle = projection(true);
-//#endregion
-//#region src/repository/kinds/stroke.ts
-/** Advisory rotation, TOTAL: rotation 0 states `null` (tri-state clear) —
-*  omission would preserve a stale advisory angle. */
-const advisoryRotation = (g) => {
-	const rot = geomRotation(g);
-	return { rotation: rot ? toPdfRotation(rot) : null };
-};
-/** `/BE` intensity for a closed poly (polygon): the curls are generated from
-*  /Vertices + /BE alone — per ISO 32000 no /RD applies — and the /Rect
-*  (geomPdfBounds WITH the border) already includes the outward cloud extent. */
-const polyCloudy = (a) => a.geom.t === "poly" && a.geom.closed ? { cloudyIntensity: a.style.border.kind === "cloudy" ? a.style.border.intensity : null } : {};
-/** The visual-bounds `/Rect` (stroke + border included) of a stroke geom. */
-const visualRect = (a, crop) => {
-	const g = a.geom;
-	if (g.t === "line" || g.t === "ink") return { rect: geomPdfBounds(g, a.style.strokeWidth, crop) };
-	if (g.t === "poly") return { rect: geomPdfBounds(g, a.style.strokeWidth, crop, a.style.border) };
-	return {};
-};
-/**
-* A lowering whose key is an INPUT of the derived /Rect: the visual bounds
-* ride along with every emission, so a sparse patch can never change an input
-* without re-emitting the derivation. (The bug this kills: patch `lineEndings`
-* alone → the engine re-bakes the /AP inside the stale /Rect → the new
-* arrowhead is clipped in every viewer except the live vector one.)
-*/
-const withRect = (lower) => (a, crop) => ({
-	...lower(a, crop),
-	...visualRect(a, crop)
-});
-/** Stroke-family prop exceptions: width, border, AND line endings feed the
-*  derived /Rect — an ending's arrowhead reaches well past the endpoint, and
-*  ISO 32000 requires /Rect to enclose it. Where a key can't change the
-*  bounds (a line's border restyle), the re-emitted rect is an idempotent
-*  no-op — uniformity beats per-case reasoning here. */
-const strokeProps = {
-	strokeWidth: withRect((a) => ({ strokeWidth: a.style.strokeWidth })),
-	border: withRect((a) => ({
-		...borderSlice(a.style),
-		...polyCloudy(a)
-	})),
-	lineEndings: withRect((a) => (a.geom.t === "line" || a.geom.t === "poly") && a.geom.ends ? { lineEndings: a.geom.ends } : {})
-};
-const line = {
-	ingest: (dto, crop) => {
-		const d = dto;
-		return { geom: {
-			t: "line",
-			a: pdfToContentPoint(d.linePoints.start, crop),
-			b: pdfToContentPoint(d.linePoints.end, crop),
-			ends: d.lineEndings,
-			...rotFromDTO(d.rotation)
-		} };
-	},
-	geometry: (a, crop) => {
-		const g = a.geom;
-		if (g.t !== "line") return null;
-		return {
-			linePoints: {
-				start: contentToPdfPoint(g.a, crop),
-				end: contentToPdfPoint(g.b, crop)
-			},
-			...visualRect(a, crop),
-			...advisoryRotation(g)
-		};
-	},
-	prop: strokeProps
-};
-const polyProjection = (closed) => ({
-	ingest: (dto, crop) => {
-		const d = dto;
-		return { geom: {
-			t: "poly",
-			points: d.vertices.map((p) => pdfToContentPoint(p, crop)),
-			closed,
-			..."lineEndings" in d ? { ends: d.lineEndings } : {},
-			...rotFromDTO(d.rotation)
-		} };
-	},
-	geometry: (a, crop) => {
-		const g = a.geom;
-		if (g.t !== "poly") return null;
-		return {
-			vertices: g.points.map((p) => contentToPdfPoint(p, crop)),
-			...visualRect(a, crop),
-			...advisoryRotation(g)
-		};
-	},
-	prop: strokeProps
-});
-const polygon = polyProjection(true);
-const polyline = polyProjection(false);
-const ink = {
-	ingest: (dto, crop) => {
-		const d = dto;
-		return {
-			geom: {
-				t: "ink",
-				strokes: d.inkList.map((stroke) => stroke.map((p) => pdfToContentPoint(p, crop))),
-				...rotFromDTO(d.rotation)
-			},
-			...d.intent ? { intent: d.intent } : {}
-		};
-	},
-	geometry: (a, crop) => {
-		const g = a.geom;
-		if (g.t !== "ink") return null;
-		return {
-			inkList: g.strokes.map((stroke) => stroke.map((p) => contentToPdfPoint(p, crop))),
-			...visualRect(a, crop),
-			...advisoryRotation(g)
-		};
-	},
-	prop: strokeProps,
-	draftExtras: (a) => a.intent === "ink-highlight" ? { intent: a.intent } : {}
-};
-//#endregion
-//#region src/rich-text.ts
-/**
-* Rich text POLICY — what the annotation plugin decides about a free-text
-* annotation's rich document, kept pure so every framework's editor glue
-* behaves identically (the mechanics live in `@embedpdf/web`'s binding, the
-* run algebra in the core):
-*
-*   • the rich document of any annot (the DTO's, or one synthesised from the
-*     plain text + the `/DA` text style for a draft that has no DTO yet)
-*   • a flat props patch → the run delta it means for a text RANGE (font,
-*     size, colour, bold/italic/underline) and the keys left for the body
-*   • what a range reads back for those keys (agree → the value, else mixed)
-*   • faces: a DTO font (standard kebab name / registered key) ↔ the face a
-*     run names (family + weight + italic) ↔ a CSS family list
-*   • the commit rule: a document nothing overrides on a plain annotation
-*     commits as `contents`; anything else as `richText`
-*/
-/** The props keys a text range takes as run deltas. */
-const RANGE_KEYS = [
-	"fontFamily",
-	"fontSize",
-	"fontColor",
-	"bold",
-	"italic",
-	"underline"
-];
-/** The engine's standard-14 vocabulary (the `StandardFont` kebab names). */
-const STANDARD_FACES = {
-	courier: {
-		family: "Courier",
-		weight: 400,
-		italic: false
-	},
-	"courier-bold": {
-		family: "Courier",
-		weight: 700,
-		italic: false
-	},
-	"courier-bold-oblique": {
-		family: "Courier",
-		weight: 700,
-		italic: true
-	},
-	"courier-oblique": {
-		family: "Courier",
-		weight: 400,
-		italic: true
-	},
-	helvetica: {
-		family: "Helvetica",
-		weight: 400,
-		italic: false
-	},
-	"helvetica-bold": {
-		family: "Helvetica",
-		weight: 700,
-		italic: false
-	},
-	"helvetica-bold-oblique": {
-		family: "Helvetica",
-		weight: 700,
-		italic: true
-	},
-	"helvetica-oblique": {
-		family: "Helvetica",
-		weight: 400,
-		italic: true
-	},
-	"times-roman": {
-		family: "Times",
-		weight: 400,
-		italic: false
-	},
-	"times-bold": {
-		family: "Times",
-		weight: 700,
-		italic: false
-	},
-	"times-bold-italic": {
-		family: "Times",
-		weight: 700,
-		italic: true
-	},
-	"times-italic": {
-		family: "Times",
-		weight: 400,
-		italic: true
-	},
-	symbol: {
-		family: "Symbol",
-		weight: 400,
-		italic: false
-	},
-	"zapf-dingbats": {
-		family: "ZapfDingbats",
-		weight: 400,
-		italic: false
-	}
-};
-/** Family names compare without case, spaces, hyphens, underscores and
-*  quotes — the engine's own rule. */
-function familyKey(family) {
-	return family.toLowerCase().replace(/[\s\-_'"]/g, "");
-}
-const STANDARD_FAMILY_KEYS = {
-	helvetica: "Helvetica",
-	arial: "Helvetica",
-	arialmt: "Helvetica",
-	sansserif: "Helvetica",
-	times: "Times",
-	timesroman: "Times",
-	timesnewroman: "Times",
-	timesnewromanpsmt: "Times",
-	serif: "Times",
-	courier: "Courier",
-	couriernew: "Courier",
-	couriernewpsmt: "Courier",
-	monospace: "Courier",
-	symbol: "Symbol",
-	zapfdingbats: "ZapfDingbats",
-	dingbats: "ZapfDingbats"
-};
-/** Web stacks with the standard families' metrics (what the DOM editor and
-*  the vector renderer show for text the engine sets in a standard font). */
-const STANDARD_STACKS = {
-	Helvetica: "Helvetica, Arial, sans-serif",
-	Times: "\"Times New Roman\", Times, serif",
-	Courier: "\"Courier New\", Courier, monospace",
-	Symbol: "serif",
-	ZapfDingbats: "serif"
-};
-/** The face a DTO font names: a standard font's family/weight/italic, a
-*  registered key's identity, else the string itself as a family. */
-function faceForFont(font, fonts) {
-	const standard = STANDARD_FACES[font];
-	if (standard) return { ...standard };
-	const registered = fonts?.().find((f) => f.key === font);
-	if (registered) return {
-		family: registered.familyName,
-		weight: registered.weight,
-		italic: registered.italic
-	};
-	return { family: font };
-}
-/** The DTO font for a face: the registered key whose identity matches (the
-*  closest weight, italic first), else the standard kebab name, else the
-*  family itself. The inverse of {@link faceForFont}. */
-function fontForFace(face, fonts) {
-	const wanted = familyKey(face.family);
-	const weight = face.weight ?? 400;
-	const italic = face.italic ?? false;
-	let best;
-	for (const f of fonts?.() ?? []) {
-		if (familyKey(f.familyName) !== wanted) continue;
-		const score = Math.abs(f.weight - weight) + (f.italic === italic ? 0 : 1e3);
-		if (!best || score < best.score) best = {
-			key: f.key,
-			score
-		};
-	}
-	if (best) return best.key;
-	const standard = STANDARD_FAMILY_KEYS[wanted];
-	if (standard) {
-		const bold = weight >= 600;
-		for (const [name, spec] of Object.entries(STANDARD_FACES)) if (spec.family === standard && spec.weight >= 600 === bold && spec.italic === italic) return name;
-		for (const [name, spec] of Object.entries(STANDARD_FACES)) if (spec.family === standard) return name;
-	}
-	return face.family;
-}
-/** The CSS family list for a face family: a standard family's web stack, a
-*  registered family's `@font-face` name (its key — see `mountWebFont`),
-*  else the family itself with a generic fallback. */
-function cssFontFamilyForFace(family, fonts) {
-	const standard = STANDARD_FAMILY_KEYS[familyKey(family)];
-	if (standard) return STANDARD_STACKS[standard];
-	const wanted = familyKey(family);
-	const registered = fonts?.().find((f) => familyKey(f.familyName) === wanted);
-	if (registered) return `"${registered.key}"`;
-	return `"${family}", sans-serif`;
-}
-/** The CSS family list for a DTO font (a standard kebab name or a key). */
-function cssFontFamilyForFont(font, fonts) {
-	const standard = STANDARD_FACES[font];
-	if (standard) return STANDARD_STACKS[standard.family];
-	return `"${font}", sans-serif`;
-}
-const hex = (css) => css.trim().toUpperCase();
-/** The rich body the `/DA` text style describes (a draft's body before its
-*  DTO exists; also the fallback for a DTO without `richText`). */
-function bodyFromTextStyle(t, fonts) {
-	const face = faceForFont(t.fontFamily, fonts);
-	return {
-		family: face.family,
-		weight: t.bold ? 700 : face.weight ?? 400,
-		italic: t.italic ?? face.italic ?? false,
-		size: t.fontSize,
-		color: hex(t.fontColor),
-		decoration: t.underline ? ["underline"] : [],
-		script: "normal",
-		letterSpacing: 0,
-		horizontalScale: 1,
-		align: t.textAlign,
-		dir: "ltr"
-	};
-}
-/** The annotation's rich document: the DTO's, else one synthesised from
-*  its plain text and text style (a draft the engine has not echoed yet). */
-function richDocOf(a, fonts) {
-	if (a.data?.subtype === "free-text" && a.data.richText) return a.data.richText;
-	return {
-		body: bodyFromTextStyle(a.text ?? {
-			fontFamily: "helvetica",
-			fontSize: 12,
-			fontColor: "#000000",
-			textAlign: "left"
-		}, fonts),
-		paragraphs: paragraphsFromPlainText(a.data?.contents ?? "")
-	};
-}
-/**
-* The write a text edit commits: the rich paragraphs, with paragraph
-* properties equal to the body's stripped (they are inherited, not
-* overrides) and the body omitted — it stays what the props path last
-* wrote. One engine, one path: plain and formatted text alike.
-*/
-function textCommitPatch(a, paragraphs, fonts) {
-	return { richText: { paragraphs: stripBodyDefaults(paragraphs, richDocOf(a, fonts).body) } };
-}
-/**
-* Paragraph alignment/direction equal to the body's are not overrides: the
-* engine echoes them resolved, the editor renders them as inline styles and
-* serialises them back, and the commit rule must see through that (a plain
-* `/Contents` annotation must not grow an `/RC` from typing).
-*/
-function stripBodyDefaults(paragraphs, body) {
-	return paragraphs.map((p) => {
-		if ((p.align === void 0 || p.align !== body.align) && (p.dir === void 0 || p.dir !== body.dir)) return p;
-		const { align, dir, ...rest } = p;
-		return {
-			...rest,
-			...align !== void 0 && align !== body.align ? { align } : {},
-			...dir !== void 0 && dir !== body.dir ? { dir } : {}
-		};
-	});
-}
-/**
-* Split a props patch for an annotation whose editor holds a text RANGE:
-* the run delta the range takes (font → face, size, colour, bold → weight,
-* italic, underline → decoration) and the keys that still go to the body.
-*/
-function runDeltaForProps(patch, fonts) {
-	const delta = {};
-	const rest = {};
-	for (const key of Object.keys(patch)) {
-		const value = patch[key];
-		if (value === void 0) continue;
-		switch (key) {
-			case "fontFamily": {
-				const face = faceForFont(patch.fontFamily, fonts);
-				delta.family = face.family;
-				if (face.weight !== void 0) delta.weight = face.weight;
-				if (face.italic !== void 0) delta.italic = face.italic;
-				break;
-			}
-			case "fontSize":
-				delta.size = patch.fontSize;
-				break;
-			case "fontColor":
-				delta.color = hex(patch.fontColor);
-				break;
-			case "bold":
-				delta.weight = patch.bold ? 700 : 400;
-				break;
-			case "italic":
-				delta.italic = patch.italic;
-				break;
-			case "underline":
-				delta.decoration = patch.underline ? ["underline"] : [];
-				break;
-			default: rest[key] = value;
-		}
-	}
-	return {
-		delta,
-		rest
-	};
-}
-/** The style deltas of every non-empty run a range overlaps. */
-function runsInRange(doc, range) {
-	const start = Math.min(range.start, range.end);
-	const end = Math.max(range.start, range.end);
-	if (end <= start) return [];
-	const from = locateOffset(doc, start);
-	const to = locateOffset(doc, end);
-	const out = [];
-	for (let index = from.paragraph; index <= to.paragraph; index++) {
-		const paragraph = doc.paragraphs[index];
-		const localStart = index === from.paragraph ? from.offset : 0;
-		const localEnd = index === to.paragraph ? to.offset : paragraph.runs.reduce((n, r) => n + r.text.length, 0);
-		let pos = 0;
-		for (const run of paragraph.runs) {
-			const runEnd = pos + run.text.length;
-			if (runEnd > localStart && pos < localEnd && run.text.length > 0) out.push(run.style ?? {});
-			pos = runEnd;
-		}
-	}
-	return out;
-}
-/** The values a range reads back for the range keys — resolved against the
-*  body, one value where every run agrees, `mixed` where they don't. */
-function rangeProps(doc, range, fonts) {
-	const runs = runsInRange(doc, range);
-	const body = doc.body;
-	const resolve = (d) => ({
-		family: d.family ?? body.family,
-		weight: d.weight ?? body.weight,
-		italic: d.italic ?? body.italic,
-		size: d.size ?? body.size,
-		color: d.color ?? body.color,
-		decoration: d.decoration ?? body.decoration
-	});
-	const styles = (runs.length ? runs : [{}]).map(resolve);
-	const values = {};
-	const mixed = [];
-	const read = (key, of) => {
-		const first = of(styles[0]);
-		values[key] = first;
-		if (styles.some((s) => JSON.stringify(of(s)) !== JSON.stringify(first))) mixed.push(key);
-	};
-	read("fontFamily", (s) => fontForFace({
-		family: s.family,
-		weight: body.weight,
-		italic: body.italic
-	}, fonts));
-	read("fontSize", (s) => s.size);
-	read("fontColor", (s) => s.color.toLowerCase());
-	read("bold", (s) => (s.weight ?? 400) >= 600);
-	read("italic", (s) => !!s.italic);
-	read("underline", (s) => (s.decoration ?? []).includes("underline"));
-	return {
-		values,
-		mixed
-	};
-}
-//#endregion
-//#region src/repository/kinds/freeText.ts
-/** Free-text `/DA` fields → content {@link TextStyle}. An absent `fontColor`
-*  falls back to the `/DA` colour — the same rule the CPVT renderer applies. */
-function textFromDTO(dto) {
-	const body = dto.richText?.body;
-	return {
-		fontFamily: dto.fontFamily,
-		fontSize: dto.fontSize,
-		fontColor: colorToCss(dto.fontColor ?? dto.color),
-		textAlign: dto.textAlign,
-		...body && body.weight >= 600 ? { bold: true } : {},
-		...body?.italic ? { italic: true } : {},
-		...body?.decoration.includes("underline") ? { underline: true } : {}
-	};
-}
-/**
-* A formatting toggle is a BODY change (runs are deltas over it), so it
-* lowers as a rich write carrying the current paragraphs — and every toggle
-* lowers the same COMPLETE body (the current one with the three toggles
-* applied: a partial body means engine defaults, which would reset the
-* size, face and colour), so a patch of several merges cleanly.
-*/
-const formattingBody = (a) => {
-	const doc = richDocOf(a);
-	const t = a.text;
-	return { richText: {
-		body: {
-			...doc.body,
-			weight: t?.bold ? 700 : 400,
-			italic: !!t?.italic,
-			decoration: t?.underline ? ["underline"] : []
-		},
-		paragraphs: doc.paragraphs
-	} };
-};
-/**
-* The engine geometry for a callout: the overall `/Rect` (text box ∪ leader ∪
-* arrow), the `/RD` inset that recovers the text box from it, the `/CL` leader
-* (`[tip, knee, conn]` with the connection point derived), and the `/LE`
-* ending. All in PDF user space (y-up), with every `/RD` inset clamped
-* non-negative.
-*
-* A tilted box (the upright policy) additionally emits `rotation` +
-* `unrotatedRect` (the logical text box) — the engine bakes the box + text
-* under an INLINE rotation about the box centre while the leader stays
-* page-space, so (unlike plain boxes) the /AP form `/Matrix` stays identity
-* and the raster stays placed by `/Rect`. `/RD` then insets to the ROTATED
-* box's AABB — the best axis-aligned text box a foreign viewer regenerating
-* the AP can draw (spec-conformant degradation). The transform pair is TOTAL
-* (nulls state the clears) like every box emission.
-*/
-function calloutFields(a, crop) {
-	const g = a.geom;
-	if (g.t !== "text" || !g.callout) return null;
-	const rot = geomRotation(g);
-	const overall = geomPdfBounds(g, a.style.strokeWidth, crop);
-	const tb = contentToPdfRect$1(rot ? rotatedAabb(g.rect, rot) : g.rect, crop);
-	const nn = (n) => Math.max(0, n);
-	const pts = calloutLinePoints(g).map((p) => contentToPdfPoint(p, crop));
-	const calloutLine = pts.length === 3 ? [
-		pts[0],
-		pts[1],
-		pts[2]
-	] : [pts[0], pts[1]];
-	return {
-		rect: overall,
-		rectDifferences: {
-			left: nn(tb.left - overall.left),
-			bottom: nn(tb.bottom - overall.bottom),
-			right: nn(overall.right - tb.right),
-			top: nn(overall.top - tb.top)
-		},
-		calloutLine,
-		lineEnding: g.callout.ending,
-		...rot ? {
-			rotation: toPdfRotation(rot),
-			unrotatedRect: contentToPdfRect$1(g.rect, crop)
-		} : {
-			rotation: null,
-			unrotatedRect: null
-		}
-	};
-}
-const freeText = {
-	ingest: (dto, crop) => {
-		const d = dto;
-		if (d.intent === "free-text-callout" && d.calloutLine && d.calloutLine.length >= 2) {
-			const cl = d.calloutLine;
-			const rot = d.rotation ? fromPdfRotation(d.rotation) : 0;
-			return {
-				geom: {
-					t: "text",
-					rect: rot && d.unrotatedRect ? pdfToContentRect$1(d.unrotatedRect, crop) : pdfToContentRect$1(insetPdfRectByRD(d.rect, d.rectDifferences), crop),
-					callout: {
-						tip: pdfToContentPoint$1(cl[0], crop),
-						knee: cl.length === 3 ? pdfToContentPoint$1(cl[1], crop) : void 0,
-						ending: d.lineEnding ?? "none"
-					},
-					...rot && d.unrotatedRect ? { rot } : {}
-				},
-				text: textFromDTO(d)
-			};
-		}
-		const rot = d.rotation ? fromPdfRotation(d.rotation) : 0;
-		return {
-			geom: {
-				t: "text",
-				rect: pdfToContentRect$1(rot && d.unrotatedRect ? d.unrotatedRect : d.rect, crop),
-				...rot ? { rot } : {}
-			},
-			text: textFromDTO(d)
-		};
-	},
-	geometry: (a, crop) => {
-		if (a.geom.t !== "text") return null;
-		const cf = calloutFields(a, crop);
-		if (cf) return { ...cf };
-		return boxEmit(a, crop);
-	},
-	prop: {
-		bold: formattingBody,
-		italic: formattingBody,
-		underline: formattingBody
-	},
-	draftExtras: (a, crop) => ({
-		intent: calloutFields(a, crop) ? "free-text-callout" : "free-text",
-		contents: a.data?.contents ?? ""
-	})
-};
-//#endregion
-//#region src/repository/kinds/quads.ts
-/**
-* Imported `/QuadPoints` → semantic TextQuads. `normalizeQuad` is a
-* NORMALIZER, not a cast: the de-facto zigzag order passes through, ring-order
-* producers are repaired, and garbage gets a deterministic labeling — so
-* drawing code can never put an underline on the wrong edge of a well-formed
-* quad, rotated ones included.
-*/
-const quadsFromDTO = (quadPoints, crop) => quadPoints.map((q) => normalizeQuad({
-	p1: pdfToContentPoint$1(q.p1, crop),
-	p2: pdfToContentPoint$1(q.p2, crop),
-	p3: pdfToContentPoint$1(q.p3, crop),
-	p4: pdfToContentPoint$1(q.p4, crop)
-}));
-/** Content quads → engine `/QuadPoints` (PDF user space, zigzag slot order:
-*  p1..p4 = upper-start, upper-end, lower-start, lower-end — under the y-flip
-*  exactly PDFium's documented TL, TR, BL, BR); null off quads geom. */
-function quadPointsFor(a, crop) {
-	if (a.geom.t !== "quads") return null;
-	return a.geom.quads.map((q) => ({
-		p1: contentToPdfPoint(q.upperStart, crop),
-		p2: contentToPdfPoint(q.upperEnd, crop),
-		p3: contentToPdfPoint(q.lowerStart, crop),
-		p4: contentToPdfPoint(q.lowerEnd, crop)
-	}));
-}
-/** PDF-space bounding box of a set of `/QuadPoints` quads — the `/Rect` a
-*  quad-bearing draft must carry alongside its quads. */
-const pdfBoundsOfQuads = (quads) => {
-	let left = Infinity;
-	let bottom = Infinity;
-	let right = -Infinity;
-	let top = -Infinity;
-	for (const q of quads) for (const p of [
-		q.p1,
-		q.p2,
-		q.p3,
-		q.p4
-	]) {
-		if (p.x < left) left = p.x;
-		if (p.x > right) right = p.x;
-		if (p.y < bottom) bottom = p.y;
-		if (p.y > top) top = p.y;
-	}
-	return {
-		left,
-		bottom,
-		right,
-		top
-	};
-};
-const markupProjection = (subtype) => {
-	return {
-		ingest: (dto, crop) => {
-			const d = dto;
-			return {
-				geom: {
-					t: "quads",
-					quads: quadsFromDTO(d.quadPoints, crop)
-				},
-				...subtype === "strikeout" && "intent" in d && d.intent ? { intent: d.intent } : {}
-			};
-		},
-		geometry: () => null,
-		draftExtras: (a, crop) => {
-			const quads = quadPointsFor(a, crop);
-			if (!quads) return null;
-			return {
-				quadPoints: quads,
-				...subtype === "strikeout" && a.intent === "strikeout-text-edit" ? { intent: a.intent } : {}
-			};
-		}
-	};
-};
-const highlight = markupProjection("highlight");
-const underline = markupProjection("underline");
-const squiggly = markupProjection("squiggly");
-const strikeout = markupProjection("strikeout");
-const caret = {
-	ingest: (dto, crop) => {
-		const d = dto;
-		const rot = d.rotation ? fromPdfRotation(d.rotation) : 0;
-		return {
-			geom: {
-				t: "caret",
-				rect: pdfToContentRect$1(rot && d.unrotatedRect ? d.unrotatedRect : d.rect, crop),
-				...rot ? { rot } : {}
-			},
-			...d.intent ? { intent: d.intent } : {}
-		};
-	},
-	geometry: (a, crop) => a.geom.t === "caret" ? boxGeomFields(a.geom.rect, a.geom.rot ?? 0, crop) : null,
-	draftExtras: (a) => ({
-		rectDifferences: {
-			left: .5,
-			top: .5,
-			right: .5,
-			bottom: .5
-		},
-		...a.intent === "replace" ? { intent: a.intent } : {},
-		...a.data?.contents != null ? { contents: a.data.contents } : {}
-	})
-};
-const redact = {
-	ingest: (dto, crop) => {
-		const d = dto;
-		return {
-			geom: d.quadPoints.length > 0 ? {
-				t: "quads",
-				quads: quadsFromDTO(d.quadPoints, crop)
-			} : {
-				t: "rect",
-				rect: pdfToContentRect$1(d.rect, crop),
-				ellipse: false
-			},
-			text: {
-				fontFamily: d.fontFamily,
-				fontSize: d.fontSize,
-				fontColor: colorToCss(d.fontColor),
-				textAlign: d.textAlign
-			},
-			...d.overlayText ? { label: {
-				text: d.overlayText,
-				repeat: d.repeat
-			} } : {}
-		};
-	},
-	geometry: (a, crop) => a.geom.t === "rect" ? { rect: contentToPdfRect$1(a.geom.rect, crop) } : null,
-	draftExtras: (a, crop) => {
-		const quads = quadPointsFor(a, crop);
-		return quads ? {
-			quadPoints: quads,
-			rect: pdfBoundsOfQuads(quads)
-		} : {};
-	}
-};
-//#endregion
-//#region src/repository/kinds/misc.ts
-const rectGeometry = (a, crop) => "rect" in a.geom ? { rect: contentToPdfRect$1(a.geom.rect, crop) } : null;
-const iconProjection = (subtype) => ({
-	ingest: (dto, crop) => {
-		const d = dto;
-		return {
-			geom: {
-				t: "rect",
-				rect: pdfToContentRect$1(d.rect, crop),
-				ellipse: false
-			},
-			icon: d.icon
-		};
-	},
-	geometry: rectGeometry,
-	createable: false
-});
-const textNote = iconProjection("text");
-const fileAttachment = iconProjection("file-attachment");
-const stamp = {
-	ingest: (dto, crop) => {
-		const d = dto;
-		return { geom: boxGeomFromDTO(d, d.rotation, d.unrotatedRect, crop, false) };
-	},
-	geometry: (a, crop) => boxEmit(a, crop),
-	createable: false
-};
-const link = {
-	ingest: (dto, crop) => {
-		const d = dto;
-		return {
-			geom: {
-				t: "rect",
-				rect: pdfToContentRect$1(d.rect, crop),
-				ellipse: false
-			},
-			link: d.target
-		};
-	},
-	geometry: rectGeometry,
-	prop: { link: (a) => {
-		const target = writableTarget(a.link);
-		return target ? { target } : a.link == null ? { target: null } : {};
-	} },
-	draftExtras: (a) => ({ target: writableTarget(a.link) })
-};
-/** One PDF `widget` subtype → per-family CLIENT kinds (radios have no font). */
-const WIDGET_KIND_BY_FAMILY = {
-	text: "widget-text",
-	combobox: "widget-choice",
-	listbox: "widget-choice",
-	pushbutton: "widget-button",
-	checkbox: "widget-toggle",
-	radio: "widget-toggle"
-};
-const widgetKindOf = (family) => WIDGET_KIND_BY_FAMILY[family] ?? "widget-box";
-const WIDGET_TEXT_KINDS = /* @__PURE__ */ new Set([
-	"widget-text",
-	"widget-choice",
-	"widget-button"
-]);
-function widgetTextFromDTO(dto) {
-	return {
-		fontFamily: dto.fontFamily ?? "helvetica",
-		fontSize: dto.fontSize ?? 0,
-		fontColor: dto.fontColor ? colorToCss(dto.fontColor) : "#000000",
-		textAlign: dto.textAlign
-	};
-}
-const widget = {
-	ingest: (dto, crop) => {
-		const d = dto;
-		return {
-			geom: boxGeomFromDTO(d, void 0, void 0, crop, false),
-			...WIDGET_TEXT_KINDS.has(widgetKindOf(d.fieldFamily)) ? { text: widgetTextFromDTO(d) } : {}
-		};
-	},
-	geometry: rectGeometry,
-	createable: false
-};
-const unsupported = {
-	ingest: (dto, crop) => ({ geom: {
-		t: "rect",
-		rect: pdfToContentRect$1(dto.rect, crop),
-		ellipse: false
-	} }),
-	geometry: () => null,
-	createable: false
-};
-//#endregion
-//#region src/repository/links.ts
-/**
-* Attached-link folding + desired-state derivation — RELATIONSHIP logic, not
-* projection: a `/Link` child grouped under a linkable parent becomes the
-* parent's `link` prop, and the reconciler derives the children it should
-* have from the parent's committed geometry.
-*/
-/**
-* The DESIRED hit rects (content 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, the v2
-* segment behaviour), 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. Exact rotated hit regions need
-* `/QuadPoints` (tier 2).
-*/
-function linkChildRects(a) {
-	if (a.geom.t === "quads") return a.geom.quads.map(textQuadBounds);
-	return [unionRect(selectionQuad(a.geom, a.style.strokeWidth, a.style.border))];
-}
-//#endregion
-//#region src/repository/index.ts
-/** Every wire subtype declares exactly one projection — a missing kind is a
-*  COMPILE error, not a silent fall-through. */
-const KINDS = {
-	square,
-	circle,
-	line,
-	polygon,
-	polyline,
-	ink,
-	"free-text": freeText,
-	highlight,
-	underline,
-	squiggly,
-	strikeout,
-	caret,
-	redact,
-	text: textNote,
-	"file-attachment": fileAttachment,
-	stamp,
-	link,
-	widget,
-	unsupported
-};
-/** Model subtypes are wire subtypes except the widget CLIENT kinds
-*  (`widget-text`…), which all project through the widget family. */
-const projectionOf = (subtype) => subtype.startsWith("widget") ? KINDS.widget : KINDS[subtype] ?? KINDS.unsupported;
-const wireSubtypeOf = (a) => a.subtype.startsWith("widget") ? "widget" : a.subtype;
-/**
-* Engine DTO → content-space Annot. `source` decides how it renders: `'baked'`
-* shows the engine's appearance raster (a page load, or a remote edit — trust
-* the authored AP); `'vector'` renders live from geom/style (we authored or
-* changed it). `apBox` is the raster's content-space box, used while baked.
-*/
-function fromDTO(dto, crop, source = "baked") {
-	const slice = projectionOf(dto.subtype).ingest(dto, crop);
-	const strippedRect = !(dto.subtype === "free-text" && dto.intent === "free-text-callout") && "unrotatedRect" in dto && "rotation" in dto && dto.rotation ? dto.unrotatedRect : void 0;
-	return {
-		id: refKey(dto.ref),
-		ref: dto.ref,
-		pon: dto.pageObjectNumber,
-		subtype: dto.subtype === "widget" ? widgetKindOf(dto.fieldFamily) : dto.subtype,
-		flags: dto.flags,
-		source,
-		data: dto,
-		...dto.inReplyTo ? { irt: refKey(dto.inReplyTo) } : {},
-		...dto.replyType === "group" && dto.inReplyTo ? { group: refKey(dto.inReplyTo) } : {},
-		style: styleFromDTO(dto),
-		...slice,
-		apBox: pdfToContentRect$1(strippedRect ?? dto.rect, crop),
-		...strippedRect ? { apRot: geomRotation(slice.geom) } : {}
-	};
-}
-/** Lower `keys` through the kind's overrides + the generic table. `null` =
-*  some key has no lowering — the caller degrades to the full projection. */
-function emitProps(a, crop, keys) {
-	const kind = projectionOf(a.subtype);
-	const out = {};
-	for (const key of keys) {
-		const lower = kind.prop?.[key] ?? GENERIC_PROPS[key];
-		if (!lower) return null;
-		Object.assign(out, lower(a, crop));
-	}
-	return out;
-}
-const editableKeys = (subtype) => propsFor(subtype).map((s) => s.key);
-/** Content Annot → the FULL engine patch: the kind's geometry group plus every
-*  prop it declares editable. The reference statement — scoped emission and
-*  drafts both build on it. */
-function toPatch(a, crop) {
-	const geo = projectionOf(a.subtype).geometry(a, crop);
-	const props = emitProps(a, crop, editableKeys(a.subtype)) ?? {};
-	if (!geo && Object.keys(props).length === 0) return null;
-	return {
-		subtype: wireSubtypeOf(a),
-		...geo,
-		...props
-	};
-}
-/**
-* Content Annot + a {@link PatchScope} → the SPARSE patch for exactly that
-* intent (the shell's `patch` effect emitter): the reducer says WHAT changed —
-* geometry, or the props keys verbatim — and this lowers only that. Kinds
-* without editable geometry (text markup) and unlowerable keys degrade to the
-* full patch: verbose, never a dropped write.
-*/
-function toScopedPatch(a, scope, crop) {
-	const kind = projectionOf(a.subtype);
-	if (scope.kind === "geometry") {
-		const geo = kind.geometry(a, crop);
-		return geo ? {
-			subtype: wireSubtypeOf(a),
-			...geo
-		} : toPatch(a, crop);
-	}
-	const props = emitProps(a, crop, scope.keys);
-	if (props === null) return toPatch(a, crop);
-	if (Object.keys(props).length === 0) return null;
-	return {
-		subtype: wireSubtypeOf(a),
-		...props
-	};
-}
-/** Content Annot → engine create draft: the full statement plus the kind's
-*  create-only extras, with the model's `/F` emitted verbatim, once, for every
-*  kind (a fresh draw carries DRAWN_FLAGS plus any tool seed). `null` for the
-*  kinds whose creates travel their own path (stamps, widgets, icon place). */
-function toCreateDraft(a, crop) {
-	const kind = projectionOf(a.subtype);
-	if (kind.createable === false) return null;
-	const base = toPatch(a, crop);
-	if (!base) return null;
-	const extras = kind.draftExtras?.(a, crop);
-	if (kind.draftExtras && extras === null) return null;
-	return {
-		...base,
-		...extras,
-		nm: crypto.randomUUID(),
-		flags: a.flags
-	};
-}
-//#endregion
-//#region src/hover-feed.ts
-/**
-* The annotation plane's E/X trigger feed — a thin adapter from the ONE
-* pointer-driven hover seam (the `hoverAt` diff) onto the shared hover pump.
-*
-* Anti-cascade is structural and lives in the CALLER's seam placement:
-* reducer-side hover clears (session-hide, remove, reload) never pass
-* through `hoverAt`, so an effect-induced hover loss can never masquerade as
-* a cursor exit. This module only decides WHO is hoverable here:
-*
-* - Drafts (no engine ref) can't carry /AA — skipped.
-* - Widgets and links belong to their own event planes (fill controls /
-*   LinkLayer anchors own their pixels). When they ARE hit-testable on this
-*   plane, an authoring tool owns them — firing hover actions while editing
-*   would be wrong — so they are skipped unconditionally.
-* - Tree-less annotations are FREE: no target, no dispatch, and per-event
-*   flags keep a lone /E or /X from dispatching its inert twin.
-*/
-function createAnnotationHoverFeed(actions, annotOf) {
-	const pump = createHoverPump(actions.dispatch);
-	const targetOf = (id) => {
-		if (!id) return null;
-		const annot = annotOf(id);
-		if (!annot?.ref) return null;
-		if (annot.subtype.startsWith("widget") || annot.subtype === "link") return null;
-		const enter = Boolean(annot.data?.actions?.cursorEnter?.root);
-		const exit = Boolean(annot.data?.actions?.cursorExit?.root);
-		if (!enter && !exit) return null;
-		return {
-			ref: annot.ref,
-			pon: annot.pon,
-			events: {
-				enter,
-				exit
-			}
-		};
-	};
-	return { hover: (id) => pump.hover(targetOf(id)) };
-}
-//#endregion
-//#region src/text-item.ts
-/**
-* The free-text presentation projection: the core's geometry-only `textBoxes`
-* joined with the DTO-derived font + CSS into render-ready {@link TextItem}s. This
-* is the text analogue of the core's `scene()` "paint" for shapes — it lives in
-* the plugin (not the portable core) because the font→CSS stack mapping and the
-* engine `Color`→CSS seam are web concerns, shared across every web framework.
-*/
-/** Project the model's free-text boxes into render-ready {@link TextItem}s — the
-*  core geometry (`textBoxes`) joined with the DTO-derived CSS. Pure; memoized by
-*  model identity at the call site so selectors get a stable reference. */
-function buildTextItems(m, pon, view) {
-	return textBoxes(m, pon, view).map((tb) => {
-		const a = m.byId[tb.id];
-		const t = a?.text ?? initialTextStyle;
-		const sw = a?.style.strokeWidth ?? 0;
-		const doc = a ? richDocOf(a) : null;
-		return {
-			id: tb.id,
-			ref: a?.ref ?? null,
-			box: tb.box,
-			contents: a?.data?.contents ?? "",
-			richText: { paragraphs: doc ? stripBodyDefaults(doc.paragraphs, doc.body) : [{ runs: [{ text: "" }] }] },
-			editing: tb.editing,
-			...tb.rot ? { rot: tb.rot } : {},
-			css: {
-				fontFamily: cssFontFamilyForFont(t.fontFamily),
-				fontSize: t.fontSize,
-				color: t.fontColor,
-				fontWeight: t.bold ? 700 : 400,
-				fontStyle: t.italic ? "italic" : "normal",
-				textDecoration: t.underline ? "underline" : "none",
-				align: t.textAlign,
-				padding: textPlateInset(sw)
-			}
-		};
-	});
-}
-//#endregion
-//#region src/placement.ts
-/**
-* Per-kind CODE for the click-to-place ICON kinds (note / file attachment)
-* — the `props.ts`/`repository.ts` pattern: all tool CONFIG stays in the
-* tool table; this module only interprets it. The stamp keeps its own
-* sizing/sniffing path in the capability; everything funnels through the
-* one `placeAt` entry there.
-*/
-/**
-* Icon kinds place at the generator's fixed box: the engine forces the
-* `/Rect` to 20×20 from its bottom-left corner (the spec's note-icon rule),
-* so the footprint ghost and the placement use exactly this size.
-*/
-const ICON_PLACE_SIZE = {
-	width: 20,
-	height: 20
-};
-const isIconPlaceKind = (subtype) => subtype === "text" || subtype === "file-attachment";
-/**
-* Build the engine create draft for a placed icon annotation. `geom` is the
-* repository's `boxGeomFields` emit (the `/Rect` + upright rotation pair);
-* `defaults` is the tool's resolved flat props bag (`defaultsFor`) — the
-* colour seam is crossed here via the repository's `cssToColor`, and the
-* icon falls back to the kind's own default when the bag carries none.
-*/
-function iconPlacementDraft(subtype, geom, defaults, flags, file) {
-	const shared = {
-		...geom,
-		color: cssToColor(defaults.color),
-		opacity: defaults.opacity,
-		flags: {
-			print: true,
-			...flags
-		}
-	};
-	if (subtype === "text") return {
-		subtype: "text",
-		icon: defaults.icon ?? "comment",
-		...shared
-	};
-	if (!file) throw new Error("[annotation] a file-attachment placement requires a file payload");
-	return {
-		subtype: "file-attachment",
-		icon: defaults.icon ?? "paperclip",
-		file,
-		...shared
-	};
-}
-//#endregion
-//#region src/capability.ts
-/** Fold `zoom`/`rotation` host args into the core's ViewEnv (or none).
-*  `zoom` is the page's RELATIVE zoom (`transform.zoom`) — never the
-*  px-per-point `scale` (that one only converts CSS-px chrome settings). */
-const viewEnv = (zoom, rotation) => zoom != null || rotation != null ? {
-	zoom: zoom ?? 1,
-	rotation: rotation ?? 0
-} : void 0;
-const TEXT_COMMIT_DEBOUNCE_MS = 250;
-/**
-* The annotation shell. The pure `update` runs HERE (so it can emit effects);
-* the resulting model is dispatched to the store, and each effect is performed
-* against the engine repository — optimistic create → reconcile to the durable
-* ref, patch/delete fire-and-forget.
-*/
-function createAnnotationCapability(ctx, config = {}) {
-	const behaviors = [];
-	/** Per-annotation debounce timer for the engine text write while typing. */
-	const textTimers = /* @__PURE__ */ new Map();
-	/** The registered fonts, for face ↔ key mapping (the local engine's list;
-	*  the cloud engine registers none). */
-	const fonts = () => ctx.engine?.fonts?.list() ?? [];
-	const configTools = config.tools ?? [];
-	const registry = buildToolRegistry(configTools);
-	/** The installed file-picker port (a DOM file dialog, wired by the framework
-	*  adapter), or null — every click-then-pick tool resolves through this ONE
-	*  slot. See {@link FilePickerProvider}. */
-	let filePickerProvider = null;
-	const model = () => ctx.getState().model;
-	const actionsForHover = ctx.tryGet(ActionsToken);
-	const hoverFeed = actionsForHover ? createAnnotationHoverFeed(actionsForHover, (id) => model().byId[id] ?? null) : null;
-	const chromeSettings = () => ctx.getState().chrome;
-	/**
-	* Ids on a page whose Behavior is currently ENGAGED (form widgets under a
-	* fill tool): they render their own DOM, so hit-test/marquee must not see
-	* them. Resolved per event — engagement follows the active tool live.
-	*/
-	const inertIdsAt = (pon) => {
-		if (!behaviors.length) return void 0;
-		const m = model();
-		let out;
-		for (const id of m.order) {
-			const a = m.byId[id];
-			if (!a || a.pon !== pon) continue;
-			if (behaviors.some((b) => b.matches({
-				subtype: a.subtype,
-				ref: a.ref
-			}) && b.engaged())) (out ?? (out = /* @__PURE__ */ new Set())).add(id);
-		}
-		return out;
-	};
-	/** The CSS-px chrome settings converted to CONTENT units by the page's view
-	*  scale (px per content unit) — screen-constant grab zones + stalk at every
-	*  zoom. No scale → the values are read as content units (headless callers).
-	*  `boost` widens the GRAB tolerances only (never the drawn chrome or the
-	*  knob's position) — the touch path passes {@link TOUCH_GRAB_BOOST} so
-	*  handles present finger-sized targets. */
-	const chromeGeomAt = (scale, boost = 1) => {
-		const cs = chromeSettings();
-		const s = scale || 1;
-		return {
-			handleTol: cs.handles.hitSize / 2 / s * boost,
-			knobTol: cs.knob.hitSize / 2 / s * boost,
-			knobOffset: cs.knob.offset / s
-		};
-	};
-	/** Finger-sized grab zones: 2× the mouse tolerances lands a ~24px handle hit
-	*  box in Apple's ~44pt-target territory without moving any visuals. */
-	const TOUCH_GRAB_BOOST = 2;
-	const grabBoost = (touch) => touch ? TOUCH_GRAB_BOOST : 1;
-	const itemsCache = /* @__PURE__ */ new Map();
-	const chromeCache = /* @__PURE__ */ new Map();
-	const memoItems = (pon, view) => {
-		const m = model();
-		const g = ctx.getState().toolGhost;
-		const c = itemsCache.get(pon);
-		if (c && c.model === m && c.ghost === g && c.zoom === view?.zoom && c.rotation === view?.rotation) return c.v;
-		const v = pageItems(m, pon, view);
-		if (g && g.pon === pon && g.kind === "vector") {
-			const tool = registry.get(g.toolId);
-			const style = styleFromProps(defaultsFor(m, tool?.preset ?? g.toolId));
-			v.push({
-				id: "tool-ghost",
-				ref: null,
-				subtype: tool?.subtype ?? "square",
-				geom: g.geom,
-				box: g.box,
-				style,
-				source: "ghost",
-				selected: false
-			});
-		}
-		itemsCache.set(pon, {
-			model: m,
-			ghost: g,
-			zoom: view?.zoom,
-			rotation: view?.rotation,
-			v
-		});
-		return v;
-	};
-	const memoChrome = (pon, scale, rotation, zoom) => {
-		const m = model();
-		const cs = chromeSettings();
-		const c = chromeCache.get(pon);
-		if (c && c.model === m && c.cs === cs && c.scale === scale && c.rotation === rotation && c.zoom === zoom) return c.v;
-		let v = chrome(m, pon, pageBoxOf(pon), chromeGeomAt(scale).knobOffset, viewEnv(zoom, rotation));
-		if (!cs.guides.enabled) v = v.filter((n) => n.kind !== "rotate-guides");
-		chromeCache.set(pon, {
-			model: m,
-			cs,
-			scale,
-			rotation,
-			zoom,
-			v
-		});
-		return v;
-	};
-	let anchorCache = null;
-	const memoAnchor = (scale, rotation, zoom) => {
-		const m = model();
-		const cs = chromeSettings();
-		if (anchorCache && anchorCache.model === m && anchorCache.cs === cs && anchorCache.scale === scale && anchorCache.rotation === rotation && anchorCache.zoom === zoom) return anchorCache.v;
-		const v = selectionAnchor(m, pageBoxOf, () => chromeGeomAt(scale).knobOffset, () => viewEnv(zoom, rotation));
-		anchorCache = {
-			model: m,
-			cs,
-			scale,
-			rotation,
-			zoom,
-			v
-		};
-		return v;
-	};
-	let draftAnchorCache = null;
-	const memoDraftAnchor = () => {
-		const m = model();
-		if (draftAnchorCache && draftAnchorCache.model === m) return draftAnchorCache.v;
-		const v = creationDraftAnchor(m);
-		draftAnchorCache = {
-			model: m,
-			v
-		};
-		return v;
-	};
-	/** The editor's text RANGE inside the annotation being edited, or null
-	*  (no editor selection, a bare caret, or a selection left behind by a
-	*  previous edit). The one condition that routes the range keys to runs. */
-	const activeTextRange = (m) => {
-		const ts = ctx.getState().textSelection;
-		return ts && m.editing === ts.id && ts.end > ts.start && m.byId[ts.id] ? ts : null;
-	};
-	let selPropsCache = null;
-	const memoSelectionProps = () => {
-		const m = model();
-		const range = activeTextRange(m);
-		if (selPropsCache && selPropsCache.model === m && selPropsCache.range === range) return selPropsCache.v;
-		const members = m.selected.map((id) => m.byId[id]).filter((a) => !!a);
-		const specs = sharedProps(members.map((a) => a.subtype));
-		const values = {};
-		const mixed = [];
-		const valueOf = (a, key) => key === "link" && a.subtype !== "link" ? linkOf(m, a.id) : readProp(a, key);
-		for (const spec of specs) {
-			const first = valueOf(members[0], spec.key);
-			values[spec.key] = first;
-			const firstJson = JSON.stringify(first);
-			if (members.some((a) => JSON.stringify(valueOf(a, spec.key)) !== firstJson)) mixed.push(spec.key);
-		}
-		if (range && members.length === 1 && members[0].id === range.id) {
-			const rp = rangeProps(richDocOf(members[0], fonts), range, fonts);
-			for (const spec of specs) {
-				if (!RANGE_KEYS.includes(spec.key)) continue;
-				values[spec.key] = rp.values[spec.key];
-				const i = mixed.indexOf(spec.key);
-				if (i >= 0) mixed.splice(i, 1);
-				if (rp.mixed.includes(spec.key)) mixed.push(spec.key);
-			}
-		}
-		const v = {
-			specs,
-			values,
-			mixed
-		};
-		selPropsCache = {
-			model: m,
-			range,
-			v
-		};
-		return v;
-	};
-	const linkItemsCache = /* @__PURE__ */ new Map();
-	const memoLinkItems = (pon) => {
-		const m = model();
-		const c = linkItemsCache.get(pon);
-		if (c && c.model === m) return c.v;
-		const v = [];
-		for (const id of m.order) {
-			const a = m.byId[id];
-			if (!a || a.pon !== pon || a.subtype !== "link") continue;
-			if (!viewable(a.flags, false)) continue;
-			const target = a.link ?? (a.data?.subtype === "link" ? a.data.target ?? null : null);
-			if (target == null || a.geom.t !== "rect") continue;
-			const activate = a.data?.actions?.activate;
-			const ref = a.ref ?? a.data?.ref ?? void 0;
-			const hoverEnter = Boolean(a.data?.actions?.cursorEnter?.root);
-			const hoverExit = Boolean(a.data?.actions?.cursorExit?.root);
-			v.push({
-				id,
-				rect: a.geom.rect,
-				target,
-				attached: a.group !== void 0,
-				...activate ? { activate } : {},
-				...ref ? { ref } : {},
-				...hoverEnter || hoverExit ? { hoverEvents: {
-					enter: hoverEnter,
-					exit: hoverExit
-				} } : {}
-			});
-		}
-		linkItemsCache.set(pon, {
-			model: m,
-			v
-		});
-		return v;
-	};
-	const textsCache = /* @__PURE__ */ new Map();
-	const memoTexts = (pon, view) => {
-		const m = model();
-		const c = textsCache.get(pon);
-		if (c && c.model === m && c.zoom === view?.zoom && c.rotation === view?.rotation) return c.v;
-		const v = buildTextItems(m, pon, view);
-		textsCache.set(pon, {
-			model: m,
-			zoom: view?.zoom,
-			rotation: view?.rotation,
-			v
-		});
-		return v;
-	};
-	let selFlagsCache = null;
-	const memoSelectionFlags = () => {
-		const m = model();
-		if (selFlagsCache && selFlagsCache.model === m) return selFlagsCache.v;
-		const members = m.selected.map((id) => m.byId[id]).filter((a) => !!a);
-		let v = null;
-		if (members.length) {
-			v = {};
-			for (const key of FLAG_KEYS) {
-				const first = members[0].flags[key];
-				v[key] = members.every((a) => a.flags[key] === first) ? first : null;
-			}
-		}
-		selFlagsCache = {
-			model: m,
-			v
-		};
-		return v;
-	};
-	const cropOf = (pon) => ctx.document()?.pages.find((p) => p.pageObjectNumber === pon)?.boxes.crop ?? null;
-	/** The page's box in content space (origin at the crop top-left) — the box
-	*  pointer gestures clamp to, so annotations stay page-bound. */
-	const pageBoxOf = (pon) => {
-		const crop = cropOf(pon);
-		return crop ? {
-			x: 0,
-			y: 0,
-			width: crop.right - crop.left,
-			height: crop.top - crop.bottom
-		} : void 0;
-	};
-	/**
-	* The armed stamp-tool payload: the bytes the next click places, plus the
-	* PDF-point placement size (derived from the sniffed intrinsic aspect).
-	* Transient tool state — deliberately NOT in the model: it is never
-	* rendered, never synced, and dies with the tool.
-	*/
-	let armedStamp = null;
-	/** Fixed bytes as a provider: the same image at every size. */
-	const fixedPreview = (bytes, mimeType) => {
-		const preview = {
-			bytes,
-			...mimeType ? { mimeType } : {}
-		};
-		return async () => preview;
-	};
-	/**
-	* The desired stamp size (PDF points) from sniffed bytes: the image's
-	* INTRINSIC pixel dimensions taken 1:1 as points (the v2 rule — keep the
-	* artwork's own size, then clamp to the page at placement). A `targetWidth`
-	* override scales to that width, aspect preserved. Vector (PDF) stamps carry
-	* no sniffable dimensions — a caller-supplied `intrinsic` override (a stamp
-	* library knows its page size) keeps the true aspect; without one they fall
-	* back to a square target.
-	*/
-	const desiredStampSize = (meta, targetWidth, intrinsicOverride) => {
-		const intrinsic = intrinsicOverride && intrinsicOverride.width > 0 && intrinsicOverride.height > 0 ? intrinsicOverride : "width" in meta && meta.width > 0 ? {
-			width: meta.width,
-			height: meta.height
-		} : {
-			width: targetWidth ?? 150,
-			height: targetWidth ?? 150
-		};
-		if (targetWidth === void 0) return intrinsic;
-		return {
-			width: targetWidth,
-			height: targetWidth * (intrinsic.height / intrinsic.width)
-		};
-	};
-	const armStamp = async (input) => {
-		const resolved = await resolveBinarySource(input.source);
-		const meta = sniffBinaryMetadata(resolved.bytes);
-		if (!meta) throw new Error("[annotation] stamp source must be PNG, JPEG, or single-page PDF bytes");
-		let preview = null;
-		if (typeof input.preview === "function") preview = input.preview;
-		else if (input.preview) {
-			const p = await resolveBinarySource(input.preview);
-			preview = fixedPreview(new Uint8Array(p.bytes), p.mimeType);
-		} else if (meta.mimeType !== "application/pdf") preview = fixedPreview(new Uint8Array(resolved.bytes), meta.mimeType);
-		armedStamp = {
-			source: input.source,
-			...desiredStampSize(meta, input.targetWidth, input.intrinsicSize),
-			preview,
-			previewCache: /* @__PURE__ */ new Map(),
-			...input.name !== void 0 ? { name: input.name } : {},
-			...input.subject !== void 0 ? { subject: input.subject } : {}
-		};
-		ctx.dispatch({ type: "STAMP_ARM_CHANGED" });
-		ctx.tryGet(InteractionToken)?.activateTool(ARMED_STAMP_TOOL_ID);
-	};
-	const disarmStamp = () => {
-		if (!armedStamp) return;
-		armedStamp = null;
-		ctx.dispatch({ type: "STAMP_ARM_CHANGED" });
-	};
-	/** Move the hover FOOTPRINT ghost to a content point. The box/geometry is
-	*  computed by the SAME rules the click's placement uses ({@link createStampAt}
-	*  fit + clamp for an armed stamp; the click-create anchor + page clamp for a
-	*  draw tool), so the ghost is the placement, not an approximation of it. */
-	const ghostHoverAt = (toolId, pon, point, displayRotation) => {
-		const tool = registry.get(toolId);
-		const crop = cropOf(pon);
-		if (!tool || tool.ghost === false || !crop) {
-			clearGhost();
-			return;
-		}
-		const page = {
-			width: crop.right - crop.left,
-			height: crop.top - crop.bottom
-		};
-		if (armedStamp) {
-			const rot = uprightRotFor(displayRotation);
-			const box = fitStampBox(point, {
-				width: armedStamp.width,
-				height: armedStamp.height
-			}, page, rot);
-			ctx.dispatch({
-				type: "SET_TOOL_GHOST",
-				ghost: {
-					pon,
-					box,
-					rot,
-					kind: "image"
-				}
-			});
-			return;
-		}
-		if (isIconPlaceKind(tool.subtype)) {
-			const box = fitStampBox(point, ICON_PLACE_SIZE, page, uprightRotFor(displayRotation));
-			dispatchVectorGhost(pon, toolId, {
-				t: "rect",
-				rect: box,
-				ellipse: false
-			});
-			return;
-		}
-		if (!tool.clickCreate) {
-			clearGhost();
-			return;
-		}
-		const placement = resolveClickPlacement(point, tool.clickCreate, {
-			pageBox: {
-				x: 0,
-				y: 0,
-				width: page.width,
-				height: page.height
-			},
-			upright: tool.upright,
-			displayRotation
-		});
-		const geom = clickCreateGeom(tool.subtype, placement, defaultsFor(model(), tool.preset));
-		if (!geom) {
-			clearGhost();
-			return;
-		}
-		dispatchVectorGhost(pon, toolId, geom);
-	};
-	/** Paint a vector ghost item for a tool's would-be geometry — shared by the
-	*  hover footprint and the externally-driven placement preview. */
-	const dispatchVectorGhost = (pon, toolId, geom) => {
-		const tool = registry.get(toolId);
-		const style = styleFromProps(defaultsFor(model(), tool?.preset ?? toolId));
-		ctx.dispatch({
-			type: "SET_TOOL_GHOST",
-			ghost: {
-				pon,
-				box: geomVisualBounds(geom, style.strokeWidth, style.border),
-				rot: 0,
-				kind: "vector",
-				toolId,
-				geom
-			}
-		});
-	};
-	/**
-	* Drive the placement preview during an EXTERNALLY-owned creation gesture
-	* (the form plugin's drag-to-place): paint the box the commit would use,
-	* styled from the TOOL's defaults, through the same ghost pipeline as every
-	* footprint. The box is clamped to the page (a drag may overshoot).
-	*/
-	const setPlacementPreview = (toolId, pon, box) => {
-		const crop = cropOf(pon);
-		if (!crop) return;
-		const page = {
-			width: crop.right - crop.left,
-			height: crop.top - crop.bottom
-		};
-		const x = Math.max(0, Math.min(box.x, page.width));
-		const y = Math.max(0, Math.min(box.y, page.height));
-		const rect = {
-			x,
-			y,
-			width: Math.max(0, Math.min(box.x + box.width, page.width) - x),
-			height: Math.max(0, Math.min(box.y + box.height, page.height) - y)
-		};
-		dispatchVectorGhost(pon, toolId, {
-			t: "rect",
-			rect,
-			ellipse: false
-		});
-	};
-	const clearGhost = () => {
-		if (ctx.getState().toolGhost) ctx.dispatch({
-			type: "SET_TOOL_GHOST",
-			ghost: null
-		});
-	};
-	/** Place a stamp of `desired` PDF-point size centred on a content point — the
-	*  one engine-write both the armed and click-to-place paths funnel through.
-	*  The size is fit to the page and clamped fully onto it (v2 rubber-stamp
-	*  rule: never larger than the page, aspect preserved), and never spills off
-	*  the edge. `rotCW` (the tool's upright counter-rotation, CW content degrees)
-	*  emits the repository's box rotation fields — the engine bakes the tilted
-	*  /AP exactly as an interactively rotated stamp round-trips, and the fit uses
-	*  the ROTATED footprint. Returns false when the page/document isn't ready. */
-	const createStampAt = (pon, point, source, desired, rotCW = 0, identity = {}) => {
-		const doc = ctx.doc;
-		const crop = cropOf(pon);
-		if (!doc || !crop) return null;
-		const box = fitStampBox(point, desired, {
-			width: crop.right - crop.left,
-			height: crop.top - crop.bottom
-		}, rotCW);
-		return doc.page(pon).annotations.create({
-			subtype: "stamp",
-			...boxGeomFields(box, rotCW, crop),
-			source,
-			fit: "contain",
-			...identity.name !== void 0 ? { name: identity.name } : {},
-			...identity.subject !== void 0 ? { subject: identity.subject } : {}
-		}).then((res) => {
-			syncDTO(res.created, "baked");
-			apply({
-				t: "select",
-				ids: [refKey(res.created.ref)]
-			});
-			return res.created.ref;
-		});
-	};
-	/** The click path's fire-and-forget wrapper: a rejected placement is logged,
-	*  never thrown into the gesture. */
-	const createStampAtSync = (pon, point, source, desired, rotCW = 0, identity = {}) => {
-		const placed = createStampAt(pon, point, source, desired, rotCW, identity);
-		if (!placed) return false;
-		placed.catch((err) => console.error("[annotation] stamp placement failed:", err));
-		return true;
-	};
-	/** Programmatic placement — the same law as a click, awaited. */
-	const placeStamp = async (input, placement) => {
-		const meta = sniffBinaryMetadata((await resolveBinarySource(input.source)).bytes);
-		if (!meta) throw new Error("[annotation] stamp source must be PNG, JPEG, or single-page PDF bytes");
-		const placed = createStampAt(placement.pageObjectNumber, placement.at, input.source, desiredStampSize(meta, placement.targetWidth ?? input.targetWidth, input.intrinsicSize), placement.rotation ?? 0, {
-			...input.name !== void 0 ? { name: input.name } : {},
-			...input.subject !== void 0 ? { subject: input.subject } : {}
-		});
-		if (!placed) throw new Error(`[annotation] cannot place a stamp on page ${placement.pageObjectNumber}: document or page not ready`);
-		return placed;
-	};
-	/** The active tool's upright counter-rotation for a click at `displayRotation`
-	*  (0 when the tool doesn't ask for upright, or the display isn't rotated). */
-	const uprightRotFor = (displayRotation) => {
-		if (!displayRotation) return 0;
-		const ix = ctx.tryGet(InteractionToken);
-		return (ix ? registry.get(ix.activeToolId()) : void 0)?.upright ? uprightRotation(displayRotation) : 0;
-	};
-	const placeArmedStamp = (pon, point, displayRotation) => {
-		const armed = armedStamp;
-		if (!armed) return false;
-		return createStampAtSync(pon, point, armed.source, {
-			width: armed.width,
-			height: armed.height
-		}, uprightRotFor(displayRotation), {
-			...armed.name !== void 0 ? { name: armed.name } : {},
-			...armed.subject !== void 0 ? { subject: armed.subject } : {}
-		});
-	};
-	/** Sniff a stamp source (rejecting non-image bytes) and place it at its
-	*  intrinsic size (fit to the page in {@link createStampAt}); `targetWidth`
-	*  overrides the width, aspect preserved. */
-	const placeStampSource = async (pon, point, source, rotCW, targetWidth) => {
-		const meta = sniffBinaryMetadata((await resolveBinarySource(source)).bytes);
-		if (!meta) {
-			console.error("[annotation] stamp source must be PNG, JPEG, or single-page PDF bytes");
-			return;
-		}
-		createStampAtSync(pon, point, source, desiredStampSize(meta, targetWidth), rotCW);
-	};
-	/**
-	* Click-to-place: resolve the ACTIVE tool's source spec. Fixed `bytes` place
-	* immediately; a `'prompt'` source asks the installed provider, then places on
-	* resolve — dropping the placement if it was cancelled, or if the tool or
-	* document changed while the picker was open (the intent expired).
-	*/
-	const requestStampAt = (pon, point, displayRotation) => {
-		const ix = ctx.tryGet(InteractionToken);
-		const tool = ix ? registry.get(ix.activeToolId()) : void 0;
-		const spec = tool?.source;
-		if (!spec) return false;
-		const rotCW = tool.upright && displayRotation ? uprightRotation(displayRotation) : 0;
-		if (spec.kind === "bytes") {
-			placeStampSource(pon, point, spec.source, rotCW);
-			return true;
-		}
-		return promptFileAt(tool, pon, point, (picked) => void placeStampSource(pon, point, picked.data, rotCW));
-	};
-	/**
-	* Run the installed file-picker port for a click-then-pick tool, with the
-	* shared expiry rule: the placement is dropped if the picker cancels, or if
-	* the document or the active tool changed while it was open (the intent
-	* expired with the click). No provider installed → decline the click (let a
-	* lower-priority handler act) rather than swallow it.
-	*/
-	const promptFileAt = (tool, pon, point, place) => {
-		const provider = filePickerProvider;
-		if (!provider) return false;
-		const spec = tool.source;
-		const req = {
-			toolId: tool.id,
-			subtype: tool.subtype,
-			accept: spec?.kind === "prompt" ? spec.accept : void 0,
-			pon,
-			point
-		};
-		const docAtClick = ctx.doc;
-		provider(req).then((picked) => {
-			if (!picked) return;
-			if (ctx.doc !== docAtClick) return;
-			if (ctx.tryGet(InteractionToken)?.activeToolId() !== tool.id) return;
-			place(picked);
-		}, (err) => console.error("[annotation] file-picker provider failed:", err));
-		return true;
-	};
-	/** Place a fixed-size ICON annotation (note / file attachment) centred on a
-	*  content point — the icon-kind sibling of {@link createStampAt}. The
-	*  engine bakes the 20×20 /AP from /C + /Name; a successful create selects
-	*  the new annotation (the anchor for its menu / future comment popup). */
-	const createIconAt = (tool, pon, point, rotCW, file) => {
-		const doc = ctx.doc;
-		const crop = cropOf(pon);
-		if (!doc || !crop || !isIconPlaceKind(tool.subtype)) return false;
-		const box = fitStampBox(point, ICON_PLACE_SIZE, {
-			width: crop.right - crop.left,
-			height: crop.top - crop.bottom
-		}, rotCW);
-		const draft = iconPlacementDraft(tool.subtype, boxGeomFields(box, rotCW, crop), defaultsFor(model(), tool.preset), tool.flags, file);
-		doc.page(pon).annotations.create(draft).then((res) => {
-			syncDTO(res.created, "baked");
-			apply({
-				t: "select",
-				ids: [refKey(res.created.ref)]
-			});
-		}, (err) => console.error("[annotation] icon placement failed:", err));
-		return true;
-	};
-	/**
-	* The ONE click-to-place entry the place handler forwards every down to —
-	* armed payload first, then the active tool's kind decides:
-	*   - stamp        → the source spec (fixed bytes, or the file-picker port)
-	*   - note (text)  → place immediately (no payload)
-	*   - attachment   → spot first, file second: the file-picker port opens
-	*                    inside the click gesture, and placement lands when it
-	*                    resolves (dropped on cancel, or if the tool/document
-	*                    changed while the picker was open).
-	* Returns whether the click was consumed.
-	*/
-	const placeAt = (pon, point, displayRotation) => {
-		if (placeArmedStamp(pon, point, displayRotation)) return true;
-		const ix = ctx.tryGet(InteractionToken);
-		const tool = ix ? registry.get(ix.activeToolId()) : void 0;
-		if (!tool) return false;
-		if (tool.subtype === "stamp") return requestStampAt(pon, point, displayRotation);
-		if (!isIconPlaceKind(tool.subtype)) return false;
-		const rotCW = tool.upright && displayRotation ? uprightRotation(displayRotation) : 0;
-		if (tool.subtype === "text") return createIconAt(tool, pon, point, rotCW, null);
-		return promptFileAt(tool, pon, point, (picked) => createIconAt(tool, pon, point, rotCW, picked));
-	};
-	/** The page a ref lives on: from the loaded model first (covers obj/nm refs
-	*  that don't carry a pon), else the ref itself (index refs do). */
-	const ponForRef = (ref) => model().byId[refKey(ref)]?.pon ?? (ref.kind === "index" ? ref.pageObjectNumber : null);
-	/**
-	* Re-sync one annotation into the model from the authoritative engine DTO,
-	* with the render `source` the caller decides: `'vector'` when WE authored or
-	* changed the appearance (create / restyle / resize), `'baked'` when the AP is
-	* still authoritative (a move, which preserves it, or a remote edit).
-	* `bumpAp` marks the upsert as confirming an engine /AP re-bake with new
-	* content, so the annotation's `apVersion` — and with it the page's
-	* appearance epoch — advances and the shell fetches the fresh raster.
-	*/
-	const syncDTO = (dto, source, bumpAp = false) => {
-		const crop = cropOf(dto.pageObjectNumber);
-		if (crop) apply({
-			t: "upsert",
-			annots: [ingestDTO(dto, crop, source)],
-			bumpAp
-		});
-	};
-	/** The one engine-update path, shared by `update` and `updateSelection`. A
-	*  programmatic patch changes the appearance → render live (vector). */
-	const updateOne = async (ref, patch) => {
-		const doc = ctx.doc;
-		if (!doc) throw new Error("[annotation] no document bound");
-		const pon = ponForRef(ref);
-		if (pon == null) throw new Error("[annotation] cannot resolve page for ref");
-		const res = await doc.page(pon).annotations.update(ref, patch);
-		syncDTO(res.updated, "vector");
-	};
-	const commitText = (ref) => {
-		const key = refKey(ref);
-		clearTimeout(textTimers.get(key));
-		textTimers.delete(key);
-		const a = model().byId[key];
-		const pon = ponForRef(ref);
-		if (!a || pon == null) return;
-		const patch = textCommitPatch(a, richDocOf(a, fonts).paragraphs, fonts);
-		ctx.doc?.page(pon).annotations.update(ref, {
-			subtype: "free-text",
-			...patch
-		}).then(() => {}, () => {});
-	};
-	const scheduleTextCommit = (ref) => {
-		const key = refKey(ref);
-		clearTimeout(textTimers.get(key));
-		textTimers.set(key, setTimeout(() => commitText(ref), TEXT_COMMIT_DEBOUNCE_MS));
-	};
-	const flushTextCommits = () => {
-		for (const key of [...textTimers.keys()]) {
-			const a = model().byId[key];
-			if (a?.ref) commitText(a.ref);
-			else {
-				clearTimeout(textTimers.get(key));
-				textTimers.delete(key);
-			}
-		}
-	};
-	function apply(msg) {
-		const [next, effects] = update(model(), msg);
-		ctx.dispatch({
-			type: "SET_MODEL",
-			model: next
-		});
-		for (const fx of effects) perform(fx, next);
-	}
-	let hydrationStarted = false;
-	let hydrationWindow = false;
-	let hydrationRunning = null;
-	let hydrateAgain = false;
-	const pendingRemote = [];
-	const setHydration = (hydration) => ctx.dispatch({
-		type: "SET_HYDRATION",
-		hydration
-	});
-	const ingestSnapshot = (snap, bumpAp) => {
-		const annots = [];
-		for (const page of snap.pages) {
-			const crop = cropOf(page.pageState.pageObjectNumber);
-			if (!crop) continue;
-			annots.push(...page.annotations.map((d) => ingestDTO(d, crop)));
-		}
-		apply({
-			t: "hydrated",
-			annots,
-			bumpAp
-		});
-	};
-	const canRead = () => ctx.doc?.security.allows("doc.annotate.read") ?? true;
-	const runHydration = (bumpAp) => {
-		const doc = ctx.doc;
-		if (!doc) return Promise.resolve();
-		if (!canRead()) {
-			setHydration({ status: "forbidden" });
-			return Promise.resolve();
-		}
-		hydrationWindow = true;
-		setHydration({ status: "loading" });
-		const run = doc.annotations.listRawAll().then((snap) => {
-			ingestSnapshot(snap, bumpAp);
-			const head = snap.auditHead;
-			const queued = pendingRemote.splice(0);
-			hydrationWindow = false;
-			for (const event of queued) {
-				const serverId = "origin" in event ? event.origin.serverId : null;
-				if (head !== void 0 && serverId !== null && serverId <= head) continue;
-				applyRemoteAnnotationEvent(event);
-			}
-			setHydration({ status: "complete" });
-		}).catch((error) => {
-			hydrationWindow = false;
-			for (const event of pendingRemote.splice(0)) applyRemoteAnnotationEvent(event);
-			setHydration({
-				status: "error",
-				error
-			});
-		}).finally(() => {
-			hydrationRunning = null;
-			if (hydrateAgain) {
-				hydrateAgain = false;
-				hydrationRunning = runHydration(true);
-			}
-		});
-		hydrationRunning = run;
-		return run;
-	};
-	const rehydrate = () => {
-		if (hydrationRunning) {
-			hydrateAgain = true;
-			return hydrationRunning;
-		}
-		hydrationRunning = runHydration(true);
-		return hydrationRunning;
-	};
-	/**
-	* Fold one REMOTE annotation event into the model (transplanted from the
-	* effects layer so hydration can queue + replay through the same code
-	* path). `bump` re-fetches rasters, `keep` doesn't — driven by the
-	* ENGINE'S appearance echo riding the event, so a remote MOVE costs
-	* peers zero re-renders while a remote restyle refreshes exactly once.
-	*/
-	const upsertRemote = (dtos, bumpAp) => {
-		const bump = [];
-		const keep = [];
-		for (const dto of dtos) {
-			const crop = cropOf(dto.pageObjectNumber);
-			if (!crop) continue;
-			const a = ingestDTO(dto, crop, "baked");
-			(bumpAp && !isSubstrateOnly(a) ? bump : keep).push(a);
-		}
-		if (bump.length) apply({
-			t: "upsert",
-			annots: bump,
-			bumpAp: true
-		});
-		if (keep.length) apply({
-			t: "upsert",
-			annots: keep
-		});
-	};
-	const applyRemoteAnnotationEvent = (event) => {
-		switch (event.type) {
-			case "annotation.created":
-				upsertRemote([event.created], true);
-				break;
-			case "annotation.updated":
-				upsertRemote([event.updated], event.appearance.changed);
-				break;
-			case "annotation.moved":
-				upsertRemote(event.moved, false);
-				break;
-			case "annotation.deleted":
-				if (event.deleted) {
-					const key = encodeStableIdKey(event.deleted);
-					if (model().byId[key]) apply({
-						t: "remove",
-						ids: [key]
-					});
-				}
-				break;
-			default: break;
-		}
-	};
-	const currentUserId = () => ctx.doc?.security.identity?.user_id;
-	let threadsMemo = null;
-	/** Value-stable layout key: display order is all the sort consumes, so
-	*  the memo must survive hosts that rebuild the pages array per read. */
-	const layoutSignature = () => (ctx.document()?.pages ?? []).map((p) => p.pageObjectNumber).join(",");
-	const computeThreadsIndex = () => {
-		const m = model();
-		const dtos = [];
-		for (const id of m.order) {
-			const data = m.byId[id]?.data;
-			if (data) dtos.push(data);
-		}
-		const threads = buildCommentThreads(dtos, { currentUserId: currentUserId() });
-		const pages = ctx.document()?.pages ?? [];
-		const displayIndex = new Map(pages.map((p, i) => [p.pageObjectNumber, i]));
-		threads.sort((a, b) => {
-			const pa = displayIndex.get(a.pageObjectNumber) ?? Number.MAX_SAFE_INTEGER;
-			const pb = displayIndex.get(b.pageObjectNumber) ?? Number.MAX_SAFE_INTEGER;
-			if (pa !== pb) return pa - pb;
-			if (a.root.rect.top !== b.root.rect.top) return b.root.rect.top - a.root.rect.top;
-			const ca = a.root.created ?? "";
-			const cb = b.root.created ?? "";
-			return ca < cb ? -1 : ca > cb ? 1 : 0;
-		});
-		const byMember = /* @__PURE__ */ new Map();
-		for (const t of threads) {
-			byMember.set(refKey(t.root.ref), t);
-			for (const r of t.replies) byMember.set(refKey(r.ref), t);
-			for (const g of t.groupedParts) byMember.set(refKey(g.ref), t);
-			for (const s of t.review.statusRefs) byMember.set(refKey(s), t);
-		}
-		return {
-			threads,
-			byMember
-		};
-	};
-	const threadsIndex = () => {
-		const m = model();
-		const layout = layoutSignature();
-		const userId = currentUserId();
-		if (threadsMemo && threadsMemo.byId === m.byId && threadsMemo.order === m.order && threadsMemo.layout === layout && threadsMemo.userId === userId) return threadsMemo;
-		threadsMemo = {
-			...computeThreadsIndex(),
-			byId: m.byId,
-			order: m.order,
-			layout,
-			userId
-		};
-		return threadsMemo;
-	};
-	const threadOf = (ref) => {
-		const t = threadsIndex().byMember.get(refKey(ref));
-		if (!t) throw new Error("[annotation] no comment thread contains this ref");
-		return t;
-	};
-	/** Engine create + model sync for conversation-plane annotations (they
-	*  never paint, so the render source is immaterial — 'baked' avoids any
-	*  vector-scene work). */
-	const createConversationAnnot = async (pon, draft) => {
-		const doc = ctx.doc;
-		if (!doc) throw new Error("[annotation] no document bound");
-		const res = await doc.page(pon).annotations.create(draft);
-		syncDTO(res.created, "baked");
-		return res.created;
-	};
-	const deleteOne = async (ref) => {
-		const doc = ctx.doc;
-		if (!doc) throw new Error("[annotation] no document bound");
-		await doc.page(ref.pageObjectNumber).annotations.delete(ref);
-		apply({
-			t: "remove",
-			ids: [refKey(ref)]
-		});
-	};
-	const REPLY_FLAGS = {
-		print: true,
-		noZoom: true,
-		noRotate: true
-	};
-	const STATUS_FLAGS = {
-		hidden: true,
-		noZoom: true,
-		noRotate: true
-	};
-	/** Coarse authority mirror (doc.annotate.modify) — B3 replaces this with
-	*  the collab-scope mirrors; the FLAG split is already the real rule. */
-	const mutationTarget = (ref) => {
-		const d = model().byId[refKey(ref)]?.data;
-		return {
-			...d?.userId !== void 0 ? { userId: d.userId } : {},
-			...d?.groupId !== void 0 ? { groupId: d.groupId } : {}
-		};
-	};
-	const allowsCreate = () => ctx.doc?.security.allowsAnnotationCreate() ?? false;
-	/**
-	* Ingest an engine DTO with this session's per-record AUTHORITY projected
-	* onto it (permissions.md) — asked of the SAME mirrors the server enforces
-	* with, against the record's stamped owner. Fused into
-	* `annotTransformable`/`annotDeletable`, so hit-test, chrome, props and
-	* delete all agree with the engine by construction. No security context
-	* (bare local engines, tests) → unstamped → allowed; the engine enforces.
-	*/
-	const ingestDTO = (dto, crop, source) => {
-		const a = fromDTO(dto, crop, source);
-		const sec = ctx.doc?.security;
-		if (!sec) return a;
-		const target = {
-			...dto.userId !== void 0 ? { userId: dto.userId } : {},
-			...dto.groupId !== void 0 ? { groupId: dto.groupId } : {}
-		};
-		return {
-			...a,
-			authority: {
-				update: sec.allowsAnnotationMutation("update", target),
-				delete: sec.allowsAnnotationMutation("delete", target)
-			}
-		};
-	};
-	const allowsMutation = (action, ref) => ctx.doc?.security.allowsAnnotationMutation(action, mutationTarget(ref)) ?? false;
-	const deletableOne = (ref) => {
-		const a = model().byId[refKey(ref)];
-		return !!a && annotDeletable(a);
-	};
-	const threadMemberRefs = (t) => [
-		...t.replies.map((r) => r.ref),
-		...t.groupedParts.map((g) => g.ref),
-		...t.review.statusRefs,
-		t.root.ref
-	];
-	const comments = {
-		threads: () => threadsIndex().threads,
-		thread: (ref) => threadsIndex().byMember.get(refKey(ref)) ?? null,
-		hydration: () => ctx.getState().hydration,
-		rehydrate,
-		reply: async (ref, text) => {
-			const t = threadOf(ref);
-			return (await createConversationAnnot(t.pageObjectNumber, {
-				subtype: "text",
-				rect: t.root.rect,
-				icon: "comment",
-				contents: text,
-				inReplyTo: t.root.ref,
-				flags: { ...REPLY_FLAGS }
-			})).ref;
-		},
-		edit: async (ref, text) => {
-			const subtype = model().byId[refKey(ref)]?.data?.subtype;
-			if (!subtype) throw new Error("[annotation] cannot edit an uncommitted annotation");
-			await updateOne(ref, {
-				subtype,
-				contents: text
-			});
-		},
-		setStatus: async (ref, state) => {
-			const t = threadOf(ref);
-			const userId = currentUserId();
-			const previous = userId ? t.review.byReviewer[userId] : void 0;
-			await createConversationAnnot(t.pageObjectNumber, {
-				subtype: "text",
-				rect: t.root.rect,
-				inReplyTo: previous?.ref ?? t.root.ref,
-				state,
-				stateModel: "review",
-				flags: { ...STATUS_FLAGS }
-			});
-		},
-		setMarked: async (ref, marked) => {
-			const t = threadOf(ref);
-			await createConversationAnnot(t.pageObjectNumber, {
-				subtype: "text",
-				rect: t.root.rect,
-				inReplyTo: t.root.ref,
-				state: marked ? "marked" : "unmarked",
-				stateModel: "marked",
-				flags: { ...STATUS_FLAGS }
-			});
-		},
-		remove: deleteOne,
-		removeThread: async (ref) => {
-			const t = threadOf(ref);
-			const members = threadMemberRefs(t);
-			const blocked = members.filter((r) => !deletableOne(r));
-			if (blocked.length > 0) return {
-				deleted: [],
-				failed: blocked.map((r) => ({
-					ref: r,
-					error: /* @__PURE__ */ new Error("delete not permitted")
-				}))
-			};
-			const deleted = [];
-			const failed = [];
-			for (const member of members) {
-				if (failed.length > 0) break;
-				try {
-					await deleteOne(member);
-					deleted.push(member);
-				} catch (error) {
-					failed.push({
-						ref: member,
-						error
-					});
-				}
-			}
-			return {
-				deleted,
-				failed
-			};
-		},
-		permissionsFor: (ref) => {
-			model().byId[refKey(ref)]?.flags;
-			const t = threadsIndex().byMember.get(refKey(ref)) ?? null;
-			return {
-				canReply: allowsCreate(),
-				canSetStatus: allowsCreate(),
-				canEditText: (() => {
-					const a = model().byId[refKey(ref)];
-					return !!a && annotContentsEditable(a);
-				})(),
-				canDelete: deletableOne(ref),
-				canDeleteThread: t !== null && threadMemberRefs(t).every(deletableOne)
-			};
-		}
-	};
-	/**
-	* Per-parent serialization of attached-link reconciles: rapid edits chain
-	* instead of interleaving (two overlapping runs could double-create
-	* children). Each run reads the CURRENT model at execution time, so a
-	* chained run converges on the latest desired state.
-	*/
-	const linkSyncChains = /* @__PURE__ */ new Map();
-	/**
-	* Queue a reconcile. `intent` is either an explicit target (a set/clear —
-	* captured by THIS run's closure, so chained sets stay latest-wins) or
-	* `'keep'` (a geometry follow: re-rect the children toward whatever target
-	* the substrate holds AT RUN TIME — so a remote retarget is never undone
-	* by a local move). Returns the chain, so `links.set()` can await commit.
-	*/
-	const scheduleLinkSync = (id, intent) => {
-		const next = (linkSyncChains.get(id) ?? Promise.resolve()).then(() => reconcileLinkChildren(id, intent === "keep" ? linkOf(model(), id) : intent.target));
-		linkSyncChains.set(id, next);
-		next.finally(() => {
-			if (linkSyncChains.get(id) === next) linkSyncChains.delete(id);
-		});
-		return next;
-	};
-	/**
-	* THE one place attached link children are created, retargeted, re-rected,
-	* or deleted. Declarative: desired state = `desired` target + the parent's
-	* committed geometry (`linkChildRects`); CURRENT state is read straight
-	* from the substrate (`linkChildrenOf`) — no join-key ledger. Results land
-	* as ordinary substrate upserts/removes, so the `linkOf` lens converges
-	* immediately locally and via events everywhere else. Idempotent — foreign
-	* inconsistencies heal on the next local edit.
-	*/
-	const reconcileLinkChildren = async (id, desired) => {
-		const doc = ctx.doc;
-		const a = model().byId[id];
-		if (!doc || !a || !a.ref || a.subtype === "link") return;
-		const crop = cropOf(a.pon);
-		if (!crop) return;
-		const page = doc.page(a.pon);
-		const target = writableTarget(desired);
-		const rects = desired == null ? [] : linkChildRects(a).map((r) => contentToPdfRect(r, crop));
-		const current = linkChildrenOf(model(), id);
-		try {
-			const paired = Math.min(current.length, rects.length);
-			for (let i = 0; i < paired; i++) {
-				const ref = current[i].ref;
-				if (!ref) continue;
-				const res = await page.annotations.update(ref, {
-					subtype: "link",
-					rect: rects[i],
-					...target ? { target } : {}
-				});
-				apply({
-					t: "upsert",
-					annots: [ingestDTO(res.updated, crop, "baked")]
-				});
-			}
-			for (let i = current.length; i < rects.length; i++) {
-				const res = await page.annotations.create({
-					subtype: "link",
-					rect: rects[i],
-					target,
-					inReplyTo: a.ref,
-					replyType: "group"
-				});
-				apply({
-					t: "upsert",
-					annots: [ingestDTO(res.created, crop, "baked")]
-				});
-			}
-			for (let i = rects.length; i < current.length; i++) {
-				const child = current[i];
-				if (child.ref) await page.annotations.delete(child.ref);
-				apply({
-					t: "remove",
-					ids: [child.id]
-				});
-			}
-		} catch (err) {
-			console.error("[annotation] attached-link sync failed:", err);
-		}
-	};
-	/** A relationship-only engine patch (sets/clears `/IRT` + `/RT`) — geometry and
-	*  style are left untouched, so grouping never re-bakes an appearance. */
-	const relationshipPatch = (subtype, rel) => ({
-		subtype,
-		...rel
-	});
-	/** Write a relationship change to one committed annotation and re-sync it from
-	*  the authoritative DTO (preserving its render source — relationships don't
-	*  change the appearance). */
-	const writeRelationship = async (a, rel) => {
-		const doc = ctx.doc;
-		if (!doc || !a.ref || !a.data) return;
-		const res = await doc.page(a.pon).annotations.update(a.ref, relationshipPatch(a.data.subtype, rel));
-		syncDTO(res.updated, a.source);
-	};
-	/** Committed, data-backed annotations in the current selection. */
-	const selectedCommitted = () => {
-		const m = model();
-		return m.selected.map((id) => m.byId[id]).filter((a) => !!a && !!a.ref && !!a.data);
-	};
-	function perform(fx, m) {
-		const doc = ctx.doc;
-		if (!doc) return;
-		if (fx.fx === "createGroup") {
-			const ids = [fx.primary, ...fx.members];
-			const annots = ids.map((id) => m.byId[id]);
-			const primary = annots[0];
-			if (!primary || annots.some((a) => !a || a.pon !== primary.pon)) {
-				apply({
-					t: "remove",
-					ids
-				});
-				return;
-			}
-			const crop = cropOf(primary.pon);
-			const drafts = crop ? annots.map((a) => a ? toCreateDraft(a, crop) : null) : annots.map(() => null);
-			if (drafts.some((d) => !d)) {
-				apply({
-					t: "remove",
-					ids
-				});
-				return;
-			}
-			(async () => {
-				const committed = [];
-				try {
-					const page = doc.page(primary.pon);
-					const primaryResult = await page.annotations.create(drafts[0]);
-					committed.push({
-						tempId: fx.primary,
-						ref: primaryResult.created.ref
-					});
-					apply({
-						t: "created",
-						tempId: fx.primary,
-						id: refKey(primaryResult.created.ref),
-						ref: primaryResult.created.ref
-					});
-					syncDTO(primaryResult.created, "vector");
-					for (let i = 0; i < fx.members.length; i++) {
-						const tempId = fx.members[i];
-						const draft = {
-							...drafts[i + 1],
-							inReplyTo: primaryResult.created.ref,
-							replyType: "group"
-						};
-						const result = await page.annotations.create(draft);
-						committed.push({
-							tempId,
-							ref: result.created.ref
-						});
-						apply({
-							t: "created",
-							tempId,
-							id: refKey(result.created.ref),
-							ref: result.created.ref
-						});
-						syncDTO(result.created, "vector");
-					}
-				} catch (error) {
-					const removeIds = ids.filter((id) => !committed.some((c) => c.tempId === id));
-					for (const part of [...committed].reverse()) try {
-						await doc.page(primary.pon).annotations.delete(part.ref);
-						removeIds.push(refKey(part.ref));
-					} catch {}
-					if (removeIds.length) apply({
-						t: "remove",
-						ids: removeIds
-					});
-					console.error("[annotation] grouped annotation creation failed:", error);
-				}
-			})();
-		} else if (fx.fx === "create") {
-			const a = m.byId[fx.id];
-			const crop = a && cropOf(a.pon);
-			const draft = a && crop ? toCreateDraft(a, crop) : null;
-			if (!a || !draft) return;
-			doc.page(a.pon).annotations.create(draft).then((res) => {
-				apply({
-					t: "created",
-					tempId: fx.id,
-					id: refKey(res.created.ref),
-					ref: res.created.ref
-				});
-				syncDTO(res.created, "vector");
-			}, () => apply({
-				t: "createFailed",
-				tempId: fx.id
-			}));
-		} else if (fx.fx === "flags") {
-			const a = m.byId[fx.id];
-			if (!a || !a.ref || !a.data) return;
-			doc.page(a.pon).annotations.update(a.ref, {
-				subtype: a.data.subtype,
-				flags: a.flags
-			}).then((res) => syncDTO(res.updated, a.source), (err) => console.error("[annotation] flags write failed:", err));
-		} else if (fx.fx === "patch") {
-			const a = m.byId[fx.id];
-			const crop = a && cropOf(a.pon);
-			const patch = a && a.ref && crop ? toScopedPatch(a, fx.scope, crop) : null;
-			if (!a || !a.ref || !patch) return;
-			doc.page(a.pon).annotations.update(a.ref, patch).then((res) => {
-				syncDTO(res.updated, a.source, res.appearance.changed);
-				if (linkChildrenOf(model(), fx.id).length) scheduleLinkSync(fx.id, "keep");
-			}, () => {
-				if (a.data && crop) apply({
-					t: "upsert",
-					annots: [ingestDTO(a.data, crop, a.source)]
-				});
-			});
-		} else if (fx.fx === "syncLink") scheduleLinkSync(fx.id, { target: fx.target });
-		else {
-			refKey(fx.ref);
-			doc.page(fx.ref.pageObjectNumber).annotations.delete(fx.ref).then(() => {}, () => {});
-		}
-	}
-	const reloadPageNow = async (pon) => {
-		const doc = ctx.doc;
-		const crop = cropOf(pon);
-		if (!doc || !crop) return;
-		try {
-			const snap = await doc.page(pon).annotations.list();
-			const m = model();
-			const stale = m.order.filter((id) => m.byId[id]?.pon === pon);
-			if (stale.length) apply({
-				t: "remove",
-				ids: stale
-			});
-			apply({
-				t: "loaded",
-				annots: snap.annotations.map((d) => ingestDTO(d, crop))
-			});
-		} catch {}
-	};
-	/** Script patch → the engine's per-kind patch vocabulary. Colors cross the
-	*  Acrobat-array → engine {r,g,b}/255 boundary here; everything else maps
-	*  one-to-one (the VM's validity matrix already scoped keys per kind). */
-	const engineScriptPatch = (subtype, patch) => {
-		const out = { subtype };
-		const toEngineColor = (color) => {
-			const rgb = scriptColorToRgb(color);
-			return rgb ? {
-				r: Math.round(rgb.r * 255),
-				g: Math.round(rgb.g * 255),
-				b: Math.round(rgb.b * 255)
-			} : null;
-		};
-		if (patch.strokeColor) {
-			const color = toEngineColor(patch.strokeColor);
-			if (!color) return /* @__PURE__ */ new Error("transparent stroke colours are not supported");
-			out.color = color;
-		}
-		if (patch.fillColor) out.interiorColor = toEngineColor(patch.fillColor);
-		if (patch.opacity !== void 0) out.opacity = patch.opacity;
-		if (patch.width !== void 0) out.strokeWidth = patch.width;
-		if (patch.borderStyle) out.borderStyle = patch.borderStyle === "D" ? "dashed" : "solid";
-		if (patch.dash) out.dashArray = patch.dash;
-		if (patch.rect) out.rect = {
-			left: patch.rect[0],
-			bottom: patch.rect[1],
-			right: patch.rect[2],
-			top: patch.rect[3]
-		};
-		if (patch.contents !== void 0) out.contents = patch.contents;
-		if (patch.flags) out.flags = patch.flags;
-		return out;
-	};
-	const updateSelection = (patch) => {
-		const m = model();
-		const range = activeTextRange(m);
-		if (range) {
-			const a = m.byId[range.id];
-			const { delta, rest } = runDeltaForProps(patch, fonts);
-			if (Object.keys(delta).length) {
-				const next = applyStyleToRange({ paragraphs: richDocOf(a, fonts).paragraphs }, range, delta);
-				apply({
-					t: "setRichText",
-					id: range.id,
-					doc: next
-				});
-				if (a.ref) scheduleTextCommit(a.ref);
-			}
-			if (Object.keys(rest).length) {
-				flushTextCommits();
-				apply({
-					t: "setProps",
-					patch: rest
-				});
-			}
-			return;
-		}
-		if (m.editing) flushTextCommits();
-		apply({
-			t: "setProps",
-			patch
-		});
-	};
-	return {
-		create: async (pon, draft) => {
-			const doc = ctx.doc;
-			if (!doc) throw new Error("[annotation] no document bound");
-			const withFlags = draft.flags ? draft : {
-				...draft,
-				flags: { print: true }
-			};
-			const res = await doc.page(pon).annotations.create(withFlags);
-			syncDTO(res.created, res.created.subtype === "stamp" ? "baked" : "vector");
-			return res.created.ref;
-		},
-		armStamp,
-		placeStamp,
-		disarmStamp,
-		placeArmedStamp,
-		requestStampAt,
-		placeAt,
-		hasArmedStamp: () => armedStamp != null,
-		ghostHoverAt,
-		clearGhost,
-		setPlacementPreview,
-		clearPlacementPreview: clearGhost,
-		toolGhost: (pon) => {
-			const g = ctx.getState().toolGhost;
-			return g && g.pon === pon ? g : null;
-		},
-		armedStampPreview: (devicePixelWidth) => {
-			const armed = armedStamp;
-			if (!armed?.preview) return Promise.resolve(null);
-			const bucket = previewBucket(devicePixelWidth ?? 0);
-			let pending = armed.previewCache.get(bucket);
-			if (!pending) {
-				pending = armed.preview(bucket).catch((error) => {
-					console.error("[annotation] stamp ghost preview failed:", error);
-					return null;
-				});
-				armed.previewCache.set(bucket, pending);
-			}
-			return pending;
-		},
-		stampArmEpoch: () => ctx.getState().stampArmEpoch,
-		setFilePickerProvider: (provider) => {
-			filePickerProvider = provider;
-		},
-		downloadAttachment: async (ref) => {
-			const doc = ctx.doc;
-			if (!doc) throw new Error("[annotation] no document bound");
-			const pon = ponForRef(ref);
-			if (pon == null) throw new Error("[annotation] cannot resolve page for ref");
-			const annotations = doc.page(pon).annotations;
-			if (!annotations.downloadFile) throw new Error("[annotation] this engine does not support attachment download");
-			return annotations.downloadFile(ref);
-		},
-		tools: () => [...registry.values()],
-		tool: (id) => registry.get(id) ?? null,
-		toolSubtype: (id) => registry.get(id)?.subtype ?? id,
-		registerTool: (def) => {
-			const resolved = buildToolRegistry([...configTools, def]).get(def.id);
-			if (!resolved) throw new Error(`[annotation] could not resolve tool '${def.id}'`);
-			registry.set(resolved.id, resolved);
-			const un = ctx.tryGet(InteractionToken)?.registerTool({
-				id: resolved.id,
-				cursor: resolved.cursor,
-				enables: resolved.enables,
-				touchDirect: isTouchDirect(resolved.enables)
-			});
-			if (resolved.defaults) apply({
-				t: "setDefaults",
-				subtype: resolved.preset,
-				patch: resolved.defaults
-			});
-			return () => {
-				registry.delete(resolved.id);
-				un?.();
-			};
-		},
-		update: (ref, patch) => updateOne(ref, patch),
-		updateSelection,
-		toggleTextFormat: (format) => {
-			const current = memoSelectionProps().values[format];
-			updateSelection({ [format]: !current });
-		},
-		updateSelectionFlags: (patch) => apply({
-			t: "setFlags",
-			patch
-		}),
-		getSelectionFlags: () => memoSelectionFlags(),
-		delete: async (ref) => {
-			const doc = ctx.doc;
-			if (!doc) throw new Error("[annotation] no document bound");
-			const pon = ponForRef(ref);
-			if (pon == null) throw new Error("[annotation] cannot resolve page for ref");
-			await doc.page(pon).annotations.delete(ref);
-			apply({
-				t: "remove",
-				ids: [refKey(ref)]
-			});
-		},
-		canRead: () => canRead(),
-		canCreate: () => allowsCreate(),
-		canEdit: (ref) => {
-			const a = model().byId[refKey(ref)];
-			return !!a && annotTransformable(a);
-		},
-		canDelete: (ref) => {
-			const a = model().byId[refKey(ref)];
-			return !!a && annotDeletable(a);
-		},
-		comments,
-		links: {
-			of: (ref) => {
-				const a = model().byId[refKey(ref)];
-				if (!a) return null;
-				return a.subtype === "link" ? a.link ?? null : linkOf(model(), a.id);
-			},
-			set: (ref, target) => scheduleLinkSync(refKey(ref), { target }),
-			clear: (ref) => scheduleLinkSync(refKey(ref), { target: null })
-		},
-		getSelection: () => {
-			const m = model();
-			return m.selected.map((id) => m.byId[id]?.ref).filter((r) => r != null);
-		},
-		get: (ref) => model().byId[refKey(ref)]?.data ?? null,
-		list: (pon) => {
-			const m = model();
-			return m.order.map((id) => m.byId[id]).filter((a) => a?.pon === pon).map((a) => a?.data).filter((d) => d != null);
-		},
-		getSelected: () => {
-			const m = model();
-			return m.selected.map((id) => m.byId[id]?.data).filter((d) => d != null);
-		},
-		getSelectionProps: () => memoSelectionProps(),
-		propsForTool: (toolId) => propsFor(registry.get(toolId)?.propsKind ?? toolId),
-		pageItems: (pon, view) => memoItems(pon, view),
-		chrome: (pon, scale, rotation, zoom) => memoChrome(pon, scale, rotation, zoom),
-		selectionAnchor: (scale, rotation, zoom) => memoAnchor(scale, rotation, zoom),
-		creationDraftAnchor: () => memoDraftAnchor(),
-		selection: () => model().selected,
-		hitKind: (pon, point, scale, rotation, zoom, touch) => hitTest(model(), pon, point, chromeGeomAt(scale, grabBoost(touch)), model().hitMargin, pageBoxOf(pon), inertIdsAt(pon), viewEnv(zoom, rotation)).t,
-		claimsTouchAt: (pon, point, scale, rotation, zoom) => {
-			const m = model();
-			const t = hitTest(m, pon, point, chromeGeomAt(scale, TOUCH_GRAB_BOOST), m.hitMargin, pageBoxOf(pon), inertIdsAt(pon), viewEnv(zoom, rotation));
-			if (t.t === "handle" || t.t === "rotate" || t.t === "group-handle") return true;
-			if (t.t === "annot") return m.selected.includes(t.id) && m.selected.every((id) => canMove(m, id));
-			return false;
-		},
-		cursorAt: (pon, point, scale, rotation, zoom) => cursorAt(model(), pon, point, chromeGeomAt(scale), model().hitMargin, pageBoxOf(pon), inertIdsAt(pon), viewEnv(zoom, rotation)),
-		hoverAt: (at) => {
-			const m = model();
-			let id = null;
-			if (at) {
-				const h = hitTest(m, at.pon, at.point, chromeGeomAt(at.scale), m.hitMargin, pageBoxOf(at.pon), inertIdsAt(at.pon), viewEnv(at.zoom, at.rotation));
-				if (h.t === "annot") id = h.id;
-			}
-			if (m.hovered !== id) {
-				hoverFeed?.hover(id);
-				apply({
-					t: "hover",
-					id
-				});
-			}
-		},
-		behaviorFor: (a) => behaviors.find((b) => b.matches(a) && b.engaged()) ?? null,
-		linkItemsOn: (pon) => memoLinkItems(pon),
-		appearanceEpoch: (pon) => {
-			const m = model();
-			const parts = [];
-			for (const id of m.order) {
-				const a = m.byId[id];
-				if (!a || a.pon !== pon || a.source !== "baked" || !a.ref) continue;
-				if (isSubstrateOnly(a)) continue;
-				parts.push(`${id}@${a.apVersion ?? 0}`);
-			}
-			return parts.sort().join("|");
-		},
-		bakeScale: (renderScale) => snapAppearanceScale(ctx.document()?.renderPolicy ?? CONTINUOUS_RENDER_POLICY, renderScale),
-		appearances: (pon, scale, signal) => {
-			const doc = ctx.doc;
-			if (!doc) return Promise.resolve([]);
-			const task = doc.page(pon).annotations.renderAppearanceImages({ scale });
-			if (signal) if (signal.aborted) task.abort(signal.reason);
-			else signal.addEventListener("abort", () => task.abort(signal.reason), { once: true });
-			return task.then((r) => r.appearances, () => []);
-		},
-		toContentBox: (pon, rect) => {
-			const crop = cropOf(pon);
-			return crop ? pdfToContentRect(rect, crop) : null;
-		},
-		editPointer: (phase, pon, point, shift, scale, rotation, zoom, touch) => apply({
-			t: "editPointer",
-			phase,
-			in: {
-				pon,
-				point,
-				shift,
-				pageBox: pageBoxOf(pon),
-				chrome: chromeGeomAt(scale, grabBoost(touch)),
-				inert: inertIdsAt(pon),
-				...zoom != null ? { zoom } : {},
-				...rotation != null ? { displayRotation: rotation } : {}
-			}
-		}),
-		marqueePointer: (phase, pon, point, shift, scale, rotation, zoom) => apply({
-			t: "marqueePointer",
-			phase,
-			in: {
-				pon,
-				point,
-				shift,
-				pageBox: pageBoxOf(pon),
-				inert: inertIdsAt(pon),
-				...zoom != null ? { zoom } : {},
-				...rotation != null ? { displayRotation: rotation } : {}
-			}
-		}),
-		createPointer: (tool, phase, pon, point, finish = false, displayRotation) => {
-			if (!allowsCreate()) return;
-			const t = registry.get(tool);
-			apply({
-				t: "createPointer",
-				phase,
-				subtype: t?.subtype ?? tool,
-				preset: t?.preset ?? tool,
-				intent: t?.intent,
-				clickCreate: t?.clickCreate,
-				flags: t?.flags,
-				deferInkCommit: (t?.ink?.groupStrokesMs ?? 0) > 0,
-				straightenInk: t?.ink?.straighten,
-				in: {
-					pon,
-					point,
-					shift: false,
-					finish,
-					pageBox: pageBoxOf(pon),
-					displayRotation,
-					upright: t?.upright
-				}
-			});
-		},
-		finishCreationDraft: () => apply({ t: "finishCreationDraft" }),
-		finishInkDraft: () => apply({ t: "finishInkDraft" }),
-		cancelCreationDraft: () => apply({ t: "cancel" }),
-		markupFromSelection: (subtype, preset) => {
-			if (!allowsCreate()) return false;
-			const selection = ctx.tryGet(SelectionToken);
-			if (!selection || !selection.hasSelection()) return false;
-			const snapshot = selection.snapshot();
-			let created = false;
-			for (const page of snapshot.pages) {
-				if (!page.segments.length) continue;
-				apply({
-					t: "createMarkup",
-					subtype,
-					pon: page.pon,
-					quads: page.segments.map((s) => s.quad),
-					preset,
-					flags: preset ? registry.get(preset)?.flags : void 0
-				});
-				created = true;
-			}
-			if (created) selection.clear();
-			return created;
-		},
-		createMarkup: (subtype, pon, quads, preset) => {
-			if (!allowsCreate()) return;
-			apply({
-				t: "createMarkup",
-				subtype,
-				pon,
-				quads,
-				preset,
-				flags: preset ? registry.get(preset)?.flags : void 0
-			});
-		},
-		createCaret: (pon, anchor) => {
-			if (!allowsCreate()) return;
-			apply({
-				t: "createCaret",
-				pon,
-				anchor
-			});
-		},
-		createReplaceText: (pon, quads, anchor, preset) => {
-			if (!allowsCreate()) return;
-			apply({
-				t: "createReplaceText",
-				pon,
-				quads,
-				anchor,
-				preset
-			});
-		},
-		previewMarkup: (subtype, quadsByPage, preset) => apply({
-			t: "setMarkupPreview",
-			subtype,
-			quadsByPage,
-			preset
-		}),
-		clearMarkupPreview: () => apply({ t: "clearMarkupPreview" }),
-		setDefaults: (subtype, patch) => apply({
-			t: "setDefaults",
-			subtype,
-			patch
-		}),
-		currentDefaults: (toolId) => defaultsFor(model(), registry.get(toolId)?.preset ?? toolId),
-		setSnap: (patch) => apply({
-			t: "setSnap",
-			patch
-		}),
-		snapSettings: () => model().snap,
-		setChrome: (patch) => ctx.dispatch({
-			type: "SET_CHROME",
-			patch
-		}),
-		chromeSettings: () => chromeSettings(),
-		deleteSelection: () => apply({ t: "delete" }),
-		deselect: () => apply({ t: "deselect" }),
-		select: (ref, options) => {
-			apply({
-				t: "select",
-				ids: [refKey(ref)],
-				add: options?.add
-			});
-		},
-		pruneEngagedSelection: () => {
-			const m = model();
-			const drop = m.selected.filter((id) => {
-				const a = m.byId[id];
-				return a && behaviors.some((b) => b.matches({
-					subtype: a.subtype,
-					ref: a.ref
-				}) && b.engaged());
-			});
-			if (drop.length) apply({
-				t: "deselect",
-				ids: drop
-			});
-		},
-		cancel: () => apply({ t: "cancel" }),
-		rotateSelection90: () => apply({ t: "rotate90" }),
-		resetSelectionRotation: () => apply({ t: "resetRotation" }),
-		/** Group the current selection into one unit: the bottom-most member becomes
-		*  the primary, every other member becomes a `/RT /Group` subordinate of it.
-		*  No-op unless 2+ committed annotations on a single page are selected. */
-		group: async () => {
-			const m = model();
-			const members = selectedCommitted();
-			if (members.length < 2) return;
-			const pon = members[0].pon;
-			if (members.some((a) => a.pon !== pon)) return;
-			const [primary, ...rest] = [...members].sort((a, b) => m.order.indexOf(a.id) - m.order.indexOf(b.id));
-			if (!primary.ref) return;
-			await Promise.all(rest.map((a) => writeRelationship(a, {
-				inReplyTo: primary.ref,
-				replyType: "group"
-			})));
-		},
-		/** Ungroup: clear `/IRT` (+ `/RT`) on every subordinate in the group(s) the
-		*  selection touches, so each member becomes top-level again. */
-		ungroup: async () => {
-			const m = model();
-			const subs = expandGroups(m, m.selected).map((id) => m.byId[id]).filter((a) => !!a && !!a.ref && !!a.data && !!a.group);
-			await Promise.all(subs.map((a) => writeRelationship(a, { inReplyTo: null })));
-		},
-		canGroup: () => {
-			const m = model();
-			const members = selectedCommitted();
-			if (members.length < 2) return false;
-			if (members.some((a) => a.pon !== members[0].pon)) return false;
-			if (!members.every((a) => a.ref != null && allowsMutation("update", a.ref))) return false;
-			const keys = new Set(m.selected.map((id) => groupKeyOf(m, id)));
-			if (keys.size === 1 && !keys.has(null)) return false;
-			return true;
-		},
-		canUngroup: () => {
-			const m = model();
-			const subs = expandGroups(m, m.selected).map((id) => m.byId[id]).filter((a) => !!a && !!a.group);
-			return subs.length > 0 && subs.every((a) => a.ref != null && allowsMutation("update", a.ref));
-		},
-		ensurePage: () => {},
-		reloadPage: (pon) => reloadPageNow(pon),
-		hydration: () => ctx.getState().hydration,
-		ensureHydrated: () => {
-			if (hydrationStarted) return;
-			hydrationStarted = true;
-			runHydration(false);
-		},
-		rehydrate,
-		deliverRemoteAnnotationEvent: (event) => {
-			if (hydrationWindow) {
-				pendingRemote.push(event);
-				return;
-			}
-			applyRemoteAnnotationEvent(event);
-		},
-		textItems: (pon, view) => memoTexts(pon, view),
-		currentEditing: () => model().editing,
-		beginTextEdit: (ref) => apply({
-			t: "beginTextEdit",
-			id: refKey(ref)
-		}),
-		beginTextEditAt: (pon, point, scale, rotation, zoom) => {
-			const m = model();
-			const h = hitTest(m, pon, point, chromeGeomAt(scale), m.hitMargin, pageBoxOf(pon), void 0, viewEnv(zoom, rotation));
-			const id = h.t === "annot" || h.t === "handle" ? h.id : null;
-			if (id != null && m.byId[id]?.geom.t === "text") {
-				apply({
-					t: "beginTextEdit",
-					id
-				});
-				return true;
-			}
-			return false;
-		},
-		setContents: (ref, text) => {
-			apply({
-				t: "setText",
-				id: refKey(ref),
-				text
-			});
-			scheduleTextCommit(ref);
-		},
-		setRichText: (ref, doc) => {
-			apply({
-				t: "setRichText",
-				id: refKey(ref),
-				doc: { paragraphs: doc.paragraphs }
-			});
-			scheduleTextCommit(ref);
-		},
-		setTextSelection: (ref, range) => {
-			const id = refKey(ref);
-			const prev = ctx.getState().textSelection;
-			const next = range ? {
-				id,
-				start: range.start,
-				end: range.end
-			} : null;
-			if (prev === null === (next === null) && (!prev || !next || prev.id === next.id && prev.start === next.start && prev.end === next.end)) return;
-			ctx.dispatch({
-				type: "SET_TEXT_SELECTION",
-				selection: next
-			});
-		},
-		cssFontFamily: (family) => cssFontFamilyForFace(family, fonts),
-		endTextEdit: () => {
-			flushTextCommits();
-			if (ctx.getState().textSelection) ctx.dispatch({
-				type: "SET_TEXT_SELECTION",
-				selection: null
-			});
-			apply({ t: "endTextEdit" });
-		},
-		commitScriptEffects: async (entries) => {
-			const doc = ctx.doc;
-			if (!doc) return { results: entries.map((entry) => ({
-				annotObjectNumber: entry.annotObjectNumber,
-				status: "failed",
-				error: "no document"
-			})) };
-			const results = [];
-			const touchedPons = /* @__PURE__ */ new Set();
-			let failed = false;
-			for (const entry of entries) {
-				if (failed) {
-					results.push({
-						annotObjectNumber: entry.annotObjectNumber,
-						status: "skipped"
-					});
-					continue;
-				}
-				const loaded = model().byId[`obj:${entry.annotObjectNumber}`];
-				const pon = loaded?.pon ?? entry.pageObjectNumber;
-				let ref = loaded?.ref ?? null;
-				let subtype = loaded?.subtype;
-				if ((!ref || !subtype) && pon !== void 0) try {
-					const { annotations } = await doc.page(pon).annotations.list();
-					const dto = annotations.find((candidate) => candidate.ref.kind === "objectNumber" && candidate.ref.annotObjectNumber === entry.annotObjectNumber);
-					if (dto) {
-						ref = dto.ref;
-						subtype = dto.subtype;
-					}
-				} catch {}
-				if (pon === void 0 || !ref || !subtype) {
-					results.push({
-						annotObjectNumber: entry.annotObjectNumber,
-						status: "failed",
-						error: "annotation not resolved (page not loaded)"
-					});
-					continue;
-				}
-				const patch = engineScriptPatch(subtype, entry.patch);
-				if (patch instanceof Error) {
-					results.push({
-						annotObjectNumber: entry.annotObjectNumber,
-						status: "failed",
-						error: patch.message
-					});
-					continue;
-				}
-				try {
-					await doc.page(pon).annotations.update(ref, patch);
-					touchedPons.add(pon);
-					results.push({
-						annotObjectNumber: entry.annotObjectNumber,
-						status: "applied"
-					});
-				} catch (error) {
-					failed = true;
-					results.push({
-						annotObjectNumber: entry.annotObjectNumber,
-						status: "failed",
-						error: error instanceof Error ? error.message : String(error)
-					});
-				}
-			}
-			for (const touched of touchedPons) await reloadPageNow(touched);
-			return { results };
-		},
-		registerBehavior: (b) => {
-			behaviors.push(b);
-			return () => {
-				const i = behaviors.indexOf(b);
-				if (i >= 0) behaviors.splice(i, 1);
-			};
-		}
-	};
-}
-//#endregion
-export { toPatch as i, fromDTO as n, toCreateDraft as r, createAnnotationCapability as t };
-
-//# sourceMappingURL=capability-B_dkoB1K.js.map