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

package/dist/scripting.cjs

@@ -0,0 +1,485 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _embedpdf_core_acrojs = require("@embedpdf/core-acrojs");
+//#region src/scripting.ts
+const refKey = (ref) => ref.kind === "objectNumber" ? `obj:${ref.fieldObjectNumber}` : `fqn:${ref.name}`;
+const sameRef = (left, right) => refKey(left) === refKey(right);
+const cloneValue = (value) => Array.isArray(value) ? [...value] : value;
+const sameValue = (left, right) => Array.isArray(left) && Array.isArray(right) ? left.length === right.length && left.every((value, index) => value === right[index]) : left === right;
+function cloneFields(fields) {
+	return fields.map((field) => ({
+		...field,
+		ref: { ...field.ref },
+		value: cloneValue(field.value),
+		defaultValue: cloneValue(field.defaultValue),
+		...field.options ? { options: field.options.map((option) => ({ ...option })) } : {}
+	}));
+}
+function fieldByRef(fields, ref) {
+	return fields.find((field) => sameRef(field.ref, ref));
+}
+function snapshotField(snapshot, ref) {
+	return snapshot.fields.find((field) => sameRef(field.ref, ref));
+}
+function scriptValueFromFormValue(field, value) {
+	if (field.family === "text" && value.type === "text") return value.value;
+	if ((field.family === "checkbox" || field.family === "radio") && value.type === "toggle") return value.state ?? "Off";
+	if (field.family === "combobox" && value.type === "choice") return value.values[0] ?? "";
+	if (field.family === "listbox" && value.type === "choice") return [...value.values];
+	throw new Error(`Form value type '${value.type}' does not match field family '${field.family}'`);
+}
+function formValueFromScriptValue(field) {
+	switch (field.family) {
+		case "text": return {
+			type: "text",
+			value: String(field.value ?? "")
+		};
+		case "checkbox":
+		case "radio": return {
+			type: "toggle",
+			state: field.value === null || field.value === void 0 || String(field.value) === "Off" ? null : String(field.value)
+		};
+		case "combobox": return {
+			type: "choice",
+			values: Array.isArray(field.value) ? field.value.slice(0, 1) : [String(field.value ?? "")]
+		};
+		case "listbox": return {
+			type: "choice",
+			values: Array.isArray(field.value) ? [...field.value] : [String(field.value ?? "")]
+		};
+		default: return null;
+	}
+}
+function applyEffects(overlay, effects) {
+	for (const effect of effects) {
+		if (effect.kind === "reset") {
+			for (const ref of effect.refs) {
+				const field = fieldByRef(overlay.fields, ref);
+				if (!field) continue;
+				field.value = cloneValue(field.defaultValue);
+				overlay.resetKeys.add(refKey(ref));
+			}
+			continue;
+		}
+		const field = fieldByRef(overlay.fields, effect.ref);
+		if (!field) continue;
+		const key = refKey(effect.ref);
+		if (effect.kind === "setValue") {
+			field.value = scriptValueFromFormValue(field, effect.value);
+			overlay.resetKeys.delete(key);
+		} else if (effect.kind === "setDisplay") field.display = effect.display;
+		else overlay.appearances.set(key, {
+			ref: effect.ref,
+			text: effect.text
+		});
+	}
+}
+function canonicalEffects(overlay) {
+	const effects = [];
+	const resets = [];
+	for (const field of overlay.fields) {
+		const original = fieldByRef(overlay.original, field.ref);
+		if (!original) continue;
+		if (!sameValue(original.value, field.value)) {
+			const key = refKey(field.ref);
+			if (overlay.resetKeys.has(key) && sameValue(field.value, field.defaultValue)) resets.push(field.ref);
+			else {
+				const value = formValueFromScriptValue(field);
+				if (value) effects.push({
+					kind: "setValue",
+					ref: field.ref,
+					value
+				});
+			}
+		}
+		if (original.display !== field.display) effects.push({
+			kind: "setDisplay",
+			ref: field.ref,
+			display: field.display
+		});
+	}
+	if (resets.length > 0) effects.unshift({
+		kind: "reset",
+		refs: resets
+	});
+	effects.push(...Array.from(overlay.appearances.values(), ({ ref, text }) => ({
+		kind: "setAppearanceText",
+		ref,
+		text
+	})));
+	return effects;
+}
+function scriptError(message) {
+	return {
+		kind: "invalid-output",
+		message
+	};
+}
+function utf8Length(value) {
+	let length = 0;
+	for (let index = 0; index < value.length; index += 1) {
+		const code = value.charCodeAt(index);
+		if (code < 128) length += 1;
+		else if (code < 2048) length += 2;
+		else if (code >= 55296 && code <= 56319 && index + 1 < value.length) {
+			length += 4;
+			index += 1;
+		} else length += 3;
+	}
+	return length;
+}
+function pageNumberFor(meta, field) {
+	const pon = field.widgets.find((widget) => widget.pageObjectNumber > 0)?.pageObjectNumber;
+	if (!meta || pon === void 0) return 0;
+	const index = meta.pages.findIndex((page) => page.pageObjectNumber === pon);
+	return Math.max(0, index);
+}
+function statusFromEffects(result) {
+	if (result.results.some(({ status }) => status === "failed" || status === "skipped")) return "failed";
+	if (result.results.some(({ status }) => status === "rejected")) return "failed";
+	return result.results.some(({ status }) => status === "applied") ? "applied" : "unchanged";
+}
+var FormScriptingController = class {
+	constructor(options) {
+		this.options = options;
+		this.disposed = false;
+		this.transaction = options.transaction.bind(options);
+		this.transactionBudget = options.budget;
+	}
+	/** The realm belongs to its OWNER (the actions plugin, or the caller that
+	*  minted a detached one) — this only fences further transactions. */
+	dispose() {
+		this.disposed = true;
+	}
+	async commit(ref, proposed) {
+		return this.transact(ref, proposed);
+	}
+	/** Execute one originating widget's activation action (`/A`, including `/Next`). */
+	async activate(ref, action) {
+		return this.transact(ref, void 0, action);
+	}
+	/** Run lazy document boot plus the `/CO` chain without a user field change.
+	*  The anchor field resolves INSIDE the transaction (undefined ref). */
+	async recalculate() {
+		return this.transact(void 0);
+	}
+	async transact(refInput, proposed, activation) {
+		if (this.disposed) throw new Error("Form scripting controller is disposed");
+		return this.transaction((txn) => this.transactBody(txn, refInput, proposed, activation));
+	}
+	async transactBody(txn, refInput, proposed, activation) {
+		const snapshot = await this.options.doc.forms.list();
+		const ref = refInput ?? snapshot.calculationOrder.find((candidate) => candidate !== null && snapshotField(snapshot, candidate) !== void 0) ?? snapshot.fields[0]?.ref;
+		if (!ref) return {
+			status: "unchanged",
+			scripted: true,
+			effectsResult: null,
+			uiEffects: [],
+			diagnostics: []
+		};
+		const target = snapshotField(snapshot, ref);
+		if (!target) return this.failed([], [], scriptError(`Form field '${refKey(ref)}' no longer exists`));
+		const original = (0, _embedpdf_core_acrojs.scriptFieldsFromSnapshot)(snapshot);
+		const overlay = {
+			original,
+			fields: cloneFields(original),
+			resetKeys: /* @__PURE__ */ new Set(),
+			appearances: /* @__PURE__ */ new Map()
+		};
+		const targetInput = fieldByRef(overlay.fields, ref);
+		if (!targetInput) return this.failed([], [], scriptError(`Form field '${refKey(ref)}' has no script view`));
+		const hasProposedValue = proposed !== void 0;
+		let proposedValue = cloneValue(targetInput.value);
+		if (proposed) try {
+			proposedValue = scriptValueFromFormValue(targetInput, proposed);
+		} catch (error) {
+			return this.failed([], [], scriptError(error instanceof Error ? error.message : String(error)));
+		}
+		const uiEffects = [];
+		const diagnostics = [];
+		const pageNumber = pageNumberFor(this.options.document(), target);
+		const budget = this.transactionBudget ?? _embedpdf_core_acrojs.DEFAULT_SCRIPT_BUDGET;
+		let executionMs = 0;
+		let aggregateOutputSize = 0;
+		const consume = (output, phase) => {
+			aggregateOutputSize += utf8Length(JSON.stringify(output));
+			uiEffects.push(...output.uiEffects.map((effect) => ({
+				...effect,
+				phase
+			})));
+			diagnostics.push(...output.diagnostics);
+			if (aggregateOutputSize > budget.maxOutputBytes) return {
+				kind: "budget",
+				message: `Form script transaction output exceeded ${budget.maxOutputBytes} bytes`
+			};
+			return output.error ?? null;
+		};
+		const remainingBudget = () => {
+			const remaining = budget.maxExecutionMs - executionMs;
+			return remaining <= 0 ? null : {
+				...budget,
+				maxExecutionMs: remaining
+			};
+		};
+		const world = (fields, event) => ({
+			fields,
+			pageNumber,
+			event
+		});
+		const run = async (source, input) => {
+			const remaining = remainingBudget();
+			if (!remaining) return { error: {
+				kind: "budget",
+				message: "Form script transaction timed out"
+			} };
+			let output;
+			try {
+				const startedAt = Date.now();
+				output = await txn.run(source, input, remaining);
+				executionMs += Date.now() - startedAt;
+			} catch (error) {
+				return { error: scriptError(error instanceof Error ? error.message : String(error)) };
+			}
+			const error = consume(output, "user");
+			return error ? { error } : { output };
+		};
+		{
+			let boot = null;
+			try {
+				boot = await txn.boot(world(overlay.fields, { kind: "name-tree-boot" }), budget);
+			} catch (error) {
+				diagnostics.push({
+					code: "script-error",
+					message: `Document boot script failed (continuing without it): ${error instanceof Error ? error.message : String(error)}`
+				});
+			}
+			if (boot) {
+				const bootError = consume(boot, "boot");
+				if (!bootError) applyEffects(overlay, boot.formEffects);
+				else diagnostics.push({
+					code: "script-error",
+					message: `Document boot script failed (continuing without it): ${bootError.message}`
+				});
+			}
+		}
+		const bootEffects = canonicalEffects(overlay);
+		if (activation) {
+			let program;
+			try {
+				program = (0, _embedpdf_core_acrojs.javaScriptProgramFromActionTree)(activation);
+			} catch (error) {
+				return this.failed(uiEffects, diagnostics, scriptError(error instanceof Error ? error.message : String(error)));
+			}
+			if (program) {
+				const activated = await run(program, world(overlay.fields, {
+					kind: "widget-activate",
+					target: ref,
+					source: ref,
+					value: targetInput.value
+				}));
+				if (activated.error) return this.failed(uiEffects, diagnostics, activated.error);
+				applyEffects(overlay, activated.output.formEffects);
+			}
+		}
+		if (!activation && hasProposedValue && target.actions?.keystroke && target.family === "text") {
+			let program;
+			try {
+				program = (0, _embedpdf_core_acrojs.javaScriptProgramFromActionTree)(target.actions.keystroke);
+			} catch (error) {
+				return this.failed(uiEffects, diagnostics, scriptError(error instanceof Error ? error.message : String(error)));
+			}
+			if (program) {
+				const oldValue = String(targetInput.value ?? "");
+				const typing = await run(program, world(overlay.fields, {
+					kind: "field-keystroke",
+					target: ref,
+					source: ref,
+					value: oldValue,
+					change: String(proposedValue ?? ""),
+					selStart: 0,
+					selEnd: oldValue.length,
+					willCommit: false
+				}));
+				if (typing.error && typing.error.kind !== "exception") return this.failed(uiEffects, diagnostics, typing.error);
+				if (typing.error) diagnostics.push({
+					code: "script-error",
+					message: `Keystroke script failed (kept the typed value): ${typing.error.message}`
+				});
+				else {
+					if (!typing.output.event.rc) return this.finishRejected(bootEffects, uiEffects, diagnostics);
+					applyEffects(overlay, typing.output.formEffects);
+					const event = typing.output.event;
+					const base = String(event.value ?? "");
+					proposedValue = base.slice(0, event.selStart) + event.change + base.slice(Math.max(event.selStart, event.selEnd));
+				}
+				const commit = await run(program, world(overlay.fields, {
+					kind: "field-keystroke",
+					target: ref,
+					source: ref,
+					value: proposedValue,
+					change: "",
+					selStart: 0,
+					selEnd: 0,
+					willCommit: true
+				}));
+				if (commit.error && commit.error.kind !== "exception") return this.failed(uiEffects, diagnostics, commit.error);
+				if (commit.error) diagnostics.push({
+					code: "script-error",
+					message: `Keystroke commit script failed (kept the typed value): ${commit.error.message}`
+				});
+				else {
+					if (!commit.output.event.rc) return this.finishRejected(bootEffects, uiEffects, diagnostics);
+					applyEffects(overlay, commit.output.formEffects);
+					proposedValue = cloneValue(commit.output.event.value);
+				}
+			}
+		}
+		if (!activation && hasProposedValue) {
+			targetInput.value = cloneValue(proposedValue);
+			overlay.resetKeys.delete(refKey(ref));
+		}
+		if (!activation && hasProposedValue && target.actions?.validate) {
+			let program;
+			try {
+				program = (0, _embedpdf_core_acrojs.javaScriptProgramFromActionTree)(target.actions.validate);
+			} catch (error) {
+				return this.failed(uiEffects, diagnostics, scriptError(error instanceof Error ? error.message : String(error)));
+			}
+			if (program) {
+				const validation = await run(program, world(overlay.fields, {
+					kind: "field-validate",
+					target: ref,
+					source: ref,
+					value: proposedValue,
+					willCommit: true
+				}));
+				if (validation.error && validation.error.kind !== "exception") return this.failed(uiEffects, diagnostics, validation.error);
+				if (validation.error) diagnostics.push({
+					code: "script-error",
+					message: `Validate script failed (accepted the value): ${validation.error.message}`
+				});
+				else {
+					if (!validation.output.event.rc) return this.finishRejected(bootEffects, uiEffects, diagnostics);
+					targetInput.value = cloneValue(validation.output.event.value);
+					applyEffects(overlay, validation.output.formEffects);
+				}
+			}
+		}
+		const formatRefs = !activation && hasProposedValue ? [ref] : [];
+		for (const calculationRef of activation ? [] : snapshot.calculationOrder) {
+			if (!calculationRef) continue;
+			const calculated = snapshotField(snapshot, calculationRef);
+			const tree = calculated?.actions?.calculate;
+			if (!calculated || !tree) continue;
+			let program;
+			try {
+				program = (0, _embedpdf_core_acrojs.javaScriptProgramFromActionTree)(tree);
+			} catch (error) {
+				return this.failed(uiEffects, diagnostics, scriptError(error instanceof Error ? error.message : String(error)));
+			}
+			const calculatedInput = fieldByRef(overlay.fields, calculationRef);
+			if (program && calculatedInput) {
+				const calculation = await run(program, world(overlay.fields, {
+					kind: "field-calculate",
+					target: calculationRef,
+					...hasProposedValue ? { source: ref } : {},
+					value: calculatedInput.value
+				}));
+				if (calculation.error && calculation.error.kind !== "exception") return this.failed(uiEffects, diagnostics, calculation.error);
+				if (calculation.error) diagnostics.push({
+					code: "script-error",
+					message: `Calculate script failed (field left unchanged): ${calculation.error.message}`
+				});
+				else applyEffects(overlay, calculation.output.formEffects);
+			}
+			if (!formatRefs.some((candidate) => sameRef(candidate, calculationRef))) formatRefs.push(calculationRef);
+		}
+		for (const formatRef of formatRefs) {
+			const field = snapshotField(snapshot, formatRef);
+			const tree = field?.actions?.format;
+			const overlayField = fieldByRef(overlay.fields, formatRef);
+			if (!field || !tree || !overlayField) continue;
+			let program;
+			try {
+				program = (0, _embedpdf_core_acrojs.javaScriptProgramFromActionTree)(tree);
+			} catch (error) {
+				return this.failed(uiEffects, diagnostics, scriptError(error instanceof Error ? error.message : String(error)));
+			}
+			if (!program) continue;
+			const format = await run(program, world(overlay.fields, {
+				kind: "field-format",
+				target: formatRef,
+				...hasProposedValue ? { source: ref } : {},
+				value: overlayField.value
+			}));
+			if (format.error && format.error.kind !== "exception") return this.failed(uiEffects, diagnostics, format.error);
+			if (format.error) {
+				diagnostics.push({
+					code: "script-error",
+					message: `Format script failed (kept the raw value): ${format.error.message}`
+				});
+				continue;
+			}
+			applyEffects(overlay, format.output.formEffects);
+		}
+		const effects = canonicalEffects(overlay);
+		if (effects.length + uiEffects.length > budget.maxEffects) return this.failed(uiEffects, diagnostics, {
+			kind: "budget",
+			message: `Form script transaction exceeded ${budget.maxEffects} effects`
+		});
+		if (effects.length === 0) return {
+			status: "unchanged",
+			scripted: true,
+			effectsResult: null,
+			uiEffects,
+			diagnostics
+		};
+		if (!this.options.doc.forms.applyEffects) return this.failed(uiEffects, diagnostics, scriptError("This engine does not support batched form effects"));
+		const effectsResult = await this.options.doc.forms.applyEffects(effects);
+		const status = statusFromEffects(effectsResult);
+		return {
+			status,
+			scripted: true,
+			effectsResult,
+			uiEffects,
+			diagnostics,
+			...status === "failed" ? { error: scriptError("One or more native form effects failed") } : {}
+		};
+	}
+	failed(uiEffects, diagnostics, error) {
+		return {
+			status: "failed",
+			scripted: true,
+			effectsResult: null,
+			uiEffects,
+			diagnostics,
+			error
+		};
+	}
+	async finishRejected(bootEffects, uiEffects, diagnostics) {
+		if (bootEffects.length === 0) return {
+			status: "rejected",
+			scripted: true,
+			effectsResult: null,
+			uiEffects,
+			diagnostics
+		};
+		if (!this.options.doc.forms.applyEffects) return this.failed(uiEffects, diagnostics, scriptError("Batched form effects are unavailable"));
+		const effectsResult = await this.options.doc.forms.applyEffects(bootEffects);
+		if (statusFromEffects(effectsResult) === "failed") return this.failed(uiEffects, diagnostics, scriptError("A name-tree boot effect failed"));
+		return {
+			status: "rejected",
+			scripted: true,
+			effectsResult,
+			uiEffects,
+			diagnostics
+		};
+	}
+};
+function createFormScriptingController(options) {
+	return new FormScriptingController(options);
+}
+//#endregion
+exports.FormScriptingController = FormScriptingController;
+exports.createFormScriptingController = createFormScriptingController;
+
+//# sourceMappingURL=scripting.cjs.map

