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

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

@@ -1,238 +1,13 @@
-import { CONTINUOUS_RENDER_POLICY, createCapabilityToken, snapAppearanceScale } from "@embedpdf/core";
-import { InteractionToken } from "@embedpdf/plugin-interaction";
+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 { n as previewBucket } from "./types-BvB1vUKb.js";
+import { CONTINUOUS_RENDER_POLICY, snapAppearanceScale } from "@embedpdf/core";
+import { ActionsToken, createHoverPump } from "@embedpdf/plugin-actions/contract";
+import { InteractionToken } from "@embedpdf/plugin-interaction/contract";
 import { buildCommentThreads, encodeStableIdKey, resolveBinarySource, sniffBinaryMetadata } from "@embedpdf/engine-core/runtime";
-import { 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 { 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/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", { 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) => normalizeDeg(-rotCW);
-const fromPdfRotation = (rotPdf) => normalizeDeg(-rotPdf);
-/** Advisory `rot` for a vertex geom, from a DTO's (PDF-convention) `rotation`.
-*  Absent → no `rot` key (kept off the geom so unrotated shapes stay clean). */
-const rotFromDTO = (rotation) => rotation ? { rot: fromPdfRotation(rotation) } : {};
-/**
-* Geometry/rotation fields for a BOX kind (square/circle/plain free-text). The
-* model's `rect` is the UNROTATED logical box and `rot` the applied tilt, so:
-*  - rot == 0 → `/Rect` IS the box; the transform pair is stated as `null`
-*    (TOTAL projection — the engine's tri-state writes preserve omissions, so
-*    an omitted field would keep a stale rotation instead of flattening it).
-*  - rot != 0 → `/Rect` is the rotated visual AABB (PDFium clips the baked /AP
-*    to it), `unrotatedRect` the logical box, `rotation` the PDF angle.
-*/
-function boxGeomFields(rect, rot, crop) {
-	if (!rot) return {
-		rect: contentToPdfRect(rect, crop),
-		rotation: null,
-		unrotatedRect: null
-	};
-	return {
-		rect: contentToPdfRect(rotatedAabb(rect, rot), crop),
-		unrotatedRect: contentToPdfRect(rect, crop),
-		rotation: toPdfRotation(rot)
-	};
-}
-/** A box geom (square/circle/stamp) from its DTO: when rotated, the LOCAL box
-*  is the stored `unrotatedRect` (the AABB `/Rect` is the rendered envelope)
-*  and `rot` the converted tilt; unrotated, `/Rect` IS the box. */
-function boxGeomFromDTO(dto, rotation, unrotatedRect, crop, ellipse) {
-	const rot = rotation ? fromPdfRotation(rotation) : 0;
-	return {
-		t: "rect",
-		rect: pdfToContentRect(rot && unrotatedRect ? unrotatedRect : dto.rect, crop),
-		ellipse,
-		...rot ? { rot } : {}
-	};
-}
-/** Inset a PdfRect by a `/RD` (PDF user space, y-up: all four are non-negative
-*  insets from the matching `/Rect` edge). Used to recover the callout text box. */
-const insetPdfRectByRD = (r, rd) => rd ? {
-	left: r.left + rd.left,
-	bottom: r.bottom + rd.bottom,
-	right: r.right - rd.right,
-	top: r.top - rd.top
-} : r;
-/** Engine border fields (`/BS /S`, `/BS /D`, `/BE /I`) → the `Border` union. A
-*  cloudy effect wins over the underlying border style (which stays solid). */
-function borderFromDTO(d) {
-	if ((d.cloudyIntensity ?? 0) > 0) return {
-		kind: "cloudy",
-		intensity: d.cloudyIntensity
-	};
-	if (d.borderStyle === "dashed") return {
-		kind: "dashed",
-		dash: d.dashArray?.length ? d.dashArray : [3, 3]
-	};
-	return { kind: "solid" };
-}
-/** The writable projection of a `link` value: `goto`/`uri` pass through,
-*  read-only arms (`javascript`, `named`, `goto-remote`, `launch`,
-*  `unsupported`) yield `null` — they can be carried, never (re)written. */
-function writableTarget(t) {
-	return t && (t.kind === "goto" || t.kind === "uri") ? t : null;
-}
-const TEXT_MARKUP = /* @__PURE__ */ new Set([
-	"highlight",
-	"underline",
-	"squiggly",
-	"strikeout"
-]);
-const STROKE_KINDS = /* @__PURE__ */ new Set([
-	"square",
-	"circle",
-	"line",
-	"polygon",
-	"polyline",
-	"ink"
-]);
-/** Engine DTO → content-space `Style` (CSS colours, `Border` union). Exported so
-*  selection-aware UIs can read display values straight off a {@link AnnotationDTO}
-*  without re-deriving the colour/border mapping. */
-function styleFromDTO(dto) {
-	if (dto.subtype === "widget") return {
-		color: dto.color ? colorToCss(dto.color) : "#1a1a1a",
-		interiorColor: dto.interiorColor ? colorToCss(dto.interiorColor) : null,
-		strokeWidth: dto.strokeWidth,
-		opacity: 1,
-		blendMode: dto.blendMode,
-		border: dto.borderStyle === "dashed" ? {
-			kind: "dashed",
-			dash: [3, 3]
-		} : { kind: "solid" }
-	};
-	if (STROKE_KINDS.has(dto.subtype)) {
-		const d = dto;
-		return {
-			color: colorToCss(d.color),
-			interiorColor: d.interiorColor ? colorToCss(d.interiorColor) : null,
-			strokeWidth: d.strokeWidth,
-			opacity: d.opacity,
-			blendMode: dto.blendMode,
-			border: borderFromDTO(d)
-		};
-	}
-	if (TEXT_MARKUP.has(dto.subtype)) {
-		const d = dto;
-		return {
-			color: colorToCss(d.color),
-			interiorColor: null,
-			strokeWidth: 0,
-			opacity: d.opacity,
-			blendMode: dto.blendMode,
-			border: { kind: "solid" }
-		};
-	}
-	if (dto.subtype === "caret") {
-		const d = dto;
-		return {
-			color: colorToCss(d.color),
-			interiorColor: null,
-			strokeWidth: 1,
-			opacity: d.opacity,
-			blendMode: dto.blendMode,
-			border: { kind: "solid" }
-		};
-	}
-	if (dto.subtype === "free-text") {
-		const d = dto;
-		return {
-			color: colorToCss(d.color),
-			interiorColor: d.interiorColor ? colorToCss(d.interiorColor) : null,
-			strokeWidth: d.strokeWidth,
-			opacity: d.opacity,
-			blendMode: dto.blendMode,
-			border: borderFromDTO(d)
-		};
-	}
-	if (dto.subtype === "redact") {
-		const d = dto;
-		return {
-			color: colorToCss(d.color),
-			interiorColor: d.interiorColor ? colorToCss(d.interiorColor) : null,
-			strokeWidth: 1.5,
-			opacity: d.opacity,
-			blendMode: dto.blendMode,
-			border: { kind: "solid" }
-		};
-	}
-	if (dto.subtype === "text" || dto.subtype === "file-attachment") {
-		const d = dto;
-		return {
-			color: colorToCss(d.color),
-			interiorColor: null,
-			strokeWidth: 1,
-			opacity: d.opacity,
-			blendMode: dto.blendMode,
-			border: { kind: "solid" }
-		};
-	}
-	return {
-		color: "#444444",
-		interiorColor: null,
-		strokeWidth: 1,
-		opacity: 1,
-		blendMode: dto.blendMode,
-		border: { kind: "solid" }
-	};
-}
-/**
-* The flat props vocabulary (CSS colours, house keys) → the engine's widget
-* appearance for `doc.forms` authoring — the SAME mapping the widget patch
-* lowering uses, exported as a boundary utility so the form plugin can style
-* `placeField` from a tool's `currentDefaults` without growing a second CSS
-* parser. Absent keys stay absent (the engine writes nothing for them).
-*/
-function widgetAppearanceFromProps(props) {
-	return {
-		...props.color !== void 0 ? { color: cssToColor(props.color) } : {},
-		...props.interiorColor !== void 0 ? { interiorColor: props.interiorColor ? cssToColor(props.interiorColor) : null } : {},
-		...props.strokeWidth !== void 0 ? { strokeWidth: props.strokeWidth } : {},
-		...props.border !== void 0 ? { borderStyle: props.border.kind === "dashed" ? "dashed" : "solid" } : {},
-		...props.fontFamily !== void 0 ? { fontFamily: props.fontFamily } : {},
-		...props.fontSize !== void 0 ? { fontSize: props.fontSize } : {},
-		...props.fontColor !== void 0 ? { fontColor: cssToColor(props.fontColor) } : {},
-		...props.textAlign !== void 0 ? { textAlign: props.textAlign } : {}
-	};
-}
-//#endregion
 //#region src/repository/props.ts
 /**
 * GENERIC per-key prop lowerings — the 1:1 mappings from the flat props
@@ -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 = 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"],
@@ -1522,6 +1346,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
@@ -1674,11 +1500,21 @@ function createAnnotationCapability(ctx, config = {}) {
 			if (!viewable(a.flags, false)) continue;
 			const target = a.link ?? (a.data?.subtype === "link" ? a.data.target ?? null : null);
 			if (target == null || a.geom.t !== "rect") continue;
+			const activate = a.data?.actions?.activate;
+			const ref = a.ref ?? a.data?.ref ?? void 0;
+			const hoverEnter = Boolean(a.data?.actions?.cursorEnter?.root);
+			const hoverExit = Boolean(a.data?.actions?.cursorExit?.root);
 			v.push({
 				id,
 				rect: a.geom.rect,
 				target,
-				attached: a.group !== void 0
+				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 = 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 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(InteractionToken)?.activateTool("stamp");
+		ctx.tryGet(InteractionToken)?.activateTool(ARMED_STAMP_TOOL_ID);
 	};
 	const disarmStamp = () => {
 		if (!armedStamp) return;
@@ -1910,28 +1752,49 @@ 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 = 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),
 			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)]
 			});
-		}, (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 = sniffBinaryMetadata((await resolveBinarySource(input.source)).bytes);
+		if (!meta) throw new Error("[annotation] stamp source must be PNG, JPEG, or single-page PDF bytes");
+		const placed = createStampAt(placement.pageObjectNumber, placement.at, input.source, desiredStampSize(meta, placement.targetWidth ?? input.targetWidth, input.intrinsicSize), placement.rotation ?? 0, {
+			...input.name !== void 0 ? { name: input.name } : {},
+			...input.subject !== void 0 ? { subject: input.subject } : {}
+		});
+		if (!placed) throw new Error(`[annotation] cannot place a stamp on page ${placement.pageObjectNumber}: document or page not ready`);
+		return placed;
+	};
 	/** The active tool's upright counter-rotation for a click at `displayRotation`
 	*  (0 when the tool doesn't ask for upright, or the display isn't rotated). */
 	const uprightRotFor = (displayRotation) => {
@@ -1942,10 +1805,13 @@ function createAnnotationCapability(ctx, config = {}) {
 	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
@@ -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 {
+			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;
@@ -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 = 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;
@@ -2779,10 +2713,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),
@@ -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;
@@ -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,6 +3081,6 @@ function createAnnotationCapability(ctx, config = {}) {
 	};
 }
 //#endregion
-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 };
+export { isTouchDirect as a, toPatch as c, buildToolRegistry as i, ARMED_STAMP_TOOL_ID as n, fromDTO as o, DEFAULT_TOOLS as r, toCreateDraft as s, createAnnotationCapability as t };
 
-//# sourceMappingURL=capability-BRf0HrOi.js.map
+//# sourceMappingURL=capability-Bh_1PL5v.js.map