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

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

@@ -1,11 +1,13 @@
 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 { i as isTouchDirect, r as buildToolRegistry, t as ARMED_STAMP_TOOL_ID } from "./tools-DBEYx3-c.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 { 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 { FLAG_KEYS, annotContentsEditable, annotDeletable, annotTransformable, applyStyleToRange, calloutLinePoints, canMove, chrome, clickCreateGeom, cloudyBorderExtent, contentToPdfRect, creationDraftAnchor, cursorAt, defaultsFor, expandGroups, fitStampBox, geomPdfBounds, geomRotation, geomVisualBounds, groupKeyOf, hitTest, initialTextStyle, isSubstrateOnly, linkChildrenOf, linkOf, locateOffset, pageItems, paragraphsFromPlainText, pdfToContentPoint, pdfToContentRect, propsFor, readProp, resolveClickPlacement, rotatedAabb, selectionAnchor, selectionQuad, sharedProps, styleFromProps, textBoxes, textPlateInset, unionRect, update, uprightRotation, viewable } from "@embedpdf/core-annotation";
 import { normalizeQuad, textQuadBounds } from "@embedpdf/core-geometry";
 //#region src/repository/props.ts
 /**
@@ -207,18 +209,387 @@ const ink = {
 	draftExtras: (a) => a.intent === "ink-highlight" ? { intent: a.intent } : {}
 };
 //#endregion
+//#region src/rich-text.ts
+/**
+* Rich text POLICY — what the annotation plugin decides about a free-text
+* annotation's rich document, kept pure so every framework's editor glue
+* behaves identically (the mechanics live in `@embedpdf/web`'s binding, the
+* run algebra in the core):
+*
+*   • the rich document of any annot (the DTO's, or one synthesised from the
+*     plain text + the `/DA` text style for a draft that has no DTO yet)
+*   • a flat props patch → the run delta it means for a text RANGE (font,
+*     size, colour, bold/italic/underline) and the keys left for the body
+*   • what a range reads back for those keys (agree → the value, else mixed)
+*   • faces: a DTO font (standard kebab name / registered key) ↔ the face a
+*     run names (family + weight + italic) ↔ a CSS family list
+*   • the commit rule: a document nothing overrides on a plain annotation
+*     commits as `contents`; anything else as `richText`
+*/
+/** The props keys a text range takes as run deltas. */
+const RANGE_KEYS = [
+	"fontFamily",
+	"fontSize",
+	"fontColor",
+	"bold",
+	"italic",
+	"underline"
+];
+/** The engine's standard-14 vocabulary (the `StandardFont` kebab names). */
+const STANDARD_FACES = {
+	courier: {
+		family: "Courier",
+		weight: 400,
+		italic: false
+	},
+	"courier-bold": {
+		family: "Courier",
+		weight: 700,
+		italic: false
+	},
+	"courier-bold-oblique": {
+		family: "Courier",
+		weight: 700,
+		italic: true
+	},
+	"courier-oblique": {
+		family: "Courier",
+		weight: 400,
+		italic: true
+	},
+	helvetica: {
+		family: "Helvetica",
+		weight: 400,
+		italic: false
+	},
+	"helvetica-bold": {
+		family: "Helvetica",
+		weight: 700,
+		italic: false
+	},
+	"helvetica-bold-oblique": {
+		family: "Helvetica",
+		weight: 700,
+		italic: true
+	},
+	"helvetica-oblique": {
+		family: "Helvetica",
+		weight: 400,
+		italic: true
+	},
+	"times-roman": {
+		family: "Times",
+		weight: 400,
+		italic: false
+	},
+	"times-bold": {
+		family: "Times",
+		weight: 700,
+		italic: false
+	},
+	"times-bold-italic": {
+		family: "Times",
+		weight: 700,
+		italic: true
+	},
+	"times-italic": {
+		family: "Times",
+		weight: 400,
+		italic: true
+	},
+	symbol: {
+		family: "Symbol",
+		weight: 400,
+		italic: false
+	},
+	"zapf-dingbats": {
+		family: "ZapfDingbats",
+		weight: 400,
+		italic: false
+	}
+};
+/** Family names compare without case, spaces, hyphens, underscores and
+*  quotes — the engine's own rule. */
+function familyKey(family) {
+	return family.toLowerCase().replace(/[\s\-_'"]/g, "");
+}
+const STANDARD_FAMILY_KEYS = {
+	helvetica: "Helvetica",
+	arial: "Helvetica",
+	arialmt: "Helvetica",
+	sansserif: "Helvetica",
+	times: "Times",
+	timesroman: "Times",
+	timesnewroman: "Times",
+	timesnewromanpsmt: "Times",
+	serif: "Times",
+	courier: "Courier",
+	couriernew: "Courier",
+	couriernewpsmt: "Courier",
+	monospace: "Courier",
+	symbol: "Symbol",
+	zapfdingbats: "ZapfDingbats",
+	dingbats: "ZapfDingbats"
+};
+/** Web stacks with the standard families' metrics (what the DOM editor and
+*  the vector renderer show for text the engine sets in a standard font). */
+const STANDARD_STACKS = {
+	Helvetica: "Helvetica, Arial, sans-serif",
+	Times: "\"Times New Roman\", Times, serif",
+	Courier: "\"Courier New\", Courier, monospace",
+	Symbol: "serif",
+	ZapfDingbats: "serif"
+};
+/** The face a DTO font names: a standard font's family/weight/italic, a
+*  registered key's identity, else the string itself as a family. */
+function faceForFont(font, fonts) {
+	const standard = STANDARD_FACES[font];
+	if (standard) return { ...standard };
+	const registered = fonts?.().find((f) => f.key === font);
+	if (registered) return {
+		family: registered.familyName,
+		weight: registered.weight,
+		italic: registered.italic
+	};
+	return { family: font };
+}
+/** The DTO font for a face: the registered key whose identity matches (the
+*  closest weight, italic first), else the standard kebab name, else the
+*  family itself. The inverse of {@link faceForFont}. */
+function fontForFace(face, fonts) {
+	const wanted = familyKey(face.family);
+	const weight = face.weight ?? 400;
+	const italic = face.italic ?? false;
+	let best;
+	for (const f of fonts?.() ?? []) {
+		if (familyKey(f.familyName) !== wanted) continue;
+		const score = Math.abs(f.weight - weight) + (f.italic === italic ? 0 : 1e3);
+		if (!best || score < best.score) best = {
+			key: f.key,
+			score
+		};
+	}
+	if (best) return best.key;
+	const standard = STANDARD_FAMILY_KEYS[wanted];
+	if (standard) {
+		const bold = weight >= 600;
+		for (const [name, spec] of Object.entries(STANDARD_FACES)) if (spec.family === standard && spec.weight >= 600 === bold && spec.italic === italic) return name;
+		for (const [name, spec] of Object.entries(STANDARD_FACES)) if (spec.family === standard) return name;
+	}
+	return face.family;
+}
+/** The CSS family list for a face family: a standard family's web stack, a
+*  registered family's `@font-face` name (its key — see `mountWebFont`),
+*  else the family itself with a generic fallback. */
+function cssFontFamilyForFace(family, fonts) {
+	const standard = STANDARD_FAMILY_KEYS[familyKey(family)];
+	if (standard) return STANDARD_STACKS[standard];
+	const wanted = familyKey(family);
+	const registered = fonts?.().find((f) => familyKey(f.familyName) === wanted);
+	if (registered) return `"${registered.key}"`;
+	return `"${family}", sans-serif`;
+}
+/** The CSS family list for a DTO font (a standard kebab name or a key). */
+function cssFontFamilyForFont(font, fonts) {
+	const standard = STANDARD_FACES[font];
+	if (standard) return STANDARD_STACKS[standard.family];
+	return `"${font}", sans-serif`;
+}
+const hex = (css) => css.trim().toUpperCase();
+/** The rich body the `/DA` text style describes (a draft's body before its
+*  DTO exists; also the fallback for a DTO without `richText`). */
+function bodyFromTextStyle(t, fonts) {
+	const face = faceForFont(t.fontFamily, fonts);
+	return {
+		family: face.family,
+		weight: t.bold ? 700 : face.weight ?? 400,
+		italic: t.italic ?? face.italic ?? false,
+		size: t.fontSize,
+		color: hex(t.fontColor),
+		decoration: t.underline ? ["underline"] : [],
+		script: "normal",
+		letterSpacing: 0,
+		horizontalScale: 1,
+		align: t.textAlign,
+		dir: "ltr"
+	};
+}
+/** The annotation's rich document: the DTO's, else one synthesised from
+*  its plain text and text style (a draft the engine has not echoed yet). */
+function richDocOf(a, fonts) {
+	if (a.data?.subtype === "free-text" && a.data.richText) return a.data.richText;
+	return {
+		body: bodyFromTextStyle(a.text ?? {
+			fontFamily: "helvetica",
+			fontSize: 12,
+			fontColor: "#000000",
+			textAlign: "left"
+		}, fonts),
+		paragraphs: paragraphsFromPlainText(a.data?.contents ?? "")
+	};
+}
+/**
+* The write a text edit commits: the rich paragraphs, with paragraph
+* properties equal to the body's stripped (they are inherited, not
+* overrides) and the body omitted — it stays what the props path last
+* wrote. One engine, one path: plain and formatted text alike.
+*/
+function textCommitPatch(a, paragraphs, fonts) {
+	return { richText: { paragraphs: stripBodyDefaults(paragraphs, richDocOf(a, fonts).body) } };
+}
+/**
+* Paragraph alignment/direction equal to the body's are not overrides: the
+* engine echoes them resolved, the editor renders them as inline styles and
+* serialises them back, and the commit rule must see through that (a plain
+* `/Contents` annotation must not grow an `/RC` from typing).
+*/
+function stripBodyDefaults(paragraphs, body) {
+	return paragraphs.map((p) => {
+		if ((p.align === void 0 || p.align !== body.align) && (p.dir === void 0 || p.dir !== body.dir)) return p;
+		const { align, dir, ...rest } = p;
+		return {
+			...rest,
+			...align !== void 0 && align !== body.align ? { align } : {},
+			...dir !== void 0 && dir !== body.dir ? { dir } : {}
+		};
+	});
+}
+/**
+* Split a props patch for an annotation whose editor holds a text RANGE:
+* the run delta the range takes (font → face, size, colour, bold → weight,
+* italic, underline → decoration) and the keys that still go to the body.
+*/
+function runDeltaForProps(patch, fonts) {
+	const delta = {};
+	const rest = {};
+	for (const key of Object.keys(patch)) {
+		const value = patch[key];
+		if (value === void 0) continue;
+		switch (key) {
+			case "fontFamily": {
+				const face = faceForFont(patch.fontFamily, fonts);
+				delta.family = face.family;
+				if (face.weight !== void 0) delta.weight = face.weight;
+				if (face.italic !== void 0) delta.italic = face.italic;
+				break;
+			}
+			case "fontSize":
+				delta.size = patch.fontSize;
+				break;
+			case "fontColor":
+				delta.color = hex(patch.fontColor);
+				break;
+			case "bold":
+				delta.weight = patch.bold ? 700 : 400;
+				break;
+			case "italic":
+				delta.italic = patch.italic;
+				break;
+			case "underline":
+				delta.decoration = patch.underline ? ["underline"] : [];
+				break;
+			default: rest[key] = value;
+		}
+	}
+	return {
+		delta,
+		rest
+	};
+}
+/** The style deltas of every non-empty run a range overlaps. */
+function runsInRange(doc, range) {
+	const start = Math.min(range.start, range.end);
+	const end = Math.max(range.start, range.end);
+	if (end <= start) return [];
+	const from = locateOffset(doc, start);
+	const to = locateOffset(doc, end);
+	const out = [];
+	for (let index = from.paragraph; index <= to.paragraph; index++) {
+		const paragraph = doc.paragraphs[index];
+		const localStart = index === from.paragraph ? from.offset : 0;
+		const localEnd = index === to.paragraph ? to.offset : paragraph.runs.reduce((n, r) => n + r.text.length, 0);
+		let pos = 0;
+		for (const run of paragraph.runs) {
+			const runEnd = pos + run.text.length;
+			if (runEnd > localStart && pos < localEnd && run.text.length > 0) out.push(run.style ?? {});
+			pos = runEnd;
+		}
+	}
+	return out;
+}
+/** The values a range reads back for the range keys — resolved against the
+*  body, one value where every run agrees, `mixed` where they don't. */
+function rangeProps(doc, range, fonts) {
+	const runs = runsInRange(doc, range);
+	const body = doc.body;
+	const resolve = (d) => ({
+		family: d.family ?? body.family,
+		weight: d.weight ?? body.weight,
+		italic: d.italic ?? body.italic,
+		size: d.size ?? body.size,
+		color: d.color ?? body.color,
+		decoration: d.decoration ?? body.decoration
+	});
+	const styles = (runs.length ? runs : [{}]).map(resolve);
+	const values = {};
+	const mixed = [];
+	const read = (key, of) => {
+		const first = of(styles[0]);
+		values[key] = first;
+		if (styles.some((s) => JSON.stringify(of(s)) !== JSON.stringify(first))) mixed.push(key);
+	};
+	read("fontFamily", (s) => fontForFace({
+		family: s.family,
+		weight: body.weight,
+		italic: body.italic
+	}, fonts));
+	read("fontSize", (s) => s.size);
+	read("fontColor", (s) => s.color.toLowerCase());
+	read("bold", (s) => (s.weight ?? 400) >= 600);
+	read("italic", (s) => !!s.italic);
+	read("underline", (s) => (s.decoration ?? []).includes("underline"));
+	return {
+		values,
+		mixed
+	};
+}
+//#endregion
 //#region src/repository/kinds/freeText.ts
 /** Free-text `/DA` fields → content {@link TextStyle}. An absent `fontColor`
 *  falls back to the `/DA` colour — the same rule the CPVT renderer applies. */
 function textFromDTO(dto) {
+	const body = dto.richText?.body;
 	return {
 		fontFamily: dto.fontFamily,
 		fontSize: dto.fontSize,
 		fontColor: colorToCss(dto.fontColor ?? dto.color),
-		textAlign: dto.textAlign
+		textAlign: dto.textAlign,
+		...body && body.weight >= 600 ? { bold: true } : {},
+		...body?.italic ? { italic: true } : {},
+		...body?.decoration.includes("underline") ? { underline: true } : {}
 	};
 }
 /**
+* A formatting toggle is a BODY change (runs are deltas over it), so it
+* lowers as a rich write carrying the current paragraphs — and every toggle
+* lowers the same COMPLETE body (the current one with the three toggles
+* applied: a partial body means engine defaults, which would reset the
+* size, face and colour), so a patch of several merges cleanly.
+*/
+const formattingBody = (a) => {
+	const doc = richDocOf(a);
+	const t = a.text;
+	return { richText: {
+		body: {
+			...doc.body,
+			weight: t?.bold ? 700 : 400,
+			italic: !!t?.italic,
+			decoration: t?.underline ? ["underline"] : []
+		},
+		paragraphs: doc.paragraphs
+	} };
+};
+/**
 * The engine geometry for a callout: the overall `/Rect` (text box ∪ leader ∪
 * arrow), the `/RD` inset that recovers the text box from it, the `/CL` leader
 * (`[tip, knee, conn]` with the connection point derived), and the `/LE`
@@ -302,6 +673,11 @@ const freeText = {
 		if (cf) return { ...cf };
 		return boxEmit(a, crop);
 	},
+	prop: {
+		bold: formattingBody,
+		italic: formattingBody,
+		underline: formattingBody
+	},
 	draftExtras: (a, crop) => ({
 		intent: calloutFields(a, crop) ? "free-text-callout" : "free-text",
 		contents: a.data?.contents ?? ""
@@ -731,18 +1107,6 @@ function createAnnotationHoverFeed(actions, annotOf) {
 * the plugin (not the portable core) because the font→CSS stack mapping and the
 * engine `Color`→CSS seam are web concerns, shared across every web framework.
 */
-/** Map a free-text `/DA` font to a CSS font-family. A standard PDF font → a web
-*  stack with the same metrics; anything else is a registered font key → mount it
-*  as a `@font-face` of that family (see the framework `mountWebFont` helper). */
-const STANDARD_FONT_CSS = {
-	helvetica: "Helvetica, Arial, sans-serif",
-	"helvetica-bold": "Helvetica, Arial, sans-serif",
-	courier: "\"Courier New\", Courier, monospace",
-	"times-roman": "\"Times New Roman\", Times, serif",
-	symbol: "serif",
-	"zapf-dingbats": "serif"
-};
-const cssFontFor = (font) => STANDARD_FONT_CSS[font] ?? `"${font}", sans-serif`;
 /** Project the model's free-text boxes into render-ready {@link TextItem}s — the
 *  core geometry (`textBoxes`) joined with the DTO-derived CSS. Pure; memoized by
 *  model identity at the call site so selectors get a stable reference. */
@@ -751,516 +1115,29 @@ function buildTextItems(m, pon, view) {
 		const a = m.byId[tb.id];
 		const t = a?.text ?? initialTextStyle;
 		const sw = a?.style.strokeWidth ?? 0;
-		const isCallout = a?.geom.t === "text" && !!a.geom.callout;
+		const doc = a ? richDocOf(a) : null;
 		return {
 			id: tb.id,
 			ref: a?.ref ?? null,
 			box: tb.box,
 			contents: a?.data?.contents ?? "",
+			richText: { paragraphs: doc ? stripBodyDefaults(doc.paragraphs, doc.body) : [{ runs: [{ text: "" }] }] },
 			editing: tb.editing,
 			...tb.rot ? { rot: tb.rot } : {},
 			css: {
-				fontFamily: cssFontFor(t.fontFamily),
+				fontFamily: cssFontFamilyForFont(t.fontFamily),
 				fontSize: t.fontSize,
-				lineHeight: t.fontSize,
 				color: t.fontColor,
+				fontWeight: t.bold ? 700 : 400,
+				fontStyle: t.italic ? "italic" : "normal",
+				textDecoration: t.underline ? "underline" : "none",
 				align: t.textAlign,
-				padding: isCallout ? sw + 2 : sw,
-				background: a?.style.interiorColor ?? null
+				padding: textPlateInset(sw)
 			}
 		};
 	});
 }
 //#endregion