package/dist/scripting.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"scripting.cjs","names":["DEFAULT_SCRIPT_BUDGET"],"sources":["../src/scripting.ts"],"sourcesContent":["import type {\n  DocumentHandle,\n  FormEffect,\n  FormEffectsResult,\n  FormFieldDTO,\n  FormFieldRef,\n  FormFieldValue,\n  FormSnapshot,\n  PdfActionTree,\n} from '@embedpdf/engine-core/runtime';\nimport {\n  DEFAULT_SCRIPT_BUDGET,\n  javaScriptProgramFromActionTree,\n  scriptFieldsFromSnapshot,\n  type ScriptBudget,\n  type ScriptDiagnostic,\n  type ScriptExecutionError,\n  type ScriptFieldInput,\n  type ScriptOutput,\n  type ScriptTransaction,\n  type ScriptUiEffect,\n  type ScriptValue,\n  type ScriptWorldInput,\n} from '@embedpdf/core-acrojs';\nimport type { DocumentMeta } from '@embedpdf/core';\n\nimport type { FormCommitResult, FormUiEffect } from './types';\n\ninterface Overlay {\n  original: ScriptFieldInput[];\n  fields: ScriptFieldInput[];\n  resetKeys: Set<string>;\n  appearances: Map<string, { ref: FormFieldRef; text: string }>;\n}\n\n/**\n * The controller never owns a realm. It rides a realm PORT — this document's\n * own (the actions plugin's per-document host) or a detached one minted by\n * the actions plugin for a document that is not displayed (stamp's\n * asset documents). Either way the owner disposes the realm; `dispose()`\n * here only fences further transactions.\n */\nexport interface FormScriptingControllerOptions {\n  doc: DocumentHandle;\n  document(): DocumentMeta | null;\n  /** The realm's transaction port ({@link ScriptTransaction}). The K/V/C/F\n   *  pipeline runs WHOLLY inside one transaction: snapshot fetch, every\n   *  pass, and the engine commit — the commit-inside-the-boundary law. */\n  transaction<T>(body: (txn: ScriptTransaction) => Promise<T>): Promise<T>;\n  /** The transaction aggregate (output bytes, wall-clock across passes);\n   *  the realm owner hands over the same budget its runs enforce. */\n  budget?: ScriptBudget;\n}\n\nconst refKey = (ref: FormFieldRef): string =>\n  ref.kind === 'objectNumber' ? `obj:${ref.fieldObjectNumber}` : `fqn:${ref.name}`;\n\nconst sameRef = (left: FormFieldRef, right: FormFieldRef): boolean =>\n  refKey(left) === refKey(right);\n\nconst cloneValue = (value: ScriptValue): ScriptValue => (Array.isArray(value) ? [...value] : value);\n\nconst sameValue = (left: ScriptValue, right: ScriptValue): boolean =>\n  Array.isArray(left) && Array.isArray(right)\n    ? left.length === right.length && left.every((value, index) => value === right[index])\n    : left === right;\n\nfunction cloneFields(fields: ScriptFieldInput[]): ScriptFieldInput[] {\n  return fields.map((field) => ({\n    ...field,\n    ref: { ...field.ref },\n    value: cloneValue(field.value),\n    defaultValue: cloneValue(field.defaultValue),\n    ...(field.options ? { options: field.options.map((option) => ({ ...option })) } : {}),\n  }));\n}\n\nfunction fieldByRef<T extends { ref: FormFieldRef }>(\n  fields: T[],\n  ref: FormFieldRef,\n): T | undefined {\n  return fields.find((field) => sameRef(field.ref, ref));\n}\n\nfunction snapshotField(snapshot: FormSnapshot, ref: FormFieldRef): FormFieldDTO | undefined {\n  return snapshot.fields.find((field) => sameRef(field.ref, ref));\n}\n\nfunction scriptValueFromFormValue(field: ScriptFieldInput, value: FormFieldValue): ScriptValue {\n  if (field.family === 'text' && value.type === 'text') return value.value;\n  if ((field.family === 'checkbox' || field.family === 'radio') && value.type === 'toggle') {\n    return value.state ?? 'Off';\n  }\n  if (field.family === 'combobox' && value.type === 'choice') return value.values[0] ?? '';\n  if (field.family === 'listbox' && value.type === 'choice') return [...value.values];\n  throw new Error(`Form value type '${value.type}' does not match field family '${field.family}'`);\n}\n\nfunction formValueFromScriptValue(field: ScriptFieldInput): FormFieldValue | null {\n  switch (field.family) {\n    case 'text':\n      return { type: 'text', value: String(field.value ?? '') };\n    case 'checkbox':\n    case 'radio':\n      return {\n        type: 'toggle',\n        state:\n          field.value === null || field.value === undefined || String(field.value) === 'Off'\n            ? null\n            : String(field.value),\n      };\n    case 'combobox':\n      return {\n        type: 'choice',\n        values: Array.isArray(field.value) ? field.value.slice(0, 1) : [String(field.value ?? '')],\n      };\n    case 'listbox':\n      return {\n        type: 'choice',\n        values: Array.isArray(field.value) ? [...field.value] : [String(field.value ?? '')],\n      };\n    default:\n      return null;\n  }\n}\n\nfunction applyEffects(overlay: Overlay, effects: FormEffect[]): void {\n  for (const effect of effects) {\n    if (effect.kind === 'reset') {\n      for (const ref of effect.refs) {\n        const field = fieldByRef(overlay.fields, ref);\n        if (!field) continue;\n        field.value = cloneValue(field.defaultValue);\n        overlay.resetKeys.add(refKey(ref));\n      }\n      continue;\n    }\n\n    const field = fieldByRef(overlay.fields, effect.ref);\n    if (!field) continue;\n    const key = refKey(effect.ref);\n    if (effect.kind === 'setValue') {\n      field.value = scriptValueFromFormValue(field, effect.value);\n      overlay.resetKeys.delete(key);\n    } else if (effect.kind === 'setDisplay') {\n      field.display = effect.display;\n    } else {\n      overlay.appearances.set(key, { ref: effect.ref, text: effect.text });\n    }\n  }\n}\n\nfunction canonicalEffects(overlay: Overlay): FormEffect[] {\n  const effects: FormEffect[] = [];\n  const resets: FormFieldRef[] = [];\n  for (const field of overlay.fields) {\n    const original = fieldByRef(overlay.original, field.ref);\n    if (!original) continue;\n    if (!sameValue(original.value, field.value)) {\n      const key = refKey(field.ref);\n      if (overlay.resetKeys.has(key) && sameValue(field.value, field.defaultValue)) {\n        resets.push(field.ref);\n      } else {\n        const value = formValueFromScriptValue(field);\n        if (value) effects.push({ kind: 'setValue', ref: field.ref, value });\n      }\n    }\n    if (original.display !== field.display) {\n      effects.push({ kind: 'setDisplay', ref: field.ref, display: field.display });\n    }\n  }\n  if (resets.length > 0) effects.unshift({ kind: 'reset', refs: resets });\n  effects.push(\n    ...Array.from(overlay.appearances.values(), ({ ref, text }) => ({\n      kind: 'setAppearanceText' as const,\n      ref,\n      text,\n    })),\n  );\n  return effects;\n}\n\nfunction scriptError(message: string): ScriptExecutionError {\n  return { kind: 'invalid-output', message };\n}\n\nfunction utf8Length(value: string): number {\n  let length = 0;\n  for (let index = 0; index < value.length; index += 1) {\n    const code = value.charCodeAt(index);\n    if (code < 0x80) length += 1;\n    else if (code < 0x800) length += 2;\n    else if (code >= 0xd800 && code <= 0xdbff && index + 1 < value.length) {\n      length += 4;\n      index += 1;\n    } else length += 3;\n  }\n  return length;\n}\n\nfunction pageNumberFor(meta: DocumentMeta | null, field: FormFieldDTO): number {\n  const pon = field.widgets.find((widget) => widget.pageObjectNumber > 0)?.pageObjectNumber;\n  if (!meta || pon === undefined) return 0;\n  const index = meta.pages.findIndex((page) => page.pageObjectNumber === pon);\n  return Math.max(0, index);\n}\n\nfunction statusFromEffects(result: FormEffectsResult): FormCommitResult['status'] {\n  if (result.results.some(({ status }) => status === 'failed' || status === 'skipped')) {\n    return 'failed';\n  }\n  if (result.results.some(({ status }) => status === 'rejected')) return 'failed';\n  return result.results.some(({ status }) => status === 'applied') ? 'applied' : 'unchanged';\n}\n\nexport class FormScriptingController {\n  private disposed = false;\n  private readonly transaction: <T>(body: (txn: ScriptTransaction) => Promise<T>) => Promise<T>;\n  private readonly transactionBudget: ScriptBudget | undefined;\n\n  constructor(private readonly options: FormScriptingControllerOptions) {\n    this.transaction = options.transaction.bind(options);\n    this.transactionBudget = options.budget;\n  }\n\n  /** The realm belongs to its OWNER (the actions plugin, or the caller that\n   *  minted a detached one) — this only fences further transactions. */\n  dispose(): void {\n    this.disposed = true;\n  }\n\n  async commit(ref: FormFieldRef, proposed: FormFieldValue): Promise<FormCommitResult> {\n    return this.transact(ref, proposed);\n  }\n\n  /** Execute one originating widget's activation action (`/A`, including `/Next`). */\n  async activate(ref: FormFieldRef, action: PdfActionTree): Promise<FormCommitResult> {\n    return this.transact(ref, undefined, action);\n  }\n\n  /** Run lazy document boot plus the `/CO` chain without a user field change.\n   *  The anchor field resolves INSIDE the transaction (undefined ref). */\n  async recalculate(): Promise<FormCommitResult> {\n    return this.transact(undefined);\n  }\n\n  private async transact(\n    refInput: FormFieldRef | undefined,\n    proposed?: FormFieldValue,\n    activation?: PdfActionTree,\n  ): Promise<FormCommitResult> {\n    if (this.disposed) throw new Error('Form scripting controller is disposed');\n    // EVERYTHING inside the realm transaction — snapshot fetch, every pass,\n    // the engine commit — so the next transaction reads post-commit truth.\n    return this.transaction((txn) => this.transactBody(txn, refInput, proposed, activation));\n  }\n\n  private async transactBody(\n    txn: ScriptTransaction,\n    refInput: FormFieldRef | undefined,\n    proposed?: FormFieldValue,\n    activation?: PdfActionTree,\n  ): Promise<FormCommitResult> {\n    const snapshot = await this.options.doc.forms.list();\n    // Recalculate's anchor resolves HERE (first live /CO field, else the\n    // first field); a zero-field document is an honest no-op.\n    const ref =\n      refInput ??\n      snapshot.calculationOrder.find(\n        (candidate): candidate is FormFieldRef =>\n          candidate !== null && snapshotField(snapshot, candidate) !== undefined,\n      ) ??\n      snapshot.fields[0]?.ref;\n    if (!ref) {\n      return {\n        status: 'unchanged',\n        scripted: true,\n        effectsResult: null,\n        uiEffects: [],\n        diagnostics: [],\n      };\n    }\n    const target = snapshotField(snapshot, ref);\n    if (!target) {\n      return this.failed([], [], scriptError(`Form field '${refKey(ref)}' no longer exists`));\n    }\n\n    const original = scriptFieldsFromSnapshot(snapshot);\n    const overlay: Overlay = {\n      original,\n      fields: cloneFields(original),\n      resetKeys: new Set(),\n      appearances: new Map(),\n    };\n    const targetInput = fieldByRef(overlay.fields, ref);\n    if (!targetInput) {\n      return this.failed([], [], scriptError(`Form field '${refKey(ref)}' has no script view`));\n    }\n\n    const hasProposedValue = proposed !== undefined;\n    let proposedValue: ScriptValue = cloneValue(targetInput.value);\n    if (proposed) {\n      try {\n        proposedValue = scriptValueFromFormValue(targetInput, proposed);\n      } catch (error) {\n        return this.failed(\n          [],\n          [],\n          scriptError(error instanceof Error ? error.message : String(error)),\n        );\n      }\n    }\n\n    const uiEffects: FormUiEffect[] = [];\n    const diagnostics: ScriptDiagnostic[] = [];\n    const meta = this.options.document();\n    // Document/identity/environment are HOST-owned now; the world carries the\n    // per-field current page for `this.pageNum`.\n    const pageNumber = pageNumberFor(meta, target);\n    const budget = this.transactionBudget ?? DEFAULT_SCRIPT_BUDGET;\n    let executionMs = 0;\n    let aggregateOutputSize = 0;\n\n    const consume = (\n      output: ScriptOutput,\n      phase: FormUiEffect['phase'],\n    ): ScriptExecutionError | null => {\n      aggregateOutputSize += utf8Length(JSON.stringify(output));\n      // Tag every UI request with WHO asked — embedders suppress boot-phase\n      // nags (Adobe's version-check alert) but show user-phase validation.\n      uiEffects.push(...output.uiEffects.map((effect) => ({ ...effect, phase })));\n      diagnostics.push(...output.diagnostics);\n      if (aggregateOutputSize > budget.maxOutputBytes) {\n        return {\n          kind: 'budget',\n          message: `Form script transaction output exceeded ${budget.maxOutputBytes} bytes`,\n        };\n      }\n      return output.error ?? null;\n    };\n    const remainingBudget = (): ScriptBudget | null => {\n      const remaining = budget.maxExecutionMs - executionMs;\n      return remaining <= 0 ? null : { ...budget, maxExecutionMs: remaining };\n    };\n    const world = (\n      fields: ScriptFieldInput[],\n      event: ScriptWorldInput['event'],\n    ): ScriptWorldInput => ({\n      fields,\n      pageNumber,\n      event,\n    });\n    const run = async (\n      source: string,\n      input: ScriptWorldInput,\n    ): Promise<{ output?: ScriptOutput; error?: ScriptExecutionError }> => {\n      const remaining = remainingBudget();\n      if (!remaining) {\n        return { error: { kind: 'budget', message: 'Form script transaction timed out' } };\n      }\n      let output: ScriptOutput;\n      try {\n        const startedAt = Date.now();\n        output = await txn.run(source, input, remaining);\n        executionMs += Date.now() - startedAt;\n      } catch (error) {\n        return {\n          error: scriptError(error instanceof Error ? error.message : String(error)),\n        };\n      }\n      const error = consume(output, 'user');\n      return error ? { error } : { output };\n    };\n\n    {\n      // Boot runs ONCE per realm (host-owned latch) and can only ever\n      // degrade, never brick — a failure surfaces a diagnostic and this\n      // transaction continues from pristine state.\n      let boot: ScriptOutput | null = null;\n      try {\n        boot = await txn.boot(world(overlay.fields, { kind: 'name-tree-boot' }), budget);\n      } catch (error) {\n        diagnostics.push({\n          code: 'script-error',\n          message: `Document boot script failed (continuing without it): ${error instanceof Error ? error.message : String(error)}`,\n        });\n      }\n      if (boot) {\n        const bootError = consume(boot, 'boot');\n        if (!bootError) applyEffects(overlay, boot.formEffects);\n        else {\n          diagnostics.push({\n            code: 'script-error',\n            message: `Document boot script failed (continuing without it): ${bootError.message}`,\n          });\n        }\n      }\n    }\n\n    const bootEffects = canonicalEffects(overlay);\n\n    if (activation) {\n      let program: string;\n      try {\n        program = javaScriptProgramFromActionTree(activation);\n      } catch (error) {\n        return this.failed(\n          uiEffects,\n          diagnostics,\n          scriptError(error instanceof Error ? error.message : String(error)),\n        );\n      }\n      if (program) {\n        const activated = await run(\n          program,\n          world(overlay.fields, {\n            kind: 'widget-activate',\n            target: ref,\n            source: ref,\n            value: targetInput.value,\n          }),\n        );\n        if (activated.error) return this.failed(uiEffects, diagnostics, activated.error);\n        applyEffects(overlay, activated.output!.formEffects);\n      }\n    }\n\n    if (!activation && hasProposedValue && target.actions?.keystroke && target.family === 'text') {\n      let program: string;\n      try {\n        program = javaScriptProgramFromActionTree(target.actions.keystroke);\n      } catch (error) {\n        return this.failed(\n          uiEffects,\n          diagnostics,\n          scriptError(error instanceof Error ? error.message : String(error)),\n        );\n      }\n      if (program) {\n        // Acrobat fires per-typing keystroke events plus one final commit\n        // event. This pipeline compresses typing into ONE paste-shaped\n        // replacement (Acrobat's own paste contract: the whole string rides\n        // `event.change`, willCommit=false) so transform/filter scripts run,\n        // then fires the Acrobat-faithful willCommit pass (the full value on\n        // `event.value`, empty `change`) so AF* and commit validators see\n        // what Adobe's library expects.\n        const oldValue = String(targetInput.value ?? '');\n        const typing = await run(\n          program,\n          world(overlay.fields, {\n            kind: 'field-keystroke',\n            target: ref,\n            source: ref,\n            value: oldValue,\n            change: String(proposedValue ?? ''),\n            selStart: 0,\n            selEnd: oldValue.length,\n            willCommit: false,\n          }),\n        );\n        if (typing.error && typing.error.kind !== 'exception') {\n          return this.failed(uiEffects, diagnostics, typing.error);\n        }\n        if (typing.error) {\n          // Fault ladder: an exception is not a rejection. Keep the typed\n          // value, surface a diagnostic, and let the transaction continue.\n          diagnostics.push({\n            code: 'script-error',\n            message: `Keystroke script failed (kept the typed value): ${typing.error.message}`,\n          });\n        } else {\n          if (!typing.output!.event.rc) {\n            return this.finishRejected(bootEffects, uiEffects, diagnostics);\n          }\n          applyEffects(overlay, typing.output!.formEffects);\n          const event = typing.output!.event;\n          const base = String(event.value ?? '');\n          proposedValue =\n            base.slice(0, event.selStart) +\n            event.change +\n            base.slice(Math.max(event.selStart, event.selEnd));\n        }\n        const commit = await run(\n          program,\n          world(overlay.fields, {\n            kind: 'field-keystroke',\n            target: ref,\n            source: ref,\n            value: proposedValue,\n            change: '',\n            selStart: 0,\n            selEnd: 0,\n            willCommit: true,\n          }),\n        );\n        if (commit.error && commit.error.kind !== 'exception') {\n          return this.failed(uiEffects, diagnostics, commit.error);\n        }\n        if (commit.error) {\n          diagnostics.push({\n            code: 'script-error',\n            message: `Keystroke commit script failed (kept the typed value): ${commit.error.message}`,\n          });\n        } else {\n          if (!commit.output!.event.rc) {\n            return this.finishRejected(bootEffects, uiEffects, diagnostics);\n          }\n          applyEffects(overlay, commit.output!.formEffects);\n          proposedValue = cloneValue(commit.output!.event.value);\n        }\n      }\n    }\n\n    if (!activation && hasProposedValue) {\n      targetInput.value = cloneValue(proposedValue);\n      overlay.resetKeys.delete(refKey(ref));\n    }\n\n    if (!activation && hasProposedValue && target.actions?.validate) {\n      let program: string;\n      try {\n        program = javaScriptProgramFromActionTree(target.actions.validate);\n      } catch (error) {\n        return this.failed(\n          uiEffects,\n          diagnostics,\n          scriptError(error instanceof Error ? error.message : String(error)),\n        );\n      }\n      if (program) {\n        const validation = await run(\n          program,\n          world(overlay.fields, {\n            kind: 'field-validate',\n            target: ref,\n            source: ref,\n            value: proposedValue,\n            willCommit: true,\n          }),\n        );\n        if (validation.error && validation.error.kind !== 'exception') {\n          return this.failed(uiEffects, diagnostics, validation.error);\n        }\n        if (validation.error) {\n          // Fault ladder: a broken validator must not reject the value.\n          diagnostics.push({\n            code: 'script-error',\n            message: `Validate script failed (accepted the value): ${validation.error.message}`,\n          });\n        } else {\n          if (!validation.output!.event.rc) {\n            return this.finishRejected(bootEffects, uiEffects, diagnostics);\n          }\n          targetInput.value = cloneValue(validation.output!.event.value);\n          applyEffects(overlay, validation.output!.formEffects);\n        }\n      }\n    }\n\n    const formatRefs: FormFieldRef[] = !activation && hasProposedValue ? [ref] : [];\n    for (const calculationRef of activation ? [] : snapshot.calculationOrder) {\n      if (!calculationRef) continue;\n      const calculated = snapshotField(snapshot, calculationRef);\n      const tree = calculated?.actions?.calculate;\n      if (!calculated || !tree) continue;\n      let program: string;\n      try {\n        program = javaScriptProgramFromActionTree(tree);\n      } catch (error) {\n        return this.failed(\n          uiEffects,\n          diagnostics,\n          scriptError(error instanceof Error ? error.message : String(error)),\n        );\n      }\n      const calculatedInput = fieldByRef(overlay.fields, calculationRef);\n      if (program && calculatedInput) {\n        const calculation = await run(\n          program,\n          world(overlay.fields, {\n            kind: 'field-calculate',\n            target: calculationRef,\n            ...(hasProposedValue ? { source: ref } : {}),\n            value: calculatedInput.value,\n          }),\n        );\n        if (calculation.error && calculation.error.kind !== 'exception') {\n          return this.failed(uiEffects, diagnostics, calculation.error);\n        }\n        if (calculation.error) {\n          // Fault ladder: this field's calculation is skipped; the /CO chain continues.\n          diagnostics.push({\n            code: 'script-error',\n            message: `Calculate script failed (field left unchanged): ${calculation.error.message}`,\n          });\n        } else {\n          applyEffects(overlay, calculation.output!.formEffects);\n        }\n      }\n      if (!formatRefs.some((candidate) => sameRef(candidate, calculationRef))) {\n        formatRefs.push(calculationRef);\n      }\n    }\n\n    for (const formatRef of formatRefs) {\n      const field = snapshotField(snapshot, formatRef);\n      const tree = field?.actions?.format;\n      const overlayField = fieldByRef(overlay.fields, formatRef);\n      if (!field || !tree || !overlayField) continue;\n      let program: string;\n      try {\n        program = javaScriptProgramFromActionTree(tree);\n      } catch (error) {\n        return this.failed(\n          uiEffects,\n          diagnostics,\n          scriptError(error instanceof Error ? error.message : String(error)),\n        );\n      }\n      if (!program) continue;\n      const format = await run(\n        program,\n        world(overlay.fields, {\n          kind: 'field-format',\n          target: formatRef,\n          ...(hasProposedValue ? { source: ref } : {}),\n          value: overlayField.value,\n        }),\n      );\n      if (format.error && format.error.kind !== 'exception') {\n        return this.failed(uiEffects, diagnostics, format.error);\n      }\n      if (format.error) {\n        // Fault ladder: formatting is cosmetic — skip it, keep the raw value.\n        diagnostics.push({\n          code: 'script-error',\n          message: `Format script failed (kept the raw value): ${format.error.message}`,\n        });\n        continue;\n      }\n      applyEffects(overlay, format.output!.formEffects);\n    }\n\n    const effects = canonicalEffects(overlay);\n    if (effects.length + uiEffects.length > budget.maxEffects) {\n      return this.failed(uiEffects, diagnostics, {\n        kind: 'budget',\n        message: `Form script transaction exceeded ${budget.maxEffects} effects`,\n      });\n    }\n    if (effects.length === 0) {\n      return { status: 'unchanged', scripted: true, effectsResult: null, uiEffects, diagnostics };\n    }\n    if (!this.options.doc.forms.applyEffects) {\n      return this.failed(\n        uiEffects,\n        diagnostics,\n        scriptError('This engine does not support batched form effects'),\n      );\n    }\n\n    const effectsResult = await this.options.doc.forms.applyEffects(effects);\n    const status = statusFromEffects(effectsResult);\n    return {\n      status,\n      scripted: true,\n      effectsResult,\n      uiEffects,\n      diagnostics,\n      ...(status === 'failed'\n        ? { error: scriptError('One or more native form effects failed') }\n        : {}),\n    };\n  }\n\n  private failed(\n    uiEffects: FormUiEffect[],\n    diagnostics: ScriptDiagnostic[],\n    error: ScriptExecutionError,\n  ): FormCommitResult {\n    return {\n      status: 'failed',\n      scripted: true,\n      effectsResult: null,\n      uiEffects,\n      diagnostics,\n      error,\n    };\n  }\n\n  private async finishRejected(\n    bootEffects: FormEffect[],\n    uiEffects: FormUiEffect[],\n    diagnostics: ScriptDiagnostic[],\n  ): Promise<FormCommitResult> {\n    if (bootEffects.length === 0) {\n      return {\n        status: 'rejected',\n        scripted: true,\n        effectsResult: null,\n        uiEffects,\n        diagnostics,\n      };\n    }\n    if (!this.options.doc.forms.applyEffects) {\n      return this.failed(\n        uiEffects,\n        diagnostics,\n        scriptError('Batched form effects are unavailable'),\n      );\n    }\n    const effectsResult = await this.options.doc.forms.applyEffects(bootEffects);\n    if (statusFromEffects(effectsResult) === 'failed') {\n      return this.failed(uiEffects, diagnostics, scriptError('A name-tree boot effect failed'));\n    }\n    return {\n      status: 'rejected',\n      scripted: true,\n      effectsResult,\n      uiEffects,\n      diagnostics,\n    };\n  }\n}\n\nexport function createFormScriptingController(\n  options: FormScriptingControllerOptions,\n): FormScriptingController {\n  return new FormScriptingController(options);\n}\n"],"mappings":"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"}

