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

package/dist/{capability-fghl0JmE.js → capability-BRf0HrOi.js}

@@ -1,14 +1,16 @@
 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";
+import { buildCommentThreads, encodeStableIdKey, resolveBinarySource, sniffBinaryMetadata } from "@embedpdf/engine-core/runtime";
+import { SelectionToken } from "@embedpdf/plugin-selection";
+import { FLAG_KEYS, annotContentsEditable, annotDeletable, annotTransformable, calloutLinePoints, canMove, chrome, clickCreateGeom, cloudyBorderExtent, contentToPdfPoint, contentToPdfRect, contentToPdfRect as contentToPdfRect$1, creationDraftAnchor, cursorAt, defaultsFor, expandGroups, fitStampBox, geomPdfBounds, geomRotation, geomVisualBounds, groupKeyOf, hitTest, initialTextStyle, isSubstrateOnly, linkChildrenOf, linkOf, 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";
+import { normalizeQuad, textQuadBounds } from "@embedpdf/core-geometry";
 //#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");
+const AnnotationToken = createCapabilityToken("annotation", { hint: `add annotationPlugin() from '@embedpdf/plugin-annotation' to your plugins list` });
 //#endregion
 //#region src/repository/seam.ts
 function refKey(ref) {
@@ -333,18 +335,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 +535,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 +615,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 +768,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 +783,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,6 +904,7 @@ function toCreateDraft(a, crop) {
 	return {
 		...base,
 		...extras,
+		nm: crypto.randomUUID(),
 		flags: a.flags
 	};
 }
@@ -949,6 +936,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 +951,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 +1104,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 +1504,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 +1512,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();
@@ -1549,16 +1544,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 +1644,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 +1670,16 @@ 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;
+			v.push({
+				id,
+				rect: a.geom.rect,
+				target,
+				attached: a.group !== void 0
+			});
 		}
 		linkItemsCache.set(pon, {
 			model: m,
@@ -2063,7 +2063,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 +2085,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 +2432,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 +2489,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,9 +2629,14 @@ 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);
+				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 doc.page(fx.ref.pageObjectNumber).annotations.delete(fx.ref).then(() => {}, () => {});
 	}
 	return {
@@ -2329,7 +2689,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 +2723,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 +2763,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();
@@ -2407,6 +2792,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 +2810,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 +2818,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 +2838,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 +2864,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,38 +2987,25 @@ 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);
-		},
-		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);
-			});
+			const subs = expandGroups(m, m.selected).map((id) => m.byId[id]).filter((a) => !!a && !!a.group);
+			return subs.length > 0 && subs.every((a) => a.ref != null && allowsMutation("update", a.ref));
 		},
+		ensurePage: () => {},
 		reloadPage: 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();
@@ -2612,11 +3016,23 @@ function createAnnotationCapability(ctx, config = {}) {
 				});
 				apply({
 					t: "loaded",
-					annots: foldAttachedLinks(snap.annotations.map((d) => fromDTO(d, crop)))
+					annots: snap.annotations.map((d) => ingestDTO(d, crop))
 				});
-			} catch {
-				loaded.delete(pon);
+			} catch {}
+		},
+		hydration: () => ctx.getState().hydration,
+		ensureHydrated: () => {
+			if (hydrationStarted) return;
+			hydrationStarted = true;
+			runHydration(false);
+		},
+		rehydrate,
+		deliverRemoteAnnotationEvent: (event) => {
+			if (hydrationWindow) {
+				pendingRemote.push(event);
+				return;
 			}
+			applyRemoteAnnotationEvent(event);
 		},
 		textItems: (pon, view) => memoTexts(pon, view),
 		currentEditing: () => model().editing,
@@ -2628,10 +3044,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({
@@ -2675,6 +3095,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, refKey as c, AnnotationToken as d, isTouchDirect as i, styleFromDTO as l, DEFAULT_TOOLS as n, toCreateDraft as o, buildToolRegistry as r, toPatch as s, createAnnotationCapability as t, widgetAppearanceFromProps as u };
 
-//# sourceMappingURL=capability-fghl0JmE.js.map
+//# sourceMappingURL=capability-BRf0HrOi.js.map