@embedpdf/plugin-form 3.0.0-next.1 → 3.0.0-next.11

package/dist/index.js

@@ -1,8 +1,104 @@
-import { createCapabilityToken, definePlugin } from "@embedpdf/core";
-import { AnnotationToken, MIN_DRAG, resolveClickPlacement, widgetAppearanceFromProps } from "@embedpdf/plugin-annotation";
-import { AnnotationToken as AnnotationToken$1 } from "@embedpdf/plugin-annotation/internal";
-import { InteractionToken, samplePointOn } from "@embedpdf/plugin-interaction";
-import { DEFAULT_SCRIPT_BUDGET, javaScriptProgramFromActionTree, scriptFieldsFromSnapshot } from "@embedpdf/core-acrojs";
+import { FormScriptingController, createFormScriptingController } from "./scripting.js";
+import { t as FormToken$1 } from "./types-DkQmmcTG.js";
+import { FormToken } from "./contract.js";
+import { createSerialQueue, definePlugin } from "@embedpdf/core";
+import { ActionsToken, createHoverPump } from "@embedpdf/plugin-actions/contract";
+import { ActionsToken as ActionsToken$1 } from "@embedpdf/plugin-actions/contract/host";
+import { AnnotationToken } from "@embedpdf/plugin-annotation/contract";
+import { AnnotationToken as AnnotationToken$1 } from "@embedpdf/plugin-annotation/contract/host";
+import { InteractionToken, samplePointOn } from "@embedpdf/plugin-interaction/contract";
+import { PermissionDenied } from "@embedpdf/engine-core/runtime";
+import { MIN_DRAG, resolveClickPlacement, widgetAppearanceFromProps } from "@embedpdf/plugin-annotation/authoring";
+//#region src/field-selection.ts
+/**
+* ISO field selection, written ONCE for ResetForm (Tables 241/242) and
+* SubmitForm (Tables 239/240): a NAME target selects the field AND its
+* descendants (FQN dot-prefix — `parent` selects `parent.c1`, the rule the
+* old exact-match resolution violated); an objectNumber target selects that
+* field dictionary. Include mode keeps the selection; exclude mode keeps
+* the complement (a name excludes its subtree the same way it includes
+* it). `targets === null` (the key ABSENT) selects everything and the flag
+* is ignored; `[]` + include selects NOTHING while `[]` + exclude selects
+* everything — presence and emptiness are different states.
+*
+* `listed` reports whether a field was ADDRESSED by the target list
+* (directly or through its subtree) — the "explicitly listed" predicate the
+* submit honesty diagnostics key on.
+*/
+const resolveFieldSelection = (all, targets, exclude) => {
+	if (targets === null) return {
+		selected: [...all],
+		listed: () => false
+	};
+	const names = targets.filter((t) => t.kind === "name").map((t) => t.name);
+	const objectNumbers = new Set(targets.filter((t) => t.kind === "objectNumber").map((t) => t.objectNumber));
+	const listed = (field) => field.ref.kind === "objectNumber" && objectNumbers.has(field.ref.fieldObjectNumber) || names.some((name) => field.name === name || field.name.startsWith(`${name}.`));
+	return {
+		selected: exclude ? all.filter((f) => !listed(f)) : all.filter(listed),
+		listed
+	};
+};
+/**
+* Build the resolved submission dataset from a live field list (Tables
+* 239/240 semantics; pure — the capability supplies a FRESH engine read so
+* no model-lag class exists):
+*
+* - the unconditional **NoExport veto** — even an explicit include cannot
+*   override it (diagnosed when explicitly listed, so the veto is
+*   observable, silent when swept in implicitly);
+* - **push-buttons and signatures** never contribute entries in v1 —
+*   ISO's explicit-pushbutton-`/AP`-in-FDF rule is unrepresentable in the
+*   current DTO, so an EXPLICITLY listed one is diagnosed
+*   (`submit-entry-unsupported`), never silently dropped;
+* - an **unsupported `/V` shape** is always diagnosed (silent omission
+*   would be data loss);
+* - a valueless field becomes a NAME-ONLY entry (`value: null`) only under
+*   IncludeNoValueFields, else it is skipped (the ISO default);
+* - values are entry-faithful: scalar → string, array (multi-select list
+*   box) → string[]; the submitted name is the fully qualified name.
+*/
+const buildSubmitEntries = (fields, intent, diagnose) => {
+	const { selected, listed } = resolveFieldSelection(fields, intent.fields, intent.exclude);
+	const explicitInclude = intent.fields !== null && !intent.exclude;
+	const entries = [];
+	for (const field of selected) {
+		const explicit = explicitInclude && listed(field);
+		if (field.family === "pushbutton" || field.family === "signature") {
+			if (explicit) diagnose({
+				code: "submit-entry-unsupported",
+				message: `submit: '${field.name}' (${field.family}) has no representable submission value in v1 — skipped`
+			});
+			continue;
+		}
+		if (field.flags.noExport) {
+			if (explicit) diagnose({
+				code: "submit-entry-unsupported",
+				message: `submit: '${field.name}' carries the NoExport flag — the veto is unconditional (ISO 12.7.6.2), skipped`
+			});
+			continue;
+		}
+		const entry = field.valueEntry;
+		if (entry.kind === "scalar") entries.push({
+			name: field.name,
+			value: entry.value
+		});
+		else if (entry.kind === "array") entries.push({
+			name: field.name,
+			value: entry.values
+		});
+		else if (entry.kind === "none") {
+			if (intent.includeNoValueFields) entries.push({
+				name: field.name,
+				value: null
+			});
+		} else diagnose({
+			code: "submit-entry-unsupported",
+			message: `submit: '${field.name}' has an unsupported /V shape — skipped (would otherwise be silent data loss)`
+		});
+	}
+	return entries;
+};
+//#endregion
 //#region src/core/model.ts
 const fieldKeyOf = (field) => field.fieldObjectNumber > 0 ? `obj:${field.fieldObjectNumber}` : `fqn:${field.name}`;
 const initialModel = () => ({
@@ -216,507 +312,8 @@ function fillItemForWidget(model, annotObjectNumber) {
 }
 //#endregion
 //#region src/mutationQueue.ts
-/** Small promise-tail queue: failures never poison later mutations. */
-function createSerialMutationQueue() {
-	let tail = Promise.resolve();
-	return (operation) => {
-		const result = tail.then(operation, operation);
-		tail = result.then(() => void 0, () => void 0);
-		return result;
-	};
-}
-//#endregion
-//#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 seedFrom(documentId, sequence) {
-	let hash = 2166136261;
-	for (const char of `${documentId}:${sequence}`) {
-		hash ^= char.charCodeAt(0);
-		hash = Math.imul(hash, 16777619);
-	}
-	return hash >>> 0;
-}
-function resolvedIdentity(doc, config) {
-	const claims = doc.security.identity;
-	const supplied = typeof config.identity === "function" ? config.identity() : config.identity ?? {};
-	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 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.sandboxPromise = null;
-		this.booted = false;
-		this.disposed = false;
-		this.sequence = 0;
-	}
-	dispose() {
-		if (this.disposed) return;
-		this.disposed = true;
-		this.sandboxPromise?.then((sandbox) => sandbox.dispose()).catch(() => void 0);
-	}
-	async commit(snapshot, ref, proposed) {
-		return this.transact(snapshot, ref, proposed);
-	}
-	/** Execute one originating widget's activation action (`/A`, including `/Next`). */
-	async activate(snapshot, ref, action) {
-		return this.transact(snapshot, ref, void 0, action);
-	}
-	/** Run lazy document boot plus the `/CO` chain without a user field change. */
-	async recalculate(snapshot) {
-		const target = snapshot.calculationOrder.find((ref) => ref !== null && snapshotField(snapshot, ref) !== void 0) ?? snapshot.fields[0]?.ref;
-		if (!target) return {
-			status: "unchanged",
-			scripted: true,
-			effectsResult: null,
-			uiEffects: [],
-			diagnostics: []
-		};
-		return this.transact(snapshot, target);
-	}
-	async transact(snapshot, ref, proposed, activation) {
-		if (this.disposed) throw new Error("Form scripting controller is disposed");
-		const target = snapshotField(snapshot, ref);
-		if (!target) return this.failed([], [], scriptError(`Form field '${refKey(ref)}' no longer exists`));
-		const original = 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 meta = this.options.document();
-		const nowMs = this.options.config.now?.() ?? Date.now();
-		const inputBase = {
-			document: {
-				id: this.options.doc.id,
-				fileName: this.options.config.fileName?.() ?? meta?.name ?? this.options.doc.id,
-				pageCount: meta?.pageCount ?? 0,
-				pageNumber: pageNumberFor(meta, target)
-			},
-			identity: resolvedIdentity(this.options.doc, this.options.config),
-			environment: {
-				nowMs,
-				utcOffsetMinutes: this.options.config.utcOffsetMinutes?.() ?? -new Date(nowMs).getTimezoneOffset(),
-				randomSeed: this.options.config.randomSeed?.() ?? seedFrom(this.options.doc.id, this.sequence++)
-			}
-		};
-		const budget = this.options.config.budget ?? 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 run = async (kind, source, input) => {
-			const remaining = remainingBudget();
-			if (!remaining) return { error: {
-				kind: "budget",
-				message: "Form script transaction timed out"
-			} };
-			let output;
-			try {
-				const sandbox = await this.sandbox();
-				const startedAt = Date.now();
-				output = kind === "boot" ? sandbox.boot(source, input, remaining) : sandbox.run(source, input, remaining);
-				executionMs += Date.now() - startedAt;
-			} catch (error) {
-				return { error: scriptError(error instanceof Error ? error.message : String(error)) };
-			}
-			const error = consume(output, kind === "boot" ? "boot" : "user");
-			return error ? { error } : { output };
-		};
-		if (!this.booted) {
-			this.booted = true;
-			let sources = [];
-			let bootError = null;
-			try {
-				sources = (this.options.doc.actions ? await this.options.doc.actions.read() : null)?.nameTreeScripts.map(({ action }) => javaScriptProgramFromActionTree(action)) ?? [];
-			} catch (error) {
-				bootError = scriptError(error instanceof Error ? error.message : String(error));
-			}
-			if (!bootError && sources.length > 0) {
-				const boot = await run("boot", sources, {
-					...inputBase,
-					fields: overlay.fields,
-					event: { kind: "name-tree-boot" }
-				});
-				if (boot.error) bootError = boot.error;
-				else applyEffects(overlay, boot.output.formEffects);
-			}
-			if (bootError) 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 = javaScriptProgramFromActionTree(activation);
-			} catch (error) {
-				return this.failed(uiEffects, diagnostics, scriptError(error instanceof Error ? error.message : String(error)));
-			}
-			if (program) {
-				const activated = await run("run", program, {
-					...inputBase,
-					fields: overlay.fields,
-					event: {
-						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 = 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 key = await run("run", program, {
-					...inputBase,
-					fields: overlay.fields,
-					event: {
-						kind: "field-keystroke",
-						target: ref,
-						source: ref,
-						value: oldValue,
-						change: String(proposedValue ?? ""),
-						selStart: 0,
-						selEnd: oldValue.length,
-						willCommit: true
-					}
-				});
-				if (key.error) return this.failed(uiEffects, diagnostics, key.error);
-				if (!key.output.event.rc) return this.finishRejected(bootEffects, uiEffects, diagnostics);
-				applyEffects(overlay, key.output.formEffects);
-				const event = key.output.event;
-				const base = String(event.value ?? "");
-				proposedValue = base.slice(0, event.selStart) + event.change + base.slice(Math.max(event.selStart, event.selEnd));
-			}
-		}
-		if (!activation && hasProposedValue) {
-			targetInput.value = cloneValue(proposedValue);
-			overlay.resetKeys.delete(refKey(ref));
-		}
-		if (!activation && hasProposedValue && target.actions?.validate) {
-			let program;
-			try {
-				program = 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("run", program, {
-					...inputBase,
-					fields: overlay.fields,
-					event: {
-						kind: "field-validate",
-						target: ref,
-						source: ref,
-						value: proposedValue,
-						willCommit: true
-					}
-				});
-				if (validation.error) return this.failed(uiEffects, diagnostics, validation.error);
-				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 = 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("run", program, {
-					...inputBase,
-					fields: overlay.fields,
-					event: {
-						kind: "field-calculate",
-						target: calculationRef,
-						...hasProposedValue ? { source: ref } : {},
-						value: calculatedInput.value
-					}
-				});
-				if (calculation.error) return this.failed(uiEffects, diagnostics, calculation.error);
-				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 = javaScriptProgramFromActionTree(tree);
-			} catch (error) {
-				return this.failed(uiEffects, diagnostics, scriptError(error instanceof Error ? error.message : String(error)));
-			}
-			if (!program) continue;
-			const format = await run("run", program, {
-				...inputBase,
-				fields: overlay.fields,
-				event: {
-					kind: "field-format",
-					target: formatRef,
-					...hasProposedValue ? { source: ref } : {},
-					value: overlayField.value
-				}
-			});
-			if (format.error) return this.failed(uiEffects, diagnostics, format.error);
-			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") } : {}
-		};
-	}
-	async sandbox() {
-		this.sandboxPromise ?? (this.sandboxPromise = this.options.sandboxFactory().then((sandbox) => {
-			if (this.disposed) sandbox.dispose();
-			return sandbox;
-		}));
-		return this.sandboxPromise;
-	}
-	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);
-}
+/** The core serial queue under its historical form-plugin name. */
+const createSerialMutationQueue = createSerialQueue;
 //#endregion
 //#region src/capability.ts
 /** PDF user-space rect (y-up) → content-space box (y-down, crop-relative). */
@@ -756,34 +353,36 @@ function createFormCapability(ctx, options = {}) {
 		};
 	};
 	const enqueueMutation = createSerialMutationQueue();