package/dist/scripting.d.cts

@@ -0,0 +1,47 @@
+import { r as FormCommitResult } from "./types-CnUW7z1W.cjs";
+import { DocumentMeta } from "@embedpdf/core";
+import { DocumentHandle, FormFieldRef, FormFieldValue, PdfActionTree } from "@embedpdf/engine-core/runtime";
+import { ScriptBudget, ScriptTransaction } from "@embedpdf/core-acrojs";
+//#region src/scripting.d.ts
+/**
+ * The controller never owns a realm. It rides a realm PORT — this document's
+ * own (the actions plugin's per-document host) or a detached one minted by
+ * the actions plugin for a document that is not displayed (stamp's
+ * asset documents). Either way the owner disposes the realm; `dispose()`
+ * here only fences further transactions.
+ */
+interface FormScriptingControllerOptions {
+  doc: DocumentHandle;
+  document(): DocumentMeta | null;
+  /** The realm's transaction port ({@link ScriptTransaction}). The K/V/C/F
+   *  pipeline runs WHOLLY inside one transaction: snapshot fetch, every
+   *  pass, and the engine commit — the commit-inside-the-boundary law. */
+  transaction<T>(body: (txn: ScriptTransaction) => Promise<T>): Promise<T>;
+  /** The transaction aggregate (output bytes, wall-clock across passes);
+   *  the realm owner hands over the same budget its runs enforce. */
+  budget?: ScriptBudget;
+}
+declare class FormScriptingController {
+  private readonly options;
+  private disposed;
+  private readonly transaction;
+  private readonly transactionBudget;
+  constructor(options: FormScriptingControllerOptions);
+  /** The realm belongs to its OWNER (the actions plugin, or the caller that
+   *  minted a detached one) — this only fences further transactions. */
+  dispose(): void;
+  commit(ref: FormFieldRef, proposed: FormFieldValue): Promise<FormCommitResult>;
+  /** Execute one originating widget's activation action (`/A`, including `/Next`). */
+  activate(ref: FormFieldRef, action: PdfActionTree): Promise<FormCommitResult>;
+  /** Run lazy document boot plus the `/CO` chain without a user field change.
+   *  The anchor field resolves INSIDE the transaction (undefined ref). */
+  recalculate(): Promise<FormCommitResult>;
+  private transact;
+  private transactBody;
+  private failed;
+  private finishRejected;
+}
+declare function createFormScriptingController(options: FormScriptingControllerOptions): FormScriptingController;
+//#endregion
+export { FormScriptingController, FormScriptingControllerOptions, createFormScriptingController };
+//# sourceMappingURL=scripting.d.cts.map

