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

package/dist/{capability-fghl0JmE.js → capability-DBsr2D-L.js}

@@ -1,236 +1,12 @@
-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
+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 { 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, calloutLinePoints, canMove, chrome, clickCreateGeom, cloudyBorderExtent, contentToPdfRect, creationDraftAnchor, cursorAt, defaultsFor, expandGroups, fitStampBox, geomPdfBounds, geomRotation, geomVisualBounds, groupKeyOf, hitTest, initialTextStyle, isSubstrateOnly, linkChildrenOf, linkOf, pageItems, pdfToContentPoint, pdfToContentRect, propsFor, readProp, resolveClickPlacement, rotatedAabb, selectionAnchor, selectionQuad, sharedProps, styleFromProps, textBoxes, 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
@@ -333,18 +109,29 @@ const visualRect = (a, 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. */
+/**
+* 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: (a, crop) => ({
-		strokeWidth: a.style.strokeWidth,
-		...visualRect(a, crop)
-	}),
-	border: (a, crop) => ({
+	strokeWidth: withRect((a) => ({ strokeWidth: a.style.strokeWidth })),
+	border: withRect((a) => ({
 		...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 } : {}
+		...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) => {
@@ -522,20 +309,29 @@ const freeText = {
 };
 //#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. */
+/**
+* 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[0], crop),
-		p2: contentToPdfPoint(q[1], crop),
-		p3: contentToPdfPoint(q[2], crop),
-		p4: contentToPdfPoint(q[3], crop)
+		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
@@ -593,15 +389,17 @@ 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(d.rect, crop)
+				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" ? { rect: contentToPdfRect$1(a.geom.rect, crop) } : null,
+	geometry: (a, crop) => a.geom.t === "caret" ? boxGeomFields(a.geom.rect, a.geom.rot ?? 0, crop) : null,
 	draftExtras: (a) => ({
 		rectDifferences: {
 			left: .5,
@@ -744,44 +542,6 @@ const unsupported = {
 * 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
@@ -797,7 +557,7 @@ const quadBounds = (q) => unionRect(q);
 * `/QuadPoints` (tier 2).
 */
 function linkChildRects(a) {
-	if (a.geom.t === "quads") return a.geom.quads.map(quadBounds);
+	if (a.geom.t === "quads") return a.geom.quads.map(textQuadBounds);
 	return [unionRect(selectionQuad(a.geom, a.style.strokeWidth, a.style.border))];
 }
 //#endregion
@@ -918,10 +678,51 @@ function toCreateDraft(a, crop) {
 	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`
@@ -949,6 +750,8 @@ 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 isCallout = a?.geom.t === "text" && !!a.geom.callout;
 		return {
 			id: tb.id,
 			ref: a?.ref ?? null,
@@ -962,7 +765,7 @@ function buildTextItems(m, pon, view) {
 				lineHeight: t.fontSize,
 				color: t.fontColor,
 				align: t.textAlign,
-				padding: 2,
+				padding: isCallout ? sw + 2 : sw,
 				background: a?.style.interiorColor ?? null
 			}
 		};
@@ -1115,6 +918,17 @@ const TOOL_DEFAULT_KEYS = {
 const DRAW_TAGS = ["annotation-draw", "annotation-edit"];
 const MARKUP_TAGS = ["text-select", "annotation-edit"];
 /**
+* Whether arming this ANNOTATION tool is touch consent (`Tool.touchDirect`):
+* drag-CREATE tools — shape/ink draw and text-markup select — take
+* single-finger touch wholesale (finger draws/marks, two fingers navigate:
+* the drawing-app convention). Click-to-PLACE tools (stamp, note) do not: a
+* tap places without any claim, and drags keep scrolling. Derived from the
+* gesture tags, so custom registered tools inherit the right behavior. Only
+* annotation-owned tools run through this — the built-in `pointer` tool also
+* enables `text-select`, but it is registered by the hub, not here.
+*/
+const isTouchDirect = (enables) => enables.has("annotation-draw") || enables.has("text-select");
+/**
 * 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.
@@ -1504,10 +1318,6 @@ 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);
@@ -1516,7 +1326,6 @@ const TEXT_COMMIT_DEBOUNCE_MS = 250;
 * 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();
@@ -1527,6 +1336,8 @@ function createAnnotationCapability(ctx, config = {}) {
 	*  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
@@ -1549,16 +1360,23 @@ function createAnnotationCapability(ctx, config = {}) {
 	};
 	/** 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) => {
+	*  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,
-			knobTol: cs.knob.hitSize / 2 / s,
+			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) => {
@@ -1642,11 +1460,12 @@ function createAnnotationCapability(ctx, config = {}) {
 		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 = readProp(members[0], spec.key);
+			const first = valueOf(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);
+			if (members.some((a) => JSON.stringify(valueOf(a, spec.key)) !== firstJson)) mixed.push(spec.key);
 		}
 		const v = {
 			specs,
@@ -1667,19 +1486,26 @@ function createAnnotationCapability(ctx, config = {}) {
 		const v = [];
 		for (const id of m.order) {
 			const a = m.byId[id];
-			if (!a || a.pon !== pon || a.link == null) continue;
+			if (!a || a.pon !== pon || a.subtype !== "link") 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
-			}));
+			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,
@@ -2063,7 +1889,7 @@ function createAnnotationCapability(ctx, config = {}) {
 		const crop = cropOf(dto.pageObjectNumber);
 		if (crop) apply({
 			t: "upsert",
-			annots: [fromDTO(dto, crop, source)],
+			annots: [ingestDTO(dto, crop, source)],
 			bumpAp
 		});
 	};
@@ -2085,6 +1911,346 @@ function createAnnotationCapability(ctx, config = {}) {
 		});
 		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
@@ -2092,41 +2258,54 @@ function createAnnotationCapability(ctx, config = {}) {
 	* 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));
+	/**
+	* 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 (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
+	* 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) => {
+	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(a.link);
-		const rects = a.link == null ? [] : linkChildRects(a).map((r) => contentToPdfRect(r, crop));
-		const current = a.linkRefs ?? [];
-		const nextRefs = [];
+		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 res = await page.annotations.update(current[i], {
+				const ref = current[i].ref;
+				if (!ref) continue;
+				const res = await page.annotations.update(ref, {
 					subtype: "link",
 					rect: rects[i],
 					...target ? { target } : {}
 				});
-				nextRefs.push(res.updated.ref);
+				apply({
+					t: "upsert",
+					annots: [ingestDTO(res.updated, crop, "baked")]
+				});
 			}
 			for (let i = current.length; i < rects.length; i++) {
 				const res = await page.annotations.create({
@@ -2136,20 +2315,22 @@ function createAnnotationCapability(ctx, config = {}) {
 					inReplyTo: a.ref,
 					replyType: "group"
 				});
-				nextRefs.push(res.created.ref);
+				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]
+				});
 			}
-			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. */
@@ -2274,11 +2455,70 @@ function createAnnotationCapability(ctx, config = {}) {
 			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(() => {}, () => {});
+				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;
+	};
 	return {
 		create: async (pon, draft) => {
 			const doc = ctx.doc;
@@ -2329,7 +2569,8 @@ function createAnnotationCapability(ctx, config = {}) {
 			const un = ctx.tryGet(InteractionToken)?.registerTool({
 				id: resolved.id,
 				cursor: resolved.cursor,
-				enables: resolved.enables
+				enables: resolved.enables,
+				touchDirect: isTouchDirect(resolved.enables)
 			});
 			if (resolved.defaults) apply({
 				t: "setDefaults",
@@ -2362,9 +2603,26 @@ function createAnnotationCapability(ctx, config = {}) {
 				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,
+		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);
@@ -2385,7 +2643,14 @@ function createAnnotationCapability(ctx, config = {}) {
 		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,
+		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();
@@ -2394,10 +2659,13 @@ function createAnnotationCapability(ctx, config = {}) {
 				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
-			});
+			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),
@@ -2407,6 +2675,7 @@ function createAnnotationCapability(ctx, config = {}) {
 			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("|");
@@ -2424,7 +2693,7 @@ function createAnnotationCapability(ctx, config = {}) {
 			const crop = cropOf(pon);
 			return crop ? pdfToContentRect(rect, crop) : null;
 		},
-		editPointer: (phase, pon, point, shift, scale, rotation, zoom) => apply({
+		editPointer: (phase, pon, point, shift, scale, rotation, zoom, touch) => apply({
 			t: "editPointer",
 			phase,
 			in: {
@@ -2432,7 +2701,7 @@ function createAnnotationCapability(ctx, config = {}) {
 				point,
 				shift,
 				pageBox: pageBoxOf(pon),
-				chrome: chromeGeomAt(scale),
+				chrome: chromeGeomAt(scale, grabBoost(touch)),
 				inert: inertIdsAt(pon),
 				...zoom != null ? { zoom } : {},
 				...rotation != null ? { displayRotation: rotation } : {}
@@ -2452,6 +2721,7 @@ function createAnnotationCapability(ctx, config = {}) {
 			}
 		}),
 		createPointer: (tool, phase, pon, point, finish = false, displayRotation) => {
+			if (!allowsCreate()) return;
 			const t = registry.get(tool);
 			apply({
 				t: "createPointer",
@@ -2477,30 +2747,60 @@ function createAnnotationCapability(ctx, config = {}) {
 		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({
+		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,
-			rectsByPage,
+			quadsByPage,
 			preset
 		}),
 		clearMarkupPreview: () => apply({ t: "clearMarkupPreview" }),
@@ -2570,53 +2870,35 @@ function createAnnotationCapability(ctx, config = {}) {
 			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;
+			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: () => {
-			if (!(ctx.doc?.security.allows(ANNOTATE_MODIFY) ?? false)) return false;
 			const m = model();
-			return m.selected.some((id) => groupKeyOf(m, id) != null);
+			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: (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);
-			});
+		ensurePage: () => {},
+		reloadPage: (pon) => reloadPageNow(pon),
+		hydration: () => ctx.getState().hydration,
+		ensureHydrated: () => {
+			if (hydrationStarted) return;
+			hydrationStarted = true;
+			runHydration(false);
 		},
-		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);
+		rehydrate,
+		deliverRemoteAnnotationEvent: (event) => {
+			if (hydrationWindow) {
+				pendingRemote.push(event);
+				return;
 			}
+			applyRemoteAnnotationEvent(event);
 		},
 		textItems: (pon, view) => memoTexts(pon, view),
 		currentEditing: () => model().editing,
@@ -2628,10 +2910,14 @@ function createAnnotationCapability(ctx, config = {}) {
 			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
-			});
+			if (id != null && m.byId[id]?.geom.t === "text") {
+				apply({
+					t: "beginTextEdit",
+					id
+				});
+				return true;
+			}
+			return false;
 		},
 		setContents: (ref, text) => {
 			apply({
@@ -2665,6 +2951,72 @@ function createAnnotationCapability(ctx, config = {}) {
 			textTimers.clear();
 			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 () => {
@@ -2675,6 +3027,6 @@ function createAnnotationCapability(ctx, config = {}) {
 	};
 }
 //#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 };
+export { fromDTO as a, isTouchDirect as i, DEFAULT_TOOLS as n, toCreateDraft as o, buildToolRegistry as r, toPatch as s, createAnnotationCapability as t };
 
-//# sourceMappingURL=capability-fghl0JmE.js.map
+//# sourceMappingURL=capability-DBsr2D-L.js.map