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

package/dist/seam-6pJeKOOJ.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"seam-6pJeKOOJ.cjs","names":[],"sources":["../src/repository/seam.ts"],"sourcesContent":["/**\n * The geometry/colour/rotation SEAM between the engine's PDF-space wire\n * vocabulary and the core's content-space model. Every conversion between the\n * two worlds lives here — kind modules speak through these helpers and never\n * hand-roll a convention flip.\n */\nimport type {\n  AnnotationDTO,\n  AnnotationRef,\n  Color,\n  PdfLinkTarget,\n  PdfLinkTargetWritable,\n  PdfRect,\n  PdfRectDifferences,\n  StandardFont,\n  WidgetAppearance,\n} from '@embedpdf/engine-core/runtime';\nimport {\n  contentToPdfRect,\n  normalizeDeg,\n  pdfToContentRect,\n  rotatedAabb,\n  type AnnotationPropsPatch,\n  type Border,\n  type Geom,\n  type Rect,\n  type Style,\n} from '@embedpdf/core-annotation';\n\n// The content↔PDF bridge, re-exported so kind modules cross the seam through\n// ONE import point and never reach into the core's geometry directly.\nexport {\n  contentToPdfPoint,\n  contentToPdfRect,\n  pdfToContentPoint,\n  pdfToContentRect,\n} from '@embedpdf/core-annotation';\n\nexport function refKey(ref: AnnotationRef): string {\n  return ref.kind === 'objectNumber'\n    ? `obj:${ref.annotObjectNumber}`\n    : ref.kind === 'nm'\n      ? `nm:${ref.nm}`\n      : `idx:${ref.pageObjectNumber}:${ref.index}`;\n}\n\n/* ── colour seam (engine Color ↔ CSS hex) ─────────────────────────────────── */\n\nconst h2 = (n: number) =>\n  Math.max(0, Math.min(255, Math.round(n)))\n    .toString(16)\n    .padStart(2, '0');\nexport const colorToCss = (c: Color): string => `#${h2(c.r)}${h2(c.g)}${h2(c.b)}`;\nexport function cssToColor(css: string): Color {\n  const s = css.trim();\n  const m6 = /^#?([0-9a-f]{6})$/i.exec(s);\n  if (m6) {\n    const n = parseInt(m6[1], 16);\n    return { r: (n >> 16) & 255, g: (n >> 8) & 255, b: n & 255 };\n  }\n  const m3 = /^#?([0-9a-f]{3})$/i.exec(s);\n  if (m3) {\n    const [a, b, c] = m3[1];\n    return { r: parseInt(a + a, 16), g: parseInt(b + b, 16), b: parseInt(c + c, 16) };\n  }\n  return { r: 0, g: 0, b: 0 };\n}\n\n/* ── rotation seam (CW content ↔ PDF convention) ──────────────────────────────\n * The model's `rot` is CLOCKWISE in content space (y-down). PDF user space is\n * y-up, so the y-flip at this boundary turns a CW content tilt into a CCW PDF\n * tilt of the same magnitude — i.e. the stored `/EMBD_Metadata/Rotation` is the\n * NEGATION (mod 360). This is the ONE place the convention is converted; every\n * layer above speaks CW-content and the engine/PDFium speaks the PDF angle.\n */\nexport const toPdfRotation = (rotCW: number): number => normalizeDeg(-rotCW);\nexport const fromPdfRotation = (rotPdf: number): number => normalizeDeg(-rotPdf);\n\n/** Advisory `rot` for a vertex geom, from a DTO's (PDF-convention) `rotation`.\n *  Absent → no `rot` key (kept off the geom so unrotated shapes stay clean). */\nexport const rotFromDTO = (rotation?: number): { rot?: number } =>\n  rotation ? { rot: fromPdfRotation(rotation) } : {};\n\n/**\n * Geometry/rotation fields for a BOX kind (square/circle/plain free-text). The\n * model's `rect` is the UNROTATED logical box and `rot` the applied tilt, so:\n *  - rot == 0 → `/Rect` IS the box; the transform pair is stated as `null`\n *    (TOTAL projection — the engine's tri-state writes preserve omissions, so\n *    an omitted field would keep a stale rotation instead of flattening it).\n *  - rot != 0 → `/Rect` is the rotated visual AABB (PDFium clips the baked /AP\n *    to it), `unrotatedRect` the logical box, `rotation` the PDF angle.\n */\nexport function boxGeomFields(\n  rect: Rect,\n  rot: number,\n  crop: PdfRect,\n): { rect: PdfRect; unrotatedRect: PdfRect | null; rotation: number | null } {\n  if (!rot) return { rect: contentToPdfRect(rect, crop), rotation: null, unrotatedRect: null };\n  return {\n    rect: contentToPdfRect(rotatedAabb(rect, rot), crop),\n    unrotatedRect: contentToPdfRect(rect, crop),\n    rotation: toPdfRotation(rot),\n  };\n}\n\n/** A box geom (square/circle/stamp) from its DTO: when rotated, the LOCAL box\n *  is the stored `unrotatedRect` (the AABB `/Rect` is the rendered envelope)\n *  and `rot` the converted tilt; unrotated, `/Rect` IS the box. */\nexport function boxGeomFromDTO(\n  dto: { rect: PdfRect },\n  rotation: number | undefined,\n  unrotatedRect: PdfRect | undefined,\n  crop: PdfRect,\n  ellipse: boolean,\n): Geom {\n  const rot = rotation ? fromPdfRotation(rotation) : 0;\n  const box = rot && unrotatedRect ? unrotatedRect : dto.rect;\n  return { t: 'rect', rect: pdfToContentRect(box, crop), ellipse, ...(rot ? { rot } : {}) };\n}\n\n/** Inset a PdfRect by a `/RD` (PDF user space, y-up: all four are non-negative\n *  insets from the matching `/Rect` edge). Used to recover the callout text box. */\nexport const insetPdfRectByRD = (r: PdfRect, rd?: PdfRectDifferences | null): PdfRect =>\n  rd\n    ? {\n        left: r.left + rd.left,\n        bottom: r.bottom + rd.bottom,\n        right: r.right - rd.right,\n        top: r.top - rd.top,\n      }\n    : r;\n\n/** Engine border fields (`/BS /S`, `/BS /D`, `/BE /I`) → the `Border` union. A\n *  cloudy effect wins over the underlying border style (which stays solid). */\nexport function borderFromDTO(d: {\n  borderStyle?: string;\n  dashArray?: number[];\n  cloudyIntensity?: number | null;\n}): Border {\n  if ((d.cloudyIntensity ?? 0) > 0) return { kind: 'cloudy', intensity: d.cloudyIntensity! };\n  if (d.borderStyle === 'dashed')\n    return { kind: 'dashed', dash: d.dashArray?.length ? d.dashArray : [3, 3] };\n  return { kind: 'solid' };\n}\n\n/** The writable projection of a `link` value: `goto`/`uri` pass through,\n *  read-only arms (`javascript`, `named`, `goto-remote`, `launch`,\n *  `unsupported`) yield `null` — they can be carried, never (re)written. */\nexport function writableTarget(t: PdfLinkTarget | null | undefined): PdfLinkTargetWritable | null {\n  return t && (t.kind === 'goto' || t.kind === 'uri') ? t : null;\n}\n\nexport const TEXT_MARKUP = new Set(['highlight', 'underline', 'squiggly', 'strikeout']);\n// Geometric kinds that carry the `/C` stroke colour + `/BS` border. Ink belongs\n// here too (it has a stroke but no `/IC`, so its interiorColor reads back null).\nconst STROKE_KINDS = new Set(['square', 'circle', 'line', 'polygon', 'polyline', 'ink']);\n\n/** Engine DTO → content-space `Style` (CSS colours, `Border` union). Exported so\n *  selection-aware UIs can read display values straight off a {@link AnnotationDTO}\n *  without re-deriving the colour/border mapping. */\nexport function styleFromDTO(dto: AnnotationDTO): Style {\n  if (dto.subtype === 'widget') {\n    return {\n      color: dto.color ? colorToCss(dto.color) : '#1a1a1a',\n      interiorColor: dto.interiorColor ? colorToCss(dto.interiorColor) : null,\n      strokeWidth: dto.strokeWidth,\n      opacity: 1,\n      blendMode: dto.blendMode,\n      border: dto.borderStyle === 'dashed' ? { kind: 'dashed', dash: [3, 3] } : { kind: 'solid' },\n    };\n  }\n  if (STROKE_KINDS.has(dto.subtype)) {\n    const d = dto as Extract<\n      AnnotationDTO,\n      { interiorColor: Color | null; opacity: number; strokeWidth: number }\n    >;\n    return {\n      color: colorToCss(d.color),\n      interiorColor: d.interiorColor ? colorToCss(d.interiorColor) : null,\n      strokeWidth: d.strokeWidth,\n      opacity: d.opacity,\n      blendMode: dto.blendMode,\n      border: borderFromDTO(d),\n    };\n  }\n  if (TEXT_MARKUP.has(dto.subtype)) {\n    const d = dto as Extract<AnnotationDTO, { color: Color }>;\n    return {\n      color: colorToCss(d.color),\n      interiorColor: null,\n      strokeWidth: 0,\n      opacity: d.opacity,\n      blendMode: dto.blendMode,\n      border: { kind: 'solid' },\n    };\n  }\n  if (dto.subtype === 'caret') {\n    const d = dto as Extract<AnnotationDTO, { color: Color; opacity: number }>;\n    return {\n      color: colorToCss(d.color),\n      interiorColor: null,\n      strokeWidth: 1,\n      opacity: d.opacity,\n      blendMode: dto.blendMode,\n      border: { kind: 'solid' },\n    };\n  }\n  if (dto.subtype === 'free-text') {\n    // `/DA` colour is the border + leader stroke; `/C` is the box background; `/BS`\n    // gives the width. A plain text box draws no vector scene, so these only matter\n    // for a callout's leader/arrow/box-border (and the style toolbar's readout).\n    const d = dto as Extract<AnnotationDTO, { subtype: 'free-text' }>;\n    return {\n      color: colorToCss(d.color),\n      interiorColor: d.interiorColor ? colorToCss(d.interiorColor) : null,\n      strokeWidth: d.strokeWidth,\n      opacity: d.opacity,\n      blendMode: dto.blendMode,\n      border: borderFromDTO(d),\n    };\n  }\n  if (dto.subtype === 'redact') {\n    // `/C` is the marking-stage outline; `/IC` the fill painted on apply.\n    // No `/BS` on redact — the outline weight is a client rendering choice.\n    const d = dto as Extract<AnnotationDTO, { subtype: 'redact' }>;\n    return {\n      color: colorToCss(d.color),\n      interiorColor: d.interiorColor ? colorToCss(d.interiorColor) : null,\n      strokeWidth: 1.5,\n      opacity: d.opacity,\n      blendMode: dto.blendMode,\n      border: { kind: 'solid' },\n    };\n  }\n  if (dto.subtype === 'text' || dto.subtype === 'file-attachment') {\n    // Icon kinds: /C is the icon fill, /CA its opacity — no stroke/fill split.\n    const d = dto as Extract<AnnotationDTO, { color: Color; opacity: number }>;\n    return {\n      color: colorToCss(d.color),\n      interiorColor: null,\n      strokeWidth: 1,\n      opacity: d.opacity,\n      blendMode: dto.blendMode,\n      border: { kind: 'solid' },\n    };\n  }\n  return {\n    color: '#444444',\n    interiorColor: null,\n    strokeWidth: 1,\n    opacity: 1,\n    blendMode: dto.blendMode,\n    border: { kind: 'solid' },\n  };\n}\n\n/**\n * The flat props vocabulary (CSS colours, house keys) → the engine's widget\n * appearance for `doc.forms` authoring — the SAME mapping the widget patch\n * lowering uses, exported as a boundary utility so the form plugin can style\n * `placeField` from a tool's `currentDefaults` without growing a second CSS\n * parser. Absent keys stay absent (the engine writes nothing for them).\n */\nexport function widgetAppearanceFromProps(props: AnnotationPropsPatch): WidgetAppearance {\n  return {\n    ...(props.color !== undefined ? { color: cssToColor(props.color) } : {}),\n    ...(props.interiorColor !== undefined\n      ? { interiorColor: props.interiorColor ? cssToColor(props.interiorColor) : null }\n      : {}),\n    ...(props.strokeWidth !== undefined ? { strokeWidth: props.strokeWidth } : {}),\n    ...(props.border !== undefined\n      ? { borderStyle: props.border.kind === 'dashed' ? ('dashed' as const) : ('solid' as const) }\n      : {}),\n    ...(props.fontFamily !== undefined ? { fontFamily: props.fontFamily as StandardFont } : {}),\n    ...(props.fontSize !== undefined ? { fontSize: props.fontSize } : {}),\n    ...(props.fontColor !== undefined ? { fontColor: cssToColor(props.fontColor) } : {}),\n    ...(props.textAlign !== undefined ? { textAlign: props.textAlign } : {}),\n  };\n}\n"],"mappings":"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"}

