@embedpdf/plugin-annotation 2.15.0 → 3.0.0-next.0

package/dist/capability-fghl0JmE.js

@@ -0,0 +1,2680 @@
+import { CONTINUOUS_RENDER_POLICY, createCapabilityToken, snapAppearanceScale } from "@embedpdf/core";
+import { InteractionToken } from "@embedpdf/plugin-interaction";
+import { resolveBinarySource, sniffBinaryMetadata } from "@embedpdf/engine-core/runtime";
+import { FLAG_KEYS, calloutLinePoints, chrome, clickCreateGeom, cloudyBorderExtent, contentToPdfPoint, contentToPdfRect, contentToPdfRect as contentToPdfRect$1, creationDraftAnchor, cursorAt, defaultsFor, expandGroups, fitStampBox, geomPdfBounds, geomRotation, geomVisualBounds, groupKeyOf, hitTest, initialTextStyle, normalizeDeg, pageItems, pdfToContentPoint, pdfToContentPoint as pdfToContentPoint$1, pdfToContentRect, pdfToContentRect as pdfToContentRect$1, propsFor, readProp, resolveClickPlacement, rotatedAabb, selectionAnchor, selectionQuad, sharedProps, styleFromProps, textBoxes, unionRect, update, uprightRotation, viewable } from "@embedpdf/core-annotation";
+//#region src/types.ts
+/**
+* The annotation capability token. Typed to the full {@link AnnotationHostCapability}
+* here (the package internals + the `/internal` entry use this view). The package
+* root re-exports the SAME token narrowed to {@link AnnotationCapability}.
+*/
+const AnnotationToken = createCapabilityToken("annotation");
+//#endregion
+//#region src/repository/seam.ts
+function refKey(ref) {
+	return ref.kind === "objectNumber" ? `obj:${ref.annotObjectNumber}` : ref.kind === "nm" ? `nm:${ref.nm}` : `idx:${ref.pageObjectNumber}:${ref.index}`;
+}
+const h2 = (n) => Math.max(0, Math.min(255, Math.round(n))).toString(16).padStart(2, "0");
+const colorToCss = (c) => `#${h2(c.r)}${h2(c.g)}${h2(c.b)}`;
+function cssToColor(css) {
+	const s = css.trim();
+	const m6 = /^#?([0-9a-f]{6})$/i.exec(s);
+	if (m6) {
+		const n = parseInt(m6[1], 16);
+		return {
+			r: n >> 16 & 255,
+			g: n >> 8 & 255,
+			b: n & 255
+		};
+	}
+	const m3 = /^#?([0-9a-f]{3})$/i.exec(s);
+	if (m3) {
+		const [a, b, c] = m3[1];
+		return {
+			r: parseInt(a + a, 16),
+			g: parseInt(b + b, 16),
+			b: parseInt(c + c, 16)
+		};
+	}
+	return {
+		r: 0,
+		g: 0,
+		b: 0
+	};
+}
+const toPdfRotation = (rotCW) => normalizeDeg(-rotCW);
+const fromPdfRotation = (rotPdf) => normalizeDeg(-rotPdf);
+/** Advisory `rot` for a vertex geom, from a DTO's (PDF-convention) `rotation`.
+*  Absent → no `rot` key (kept off the geom so unrotated shapes stay clean). */
+const rotFromDTO = (rotation) => rotation ? { rot: fromPdfRotation(rotation) } : {};
+/**
+* Geometry/rotation fields for a BOX kind (square/circle/plain free-text). The
+* model's `rect` is the UNROTATED logical box and `rot` the applied tilt, so:
+*  - rot == 0 → `/Rect` IS the box; the transform pair is stated as `null`
+*    (TOTAL projection — the engine's tri-state writes preserve omissions, so
+*    an omitted field would keep a stale rotation instead of flattening it).
+*  - rot != 0 → `/Rect` is the rotated visual AABB (PDFium clips the baked /AP
+*    to it), `unrotatedRect` the logical box, `rotation` the PDF angle.
+*/
+function boxGeomFields(rect, rot, crop) {
+	if (!rot) return {
+		rect: contentToPdfRect(rect, crop),
+		rotation: null,
+		unrotatedRect: null
+	};
+	return {
+		rect: contentToPdfRect(rotatedAabb(rect, rot), crop),
+		unrotatedRect: contentToPdfRect(rect, crop),
+		rotation: toPdfRotation(rot)
+	};
+}
+/** A box geom (square/circle/stamp) from its DTO: when rotated, the LOCAL box
+*  is the stored `unrotatedRect` (the AABB `/Rect` is the rendered envelope)
+*  and `rot` the converted tilt; unrotated, `/Rect` IS the box. */
+function boxGeomFromDTO(dto, rotation, unrotatedRect, crop, ellipse) {
+	const rot = rotation ? fromPdfRotation(rotation) : 0;
+	return {
+		t: "rect",
+		rect: pdfToContentRect(rot && unrotatedRect ? unrotatedRect : dto.rect, crop),
+		ellipse,
+		...rot ? { rot } : {}
+	};
+}
+/** Inset a PdfRect by a `/RD` (PDF user space, y-up: all four are non-negative
+*  insets from the matching `/Rect` edge). Used to recover the callout text box. */
+const insetPdfRectByRD = (r, rd) => rd ? {
+	left: r.left + rd.left,
+	bottom: r.bottom + rd.bottom,
+	right: r.right - rd.right,
+	top: r.top - rd.top
+} : r;
+/** Engine border fields (`/BS /S`, `/BS /D`, `/BE /I`) → the `Border` union. A
+*  cloudy effect wins over the underlying border style (which stays solid). */
+function borderFromDTO(d) {
+	if ((d.cloudyIntensity ?? 0) > 0) return {
+		kind: "cloudy",
+		intensity: d.cloudyIntensity
+	};
+	if (d.borderStyle === "dashed") return {
+		kind: "dashed",
+		dash: d.dashArray?.length ? d.dashArray : [3, 3]
+	};
+	return { kind: "solid" };
+}
+/** The writable projection of a `link` value: `goto`/`uri` pass through,
+*  read-only arms (`javascript`, `named`, `goto-remote`, `launch`,
+*  `unsupported`) yield `null` — they can be carried, never (re)written. */
+function writableTarget(t) {
+	return t && (t.kind === "goto" || t.kind === "uri") ? t : null;
+}
+const TEXT_MARKUP = /* @__PURE__ */ new Set([
+	"highlight",
+	"underline",
+	"squiggly",
+	"strikeout"
+]);
+const STROKE_KINDS = /* @__PURE__ */ new Set([
+	"square",
+	"circle",
+	"line",
+	"polygon",
+	"polyline",
+	"ink"
+]);
+/** Engine DTO → content-space `Style` (CSS colours, `Border` union). Exported so
+*  selection-aware UIs can read display values straight off a {@link AnnotationDTO}
+*  without re-deriving the colour/border mapping. */
+function styleFromDTO(dto) {
+	if (dto.subtype === "widget") return {
+		color: dto.color ? colorToCss(dto.color) : "#1a1a1a",
+		interiorColor: dto.interiorColor ? colorToCss(dto.interiorColor) : null,
+		strokeWidth: dto.strokeWidth,
+		opacity: 1,
+		blendMode: dto.blendMode,
+		border: dto.borderStyle === "dashed" ? {
+			kind: "dashed",
+			dash: [3, 3]
+		} : { kind: "solid" }
+	};
+	if (STROKE_KINDS.has(dto.subtype)) {
+		const d = dto;
+		return {
+			color: colorToCss(d.color),
+			interiorColor: d.interiorColor ? colorToCss(d.interiorColor) : null,
+			strokeWidth: d.strokeWidth,
+			opacity: d.opacity,
+			blendMode: dto.blendMode,
+			border: borderFromDTO(d)
+		};
+	}
+	if (TEXT_MARKUP.has(dto.subtype)) {
+		const d = dto;
+		return {
+			color: colorToCss(d.color),
+			interiorColor: null,
+			strokeWidth: 0,
+			opacity: d.opacity,
+			blendMode: dto.blendMode,
+			border: { kind: "solid" }
+		};
+	}
+	if (dto.subtype === "caret") {
+		const d = dto;
+		return {
+			color: colorToCss(d.color),
+			interiorColor: null,
+			strokeWidth: 1,
+			opacity: d.opacity,
+			blendMode: dto.blendMode,
+			border: { kind: "solid" }
+		};
+	}
+	if (dto.subtype === "free-text") {
+		const d = dto;
+		return {
+			color: colorToCss(d.color),
+			interiorColor: d.interiorColor ? colorToCss(d.interiorColor) : null,
+			strokeWidth: d.strokeWidth,
+			opacity: d.opacity,
+			blendMode: dto.blendMode,
+			border: borderFromDTO(d)
+		};
+	}
+	if (dto.subtype === "redact") {
+		const d = dto;
+		return {
+			color: colorToCss(d.color),
+			interiorColor: d.interiorColor ? colorToCss(d.interiorColor) : null,
+			strokeWidth: 1.5,
+			opacity: d.opacity,
+			blendMode: dto.blendMode,
+			border: { kind: "solid" }
+		};
+	}
+	if (dto.subtype === "text" || dto.subtype === "file-attachment") {
+		const d = dto;
+		return {
+			color: colorToCss(d.color),
+			interiorColor: null,
+			strokeWidth: 1,
+			opacity: d.opacity,
+			blendMode: dto.blendMode,
+			border: { kind: "solid" }
+		};
+	}
+	return {
+		color: "#444444",
+		interiorColor: null,
+		strokeWidth: 1,
+		opacity: 1,
+		blendMode: dto.blendMode,
+		border: { kind: "solid" }
+	};
+}
+/**
+* The flat props vocabulary (CSS colours, house keys) → the engine's widget
+* appearance for `doc.forms` authoring — the SAME mapping the widget patch
+* lowering uses, exported as a boundary utility so the form plugin can style
+* `placeField` from a tool's `currentDefaults` without growing a second CSS
+* parser. Absent keys stay absent (the engine writes nothing for them).
+*/
+function widgetAppearanceFromProps(props) {
+	return {
+		...props.color !== void 0 ? { color: cssToColor(props.color) } : {},
+		...props.interiorColor !== void 0 ? { interiorColor: props.interiorColor ? cssToColor(props.interiorColor) : null } : {},
+		...props.strokeWidth !== void 0 ? { strokeWidth: props.strokeWidth } : {},
+		...props.border !== void 0 ? { borderStyle: props.border.kind === "dashed" ? "dashed" : "solid" } : {},
+		...props.fontFamily !== void 0 ? { fontFamily: props.fontFamily } : {},
+		...props.fontSize !== void 0 ? { fontSize: props.fontSize } : {},
+		...props.fontColor !== void 0 ? { fontColor: cssToColor(props.fontColor) } : {},
+		...props.textAlign !== void 0 ? { textAlign: props.textAlign } : {}
+	};
+}
+//#endregion
+//#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 {};
+};
+/** Stroke-family prop exceptions: width and border feed the derived /Rect. */
+const strokeProps = {
+	strokeWidth: (a, crop) => ({
+		strokeWidth: a.style.strokeWidth,
+		...visualRect(a, crop)
+	}),
+	border: (a, crop) => ({
+		...borderSlice(a.style),
+		...polyCloudy(a),
+		...a.geom.t === "poly" && a.geom.closed ? visualRect(a, crop) : {}
+	}),
+	lineEndings: (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/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) {
+	return {
+		fontFamily: dto.fontFamily,
+		fontSize: dto.fontSize,
+		fontColor: colorToCss(dto.fontColor ?? dto.color),
+		textAlign: dto.textAlign
+	};
+}
+/**
+* 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);
+	},
+	draftExtras: (a, crop) => ({
+		intent: calloutFields(a, crop) ? "free-text-callout" : "free-text",
+		contents: a.data?.contents ?? ""
+	})
+};
+//#endregion
+//#region src/repository/kinds/quads.ts
+const quadsFromDTO = (quadPoints, crop) => quadPoints.map((q) => [
+	pdfToContentPoint$1(q.p1, crop),
+	pdfToContentPoint$1(q.p2, crop),
+	pdfToContentPoint$1(q.p3, crop),
+	pdfToContentPoint$1(q.p4, crop)
+]);
+/** Content quads → engine `/QuadPoints` (PDF user space); null off quads geom. */
+function quadPointsFor(a, crop) {
+	if (a.geom.t !== "quads") return null;
+	return a.geom.quads.map((q) => ({
+		p1: contentToPdfPoint(q[0], crop),
+		p2: contentToPdfPoint(q[1], crop),
+		p3: contentToPdfPoint(q[2], crop),
+		p4: contentToPdfPoint(q[3], 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;
+		return {
+			geom: {
+				t: "caret",
+				rect: pdfToContentRect$1(d.rect, crop)
+			},
+			...d.intent ? { intent: d.intent } : {}
+		};
+	},
+	geometry: (a, crop) => a.geom.t === "caret" ? { rect: contentToPdfRect$1(a.geom.rect, 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.
+*/
+/** Does this kind's table declare the `link` prop (may it carry an attached
+*  link)? Widgets/caret/redact/file-attachment deliberately don't. */
+const takesLink = (subtype) => propsFor(subtype).some((s) => s.key === "link");
+/**
+* Fold attached link children onto their parents: a `/Link` annotation
+* grouped (`/RT /Group`) under a linkable non-link parent is not an object
+* in the client model — it becomes the parent's `link` prop value plus the
+* `linkRefs` join keys the write side needs. Folded children are REMOVED
+* from the returned list, so they never render, hit-test, or select.
+* Anything that doesn't match (orphans, links grouped under widgets or
+* other links) stays a standalone annotation — nothing is ever hidden.
+*
+* Multi-segment parents (markup) carry several children with one shared
+* target; the first child's target wins and the next write heals any
+* foreign disagreement.
+*/
+function foldAttachedLinks(annots) {
+	const byId = new Map(annots.map((a) => [a.id, a]));
+	const folded = /* @__PURE__ */ new Set();
+	const patched = /* @__PURE__ */ new Map();
+	for (const a of annots) {
+		if (a.subtype !== "link" || a.data?.subtype !== "link") continue;
+		if (a.data.replyType !== "group" || !a.data.inReplyTo || !a.ref) continue;
+		const parentId = refKey(a.data.inReplyTo);
+		const parent = patched.get(parentId) ?? byId.get(parentId);
+		if (!parent || parent.subtype === "link" || !takesLink(parent.subtype)) continue;
+		patched.set(parentId, {
+			...parent,
+			link: parent.link ?? a.data.target,
+			linkRefs: [...parent.linkRefs ?? [], a.ref]
+		});
+		folded.add(a.id);
+	}
+	if (!folded.size) return annots;
+	return annots.filter((a) => !folded.has(a.id)).map((a) => patched.get(a.id) ?? a);
+}
+/** Bounds of one quad (content space). */
+const quadBounds = (q) => unionRect(q);
+/**
+* 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(quadBounds);
+	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,
+		flags: a.flags
+	};
+}
+//#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.
+*/
+/** Map a free-text `/DA` font to a CSS font-family. A standard PDF font → a web
+*  stack with the same metrics; anything else is a registered font key → mount it
+*  as a `@font-face` of that family (see the framework `mountWebFont` helper). */
+const STANDARD_FONT_CSS = {
+	helvetica: "Helvetica, Arial, sans-serif",
+	"helvetica-bold": "Helvetica, Arial, sans-serif",
+	courier: "\"Courier New\", Courier, monospace",
+	"times-roman": "\"Times New Roman\", Times, serif",
+	symbol: "serif",
+	"zapf-dingbats": "serif"
+};
+const cssFontFor = (font) => STANDARD_FONT_CSS[font] ?? `"${font}", sans-serif`;
+/** 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;
+		return {
+			id: tb.id,
+			ref: a?.ref ?? null,
+			box: tb.box,
+			contents: a?.data?.contents ?? "",
+			editing: tb.editing,
+			...tb.rot ? { rot: tb.rot } : {},
+			css: {
+				fontFamily: cssFontFor(t.fontFamily),
+				fontSize: t.fontSize,
+				lineHeight: t.fontSize,
+				color: t.fontColor,
+				align: t.textAlign,
+				padding: 2,
+				background: a?.style.interiorColor ?? null
+			}
+		};
+	});
+}
+//#endregion
+//#region src/tools.ts
+/**
+* The creation properties each known authoring kind actually consumes. This is
+* deliberately separate from the flat internal patch vocabulary: it gives tool
+* configuration precise compile-time and runtime validation while mixed-selection
+* edits can keep using `AnnotationPropsPatch`.
+*/
+const TOOL_DEFAULT_KEYS = {
+	square: [
+		"color",
+		"interiorColor",
+		"opacity",
+		"strokeWidth",
+		"border"
+	],
+	circle: [
+		"color",
+		"interiorColor",
+		"opacity",
+		"strokeWidth",
+		"border"
+	],
+	line: [
+		"color",
+		"interiorColor",
+		"opacity",
+		"strokeWidth",
+		"border",
+		"lineEndings"
+	],
+	polygon: [
+		"color",
+		"interiorColor",
+		"opacity",
+		"strokeWidth",
+		"border"
+	],
+	polyline: [
+		"color",
+		"interiorColor",
+		"opacity",
+		"strokeWidth",
+		"border",
+		"lineEndings"
+	],
+	ink: [
+		"color",
+		"opacity",
+		"strokeWidth",
+		"blendMode"
+	],
+	"free-text": [
+		"fontFamily",
+		"fontSize",
+		"fontColor",
+		"textAlign",
+		"opacity",
+		"interiorColor",
+		"color",
+		"strokeWidth",
+		"border"
+	],
+	"free-text-callout": [
+		"fontFamily",
+		"fontSize",
+		"fontColor",
+		"textAlign",
+		"opacity",
+		"interiorColor",
+		"color",
+		"strokeWidth",
+		"border",
+		"lineEndings"
+	],
+	highlight: [
+		"color",
+		"opacity",
+		"blendMode"
+	],
+	underline: [
+		"color",
+		"opacity",
+		"blendMode"
+	],
+	strikeout: [
+		"color",
+		"opacity",
+		"blendMode"
+	],
+	squiggly: [
+		"color",
+		"opacity",
+		"blendMode"
+	],
+	caret: ["color", "opacity"],
+	redact: [
+		"color",
+		"interiorColor",
+		"opacity",
+		"fontFamily",
+		"fontSize",
+		"fontColor",
+		"textAlign"
+	],
+	stamp: [],
+	link: ["link"],
+	text: [
+		"icon",
+		"color",
+		"opacity"
+	],
+	"file-attachment": [
+		"icon",
+		"color",
+		"opacity"
+	],
+	"widget-text": [
+		"color",
+		"interiorColor",
+		"strokeWidth",
+		"border",
+		"fontFamily",
+		"fontSize",
+		"fontColor",
+		"textAlign"
+	],
+	"widget-choice": [
+		"color",
+		"interiorColor",
+		"strokeWidth",
+		"border",
+		"fontFamily",
+		"fontSize",
+		"fontColor",
+		"textAlign"
+	],
+	"widget-toggle": [
+		"color",
+		"interiorColor",
+		"strokeWidth",
+		"border"
+	]
+};
+const DRAW_TAGS = ["annotation-draw", "annotation-edit"];
+const MARKUP_TAGS = ["text-select", "annotation-edit"];
+/**
+* The built-in tools — a data mirror of v2's registrations (shapes + lines + ink
+* + free text in the draw channel, text markup + caret behind text selection, and
+* the click-to-place stamp). Order is display-neutral; the toolbar owns layout.
+*/
+const DEFAULT_TOOLS = [
+	{
+		id: "square",
+		subtype: "square",
+		cursor: "crosshair",
+		enables: DRAW_TAGS,
+		defaults: { strokeWidth: 6 },
+		clickCreate: {
+			width: 80,
+			height: 60
+		}
+	},
+	{
+		id: "circle",
+		subtype: "circle",
+		cursor: "crosshair",
+		enables: DRAW_TAGS,
+		defaults: { strokeWidth: 6 },
+		clickCreate: {
+			width: 80,
+			height: 60
+		}
+	},
+	{
+		id: "line",
+		subtype: "line",
+		cursor: "crosshair",
+		enables: DRAW_TAGS,
+		defaults: { strokeWidth: 6 },
+		clickCreate: { length: 80 }
+	},
+	{
+		id: "polygon",
+		subtype: "polygon",
+		cursor: "crosshair",
+		enables: DRAW_TAGS,
+		defaults: { strokeWidth: 6 }
+	},
+	{
+		id: "polyline",
+		subtype: "polyline",
+		cursor: "crosshair",
+		enables: DRAW_TAGS,
+		defaults: { strokeWidth: 6 }
+	},
+	{
+		id: "ink",
+		subtype: "ink",
+		cursor: "crosshair",
+		enables: DRAW_TAGS,
+		defaults: {
+			color: "#ef4444",
+			strokeWidth: 6,
+			blendMode: "normal"
+		},
+		ink: { groupStrokesMs: 800 }
+	},
+	{
+		id: "ink-highlight",
+		extends: "ink",
+		intent: "ink-highlight",
+		defaults: {
+			color: "#ffcd45",
+			strokeWidth: 14,
+			blendMode: "multiply"
+		},
+		ink: { straighten: {
+			deviationThreshold: .15,
+			axisSnapDegrees: 15
+		} }
+	},
+	{
+		id: "free-text",
+		subtype: "free-text",
+		cursor: "crosshair",
+		enables: DRAW_TAGS,
+		defaults: { fontColor: "#ef4444" },
+		upright: true,
+		clickCreate: {
+			width: 180,
+			height: 40,
+			anchor: "top-left"
+		}
+	},
+	{
+		id: "free-text-callout",
+		subtype: "free-text-callout",
+		propsKind: "free-text",
+		cursor: "crosshair",
+		enables: DRAW_TAGS,
+		defaults: {
+			strokeWidth: 6,
+			lineEndings: { end: "open-arrow" }
+		},
+		upright: true
+	},
+	{
+		id: "highlight",
+		subtype: "highlight",
+		cursor: "default",
+		enables: MARKUP_TAGS,
+		defaults: {
+			color: "#ffe16a",
+			blendMode: "multiply"
+		},
+		selection: { kind: "markup" }
+	},
+	{
+		id: "redact",
+		subtype: "redact",
+		cursor: "crosshair",
+		enables: [
+			"text-select",
+			"annotation-draw",
+			"annotation-edit"
+		],
+		defaults: {
+			color: "#e44234",
+			interiorColor: "#000000",
+			fontColor: "#ffffff",
+			opacity: 1
+		},
+		selection: { kind: "markup" }
+	},
+	{
+		id: "underline",
+		subtype: "underline",
+		cursor: "default",
+		enables: MARKUP_TAGS,
+		defaults: { color: "#ef4444" },
+		selection: { kind: "markup" }
+	},
+	{
+		id: "strikeout",
+		subtype: "strikeout",
+		cursor: "default",
+		enables: MARKUP_TAGS,
+		defaults: { color: "#ef4444" },
+		selection: { kind: "markup" }
+	},
+	{
+		id: "squiggly",
+		subtype: "squiggly",
+		cursor: "default",
+		enables: MARKUP_TAGS,
+		defaults: { color: "#ef4444" },
+		selection: { kind: "markup" }
+	},
+	{
+		id: "insert-text",
+		subtype: "caret",
+		propsKind: "caret",
+		preset: "caret",
+		cursor: "default",
+		enables: MARKUP_TAGS,
+		defaults: { color: "#ef4444" },
+		selection: {
+			kind: "text-edit",
+			operation: "insert"
+		}
+	},
+	{
+		id: "replace-text",
+		subtype: "strikeout",
+		propsKind: "strikeout",
+		cursor: "default",
+		enables: MARKUP_TAGS,
+		defaults: { color: "#ef4444" },
+		selection: {
+			kind: "text-edit",
+			operation: "replace"
+		}
+	},
+	{
+		id: "stamp",
+		subtype: "stamp",
+		cursor: "copy",
+		enables: ["annotation-place", "annotation-edit"],
+		source: {
+			kind: "prompt",
+			accept: "image/png,image/jpeg,application/pdf"
+		},
+		upright: true,
+		ghost: { mode: "footprint" }
+	},
+	{
+		id: "link",
+		subtype: "link",
+		cursor: "crosshair",
+		enables: DRAW_TAGS
+	},
+	{
+		id: "note",
+		subtype: "text",
+		cursor: "crosshair",
+		enables: ["annotation-place", "annotation-edit"],
+		defaults: {
+			icon: "comment",
+			color: "#facc15"
+		},
+		flags: {
+			noZoom: true,
+			noRotate: true
+		},
+		upright: true,
+		ghost: { mode: "footprint" }
+	},
+	{
+		id: "attachment",
+		subtype: "file-attachment",
+		cursor: "copy",
+		enables: ["annotation-place", "annotation-edit"],
+		source: { kind: "prompt" },
+		defaults: {
+			icon: "paperclip",
+			color: "#facc15"
+		},
+		flags: {
+			noZoom: true,
+			noRotate: true
+		},
+		upright: true,
+		ghost: { mode: "footprint" }
+	}
+];
+/** Merge two default patches, `b` over `a`, with line endings merged per side. */
+function mergeDefaults(a, b) {
+	if (!a) return b;
+	if (!b) return a;
+	const merged = {
+		...a,
+		...b
+	};
+	if (a.lineEndings || b.lineEndings) merged.lineEndings = {
+		...a.lineEndings,
+		...b.lineEndings
+	};
+	return merged;
+}
+/** Overlay a same-id override onto a base definition (configure a built-in). */
+function mergeDef(base, over) {
+	return {
+		...base,
+		...over,
+		enables: over.enables ?? base.enables,
+		meta: base.meta || over.meta ? {
+			...base.meta,
+			...over.meta
+		} : void 0,
+		defaults: mergeDefaults(base.defaults, over.defaults),
+		flags: base.flags || over.flags ? {
+			...base.flags,
+			...over.flags
+		} : void 0,
+		ink: base.ink || over.ink ? {
+			...base.ink,
+			...over.ink
+		} : void 0
+	};
+}
+function validateDefaults(tool) {
+	if (!tool.defaults) return;
+	const allowed = TOOL_DEFAULT_KEYS[tool.subtype];
+	if (!allowed) return;
+	const keys = new Set(allowed);
+	for (const key of Object.keys(tool.defaults)) if (!keys.has(key)) throw new Error(`[annotation] tool '${tool.id}' does not support default '${key}' for '${tool.subtype}'`);
+}
+/**
+* Resolve {@link DEFAULT_TOOLS} + embedder overrides into the ready-to-use table.
+* A same-id override merges over the built-in; a new id adds a tool; `extends`
+* inherits from an already-defined tool. Keyed by id, so lookups are O(1).
+*/
+function buildToolRegistry(overrides = []) {
+	const defs = /* @__PURE__ */ new Map();
+	for (const d of DEFAULT_TOOLS) defs.set(d.id, d);
+	for (const o of overrides) {
+		const prev = defs.get(o.id);
+		defs.set(o.id, prev ? mergeDef(prev, o) : o);
+	}
+	const out = /* @__PURE__ */ new Map();
+	const resolving = /* @__PURE__ */ new Set();
+	const resolve = (id) => {
+		const cached = out.get(id);
+		if (cached) return cached;
+		const def = defs.get(id);
+		if (!def) throw new Error(`[annotation] tool '${id}' extends an unknown tool`);
+		let base;
+		if (def.extends && def.extends !== id && !resolving.has(def.extends)) {
+			resolving.add(id);
+			base = resolve(def.extends);
+			resolving.delete(id);
+		}
+		const subtype = def.subtype ?? base?.subtype ?? def.id;
+		const resolved = {
+			id: def.id,
+			subtype,
+			preset: def.preset ?? def.id,
+			propsKind: def.propsKind ?? base?.propsKind ?? subtype,
+			cursor: def.cursor ?? base?.cursor ?? "crosshair",
+			enables: new Set(def.enables ?? (base ? [...base.enables] : [])),
+			defaults: mergeDefaults(base?.defaults, def.defaults),
+			flags: base?.flags || def.flags ? {
+				...base?.flags,
+				...def.flags
+			} : void 0,
+			source: def.source ?? base?.source,
+			selection: def.selection ?? base?.selection,
+			intent: def.intent ?? base?.intent,
+			ink: base?.ink || def.ink ? {
+				...base?.ink,
+				...def.ink
+			} : void 0,
+			upright: def.upright ?? base?.upright ?? false,
+			clickCreate: def.clickCreate ?? base?.clickCreate ?? false,
+			ghost: def.ghost ?? base?.ghost ?? false,
+			meta: base?.meta || def.meta ? {
+				...base?.meta,
+				...def.meta
+			} : void 0
+		};
+		validateDefaults(resolved);
+		out.set(id, resolved);
+		return resolved;
+	};
+	for (const id of defs.keys()) resolve(id);
+	return out;
+}
+//#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;
+/** Broad annotate-write capability (PDF bit 6). The engine independently
+*  enforces this AND the per-owner collab rules; `canEdit`/`canDelete` are the
+*  UI mirror of the coarse gate. */
+const ANNOTATE_MODIFY = "doc.annotate.modify";
+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 loaded = /* @__PURE__ */ new Set();
+	const behaviors = [];
+	/** Per-annotation debounce timer for the engine `contents` write while typing. */
+	const textTimers = /* @__PURE__ */ new Map();
+	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 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). */
+	const chromeGeomAt = (scale) => {
+		const cs = chromeSettings();
+		const s = scale || 1;
+		return {
+			handleTol: cs.handles.hitSize / 2 / s,
+			knobTol: cs.knob.hitSize / 2 / s,
+			knobOffset: cs.knob.offset / s
+		};
+	};
+	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;
+	};
+	let selPropsCache = null;
+	const memoSelectionProps = () => {
+		const m = model();
+		if (selPropsCache && selPropsCache.model === m) 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 = [];
+		for (const spec of specs) {
+			const first = readProp(members[0], spec.key);
+			values[spec.key] = first;
+			const firstJson = JSON.stringify(first);
+			if (members.some((a) => JSON.stringify(readProp(a, spec.key)) !== firstJson)) mixed.push(spec.key);
+		}
+		const v = {
+			specs,
+			values,
+			mixed
+		};
+		selPropsCache = {
+			model: m,
+			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.link == null) continue;
+			if (!viewable(a.flags, false)) continue;
+			if (a.subtype === "link") {
+				if (a.geom.t === "rect") v.push({
+					id,
+					rect: a.geom.rect,
+					target: a.link
+				});
+			} else linkChildRects(a).forEach((rect, i) => v.push({
+				id: `${id}#${i}`,
+				rect,
+				target: a.link
+			}));
+		}
+		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;
+	/**
+	* 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 (input.preview) {
+			const p = await resolveBinarySource(input.preview);
+			preview = {
+				bytes: new Uint8Array(p.bytes),
+				mimeType: p.mimeType
+			};
+		} else if (meta.mimeType !== "application/pdf") preview = {
+			bytes: new Uint8Array(resolved.bytes),
+			mimeType: meta.mimeType
+		};
+		armedStamp = {
+			source: input.source,
+			...desiredStampSize(meta, input.targetWidth, input.intrinsicSize),
+			preview
+		};
+		ctx.dispatch({ type: "STAMP_ARM_CHANGED" });
+		ctx.tryGet(InteractionToken)?.activateTool("stamp");
+	};
+	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) => {
+		const doc = ctx.doc;
+		const crop = cropOf(pon);
+		if (!doc || !crop) return false;
+		const box = fitStampBox(point, desired, {
+			width: crop.right - crop.left,
+			height: crop.top - crop.bottom
+		}, rotCW);
+		doc.page(pon).annotations.create({
+			subtype: "stamp",
+			...boxGeomFields(box, rotCW, crop),
+			source,
+			fit: "contain"
+		}).then((res) => {
+			syncDTO(res.created, "baked");
+			apply({
+				t: "select",
+				ids: [refKey(res.created.ref)]
+			});
+		}, (err) => console.error("[annotation] stamp placement failed:", err));
+		return true;
+	};
+	/** 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 createStampAt(pon, point, armed.source, {
+			width: armed.width,
+			height: armed.height
+		}, uprightRotFor(displayRotation));
+	};
+	/** 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;
+		}
+		createStampAt(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: [fromDTO(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");
+	};
+	function apply(msg) {
+		const [next, effects] = update(model(), msg);
+		ctx.dispatch({
+			type: "SET_MODEL",
+			model: next
+		});
+		for (const fx of effects) perform(fx, next);
+	}
+	/**
+	* 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();
+	const scheduleLinkSync = (id) => {
+		const next = (linkSyncChains.get(id) ?? Promise.resolve()).then(() => reconcileLinkChildren(id));
+		linkSyncChains.set(id, next);
+		next.finally(() => {
+			if (linkSyncChains.get(id) === next) linkSyncChains.delete(id);
+		});
+	};
+	/**
+	* THE one place attached link children are created, retargeted, re-rected,
+	* or deleted (the delete-with-parent expansion in the core is the one other
+	* consumer of `linkRefs`). Declarative: desired state is derived fresh from
+	* the parent's `link` value + committed geometry (`linkChildRects`), then
+	* diffed against the join keys the last fold reported. Idempotent — foreign
+	* inconsistencies heal on the next local edit.
+	*/
+	const reconcileLinkChildren = async (id) => {
+		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(a.link);
+		const rects = a.link == null ? [] : linkChildRects(a).map((r) => contentToPdfRect(r, crop));
+		const current = a.linkRefs ?? [];
+		const nextRefs = [];
+		try {
+			const paired = Math.min(current.length, rects.length);
+			for (let i = 0; i < paired; i++) {
+				const res = await page.annotations.update(current[i], {
+					subtype: "link",
+					rect: rects[i],
+					...target ? { target } : {}
+				});
+				nextRefs.push(res.updated.ref);
+			}
+			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"
+				});
+				nextRefs.push(res.created.ref);
+			}
+			for (let i = rects.length; i < current.length; i++) await page.annotations.delete(current[i]);
+		} catch (err) {
+			console.error("[annotation] attached-link sync failed:", err);
+		}
+		const cur = model().byId[id];
+		if (cur) apply({
+			t: "upsert",
+			annots: [{
+				...cur,
+				linkRefs: nextRefs
+			}]
+		});
+	};
+	/** 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 (a.linkRefs?.length) scheduleLinkSync(fx.id);
+			}, () => {});
+		} else if (fx.fx === "syncLink") scheduleLinkSync(fx.id);
+		else doc.page(fx.ref.pageObjectNumber).annotations.delete(fx.ref).then(() => {}, () => {});
+	}
+	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,
+		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: () => armedStamp?.preview ?? null,
+		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
+			});
+			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: (patch) => apply({
+			t: "setProps",
+			patch
+		}),
+		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)]
+			});
+		},
+		canCreate: () => ctx.doc?.security.allows(ANNOTATE_MODIFY) ?? false,
+		canEdit: () => ctx.doc?.security.allows(ANNOTATE_MODIFY) ?? false,
+		canDelete: () => ctx.doc?.security.allows(ANNOTATE_MODIFY) ?? false,
+		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) => hitTest(model(), pon, point, chromeGeomAt(scale), model().hitMargin, pageBoxOf(pon), inertIdsAt(pon), viewEnv(zoom, rotation)).t,
+		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) 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;
+				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) => apply({
+			t: "editPointer",
+			phase,
+			in: {
+				pon,
+				point,
+				shift,
+				pageBox: pageBoxOf(pon),
+				chrome: chromeGeomAt(scale),
+				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) => {
+			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" }),
+		createMarkup: (subtype, pon, rects, preset) => apply({
+			t: "createMarkup",
+			subtype,
+			pon,
+			rects,
+			preset,
+			flags: preset ? registry.get(preset)?.flags : void 0
+		}),
+		createCaret: (pon, textEndRect) => apply({
+			t: "createCaret",
+			pon,
+			rect: textEndRect
+		}),
+		createReplaceText: (pon, rects, textEndRect, preset) => apply({
+			t: "createReplaceText",
+			pon,
+			rects,
+			endRect: textEndRect,
+			preset
+		}),
+		previewMarkup: (subtype, rectsByPage, preset) => apply({
+			t: "setMarkupPreview",
+			subtype,
+			rectsByPage,
+			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: () => {
+			if (!(ctx.doc?.security.allows(ANNOTATE_MODIFY) ?? false)) return false;
+			const m = model();
+			const members = selectedCommitted();
+			if (members.length < 2) return false;
+			if (members.some((a) => a.pon !== members[0].pon)) 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: () => {
+			if (!(ctx.doc?.security.allows(ANNOTATE_MODIFY) ?? false)) return false;
+			const m = model();
+			return m.selected.some((id) => groupKeyOf(m, id) != null);
+		},
+		ensurePage: (pon) => {
+			if (loaded.has(pon)) return;
+			const doc = ctx.doc;
+			const crop = cropOf(pon);
+			if (!doc || !crop) return;
+			loaded.add(pon);
+			doc.page(pon).annotations.list().then((snap) => apply({
+				t: "loaded",
+				annots: foldAttachedLinks(snap.annotations.map((d) => fromDTO(d, crop)))
+			}), () => {
+				loaded.delete(pon);
+			});
+		},
+		reloadPage: async (pon) => {
+			const doc = ctx.doc;
+			const crop = cropOf(pon);
+			if (!doc || !crop) return;
+			loaded.add(pon);
+			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: foldAttachedLinks(snap.annotations.map((d) => fromDTO(d, crop)))
+				});
+			} catch {
+				loaded.delete(pon);
+			}
+		},
+		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
+			});
+		},
+		setContents: (ref, text) => {
+			apply({
+				t: "setText",
+				id: refKey(ref),
+				text
+			});
+			const key = refKey(ref);
+			clearTimeout(textTimers.get(key));
+			textTimers.set(key, setTimeout(() => {
+				textTimers.delete(key);
+				const pon = ponForRef(ref);
+				if (pon != null) ctx.doc?.page(pon).annotations.update(ref, {
+					subtype: "free-text",
+					contents: text
+				}).then(() => {}, () => {});
+			}, TEXT_COMMIT_DEBOUNCE_MS));
+		},
+		endTextEdit: () => {
+			for (const t of textTimers.values()) clearTimeout(t);
+			const id = model().editing;
+			const a = id ? model().byId[id] : null;
+			if (a?.ref) {
+				const pon = ponForRef(a.ref);
+				const text = a.data?.contents ?? "";
+				if (pon != null) ctx.doc?.page(pon).annotations.update(a.ref, {
+					subtype: "free-text",
+					contents: text
+				}).then(() => {}, () => {});
+			}
+			textTimers.clear();
+			apply({ t: "endTextEdit" });
+		},
+		registerBehavior: (b) => {
+			behaviors.push(b);
+			return () => {
+				const i = behaviors.indexOf(b);
+				if (i >= 0) behaviors.splice(i, 1);
+			};
+		}
+	};
+}
+//#endregion
+export { toCreateDraft as a, styleFromDTO as c, fromDTO as i, widgetAppearanceFromProps as l, DEFAULT_TOOLS as n, toPatch as o, buildToolRegistry as r, refKey as s, createAnnotationCapability as t, AnnotationToken as u };
+
+//# sourceMappingURL=capability-fghl0JmE.js.map