package/dist/scripting.d.ts

@@ -0,0 +1,47 @@
+import { r as FormCommitResult } from "./types-NGRZjJNj.js";
+import { DocumentMeta } from "@embedpdf/core";
+import { DocumentHandle, FormFieldRef, FormFieldValue, PdfActionTree } from "@embedpdf/engine-core/runtime";
+import { ScriptBudget, ScriptTransaction } from "@embedpdf/core-acrojs";
+//#region src/scripting.d.ts
+/**
+ * The controller never owns a realm. It rides a realm PORT — this document's
+ * own (the actions plugin's per-document host) or a detached one minted by
+ * the actions plugin for a document that is not displayed (stamp's
+ * asset documents). Either way the owner disposes the realm; `dispose()`
+ * here only fences further transactions.
+ */
+interface FormScriptingControllerOptions {
+  doc: DocumentHandle;
+  document(): DocumentMeta | null;
+  /** The realm's transaction port ({@link ScriptTransaction}). The K/V/C/F
+   *  pipeline runs WHOLLY inside one transaction: snapshot fetch, every
+   *  pass, and the engine commit — the commit-inside-the-boundary law. */
+  transaction<T>(body: (txn: ScriptTransaction) => Promise<T>): Promise<T>;
+  /** The transaction aggregate (output bytes, wall-clock across passes);
+   *  the realm owner hands over the same budget its runs enforce. */
+  budget?: ScriptBudget;
+}
+declare class FormScriptingController {
+  private readonly options;
+  private disposed;
+  private readonly transaction;
+  private readonly transactionBudget;
+  constructor(options: FormScriptingControllerOptions);
+  /** The realm belongs to its OWNER (the actions plugin, or the caller that
+   *  minted a detached one) — this only fences further transactions. */
+  dispose(): void;
+  commit(ref: FormFieldRef, proposed: FormFieldValue): Promise<FormCommitResult>;
+  /** Execute one originating widget's activation action (`/A`, including `/Next`). */
+  activate(ref: FormFieldRef, action: PdfActionTree): Promise<FormCommitResult>;
+  /** Run lazy document boot plus the `/CO` chain without a user field change.
+   *  The anchor field resolves INSIDE the transaction (undefined ref). */
+  recalculate(): Promise<FormCommitResult>;
+  private transact;
+  private transactBody;
+  private failed;
+  private finishRejected;
+}
+declare function createFormScriptingController(options: FormScriptingControllerOptions): FormScriptingController;
+//#endregion
+export { FormScriptingController, FormScriptingControllerOptions, createFormScriptingController };
+//# sourceMappingURL=scripting.d.ts.map