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

package/dist/{capability-Cl9x8oLS.cjs → capability-R7dgogJs.cjs}

@@ -1,238 +1,13 @@
+const require_seam = require("./seam-6pJeKOOJ.cjs");
+const require_types = require("./types-Dlhdw2k_.cjs");
 let _embedpdf_core = require("@embedpdf/core");
-let _embedpdf_plugin_interaction = require("@embedpdf/plugin-interaction");
+let _embedpdf_plugin_actions_contract = require("@embedpdf/plugin-actions/contract");
+let _embedpdf_plugin_interaction_contract = require("@embedpdf/plugin-interaction/contract");
 let _embedpdf_engine_core_runtime = require("@embedpdf/engine-core/runtime");
-let _embedpdf_plugin_selection = require("@embedpdf/plugin-selection");
+let _embedpdf_core_acrojs = require("@embedpdf/core-acrojs");
+let _embedpdf_plugin_selection_contract = require("@embedpdf/plugin-selection/contract");
 let _embedpdf_core_annotation = require("@embedpdf/core-annotation");
 let _embedpdf_core_geometry = require("@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 = (0, _embedpdf_core.createCapabilityToken)("annotation", { hint: `add annotationPlugin() from '@embedpdf/plugin-annotation' to your plugins list` });
-//#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) => (0, _embedpdf_core_annotation.normalizeDeg)(-rotCW);
-const fromPdfRotation = (rotPdf) => (0, _embedpdf_core_annotation.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: (0, _embedpdf_core_annotation.contentToPdfRect)(rect, crop),
-		rotation: null,
-		unrotatedRect: null
-	};
-	return {
-		rect: (0, _embedpdf_core_annotation.contentToPdfRect)((0, _embedpdf_core_annotation.rotatedAabb)(rect, rot), crop),
-		unrotatedRect: (0, _embedpdf_core_annotation.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: (0, _embedpdf_core_annotation.pdfToContentRect)(rot && unrotatedRect ? unrotatedRect : dto.rect, crop),
-		ellipse,
-		...rot ? { rot } : {}
-	};
-}
-/** Inset a PdfRect by a `/RD` (PDF user space, y-up: all four are non-negative
-*  insets from the matching `/Rect` edge). Used to recover the callout text box. */
-const insetPdfRectByRD = (r, rd) => rd ? {
-	left: r.left + rd.left,
-	bottom: r.bottom + rd.bottom,
-	right: r.right - rd.right,
-	top: r.top - rd.top
-} : r;
-/** Engine border fields (`/BS /S`, `/BS /D`, `/BE /I`) → the `Border` union. A
-*  cloudy effect wins over the underlying border style (which stays solid). */
-function borderFromDTO(d) {
-	if ((d.cloudyIntensity ?? 0) > 0) return {
-		kind: "cloudy",
-		intensity: d.cloudyIntensity
-	};
-	if (d.borderStyle === "dashed") return {
-		kind: "dashed",
-		dash: d.dashArray?.length ? d.dashArray : [3, 3]
-	};
-	return { kind: "solid" };
-}
-/** The writable projection of a `link` value: `goto`/`uri` pass through,
-*  read-only arms (`javascript`, `named`, `goto-remote`, `launch`,
-*  `unsupported`) yield `null` — they can be carried, never (re)written. */
-function writableTarget(t) {
-	return t && (t.kind === "goto" || t.kind === "uri") ? t : null;
-}
-const TEXT_MARKUP = /* @__PURE__ */ new Set([
-	"highlight",
-	"underline",
-	"squiggly",
-	"strikeout"
-]);
-const STROKE_KINDS = /* @__PURE__ */ new Set([
-	"square",
-	"circle",
-	"line",
-	"polygon",
-	"polyline",
-	"ink"
-]);
-/** Engine DTO → content-space `Style` (CSS colours, `Border` union). Exported so
-*  selection-aware UIs can read display values straight off a {@link AnnotationDTO}
-*  without re-deriving the colour/border mapping. */
-function styleFromDTO(dto) {
-	if (dto.subtype === "widget") return {
-		color: dto.color ? colorToCss(dto.color) : "#1a1a1a",
-		interiorColor: dto.interiorColor ? colorToCss(dto.interiorColor) : null,
-		strokeWidth: dto.strokeWidth,
-		opacity: 1,
-		blendMode: dto.blendMode,
-		border: dto.borderStyle === "dashed" ? {
-			kind: "dashed",
-			dash: [3, 3]
-		} : { kind: "solid" }
-	};
-	if (STROKE_KINDS.has(dto.subtype)) {
-		const d = dto;
-		return {
-			color: colorToCss(d.color),
-			interiorColor: d.interiorColor ? colorToCss(d.interiorColor) : null,
-			strokeWidth: d.strokeWidth,
-			opacity: d.opacity,
-			blendMode: dto.blendMode,
-			border: borderFromDTO(d)
-		};
-	}
-	if (TEXT_MARKUP.has(dto.subtype)) {
-		const d = dto;
-		return {
-			color: colorToCss(d.color),
-			interiorColor: null,
-			strokeWidth: 0,
-			opacity: d.opacity,
-			blendMode: dto.blendMode,
-			border: { kind: "solid" }
-		};
-	}
-	if (dto.subtype === "caret") {
-		const d = dto;
-		return {
-			color: colorToCss(d.color),
-			interiorColor: null,
-			strokeWidth: 1,
-			opacity: d.opacity,
-			blendMode: dto.blendMode,
-			border: { kind: "solid" }
-		};
-	}
-	if (dto.subtype === "free-text") {
-		const d = dto;
-		return {
-			color: colorToCss(d.color),
-			interiorColor: d.interiorColor ? colorToCss(d.interiorColor) : null,
-			strokeWidth: d.strokeWidth,
-			opacity: d.opacity,
-			blendMode: dto.blendMode,
-			border: borderFromDTO(d)
-		};
-	}
-	if (dto.subtype === "redact") {
-		const d = dto;
-		return {
-			color: colorToCss(d.color),
-			interiorColor: d.interiorColor ? colorToCss(d.interiorColor) : null,
-			strokeWidth: 1.5,
-			opacity: d.opacity,
-			blendMode: dto.blendMode,
-			border: { kind: "solid" }
-		};
-	}
-	if (dto.subtype === "text" || dto.subtype === "file-attachment") {
-		const d = dto;
-		return {
-			color: colorToCss(d.color),
-			interiorColor: null,
-			strokeWidth: 1,
-			opacity: d.opacity,
-			blendMode: dto.blendMode,
-			border: { kind: "solid" }
-		};
-	}
-	return {
-		color: "#444444",
-		interiorColor: null,
-		strokeWidth: 1,
-		opacity: 1,
-		blendMode: dto.blendMode,
-		border: { kind: "solid" }
-	};
-}
-/**
-* The flat props vocabulary (CSS colours, house keys) → the engine's widget
-* appearance for `doc.forms` authoring — the SAME mapping the widget patch
-* lowering uses, exported as a boundary utility so the form plugin can style
-* `placeField` from a tool's `currentDefaults` without growing a second CSS
-* parser. Absent keys stay absent (the engine writes nothing for them).
-*/
-function widgetAppearanceFromProps(props) {
-	return {
-		...props.color !== void 0 ? { color: cssToColor(props.color) } : {},
-		...props.interiorColor !== void 0 ? { interiorColor: props.interiorColor ? cssToColor(props.interiorColor) : null } : {},
-		...props.strokeWidth !== void 0 ? { strokeWidth: props.strokeWidth } : {},
-		...props.border !== void 0 ? { borderStyle: props.border.kind === "dashed" ? "dashed" : "solid" } : {},
-		...props.fontFamily !== void 0 ? { fontFamily: props.fontFamily } : {},
-		...props.fontSize !== void 0 ? { fontSize: props.fontSize } : {},
-		...props.fontColor !== void 0 ? { fontColor: cssToColor(props.fontColor) } : {},
-		...props.textAlign !== void 0 ? { textAlign: props.textAlign } : {}
-	};
-}
-//#endregion
 //#region src/repository/props.ts
 /**
 * GENERIC per-key prop lowerings — the 1:1 mappings from the flat props
@@ -251,15 +26,15 @@ const borderSlice = (style) => ({
 *  the old projections did (a fresh draft may not carry `text` yet). */
 const textOf = (a) => a.text ?? _embedpdf_core_annotation.initialTextStyle;
 const GENERIC_PROPS = {
-	color: (a) => ({ color: cssToColor(a.style.color) }),
+	color: (a) => ({ color: require_seam.cssToColor(a.style.color) }),
 	opacity: (a) => ({ opacity: a.style.opacity }),
 	blendMode: (a) => ({ blendMode: a.style.blendMode }),
-	interiorColor: (a) => ({ interiorColor: a.style.interiorColor ? cssToColor(a.style.interiorColor) : null }),
+	interiorColor: (a) => ({ interiorColor: a.style.interiorColor ? require_seam.cssToColor(a.style.interiorColor) : null }),
 	strokeWidth: (a) => ({ strokeWidth: a.style.strokeWidth }),
 	border: (a) => borderSlice(a.style),
 	fontFamily: (a) => ({ fontFamily: textOf(a).fontFamily }),
 	fontSize: (a) => ({ fontSize: textOf(a).fontSize }),
-	fontColor: (a) => ({ fontColor: cssToColor(textOf(a).fontColor) }),
+	fontColor: (a) => ({ fontColor: require_seam.cssToColor(textOf(a).fontColor) }),
 	textAlign: (a) => ({ textAlign: textOf(a).textAlign }),
 	icon: (a) => a.icon !== void 0 ? { icon: a.icon } : {},
 	link: () => ({})
@@ -270,7 +45,7 @@ const GENERIC_PROPS = {
 *  `/Rect`(+`unrotatedRect`+`rotation`), total (nulls state the clears). */
 const boxEmit = (a, crop) => {
 	const g = a.geom;
-	return boxGeomFields(g.rect, (0, _embedpdf_core_annotation.geomRotation)(a.geom), crop);
+	return require_seam.boxGeomFields(g.rect, (0, _embedpdf_core_annotation.geomRotation)(a.geom), crop);
 };
 //#endregion
 //#region src/repository/kinds/shape.ts
@@ -298,7 +73,7 @@ function cloudyExtras(a) {
 }
 const ingest = (dto, crop, ellipse) => {
 	const d = dto;
-	return { geom: boxGeomFromDTO(d, d.rotation, d.unrotatedRect, crop, ellipse) };
+	return { geom: require_seam.boxGeomFromDTO(d, d.rotation, d.unrotatedRect, crop, ellipse) };
 };
 const projection = (ellipse) => ({
 	ingest: (dto, crop) => ingest(dto, crop, ellipse),
@@ -322,7 +97,7 @@ const circle = projection(true);
 *  omission would preserve a stale advisory angle. */
 const advisoryRotation = (g) => {
 	const rot = (0, _embedpdf_core_annotation.geomRotation)(g);
-	return { rotation: rot ? toPdfRotation(rot) : null };
+	return { rotation: rot ? require_seam.toPdfRotation(rot) : null };
 };
 /** `/BE` intensity for a closed poly (polygon): the curls are generated from
 *  /Vertices + /BE alone — per ISO 32000 no /RD applies — and the /Rect
@@ -367,7 +142,7 @@ const line = {
 			a: (0, _embedpdf_core_annotation.pdfToContentPoint)(d.linePoints.start, crop),
 			b: (0, _embedpdf_core_annotation.pdfToContentPoint)(d.linePoints.end, crop),
 			ends: d.lineEndings,
-			...rotFromDTO(d.rotation)
+			...require_seam.rotFromDTO(d.rotation)
 		} };
 	},
 	geometry: (a, crop) => {
@@ -392,7 +167,7 @@ const polyProjection = (closed) => ({
 			points: d.vertices.map((p) => (0, _embedpdf_core_annotation.pdfToContentPoint)(p, crop)),
 			closed,
 			..."lineEndings" in d ? { ends: d.lineEndings } : {},
-			...rotFromDTO(d.rotation)
+			...require_seam.rotFromDTO(d.rotation)
 		} };
 	},
 	geometry: (a, crop) => {
@@ -415,7 +190,7 @@ const ink = {
 			geom: {
 				t: "ink",
 				strokes: d.inkList.map((stroke) => stroke.map((p) => (0, _embedpdf_core_annotation.pdfToContentPoint)(p, crop))),
-				...rotFromDTO(d.rotation)
+				...require_seam.rotFromDTO(d.rotation)
 			},
 			...d.intent ? { intent: d.intent } : {}
 		};
@@ -440,7 +215,7 @@ function textFromDTO(dto) {
 	return {
 		fontFamily: dto.fontFamily,
 		fontSize: dto.fontSize,
-		fontColor: colorToCss(dto.fontColor ?? dto.color),
+		fontColor: require_seam.colorToCss(dto.fontColor ?? dto.color),
 		textAlign: dto.textAlign
 	};
 }
@@ -484,7 +259,7 @@ function calloutFields(a, crop) {
 		calloutLine,
 		lineEnding: g.callout.ending,
 		...rot ? {
-			rotation: toPdfRotation(rot),
+			rotation: require_seam.toPdfRotation(rot),
 			unrotatedRect: (0, _embedpdf_core_annotation.contentToPdfRect)(g.rect, crop)
 		} : {
 			rotation: null,
@@ -497,11 +272,11 @@ const freeText = {
 		const d = dto;
 		if (d.intent === "free-text-callout" && d.calloutLine && d.calloutLine.length >= 2) {
 			const cl = d.calloutLine;
-			const rot = d.rotation ? fromPdfRotation(d.rotation) : 0;
+			const rot = d.rotation ? require_seam.fromPdfRotation(d.rotation) : 0;
 			return {
 				geom: {
 					t: "text",
-					rect: rot && d.unrotatedRect ? (0, _embedpdf_core_annotation.pdfToContentRect)(d.unrotatedRect, crop) : (0, _embedpdf_core_annotation.pdfToContentRect)(insetPdfRectByRD(d.rect, d.rectDifferences), crop),
+					rect: rot && d.unrotatedRect ? (0, _embedpdf_core_annotation.pdfToContentRect)(d.unrotatedRect, crop) : (0, _embedpdf_core_annotation.pdfToContentRect)(require_seam.insetPdfRectByRD(d.rect, d.rectDifferences), crop),
 					callout: {
 						tip: (0, _embedpdf_core_annotation.pdfToContentPoint)(cl[0], crop),
 						knee: cl.length === 3 ? (0, _embedpdf_core_annotation.pdfToContentPoint)(cl[1], crop) : void 0,
@@ -512,7 +287,7 @@ const freeText = {
 				text: textFromDTO(d)
 			};
 		}
-		const rot = d.rotation ? fromPdfRotation(d.rotation) : 0;
+		const rot = d.rotation ? require_seam.fromPdfRotation(d.rotation) : 0;
 		return {
 			geom: {
 				t: "text",
@@ -615,7 +390,7 @@ const strikeout = markupProjection("strikeout");
 const caret = {
 	ingest: (dto, crop) => {
 		const d = dto;
-		const rot = d.rotation ? fromPdfRotation(d.rotation) : 0;
+		const rot = d.rotation ? require_seam.fromPdfRotation(d.rotation) : 0;
 		return {
 			geom: {
 				t: "caret",
@@ -625,7 +400,7 @@ const caret = {
 			...d.intent ? { intent: d.intent } : {}
 		};
 	},
-	geometry: (a, crop) => a.geom.t === "caret" ? boxGeomFields(a.geom.rect, a.geom.rot ?? 0, crop) : null,
+	geometry: (a, crop) => a.geom.t === "caret" ? require_seam.boxGeomFields(a.geom.rect, a.geom.rot ?? 0, crop) : null,
 	draftExtras: (a) => ({
 		rectDifferences: {
 			left: .5,
@@ -652,7 +427,7 @@ const redact = {
 			text: {
 				fontFamily: d.fontFamily,
 				fontSize: d.fontSize,
-				fontColor: colorToCss(d.fontColor),
+				fontColor: require_seam.colorToCss(d.fontColor),
 				textAlign: d.textAlign
 			},
 			...d.overlayText ? { label: {
@@ -693,7 +468,7 @@ const fileAttachment = iconProjection("file-attachment");
 const stamp = {
 	ingest: (dto, crop) => {
 		const d = dto;
-		return { geom: boxGeomFromDTO(d, d.rotation, d.unrotatedRect, crop, false) };
+		return { geom: require_seam.boxGeomFromDTO(d, d.rotation, d.unrotatedRect, crop, false) };
 	},
 	geometry: (a, crop) => boxEmit(a, crop),
 	createable: false
@@ -712,10 +487,10 @@ const link = {
 	},
 	geometry: rectGeometry,
 	prop: { link: (a) => {
-		const target = writableTarget(a.link);
+		const target = require_seam.writableTarget(a.link);
 		return target ? { target } : a.link == null ? { target: null } : {};
 	} },
-	draftExtras: (a) => ({ target: writableTarget(a.link) })
+	draftExtras: (a) => ({ target: require_seam.writableTarget(a.link) })
 };
 /** One PDF `widget` subtype → per-family CLIENT kinds (radios have no font). */
 const WIDGET_KIND_BY_FAMILY = {
@@ -736,7 +511,7 @@ function widgetTextFromDTO(dto) {
 	return {
 		fontFamily: dto.fontFamily ?? "helvetica",
 		fontSize: dto.fontSize ?? 0,
-		fontColor: dto.fontColor ? colorToCss(dto.fontColor) : "#000000",
+		fontColor: dto.fontColor ? require_seam.colorToCss(dto.fontColor) : "#000000",
 		textAlign: dto.textAlign
 	};
 }
@@ -744,7 +519,7 @@ const widget = {
 	ingest: (dto, crop) => {
 		const d = dto;
 		return {
-			geom: boxGeomFromDTO(d, void 0, void 0, crop, false),
+			geom: require_seam.boxGeomFromDTO(d, void 0, void 0, crop, false),
 			...WIDGET_TEXT_KINDS.has(widgetKindOf(d.fieldFamily)) ? { text: widgetTextFromDTO(d) } : {}
 		};
 	},
@@ -825,16 +600,16 @@ function fromDTO(dto, crop, source = "baked") {
 	const slice = projectionOf(dto.subtype).ingest(dto, crop);
 	const strippedRect = !(dto.subtype === "free-text" && dto.intent === "free-text-callout") && "unrotatedRect" in dto && "rotation" in dto && dto.rotation ? dto.unrotatedRect : void 0;
 	return {
-		id: refKey(dto.ref),
+		id: require_seam.refKey(dto.ref),
 		ref: dto.ref,
 		pon: dto.pageObjectNumber,
 		subtype: dto.subtype === "widget" ? widgetKindOf(dto.fieldFamily) : dto.subtype,
 		flags: dto.flags,
 		source,
 		data: dto,
-		...dto.inReplyTo ? { irt: refKey(dto.inReplyTo) } : {},
-		...dto.replyType === "group" && dto.inReplyTo ? { group: refKey(dto.inReplyTo) } : {},
-		style: styleFromDTO(dto),
+		...dto.inReplyTo ? { irt: require_seam.refKey(dto.inReplyTo) } : {},
+		...dto.replyType === "group" && dto.inReplyTo ? { group: require_seam.refKey(dto.inReplyTo) } : {},
+		style: require_seam.styleFromDTO(dto),
 		...slice,
 		apBox: (0, _embedpdf_core_annotation.pdfToContentRect)(strippedRect ?? dto.rect, crop),
 		...strippedRect ? { apRot: (0, _embedpdf_core_annotation.geomRotation)(slice.geom) } : {}
@@ -909,6 +684,46 @@ function toCreateDraft(a, crop) {
 	};
 }
 //#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 = (0, _embedpdf_plugin_actions_contract.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`
@@ -960,6 +775,15 @@ function buildTextItems(m, pon, view) {
 //#endregion
 //#region src/tools.ts
 /**
+* The tool `armStamp` activates — and the only tool an armed payload survives
+* onto (plus the legacy `annotation-stamp` tag, honoured for embedder configs
+* written before the tags were unified). Placement consults the armed payload
+* BEFORE the active tool's own `source` spec, so a payload must not outlive
+* its tool onto a sibling stamp preset: an `image` preset's click has to open
+* its own picker, not silently place whatever the stamp panel last armed.
+*/
+const ARMED_STAMP_TOOL_ID = "stamp";
+/**
 * The creation properties each known authoring kind actually consumes. This is
 * deliberately separate from the flat internal patch vocabulary: it gives tool
 * configuration precise compile-time and runtime validation while mixed-selection
@@ -1293,7 +1117,7 @@ const DEFAULT_TOOLS = [
 		}
 	},
 	{
-		id: "stamp",
+		id: ARMED_STAMP_TOOL_ID,
 		subtype: "stamp",
 		cursor: "copy",
 		enables: ["annotation-place", "annotation-edit"],
@@ -1475,7 +1299,7 @@ const isIconPlaceKind = (subtype) => subtype === "text" || subtype === "file-att
 function iconPlacementDraft(subtype, geom, defaults, flags, file) {
 	const shared = {
 		...geom,
-		color: cssToColor(defaults.color),
+		color: require_seam.cssToColor(defaults.color),
 		opacity: defaults.opacity,
 		flags: {
 			print: true,
@@ -1522,6 +1346,8 @@ function createAnnotationCapability(ctx, config = {}) {
 	*  slot. See {@link FilePickerProvider}. */
 	let filePickerProvider = null;
 	const model = () => ctx.getState().model;
+	const actionsForHover = ctx.tryGet(_embedpdf_plugin_actions_contract.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
@@ -1674,11 +1500,21 @@ function createAnnotationCapability(ctx, config = {}) {
 			if (!(0, _embedpdf_core_annotation.viewable)(a.flags, false)) continue;
 			const target = a.link ?? (a.data?.subtype === "link" ? a.data.target ?? null : null);
 			if (target == null || a.geom.t !== "rect") continue;
+			const activate = a.data?.actions?.activate;
+			const ref = a.ref ?? a.data?.ref ?? void 0;
+			const hoverEnter = Boolean(a.data?.actions?.cursorEnter?.root);
+			const hoverExit = Boolean(a.data?.actions?.cursorExit?.root);
 			v.push({
 				id,
 				rect: a.geom.rect,
 				target,
-				attached: a.group !== void 0
+				attached: a.group !== void 0,
+				...activate ? { activate } : {},
+				...ref ? { ref } : {},
+				...hoverEnter || hoverExit ? { hoverEvents: {
+					enter: hoverEnter,
+					exit: hoverExit
+				} } : {}
 			});
 		}
 		linkItemsCache.set(pon, {
@@ -1739,6 +1575,14 @@ function createAnnotationCapability(ctx, config = {}) {
 	* rendered, never synced, and dies with the tool.
 	*/
 	let armedStamp = null;
+	/** Fixed bytes as a provider: the same image at every size. */
+	const fixedPreview = (bytes, mimeType) => {
+		const preview = {
+			bytes,
+			...mimeType ? { mimeType } : {}
+		};
+		return async () => preview;
+	};
 	/**
 	* The desired stamp size (PDF points) from sniffed bytes: the image's
 	* INTRINSIC pixel dimensions taken 1:1 as points (the v2 rule — keep the
@@ -1767,23 +1611,21 @@ function createAnnotationCapability(ctx, config = {}) {
 		const meta = (0, _embedpdf_engine_core_runtime.sniffBinaryMetadata)(resolved.bytes);
 		if (!meta) throw new Error("[annotation] stamp source must be PNG, JPEG, or single-page PDF bytes");
 		let preview = null;
-		if (input.preview) {
+		if (typeof input.preview === "function") preview = input.preview;
+		else if (input.preview) {
 			const p = await (0, _embedpdf_engine_core_runtime.resolveBinarySource)(input.preview);
-			preview = {
-				bytes: new Uint8Array(p.bytes),
-				mimeType: p.mimeType
-			};
-		} else if (meta.mimeType !== "application/pdf") preview = {
-			bytes: new Uint8Array(resolved.bytes),
-			mimeType: meta.mimeType
-		};
+			preview = fixedPreview(new Uint8Array(p.bytes), p.mimeType);
+		} else if (meta.mimeType !== "application/pdf") preview = fixedPreview(new Uint8Array(resolved.bytes), meta.mimeType);
 		armedStamp = {
 			source: input.source,
 			...desiredStampSize(meta, input.targetWidth, input.intrinsicSize),
-			preview
+			preview,
+			previewCache: /* @__PURE__ */ new Map(),
+			...input.name !== void 0 ? { name: input.name } : {},
+			...input.subject !== void 0 ? { subject: input.subject } : {}
 		};
 		ctx.dispatch({ type: "STAMP_ARM_CHANGED" });
-		ctx.tryGet(_embedpdf_plugin_interaction.InteractionToken)?.activateTool("stamp");
+		ctx.tryGet(_embedpdf_plugin_interaction_contract.InteractionToken)?.activateTool(ARMED_STAMP_TOOL_ID);
 	};
 	const disarmStamp = () => {
 		if (!armedStamp) return;
@@ -1910,42 +1752,66 @@ function createAnnotationCapability(ctx, config = {}) {
 	*  emits the repository's box rotation fields — the engine bakes the tilted
 	*  /AP exactly as an interactively rotated stamp round-trips, and the fit uses
 	*  the ROTATED footprint. Returns false when the page/document isn't ready. */
-	const createStampAt = (pon, point, source, desired, rotCW = 0) => {
+	const createStampAt = (pon, point, source, desired, rotCW = 0, identity = {}) => {
 		const doc = ctx.doc;
 		const crop = cropOf(pon);
-		if (!doc || !crop) return false;
+		if (!doc || !crop) return null;
 		const box = (0, _embedpdf_core_annotation.fitStampBox)(point, desired, {
 			width: crop.right - crop.left,
 			height: crop.top - crop.bottom
 		}, rotCW);
-		doc.page(pon).annotations.create({
+		return doc.page(pon).annotations.create({
 			subtype: "stamp",
-			...boxGeomFields(box, rotCW, crop),
+			...require_seam.boxGeomFields(box, rotCW, crop),
 			source,
-			fit: "contain"
+			fit: "contain",
+			...identity.name !== void 0 ? { name: identity.name } : {},
+			...identity.subject !== void 0 ? { subject: identity.subject } : {}
 		}).then((res) => {
 			syncDTO(res.created, "baked");
 			apply({
 				t: "select",
-				ids: [refKey(res.created.ref)]
+				ids: [require_seam.refKey(res.created.ref)]
 			});
-		}, (err) => console.error("[annotation] stamp placement failed:", err));
+			return res.created.ref;
+		});
+	};
+	/** The click path's fire-and-forget wrapper: a rejected placement is logged,
+	*  never thrown into the gesture. */
+	const createStampAtSync = (pon, point, source, desired, rotCW = 0, identity = {}) => {
+		const placed = createStampAt(pon, point, source, desired, rotCW, identity);
+		if (!placed) return false;
+		placed.catch((err) => console.error("[annotation] stamp placement failed:", err));
 		return true;
 	};
+	/** Programmatic placement — the same law as a click, awaited. */
+	const placeStamp = async (input, placement) => {
+		const meta = (0, _embedpdf_engine_core_runtime.sniffBinaryMetadata)((await (0, _embedpdf_engine_core_runtime.resolveBinarySource)(input.source)).bytes);
+		if (!meta) throw new Error("[annotation] stamp source must be PNG, JPEG, or single-page PDF bytes");
+		const placed = createStampAt(placement.pageObjectNumber, placement.at, input.source, desiredStampSize(meta, placement.targetWidth ?? input.targetWidth, input.intrinsicSize), placement.rotation ?? 0, {
+			...input.name !== void 0 ? { name: input.name } : {},
+			...input.subject !== void 0 ? { subject: input.subject } : {}
+		});
+		if (!placed) throw new Error(`[annotation] cannot place a stamp on page ${placement.pageObjectNumber}: document or page not ready`);
+		return placed;
+	};
 	/** The active tool's upright counter-rotation for a click at `displayRotation`
 	*  (0 when the tool doesn't ask for upright, or the display isn't rotated). */
 	const uprightRotFor = (displayRotation) => {
 		if (!displayRotation) return 0;
-		const ix = ctx.tryGet(_embedpdf_plugin_interaction.InteractionToken);
+		const ix = ctx.tryGet(_embedpdf_plugin_interaction_contract.InteractionToken);
 		return (ix ? registry.get(ix.activeToolId()) : void 0)?.upright ? (0, _embedpdf_core_annotation.uprightRotation)(displayRotation) : 0;
 	};
 	const placeArmedStamp = (pon, point, displayRotation) => {
 		const armed = armedStamp;
 		if (!armed) return false;
-		return createStampAt(pon, point, armed.source, {
+		return createStampAtSync(pon, point, armed.source, {
 			width: armed.width,
 			height: armed.height
-		}, uprightRotFor(displayRotation));
+		}, uprightRotFor(displayRotation), {
+			...armed.name !== void 0 ? { name: armed.name } : {},
+			...armed.subject !== void 0 ? { subject: armed.subject } : {}
+		});
 	};
 	/** Sniff a stamp source (rejecting non-image bytes) and place it at its
 	*  intrinsic size (fit to the page in {@link createStampAt}); `targetWidth`
@@ -1956,7 +1822,7 @@ function createAnnotationCapability(ctx, config = {}) {
 			console.error("[annotation] stamp source must be PNG, JPEG, or single-page PDF bytes");
 			return;
 		}
-		createStampAt(pon, point, source, desiredStampSize(meta, targetWidth), rotCW);
+		createStampAtSync(pon, point, source, desiredStampSize(meta, targetWidth), rotCW);
 	};
 	/**
 	* Click-to-place: resolve the ACTIVE tool's source spec. Fixed `bytes` place
@@ -1965,7 +1831,7 @@ function createAnnotationCapability(ctx, config = {}) {
 	* document changed while the picker was open (the intent expired).
 	*/
 	const requestStampAt = (pon, point, displayRotation) => {
-		const ix = ctx.tryGet(_embedpdf_plugin_interaction.InteractionToken);
+		const ix = ctx.tryGet(_embedpdf_plugin_interaction_contract.InteractionToken);
 		const tool = ix ? registry.get(ix.activeToolId()) : void 0;
 		const spec = tool?.source;
 		if (!spec) return false;
@@ -1998,7 +1864,7 @@ function createAnnotationCapability(ctx, config = {}) {
 		provider(req).then((picked) => {
 			if (!picked) return;
 			if (ctx.doc !== docAtClick) return;
-			if (ctx.tryGet(_embedpdf_plugin_interaction.InteractionToken)?.activeToolId() !== tool.id) return;
+			if (ctx.tryGet(_embedpdf_plugin_interaction_contract.InteractionToken)?.activeToolId() !== tool.id) return;
 			place(picked);
 		}, (err) => console.error("[annotation] file-picker provider failed:", err));
 		return true;
@@ -2015,12 +1881,12 @@ function createAnnotationCapability(ctx, config = {}) {
 			width: crop.right - crop.left,
 			height: crop.top - crop.bottom
 		}, rotCW);
-		const draft = iconPlacementDraft(tool.subtype, boxGeomFields(box, rotCW, crop), (0, _embedpdf_core_annotation.defaultsFor)(model(), tool.preset), tool.flags, file);
+		const draft = iconPlacementDraft(tool.subtype, require_seam.boxGeomFields(box, rotCW, crop), (0, _embedpdf_core_annotation.defaultsFor)(model(), tool.preset), tool.flags, file);
 		doc.page(pon).annotations.create(draft).then((res) => {
 			syncDTO(res.created, "baked");
 			apply({
 				t: "select",
-				ids: [refKey(res.created.ref)]
+				ids: [require_seam.refKey(res.created.ref)]
 			});
 		}, (err) => console.error("[annotation] icon placement failed:", err));
 		return true;
@@ -2038,7 +1904,7 @@ function createAnnotationCapability(ctx, config = {}) {
 	*/
 	const placeAt = (pon, point, displayRotation) => {
 		if (placeArmedStamp(pon, point, displayRotation)) return true;
-		const ix = ctx.tryGet(_embedpdf_plugin_interaction.InteractionToken);
+		const ix = ctx.tryGet(_embedpdf_plugin_interaction_contract.InteractionToken);
 		const tool = ix ? registry.get(ix.activeToolId()) : void 0;
 		if (!tool) return false;
 		if (tool.subtype === "stamp") return requestStampAt(pon, point, displayRotation);
@@ -2049,7 +1915,7 @@ function createAnnotationCapability(ctx, config = {}) {
 	};
 	/** The page a ref lives on: from the loaded model first (covers obj/nm refs
 	*  that don't carry a pon), else the ref itself (index refs do). */
-	const ponForRef = (ref) => model().byId[refKey(ref)]?.pon ?? (ref.kind === "index" ? ref.pageObjectNumber : null);
+	const ponForRef = (ref) => model().byId[require_seam.refKey(ref)]?.pon ?? (ref.kind === "index" ? ref.pageObjectNumber : null);
 	/**
 	* Re-sync one annotation into the model from the authoritative engine DTO,
 	* with the render `source` the caller decides: `'vector'` when WE authored or
@@ -2228,10 +2094,10 @@ function createAnnotationCapability(ctx, config = {}) {
 		});
 		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);
+			byMember.set(require_seam.refKey(t.root.ref), t);
+			for (const r of t.replies) byMember.set(require_seam.refKey(r.ref), t);
+			for (const g of t.groupedParts) byMember.set(require_seam.refKey(g.ref), t);
+			for (const s of t.review.statusRefs) byMember.set(require_seam.refKey(s), t);
 		}
 		return {
 			threads,
@@ -2253,7 +2119,7 @@ function createAnnotationCapability(ctx, config = {}) {
 		return threadsMemo;
 	};
 	const threadOf = (ref) => {
-		const t = threadsIndex().byMember.get(refKey(ref));
+		const t = threadsIndex().byMember.get(require_seam.refKey(ref));
 		if (!t) throw new Error("[annotation] no comment thread contains this ref");
 		return t;
 	};
@@ -2273,7 +2139,7 @@ function createAnnotationCapability(ctx, config = {}) {
 		await doc.page(ref.pageObjectNumber).annotations.delete(ref);
 		apply({
 			t: "remove",
-			ids: [refKey(ref)]
+			ids: [require_seam.refKey(ref)]
 		});
 	};
 	const REPLY_FLAGS = {
@@ -2289,7 +2155,7 @@ function createAnnotationCapability(ctx, config = {}) {
 	/** 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;
+		const d = model().byId[require_seam.refKey(ref)]?.data;
 		return {
 			...d?.userId !== void 0 ? { userId: d.userId } : {},
 			...d?.groupId !== void 0 ? { groupId: d.groupId } : {}
@@ -2322,7 +2188,7 @@ function createAnnotationCapability(ctx, config = {}) {
 	};
 	const allowsMutation = (action, ref) => ctx.doc?.security.allowsAnnotationMutation(action, mutationTarget(ref)) ?? false;
 	const deletableOne = (ref) => {
-		const a = model().byId[refKey(ref)];
+		const a = model().byId[require_seam.refKey(ref)];
 		return !!a && (0, _embedpdf_core_annotation.annotDeletable)(a);
 	};
 	const threadMemberRefs = (t) => [
@@ -2333,7 +2199,7 @@ function createAnnotationCapability(ctx, config = {}) {
 	];
 	const comments = {
 		threads: () => threadsIndex().threads,
-		thread: (ref) => threadsIndex().byMember.get(refKey(ref)) ?? null,
+		thread: (ref) => threadsIndex().byMember.get(require_seam.refKey(ref)) ?? null,
 		hydration: () => ctx.getState().hydration,
 		rehydrate,
 		reply: async (ref, text) => {
@@ -2348,7 +2214,7 @@ function createAnnotationCapability(ctx, config = {}) {
 			})).ref;
 		},
 		edit: async (ref, text) => {
-			const subtype = model().byId[refKey(ref)]?.data?.subtype;
+			const subtype = model().byId[require_seam.refKey(ref)]?.data?.subtype;
 			if (!subtype) throw new Error("[annotation] cannot edit an uncommitted annotation");
 			await updateOne(ref, {
 				subtype,
@@ -2411,13 +2277,13 @@ function createAnnotationCapability(ctx, config = {}) {
 			};
 		},
 		permissionsFor: (ref) => {
-			model().byId[refKey(ref)]?.flags;
-			const t = threadsIndex().byMember.get(refKey(ref)) ?? null;
+			model().byId[require_seam.refKey(ref)]?.flags;
+			const t = threadsIndex().byMember.get(require_seam.refKey(ref)) ?? null;
 			return {
 				canReply: allowsCreate(),
 				canSetStatus: allowsCreate(),
 				canEditText: (() => {
-					const a = model().byId[refKey(ref)];
+					const a = model().byId[require_seam.refKey(ref)];
 					return !!a && (0, _embedpdf_core_annotation.annotContentsEditable)(a);
 				})(),
 				canDelete: deletableOne(ref),
@@ -2463,7 +2329,7 @@ function createAnnotationCapability(ctx, config = {}) {
 		const crop = cropOf(a.pon);
 		if (!crop) return;
 		const page = doc.page(a.pon);
-		const target = writableTarget(desired);
+		const target = require_seam.writableTarget(desired);
 		const rects = desired == null ? [] : linkChildRects(a).map((r) => (0, _embedpdf_core_annotation.contentToPdfRect)(r, crop));
 		const current = (0, _embedpdf_core_annotation.linkChildrenOf)(model(), id);
 		try {
@@ -2561,7 +2427,7 @@ function createAnnotationCapability(ctx, config = {}) {
 					apply({
 						t: "created",
 						tempId: fx.primary,
-						id: refKey(primaryResult.created.ref),
+						id: require_seam.refKey(primaryResult.created.ref),
 						ref: primaryResult.created.ref
 					});
 					syncDTO(primaryResult.created, "vector");
@@ -2580,7 +2446,7 @@ function createAnnotationCapability(ctx, config = {}) {
 						apply({
 							t: "created",
 							tempId,
-							id: refKey(result.created.ref),
+							id: require_seam.refKey(result.created.ref),
 							ref: result.created.ref
 						});
 						syncDTO(result.created, "vector");
@@ -2589,7 +2455,7 @@ function createAnnotationCapability(ctx, config = {}) {
 					const removeIds = ids.filter((id) => !committed.some((c) => c.tempId === id));
 					for (const part of [...committed].reverse()) try {
 						await doc.page(primary.pon).annotations.delete(part.ref);
-						removeIds.push(refKey(part.ref));
+						removeIds.push(require_seam.refKey(part.ref));
 					} catch {}
 					if (removeIds.length) apply({
 						t: "remove",
@@ -2607,7 +2473,7 @@ function createAnnotationCapability(ctx, config = {}) {
 				apply({
 					t: "created",
 					tempId: fx.id,
-					id: refKey(res.created.ref),
+					id: require_seam.refKey(res.created.ref),
 					ref: res.created.ref
 				});
 				syncDTO(res.created, "vector");
@@ -2637,8 +2503,62 @@ function createAnnotationCapability(ctx, config = {}) {
 				});
 			});
 		} else if (fx.fx === "syncLink") scheduleLinkSync(fx.id, { target: fx.target });
-		else doc.page(fx.ref.pageObjectNumber).annotations.delete(fx.ref).then(() => {}, () => {});
+		else {
+			require_seam.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 = (0, _embedpdf_core_acrojs.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;
@@ -2652,6 +2572,7 @@ function createAnnotationCapability(ctx, config = {}) {
 			return res.created.ref;
 		},
 		armStamp,
+		placeStamp,
 		disarmStamp,
 		placeArmedStamp,
 		requestStampAt,
@@ -2665,7 +2586,20 @@ function createAnnotationCapability(ctx, config = {}) {
 			const g = ctx.getState().toolGhost;
 			return g && g.pon === pon ? g : null;
 		},
-		armedStampPreview: () => armedStamp?.preview ?? null,
+		armedStampPreview: (devicePixelWidth) => {
+			const armed = armedStamp;
+			if (!armed?.preview) return Promise.resolve(null);
+			const bucket = require_types.previewBucket(devicePixelWidth ?? 0);
+			let pending = armed.previewCache.get(bucket);
+			if (!pending) {
+				pending = armed.preview(bucket).catch((error) => {
+					console.error("[annotation] stamp ghost preview failed:", error);
+					return null;
+				});
+				armed.previewCache.set(bucket, pending);
+			}
+			return pending;
+		},
 		stampArmEpoch: () => ctx.getState().stampArmEpoch,
 		setFilePickerProvider: (provider) => {
 			filePickerProvider = provider;
@@ -2686,7 +2620,7 @@ function createAnnotationCapability(ctx, config = {}) {
 			const resolved = buildToolRegistry([...configTools, def]).get(def.id);
 			if (!resolved) throw new Error(`[annotation] could not resolve tool '${def.id}'`);
 			registry.set(resolved.id, resolved);
-			const un = ctx.tryGet(_embedpdf_plugin_interaction.InteractionToken)?.registerTool({
+			const un = ctx.tryGet(_embedpdf_plugin_interaction_contract.InteractionToken)?.registerTool({
 				id: resolved.id,
 				cursor: resolved.cursor,
 				enables: resolved.enables,
@@ -2720,34 +2654,34 @@ function createAnnotationCapability(ctx, config = {}) {
 			await doc.page(pon).annotations.delete(ref);
 			apply({
 				t: "remove",
-				ids: [refKey(ref)]
+				ids: [require_seam.refKey(ref)]
 			});
 		},
 		canRead: () => canRead(),
 		canCreate: () => allowsCreate(),
 		canEdit: (ref) => {
-			const a = model().byId[refKey(ref)];
+			const a = model().byId[require_seam.refKey(ref)];
 			return !!a && (0, _embedpdf_core_annotation.annotTransformable)(a);
 		},
 		canDelete: (ref) => {
-			const a = model().byId[refKey(ref)];
+			const a = model().byId[require_seam.refKey(ref)];
 			return !!a && (0, _embedpdf_core_annotation.annotDeletable)(a);
 		},
 		comments,
 		links: {
 			of: (ref) => {
-				const a = model().byId[refKey(ref)];
+				const a = model().byId[require_seam.refKey(ref)];
 				if (!a) return null;
 				return a.subtype === "link" ? a.link ?? null : (0, _embedpdf_core_annotation.linkOf)(model(), a.id);
 			},
-			set: (ref, target) => scheduleLinkSync(refKey(ref), { target }),
-			clear: (ref) => scheduleLinkSync(refKey(ref), { target: null })
+			set: (ref, target) => scheduleLinkSync(require_seam.refKey(ref), { target }),
+			clear: (ref) => scheduleLinkSync(require_seam.refKey(ref), { target: null })
 		},
 		getSelection: () => {
 			const m = model();
 			return m.selected.map((id) => m.byId[id]?.ref).filter((r) => r != null);
 		},
-		get: (ref) => model().byId[refKey(ref)]?.data ?? null,
+		get: (ref) => model().byId[require_seam.refKey(ref)]?.data ?? null,
 		list: (pon) => {
 			const m = model();
 			return m.order.map((id) => m.byId[id]).filter((a) => a?.pon === pon).map((a) => a?.data).filter((d) => d != null);
@@ -2779,10 +2713,13 @@ function createAnnotationCapability(ctx, config = {}) {
 				const h = (0, _embedpdf_core_annotation.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),
@@ -2866,7 +2803,7 @@ function createAnnotationCapability(ctx, config = {}) {
 		cancelCreationDraft: () => apply({ t: "cancel" }),
 		markupFromSelection: (subtype, preset) => {
 			if (!allowsCreate()) return false;
-			const selection = ctx.tryGet(_embedpdf_plugin_selection.SelectionToken);
+			const selection = ctx.tryGet(_embedpdf_plugin_selection_contract.SelectionToken);
 			if (!selection || !selection.hasSelection()) return false;
 			const snapshot = selection.snapshot();
 			let created = false;
@@ -2942,7 +2879,7 @@ function createAnnotationCapability(ctx, config = {}) {
 		select: (ref, options) => {
 			apply({
 				t: "select",
-				ids: [refKey(ref)],
+				ids: [require_seam.refKey(ref)],
 				add: options?.add
 			});
 		},
@@ -3002,24 +2939,7 @@ function createAnnotationCapability(ctx, config = {}) {
 			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;
-			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 {}
-		},
+		reloadPage: (pon) => reloadPageNow(pon),
 		hydration: () => ctx.getState().hydration,
 		ensureHydrated: () => {
 			if (hydrationStarted) return;
@@ -3038,7 +2958,7 @@ function createAnnotationCapability(ctx, config = {}) {
 		currentEditing: () => model().editing,
 		beginTextEdit: (ref) => apply({
 			t: "beginTextEdit",
-			id: refKey(ref)
+			id: require_seam.refKey(ref)
 		}),
 		beginTextEditAt: (pon, point, scale, rotation, zoom) => {
 			const m = model();
@@ -3056,10 +2976,10 @@ function createAnnotationCapability(ctx, config = {}) {
 		setContents: (ref, text) => {
 			apply({
 				t: "setText",
-				id: refKey(ref),
+				id: require_seam.refKey(ref),
 				text
 			});
-			const key = refKey(ref);
+			const key = require_seam.refKey(ref);
 			clearTimeout(textTimers.get(key));
 			textTimers.set(key, setTimeout(() => {
 				textTimers.delete(key);
@@ -3085,6 +3005,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 () => {
@@ -3095,10 +3081,10 @@ function createAnnotationCapability(ctx, config = {}) {
 	};
 }
 //#endregion
-Object.defineProperty(exports, "AnnotationToken", {
+Object.defineProperty(exports, "ARMED_STAMP_TOOL_ID", {
 	enumerable: true,
 	get: function() {
-		return AnnotationToken;
+		return ARMED_STAMP_TOOL_ID;
 	}
 });
 Object.defineProperty(exports, "DEFAULT_TOOLS", {
@@ -3131,18 +3117,6 @@ Object.defineProperty(exports, "isTouchDirect", {
 		return isTouchDirect;
 	}
 });
-Object.defineProperty(exports, "refKey", {
-	enumerable: true,
-	get: function() {
-		return refKey;
-	}
-});
-Object.defineProperty(exports, "styleFromDTO", {
-	enumerable: true,
-	get: function() {
-		return styleFromDTO;
-	}
-});
 Object.defineProperty(exports, "toCreateDraft", {
 	enumerable: true,
 	get: function() {
@@ -3155,11 +3129,5 @@ Object.defineProperty(exports, "toPatch", {
 		return toPatch;
 	}
 });
-Object.defineProperty(exports, "widgetAppearanceFromProps", {
-	enumerable: true,
-	get: function() {
-		return widgetAppearanceFromProps;
-	}
-});
 
-//# sourceMappingURL=capability-Cl9x8oLS.cjs.map
+//# sourceMappingURL=capability-R7dgogJs.cjs.map