@embedpdf/core-acrojs 3.0.0-next.10 → 3.0.0-next.11

package/dist/index.js

@@ -7,7 +7,7 @@ function javaScriptSourcesFromActionTree(tree) {
 	if (tree.incomplete) throw new Error("Refusing to execute an incomplete PDF action tree");
 	const sources = [];
 	const visit = (node) => {
-		if (node.type === "javascript" && node.script !== void 0) sources.push(node.script);
+		if (node.type === "javascript") sources.push(node.script);
 		for (const child of node.next) visit(child);
 	};
 	if (tree.root) visit(tree.root);
@@ -18,6 +18,324 @@ function javaScriptProgramFromActionTree(tree) {
 	return javaScriptSourcesFromActionTree(tree).join("\n;\n");
 }
 //#endregion
+//#region src/color.ts
+/**
+* Host-side Acrobat color-array conversions — the commit sinks and world
+* builders cross the Acrobat-array ↔ renderer-color boundary through these.
+* The PRELUDE inlines its own identical formulas (it must stay
+* self-contained); `prelude.test.ts` pins the two implementations together.
+*
+* Conversion vectors (the documented Acrobat semantics):
+*   G → RGB: replicate the gray component.
+*   CMYK → RGB: component = 1 − min(1, channel + k).
+*   RGB → G: luminosity 0.3r + 0.59g + 0.11b.
+*   RGB → CMYK: k = 1 − max(r,g,b); channels = 1 − component − k.
+*   T (transparent) converts to itself only.
+*/
+function scriptColorToRgb(color) {
+	switch (color[0]) {
+		case "T": return null;
+		case "G": return {
+			r: color[1],
+			g: color[1],
+			b: color[1]
+		};
+		case "RGB": return {
+			r: color[1],
+			g: color[2],
+			b: color[3]
+		};
+		case "CMYK": {
+			const [, c, m, y, k] = color;
+			return {
+				r: 1 - Math.min(1, c + k),
+				g: 1 - Math.min(1, m + k),
+				b: 1 - Math.min(1, y + k)
+			};
+		}
+	}
+}
+const clamp01 = (value) => Math.min(1, Math.max(0, value));
+const hex = (value) => Math.round(clamp01(value) * 255).toString(16).padStart(2, "0");
+/** Acrobat array → CSS hex, or null for transparent. */
+function scriptColorToCss(color) {
+	const rgb = scriptColorToRgb(color);
+	return rgb === null ? null : `#${hex(rgb.r)}${hex(rgb.g)}${hex(rgb.b)}`;
+}
+/** CSS hex (#rgb/#rrggbb) → Acrobat RGB array; null/undefined → transparent. */
+function cssToScriptColor(css) {
+	if (!css) return ["T"];
+	const raw = css.trim().replace(/^#/, "");
+	const long = raw.length === 3 ? raw.split("").map((ch) => ch + ch).join("") : raw;
+	if (!/^[0-9a-fA-F]{6}$/.test(long)) return ["T"];
+	const channel = (offset) => parseInt(long.slice(offset, offset + 2), 16) / 255;
+	return [
+		"RGB",
+		channel(0),
+		channel(2),
+		channel(4)
+	];
+}
+/** Structural validation for values scripts assign. */
+function isScriptColorArray(value) {
+	if (!Array.isArray(value) || value.length === 0) return false;
+	const [space, ...parts] = value;
+	const expected = {
+		T: 0,
+		G: 1,
+		RGB: 3,
+		CMYK: 4
+	}[String(space)];
+	return expected !== void 0 && parts.length === expected && parts.every((part) => typeof part === "number" && Number.isFinite(part));
+}
+//#endregion
+//#region src/types.ts
+/**
+* The writable-property validity matrix, keyed by engine subtype — the ONE
+* exported table (the prelude inlines an identical copy; a parity test pins
+* them together, and plugin-annotation drift-guards this against the kind
+* registry's PropSpecs). Flags + contents are writable everywhere
+* script-addressable; appearance keys vary by kind.
+*/
+const ANNOT_WRITABLE_KEYS = Object.freeze({
+	square: [
+		"strokeColor",
+		"fillColor",
+		"opacity",
+		"width",
+		"borderStyle",
+		"dash",
+		"rect"
+	],
+	circle: [
+		"strokeColor",
+		"fillColor",
+		"opacity",
+		"width",
+		"borderStyle",
+		"dash",
+		"rect"
+	],
+	polygon: [
+		"strokeColor",
+		"fillColor",
+		"opacity",
+		"width",
+		"borderStyle",
+		"dash",
+		"rect"
+	],
+	polyline: [
+		"strokeColor",
+		"fillColor",
+		"opacity",
+		"width",
+		"borderStyle",
+		"dash",
+		"rect"
+	],
+	line: [
+		"strokeColor",
+		"fillColor",
+		"opacity",
+		"width",
+		"borderStyle",
+		"dash",
+		"rect"
+	],
+	ink: [
+		"strokeColor",
+		"opacity",
+		"width",
+		"rect"
+	],
+	"free-text": [
+		"strokeColor",
+		"fillColor",
+		"opacity",
+		"rect"
+	],
+	highlight: ["strokeColor", "opacity"],
+	underline: ["strokeColor", "opacity"],
+	squiggly: ["strokeColor", "opacity"],
+	strikeout: ["strokeColor", "opacity"],
+	caret: ["strokeColor", "opacity"],
+	text: [
+		"strokeColor",
+		"opacity",
+		"rect"
+	],
+	stamp: ["rect"],
+	"file-attachment": ["strokeColor", "opacity"]
+});
+const DEFAULT_SCRIPT_BUDGET = Object.freeze({
+	maxExecutionMs: 50,
+	maxMemoryBytes: 16 * 1024 * 1024,
+	maxStackBytes: 512 * 1024,
+	maxEffects: 256,
+	maxOutputBytes: 1024 * 1024
+});
+const DEFAULT_SCRIPT_SECURITY_POLICY = Object.freeze({
+	enabled: false,
+	executionOwner: "originating-client-only",
+	nameTreeBoot: "lazy-first-transaction",
+	submitForm: "sink-chain",
+	openAction: "execute-lifecycle",
+	pageActions: "execute-lifecycle",
+	catalogLifecycleActions: "execute-on-verb",
+	annotationActions: "execute-full-matrix"
+});
+/** The shipped dispatch matrix; extracted actions outside it remain data
+*  only. (Historical note: v1 froze everything beyond K/V/C/F as
+*  preserve-only; phases 1–4 executed the rest.) */
+const SCRIPT_EVENT_MATRIX = Object.freeze({
+	nameTree: "lazy-first-originating-field-transaction",
+	field: Object.freeze({
+		keystroke: "execute-on-commit",
+		validate: "execute",
+		calculate: "execute-in-calculation-order",
+		format: "execute-after-value-calculation"
+	}),
+	openAction: "execute-lifecycle",
+	page: "execute-lifecycle",
+	catalogLifecycle: "execute-on-verb",
+	annotation: Object.freeze({
+		widgetActivate: "execute-on-originating-client",
+		other: "execute-full-matrix"
+	}),
+	submitForm: "sink-chain"
+});
+//#endregion
+//#region src/host.ts
+/** FNV-1a over `documentId:sequence` — the deterministic default random seed
+*  (ported verbatim from the form controller; exported for callers building
+*  `ScriptHostOptions.environment`). */
+function seedFrom(documentId, sequence) {
+	let hash = 2166136261;
+	for (const char of `${documentId}:${sequence}`) {
+		hash ^= char.charCodeAt(0);
+		hash = Math.imul(hash, 16777619);
+	}
+	return hash >>> 0;
+}
+/** Engine JWT/session identity composed under embedder overrides — the
+*  standard `ScriptHostOptions.identity` builder. */
+function resolveScriptIdentity(doc, overrides) {
+	const claims = doc.security.identity;
+	const supplied = typeof overrides === "function" ? overrides() : overrides ?? {};
+	return {
+		name: supplied.name ?? claims?.display_name ?? claims?.user_id ?? "",
+		loginName: supplied.loginName ?? claims?.user_id ?? "",
+		corporation: supplied.corporation ?? claims?.group_id ?? "",
+		email: supplied.email ?? ""
+	};
+}
+function createScriptHost(options) {
+	const budget = options.budget ?? DEFAULT_SCRIPT_BUDGET;
+	let tail = Promise.resolve();
+	const enqueue = (operation) => {
+		const result = tail.then(operation, operation);
+		tail = result.then(() => void 0, () => void 0);
+		return result;
+	};
+	let sandboxPromise = null;
+	let booted = false;
+	let pendingBoot = null;
+	let bootSourcesCache = null;
+	let sequence = 0;
+	let disposed = false;
+	const ensureSandbox = () => {
+		sandboxPromise ?? (sandboxPromise = options.sandboxFactory());
+		return sandboxPromise;
+	};
+	const inputFor = (world) => ({
+		document: {
+			...options.document(),
+			...world.pageNumber !== void 0 ? { pageNumber: world.pageNumber } : {}
+		},
+		identity: options.identity(),
+		environment: options.environment(sequence++),
+		fields: world.fields,
+		...world.annots ? { annots: world.annots } : {},
+		...world.annotPages ? { annotPages: world.annotPages } : {},
+		...world.annotsCoverDocument !== void 0 ? { annotsCoverDocument: world.annotsCoverDocument } : {},
+		event: world.event
+	});
+	/** A resource fault poisons the realm: rebuild + re-boot lazily NEXT time. */
+	const noteFault = (sandbox) => {
+		if (!sandbox.disposed) return;
+		sandboxPromise = null;
+		booted = false;
+		pendingBoot = null;
+	};
+	const bootNow = async (world, runBudget) => {
+		if (booted) return null;
+		booted = true;
+		const sandbox = await ensureSandbox();
+		bootSourcesCache ?? (bootSourcesCache = options.bootSources());
+		let sources = [];
+		try {
+			sources = await bootSourcesCache;
+		} catch (error) {
+			bootSourcesCache = null;
+			return {
+				event: {
+					rc: true,
+					value: null,
+					change: "",
+					selStart: 0,
+					selEnd: 0
+				},
+				formEffects: [],
+				annotEffects: [],
+				uiEffects: [],
+				diagnostics: [{
+					code: "script-error",
+					message: `Document boot script failed (continuing without it): ${error instanceof Error ? error.message : String(error)}`
+				}]
+			};
+		}
+		if (sources.length === 0) return null;
+		const output = sandbox.boot(sources, inputFor({
+			...world,
+			event: { kind: "name-tree-boot" }
+		}), runBudget ?? budget);
+		noteFault(sandbox);
+		return output;
+	};
+	const runNow = async (program, world, runBudget) => {
+		if (!booted) pendingBoot = await bootNow(world, runBudget);
+		const sandbox = await ensureSandbox();
+		const output = sandbox.run(program, inputFor(world), runBudget ?? budget);
+		noteFault(sandbox);
+		return output;
+	};
+	return {
+		transaction(body) {
+			if (disposed) return Promise.reject(/* @__PURE__ */ new Error("script host is disposed"));
+			return enqueue(() => body({
+				boot: async (world, runBudget) => {
+					if (pendingBoot) {
+						const output = pendingBoot;
+						pendingBoot = null;
+						return output;
+					}
+					return bootNow(world, runBudget);
+				},
+				run: (program, world, runBudget) => runNow(program, world, runBudget)
+			}));
+		},
+		dispose() {
+			disposed = true;
+			const dying = sandboxPromise;
+			sandboxPromise = null;
+			booted = false;
+			pendingBoot = null;
+			dying?.then((sandbox) => sandbox.dispose()).catch(() => void 0);
+		}
+	};
+}
+//#endregion
 //#region src/input.ts
 function valueFromEntry(entry) {
 	switch (entry.kind) {
@@ -145,6 +463,242 @@ function installAcroJs(g) {
 		return wrapper;
 	};
 	const getField = (name) => state?.fieldsByName.get(String(name))?.wrapper ?? null;
+	const ANNOT_WRITABLE = {
+		square: [
+			"strokeColor",
+			"fillColor",
+			"opacity",
+			"width",
+			"borderStyle",
+			"dash",
+			"rect"
+		],
+		circle: [
+			"strokeColor",
+			"fillColor",
+			"opacity",
+			"width",
+			"borderStyle",
+			"dash",
+			"rect"
+		],
+		polygon: [
+			"strokeColor",
+			"fillColor",
+			"opacity",
+			"width",
+			"borderStyle",
+			"dash",
+			"rect"
+		],
+		polyline: [
+			"strokeColor",
+			"fillColor",
+			"opacity",
+			"width",
+			"borderStyle",
+			"dash",
+			"rect"
+		],
+		line: [
+			"strokeColor",
+			"fillColor",
+			"opacity",
+			"width",
+			"borderStyle",
+			"dash",
+			"rect"
+		],
+		ink: [
+			"strokeColor",
+			"opacity",
+			"width",
+			"rect"
+		],
+		"free-text": [
+			"strokeColor",
+			"fillColor",
+			"opacity",
+			"rect"
+		],
+		highlight: ["strokeColor", "opacity"],
+		underline: ["strokeColor", "opacity"],
+		squiggly: ["strokeColor", "opacity"],
+		strikeout: ["strokeColor", "opacity"],
+		caret: ["strokeColor", "opacity"],
+		text: [
+			"strokeColor",
+			"opacity",
+			"rect"
+		],
+		stamp: ["rect"],
+		"file-attachment": ["strokeColor", "opacity"]
+	};
+	const ANNOT_FLAG_KEYS = [
+		"hidden",
+		"print",
+		"readOnly",
+		"locked",
+		"noView",
+		"toggleNoView"
+	];
+	const ACROBAT_TYPE = {
+		square: "Square",
+		circle: "Circle",
+		line: "Line",
+		polygon: "Polygon",
+		polyline: "PolyLine",
+		ink: "Ink",
+		"free-text": "FreeText",
+		highlight: "Highlight",
+		underline: "Underline",
+		squiggly: "Squiggly",
+		strikeout: "StrikeOut",
+		text: "Text",
+		stamp: "Stamp",
+		caret: "Caret",
+		"file-attachment": "FileAttachment"
+	};
+	const isColorArray = (value) => {
+		if (!Array.isArray(value) || value.length === 0) return false;
+		const expected = {
+			T: 0,
+			G: 1,
+			RGB: 3,
+			CMYK: 4
+		}[String(value[0])];
+		return expected !== void 0 && value.length === expected + 1 && value.slice(1).every((part) => typeof part === "number" && isFinite(Number(part)));
+	};
+	const colorToRgbTriple = (value) => {
+		const color = value;
+		const space = String(color[0]);
+		if (space === "T") return null;
+		if (space === "G") return [
+			Number(color[1]),
+			Number(color[1]),
+			Number(color[1])
+		];
+		if (space === "RGB") return [
+			Number(color[1]),
+			Number(color[2]),
+			Number(color[3])
+		];
+		const c = Number(color[1]);
+		const m = Number(color[2]);
+		const y = Number(color[3]);
+		const k = Number(color[4]);
+		return [
+			1 - Math.min(1, c + k),
+			1 - Math.min(1, m + k),
+			1 - Math.min(1, y + k)
+		];
+	};
+	const sameAnnotValue = (a, b) => {
+		if (Array.isArray(a) && Array.isArray(b)) return a.length === b.length && a.every((item, index) => item === b[index]);
+		return a === b;
+	};
+	const cloneAnnotValue = (value) => Array.isArray(value) ? [...value] : value;
+	const makeAnnot = (record) => {
+		const input = record.input;
+		const subtype = String(input.subtype);
+		const writable = ANNOT_WRITABLE[subtype] ?? [];
+		const wrapper = {};
+		const stage = (key, value, validate) => {
+			if (key !== "contents" && ANNOT_FLAG_KEYS.indexOf(key) < 0 && writable.indexOf(key) < 0) {
+				diagnostic("unsupported-api", `Annot.${key} is not writable on subtype '${subtype}' (write ignored)`);
+				return;
+			}
+			if (input.opaqueBody && ANNOT_FLAG_KEYS.indexOf(key) < 0 && key !== "contents") {
+				diagnostic("unsupported-api", `Annot.${key}: '${subtype}' has an opaque appearance (write ignored)`);
+				return;
+			}
+			if (!validate(value)) {
+				diagnostic("invalid-field-value", `Annot.${key}: invalid value (write ignored)`);
+				return;
+			}
+			record.current[key] = cloneAnnotValue(value);
+		};
+		const prop = (key, validate) => ({
+			enumerable: true,
+			get: () => cloneAnnotValue(record.current[key]),
+			set: (value) => stage(key, value, validate)
+		});
+		const isNum = (v) => typeof v === "number" && isFinite(v);
+		const isBool = (v) => typeof v === "boolean";
+		Object.defineProperties(wrapper, {
+			name: {
+				enumerable: true,
+				get: () => String(input.name ?? "")
+			},
+			type: {
+				enumerable: true,
+				get: () => ACROBAT_TYPE[subtype] ?? subtype
+			},
+			page: {
+				enumerable: true,
+				get: () => Number(input.page ?? 0)
+			},
+			author: {
+				enumerable: true,
+				get: () => String(input.author ?? "")
+			},
+			subject: {
+				enumerable: true,
+				get: () => String(input.subject ?? "")
+			},
+			strokeColor: prop("strokeColor", isColorArray),
+			fillColor: prop("fillColor", isColorArray),
+			opacity: prop("opacity", (v) => isNum(v) && Number(v) >= 0 && Number(v) <= 1),
+			width: prop("width", (v) => isNum(v) && Number(v) >= 0),
+			style: prop("borderStyle", (v) => v === "S" || v === "D"),
+			dash: prop("dash", (v) => Array.isArray(v) && v.every(isNum)),
+			rect: prop("rect", (v) => Array.isArray(v) && v.length === 4 && v.every(isNum)),
+			contents: prop("contents", (v) => typeof v === "string"),
+			hidden: prop("hidden", isBool),
+			print: prop("print", isBool),
+			readOnly: prop("readOnly", isBool),
+			lock: prop("locked", isBool),
+			noView: prop("noView", isBool),
+			toggleNoView: prop("toggleNoView", isBool),
+			doc: {
+				enumerable: false,
+				get: () => doc
+			}
+		});
+		wrapper.getProps = () => {
+			const out = {};
+			for (const key of Object.keys(record.current)) out[key] = cloneAnnotValue(record.current[key]);
+			return out;
+		};
+		wrapper.setProps = (props) => {
+			const source = props ?? {};
+			for (const key of Object.keys(source)) wrapper[key] = source[key];
+		};
+		return wrapper;
+	};
+	const getAnnots = (spec) => {
+		if (!state) return null;
+		const nPage = spec?.nPage;
+		if (nPage === void 0 || nPage === null) {
+			if (!state.annotsCoverDocument) diagnostic("unsupported-api", "getAnnots: whole-document search is limited to the prefetched pages (compatibility deviation)");
+			return state.annots.length ? state.annots.map((record) => record.wrapper) : null;
+		}
+		const page = Math.trunc(Number(nPage));
+		if (!state.annotPages.has(page)) {
+			diagnostic("unsupported-api", `getAnnots: page ${page} is outside the prefetched annots plane (compatibility deviation)`);
+			return null;
+		}
+		const records = state.annotsByPage.get(page) ?? [];
+		return records.length ? records.map((record) => record.wrapper) : null;
+	};
+	const getAnnot = (nPage, name) => {
+		const records = getAnnots({ nPage });
+		if (!records) return null;
+		for (const wrapper of records) if (String(wrapper.name) === String(name)) return wrapper;
+		return null;
+	};
+	doc.getAnnots = getAnnots;
+	doc.getAnnot = getAnnot;
 	Object.defineProperties(doc, {
 		documentFileName: {
 			enumerable: true,
@@ -181,7 +735,26 @@ function installAcroJs(g) {
 		}
 	};
 	doc.print = () => state?.uiEffects.push({ kind: "print" });
-	doc.submitForm = () => blocked("submitForm");
+	doc.submitForm = (cUrlOrArgs, bFDF, bEmpty, aFields) => {
+		if (!state) return;
+		const args = cUrlOrArgs !== null && typeof cUrlOrArgs === "object" ? cUrlOrArgs : {
+			cURL: cUrlOrArgs,
+			bFDF,
+			bEmpty,
+			aFields
+		};
+		const names = Array.isArray(args.aFields) ? args.aFields.map((name) => String(name)) : null;
+		const submitAs = args.cSubmitAs === void 0 ? void 0 : String(args.cSubmitAs).toUpperCase();
+		const format = submitAs === "FDF" ? "fdf" : submitAs === "XFDF" ? "xfdf" : submitAs === "HTML" ? "html" : submitAs === "PDF" ? "pdf" : args.bFDF === false ? "html" : void 0;
+		state.uiEffects.push({
+			kind: "submitForm",
+			url: args.cURL === void 0 || args.cURL === null ? null : String(args.cURL),
+			fieldNames: names,
+			includeEmpty: Boolean(args.bEmpty),
+			...format === void 0 ? {} : { format },
+			...args.bGet === void 0 ? {} : { method: args.bGet ? "get" : "post" }
+		});
+	};
 	doc.mailDoc = () => blocked("mailDoc");
 	doc.getURL = () => blocked("getURL");
 	const app = {
@@ -249,6 +822,7 @@ function installAcroJs(g) {
 		const hour = local.getUTCHours();
 		const minute = local.getUTCMinutes();
 		const second = local.getUTCSeconds();
+		const hour12 = hour % 12 === 0 ? 12 : hour % 12;
 		const tokens = {
 			yyyy: String(year),
 			yy: pad(year % 100),
@@ -259,12 +833,15 @@ function installAcroJs(g) {
 			dd: pad(day),
 			d: String(day),
 			HH: pad(hour),
+			hh: pad(hour12),
+			h: String(hour12),
 			H: String(hour),
 			MM: pad(minute),
 			M: String(minute),
-			ss: pad(second)
+			ss: pad(second),
+			tt: hour < 12 ? "am" : "pm"
 		};
-		return String(format).replace(/yyyy|mmmm|mmm|yy|mm|dd|HH|MM|ss|m|d|H|M/g, (token) => tokens[token]);
+		return String(format).replace(/yyyy|mmmm|mmm|yy|mm|dd|HH|hh|MM|ss|tt|m|d|H|h|M/g, (token) => tokens[token]);
 	};
 	const util = {
 		printd,
@@ -294,14 +871,53 @@ function installAcroJs(g) {
 		});
 		const fieldsByName = new Map(fields.map((field) => [String(field.input.name), field]));
 		const fieldsByRef = new Map(fields.map((field) => [refKey(field.input.ref), field]));
+		const annots = (input.annots ?? []).map((annot) => {
+			const writableSnapshot = () => ({
+				strokeColor: cloneAnnotValue(annot.strokeColor ?? ["T"]),
+				fillColor: cloneAnnotValue(annot.fillColor ?? ["T"]),
+				opacity: Number(annot.opacity ?? 1),
+				width: Number(annot.width ?? 1),
+				borderStyle: String(annot.borderStyle ?? "S"),
+				dash: cloneAnnotValue(annot.dash ?? []),
+				rect: cloneAnnotValue(annot.rect ?? [
+					0,
+					0,
+					0,
+					0
+				]),
+				contents: String(annot.contents ?? ""),
+				hidden: Boolean(annot.hidden),
+				print: Boolean(annot.print),
+				readOnly: Boolean(annot.readOnly),
+				locked: Boolean(annot.locked),
+				noView: Boolean(annot.noView),
+				toggleNoView: Boolean(annot.toggleNoView)
+			});
+			const record = {
+				input: annot,
+				original: writableSnapshot(),
+				current: writableSnapshot(),
+				wrapper: {}
+			};
+			record.wrapper = makeAnnot(record);
+			return record;
+		});
+		const annotsByPage = /* @__PURE__ */ new Map();
+		for (const record of annots) {
+			const page = Number(record.input.page ?? 0);
+			const bucket = annotsByPage.get(page);
+			if (bucket) bucket.push(record);
+			else annotsByPage.set(page, [record]);
+		}
 		const eventInput = input.event ?? {};
 		const target = fieldsByRef.get(refKey(eventInput.target));
 		const source = fieldsByRef.get(refKey(eventInput.source));
 		const initialValue = eventInput.value !== void 0 ? cloneValue(eventInput.value) : cloneValue(target?.value ?? null);
+		const eventType = eventInput.type !== void 0 ? String(eventInput.type) : eventInput.kind === "name-tree-boot" ? "Doc" : "Field";
 		const event = {
-			name: eventName(String(eventInput.kind ?? "")),
-			type: eventInput.kind === "name-tree-boot" ? "Doc" : "Field",
-			target: target?.wrapper ?? null,
+			name: eventInput.name !== void 0 ? String(eventInput.name) : eventName(String(eventInput.kind ?? "")),
+			type: eventType,
+			target: target?.wrapper ?? (eventType === "Doc" ? doc : null),
 			targetName: String(target?.input.name ?? ""),
 			source: source?.wrapper ?? { source: doc },
 			value: initialValue,
@@ -318,6 +934,10 @@ function installAcroJs(g) {
 			fields,
 			fieldsByName,
 			fieldsByRef,
+			annots,
+			annotsByPage,
+			annotPages: new Set((input.annotPages ?? []).map((page) => Math.trunc(Number(page)))),
+			annotsCoverDocument: Boolean(input.annotsCoverDocument),
 			event,
 			resetRefs: [],
 			resetKeys: /* @__PURE__ */ new Set(),
@@ -390,10 +1010,26 @@ function installAcroJs(g) {
 			ref: target.input.ref,
 			text: String(state.event.value ?? "")
 		});
-		const totalEffects = formEffects.length + state.uiEffects.length;
+		const annotEffects = [];
+		for (const record of state.annots) {
+			const patch = {};
+			const flags = {};
+			for (const key of Object.keys(record.current)) {
+				if (sameAnnotValue(record.current[key], record.original[key])) continue;
+				if (ANNOT_FLAG_KEYS.indexOf(key) >= 0) flags[key] = record.current[key];
+				else patch[key] = cloneAnnotValue(record.current[key]);
+			}
+			if (Object.keys(flags).length > 0) patch.flags = flags;
+			if (Object.keys(patch).length > 0) annotEffects.push({
+				ref: record.input.ref,
+				patch
+			});
+		}
+		const totalEffects = formEffects.length + annotEffects.length + state.uiEffects.length;
 		if (totalEffects > state.maxEffects) return {
 			event: eventOutput(),
 			formEffects: [],
+			annotEffects: [],
 			uiEffects: [],
 			diagnostics: [...state.diagnostics],
 			error: {
@@ -404,6 +1040,7 @@ function installAcroJs(g) {
 		return {
 			event: eventOutput(),
 			formEffects,
+			annotEffects,
 			uiEffects: [...state.uiEffects],
 			diagnostics: [...state.diagnostics]
 		};
@@ -411,6 +1048,7 @@ function installAcroJs(g) {
 	const failed = (error) => ({
 		event: eventOutput(),
 		formEffects: [],
+		annotEffects: [],
 		uiEffects: [],
 		diagnostics: [...state?.diagnostics ?? []],
 		error: {
@@ -460,7 +1098,87 @@ function installAcroJs(g) {
 		noPrint: 2,
 		noView: 3
 	});
+	host.color = Object.freeze({
+		transparent: Object.freeze(["T"]),
+		black: Object.freeze(["G", 0]),
+		white: Object.freeze(["G", 1]),
+		gray: Object.freeze(["G", .5]),
+		ltGray: Object.freeze(["G", .75]),
+		dkGray: Object.freeze(["G", .25]),
+		red: Object.freeze([
+			"RGB",
+			1,
+			0,
+			0
+		]),
+		green: Object.freeze([
+			"RGB",
+			0,
+			1,
+			0
+		]),
+		blue: Object.freeze([
+			"RGB",
+			0,
+			0,
+			1
+		]),
+		cyan: Object.freeze([
+			"CMYK",
+			1,
+			0,
+			0,
+			0
+		]),
+		magenta: Object.freeze([
+			"CMYK",
+			0,
+			1,
+			0,
+			0
+		]),
+		yellow: Object.freeze([
+			"CMYK",
+			0,
+			0,
+			1,
+			0
+		]),
+		convert: (value, space) => {
+			if (!isColorArray(value)) return ["T"];
+			const target = String(space);
+			const rgb = colorToRgbTriple(value);
+			if (target === "T" || rgb === null) return ["T"];
+			if (target === "G") return ["G", .3 * rgb[0] + .59 * rgb[1] + .11 * rgb[2]];
+			if (target === "RGB") return [
+				"RGB",
+				rgb[0],
+				rgb[1],
+				rgb[2]
+			];
+			if (target === "CMYK") {
+				const k = 1 - Math.max(rgb[0], rgb[1], rgb[2]);
+				return [
+					"CMYK",
+					1 - rgb[0] - k,
+					1 - rgb[1] - k,
+					1 - rgb[2] - k,
+					k
+				];
+			}
+			return ["T"];
+		},
+		equal: (a, b) => {
+			if (!isColorArray(a) || !isColorArray(b)) return false;
+			const left = colorToRgbTriple(a);
+			const right = colorToRgbTriple(b);
+			if (left === null || right === null) return left === right;
+			return left.every((component, index) => Math.abs(component - right[index]) < 1e-6);
+		}
+	});
 	host.getField = getField;
+	host.getAnnots = getAnnots;
+	host.getAnnot = getAnnot;
 	host.resetForm = doc.resetForm;
 	host.print = doc.print;
 	host.submitForm = doc.submitForm;
@@ -522,8 +1240,226 @@ function installAcroJs(g) {
 		const places = Math.max(0, Math.min(10, Math.trunc(Number(decimals))));
 		state.event.value = `${(numberValue(state.event.value) * 100).toFixed(places)}%`;
 	};
-	host.AFDate_FormatEx = (format) => {
-		if (state) state.event.value = printd(format, new FixedDate(String(state.event.value ?? "")));
+	const DATE_FORMATS = [
+		"m/d",
+		"m/d/yy",
+		"mm/dd/yy",
+		"mm/yy",
+		"d-mmm",
+		"d-mmm-yy",
+		"dd-mmm-yy",
+		"yy-mm-dd",
+		"mmm-yy",
+		"mmmm-yy",
+		"mmm d, yyyy",
+		"mmmm d, yyyy",
+		"m/d/yy h:MM tt",
+		"m/d/yy HH:MM"
+	];
+	const TIME_FORMATS = [
+		"HH:MM",
+		"h:MM tt",
+		"HH:MM:ss",
+		"h:MM:ss tt"
+	];
+	const rejectWithAlert = (message) => {
+		if (!state) return;
+		state.uiEffects.push({
+			kind: "alert",
+			message,
+			icon: 0
+		});
+		state.event.rc = false;
+	};
+	const formatMismatch = () => rejectWithAlert(`The value entered does not match the format of the field [ ${String(state?.event.targetName ?? "")} ]`);
+	const dateMismatch = (format) => rejectWithAlert(`Invalid date/time: please ensure that the date/time exists. Field [ ${String(state?.event.targetName ?? "")} ] should match format ${String(format ?? "")}`);
+	const mergeChange = (eventObject) => {
+		const e = eventObject ?? state?.event ?? {};
+		const value = String(e.value ?? "");
+		if (e.willCommit) return value;
+		const start = Math.max(0, Math.trunc(Number(e.selStart ?? 0)));
+		const end = Math.max(start, Math.trunc(Number(e.selEnd ?? 0)));
+		return value.slice(0, start) + String(e.change ?? "") + value.slice(end);
+	};
+	host.AFMergeChange = mergeChange;
+	const makeNumber = (value) => {
+		if (typeof value === "number") return Number.isFinite(value) ? value : null;
+		let text = String(value ?? "").trim();
+		if (text === "") return null;
+		text = text.replace(/[^0-9,.\-+eE]/g, "");
+		if (text.includes(",") && text.includes(".")) text = text.lastIndexOf(",") > text.lastIndexOf(".") ? text.replace(/\./g, "").replace(",", ".") : text.replace(/,/g, "");
+		else if (text.includes(",")) text = (text.match(/,/g) ?? []).length === 1 ? text.replace(",", ".") : text.replace(/,/g, "");
+		const parsed = Number(text);
+		return text !== "" && Number.isFinite(parsed) ? parsed : null;
+	};
+	host.AFMakeNumber = makeNumber;
+	host.AFExtractNums = (value) => {
+		const matches = String(value ?? "").match(/\d+/g);
+		return matches && matches.length > 0 ? [...matches] : null;
+	};
+	const validNumberText = (text, separatorStyle) => {
+		const trimmed = text.trim();
+		if (trimmed === "") return true;
+		return (separatorStyle === 2 || separatorStyle === 3 ? /^[+-]?(\d+|\d{1,3}(\.\d{3})+)?(,\d*)?$/ : /^[+-]?(\d+|\d{1,3}(,\d{3})+)?(\.\d*)?$/).test(trimmed) && /\d/.test(trimmed);
+	};
+	host.AFNumber_Keystroke = (_decimals, separatorStyle, _negativeStyle, _currencyStyle, currency) => {
+		if (!state || !state.event.willCommit) return;
+		const proposed = mergeChange(state.event);
+		const cleaned = currency ? proposed.split(String(currency)).join("") : proposed;
+		if (!validNumberText(cleaned, Math.trunc(Number(separatorStyle)))) formatMismatch();
+	};
+	host.AFPercent_Keystroke = (_decimals, separatorStyle) => {
+		if (!state || !state.event.willCommit) return;
+		const cleaned = mergeChange(state.event).replace(/%\s*$/, "");
+		if (!validNumberText(cleaned, Math.trunc(Number(separatorStyle)))) formatMismatch();
+	};
+	const digitsOf = (value) => String(value ?? "").replace(/\D/g, "");
+	const afSpecialFormat = (psf) => {
+		if (!state) return;
+		const digits = digitsOf(state.event.value);
+		const kind = Math.trunc(Number(psf));
+		let formatted = String(state.event.value ?? "");
+		if (kind === 0) formatted = digits.slice(0, 5);
+		else if (kind === 1) formatted = `${digits.slice(0, 5)}-${digits.slice(5, 9)}`;
+		else if (kind === 2) formatted = digits.length >= 10 ? `(${digits.slice(0, 3)}) ${digits.slice(3, 6)}-${digits.slice(6, 10)}` : `${digits.slice(0, 3)}-${digits.slice(3, 7)}`;
+		else if (kind === 3) formatted = `${digits.slice(0, 3)}-${digits.slice(3, 5)}-${digits.slice(5, 9)}`;
+		state.event.value = formatted;
+	};
+	host.AFSpecial_Format = afSpecialFormat;
+	host.AFSpecial_Keystroke = (psf) => {
+		if (!state || !state.event.willCommit) return;
+		const merged = mergeChange(state.event);
+		if (merged.trim() === "") return;
+		const digits = digitsOf(merged).length;
+		const kind = Math.trunc(Number(psf));
+		if (!(kind === 0 ? digits === 5 : kind === 1 ? digits === 9 : kind === 2 ? digits === 7 || digits === 10 : digits === 9)) formatMismatch();
+	};
+	host.AFRange_Validate = (useGreater, greaterThan, useLess, lessThan) => {
+		if (!state) return;
+		const value = makeNumber(state.event.value);
+		if (value === null) return;
+		const hasGreater = Boolean(useGreater);
+		const hasLess = Boolean(useLess);
+		const low = Number(greaterThan);
+		const high = Number(lessThan);
+		if ((!hasGreater || value >= low) && (!hasLess || value <= high)) return;
+		rejectWithAlert(hasGreater && hasLess ? `Invalid value: must be greater than or equal to ${low} and less than or equal to ${high}.` : hasGreater ? `Invalid value: must be greater than or equal to ${low}.` : `Invalid value: must be less than or equal to ${high}.`);
+	};
+	const nowWall = () => {
+		const env = state?.input.environment ?? {};
+		const local = new NativeDate(Number(env.nowMs ?? 0) + Number(env.utcOffsetMinutes ?? 0) * 6e4);
+		return {
+			y: local.getUTCFullYear(),
+			m: local.getUTCMonth() + 1,
+			d: local.getUTCDate(),
+			H: 0,
+			M: 0,
+			S: 0
+		};
+	};
+	/** printd adds the environment offset itself, so a wall time converts back. */
+	const wallDate = (parts) => {
+		const env = state?.input.environment ?? {};
+		return new NativeDate(NativeDate.UTC(parts.y, parts.m - 1, parts.d, parts.H, parts.M, parts.S) - Number(env.utcOffsetMinutes ?? 0) * 6e4);
+	};
+	/** Lenient scand-style parse: numbers mapped by the format's token order,
+	*  month names accepted, missing parts defaulted like Acrobat's scand. */
+	const parseDateLoose = (raw, format) => {
+		const text = String(raw ?? "").trim();
+		if (text === "") return null;
+		const lower = text.toLowerCase();
+		let namedMonth = null;
+		for (let index = 0; index < 12; index += 1) if (lower.indexOf(monthShort[index].toLowerCase()) >= 0) {
+			namedMonth = index + 1;
+			break;
+		}
+		const timeMatch = /(\d{1,2}):(\d{2})(?::(\d{2}))?\s*(am|pm)?/i.exec(text);
+		let H = 0;
+		let M = 0;
+		let S = 0;
+		if (timeMatch) {
+			H = Number(timeMatch[1]);
+			M = Number(timeMatch[2]);
+			S = Number(timeMatch[3] ?? 0);
+			const marker = String(timeMatch[4] ?? "").toLowerCase();
+			if (marker === "pm" && H < 12) H += 12;
+			if (marker === "am" && H === 12) H = 0;
+			if (H > 23 || M > 59 || S > 59) return null;
+		}
+		const numbers = ((timeMatch ? text.slice(0, timeMatch.index) + text.slice(timeMatch.index + timeMatch[0].length) : text).match(/\d+/g) ?? []).map((token) => Number(token));
+		const order = [];
+		for (const token of String(format ?? "").match(/yyyy|mmmm|mmm|yy|mm|dd|m|d/g) ?? []) {
+			const kind = token[0] === "y" ? "y" : token[0] === "m" ? "m" : "d";
+			if (order.indexOf(kind) < 0) order.push(kind);
+		}
+		let y = null;
+		let m = namedMonth;
+		let d = null;
+		let cursor = 0;
+		for (const kind of order) {
+			if (kind === "m" && namedMonth !== null) continue;
+			if (cursor >= numbers.length) break;
+			const value = numbers[cursor];
+			cursor += 1;
+			if (kind === "y") y = value;
+			else if (kind === "m") m = value;
+			else d = value;
+		}
+		if (y === null && m === null && d === null && !timeMatch) return null;
+		const today = nowWall();
+		if (y === null) y = today.y;
+		else if (y < 100) y = y < 50 ? 2e3 + y : 1900 + y;
+		if (m === null) m = today.m;
+		if (d === null) d = 1;
+		if (m < 1 || m > 12 || d < 1 || d > 31) return null;
+		const probe = new NativeDate(NativeDate.UTC(y, m - 1, d));
+		if (probe.getUTCFullYear() !== y || probe.getUTCMonth() !== m - 1 || probe.getUTCDate() !== d) return null;
+		return {
+			y,
+			m,
+			d,
+			H,
+			M,
+			S
+		};
+	};
+	const afDateFormatEx = (format) => {
+		if (!state) return;
+		const raw = String(state.event.value ?? "");
+		if (raw.trim() === "") return;
+		let date = new FixedDate(raw);
+		if (Number.isNaN(date.getTime())) {
+			const parts = parseDateLoose(raw, format);
+			if (!parts) return;
+			date = wallDate(parts);
+		}
+		state.event.value = printd(format, date);
+	};
+	host.AFDate_FormatEx = afDateFormatEx;
+	host.AFDate_Format = (index) => afDateFormatEx(DATE_FORMATS[Math.trunc(Number(index))] ?? "m/d/yy");
+	const afDateKeystrokeEx = (format) => {
+		if (!state || !state.event.willCommit) return;
+		const merged = mergeChange(state.event);
+		if (merged.trim() === "") return;
+		if (!parseDateLoose(merged, format)) dateMismatch(format);
+	};
+	host.AFDate_KeystrokeEx = afDateKeystrokeEx;
+	host.AFDate_Keystroke = (index) => afDateKeystrokeEx(DATE_FORMATS[Math.trunc(Number(index))] ?? "m/d/yy");
+	const afTimeFormatEx = (format) => {
+		if (!state) return;
+		const raw = String(state.event.value ?? "");
+		if (raw.trim() === "") return;
+		const parts = parseDateLoose(raw, format);
+		if (!parts) return;
+		state.event.value = printd(format, wallDate(parts));
+	};
+	host.AFTime_FormatEx = afTimeFormatEx;
+	host.AFTime_Format = (index) => afTimeFormatEx(TIME_FORMATS[Math.trunc(Number(index))] ?? "HH:MM");
+	host.AFTime_Keystroke = (index) => {
+		if (!state || !state.event.willCommit) return;
+		const merged = mergeChange(state.event);
+		if (merged.trim() === "") return;
+		if (!parseDateLoose(merged, TIME_FORMATS[Math.trunc(Number(index))] ?? "HH:MM")) dateMismatch(TIME_FORMATS[Math.trunc(Number(index))] ?? "HH:MM");
 	};
 	host.fetch = void 0;
 	host.XMLHttpRequest = void 0;
@@ -532,43 +1468,6 @@ function installAcroJs(g) {
 /** The exact self-contained source evaluated in Node parity tests and QuickJS. */
 const PRELUDE_SOURCE = `(${installAcroJs.toString()})(globalThis);`;
 //#endregion
-//#region src/types.ts
-const DEFAULT_SCRIPT_BUDGET = Object.freeze({
-	maxExecutionMs: 50,
-	maxMemoryBytes: 16 * 1024 * 1024,
-	maxStackBytes: 512 * 1024,
-	maxEffects: 256,
-	maxOutputBytes: 1024 * 1024
-});
-const DEFAULT_SCRIPT_SECURITY_POLICY = Object.freeze({
-	enabled: false,
-	executionOwner: "originating-client-only",
-	nameTreeBoot: "lazy-first-transaction",
-	submitForm: "blocked",
-	openAction: "preserve-only",
-	pageActions: "preserve-only",
-	catalogLifecycleActions: "preserve-only",
-	annotationActions: "widget-activate-only"
-});
-/** Frozen V1 dispatch matrix; extracted actions outside it remain data only. */
-const SCRIPT_EVENT_MATRIX = Object.freeze({
-	nameTree: "lazy-first-originating-field-transaction",
-	field: Object.freeze({
-		keystroke: "execute-on-commit",
-		validate: "execute",
-		calculate: "execute-in-calculation-order",
-		format: "execute-after-value-calculation"
-	}),
-	openAction: "preserve-only",
-	page: "preserve-only",
-	catalogLifecycle: "preserve-only",
-	annotation: Object.freeze({
-		widgetActivate: "execute-on-originating-client",
-		other: "preserve-only"
-	}),
-	submitForm: "blocked"
-});
-//#endregion
-export { DEFAULT_SCRIPT_BUDGET, DEFAULT_SCRIPT_SECURITY_POLICY, PRELUDE_SOURCE, SCRIPT_EVENT_MATRIX, installAcroJs, javaScriptProgramFromActionTree, javaScriptSourcesFromActionTree, scriptFieldsFromSnapshot };
+export { ANNOT_WRITABLE_KEYS, DEFAULT_SCRIPT_BUDGET, DEFAULT_SCRIPT_SECURITY_POLICY, PRELUDE_SOURCE, SCRIPT_EVENT_MATRIX, createScriptHost, cssToScriptColor, installAcroJs, isScriptColorArray, javaScriptProgramFromActionTree, javaScriptSourcesFromActionTree, resolveScriptIdentity, scriptColorToCss, scriptColorToRgb, scriptFieldsFromSnapshot, seedFrom };
 
 //# sourceMappingURL=index.js.map