package/dist/seam-C4L_7rDt.js

@@ -0,0 +1,225 @@
+import { contentToPdfPoint, contentToPdfRect, contentToPdfRect as contentToPdfRect$1, normalizeDeg, pdfToContentPoint as pdfToContentPoint$1, pdfToContentRect, pdfToContentRect as pdfToContentRect$1, rotatedAabb } from "@embedpdf/core-annotation";
+//#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
+export { contentToPdfRect$1 as a, insetPdfRectByRD as c, refKey as d, rotFromDTO as f, writableTarget as g, widgetAppearanceFromProps as h, contentToPdfPoint as i, pdfToContentPoint$1 as l, toPdfRotation as m, boxGeomFromDTO as n, cssToColor as o, styleFromDTO as p, colorToCss as r, fromPdfRotation as s, boxGeomFields as t, pdfToContentRect$1 as u };
+
+//# sourceMappingURL=seam-C4L_7rDt.js.map

package/dist/seam-C4L_7rDt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"seam-C4L_7rDt.js","names":[],"sources":["../src/repository/seam.ts"],"sourcesContent":["/**\n * The geometry/colour/rotation SEAM between the engine's PDF-space wire\n * vocabulary and the core's content-space model. Every conversion between the\n * two worlds lives here — kind modules speak through these helpers and never\n * hand-roll a convention flip.\n */\nimport type {\n  AnnotationDTO,\n  AnnotationRef,\n  Color,\n  PdfLinkTarget,\n  PdfLinkTargetWritable,\n  PdfRect,\n  PdfRectDifferences,\n  StandardFont,\n  WidgetAppearance,\n} from '@embedpdf/engine-core/runtime';\nimport {\n  contentToPdfRect,\n  normalizeDeg,\n  pdfToContentRect,\n  rotatedAabb,\n  type AnnotationPropsPatch,\n  type Border,\n  type Geom,\n  type Rect,\n  type Style,\n} from '@embedpdf/core-annotation';\n\n// The content↔PDF bridge, re-exported so kind modules cross the seam through\n// ONE import point and never reach into the core's geometry directly.\nexport {\n  contentToPdfPoint,\n  contentToPdfRect,\n  pdfToContentPoint,\n  pdfToContentRect,\n} from '@embedpdf/core-annotation';\n\nexport function refKey(ref: AnnotationRef): string {\n  return ref.kind === 'objectNumber'\n    ? `obj:${ref.annotObjectNumber}`\n    : ref.kind === 'nm'\n      ? `nm:${ref.nm}`\n      : `idx:${ref.pageObjectNumber}:${ref.index}`;\n}\n\n/* ── colour seam (engine Color ↔ CSS hex) ─────────────────────────────────── */\n\nconst h2 = (n: number) =>\n  Math.max(0, Math.min(255, Math.round(n)))\n    .toString(16)\n    .padStart(2, '0');\nexport const colorToCss = (c: Color): string => `#${h2(c.r)}${h2(c.g)}${h2(c.b)}`;\nexport function cssToColor(css: string): Color {\n  const s = css.trim();\n  const m6 = /^#?([0-9a-f]{6})$/i.exec(s);\n  if (m6) {\n    const n = parseInt(m6[1], 16);\n    return { r: (n >> 16) & 255, g: (n >> 8) & 255, b: n & 255 };\n  }\n  const m3 = /^#?([0-9a-f]{3})$/i.exec(s);\n  if (m3) {\n    const [a, b, c] = m3[1];\n    return { r: parseInt(a + a, 16), g: parseInt(b + b, 16), b: parseInt(c + c, 16) };\n  }\n  return { r: 0, g: 0, b: 0 };\n}\n\n/* ── rotation seam (CW content ↔ PDF convention) ──────────────────────────────\n * The model's `rot` is CLOCKWISE in content space (y-down). PDF user space is\n * y-up, so the y-flip at this boundary turns a CW content tilt into a CCW PDF\n * tilt of the same magnitude — i.e. the stored `/EMBD_Metadata/Rotation` is the\n * NEGATION (mod 360). This is the ONE place the convention is converted; every\n * layer above speaks CW-content and the engine/PDFium speaks the PDF angle.\n */\nexport const toPdfRotation = (rotCW: number): number => normalizeDeg(-rotCW);\nexport const fromPdfRotation = (rotPdf: number): number => normalizeDeg(-rotPdf);\n\n/** Advisory `rot` for a vertex geom, from a DTO's (PDF-convention) `rotation`.\n *  Absent → no `rot` key (kept off the geom so unrotated shapes stay clean). */\nexport const rotFromDTO = (rotation?: number): { rot?: number } =>\n  rotation ? { rot: fromPdfRotation(rotation) } : {};\n\n/**\n * Geometry/rotation fields for a BOX kind (square/circle/plain free-text). The\n * model's `rect` is the UNROTATED logical box and `rot` the applied tilt, so:\n *  - rot == 0 → `/Rect` IS the box; the transform pair is stated as `null`\n *    (TOTAL projection — the engine's tri-state writes preserve omissions, so\n *    an omitted field would keep a stale rotation instead of flattening it).\n *  - rot != 0 → `/Rect` is the rotated visual AABB (PDFium clips the baked /AP\n *    to it), `unrotatedRect` the logical box, `rotation` the PDF angle.\n */\nexport function boxGeomFields(\n  rect: Rect,\n  rot: number,\n  crop: PdfRect,\n): { rect: PdfRect; unrotatedRect: PdfRect | null; rotation: number | null } {\n  if (!rot) return { rect: contentToPdfRect(rect, crop), rotation: null, unrotatedRect: null };\n  return {\n    rect: contentToPdfRect(rotatedAabb(rect, rot), crop),\n    unrotatedRect: contentToPdfRect(rect, crop),\n    rotation: toPdfRotation(rot),\n  };\n}\n\n/** A box geom (square/circle/stamp) from its DTO: when rotated, the LOCAL box\n *  is the stored `unrotatedRect` (the AABB `/Rect` is the rendered envelope)\n *  and `rot` the converted tilt; unrotated, `/Rect` IS the box. */\nexport function boxGeomFromDTO(\n  dto: { rect: PdfRect },\n  rotation: number | undefined,\n  unrotatedRect: PdfRect | undefined,\n  crop: PdfRect,\n  ellipse: boolean,\n): Geom {\n  const rot = rotation ? fromPdfRotation(rotation) : 0;\n  const box = rot && unrotatedRect ? unrotatedRect : dto.rect;\n  return { t: 'rect', rect: pdfToContentRect(box, crop), ellipse, ...(rot ? { rot } : {}) };\n}\n\n/** Inset a PdfRect by a `/RD` (PDF user space, y-up: all four are non-negative\n *  insets from the matching `/Rect` edge). Used to recover the callout text box. */\nexport const insetPdfRectByRD = (r: PdfRect, rd?: PdfRectDifferences | null): PdfRect =>\n  rd\n    ? {\n        left: r.left + rd.left,\n        bottom: r.bottom + rd.bottom,\n        right: r.right - rd.right,\n        top: r.top - rd.top,\n      }\n    : r;\n\n/** Engine border fields (`/BS /S`, `/BS /D`, `/BE /I`) → the `Border` union. A\n *  cloudy effect wins over the underlying border style (which stays solid). */\nexport function borderFromDTO(d: {\n  borderStyle?: string;\n  dashArray?: number[];\n  cloudyIntensity?: number | null;\n}): Border {\n  if ((d.cloudyIntensity ?? 0) > 0) return { kind: 'cloudy', intensity: d.cloudyIntensity! };\n  if (d.borderStyle === 'dashed')\n    return { kind: 'dashed', dash: d.dashArray?.length ? d.dashArray : [3, 3] };\n  return { kind: 'solid' };\n}\n\n/** The writable projection of a `link` value: `goto`/`uri` pass through,\n *  read-only arms (`javascript`, `named`, `goto-remote`, `launch`,\n *  `unsupported`) yield `null` — they can be carried, never (re)written. */\nexport function writableTarget(t: PdfLinkTarget | null | undefined): PdfLinkTargetWritable | null {\n  return t && (t.kind === 'goto' || t.kind === 'uri') ? t : null;\n}\n\nexport const TEXT_MARKUP = new Set(['highlight', 'underline', 'squiggly', 'strikeout']);\n// Geometric kinds that carry the `/C` stroke colour + `/BS` border. Ink belongs\n// here too (it has a stroke but no `/IC`, so its interiorColor reads back null).\nconst STROKE_KINDS = new Set(['square', 'circle', 'line', 'polygon', 'polyline', 'ink']);\n\n/** Engine DTO → content-space `Style` (CSS colours, `Border` union). Exported so\n *  selection-aware UIs can read display values straight off a {@link AnnotationDTO}\n *  without re-deriving the colour/border mapping. */\nexport function styleFromDTO(dto: AnnotationDTO): Style {\n  if (dto.subtype === 'widget') {\n    return {\n      color: dto.color ? colorToCss(dto.color) : '#1a1a1a',\n      interiorColor: dto.interiorColor ? colorToCss(dto.interiorColor) : null,\n      strokeWidth: dto.strokeWidth,\n      opacity: 1,\n      blendMode: dto.blendMode,\n      border: dto.borderStyle === 'dashed' ? { kind: 'dashed', dash: [3, 3] } : { kind: 'solid' },\n    };\n  }\n  if (STROKE_KINDS.has(dto.subtype)) {\n    const d = dto as Extract<\n      AnnotationDTO,\n      { interiorColor: Color | null; opacity: number; strokeWidth: number }\n    >;\n    return {\n      color: colorToCss(d.color),\n      interiorColor: d.interiorColor ? colorToCss(d.interiorColor) : null,\n      strokeWidth: d.strokeWidth,\n      opacity: d.opacity,\n      blendMode: dto.blendMode,\n      border: borderFromDTO(d),\n    };\n  }\n  if (TEXT_MARKUP.has(dto.subtype)) {\n    const d = dto as Extract<AnnotationDTO, { color: Color }>;\n    return {\n      color: colorToCss(d.color),\n      interiorColor: null,\n      strokeWidth: 0,\n      opacity: d.opacity,\n      blendMode: dto.blendMode,\n      border: { kind: 'solid' },\n    };\n  }\n  if (dto.subtype === 'caret') {\n    const d = dto as Extract<AnnotationDTO, { color: Color; opacity: number }>;\n    return {\n      color: colorToCss(d.color),\n      interiorColor: null,\n      strokeWidth: 1,\n      opacity: d.opacity,\n      blendMode: dto.blendMode,\n      border: { kind: 'solid' },\n    };\n  }\n  if (dto.subtype === 'free-text') {\n    // `/DA` colour is the border + leader stroke; `/C` is the box background; `/BS`\n    // gives the width. A plain text box draws no vector scene, so these only matter\n    // for a callout's leader/arrow/box-border (and the style toolbar's readout).\n    const d = dto as Extract<AnnotationDTO, { subtype: 'free-text' }>;\n    return {\n      color: colorToCss(d.color),\n      interiorColor: d.interiorColor ? colorToCss(d.interiorColor) : null,\n      strokeWidth: d.strokeWidth,\n      opacity: d.opacity,\n      blendMode: dto.blendMode,\n      border: borderFromDTO(d),\n    };\n  }\n  if (dto.subtype === 'redact') {\n    // `/C` is the marking-stage outline; `/IC` the fill painted on apply.\n    // No `/BS` on redact — the outline weight is a client rendering choice.\n    const d = dto as Extract<AnnotationDTO, { subtype: 'redact' }>;\n    return {\n      color: colorToCss(d.color),\n      interiorColor: d.interiorColor ? colorToCss(d.interiorColor) : null,\n      strokeWidth: 1.5,\n      opacity: d.opacity,\n      blendMode: dto.blendMode,\n      border: { kind: 'solid' },\n    };\n  }\n  if (dto.subtype === 'text' || dto.subtype === 'file-attachment') {\n    // Icon kinds: /C is the icon fill, /CA its opacity — no stroke/fill split.\n    const d = dto as Extract<AnnotationDTO, { color: Color; opacity: number }>;\n    return {\n      color: colorToCss(d.color),\n      interiorColor: null,\n      strokeWidth: 1,\n      opacity: d.opacity,\n      blendMode: dto.blendMode,\n      border: { kind: 'solid' },\n    };\n  }\n  return {\n    color: '#444444',\n    interiorColor: null,\n    strokeWidth: 1,\n    opacity: 1,\n    blendMode: dto.blendMode,\n    border: { kind: 'solid' },\n  };\n}\n\n/**\n * The flat props vocabulary (CSS colours, house keys) → the engine's widget\n * appearance for `doc.forms` authoring — the SAME mapping the widget patch\n * lowering uses, exported as a boundary utility so the form plugin can style\n * `placeField` from a tool's `currentDefaults` without growing a second CSS\n * parser. Absent keys stay absent (the engine writes nothing for them).\n */\nexport function widgetAppearanceFromProps(props: AnnotationPropsPatch): WidgetAppearance {\n  return {\n    ...(props.color !== undefined ? { color: cssToColor(props.color) } : {}),\n    ...(props.interiorColor !== undefined\n      ? { interiorColor: props.interiorColor ? cssToColor(props.interiorColor) : null }\n      : {}),\n    ...(props.strokeWidth !== undefined ? { strokeWidth: props.strokeWidth } : {}),\n    ...(props.border !== undefined\n      ? { borderStyle: props.border.kind === 'dashed' ? ('dashed' as const) : ('solid' as const) }\n      : {}),\n    ...(props.fontFamily !== undefined ? { fontFamily: props.fontFamily as StandardFont } : {}),\n    ...(props.fontSize !== undefined ? { fontSize: props.fontSize } : {}),\n    ...(props.fontColor !== undefined ? { fontColor: cssToColor(props.fontColor) } : {}),\n    ...(props.textAlign !== undefined ? { textAlign: props.textAlign } : {}),\n  };\n}\n"],"mappings":"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"}