-	const scripting = options.scripting?.enabled && ctx.doc ? createFormScriptingController({
+	const actionsHost = ctx.tryGet(ActionsToken$1);
+	const scriptPort = actionsHost?.scriptTransaction?.bind(actionsHost) ?? null;
+	const scripting = scriptPort && ctx.doc ? createFormScriptingController({
 		doc: ctx.doc,
 		document: () => ctx.document(),
-		config: options.scripting,
-		sandboxFactory: options.scripting.sandboxFactory ?? (() => import("@embedpdf/core-js-sandbox").then(({ createQuickJsSandbox }) => createQuickJsSandbox()))
+		transaction: scriptPort
 	}) : null;
 	if (scripting) ctx.cleanup(() => scripting.dispose());
-	let uiEffectProvider = null;
-	const surfaceScriptingResult = (result) => {
-		const observe = (callback) => {
-			if (!callback) return;
-			try {
-				callback();
-			} catch (error) {
-				globalThis.console?.error("[form] scripting observer failed:", error);
-			}
-		};
-		for (const effect of result.uiEffects) {
-			observe(options.scripting?.onUiEffect ? () => options.scripting.onUiEffect(effect) : void 0);
-			observe(uiEffectProvider ? () => uiEffectProvider(effect) : void 0);
+	/** Every script surface (UI effects, diagnostics, errors) flows through
+	*  the actions plugin's ONE port — origin/phase attached (D9). */
+	const surfaceViaActions = (result, origin) => {
+		if (!actionsHost) return;
+		for (const phase of ["boot", "user"]) {
+			const uiEffects = result.uiEffects.filter((effect) => effect.phase === phase);
+			if (uiEffects.length === 0 && phase === "boot") continue;
+			actionsHost.surfaceScriptResult({
+				uiEffects,
+				diagnostics: phase === "user" ? result.diagnostics : [],
+				...phase === "user" && result.error ? { error: result.error } : {},
+				origin,
+				phase
+			});
 		}
-		for (const diagnostic of result.diagnostics) observe(options.scripting?.onDiagnostic ? () => options.scripting.onDiagnostic(diagnostic) : void 0);
-		if (result.error) observe(options.scripting?.onError ? () => options.scripting.onError(result.error) : void 0);
 	};
+	const can = (cap) => ctx.doc?.security.allows(cap) ?? false;
 	let refreshPromise = null;
 	const refresh = async (force = false) => {
 		const doc = ctx.doc;
 		if (!doc) return;
+		if (!can("doc.forms.read")) return;
 		if (refreshPromise) {
 			await refreshPromise;
 			if (!force) return;
@@ -791,7 +390,9 @@ function createFormCapability(ctx, options = {}) {
 		refreshPromise = doc.forms.list().then((snapshot) => apply({
 			t: "snapshot",
 			snapshot
-		})).finally(() => {
+		})).catch((err) => {
+			console.warn("[form] form snapshot failed to load", err);
+		}).finally(() => {
 			refreshPromise = null;
 		});
 		return refreshPromise;
@@ -819,14 +420,20 @@ function createFormCapability(ctx, options = {}) {
 			geomLoading.delete(pon);
 		});
 	};
+	const fuseFill = (item, fillable) => item === null || fillable || item.disabled ? item : {
+		...item,
+		disabled: true
+	};
 	const fillCache = /* @__PURE__ */ new Map();
 	const fillItems$1 = (pon) => {
 		const m = model();
+		const fillable = can("doc.forms.fill");
 		const hit = fillCache.get(pon);
-		if (hit && hit.seq === m.seq) return hit.items;
-		const items = fillItems(m, pon);
+		if (hit && hit.seq === m.seq && hit.fillable === fillable) return hit.items;
+		const items = fillItems(m, pon).map((item) => fuseFill(item, fillable));
 		fillCache.set(pon, {
 			seq: m.seq,
+			fillable,
 			items
 		});
 		return items;
@@ -834,11 +441,13 @@ function createFormCapability(ctx, options = {}) {
 	const fillItemCache = /* @__PURE__ */ new Map();
 	const fillItem = (annotObjectNumber) => {
 		const m = model();
+		const fillable = can("doc.forms.fill");
 		const hit = fillItemCache.get(annotObjectNumber);
-		if (hit && hit.seq === m.seq) return hit.item;
-		const item = fillItemForWidget(m, annotObjectNumber);
+		if (hit && hit.seq === m.seq && hit.fillable === fillable) return hit.item;
+		const item = fuseFill(fillItemForWidget(m, annotObjectNumber), fillable);
 		fillItemCache.set(annotObjectNumber, {
 			seq: m.seq,
+			fillable,
 			item
 		});
 		return item;
@@ -847,8 +456,8 @@ function createFormCapability(ctx, options = {}) {
 		const doc = ctx.doc;
 		if (!doc) throw new Error("no document");
 		if (scripting) {
-			const result = await scripting.commit(await doc.forms.list(), ref, value);
-			surfaceScriptingResult(result);
+			const result = await scripting.commit(ref, value);
+			surfaceViaActions(result, "user");
 			if (result.effectsResult !== null) await refresh(true);
 			return result;
 		}
@@ -862,31 +471,33 @@ function createFormCapability(ctx, options = {}) {
 			diagnostics: []
 		};
 	};
-	const write = (key, value) => enqueueMutation(async () => {
-		if (!ctx.doc) return;
-		apply({
-			t: "writeStart",
-			key
-		});
-		try {
-			const result = await commitValueNow(refKeyOf(key), value);
-			if (result.status === "rejected" || result.status === "failed") apply({
-				t: "writeFailed",
-				key
-			});
-			else if (result.effectsResult === null && result.scripted) apply({
-				t: "writeFailed",
-				key
-			});
-		} catch (err) {
+	const write = (key, value) => {
+		if (!can("doc.forms.fill")) return Promise.reject(new PermissionDenied("doc.forms.fill", "form.fill"));
+		return enqueueMutation(async () => {
+			if (!ctx.doc) return;
 			apply({
-				t: "writeFailed",
+				t: "writeStart",
 				key
 			});
-			throw err;
-		}
-	});
-	const can = (cap) => ctx.doc?.security.allows(cap) ?? false;
+			try {
+				const result = await commitValueNow(refKeyOf(key), value);
+				if (result.status === "rejected" || result.status === "failed") apply({
+					t: "writeFailed",
+					key
+				});
+				else if (result.effectsResult === null && result.scripted) apply({
+					t: "writeFailed",
+					key
+				});
+			} catch (err) {
+				apply({
+					t: "writeFailed",
+					key
+				});
+				throw err;
+			}
+		});
+	};
 	const annotationHost = ctx.tryGet(AnnotationToken$1);
 	const annotationActivation = async (ref) => {
 		const doc = ctx.doc;
@@ -898,8 +509,7 @@ function createFormCapability(ctx, options = {}) {
 		return annotation?.subtype === "widget" ? annotation.actions?.activate ?? null : null;
 	};
 	const activateWidgetNow = async (key, annotationRef) => {
-		const doc = ctx.doc;
-		if (!doc) throw new Error("no document");
+		if (!ctx.doc) throw new Error("no document");
 		if (!scripting) return {
 			status: "unchanged",
 			scripted: false,
@@ -915,11 +525,118 @@ function createFormCapability(ctx, options = {}) {
 			uiEffects: [],
 			diagnostics: []
 		};
-		const result = await scripting.activate(await doc.forms.list(), refKeyOf(key), action);
-		surfaceScriptingResult(result);
+		const result = await scripting.activate(refKeyOf(key), action);
+		surfaceViaActions(result, "user");
 		if (result.effectsResult !== null) await refresh(true);
 		return result;
 	};
+	const NOT_SCRIPTED = {
+		status: "unchanged",
+		scripted: false,
+		effectsResult: null,
+		uiEffects: [],
+		diagnostics: []
+	};
+	/**
+	* The shared reset core: one effects batch → refresh → V/C/F
+	* recalculation when the transaction port is present. Ridden by BOTH
+	* doors — the /ResetForm executor and the public `reset(key)` — so the
+	* two can never diverge again (the "reset() asymmetry" fix). `origin` is
+	* PRESERVED through recalculation surfacing: a lifecycle/hover ResetForm
+	* can no longer launder its alerts into user origin.
+	*/
+	const applyResetBatch = async (refs, origin) => {
+		const doc = ctx.doc;
+		if (!doc) throw new Error("no document");
+		if (!doc.forms.applyEffects) {
+			const result = {
+				...NOT_SCRIPTED,
+				diagnostics: [{
+					code: "unsupported-api",
+					message: "this engine has no form-effects batch door"
+				}]
+			};
+			surfaceViaActions(result, origin);
+			return result;
+		}
+		if (refs.length === 0) return NOT_SCRIPTED;
+		const effectsResult = await doc.forms.applyEffects([{
+			kind: "reset",
+			refs
+		}]);
+		const resetFailed = effectsResult.results.some((entry) => entry.status === "failed" || entry.status === "rejected");
+		await refresh(true);
+		if (resetFailed) return {
+			status: "failed",
+			scripted: false,
+			effectsResult,
+			uiEffects: [],
+			diagnostics: []
+		};
+		let recalc = null;
+		if (scripting) {
+			recalc = await scripting.recalculate();
+			surfaceViaActions(recalc, origin);
+			if (recalc.effectsResult !== null) await refresh(true);
+		}
+		return {
+			status: "applied",
+			scripted: recalc !== null,
+			effectsResult,
+			uiEffects: recalc?.uiEffects ?? [],
+			diagnostics: recalc?.diagnostics ?? [],
+			...recalc?.error ? { error: recalc.error } : {}
+		};
+	};
+	const resetFormAction = (targets, exclude, origin = "user") => enqueueMutation(async () => {
+		const doc = ctx.doc;
+		if (!doc) throw new Error("no document");
+		const { selected } = resolveFieldSelection((await doc.forms.list()).fields, targets, exclude);
+		const resettable = selected.filter((f) => f.family !== "pushbutton" && f.family !== "signature");
+		return applyResetBatch(resettable.map((f) => f.ref), origin);
+	});
+	/**
+	* The submit dataset resolver (Phase 4, D7): a FRESH engine read — never
+	* the cached model, so no staleness class exists — then the pure ISO
+	* builder. Selection/veto/value semantics live in `field-selection.ts`;
+	* this door only supplies the live fields and assembles the request.
+	*/
+	const resolveSubmitDataset = async (intent, actionCtx, diagnose) => {
+		const doc = ctx.doc;
+		if (!doc) throw new Error("no document");
+		const snapshot = await doc.forms.list();
+		return {
+			url: intent.url,
+			method: intent.method,
+			format: intent.format,
+			flagsRaw: intent.flagsRaw,
+			...intent.charSet === void 0 ? {} : { charSet: intent.charSet },
+			entries: buildSubmitEntries(snapshot.fields, intent, diagnose),
+			origin: actionCtx.origin,
+			event: actionCtx.event
+		};
+	};
+	const widgetSource = (key, annotationRef) => ({
+		kind: "widget",
+		field: refKeyOf(key),
+		annotation: annotationRef,
+		pon: annotationRef.pageObjectNumber
+	});
+	/** One shared hover pump (Exit→Enter as one ordered pair; intermediates
+	*  skipped), created on first use against the resolved actions capability. */
+	let widgetPump = null;
+	const widgetHoverPump = (actions) => {
+		widgetPump ?? (widgetPump = createHoverPump(actions.dispatch));
+		return widgetPump;
+	};
+	const widgetHoverFlags = (annotationRef) => {
+		const loaded = annotationHost?.get(annotationRef);
+		if (loaded?.subtype !== "widget") return null;
+		return {
+			enter: Boolean(loaded.actions?.cursorEnter?.root),
+			exit: Boolean(loaded.actions?.cursorExit?.root)
+		};
+	};
 	const nudgeAnnotations = (pons) => {
 		if (!annotationHost) return;
 		for (const pon of new Set(pons)) annotationHost.reloadPage(pon);
@@ -1063,32 +780,137 @@ function createFormCapability(ctx, options = {}) {
 			type: "choice",
 			values
 		}),
-		reset: (key) => enqueueMutation(async () => {
-			const doc = ctx.doc;
-			if (!doc) return;
-			apply({
-				t: "writeStart",
-				key
-			});
-			try {
-				const result = await doc.forms.reset(refKeyOf(key));
+		reset: (key) => {
+			if (!can("doc.forms.fill")) return Promise.reject(new PermissionDenied("doc.forms.fill", "form.reset"));
+			return enqueueMutation(async () => {
+				const doc = ctx.doc;
+				if (!doc) return;
 				apply({
-					t: "writeDone",
-					key,
-					field: result.field
-				});
-			} catch (err) {
-				apply({
-					t: "writeFailed",
+					t: "writeStart",
 					key
 				});
-				throw err;
-			}
-		}),
+				try {
+					if (doc.forms.applyEffects) {
+						const result = await applyResetBatch([refKeyOf(key)], "user");
+						if (result.status === "failed") throw new Error(result.effectsResult?.results.find((entry) => entry.status === "failed" || entry.status === "rejected")?.error?.message ?? "reset failed");
+						const field = fieldByKey(model(), key);
+						if (field) apply({
+							t: "writeDone",
+							key,
+							field
+						});
+						else apply({
+							t: "writeFailed",
+							key
+						});
+					} else {
+						const result = await doc.forms.reset(refKeyOf(key));
+						apply({
+							t: "writeDone",
+							key,
+							field: result.field
+						});
+					}
+				} catch (err) {
+					apply({
+						t: "writeFailed",
+						key
+					});
+					throw err;
+				}
+			});
+		},
 		commitValue: (ref, value) => enqueueMutation(() => commitValueNow(ref, value)),
-		activateWidget: (key, annotationRef) => enqueueMutation(() => activateWidgetNow(key, annotationRef)),
-		setUiEffectProvider: (provider) => {
-			uiEffectProvider = provider;
+		activateWidget: async (key, annotationRef) => {
+			const actions = ctx.tryGet(ActionsToken);
+			if (actions) {
+				const result = await actions.dispatch({
+					scope: "activate",
+					ref: annotationRef,
+					pon: annotationRef.pageObjectNumber,
+					source: widgetSource(key, annotationRef)
+				});
+				if (!(result.status === "inert" && result.steps.length === 0 && result.diagnostics.length === 0)) return {
+					kind: "dispatched",
+					result
+				};
+			}
+			return {
+				kind: "form",
+				result: await enqueueMutation(() => activateWidgetNow(key, annotationRef))
+			};
+		},
+		notifyWidgetEvent: (key, annotationRef, event) => {
+			const actions = ctx.tryGet(ActionsToken);
+			if (!actions) return;
+			const source = widgetSource(key, annotationRef);
+			if (event === "cursorEnter" || event === "cursorExit") {
+				if (event === "cursorExit") {
+					widgetHoverPump(actions).hover(null);
+					return;
+				}
+				const flags = widgetHoverFlags(annotationRef);
+				if (flags && !flags.enter && !flags.exit) return;
+				widgetHoverPump(actions).hover({
+					ref: annotationRef,
+					pon: annotationRef.pageObjectNumber,
+					source,
+					...flags ? { events: flags } : {}
+				});
+				return;
+			}
+			actions.dispatch({
+				scope: "annotation",
+				event,
+				ref: annotationRef,
+				pon: annotationRef.pageObjectNumber,
+				source
+			});
+		},
+		resetFormAction,
+		resolveSubmitDataset,
+		commitScriptFormEffects: async (effects) => {
+			const doc = ctx.doc;
+			if (!doc?.forms.applyEffects) return {
+				results: effects.map((_, index) => ({
+					index,
+					status: "failed",
+					fields: [],
+					changedWidgets: [],
+					error: {
+						code: "NotSupported",
+						message: "no form-effects batch door"
+					}
+				})),
+				changedWidgets: [],
+				meta: null
+			};
+			let result;
+			try {
+				result = await doc.forms.applyEffects(effects);
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				return {
+					results: effects.map((_, index) => ({
+						index,
+						status: "failed",
+						fields: [],
+						changedWidgets: [],
+						error: {
+							code: "Refused",
+							message
+						}
+					})),
+					changedWidgets: [],
+					meta: null
+				};
+			}
+			await refresh(true);
+			if (annotationHost) {
+				const pons = new Set(result.changedWidgets.map((widget) => widget.pageObjectNumber).filter((pon) => pon > 0));
+				for (const pon of pons) await annotationHost.reloadPage(pon);
+			}
+			return result;
 		},
 		setValue: (ref, value) => enqueueMutation(async () => {
 			const doc = ctx.doc;
@@ -1124,8 +946,9 @@ function createFormCapability(ctx, options = {}) {
 		updateField: (key, patch) => enqueueMutation(() => updateFieldNow(key, patch)),
 		deleteField: (key) => enqueueMutation(() => deleteFieldNow(key)),
 		detachWidget: (key, annotObjectNumber) => enqueueMutation(() => detachWidgetNow(key, annotObjectNumber)),
+		canRead: () => can("doc.forms.read"),
 		canFill: () => can("doc.forms.fill"),
-		canModify: () => can("doc.forms.modify")
+		canDesign: () => can("doc.forms.modify")
 	};
 }
 //#endregion
@@ -1159,7 +982,11 @@ function registerFormEffects(ctx) {
 		}
 	};
 	const unsubscribe = doc.events.subscribe((event) => {
-		if (!event.type.startsWith("form.")) return;
+		if (event.type === "stream.desynced") {
+			refresh();
+			return;
+		}
+		if (!event.type.startsWith("form.") || !("origin" in event)) return;
 		const structural = STRUCTURAL.has(event.type);
 		if (event.origin.kind !== "remote" && !structural) return;
 		if (structural) ctx.dispatch({
@@ -1275,7 +1102,7 @@ function createPlaceHandler(form, interaction, annotation) {
 		enabledFor: (t) => t.enables.has("form-place"),
 		onDown: (s) => {
 			if (!s.page || !FORM_TOOL_BY_ID.has(interaction.activeToolId())) return false;
-			if (!form.canModify()) return false;
+			if (!form.canDesign()) return false;
 			origin = {
 				pon: s.page.pon,
 				start: s.page.point,
@@ -1342,9 +1169,6 @@ const initialFormState = () => ({ model: initialModel() });
 /** Dumb store: the pure core computes the next model; the shell dispatches it. */
 const formReducer = (state, action) => action.type === "SET_MODEL" ? { model: action.model } : state;
 //#endregion
-//#region src/types.ts
-const FormToken = createCapabilityToken("form");
-//#endregion
 //#region src/form.plugin.ts
 /**
 * The form plugin: the FIELD plane. Document-scoped; requires the
@@ -1359,17 +1183,17 @@ const FormToken = createCapabilityToken("form");
 */
 const formPlugin = (options = {}) => definePlugin({
 	id: "form",
-	token: FormToken,
+	token: FormToken$1,
 	scope: "document",
 	requires: [InteractionToken],
-	optional: [AnnotationToken],
+	optional: [AnnotationToken, ActionsToken],
 	initialState: initialFormState,
 	reduce: formReducer,
 	capability: (ctx) => createFormCapability(ctx, options),
 	effects: registerFormEffects,
 	init: (ctx) => {
 		const interaction = ctx.get(InteractionToken);
-		const form = ctx.get(FormToken);
+		const form = ctx.get(FormToken$1);
 		interaction.registerTool({
 			id: "form-fill",
 			cursor: "default",
@@ -1400,6 +1224,49 @@ const formPlugin = (options = {}) => definePlugin({
 			matches: (a) => a.subtype.startsWith("widget"),
 			engaged: () => interaction.activeTool()?.enables.has("form-fill") ?? false
 		});
+		const actions = ctx.tryGet(ActionsToken$1);
+		if (actions) {
+			ctx.cleanup(actions.registerFormCommitSink((effects) => {
+				const formHost = ctx.tryGet(FormToken$1);
+				if (!formHost) return Promise.resolve({
+					results: effects.map((_, index) => ({
+						index,
+						status: "failed",
+						fields: [],
+						changedWidgets: []
+					})),
+					changedWidgets: [],
+					meta: null
+				});
+				return formHost.commitScriptFormEffects(effects);
+			}));
+			ctx.cleanup(actions.registerSubmitResolver((intent, actionCtx, diagnose) => {
+				const formHost = ctx.tryGet(FormToken$1);
+				if (!formHost) throw new Error("form plugin unavailable");
+				return formHost.resolveSubmitDataset(intent, actionCtx, diagnose);
+			}));
+			ctx.cleanup(actions.registerExecutor("reset-form", async (node, actionCtx) => {
+				if (node.type !== "reset-form") return {
+					status: "inert",
+					reason: "not a reset-form node"
+				};
+				const formHost = ctx.tryGet(FormToken$1);
+				if (!formHost) return {
+					status: "inert",
+					reason: "form plugin unavailable"
+				};
+				const result = await formHost.resetFormAction(node.fields, node.exclude, actionCtx.origin);
+				if (result.status === "failed") return {
+					status: "failed",
+					error: result.error?.message ?? "reset failed"
+				};
+				if (result.effectsResult === null) return {
+					status: "inert",
+					reason: result.diagnostics[0]?.message ?? "reset-form resolved no fields"
+				};
+				return { status: "executed" };
+			}));
+		}
 	}
 });
 //#endregion