-//#region src/tools.ts
-/**
-* 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
-* edits can keep using `AnnotationPropsPatch`.
-*/
-const TOOL_DEFAULT_KEYS = {
-	square: [
-		"color",
-		"interiorColor",
-		"opacity",
-		"strokeWidth",
-		"border"
-	],
-	circle: [
-		"color",
-		"interiorColor",
-		"opacity",
-		"strokeWidth",
-		"border"
-	],
-	line: [
-		"color",
-		"interiorColor",
-		"opacity",
-		"strokeWidth",
-		"border",
-		"lineEndings"
-	],
-	polygon: [
-		"color",
-		"interiorColor",
-		"opacity",
-		"strokeWidth",
-		"border"
-	],
-	polyline: [
-		"color",
-		"interiorColor",
-		"opacity",
-		"strokeWidth",
-		"border",
-		"lineEndings"
-	],
-	ink: [
-		"color",
-		"opacity",
-		"strokeWidth",
-		"blendMode"
-	],
-	"free-text": [
-		"fontFamily",
-		"fontSize",
-		"fontColor",
-		"textAlign",
-		"opacity",
-		"interiorColor",
-		"color",
-		"strokeWidth",
-		"border"
-	],
-	"free-text-callout": [
-		"fontFamily",
-		"fontSize",
-		"fontColor",
-		"textAlign",
-		"opacity",
-		"interiorColor",
-		"color",
-		"strokeWidth",
-		"border",
-		"lineEndings"
-	],
-	highlight: [
-		"color",
-		"opacity",
-		"blendMode"
-	],
-	underline: [
-		"color",
-		"opacity",
-		"blendMode"
-	],
-	strikeout: [
-		"color",
-		"opacity",
-		"blendMode"
-	],
-	squiggly: [
-		"color",
-		"opacity",
-		"blendMode"
-	],
-	caret: ["color", "opacity"],
-	redact: [
-		"color",
-		"interiorColor",
-		"opacity",
-		"fontFamily",
-		"fontSize",
-		"fontColor",
-		"textAlign"
-	],
-	stamp: [],
-	link: ["link"],
-	text: [
-		"icon",
-		"color",
-		"opacity"
-	],
-	"file-attachment": [
-		"icon",
-		"color",
-		"opacity"
-	],
-	"widget-text": [
-		"color",
-		"interiorColor",
-		"strokeWidth",
-		"border",
-		"fontFamily",
-		"fontSize",
-		"fontColor",
-		"textAlign"
-	],
-	"widget-choice": [
-		"color",
-		"interiorColor",
-		"strokeWidth",
-		"border",
-		"fontFamily",
-		"fontSize",
-		"fontColor",
-		"textAlign"
-	],
-	"widget-toggle": [
-		"color",
-		"interiorColor",
-		"strokeWidth",
-		"border"
-	]
-};
-const DRAW_TAGS = ["annotation-draw", "annotation-edit"];
-const MARKUP_TAGS = ["text-select", "annotation-edit"];
-/**
-* Whether arming this ANNOTATION tool is touch consent (`Tool.touchDirect`):
-* drag-CREATE tools — shape/ink draw and text-markup select — take
-* single-finger touch wholesale (finger draws/marks, two fingers navigate:
-* the drawing-app convention). Click-to-PLACE tools (stamp, note) do not: a
-* tap places without any claim, and drags keep scrolling. Derived from the
-* gesture tags, so custom registered tools inherit the right behavior. Only
-* annotation-owned tools run through this — the built-in `pointer` tool also
-* enables `text-select`, but it is registered by the hub, not here.
-*/
-const isTouchDirect = (enables) => enables.has("annotation-draw") || enables.has("text-select");
-/**
-* The built-in tools — a data mirror of v2's registrations (shapes + lines + ink
-* + free text in the draw channel, text markup + caret behind text selection, and
-* the click-to-place stamp). Order is display-neutral; the toolbar owns layout.
-*/
-const DEFAULT_TOOLS = [
-	{
-		id: "square",
-		subtype: "square",
-		cursor: "crosshair",
-		enables: DRAW_TAGS,
-		defaults: { strokeWidth: 6 },
-		clickCreate: {
-			width: 80,
-			height: 60
-		}
-	},
-	{
-		id: "circle",
-		subtype: "circle",
-		cursor: "crosshair",
-		enables: DRAW_TAGS,
-		defaults: { strokeWidth: 6 },
-		clickCreate: {
-			width: 80,
-			height: 60
-		}
-	},
-	{
-		id: "line",
-		subtype: "line",
-		cursor: "crosshair",
-		enables: DRAW_TAGS,
-		defaults: { strokeWidth: 6 },
-		clickCreate: { length: 80 }
-	},
-	{
-		id: "polygon",
-		subtype: "polygon",
-		cursor: "crosshair",
-		enables: DRAW_TAGS,
-		defaults: { strokeWidth: 6 }
-	},
-	{
-		id: "polyline",
-		subtype: "polyline",
-		cursor: "crosshair",
-		enables: DRAW_TAGS,
-		defaults: { strokeWidth: 6 }
-	},
-	{
-		id: "ink",
-		subtype: "ink",
-		cursor: "crosshair",
-		enables: DRAW_TAGS,
-		defaults: {
-			color: "#ef4444",
-			strokeWidth: 6,
-			blendMode: "normal"
-		},
-		ink: { groupStrokesMs: 800 }
-	},
-	{
-		id: "ink-highlight",
-		extends: "ink",
-		intent: "ink-highlight",
-		defaults: {
-			color: "#ffcd45",
-			strokeWidth: 14,
-			blendMode: "multiply"
-		},
-		ink: { straighten: {
-			deviationThreshold: .15,
-			axisSnapDegrees: 15
-		} }
-	},
-	{
-		id: "free-text",
-		subtype: "free-text",
-		cursor: "crosshair",
-		enables: DRAW_TAGS,
-		defaults: { fontColor: "#ef4444" },
-		upright: true,
-		clickCreate: {
-			width: 180,
-			height: 40,
-			anchor: "top-left"
-		}
-	},
-	{
-		id: "free-text-callout",
-		subtype: "free-text-callout",
-		propsKind: "free-text",
-		cursor: "crosshair",
-		enables: DRAW_TAGS,
-		defaults: {
-			strokeWidth: 6,
-			lineEndings: { end: "open-arrow" }
-		},
-		upright: true
-	},
-	{
-		id: "highlight",
-		subtype: "highlight",
-		cursor: "default",
-		enables: MARKUP_TAGS,
-		defaults: {
-			color: "#ffe16a",
-			blendMode: "multiply"
-		},
-		selection: { kind: "markup" }
-	},
-	{
-		id: "redact",
-		subtype: "redact",
-		cursor: "crosshair",
-		enables: [
-			"text-select",
-			"annotation-draw",
-			"annotation-edit"
-		],
-		defaults: {
-			color: "#e44234",
-			interiorColor: "#000000",
-			fontColor: "#ffffff",
-			opacity: 1
-		},
-		selection: { kind: "markup" }
-	},
-	{
-		id: "underline",
-		subtype: "underline",
-		cursor: "default",
-		enables: MARKUP_TAGS,
-		defaults: { color: "#ef4444" },
-		selection: { kind: "markup" }
-	},
-	{
-		id: "strikeout",
-		subtype: "strikeout",
-		cursor: "default",
-		enables: MARKUP_TAGS,
-		defaults: { color: "#ef4444" },
-		selection: { kind: "markup" }
-	},
-	{
-		id: "squiggly",
-		subtype: "squiggly",
-		cursor: "default",
-		enables: MARKUP_TAGS,
-		defaults: { color: "#ef4444" },
-		selection: { kind: "markup" }
-	},
-	{
-		id: "insert-text",
-		subtype: "caret",
-		propsKind: "caret",
-		preset: "caret",
-		cursor: "default",
-		enables: MARKUP_TAGS,
-		defaults: { color: "#ef4444" },
-		selection: {
-			kind: "text-edit",
-			operation: "insert"
-		}
-	},
-	{
-		id: "replace-text",
-		subtype: "strikeout",
-		propsKind: "strikeout",
-		cursor: "default",
-		enables: MARKUP_TAGS,
-		defaults: { color: "#ef4444" },
-		selection: {
-			kind: "text-edit",
-			operation: "replace"
-		}
-	},
-	{
-		id: "stamp",
-		subtype: "stamp",
-		cursor: "copy",
-		enables: ["annotation-place", "annotation-edit"],
-		source: {
-			kind: "prompt",
-			accept: "image/png,image/jpeg,application/pdf"
-		},
-		upright: true,
-		ghost: { mode: "footprint" }
-	},
-	{
-		id: "link",
-		subtype: "link",
-		cursor: "crosshair",
-		enables: DRAW_TAGS
-	},
-	{
-		id: "note",
-		subtype: "text",
-		cursor: "crosshair",
-		enables: ["annotation-place", "annotation-edit"],
-		defaults: {
-			icon: "comment",
-			color: "#facc15"
-		},
-		flags: {
-			noZoom: true,
-			noRotate: true
-		},
-		upright: true,
-		ghost: { mode: "footprint" }
-	},
-	{
-		id: "attachment",
-		subtype: "file-attachment",
-		cursor: "copy",
-		enables: ["annotation-place", "annotation-edit"],
-		source: { kind: "prompt" },
-		defaults: {
-			icon: "paperclip",
-			color: "#facc15"
-		},
-		flags: {
-			noZoom: true,
-			noRotate: true
-		},
-		upright: true,
-		ghost: { mode: "footprint" }
-	}
-];
-/** Merge two default patches, `b` over `a`, with line endings merged per side. */
-function mergeDefaults(a, b) {
-	if (!a) return b;
-	if (!b) return a;
-	const merged = {
-		...a,
-		...b
-	};
-	if (a.lineEndings || b.lineEndings) merged.lineEndings = {
-		...a.lineEndings,
-		...b.lineEndings
-	};
-	return merged;
-}
-/** Overlay a same-id override onto a base definition (configure a built-in). */
-function mergeDef(base, over) {
-	return {
-		...base,
-		...over,
-		enables: over.enables ?? base.enables,
-		meta: base.meta || over.meta ? {
-			...base.meta,
-			...over.meta
-		} : void 0,
-		defaults: mergeDefaults(base.defaults, over.defaults),
-		flags: base.flags || over.flags ? {
-			...base.flags,
-			...over.flags
-		} : void 0,
-		ink: base.ink || over.ink ? {
-			...base.ink,
-			...over.ink
-		} : void 0
-	};
-}
-function validateDefaults(tool) {
-	if (!tool.defaults) return;
-	const allowed = TOOL_DEFAULT_KEYS[tool.subtype];
-	if (!allowed) return;
-	const keys = new Set(allowed);
-	for (const key of Object.keys(tool.defaults)) if (!keys.has(key)) throw new Error(`[annotation] tool '${tool.id}' does not support default '${key}' for '${tool.subtype}'`);
-}
-/**
-* Resolve {@link DEFAULT_TOOLS} + embedder overrides into the ready-to-use table.
-* A same-id override merges over the built-in; a new id adds a tool; `extends`
-* inherits from an already-defined tool. Keyed by id, so lookups are O(1).
-*/
-function buildToolRegistry(overrides = []) {
-	const defs = /* @__PURE__ */ new Map();
-	for (const d of DEFAULT_TOOLS) defs.set(d.id, d);
-	for (const o of overrides) {
-		const prev = defs.get(o.id);
-		defs.set(o.id, prev ? mergeDef(prev, o) : o);
-	}
-	const out = /* @__PURE__ */ new Map();
-	const resolving = /* @__PURE__ */ new Set();
-	const resolve = (id) => {
-		const cached = out.get(id);
-		if (cached) return cached;
-		const def = defs.get(id);
-		if (!def) throw new Error(`[annotation] tool '${id}' extends an unknown tool`);
-		let base;
-		if (def.extends && def.extends !== id && !resolving.has(def.extends)) {
-			resolving.add(id);
-			base = resolve(def.extends);
-			resolving.delete(id);
-		}
-		const subtype = def.subtype ?? base?.subtype ?? def.id;
-		const resolved = {
-			id: def.id,
-			subtype,
-			preset: def.preset ?? def.id,
-			propsKind: def.propsKind ?? base?.propsKind ?? subtype,
-			cursor: def.cursor ?? base?.cursor ?? "crosshair",
-			enables: new Set(def.enables ?? (base ? [...base.enables] : [])),
-			defaults: mergeDefaults(base?.defaults, def.defaults),
-			flags: base?.flags || def.flags ? {
-				...base?.flags,
-				...def.flags
-			} : void 0,
-			source: def.source ?? base?.source,
-			selection: def.selection ?? base?.selection,
-			intent: def.intent ?? base?.intent,
-			ink: base?.ink || def.ink ? {
-				...base?.ink,
-				...def.ink
-			} : void 0,
-			upright: def.upright ?? base?.upright ?? false,
-			clickCreate: def.clickCreate ?? base?.clickCreate ?? false,
-			ghost: def.ghost ?? base?.ghost ?? false,
-			meta: base?.meta || def.meta ? {
-				...base?.meta,
-				...def.meta
-			} : void 0
-		};
-		validateDefaults(resolved);
-		out.set(id, resolved);
-		return resolved;
-	};
-	for (const id of defs.keys()) resolve(id);
-	return out;
-}
-//#endregion
 //#region src/placement.ts
 /**
 * Per-kind CODE for the click-to-place ICON kinds (note / file attachment)
@@ -1327,8 +1204,11 @@ const TEXT_COMMIT_DEBOUNCE_MS = 250;
 */
 function createAnnotationCapability(ctx, config = {}) {
 	const behaviors = [];
-	/** Per-annotation debounce timer for the engine `contents` write while typing. */
+	/** Per-annotation debounce timer for the engine text write while typing. */
 	const textTimers = /* @__PURE__ */ new Map();
+	/** The registered fonts, for face ↔ key mapping (the local engine's list;
+	*  the cloud engine registers none). */
+	const fonts = () => ctx.engine?.fonts?.list() ?? [];
 	const configTools = config.tools ?? [];
 	const registry = buildToolRegistry(configTools);
 	/** The installed file-picker port (a DOM file dialog, wired by the framework
@@ -1452,10 +1332,18 @@ function createAnnotationCapability(ctx, config = {}) {
 		};
 		return v;
 	};
+	/** The editor's text RANGE inside the annotation being edited, or null
+	*  (no editor selection, a bare caret, or a selection left behind by a
+	*  previous edit). The one condition that routes the range keys to runs. */
+	const activeTextRange = (m) => {
+		const ts = ctx.getState().textSelection;
+		return ts && m.editing === ts.id && ts.end > ts.start && m.byId[ts.id] ? ts : null;
+	};
 	let selPropsCache = null;
 	const memoSelectionProps = () => {
 		const m = model();
-		if (selPropsCache && selPropsCache.model === m) return selPropsCache.v;
+		const range = activeTextRange(m);
+		if (selPropsCache && selPropsCache.model === m && selPropsCache.range === range) return selPropsCache.v;
 		const members = m.selected.map((id) => m.byId[id]).filter((a) => !!a);
 		const specs = sharedProps(members.map((a) => a.subtype));
 		const values = {};
@@ -1467,6 +1355,16 @@ function createAnnotationCapability(ctx, config = {}) {
 			const firstJson = JSON.stringify(first);
 			if (members.some((a) => JSON.stringify(valueOf(a, spec.key)) !== firstJson)) mixed.push(spec.key);
 		}
+		if (range && members.length === 1 && members[0].id === range.id) {
+			const rp = rangeProps(richDocOf(members[0], fonts), range, fonts);
+			for (const spec of specs) {
+				if (!RANGE_KEYS.includes(spec.key)) continue;
+				values[spec.key] = rp.values[spec.key];
+				const i = mixed.indexOf(spec.key);
+				if (i >= 0) mixed.splice(i, 1);
+				if (rp.mixed.includes(spec.key)) mixed.push(spec.key);
+			}
+		}
 		const v = {
 			specs,
 			values,
@@ -1474,6 +1372,7 @@ function createAnnotationCapability(ctx, config = {}) {
 		};
 		selPropsCache = {
 			model: m,
+			range,
 			v
 		};
 		return v;
@@ -1565,6 +1464,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
@@ -1593,23 +1500,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;
@@ -1736,28 +1641,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) => {
@@ -1768,10 +1694,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`
@@ -1782,7 +1711,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
@@ -1903,6 +1832,34 @@ function createAnnotationCapability(ctx, config = {}) {
 		const res = await doc.page(pon).annotations.update(ref, patch);
 		syncDTO(res.updated, "vector");
 	};
+	const commitText = (ref) => {
+		const key = refKey(ref);
+		clearTimeout(textTimers.get(key));
+		textTimers.delete(key);
+		const a = model().byId[key];
+		const pon = ponForRef(ref);
+		if (!a || pon == null) return;
+		const patch = textCommitPatch(a, richDocOf(a, fonts).paragraphs, fonts);
+		ctx.doc?.page(pon).annotations.update(ref, {
+			subtype: "free-text",
+			...patch
+		}).then(() => {}, () => {});
+	};
+	const scheduleTextCommit = (ref) => {
+		const key = refKey(ref);
+		clearTimeout(textTimers.get(key));
+		textTimers.set(key, setTimeout(() => commitText(ref), TEXT_COMMIT_DEBOUNCE_MS));
+	};
+	const flushTextCommits = () => {
+		for (const key of [...textTimers.keys()]) {
+			const a = model().byId[key];
+			if (a?.ref) commitText(a.ref);
+			else {
+				clearTimeout(textTimers.get(key));
+				textTimers.delete(key);
+			}
+		}
+	};
 	function apply(msg) {
 		const [next, effects] = update(model(), msg);
 		ctx.dispatch({
@@ -2519,6 +2476,36 @@ function createAnnotationCapability(ctx, config = {}) {
 		if (patch.flags) out.flags = patch.flags;
 		return out;
 	};
+	const updateSelection = (patch) => {
+		const m = model();
+		const range = activeTextRange(m);
+		if (range) {
+			const a = m.byId[range.id];
+			const { delta, rest } = runDeltaForProps(patch, fonts);
+			if (Object.keys(delta).length) {
+				const next = applyStyleToRange({ paragraphs: richDocOf(a, fonts).paragraphs }, range, delta);
+				apply({
+					t: "setRichText",
+					id: range.id,
+					doc: next
+				});
+				if (a.ref) scheduleTextCommit(a.ref);
+			}
+			if (Object.keys(rest).length) {
+				flushTextCommits();
+				apply({
+					t: "setProps",
+					patch: rest
+				});
+			}
+			return;
+		}
+		if (m.editing) flushTextCommits();
+		apply({
+			t: "setProps",
+			patch
+		});
+	};
 	return {
 		create: async (pon, draft) => {
 			const doc = ctx.doc;
@@ -2532,6 +2519,7 @@ function createAnnotationCapability(ctx, config = {}) {
 			return res.created.ref;
 		},
 		armStamp,
+		placeStamp,
 		disarmStamp,
 		placeArmedStamp,
 		requestStampAt,
@@ -2545,7 +2533,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;
@@ -2583,10 +2584,11 @@ function createAnnotationCapability(ctx, config = {}) {
 			};
 		},
 		update: (ref, patch) => updateOne(ref, patch),
-		updateSelection: (patch) => apply({
-			t: "setProps",
-			patch
-		}),
+		updateSelection,
+		toggleTextFormat: (format) => {
+			const current = memoSelectionProps().values[format];
+			updateSelection({ [format]: !current });
+		},
 		updateSelectionFlags: (patch) => apply({
 			t: "setFlags",
 			patch
@@ -2925,30 +2927,37 @@ function createAnnotationCapability(ctx, config = {}) {
 				id: refKey(ref),
 				text
 			});
-			const key = refKey(ref);
-			clearTimeout(textTimers.get(key));
-			textTimers.set(key, setTimeout(() => {
-				textTimers.delete(key);
-				const pon = ponForRef(ref);
-				if (pon != null) ctx.doc?.page(pon).annotations.update(ref, {
-					subtype: "free-text",
-					contents: text
-				}).then(() => {}, () => {});
-			}, TEXT_COMMIT_DEBOUNCE_MS));
+			scheduleTextCommit(ref);
 		},
+		setRichText: (ref, doc) => {
+			apply({
+				t: "setRichText",
+				id: refKey(ref),
+				doc: { paragraphs: doc.paragraphs }
+			});
+			scheduleTextCommit(ref);
+		},
+		setTextSelection: (ref, range) => {
+			const id = refKey(ref);
+			const prev = ctx.getState().textSelection;
+			const next = range ? {
+				id,
+				start: range.start,
+				end: range.end
+			} : null;
+			if (prev === null === (next === null) && (!prev || !next || prev.id === next.id && prev.start === next.start && prev.end === next.end)) return;
+			ctx.dispatch({
+				type: "SET_TEXT_SELECTION",
+				selection: next
+			});
+		},
+		cssFontFamily: (family) => cssFontFamilyForFace(family, fonts),
 		endTextEdit: () => {
-			for (const t of textTimers.values()) clearTimeout(t);
-			const id = model().editing;
-			const a = id ? model().byId[id] : null;
-			if (a?.ref) {
-				const pon = ponForRef(a.ref);
-				const text = a.data?.contents ?? "";
-				if (pon != null) ctx.doc?.page(pon).annotations.update(a.ref, {
-					subtype: "free-text",
-					contents: text
-				}).then(() => {}, () => {});
-			}
-			textTimers.clear();
+			flushTextCommits();
+			if (ctx.getState().textSelection) ctx.dispatch({
+				type: "SET_TEXT_SELECTION",
+				selection: null
+			});
 			apply({ t: "endTextEdit" });
 		},
 		commitScriptEffects: async (entries) => {
@@ -3027,6 +3036,6 @@ function createAnnotationCapability(ctx, config = {}) {
 	};
 }
 //#endregion
-export { fromDTO as a, isTouchDirect as i, DEFAULT_TOOLS as n, toCreateDraft as o, buildToolRegistry as r, toPatch as s, createAnnotationCapability as t };
+export { toPatch as i, fromDTO as n, toCreateDraft as r, createAnnotationCapability as t };
 
-//# sourceMappingURL=capability-DBsr2D-L.js.map
+//# sourceMappingURL=capability-B_dkoB1K.js.map