package/dist/{types-Due7UgzE.d.cts → types-BAPdbfPT.d.cts}

@@ -1,7 +1,8 @@
+import { AnnotationFlags, AnnotationProps, AnnotationPropsPatch, ChromeNode, ClickCreate, CreationDraftAnchor, Geom, Id, InkStraightenOptions, Model, PropKey, PropSpec, Rect, RenderItem, SnapSettings, Subtype, TextEndAnchor, TextQuad, Vec, ViewEnv } from "@embedpdf/core-annotation";
+import { AnnotationAppearanceImage, AnnotationDTO, AnnotationDraft, AnnotationPatch, AnnotationRef, AttachmentContent, AttachmentFileSource, BinarySource, CommentThread, InkIntent, PdfActionTree, PdfLinkTarget, PdfRect } from "@embedpdf/engine-core/runtime";
 import { DocumentEvent, PageObjectNumber } from "@embedpdf/core";
+import { AnnotCommitEntry, AnnotCommitResult } from "@embedpdf/plugin-actions/contract/host";
 import { PageRotation } from "@embedpdf/core-geometry";
-import { AnnotationAppearanceImage, AnnotationDTO, AnnotationDraft, AnnotationPatch, AnnotationRef, AttachmentContent, AttachmentFileSource, BinarySource, CommentThread, InkIntent, PdfLinkTarget, PdfRect } from "@embedpdf/engine-core/runtime";
-import { AnnotationFlags, AnnotationProps, AnnotationPropsPatch, ChromeNode, ClickCreate, CreationDraftAnchor, Geom, Id, InkStraightenOptions, Model, PropKey, PropSpec, Rect, RenderItem, SnapSettings, Subtype, TextEndAnchor, TextQuad, Vec, ViewEnv } from "@embedpdf/core-annotation";
 //#region src/tools.d.ts
 /**
  * How a stamp-family tool resolves the image bytes it places — pure DATA, so a
@@ -429,6 +430,19 @@ interface LinkNavItem {
    * stays selectable/movable; standalone document links navigate regardless.
    */
   attached: boolean;
+  /** The full payload-carrying `/A` tree, when one exists — the action
+   *  engine's dispatch input. `target` remains its root projection. */
+  activate?: PdfActionTree;
+  /** The annotation ref, carried for ActionSource context. */
+  ref?: AnnotationRef;
+  /** Which `/AA` hover trees this link carries — the nav layer's pump flags
+   *  (tree-less hover must cost zero dispatches). Links are behavior-inert
+   *  to the annotation plane's hover feed while navigable, so THEIR
+   *  cursorEnter/cursorExit can only fire from the LinkLayer anchors. */
+  hoverEvents?: {
+    enter: boolean;
+    exit: boolean;
+  };
 }
 interface Behavior {
   id: string;
@@ -490,8 +504,9 @@ interface TextItem {
  * package root (`@embedpdf/plugin-annotation`).
  *
  * Framework-only plumbing (render projection, pointer gestures, behavior
- * registration) lives on {@link AnnotationHostCapability}, reachable only through
- * the `@embedpdf/plugin-annotation/internal` entry. Both are the SAME runtime
+ * registration) lives on {@link AnnotationHostCapability}, reachable through
+ * `@embedpdf/plugin-annotation/contract/host` (and the framework's `/internal`
+ * entry). Both are the SAME runtime
  * object — two typed lenses on one token — so app code simply can't see the host
  * methods.
  */
@@ -709,6 +724,13 @@ interface AnnotationCapability {
   armStamp(input: StampToolInput): Promise<void>;
   /** Drop the armed stamp payload (a tool change away from 'stamp' does this too). */
   disarmStamp(): void;
+  /**
+   * Place a stamp WITHOUT the pointer: the same validation, fit, page clamp,
+   * `/Name`, and `/Subj` a click after {@link armStamp} produces — the one
+   * placement law, exposed for code. Resolves to the created annotation's
+   * ref; the placement is selected like a click's.
+   */
+  placeStamp(input: StampToolInput, placement: StampPlacement): Promise<AnnotationRef>;
   /**
    * Install the ONE file-picker port every click-then-pick tool resolves
    * through (see {@link FilePickerProvider}) — the stamp `'prompt'` source and
@@ -757,14 +779,18 @@ interface StampToolInput {
   source: BinarySource;
   /** Placed width in PDF points (height follows the intrinsic aspect). Default 150. */
   targetWidth?: number;
+  /** The placed annotation's `/Name` — the stamp identifier (standard or custom). */
+  name?: string;
+  /** The placed annotation's `/Subj`. */
+  subject?: string;
   /**
-   * A browser-paintable render of `source` for the hover ghost (PNG/JPEG).
-   * Required for the ghost when `source` is PDF bytes — the browser cannot
-   * paint those; the caller (e.g. a stamp library) supplies its cached page
-   * render. Raster sources default to the source itself; omit everywhere
-   * else and the tool simply shows no ghost.
+   * The hover ghost's image. Either fixed bytes (PNG/JPEG) or — for vector
+   * sources, which are only ever right at ONE on-screen size — a
+   * {@link StampPreviewProvider} the ghost asks for a render at the device
+   * pixel width it is displayed at. Raster sources default to themselves;
+   * omit and the tool simply shows no ghost.
    */
-  preview?: BinarySource;
+  preview?: BinarySource | StampPreviewProvider;
   /**
    * The source's intrinsic size in PDF points. Raster sources are measured
    * from their own header, but PDF bytes carry no sniffable dimensions —
@@ -782,6 +808,33 @@ interface ArmedStampPreview {
   bytes: Uint8Array;
   mimeType?: string;
 }
+/**
+ * Resolution-aware ghost preview: "give me this stamp at `devicePixelWidth`
+ * pixels wide". The annotation plugin buckets the request (see
+ * {@link previewBucket}) and caches per bucket for the arm's lifetime, so a
+ * zoom gesture never renders per frame and one render serves a zoom range.
+ * A stamp library renders its page lazily through its asset engine; a raster
+ * returns itself (it cannot get sharper than its pixels).
+ */
+type StampPreviewProvider = (devicePixelWidth: number) => Promise<ArmedStampPreview | null>;
+/**
+ * Ghost render buckets: powers of two from 128 px up to `cap`. The same policy
+ * the page renderer uses — one bitmap per size class, never per zoom step.
+ */
+declare function previewBucket(devicePixelWidth: number, cap?: number): number;
+/**
+ * Where a programmatic stamp placement lands — the inputs a click supplies.
+ * The box is fitted and clamped exactly as the click path does it.
+ */
+interface StampPlacement {
+  pageObjectNumber: PageObjectNumber;
+  /** Anchor in page points (content space): the placement is centred here. */
+  at: Vec;
+  /** Placed width in PDF points; default the payload's intrinsic size. */
+  targetWidth?: number;
+  /** Content rotation, degrees clockwise. Default 0. */
+  rotation?: number;
+}
 /**
  * What the {@link FilePickerProvider} is asked for: which tool clicked (id +
  * the kind it creates), the tool's `accept` filter, and the page-space point
@@ -818,8 +871,9 @@ type FilePickerProvider = (req: FilePromptRequest) => Promise<AttachmentFileSour
 /**
  * The HOST (framework) surface: everything the render layer, the interaction hub,
  * and sibling plugins need, on top of the public {@link AnnotationCapability}.
- * Internal — import the token from `@embedpdf/plugin-annotation/internal`, never
- * from application code.
+ * Host-only — sibling plugins import the token from
+ * `@embedpdf/plugin-annotation/contract/host`; framework implementation code may
+ * use `/internal`. Never use either from application code.
  */
 interface AnnotationHostCapability extends AnnotationCapability {
   /** `view` (the page's scale + total display rotation, from its transform)
@@ -1024,8 +1078,13 @@ interface AnnotationHostCapability extends AnnotationCapability {
    *  Vector ghosts also ride {@link pageItems}; only `kind: 'image'` ghosts
    *  need the framework's blit. */
   toolGhost(pon: PageObjectNumber): ToolGhost | null;
-  /** The armed stamp's paintable preview bytes, or null (no ghost to show). */
-  armedStampPreview(): ArmedStampPreview | null;
+  /**
+   * The armed stamp's paintable preview at (roughly) `devicePixelWidth`
+   * pixels wide — bucketed and cached per bucket for the arm's lifetime —
+   * or null when there is no ghost to show. Omit the width for the
+   * smallest bucket.
+   */
+  armedStampPreview(devicePixelWidth?: number): Promise<ArmedStampPreview | null>;
   /** Bumps on arm/disarm — keys the render layer's preview object-URL lifetime. */
   stampArmEpoch(): number;
   /**
@@ -1046,13 +1105,25 @@ interface AnnotationHostCapability extends AnnotationCapability {
    *  gesture and the created annotation's PDF kind. Falls back to the id. */
   toolSubtype(id: string): Subtype;
   registerBehavior(b: Behavior): () => void;
+  /**
+   * The actions plane's session-visibility write (Hide actions, script
+   * `annot.hidden`): resolve annotation OBJECT NUMBERS to loaded model ids
+   * (the `obj:` refKey seam) and merge session-hidden overrides. Returns how
+   * many resolved — unresolved numbers (unloaded pages, nm/index refs) are
+   * the caller's diagnostics. Session state only; never an engine write.
+   */
+  /** The script/Hide DOCUMENT-commit door (full ISO): engine updates +
+   *  model reconciliation, per entry, stop-on-failure. Never enqueues,
+   *  never touches the script host — the D2 sink contract. */
+  commitScriptEffects(entries: AnnotCommitEntry[]): Promise<AnnotCommitResult>;
 }
 /**
  * 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}.
+ * here (the package internals, `/contract/host`, and `/internal` use this view).
+ * The package root re-exports the SAME token narrowed to
+ * {@link AnnotationCapability}.
  */
 declare const AnnotationToken: import("@embedpdf/core").CapabilityToken<AnnotationHostCapability>;
 //#endregion
-export { StampSourceSpec as A, AnnotationToolInput as C, PromptSourceSpec as D, InkAuthoringOptions as E, ToolDefaultsFor as M, buildToolRegistry as N, ResolvedTool as O, AnnotationToolDef as S, GhostPolicy as T, SelectionProps as _, AnnotationHydration as a, ThreadDeleteResult as b, Behavior as c, CommentPermissions as d, CommentsApi as f, SelectionFlags as g, LinkNavItem as h, AnnotationHostCapability as i, ToolAuthoringKind as j, SelectionAuthoring as k, ChromeSettings as l, FilePromptRequest as m, AnnotationCapability as n, AnnotationState as o, FilePickerProvider as p, AnnotationConfig as r, AnnotationToken as s, AnnotationAction as t, ChromeSettingsPatch as u, StampToolInput as v, DEFAULT_TOOLS as w, ToolGhost as x, TextItem as y };
-//# sourceMappingURL=types-Due7UgzE.d.cts.map
+export { PromptSourceSpec as A, ToolGhost as C, DEFAULT_TOOLS as D, AnnotationToolInput as E, ToolDefaultsFor as F, buildToolRegistry as I, SelectionAuthoring as M, StampSourceSpec as N, GhostPolicy as O, ToolAuthoringKind as P, ThreadDeleteResult as S, AnnotationToolDef as T, SelectionProps as _, AnnotationHydration as a, StampToolInput as b, Behavior as c, CommentPermissions as d, CommentsApi as f, SelectionFlags as g, LinkNavItem as h, AnnotationHostCapability as i, ResolvedTool as j, InkAuthoringOptions as k, ChromeSettings as l, FilePromptRequest as m, AnnotationCapability as n, AnnotationState as o, FilePickerProvider as p, AnnotationConfig as r, AnnotationToken as s, AnnotationAction as t, ChromeSettingsPatch as u, StampPlacement as v, previewBucket as w, TextItem as x, StampPreviewProvider as y };
+//# sourceMappingURL=types-BAPdbfPT.d.cts.map

package/dist/{types-DITX_3CG.d.ts → types-BgetZ4BK.d.ts}

@@ -1,5 +1,6 @@
 import { DocumentEvent, PageObjectNumber } from "@embedpdf/core";
-import { AnnotationAppearanceImage, AnnotationDTO, AnnotationDraft, AnnotationPatch, AnnotationRef, AttachmentContent, AttachmentFileSource, BinarySource, CommentThread, InkIntent, PdfLinkTarget, PdfRect } from "@embedpdf/engine-core/runtime";
+import { AnnotCommitEntry, AnnotCommitResult } from "@embedpdf/plugin-actions/contract/host";
+import { AnnotationAppearanceImage, AnnotationDTO, AnnotationDraft, AnnotationPatch, AnnotationRef, AttachmentContent, AttachmentFileSource, BinarySource, CommentThread, InkIntent, PdfActionTree, PdfLinkTarget, PdfRect } from "@embedpdf/engine-core/runtime";
 import { AnnotationFlags, AnnotationProps, AnnotationPropsPatch, ChromeNode, ClickCreate, CreationDraftAnchor, Geom, Id, InkStraightenOptions, Model, PropKey, PropSpec, Rect, RenderItem, SnapSettings, Subtype, TextEndAnchor, TextQuad, Vec, ViewEnv } from "@embedpdf/core-annotation";
 import { PageRotation } from "@embedpdf/core-geometry";
 //#region src/tools.d.ts
@@ -429,6 +430,19 @@ interface LinkNavItem {
    * stays selectable/movable; standalone document links navigate regardless.
    */
   attached: boolean;
+  /** The full payload-carrying `/A` tree, when one exists — the action
+   *  engine's dispatch input. `target` remains its root projection. */
+  activate?: PdfActionTree;
+  /** The annotation ref, carried for ActionSource context. */
+  ref?: AnnotationRef;
+  /** Which `/AA` hover trees this link carries — the nav layer's pump flags
+   *  (tree-less hover must cost zero dispatches). Links are behavior-inert
+   *  to the annotation plane's hover feed while navigable, so THEIR
+   *  cursorEnter/cursorExit can only fire from the LinkLayer anchors. */
+  hoverEvents?: {
+    enter: boolean;
+    exit: boolean;
+  };
 }
 interface Behavior {
   id: string;
@@ -490,8 +504,9 @@ interface TextItem {
  * package root (`@embedpdf/plugin-annotation`).
  *
  * Framework-only plumbing (render projection, pointer gestures, behavior
- * registration) lives on {@link AnnotationHostCapability}, reachable only through
- * the `@embedpdf/plugin-annotation/internal` entry. Both are the SAME runtime
+ * registration) lives on {@link AnnotationHostCapability}, reachable through
+ * `@embedpdf/plugin-annotation/contract/host` (and the framework's `/internal`
+ * entry). Both are the SAME runtime
  * object — two typed lenses on one token — so app code simply can't see the host
  * methods.
  */
@@ -709,6 +724,13 @@ interface AnnotationCapability {
   armStamp(input: StampToolInput): Promise<void>;
   /** Drop the armed stamp payload (a tool change away from 'stamp' does this too). */
   disarmStamp(): void;
+  /**
+   * Place a stamp WITHOUT the pointer: the same validation, fit, page clamp,
+   * `/Name`, and `/Subj` a click after {@link armStamp} produces — the one
+   * placement law, exposed for code. Resolves to the created annotation's
+   * ref; the placement is selected like a click's.
+   */
+  placeStamp(input: StampToolInput, placement: StampPlacement): Promise<AnnotationRef>;
   /**
    * Install the ONE file-picker port every click-then-pick tool resolves
    * through (see {@link FilePickerProvider}) — the stamp `'prompt'` source and
@@ -757,14 +779,18 @@ interface StampToolInput {
   source: BinarySource;
   /** Placed width in PDF points (height follows the intrinsic aspect). Default 150. */
   targetWidth?: number;
+  /** The placed annotation's `/Name` — the stamp identifier (standard or custom). */
+  name?: string;
+  /** The placed annotation's `/Subj`. */
+  subject?: string;
   /**
-   * A browser-paintable render of `source` for the hover ghost (PNG/JPEG).
-   * Required for the ghost when `source` is PDF bytes — the browser cannot
-   * paint those; the caller (e.g. a stamp library) supplies its cached page
-   * render. Raster sources default to the source itself; omit everywhere
-   * else and the tool simply shows no ghost.
+   * The hover ghost's image. Either fixed bytes (PNG/JPEG) or — for vector
+   * sources, which are only ever right at ONE on-screen size — a
+   * {@link StampPreviewProvider} the ghost asks for a render at the device
+   * pixel width it is displayed at. Raster sources default to themselves;
+   * omit and the tool simply shows no ghost.
    */
-  preview?: BinarySource;
+  preview?: BinarySource | StampPreviewProvider;
   /**
    * The source's intrinsic size in PDF points. Raster sources are measured
    * from their own header, but PDF bytes carry no sniffable dimensions —
@@ -782,6 +808,33 @@ interface ArmedStampPreview {
   bytes: Uint8Array;
   mimeType?: string;
 }
+/**
+ * Resolution-aware ghost preview: "give me this stamp at `devicePixelWidth`
+ * pixels wide". The annotation plugin buckets the request (see
+ * {@link previewBucket}) and caches per bucket for the arm's lifetime, so a
+ * zoom gesture never renders per frame and one render serves a zoom range.
+ * A stamp library renders its page lazily through its asset engine; a raster
+ * returns itself (it cannot get sharper than its pixels).
+ */
+type StampPreviewProvider = (devicePixelWidth: number) => Promise<ArmedStampPreview | null>;
+/**
+ * Ghost render buckets: powers of two from 128 px up to `cap`. The same policy
+ * the page renderer uses — one bitmap per size class, never per zoom step.
+ */
+declare function previewBucket(devicePixelWidth: number, cap?: number): number;
+/**
+ * Where a programmatic stamp placement lands — the inputs a click supplies.
+ * The box is fitted and clamped exactly as the click path does it.
+ */
+interface StampPlacement {
+  pageObjectNumber: PageObjectNumber;
+  /** Anchor in page points (content space): the placement is centred here. */
+  at: Vec;
+  /** Placed width in PDF points; default the payload's intrinsic size. */
+  targetWidth?: number;
+  /** Content rotation, degrees clockwise. Default 0. */
+  rotation?: number;
+}
 /**
  * What the {@link FilePickerProvider} is asked for: which tool clicked (id +
  * the kind it creates), the tool's `accept` filter, and the page-space point
@@ -818,8 +871,9 @@ type FilePickerProvider = (req: FilePromptRequest) => Promise<AttachmentFileSour
 /**
  * The HOST (framework) surface: everything the render layer, the interaction hub,
  * and sibling plugins need, on top of the public {@link AnnotationCapability}.
- * Internal — import the token from `@embedpdf/plugin-annotation/internal`, never
- * from application code.
+ * Host-only — sibling plugins import the token from
+ * `@embedpdf/plugin-annotation/contract/host`; framework implementation code may
+ * use `/internal`. Never use either from application code.
  */
 interface AnnotationHostCapability extends AnnotationCapability {
   /** `view` (the page's scale + total display rotation, from its transform)
@@ -1024,8 +1078,13 @@ interface AnnotationHostCapability extends AnnotationCapability {
    *  Vector ghosts also ride {@link pageItems}; only `kind: 'image'` ghosts
    *  need the framework's blit. */
   toolGhost(pon: PageObjectNumber): ToolGhost | null;
-  /** The armed stamp's paintable preview bytes, or null (no ghost to show). */
-  armedStampPreview(): ArmedStampPreview | null;
+  /**
+   * The armed stamp's paintable preview at (roughly) `devicePixelWidth`
+   * pixels wide — bucketed and cached per bucket for the arm's lifetime —
+   * or null when there is no ghost to show. Omit the width for the
+   * smallest bucket.
+   */
+  armedStampPreview(devicePixelWidth?: number): Promise<ArmedStampPreview | null>;
   /** Bumps on arm/disarm — keys the render layer's preview object-URL lifetime. */
   stampArmEpoch(): number;
   /**
@@ -1046,13 +1105,25 @@ interface AnnotationHostCapability extends AnnotationCapability {
    *  gesture and the created annotation's PDF kind. Falls back to the id. */
   toolSubtype(id: string): Subtype;
   registerBehavior(b: Behavior): () => void;
+  /**
+   * The actions plane's session-visibility write (Hide actions, script
+   * `annot.hidden`): resolve annotation OBJECT NUMBERS to loaded model ids
+   * (the `obj:` refKey seam) and merge session-hidden overrides. Returns how
+   * many resolved — unresolved numbers (unloaded pages, nm/index refs) are
+   * the caller's diagnostics. Session state only; never an engine write.
+   */
+  /** The script/Hide DOCUMENT-commit door (full ISO): engine updates +
+   *  model reconciliation, per entry, stop-on-failure. Never enqueues,
+   *  never touches the script host — the D2 sink contract. */
+  commitScriptEffects(entries: AnnotCommitEntry[]): Promise<AnnotCommitResult>;
 }
 /**
  * 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}.
+ * here (the package internals, `/contract/host`, and `/internal` use this view).
+ * The package root re-exports the SAME token narrowed to
+ * {@link AnnotationCapability}.
  */
 declare const AnnotationToken: import("@embedpdf/core").CapabilityToken<AnnotationHostCapability>;
 //#endregion
-export { StampSourceSpec as A, AnnotationToolInput as C, PromptSourceSpec as D, InkAuthoringOptions as E, ToolDefaultsFor as M, buildToolRegistry as N, ResolvedTool as O, AnnotationToolDef as S, GhostPolicy as T, SelectionProps as _, AnnotationHydration as a, ThreadDeleteResult as b, Behavior as c, CommentPermissions as d, CommentsApi as f, SelectionFlags as g, LinkNavItem as h, AnnotationHostCapability as i, ToolAuthoringKind as j, SelectionAuthoring as k, ChromeSettings as l, FilePromptRequest as m, AnnotationCapability as n, AnnotationState as o, FilePickerProvider as p, AnnotationConfig as r, AnnotationToken as s, AnnotationAction as t, ChromeSettingsPatch as u, StampToolInput as v, DEFAULT_TOOLS as w, ToolGhost as x, TextItem as y };
-//# sourceMappingURL=types-DITX_3CG.d.ts.map
+export { PromptSourceSpec as A, ToolGhost as C, DEFAULT_TOOLS as D, AnnotationToolInput as E, ToolDefaultsFor as F, buildToolRegistry as I, SelectionAuthoring as M, StampSourceSpec as N, GhostPolicy as O, ToolAuthoringKind as P, ThreadDeleteResult as S, AnnotationToolDef as T, SelectionProps as _, AnnotationHydration as a, StampToolInput as b, Behavior as c, CommentPermissions as d, CommentsApi as f, SelectionFlags as g, LinkNavItem as h, AnnotationHostCapability as i, ResolvedTool as j, InkAuthoringOptions as k, ChromeSettings as l, FilePromptRequest as m, AnnotationCapability as n, AnnotationState as o, FilePickerProvider as p, AnnotationConfig as r, AnnotationToken as s, AnnotationAction as t, ChromeSettingsPatch as u, StampPlacement as v, previewBucket as w, TextItem as x, StampPreviewProvider as y };
+//# sourceMappingURL=types-BgetZ4BK.d.ts.map