@embedpdf/plugin-actions 3.0.0-next.13 → 3.0.0-next.15

package/dist/index.js

@@ -1,67 +1,286 @@
-import { n as eventOf, r as originOf, t as ActionsToken } from "./types-DgBMy5nE.js";
-import { n as createHoverPump, t as submitEntriesToUrlEncoded } from "./contract-DAem-EST.js";
-import { DocumentsToken, createEventHook, createSerialQueue, definePlugin } from "@embedpdf/core";
+import { a as createHoverPump, i as submitEntriesToUrlEncoded, n as eventOf, o as ActionsToken, r as triggerOriginOf, t as ACTIONS_DEFAULTS } from "./contract-CwN3NAXU.js";
+import { ActionsToken as ActionsToken$1 } from "./contract/host.js";
+import { PluginError, composeApi, definePlugin, isPluginError, toPageRef } from "@embedpdf/core";
+import { annotationKey, pdfRectOf, rgbOf, toPageRef as toPageRef$1 } from "@embedpdf/engine-core/runtime";
 import { DEFAULT_SCRIPT_BUDGET, createScriptHost, javaScriptProgramFromActionTree, resolveScriptIdentity, scriptFieldsFromSnapshot, seedFrom } from "@embedpdf/core-acrojs";
-//#region src/script-environment.ts
-function createScriptRealmFactory(js, identityDoc) {
-	const sandboxFactory = js.sandboxFactory ?? (() => import("@embedpdf/core-js-sandbox").then(({ createQuickJsSandbox }) => createQuickJsSandbox()));
-	const budget = js.budget ?? DEFAULT_SCRIPT_BUDGET;
+//#region src/services/annotation-rows.ts
+/**
+* The annotations an action can live on, of both read families: a page's
+* annotations (`doc.annotations`, `doc.annotate.read`) and its widgets, which
+* come with the form (`ActionsForm`, `doc.forms.read`). Each family is read
+* only when the session may read it, so a fill-only session still finds its
+* widgets' actions.
+*/
+/** Every annotation of a page the session may read: its annotations, then its widgets. */
+async function readPageAnnotations(ctx, form, page, read = (task) => task) {
+	const [annotations, widgets] = await Promise.all([ctx.allows("doc.annotate.read") ? read(ctx.doc.page(page).annotations.list()).then((list) => list.annotations) : Promise.resolve([]), ctx.allows("doc.forms.read") ? form.read(read).then((snapshot) => snapshot.widgets.filter((widget) => widget.page.objectNumber === page.objectNumber)) : Promise.resolve([])]);
+	return [...annotations, ...widgets];
+}
+/**
+* The annotation `ref` names, of either family, or `null` when the session
+* can't see it: the form's widgets first (most actions a viewer runs are a
+* field's), then the page's annotations.
+*/
+async function readAnnotation(ctx, form, ref, read = (task) => task) {
+	const key = annotationKey(ref);
+	const matches = (candidate) => annotationKey(candidate.ref) === key;
+	if (ctx.allows("doc.forms.read")) {
+		const widget = (await form.read(read)).widgets.find(matches);
+		if (widget) return widget;
+	}
+	if (!ctx.allows("doc.annotate.read")) return null;
+	return (await read(ctx.doc.page(ref.page).annotations.list())).annotations.find(matches) ?? null;
+}
+//#endregion
+//#region src/dispatch/fold.ts
+const foldSteps = (steps, diagnostics) => {
+	const statuses = steps.map((step) => step.result.status);
 	return {
-		budget,
-		realmFor: (target) => createScriptHost({
-			sandboxFactory,
-			document: () => {
-				const meta = target.document();
-				return {
-					id: target.doc.id,
-					fileName: js.fileName?.() ?? meta?.name ?? "document.pdf",
-					pageCount: meta?.pageCount ?? 0,
-					pageNumber: 0
-				};
-			},
-			identity: () => resolveScriptIdentity(identityDoc, js.identity),
-			environment: (sequence) => {
-				const nowMs = js.now?.() ?? Date.now();
+		status: steps.length === 0 ? "inert" : statuses.every((stepStatus) => stepStatus === "refused") ? "refused" : statuses.every((stepStatus) => stepStatus === "inert") ? "inert" : statuses.every((stepStatus) => stepStatus === "executed") ? "executed" : "partial",
+		steps,
+		diagnostics
+	};
+};
+//#endregion
+//#region src/dispatch/dispatcher.ts
+/**
+* The dispatcher: the one serialized queue every tree rides. `execute` runs
+* a resolved tree; `dispatch` resolves a trigger inside the queued operation
+* (submission order is execution order) and fans out through the lifecycle
+* areas. `runAndEmit` is the shared per-tree unit: run, then `onExecuted`.
+*
+* A caller's signal skips an operation that hasn't started, stops a
+* trigger's reads, and stops a tree before its next node. `execute` then
+* rejects `operation-cancelled`; `dispatch` never rejects, so it resolves
+* `cancelled`.
+*/
+/** The source a trigger reports for: what its diagnostics carry before a tree is found. */
+const sourceOfTrigger = (trigger) => {
+	switch (trigger.scope) {
+		case "activate":
+		case "annotation": return trigger.source ?? {
+			kind: "annotation",
+			annotation: trigger.ref,
+			page: trigger.page
+		};
+		case "page": return {
+			kind: "page",
+			page: trigger.page
+		};
+		case "document": return { kind: "document" };
+	}
+};
+const cancelled = (operation, signal) => new PluginError("operation-cancelled", "actions", `${operation} was cancelled`, { cause: signal?.reason });
+function createDispatcher(ctx, services, { run }, { triggerEnabled, lifecycleAnnotationsOf, planPageSteps }, openSequence, { runDocumentEventOp }) {
+	const { executed, reportDiagnostic } = services.events;
+	const { decisionFor } = services.policy;
+	const { allowsPrint } = services.authority;
+	const { enqueue, budget } = services.queue;
+	const { readDocumentActions, DOC_EVENT_TREES } = services.catalog;
+	const { form } = services;
+	const { noteUserActivity } = openSequence;
+	/** Run one tree and announce it: the shared per-tree unit (queued by
+	*  `execute`; called inline per step by the queued trigger resolver). */
+	const runAndEmit = async (tree, actionContext, signal) => {
+		const result = await run(tree, actionContext, signal);
+		executed.emit({
+			tree,
+			result,
+			source: actionContext.source
+		});
+		return result;
+	};
+	const execute = (tree, actionContext, options) => {
+		const signal = options?.signal;
+		if (actionContext.origin === "user") noteUserActivity();
+		return enqueue(async () => {
+			budget.scriptNodes = 0;
+			const result = await runAndEmit(tree, actionContext, signal);
+			if (result.status === "cancelled") throw cancelled("actions.execute", signal);
+			return result;
+		}, options);
+	};
+	const canExecute = (tree, actionContext) => {
+		if (tree.incomplete || !tree.root) return false;
+		const decision = decisionFor(tree.root, actionContext.origin);
+		return decision === "allow" || decision === "adapter";
+	};
+	const runSteps = async (steps, origin, event, diagnostics, signal) => {
+		const results = [];
+		for (const step of steps) {
+			if (signal?.aborted) break;
+			const result = await runAndEmit(step.tree, {
+				origin,
+				source: step.source,
+				event
+			}, signal);
+			results.push({
+				source: step.source,
+				tree: step.tree,
+				result
+			});
+		}
+		if (signal?.aborted) return {
+			status: "cancelled",
+			steps: results,
+			diagnostics
+		};
+		return foldSteps(results, diagnostics);
+	};
+	/** Everything a trigger needs, reads included, inside the queued operation:
+	*  submission order is execution order. Never throws. */
+	const resolveAndRun = async (trigger, signal) => {
+		const diagnostics = [];
+		const diagnose = (diagnostic) => {
+			diagnostics.push(diagnostic);
+			reportDiagnostic(diagnostic, { source: sourceOfTrigger(trigger) });
+		};
+		/** A read the caller's signal can stop. */
+		const read = (task) => ctx.cancellable(signal, task);
+		try {
+			if (!triggerEnabled(trigger)) {
+				diagnose({
+					code: "trigger-disabled",
+					message: `${trigger.scope}: trigger family disabled by config`
+				});
 				return {
-					nowMs,
-					utcOffsetMinutes: js.utcOffsetMinutes?.() ?? -new Date(nowMs).getTimezoneOffset(),
-					randomSeed: js.randomSeed?.() ?? seedFrom(target.doc.id, sequence)
+					status: "inert",
+					steps: [],
+					diagnostics
 				};
-			},
-			bootSources: target.bootSources,
-			budget
-		})
+			}
+			const origin = triggerOriginOf(trigger);
+			switch (trigger.scope) {
+				case "activate":
+				case "annotation": {
+					const event = trigger.scope === "activate" ? "activate" : trigger.event;
+					const annotation = await readAnnotation(ctx, form, trigger.ref, read);
+					if (event === "mouseUp" && annotation?.actions?.activate) return {
+						status: "inert",
+						steps: [],
+						diagnostics
+					};
+					const tree = annotation?.actions?.[event];
+					if (!tree?.root && !tree?.incomplete) return {
+						status: "inert",
+						steps: [],
+						diagnostics
+					};
+					const source = sourceOfTrigger(trigger);
+					return await runSteps([{
+						source,
+						tree
+					}], origin, eventOf(trigger), diagnostics, signal);
+				}
+				case "page": {
+					const lifecycle = await lifecycleAnnotationsOf(trigger.page);
+					const pageActions = ctx.getPage(trigger.page)?.actions;
+					const steps = planPageSteps(trigger.event, trigger.page, pageActions, lifecycle);
+					return await runSteps(steps, origin, eventOf(trigger), diagnostics, signal);
+				}
+				case "document":
+					if (trigger.event !== "open") return await runDocumentEventOp(trigger.event, diagnostics, diagnose);
+					if (!openSequence.claim()) {
+						diagnose({
+							code: "open-sequence-replayed",
+							message: "document open sequence already fired for this document"
+						});
+						return {
+							status: "inert",
+							steps: [],
+							diagnostics
+						};
+					}
+					return await openSequence.run();
+			}
+		} catch (error) {
+			if (isPluginError(error, "operation-cancelled") && signal?.aborted) return {
+				status: "cancelled",
+				steps: [],
+				diagnostics
+			};
+			diagnose({
+				code: "trigger-failed",
+				message: `trigger resolution failed: ${error instanceof Error ? error.message : String(error)}`
+			});
+			return {
+				status: "refused",
+				steps: [],
+				diagnostics
+			};
+		}
+	};
+	const dispatch = (trigger, options) => {
+		const signal = options?.signal;
+		if (triggerOriginOf(trigger) === "user") noteUserActivity();
+		return enqueue(() => {
+			budget.scriptNodes = 0;
+			return resolveAndRun(trigger, signal);
+		}, options).catch(() => ({
+			status: "cancelled",
+			steps: [],
+			diagnostics: []
+		}));
+	};
+	/** The tree `executeNamed` runs, and its context: a click from your code unless `context` says otherwise. */
+	const namedTree = (name) => ({
+		root: {
+			type: "named",
+			subtype: "Named",
+			name,
+			next: []
+		},
+		incomplete: false,
+		warningFlags: 0,
+		warnings: []
+	});
+	const namedContext = (context) => ({
+		origin: "user",
+		source: { kind: "api" },
+		event: { scope: "activate" },
+		...context
+	});
+	const executeNamed = (name, context, options) => execute(namedTree(name), namedContext(context), options);
+	const canExecuteNamed = (name, context) => canExecute(namedTree(name), namedContext(context)) && (name !== "Print" || allowsPrint());
+	/** The raw tree behind a source, read from the document, with no dispatch
+	*  rules applied (the /A-shadows-U rule lives in `resolveAndRun`). */
+	const readActionTree = async (source) => {
+		switch (source.kind) {
+			case "annotation": return (await readAnnotation(ctx, form, source.annotation))?.actions?.[source.event ?? "activate"] ?? null;
+			case "field": {
+				const { fields } = await form.read();
+				const target = source.field;
+				return fields.find((candidate) => target.kind === "objectNumber" ? candidate.ref.kind === "objectNumber" && candidate.ref.objectNumber === target.objectNumber : candidate.name === target.name)?.actions?.[source.event] ?? null;
+			}
+			case "page": return ctx.getPage(source.page)?.actions?.[source.event ?? "open"] ?? null;
+			case "document": {
+				const snapshot = await readDocumentActions();
+				if (!snapshot) return null;
+				const event = source.event ?? "open";
+				return (event === "open" ? snapshot.openAction : snapshot[DOC_EVENT_TREES[event]]) ?? null;
+			}
+		}
+	};
+	return {
+		runAndEmit,
+		dispatch,
+		api: {
+			execute,
+			canExecute,
+			executeNamed,
+			canExecuteNamed,
+			getActionTree: (source, options) => ctx.cancellable(options?.signal, readActionTree(source)),
+			dispatch,
+			canDispatch: (trigger) => triggerEnabled(trigger),
+			prepareClose: (options) => dispatch({
+				scope: "document",
+				event: "will-close"
+			}, options)
+		}
 	};
 }
 //#endregion
-//#region src/capability.ts
-const ALLOW_ALL = {
-	user: "allow",
-	hover: "allow",
-	lifecycle: "allow"
-};
-const DEFAULT_POLICY = {
-	goto: ALLOW_ALL,
-	named: ALLOW_ALL,
-	hide: ALLOW_ALL,
-	"reset-form": ALLOW_ALL,
-	javascript: ALLOW_ALL,
-	uri: {
-		user: "adapter",
-		hover: "report",
-		lifecycle: "report"
-	},
-	print: {
-		user: "adapter",
-		hover: "block",
-		lifecycle: "block"
-	},
-	"submit-form": {
-		user: "adapter",
-		hover: "block",
-		lifecycle: "block"
-	}
-};
+//#region src/services/policy.ts
 /** Never executable, not configurable — diagnostics only. */
 const NEVER_TYPES = /* @__PURE__ */ new Set([
 	"launch",
@@ -71,7 +290,7 @@ const NEVER_TYPES = /* @__PURE__ */ new Set([
 	"movie",
 	"import-data"
 ]);
-/** Recognized types with no Phase-1 interpreter. */
+/** Recognized types with no interpreter: reported, never executed. */
 const UNSUPPORTED_TYPES = /* @__PURE__ */ new Set([
 	"rendition",
 	"thread",
@@ -82,565 +301,146 @@ const UNSUPPORTED_TYPES = /* @__PURE__ */ new Set([
 ]);
 /** Document-lifetime node types: engine mutations, committed in walk order. */
 const DOCUMENT_TYPES = /* @__PURE__ */ new Set(["reset-form", "javascript"]);
-const sameRef = (left, right) => {
-	if (left.kind === "objectNumber" && right.kind === "objectNumber") return left.annotObjectNumber === right.annotObjectNumber;
-	if (left.kind === "nm" && right.kind === "nm") return left.pageObjectNumber === right.pageObjectNumber && left.nm === right.nm;
-	if (left.kind === "index" && right.kind === "index") return left.pageObjectNumber === right.pageObjectNumber && left.index === right.index;
-	return false;
-};
 const isPrintVerb = (node) => node.type === "named" && node.name === "Print";
-function createActionsCapability(ctx, config = {}) {
-	const policy = {
-		...DEFAULT_POLICY,
-		...config.policy
-	};
-	const enqueue = createSerialQueue();
-	const executors = /* @__PURE__ */ new Map();
-	let annotCommitSink = null;
-	let formCommitSink = null;
-	let uiAdapter = null;
-	/** Sink 1 of the submit chain (consent = installation). */
-	let submitHandler = null;
-	/** The form plugin's dataset resolver (D7's one door). */
-	let submitResolver = null;
-	/** D3's document-print latch: while a print event wrapper is active, a
-	*  nested print request is SUPPRESSED (`reentrant-print`) — the adapter
-	*  opens exactly one dialog per outer request. */
-	let docPrintEventActive = false;
-	/** D11's deterministic aggregate: JS nodes run in the CURRENT dispatch. */
-	let jsNodesThisDispatch = 0;
-	const actionHook = createEventHook((error) => globalThis.console?.error("[actions] onAction observer failed:", error));
-	const diagnosticHook = createEventHook((error) => globalThis.console?.error("[actions] onDiagnostic observer failed:", error));
-	const scriptDiagnosticHook = createEventHook((error) => globalThis.console?.error("[actions] onScriptDiagnostic observer failed:", error));
-	const scriptErrorHook = createEventHook((error) => globalThis.console?.error("[actions] onScriptError observer failed:", error));
-	ctx.cleanup(() => {
-		actionHook.dispose();
-		diagnosticHook.dispose();
-		scriptDiagnosticHook.dispose();
-		scriptErrorHook.dispose();
-	});
-	/** Policy lookup — `null` means "recognized, no interpreter" (inert). */
+function createPolicy(ctx) {
+	const settings = ctx.settings();
+	/** The live policy: read at decision time, never captured. */
+	const current = () => settings.get().policy;
+	/** The decision for one node and origin; `'never'` and `'unsupported'` are fixed, not configurable. */
 	const decisionFor = (node, origin) => {
 		if (NEVER_TYPES.has(node.type)) return "never";
 		if (UNSUPPORTED_TYPES.has(node.type)) return "unsupported";
+		const policy = current();
 		if (isPrintVerb(node)) return policy.print[origin];
 		const row = policy[node.type];
 		return row ? row[origin] : "unsupported";
 	};
-	const allowsPrint = () => ctx.tryGet(DocumentsToken)?.allows("doc.print", ctx.documentId ?? void 0) ?? true;
-	let actionsSnapshotPromise = null;
-	const readDocumentActions = () => {
-		if (!actionsSnapshotPromise) {
-			const doc = ctx.doc;
-			const memo = (doc?.actions ? Promise.resolve(doc.actions.read()) : Promise.resolve(null)).catch((error) => {
-				if (actionsSnapshotPromise === memo) actionsSnapshotPromise = null;
-				throw error;
-			});
-			actionsSnapshotPromise = memo;
-		}
-		return actionsSnapshotPromise;
+	return {
+		decisionFor,
+		current
 	};
-	/** The Table-200 key for each verb-shaped document trigger event. */
-	const DOC_EVENT_TREES = {
-		"will-save": "willSave",
-		"did-save": "didSave",
-		"will-print": "willPrint",
-		"did-print": "didPrint",
-		"will-close": "willClose"
+}
+//#endregion
+//#region src/submit/intent.ts
+const intentOfPayload = (payload) => ({
+	url: payload.url,
+	fields: payload.fields,
+	exclude: payload.flags.exclude,
+	includeNoValueFields: payload.flags.includeNoValueFields,
+	format: payload.flags.format,
+	method: payload.flags.method,
+	flagsRaw: payload.flags.raw,
+	...payload.charSet === void 0 ? {} : { charSet: payload.charSet }
+});
+const toFormSubmissionRequest = (request, sentAt) => ({
+	entries: request.entries,
+	intent: {
+		url: request.url,
+		format: request.format,
+		method: request.method,
+		flagsRaw: request.flagsRaw,
+		...request.charSet === void 0 ? {} : { charSet: request.charSet }
+	},
+	origin: request.origin,
+	sentAt
+});
+/** Script `doc.submitForm(...)` → the one normalized intent. Script field
+*  names are include-mode by definition (Acrobat's aFields). */
+const intentOfSubmitEffect = (effect) => {
+	const format = effect.format ?? "fdf";
+	return {
+		url: effect.url,
+		fields: effect.fieldNames?.map((name) => ({
+			kind: "name",
+			name
+		})) ?? null,
+		exclude: false,
+		includeNoValueFields: effect.includeEmpty,
+		format,
+		method: effect.method ?? "post",
+		flagsRaw: 0
 	};
-	const nowMs = () => js?.now?.() ?? Date.now();
-	const intentOfPayload = (payload) => ({
-		url: payload.url,
-		fields: payload.fields,
-		exclude: payload.flags.exclude,
-		includeNoValueFields: payload.flags.includeNoValueFields,
-		format: payload.flags.format,
-		method: payload.flags.method,
-		flagsRaw: payload.flags.raw,
-		...payload.charSet === void 0 ? {} : { charSet: payload.charSet }
-	});
-	const toFormSubmissionRequest = (request) => ({
-		entries: request.entries,
-		intent: {
-			url: request.url,
-			format: request.format,
-			method: request.method,
-			flagsRaw: request.flagsRaw,
-			...request.charSet === void 0 ? {} : { charSet: request.charSet }
-		},
-		origin: request.origin,
-		clientTimeMs: nowMs()
-	});
-	/**
-	* The ONE submit door — both sources land here after policy. Sink order:
-	* embedder handler (explicit beats ambient; detached-promise contract) →
-	* the document's home (`doc.forms.submit`, engine-asserted, AWAITED — a
-	* real op with a real receipt) → blocked with `no-submit-sink`. Never a
-	* network call from this plugin.
-	*/
-	const performSubmit = async (intent, actionCtx, diagnose) => {
-		const decision = policy["submit-form"][actionCtx.origin];
-		if (decision !== "adapter" && decision !== "allow") {
-			diagnose({
-				code: "blocked",
-				message: `submit-form: policy '${decision}' for origin '${actionCtx.origin}'`
-			});
-			return { status: "blocked" };
-		}
-		if (!submitResolver) {
-			diagnose({
-				code: "no-submit-resolver",
-				message: "submit-form: no dataset resolver registered (form plugin missing?)"
+};
+//#endregion
+//#region src/dispatch/run.ts
+function createRunner(ctx, services, { performSubmit }, { firePrintThroughAdapter }) {
+	const { decisionFor } = services.policy;
+	const ports = services.ports.slots;
+	const { reportDiagnostic } = services.events;
+	const { form } = services;
+	async function run(tree, actionContext, signal) {
+		const diagnostics = [];
+		/** Record a diagnostic in the result and report it, with the action it concerns. */
+		const diagnose = (diagnostic, action) => {
+			diagnostics.push(diagnostic);
+			reportDiagnostic(diagnostic, {
+				action,
+				source: actionContext.source
 			});
-			return {
-				status: "blocked",
-				detail: "no dataset resolver"
-			};
-		}
-		let request;
-		try {
-			request = await submitResolver(intent, actionCtx, diagnose);
-		} catch (error) {
-			const detail = error instanceof Error ? error.message : String(error);
+		};
+		if (tree.incomplete) {
 			diagnose({
-				code: "executor-failed",
-				message: `submit-form: dataset resolution: ${detail}`
-			});
+				code: "incomplete-tree",
+				message: "refused: the action tree is incomplete"
+			}, tree.root?.type ?? null);
 			return {
-				status: "failed",
-				detail
+				status: "refused",
+				nodes: [],
+				diagnostics
 			};
 		}
-		const doc = ctx.doc;
-		const homeSubmit = doc && typeof doc.forms.submit === "function" ? () => Promise.resolve(doc.forms.submit(toFormSubmissionRequest(request))) : null;
-		if (submitHandler) try {
-			const outcome = submitHandler(request, { submitToDocumentHome: homeSubmit });
-			if (outcome && typeof outcome.then === "function") outcome.catch((error) => {
-				diagnosticHook.emit({
+		if (!tree.root) return {
+			status: "inert",
+			nodes: [],
+			diagnostics
+		};
+		const nodes = [];
+		const deferred = [];
+		let documentFailed = false;
+		let cancelled = false;
+		const settle = (result, outcome) => {
+			if (outcome.status === "executed") result.status = "executed";
+			else if (outcome.status === "inert") {
+				result.status = "inert";
+				result.detail = outcome.reason;
+				diagnose({
+					code: "executor-inert",
+					message: `${result.type}: ${outcome.reason}`
+				}, result.type);
+			} else {
+				result.status = "failed";
+				result.detail = outcome.error;
+				diagnose({
 					code: "executor-failed",
-					message: `submit handler rejected (detached): ${error instanceof Error ? error.message : String(error)}`
-				});
-			});
-			return { status: "executed" };
-		} catch (error) {
-			const detail = error instanceof Error ? error.message : String(error);
-			diagnose({
-				code: "executor-failed",
-				message: `submit handler threw: ${detail}`
-			});
-			return {
-				status: "failed",
-				detail
-			};
-		}
-		if (homeSubmit) try {
-			await homeSubmit();
-			return { status: "executed" };
-		} catch (error) {
-			const detail = error instanceof Error ? error.message : String(error);
-			diagnose({
-				code: "executor-failed",
-				message: `document home refused submit: ${detail}`
-			});
-			return {
-				status: "failed",
-				detail
-			};
-		}
-		diagnose({
-			code: "no-submit-sink",
-			message: "submit-form: no handler installed and the document has no submit-capable home"
-		});
-		return {
-			status: "blocked",
-			detail: "no submit sink"
-		};
-	};
-	const js = config.javascript;
-	const realms = js?.enabled && ctx.doc ? createScriptRealmFactory(js, ctx.doc) : null;
-	const scriptHost = realms && ctx.doc ? realms.realmFor({
-		doc: ctx.doc,
-		document: () => ctx.document(),
-		bootSources: async () => {
-			return ((await readDocumentActions())?.nameTreeScripts ?? []).map(({ action }) => javaScriptProgramFromActionTree(action));
-		}
-	}) : null;
-	if (scriptHost) ctx.cleanup(() => scriptHost.dispose());
-	const surfaceScriptResult = (result) => {
-		const uiContext = {
-			origin: result.origin,
-			phase: result.phase
-		};
-		for (const effect of result.uiEffects) {
-			if (result.realm === "detached" && effect.kind !== "alert") {
-				scriptDiagnosticHook.emit({
-					code: "ui-effect-suppressed",
-					message: `script ${effect.kind} request from a detached realm suppressed: no document surface`
-				});
-				continue;
-			}
-			if (effect.kind === "submitForm") {
-				performSubmit(intentOfSubmitEffect(effect), {
-					origin: result.origin,
-					source: { kind: "api" },
-					event: { scope: "activate" }
-				}, (diagnostic) => diagnosticHook.emit(diagnostic));
-				continue;
-			}
-			if (effect.kind === "print" && !allowsPrint()) {
-				scriptDiagnosticHook.emit({
-					code: "ui-effect-suppressed",
-					message: "script print request withheld: doc.print is not allowed"
-				});
-				continue;
-			}
-			if (effect.kind === "print" && docPrintEventActive) {
-				scriptDiagnosticHook.emit({
-					code: "ui-effect-suppressed",
-					message: "script print request during a document print event — suppressed (reentrant)"
-				});
-				continue;
-			}
-			if (!uiAdapter) {
-				diagnosticHook.emit({
-					code: "no-adapter",
-					message: `script ${effect.kind}: no UI adapter installed`
-				});
-				continue;
-			}
-			if (effect.kind === "alert") uiAdapter.alert?.(effect.message, {
-				...uiContext,
-				icon: effect.icon,
-				...effect.title !== void 0 ? { title: effect.title } : {}
-			});
-			else if (effect.kind === "gotoPage") uiAdapter.gotoPage?.(effect.page, uiContext);
-			else uiAdapter.print(uiContext);
-		}
-		for (const diagnostic of result.diagnostics) scriptDiagnosticHook.emit(diagnostic);
-		if (result.error) scriptErrorHook.emit(result.error);
-	};
-	/** A K/V/C/F commit surfaces as up to two results: the boot phase (only
-	*  when it produced effects) and the user phase (always — it carries the
-	*  diagnostics and the error). */
-	const surfaceScriptCommit = (commit, context) => {
-		for (const phase of ["boot", "user"]) {
-			const uiEffects = commit.uiEffects.filter((effect) => effect.phase === phase);
-			if (uiEffects.length === 0 && phase === "boot") continue;
-			surfaceScriptResult({
-				uiEffects,
-				diagnostics: phase === "user" ? commit.diagnostics : [],
-				...phase === "user" && commit.error ? { error: commit.error } : {},
-				origin: context.origin,
-				phase,
-				realm: context.realm
-			});
-		}
-	};
-	/** Script `doc.submitForm(...)` → the one normalized intent. Script field
-	*  names are include-mode by definition (Acrobat's aFields). */
-	const intentOfSubmitEffect = (effect) => {
-		const format = effect.format ?? "fdf";
-		return {
-			url: effect.url,
-			fields: effect.fieldNames?.map((name) => ({
-				kind: "name",
-				name
-			})) ?? null,
-			exclude: false,
-			includeNoValueFields: effect.includeEmpty,
-			format,
-			method: effect.method ?? "post",
-			flagsRaw: 0
-		};
-	};
-	const engineColorToArray = (color) => color ? [
-		"RGB",
-		color.r / 255,
-		color.g / 255,
-		color.b / 255
-	] : ["T"];
-	const pageIndexOf = (pon) => ctx.document()?.pages.findIndex((page) => page.pageObjectNumber === pon) ?? -1;
-	const scriptWorldFor = async (pon) => {
-		const doc = ctx.doc;
-		const snapshot = await doc.forms.list();
-		const pageIndex = Math.max(0, pageIndexOf(pon));
-		const { annotations } = await doc.page(pon).annotations.list();
-		const annots = annotations.filter((a) => a.subtype !== "link" && !a.subtype.startsWith("widget")).map((a) => {
-			const styled = a;
-			return {
-				ref: a.ref,
-				name: a.nm ?? "",
-				subtype: a.subtype,
-				page: pageIndex,
-				rect: [
-					a.rect.left,
-					a.rect.bottom,
-					a.rect.right,
-					a.rect.top
-				],
-				contents: a.contents ?? "",
-				author: a.author ?? "",
-				subject: a.subject ?? "",
-				strokeColor: engineColorToArray(styled.color),
-				fillColor: engineColorToArray(styled.interiorColor),
-				opacity: styled.opacity ?? 1,
-				width: styled.strokeWidth ?? 1,
-				borderStyle: styled.borderStyle === "dashed" ? "D" : "S",
-				dash: styled.dashArray ?? [],
-				hidden: a.flags.hidden,
-				print: a.flags.print,
-				readOnly: a.flags.readOnly,
-				locked: a.flags.locked,
-				noView: a.flags.noView,
-				toggleNoView: a.flags.toggleNoView,
-				opaqueBody: a.subtype === "stamp"
-			};
-		});
-		return {
-			snapshot,
-			world: {
-				fields: scriptFieldsFromSnapshot(snapshot),
-				annots,
-				annotPages: [pageIndex],
-				annotsCoverDocument: (ctx.document()?.pageCount ?? 0) <= 1
-			}
-		};
-	};
-	const ANNOTATION_EVENT_NAMES = {
-		cursorEnter: "Mouse Enter",
-		cursorExit: "Mouse Exit",
-		mouseDown: "Mouse Down",
-		mouseUp: "Mouse Up",
-		focus: "Focus",
-		blur: "Blur"
-	};
-	const PAGE_EVENT_NAMES = {
-		open: "Open",
-		close: "Close",
-		visible: "Visible",
-		invisible: "Invisible"
-	};
-	const DOC_EVENT_NAMES = {
-		open: "Open",
-		"will-save": "WillSave",
-		"did-save": "DidSave",
-		"will-print": "WillPrint",
-		"did-print": "DidPrint",
-		"will-close": "WillClose"
-	};
-	const scriptEventFor = (actionCtx, snapshot) => {
-		const provenance = actionCtx.event;
-		const type = provenance.scope === "page" ? "Page" : provenance.scope === "document" ? "Doc" : actionCtx.source.kind === "widget" ? "Field" : actionCtx.source.kind === "link" ? "Link" : "Annot";
-		const name = provenance.scope === "activate" ? "Mouse Up" : provenance.scope === "annotation" ? ANNOTATION_EVENT_NAMES[provenance.name] ?? "Mouse Up" : provenance.scope === "page" ? PAGE_EVENT_NAMES[provenance.name] ?? "Open" : DOC_EVENT_NAMES[provenance.name] ?? "Open";
-		const targetRef = actionCtx.source.kind === "widget" ? actionCtx.source.field : void 0;
-		const targetField = targetRef ? snapshot.fields.find((field) => targetRef.kind === "objectNumber" && field.ref.kind === "objectNumber" ? field.ref.fieldObjectNumber === targetRef.fieldObjectNumber : targetRef.kind === "fqn" && field.name === targetRef.name) : void 0;
-		return {
-			kind: "widget-activate",
-			type,
-			name,
-			...targetRef ? {
-				target: targetRef,
-				source: targetRef
-			} : {},
-			...targetField && targetField.valueEntry.kind === "scalar" ? { value: targetField.valueEntry.value } : {}
-		};
-	};
-	/** Commit one run's document effects through the owner sinks in the
-	*  DECLARED order (form first, then annot); the first failure skips the
-	*  rest across BOTH streams. Returns the failure summary, if any. */
-	const commitScriptOutput = async (output, diagnose) => {
-		let failure = null;
-		if (output.formEffects.length > 0) if (!formCommitSink) diagnose({
-			code: "no-commit-sink",
-			message: `script form effects dropped: no form commit sink registered (${output.formEffects.length})`
-		});
-		else {
-			const bad = (await formCommitSink(output.formEffects)).results.find((entry) => entry.status === "failed" || entry.status === "rejected");
-			if (bad) failure = `form effect ${bad.index}: ${bad.error?.message ?? bad.status}`;
-		}
-		if (output.annotEffects.length > 0) if (failure) diagnose({
-			code: "executor-failed",
-			message: `script annot effects skipped after form failure (${output.annotEffects.length})`
-		});
-		else if (!annotCommitSink) diagnose({
-			code: "no-commit-sink",
-			message: `script annot effects dropped: no annotation commit sink registered (${output.annotEffects.length})`
-		});
-		else {
-			const entries = output.annotEffects.map((effect) => ({
-				annotObjectNumber: effect.ref.kind === "objectNumber" ? effect.ref.annotObjectNumber : -1,
-				...effect.ref.kind === "objectNumber" ? { pageObjectNumber: effect.ref.pageObjectNumber } : {},
-				patch: effect.patch
-			}));
-			const bad = (await annotCommitSink(entries)).results.find((entry) => entry.status === "failed");
-			if (bad) failure = `annotation ${bad.annotObjectNumber}: ${bad.error ?? "failed"}`;
-		}
-		if (failure) diagnose({
-			code: "executor-failed",
-			message: `script commit: ${failure}`
-		});
-		return failure;
-	};
-	if (scriptHost) {
-		const nodeCap = js?.maxScriptNodesPerDispatch ?? 16;
-		executors.set("javascript", async (node, actionCtx) => {
-			if (node.type !== "javascript") return {
-				status: "inert",
-				reason: "not a JS node"
-			};
-			if (!ctx.doc) return {
-				status: "inert",
-				reason: "no document"
-			};
-			if (jsNodesThisDispatch >= nodeCap) return {
-				status: "inert",
-				reason: `dispatch script budget exhausted (${nodeCap} JS nodes)`
-			};
-			jsNodesThisDispatch += 1;
-			const source = actionCtx.source;
-			const pon = source.kind === "widget" ? source.pon : source.kind === "link" || source.kind === "annotation" ? source.pon ?? ctx.document()?.pages[0]?.pageObjectNumber : source.kind === "page" ? source.pon : ctx.document()?.pages[0]?.pageObjectNumber;
-			if (pon === void 0) return {
-				status: "inert",
-				reason: "no page to anchor the world on"
-			};
-			const diagnose = (diagnostic) => diagnosticHook.emit(diagnostic);
-			const pendingExternal = [];
-			const splitExternal = (output, phase) => output.uiEffects.filter((effect) => {
-				if (effect.kind === "print" || effect.kind === "submitForm") {
-					pendingExternal.push({
-						effect,
-						phase
-					});
-					return false;
-				}
-				return true;
-			});
-			const outcome = await scriptHost.transaction(async (txn) => {
-				let built = await scriptWorldFor(pon);
-				const boot = await txn.boot({
-					...built.world,
-					event: {
-						kind: "name-tree-boot",
-						type: "Doc",
-						name: "Open"
-					}
-				});
-				if (boot) {
-					await commitScriptOutput(boot, diagnose);
-					surfaceScriptResult({
-						uiEffects: splitExternal(boot, "boot"),
-						diagnostics: boot.diagnostics,
-						...boot.error ? { error: boot.error } : {},
-						origin: actionCtx.origin,
-						phase: "boot",
-						realm: "document"
-					});
-					if (boot.formEffects.length || boot.annotEffects.length) built = await scriptWorldFor(pon);
-				}
-				const output = await txn.run(node.script, {
-					...built.world,
-					event: scriptEventFor(actionCtx, built.snapshot)
-				});
-				surfaceScriptResult({
-					uiEffects: splitExternal(output, "user"),
-					diagnostics: output.diagnostics,
-					...output.error ? { error: output.error } : {},
-					origin: actionCtx.origin,
-					phase: "user",
-					realm: "document"
-				});
-				if (output.error) return {
-					status: "failed",
-					error: output.error.message
-				};
-				const failure = await commitScriptOutput(output, diagnose);
-				return failure ? {
-					status: "failed",
-					error: failure
-				} : { status: "executed" };
-			});
-			for (const entry of pendingExternal) if (entry.effect.kind === "print") await firePrintThroughAdapter({
-				origin: actionCtx.origin,
-				phase: entry.phase
-			}, diagnose);
-			else await performSubmit(intentOfSubmitEffect(entry.effect), actionCtx, diagnose);
-			return outcome;
-		});
-	}
-	async function run(tree, actionCtx) {
-		const diagnostics = [];
-		const diagnose = (diagnostic) => {
-			diagnostics.push(diagnostic);
-			diagnosticHook.emit(diagnostic);
-		};
-		if (tree.incomplete) {
-			diagnose({
-				code: "incomplete-tree",
-				message: "refused: the action tree is incomplete"
-			});
-			return {
-				status: "refused",
-				nodes: [],
-				diagnostics
-			};
-		}
-		if (!tree.root) return {
-			status: "inert",
-			nodes: [],
-			diagnostics
-		};
-		const nodes = [];
-		const deferred = [];
-		let documentFailed = false;
-		const settle = (result, outcome) => {
-			if (outcome.status === "executed") result.status = "executed";
-			else if (outcome.status === "inert") {
-				result.status = "inert";
-				result.detail = outcome.reason;
-				diagnose({
-					code: "executor-inert",
-					message: `${result.type}: ${outcome.reason}`
-				});
-			} else {
-				result.status = "failed";
-				result.detail = outcome.error;
-				diagnose({
-					code: "executor-failed",
-					message: `${result.type}: ${outcome.error}`
-				});
-			}
+					message: `${result.type}: ${outcome.error}`
+				}, result.type);
+			}
 		};
 		const interpretHide = async (node) => {
-			const doc = ctx.doc;
 			const display = node.hide ? "hidden" : "visible";
+			const diagnoseHide = (diagnostic) => diagnose(diagnostic, "hide");
 			const fieldRefs = [];
 			const annotEntries = [];
 			const names = [];
 			const bareObjectNumbers = [];
 			for (const target of node.targets) if (target.kind === "objectNumber") bareObjectNumbers.push(target.objectNumber);
 			else names.push(target.name);
-			if ((names.length || bareObjectNumbers.length) && doc) {
-				const snapshot = names.length || bareObjectNumbers.length ? await doc.forms.list() : null;
+			if (names.length || bareObjectNumbers.length) {
+				const snapshot = await form.read();
 				for (const name of names) {
-					const field = snapshot?.fields.find((candidate) => candidate.name === name);
+					const field = snapshot.fields.find((candidate) => candidate.name === name);
 					if (!field) {
-						diagnose({
+						diagnoseHide({
 							code: "unresolved-target",
 							message: `hide: no field named '${name}'`
 						});
 						continue;
 					}
-					fieldRefs.push({
-						kind: "objectNumber",
-						fieldObjectNumber: field.fieldObjectNumber
-					});
+					fieldRefs.push(field.ref);
 				}
 				for (const objectNumber of bareObjectNumbers) {
-					const owner = snapshot?.fields.find((field) => field.widgets.some((widget) => widget.annotObjectNumber === objectNumber));
-					if (owner) fieldRefs.push({
-						kind: "objectNumber",
-						fieldObjectNumber: owner.fieldObjectNumber
-					});
+					const owner = snapshot.fields.find((field) => field.widgets.some((widget) => widget.objectNumber === objectNumber));
+					if (owner) fieldRefs.push(owner.ref);
 					else annotEntries.push({
 						annotObjectNumber: objectNumber,
 						patch: { flags: { hidden: node.hide } }
@@ -649,37 +449,37 @@ function createActionsCapability(ctx, config = {}) {
 			}
 			let failedDetail;
 			if (fieldRefs.length) {
-				if (!formCommitSink) {
-					diagnose({
+				if (!ports.formCommitSink) {
+					diagnoseHide({
 						code: "no-commit-sink",
 						message: "hide: no form commit sink registered (form plugin absent)"
 					});
 					return { status: "no-executor" };
 				}
-				const bad = (await formCommitSink(fieldRefs.map((ref) => ({
+				const result = await ports.formCommitSink(fieldRefs.map((ref) => ({
 					kind: "setDisplay",
 					ref,
 					display
-				})))).results.find((entry) => entry.status === "failed" || entry.status === "rejected");
-				if (bad) {
-					failedDetail = bad.error?.message ?? bad.status;
-					diagnose({
+				})));
+				if (result.status === "failed") {
+					failedDetail = result.error ?? "failed";
+					diagnoseHide({
 						code: "executor-failed",
 						message: `hide: ${failedDetail}`
 					});
 				}
 			}
 			if (annotEntries.length && !failedDetail) {
-				if (!annotCommitSink) {
-					diagnose({
+				if (!ports.annotCommitSink) {
+					diagnoseHide({
 						code: "no-commit-sink",
 						message: "hide: no annotation commit sink registered (annotation plugin absent)"
 					});
 					return { status: "no-executor" };
 				}
-				const committed = await annotCommitSink(annotEntries);
+				const committed = await ports.annotCommitSink(annotEntries);
 				const failed = committed.results.filter((entry) => entry.status === "failed");
-				for (const failure of failed) diagnose({
+				for (const failure of failed) diagnoseHide({
 					code: "executor-failed",
 					message: `hide: annotation ${failure.annotObjectNumber}: ${failure.error ?? "failed"}`
 				});
@@ -698,12 +498,13 @@ function createActionsCapability(ctx, config = {}) {
 				status: "blocked"
 			};
 			nodes.push(result);
-			const decision = decisionFor(node, actionCtx.origin);
+			const decision = decisionFor(node, actionContext.origin);
+			const diagnoseNode = (diagnostic) => diagnose(diagnostic, node.type);
 			if (decision === "never" || decision === "block" || decision === "report") {
 				result.status = "blocked";
-				diagnose({
+				if (decision !== "block") diagnoseNode({
 					code: "blocked",
-					message: `${node.type}: ${decision === "never" ? "never executable" : `policy '${decision}' for origin '${actionCtx.origin}'`}`
+					message: `${node.type}: ${decision === "never" ? "never executable" : `policy 'report' for origin '${actionContext.origin}'`}`
 				});
 				return;
 			}
@@ -727,17 +528,17 @@ function createActionsCapability(ctx, config = {}) {
 					result.status = "skipped";
 					return;
 				}
-				const executor = executors.get(node.type);
+				const executor = ports.executors.get(node.type);
 				if (!executor) {
 					result.status = node.type === "javascript" ? "inert" : "no-executor";
-					diagnose({
+					diagnoseNode({
 						code: "no-executor",
 						message: `${node.type}: no executor registered${node.type === "javascript" ? " (scripting unavailable)" : ""}`
 					});
 					return;
 				}
 				try {
-					settle(result, await executor(node, actionCtx));
+					settle(result, await executor(node, actionContext));
 				} catch (error) {
 					settle(result, {
 						status: "failed",
@@ -751,7 +552,7 @@ function createActionsCapability(ctx, config = {}) {
 				if (!node.payload) {
 					result.status = "inert";
 					result.detail = "submit payload unavailable (older runtime extraction)";
-					diagnose({
+					diagnoseNode({
 						code: "submit-payload-unavailable",
 						message: "submit-form: payload unavailable (older runtime extraction) — node inert"
 					});
@@ -762,7 +563,7 @@ function createActionsCapability(ctx, config = {}) {
 				deferred.push({
 					result,
 					fire: async () => {
-						const outcome = await performSubmit(intentOfPayload(payload), actionCtx, diagnose);
+						const outcome = await performSubmit(intentOfPayload(payload), actionContext, diagnoseNode);
 						result.status = outcome.status;
 						if (outcome.detail) result.detail = outcome.detail;
 					}
@@ -775,22 +576,22 @@ function createActionsCapability(ctx, config = {}) {
 					result,
 					fire: async () => {
 						if (node.type === "uri") {
-							if (!uiAdapter) {
+							if (!ports.uiAdapter) {
 								result.status = "no-executor";
-								diagnose({
+								diagnoseNode({
 									code: "no-adapter",
 									message: `${node.type}: no UI adapter installed`
 								});
 								return;
 							}
-							uiAdapter.openUri(node.uri, {
+							ports.uiAdapter.openUri(node.uri, {
 								isMap: node.isMap,
-								origin: actionCtx.origin
+								origin: actionContext.origin
 							});
 							result.status = "executed";
 							return;
 						}
-						const outcome = await firePrintThroughAdapter(void 0, diagnose);
+						const outcome = await firePrintThroughAdapter(void 0, diagnoseNode);
 						result.status = outcome.status;
 						if (outcome.detail) result.detail = outcome.detail;
 					}
@@ -801,17 +602,17 @@ function createActionsCapability(ctx, config = {}) {
 			deferred.push({
 				result,
 				fire: async () => {
-					const executor = executors.get(node.type);
+					const executor = ports.executors.get(node.type);
 					if (!executor) {
 						result.status = "no-executor";
-						diagnose({
+						diagnoseNode({
 							code: "no-executor",
 							message: `${node.type}: no executor registered`
 						});
 						return;
 					}
 					try {
-						settle(result, await executor(node, actionCtx));
+						settle(result, await executor(node, actionContext));
 					} catch (error) {
 						settle(result, {
 							status: "failed",
@@ -822,11 +623,20 @@ function createActionsCapability(ctx, config = {}) {
 			});
 		};
 		const walk = async (node, path) => {
+			if (signal?.aborted) {
+				cancelled = true;
+				return;
+			}
 			await interpret(node, path);
-			for (let index = 0; index < node.next.length; index++) await walk(node.next[index], [...path, index]);
+			for (let index = 0; index < node.next.length && !cancelled; index++) await walk(node.next[index], [...path, index]);
 		};
 		await walk(tree.root, []);
-		if (!documentFailed) for (const entry of deferred) await entry.fire();
+		if (!documentFailed && !cancelled) for (const entry of deferred) await entry.fire();
+		if (cancelled) return {
+			status: "cancelled",
+			nodes,
+			diagnostics
+		};
 		const anyExecuted = nodes.some((node) => node.status === "executed");
 		const anyFailedOrSkipped = nodes.some((node) => node.status === "failed" || node.status === "skipped");
 		return {
@@ -835,239 +645,400 @@ function createActionsCapability(ctx, config = {}) {
 			diagnostics
 		};
 	}
-	/** run + seq + event — the shared per-tree unit (queued by execute; called
-	*  inline per step by the queued trigger resolver). */
-	const runAndEmit = async (tree, actionCtx) => {
-		const result = await run(tree, actionCtx);
-		ctx.dispatch({ type: "ACTIONS_DISPATCHED" });
-		actionHook.emit({
-			ctx: actionCtx,
-			tree,
-			result
-		});
-		return result;
-	};
-	const execute = (tree, actionCtx) => {
-		if (actionCtx.origin === "user") noteUserActivity();
-		return enqueue(() => {
-			jsNodesThisDispatch = 0;
-			return runAndEmit(tree, actionCtx);
-		});
-	};
-	const canExecute = (tree, actionCtx) => {
-		if (tree.incomplete || !tree.root) return false;
-		const decision = decisionFor(tree.root, actionCtx.origin);
-		return decision === "allow" || decision === "adapter";
-	};
+	return { run };
+}
+//#endregion
+//#region src/dispatch/triggers.ts
+/**
+* The pages whose annotations an event changes: those pages, every page
+* (`'all'`: a redaction, a skipped stretch of the stream, new document
+* bytes), or none.
+*/
+const annotationPagesOf = (event) => {
+	switch (event.type) {
+		case "annotations.created":
+		case "annotations.updated":
+		case "annotations.deleted":
+		case "annotations.reordered":
+		case "annotations.flattened":
+		case "forms.widgetsReordered": return [event.page];
+		case "forms.created":
+		case "forms.deleted":
+		case "forms.widgetAdded":
+		case "forms.widgetRemoved":
+		case "forms.widgetDeleted":
+		case "forms.widgetRestored":
+		case "forms.widgetUpdated":
+		case "forms.restored":
+		case "forms.repaired": return "all";
+		case "pages.flattened": return event.pages;
+		case "redaction.applied":
+		case "stream.desynced":
+		case "document.versioned": return "all";
+		default: return null;
+	}
+};
+function createTriggers(ctx, { settings, form }) {
 	const triggerEnabled = (trigger) => {
+		const { triggers } = settings.get();
 		switch (trigger.scope) {
 			case "activate": return true;
-			case "annotation": return config.triggers?.annotation !== false;
-			case "page": return config.triggers?.page !== false;
-			case "document": return config.triggers?.document !== false;
+			case "annotation": return triggers.annotation;
+			case "page": return triggers.page;
+			case "document": return triggers.document;
 		}
 	};
-	const lifecycleCache = /* @__PURE__ */ new Map();
-	const lifecycleTreesFor = async (pon) => {
-		const hit = lifecycleCache.get(pon);
-		if (hit) return hit;
-		const doc = ctx.doc;
-		if (!doc) return [];
-		const { annotations } = await doc.page(pon).annotations.list();
-		const bearing = annotations.filter((a) => a.actions && (a.actions.pageOpen?.root || a.actions.pageClose?.root || a.actions.pageVisible?.root || a.actions.pageInvisible?.root)).map((a) => ({
-			ref: a.ref,
-			actions: a.actions
-		}));
-		lifecycleCache.set(pon, bearing);
-		return bearing;
-	};
-	{
-		const unsubscribe = ctx.doc?.events?.subscribe((event) => {
-			if (event.type.startsWith("annotation.") || event.type === "stream.desynced") lifecycleCache.clear();
+	const lifecycleReads = /* @__PURE__ */ new Map();
+	const lifecycleAnnotationsOf = (page) => {
+		const key = page.objectNumber;
+		const cached = lifecycleReads.get(key);
+		if (cached) return cached;
+		const read = readPageAnnotations(ctx, form, page).then((annotations) => annotations.filter((annotation) => annotation.actions && (annotation.actions.pageOpen?.root || annotation.actions.pageClose?.root || annotation.actions.pageVisible?.root || annotation.actions.pageInvisible?.root)).map((annotation) => ({
+			ref: annotation.ref,
+			actions: annotation.actions
+		})));
+		lifecycleReads.set(key, read);
+		read.catch(() => {
+			if (lifecycleReads.get(key) === read) lifecycleReads.delete(key);
 		});
-		if (unsubscribe) ctx.cleanup(unsubscribe);
-	}
+		return read;
+	};
+	/** Forget the pages a confirmed document event changed. */
+	const invalidate = (event) => {
+		const pages = annotationPagesOf(event);
+		if (pages === "all") lifecycleReads.clear();
+		else if (pages) for (const page of pages) lifecycleReads.delete(page.objectNumber);
+	};
 	/**
-	* ISO order, verified against 32000-2 Table 197 (2026-09-02): PO "shall be
-	* executed after the O action … and the OpenAction entry"; PC "shall be
-	* executed before the C action". Rootless trees are skipped (a
-	* budget-degraded tree with no root has nothing to walk).
+	* ISO 32000-2 Table 197 order: /PO "shall be executed after the O action …
+	* and the OpenAction entry"; /PC "shall be executed before the C action".
+	* Rootless trees are skipped (a budget-degraded tree with no root has
+	* nothing to walk).
 	*/
-	const planPageSteps = (event, pon, pageActions, lifecycle) => {
+	const planPageSteps = (event, page, pageActions, lifecycle) => {
 		const pageSource = {
 			kind: "page",
-			pon
+			page
 		};
-		const annotSteps = (key) => lifecycle.filter((a) => a.actions[key]?.root).map((a) => ({
+		const annotationSteps = (key) => lifecycle.filter((annotation) => annotation.actions[key]?.root).map((annotation) => ({
 			source: {
 				kind: "annotation",
-				annotation: a.ref,
-				pon
+				annotation: annotation.ref,
+				page
 			},
-			tree: a.actions[key]
+			tree: annotation.actions[key]
 		}));
 		switch (event) {
 			case "open": return [...pageActions?.open?.root ? [{
 				source: pageSource,
 				tree: pageActions.open
-			}] : [], ...annotSteps("pageOpen")];
-			case "close": return [...annotSteps("pageClose"), ...pageActions?.close?.root ? [{
+			}] : [], ...annotationSteps("pageOpen")];
+			case "close": return [...annotationSteps("pageClose"), ...pageActions?.close?.root ? [{
 				source: pageSource,
 				tree: pageActions.close
 			}] : []];
-			case "visible": return annotSteps("pageVisible");
-			case "invisible": return annotSteps("pageInvisible");
+			case "visible": return annotationSteps("pageVisible");
+			case "invisible": return annotationSteps("pageInvisible");
 		}
 	};
-	/** Aggregate step statuses. A step failure never skips its siblings; this
-	*  only FOLDS what each step reported. */
-	const foldSteps = (steps, diagnostics) => {
-		const statuses = steps.map((s) => s.result.status);
-		return {
-			status: steps.length === 0 ? "inert" : statuses.every((s) => s === "refused") ? "refused" : statuses.every((s) => s === "inert") ? "inert" : statuses.every((s) => s === "executed") ? "executed" : "partial",
-			steps,
-			diagnostics
-		};
-	};
-	const runSteps = async (steps, origin, event, diagnostics) => {
-		const results = [];
-		for (const step of steps) {
-			const result = await runAndEmit(step.tree, {
-				origin,
-				source: step.source,
-				event
-			});
-			results.push({
-				source: step.source,
-				tree: step.tree,
-				result
-			});
-		}
-		return foldSteps(results, diagnostics);
+	return {
+		triggerEnabled,
+		lifecycleAnnotationsOf,
+		invalidate,
+		planPageSteps
 	};
-	/** Everything a trigger needs — reads included — INSIDE the queued op:
-	*  submission order is execution order. Never throws. */
-	const resolveAndRun = async (trigger) => {
-		const diagnostics = [];
-		const diagnose = (diagnostic) => {
-			diagnostics.push(diagnostic);
-			diagnosticHook.emit(diagnostic);
-		};
+}
+//#endregion
+//#region src/lifecycle/document-events.ts
+/**
+* The verb-shaped document events (/WC, /WS, /DS, /WP, /DP) and the print
+* door: one catalog lifecycle tree per event, run inside the current queue
+* operation and never throwing (a broken script must not cancel the user's
+* save or print), and the adapter print wrapped /WP → print → /DP under the
+* print latch.
+*/
+function createDocumentEvents(services, { ensureOpenSequenceBeforeDocEvent }, { runAndEmit }) {
+	const { reportDiagnostic } = services.events;
+	const { readDocumentActions, DOC_EVENT_TREES } = services.catalog;
+	const { enqueue, budget } = services.queue;
+	const ports = services.ports.slots;
+	const { allowsPrint } = services.authority;
+	const printLatch = services.printLatch;
+	/**
+	* Run one catalog lifecycle tree inside the current queue operation, shared
+	* by the dispatch path, `runDocumentVerb` and the print wrapper. Never
+	* throws: a read or resolution failure degrades to a diagnostic, because a
+	* broken script must not cancel the user's save or print.
+	*/
+	const runDocEventTreeSafe = async (event, diagnose) => {
+		if (!services.settings.get().triggers.document) return null;
 		try {
-			const doc = ctx.doc;
-			if (!doc) return {
-				status: "inert",
-				steps: [],
-				diagnostics
-			};
-			if (!triggerEnabled(trigger)) {
-				diagnose({
-					code: "trigger-disabled",
-					message: `${trigger.scope}: trigger family disabled by config`
-				});
-				return {
-					status: "inert",
-					steps: [],
-					diagnostics
-				};
-			}
-			const origin = originOf(trigger);
-			switch (trigger.scope) {
-				case "activate":
-				case "annotation": {
-					const event = trigger.scope === "activate" ? "activate" : trigger.event;
-					const { annotations } = await doc.page(trigger.pon).annotations.list();
-					const annotation = annotations.find((candidate) => sameRef(candidate.ref, trigger.ref));
-					if (event === "mouseUp" && annotation?.actions?.activate) return {
-						status: "inert",
-						steps: [],
-						diagnostics
-					};
-					const tree = annotation?.actions?.[event];
-					if (!tree?.root && !tree?.incomplete) return {
-						status: "inert",
-						steps: [],
-						diagnostics
-					};
-					const source = trigger.source ?? {
-						kind: "annotation",
-						annotation: trigger.ref,
-						pon: trigger.pon
-					};
-					return await runSteps([{
-						source,
-						tree
-					}], origin, eventOf(trigger), diagnostics);
-				}
-				case "page": {
-					const layout = ctx.document()?.pages.find((page) => page.pageObjectNumber === trigger.pon);
-					const lifecycle = await lifecycleTreesFor(trigger.pon);
-					const steps = planPageSteps(trigger.event, trigger.pon, layout?.actions, lifecycle);
-					return await runSteps(steps, origin, eventOf(trigger), diagnostics);
-				}
-				case "document":
-					if (trigger.event !== "open") return await runDocumentEventOp(trigger.event, diagnostics, diagnose);
-					if (openFired) {
-						diagnose({
-							code: "open-sequence-replayed",
-							message: "document open sequence already fired for this document"
-						});
-						return {
-							status: "inert",
-							steps: [],
-							diagnostics
-						};
+			await ensureOpenSequenceBeforeDocEvent();
+			const tree = (await readDocumentActions())?.[DOC_EVENT_TREES[event]];
+			if (!tree?.root && !tree?.incomplete) return null;
+			return {
+				source: { kind: "document" },
+				tree,
+				result: await runAndEmit(tree, {
+					origin: "lifecycle",
+					source: { kind: "document" },
+					event: {
+						scope: "document",
+						name: event
 					}
-					openFired = true;
-					return await runOpenSequenceOp();
-			}
+				})
+			};
 		} catch (error) {
 			diagnose({
 				code: "trigger-failed",
-				message: `trigger resolution failed: ${error instanceof Error ? error.message : String(error)}`
+				message: `${event}: ${error instanceof Error ? error.message : String(error)}`
+			});
+			return null;
+		}
+	};
+	/** The dispatch-path body for a verb-shaped document event. */
+	const runDocumentEventOp = async (event, diagnostics, diagnose) => {
+		const step = await runDocEventTreeSafe(event, diagnose);
+		return foldSteps(step ? [step] : [], diagnostics);
+	};
+	/**
+	* Both adapter print paths (the Named Print verb, and script `doc.print()`
+	* effects from the actions plane) go through here: /WP →
+	* `ports.uiAdapter.print` exactly once → /DP, with the latch reset in
+	* `finally`. While the latch is held (including `runDocumentVerb('print')`'s
+	* body) a nested request is suppressed with `reentrant-print`. An adapter
+	* throw skips /DP (the latch still resets). /DP fires when the adapter call
+	* returns, since a browser cannot observe dialog completion.
+	*/
+	const firePrintThroughAdapter = async (uiContext, diagnose) => {
+		if (printLatch.active) {
+			diagnose({
+				code: "reentrant-print",
+				message: "print request during a document print event — suppressed (one dialog per request)"
 			});
 			return {
-				status: "refused",
-				steps: [],
-				diagnostics
+				status: "blocked",
+				detail: "reentrant print suppressed"
+			};
+		}
+		if (!allowsPrint()) {
+			diagnose({
+				code: "blocked",
+				message: "print: doc.print is not allowed"
+			});
+			return {
+				status: "blocked",
+				detail: "doc.print is not allowed"
 			};
 		}
+		if (!ports.uiAdapter) {
+			diagnose({
+				code: "no-adapter",
+				message: "print: no UI adapter installed"
+			});
+			return {
+				status: "no-executor",
+				detail: "no UI adapter installed"
+			};
+		}
+		printLatch.active = true;
+		try {
+			await runDocEventTreeSafe("will-print", diagnose);
+			const adapter = ports.uiAdapter;
+			if (!adapter) return {
+				status: "no-executor",
+				detail: "UI adapter uninstalled mid-print"
+			};
+			if (uiContext) adapter.print(uiContext);
+			else adapter.print();
+			await runDocEventTreeSafe("did-print", diagnose);
+			return { status: "executed" };
+		} finally {
+			printLatch.active = false;
+		}
 	};
-	const dispatch = (trigger) => {
-		if (originOf(trigger) === "user") noteUserActivity();
-		return enqueue(() => {
-			jsNodesThisDispatch = 0;
-			return resolveAndRun(trigger);
-		});
+	return {
+		runDocumentEventOp,
+		firePrintThroughAdapter,
+		api: { runDocumentVerb: (verb, operation, options) => enqueue(async () => {
+			budget.scriptNodes = 0;
+			const diagnose = (diagnostic) => reportDiagnostic(diagnostic, { source: { kind: "document" } });
+			const before = verb === "save" ? "will-save" : "will-print";
+			const after = verb === "save" ? "did-save" : "did-print";
+			const body = async () => {
+				await runDocEventTreeSafe(before, diagnose);
+				if (options?.signal?.aborted) throw new PluginError("operation-cancelled", "actions", `${verb} was cancelled`, { cause: options.signal.reason });
+				const value = await operation();
+				await runDocEventTreeSafe(after, diagnose);
+				return value;
+			};
+			if (verb !== "print") return body();
+			printLatch.active = true;
+			try {
+				return await body();
+			} finally {
+				printLatch.active = false;
+			}
+		}, options) }
+	};
+}
+//#endregion
+//#region src/lifecycle/open-sequence.ts
+function createOpenSequence(services, { releaseBarrier, resetCascade }, { runAndEmit }) {
+	const { reportDiagnostic, openSequenceCompleted } = services.events;
+	/** The `openSequence` setting, read when it decides: it applies until the sequence has run. */
+	const mode = () => services.settings.get().openSequence;
+	const { readDocumentActions } = services.catalog;
+	const { enqueue } = services.queue;
+	const ports = services.ports.slots;
+	let openFired = false;
+	let sawUserActivity = false;
+	/** The sequence body. Runs inside the queue (through dispatch or the
+	*  latch's own enqueue); callers guarantee `openFired` was set. */
+	const runOpenSequenceOp = async () => {
+		const diagnostics = [];
+		const steps = [];
+		const openContext = {
+			origin: "lifecycle",
+			source: { kind: "document" },
+			event: {
+				scope: "document",
+				name: "open"
+			}
+		};
+		try {
+			const snapshot = await readDocumentActions();
+			if (snapshot?.openDestination) {
+				const tree = {
+					root: {
+						type: "goto",
+						subtype: "GoTo",
+						destination: snapshot.openDestination,
+						next: []
+					},
+					incomplete: false,
+					warningFlags: 0,
+					warnings: []
+				};
+				steps.push({
+					source: { kind: "document" },
+					tree,
+					result: await runAndEmit(tree, openContext)
+				});
+			}
+			if (snapshot?.openAction?.root || snapshot?.openAction?.incomplete) steps.push({
+				source: { kind: "document" },
+				tree: snapshot.openAction,
+				result: await runAndEmit(snapshot.openAction, openContext)
+			});
+		} catch (error) {
+			const diagnostic = {
+				code: "trigger-failed",
+				message: `open sequence failed: ${error instanceof Error ? error.message : String(error)}`
+			};
+			diagnostics.push(diagnostic);
+			reportDiagnostic(diagnostic, { source: { kind: "document" } });
+		} finally {
+			releaseBarrier(true);
+		}
+		const result = foldSteps(steps, diagnostics);
+		openSequenceCompleted.emit({ result });
+		return result;
+	};
+	/**
+	* The catalog /OpenAction never runs after a /WS, /WP or /WC script: before
+	* the first verb-shaped document event, an armed but unfired open sequence
+	* runs inline (the caller is already inside the queue; `runOpenSequenceOp`
+	* never enqueues). It does not wait for the initial page /O: the guarantee
+	* is catalog-level.
+	*/
+	const ensureOpenSequenceBeforeDocEvent = async () => {
+		if (openFired || mode() === "off") return;
+		openFired = true;
+		await runOpenSequenceOp();
 	};
-	const CASCADE_CAP = 8;
+	const maybeFireOpenSequence = () => {
+		if (openFired) return;
+		if (mode() === "off") {
+			openFired = true;
+			releaseBarrier(false);
+			return;
+		}
+		if (!ports.uiAdapter && mode() !== "headless" && !sawUserActivity) return;
+		openFired = true;
+		enqueue(() => runOpenSequenceOp());
+	};
+	const noteUserActivity = () => {
+		resetCascade();
+		if (!sawUserActivity) {
+			sawUserActivity = true;
+			maybeFireOpenSequence();
+		}
+	};
+	/** Claim the one-shot open for a dispatched document-open trigger: false
+	*  when it already fired (the caller reports a replay). */
+	const claim = () => {
+		if (openFired) return false;
+		openFired = true;
+		return true;
+	};
+	return {
+		run: runOpenSequenceOp,
+		ensureOpenSequenceBeforeDocEvent,
+		noteUserActivity,
+		claim,
+		/** Arm the latch at bringup: fires immediately for 'headless', releases
+		*  the barrier for 'off', waits for an adapter or user activity for 'auto'. */
+		arm: maybeFireOpenSequence,
+		api: { setUiAdapter: (adapter) => {
+			ports.uiAdapter = adapter;
+			if (adapter) maybeFireOpenSequence();
+			return () => {
+				if (ports.uiAdapter === adapter) ports.uiAdapter = null;
+			};
+		} }
+	};
+}
+//#endregion
+//#region src/lifecycle/page-lifecycle.ts
+/**
+* The lifecycle coordinator's page half: the document-open barrier and the
+* cascade budget. The stage owns page truth (it reports through
+* `reportPageState`); this owns when page-lifecycle triggers fire: nothing
+* emits before the document-open sequence has run (or was declared off or
+* headless), and emission is a diff against the last-emitted state, so
+* pre-open motion collapses to one open with no phantom close.
+*/
+/** Consecutive programmatic rounds after which page-lifecycle emission is suppressed. */
+const CASCADE_LIMIT = 8;
+function createPageLifecycle(ctx, { events, settings }, { dispatch }) {
+	const { reportDiagnostic } = events;
 	let barrierOpen = false;
 	let bufferedReport = null;
 	let lastEmitted = {
-		currentPon: null,
+		current: null,
 		visible: /* @__PURE__ */ new Set()
 	};
 	let cascadeRounds = 0;
-	let openFired = false;
-	let sawUserActivity = false;
 	const emitForReport = (report) => {
 		if (report.cause === "user") cascadeRounds = 0;
-		const nextVisible = new Set(report.visiblePons);
-		const changedCurrent = report.currentPon !== lastEmitted.currentPon;
-		const leaving = [...lastEmitted.visible].filter((pon) => !nextVisible.has(pon));
-		const entering = [...nextVisible].filter((pon) => !lastEmitted.visible.has(pon));
+		const current = report.currentPage === null ? null : report.currentPage.objectNumber;
+		const nextVisible = new Set(report.visiblePages.map((page) => page.objectNumber));
+		const changedCurrent = current !== lastEmitted.current;
+		const leaving = [...lastEmitted.visible].filter((pageObjectNumber) => !nextVisible.has(pageObjectNumber));
+		const entering = [...nextVisible].filter((pageObjectNumber) => !lastEmitted.visible.has(pageObjectNumber));
 		if (!changedCurrent && leaving.length === 0 && entering.length === 0) return;
-		const previousCurrent = lastEmitted.currentPon;
+		const previousCurrent = lastEmitted.current;
 		lastEmitted = {
-			currentPon: report.currentPon,
+			current,
 			visible: nextVisible
 		};
 		if (report.cause === "programmatic") {
 			cascadeRounds += 1;
-			if (cascadeRounds > CASCADE_CAP) {
-				diagnosticHook.emit({
+			if (cascadeRounds > CASCADE_LIMIT) {
+				reportDiagnostic({
 					code: "cascade-budget",
-					message: `page-lifecycle emission suppressed: ${cascadeRounds} consecutive programmatic rounds (cap ${CASCADE_CAP})`
+					message: `page-lifecycle emission suppressed: ${cascadeRounds} consecutive programmatic rounds (cap ${CASCADE_LIMIT})`
 				});
 				return;
 			}
@@ -1075,22 +1046,22 @@ function createActionsCapability(ctx, config = {}) {
 		if (changedCurrent && previousCurrent !== null) dispatch({
 			scope: "page",
 			event: "close",
-			pon: previousCurrent
+			page: toPageRef(previousCurrent)
 		});
-		for (const pon of leaving) dispatch({
+		for (const pageObjectNumber of leaving) dispatch({
 			scope: "page",
 			event: "invisible",
-			pon
+			page: toPageRef(pageObjectNumber)
 		});
-		for (const pon of entering) dispatch({
+		for (const pageObjectNumber of entering) dispatch({
 			scope: "page",
 			event: "visible",
-			pon
+			page: toPageRef(pageObjectNumber)
 		});
-		if (changedCurrent && report.currentPon !== null) dispatch({
+		if (changedCurrent && current !== null) dispatch({
 			scope: "page",
 			event: "open",
-			pon: report.currentPon
+			page: toPageRef(current)
 		});
 	};
 	const reportPageState = (report) => {
@@ -1100,331 +1071,806 @@ function createActionsCapability(ctx, config = {}) {
 			bufferedReport = report;
 			return;
 		}
-		emitForReport(report);
+		emitForReport(report);
+	};
+	const releaseBarrier = (fireFallback) => {
+		barrierOpen = true;
+		const report = bufferedReport;
+		bufferedReport = null;
+		try {
+			if (report) emitForReport(report);
+			else if (fireFallback && settings.get().openSequence === "headless") {
+				const first = ctx.document()?.pages[0]?.ref.objectNumber;
+				if (first !== void 0) {
+					lastEmitted = {
+						current: first,
+						visible: lastEmitted.visible
+					};
+					dispatch({
+						scope: "page",
+						event: "open",
+						page: toPageRef(first)
+					});
+				}
+			}
+		} catch (error) {
+			reportDiagnostic({
+				code: "trigger-failed",
+				message: `barrier release failed: ${error instanceof Error ? error.message : String(error)}`
+			});
+		}
+	};
+	return {
+		releaseBarrier,
+		/** A user gesture resets the programmatic-cascade counter. */
+		resetCascade: () => {
+			cascadeRounds = 0;
+		},
+		api: { reportPageState }
+	};
+}
+//#endregion
+//#region src/scripting/world.ts
+/**
+* Script world building (a page-scoped prefetch: the form as the user sees it
+* plus the annotations of the page the action runs on) and the event bridge between
+* two standards: the /AA keys are ISO 32000-2 Table 200; the event names
+* live in the JavaScript API layer (ISO 21757-1, Acrobat).
+*/
+function createScriptWorld(ctx, { form }) {
+	const engineColorToArray = (color) => {
+		if (!color) return ["T"];
+		const { r, g, b } = rgbOf(color);
+		return [
+			"RGB",
+			r / 255,
+			g / 255,
+			b / 255
+		];
+	};
+	const scriptWorldFor = async (pageObjectNumber) => {
+		const page = toPageRef$1(pageObjectNumber);
+		const snapshot = await form.read();
+		const layout = ctx.getPage(page);
+		const pageIndex = Math.max(0, layout?.index ?? -1);
+		const { annotations } = await ctx.doc.page(page).annotations.list();
+		const annots = annotations.filter((annotation) => annotation.subtype !== "link" && !annotation.subtype.startsWith("widget")).map((annotation) => {
+			const inFile = layout ? pdfRectOf(annotation.rect, layout.pdfCropBox) : null;
+			const styled = annotation;
+			return {
+				ref: annotation.ref,
+				name: annotation.nm ?? "",
+				subtype: annotation.subtype,
+				page: pageIndex,
+				rect: inFile ? [
+					inFile.left,
+					inFile.bottom,
+					inFile.right,
+					inFile.top
+				] : [
+					0,
+					0,
+					0,
+					0
+				],
+				contents: annotation.contents ?? "",
+				author: annotation.author ?? "",
+				subject: annotation.subject ?? "",
+				strokeColor: engineColorToArray(styled.color),
+				fillColor: engineColorToArray(styled.interiorColor),
+				opacity: styled.opacity ?? 1,
+				width: styled.strokeWidth ?? 1,
+				borderStyle: styled.borderStyle === "dashed" ? "D" : "S",
+				dash: styled.dashArray ?? [],
+				hidden: annotation.hidden,
+				print: annotation.print,
+				readOnly: annotation.readOnly,
+				locked: annotation.locked,
+				noView: annotation.noView,
+				toggleNoView: annotation.toggleNoView,
+				opaqueBody: annotation.subtype === "stamp"
+			};
+		});
+		return {
+			snapshot,
+			world: {
+				fields: scriptFieldsFromSnapshot(snapshot),
+				annots,
+				annotPages: [pageIndex],
+				annotsCoverDocument: (ctx.document()?.pageCount ?? 0) <= 1
+			}
+		};
+	};
+	const ANNOTATION_EVENT_NAMES = {
+		cursorEnter: "Mouse Enter",
+		cursorExit: "Mouse Exit",
+		mouseDown: "Mouse Down",
+		mouseUp: "Mouse Up",
+		focus: "Focus",
+		blur: "Blur"
+	};
+	const PAGE_EVENT_NAMES = {
+		open: "Open",
+		close: "Close",
+		visible: "Visible",
+		invisible: "Invisible"
+	};
+	const DOC_EVENT_NAMES = {
+		open: "Open",
+		"will-save": "WillSave",
+		"did-save": "DidSave",
+		"will-print": "WillPrint",
+		"did-print": "DidPrint",
+		"will-close": "WillClose"
+	};
+	const scriptEventFor = (actionContext, snapshot) => {
+		const provenance = actionContext.event;
+		const type = provenance.scope === "page" ? "Page" : provenance.scope === "document" ? "Doc" : actionContext.source.kind === "widget" ? "Field" : actionContext.source.kind === "link" ? "Link" : "Annot";
+		const name = provenance.scope === "activate" ? "Mouse Up" : provenance.scope === "annotation" ? ANNOTATION_EVENT_NAMES[provenance.name] ?? "Mouse Up" : provenance.scope === "page" ? PAGE_EVENT_NAMES[provenance.name] ?? "Open" : DOC_EVENT_NAMES[provenance.name] ?? "Open";
+		const targetRef = actionContext.source.kind === "widget" ? actionContext.source.field : void 0;
+		const targetField = targetRef ? snapshot.fields.find((field) => targetRef.kind === "objectNumber" && field.ref.kind === "objectNumber" ? field.ref.objectNumber === targetRef.objectNumber : targetRef.kind === "fqn" && field.name === targetRef.name) : void 0;
+		return {
+			kind: "widget-activate",
+			type,
+			name,
+			...targetRef ? {
+				target: targetRef,
+				source: targetRef
+			} : {},
+			...targetField && targetField.valueEntry.kind === "scalar" ? { value: targetField.valueEntry.value } : {}
+		};
+	};
+	return {
+		scriptWorldFor,
+		scriptEventFor
+	};
+}
+//#endregion
+//#region src/scripting/executor.ts
+/** The default cap on JavaScript nodes one dispatch may run. */
+const DEFAULT_SCRIPT_NODES_PER_DISPATCH = 16;
+function registerScriptExecutor(ctx, services, environment, { scriptHost }, { performSubmit }, { surfaceScriptResult }, documentEvents) {
+	const { reportDiagnostic } = services.events;
+	const ports = services.ports.slots;
+	const { budget } = services.queue;
+	const { firePrintThroughAdapter } = documentEvents;
+	const { scriptWorldFor, scriptEventFor } = createScriptWorld(ctx, services);
+	/** Commit one run's document effects through the owner sinks in the
+	*  declared order (form first, then annotations); the first failure skips
+	*  the rest across both streams. Returns the failure summary, if any. */
+	const commitScriptOutput = async (output, diagnose) => {
+		let failure = null;
+		if (output.formEffects.length > 0) if (!ports.formCommitSink) diagnose({
+			code: "no-commit-sink",
+			message: `script form effects dropped: no form commit sink registered (${output.formEffects.length})`
+		});
+		else {
+			const result = await ports.formCommitSink(output.formEffects);
+			if (result.status === "failed") failure = `form effects: ${result.error ?? "failed"}`;
+		}
+		if (output.annotEffects.length > 0) if (failure) diagnose({
+			code: "executor-failed",
+			message: `script annot effects skipped after form failure (${output.annotEffects.length})`
+		});
+		else if (!ports.annotCommitSink) diagnose({
+			code: "no-commit-sink",
+			message: `script annot effects dropped: no annotation commit sink registered (${output.annotEffects.length})`
+		});
+		else {
+			const entries = output.annotEffects.map((effect) => ({
+				annotObjectNumber: effect.ref.kind === "objectNumber" ? effect.ref.objectNumber : -1,
+				...effect.ref.kind === "objectNumber" ? { page: effect.ref.page } : {},
+				patch: effect.patch
+			}));
+			const firstFailure = (await ports.annotCommitSink(entries)).results.find((entry) => entry.status === "failed");
+			if (firstFailure) failure = `annotation ${firstFailure.annotObjectNumber}: ${firstFailure.error ?? "failed"}`;
+		}
+		if (failure) diagnose({
+			code: "executor-failed",
+			message: `script commit: ${failure}`
+		});
+		return failure;
+	};
+	if (!scriptHost) return;
+	const nodeLimit = environment.maxScriptNodesPerDispatch ?? DEFAULT_SCRIPT_NODES_PER_DISPATCH;
+	ports.executors.set("javascript", async (node, actionContext) => {
+		if (node.type !== "javascript") return {
+			status: "inert",
+			reason: "not a JS node"
+		};
+		if (budget.scriptNodes >= nodeLimit) return {
+			status: "inert",
+			reason: `dispatch script budget exhausted (${nodeLimit} JS nodes)`
+		};
+		budget.scriptNodes += 1;
+		const source = actionContext.source;
+		const firstPage = ctx.document()?.pages[0]?.ref.objectNumber;
+		const pageObjectNumber = source.kind === "widget" || source.kind === "page" ? source.page.objectNumber : source.kind === "link" || source.kind === "annotation" ? source.page?.objectNumber ?? firstPage : firstPage;
+		if (pageObjectNumber === void 0) return {
+			status: "inert",
+			reason: "no page to anchor the world on"
+		};
+		const diagnose = (diagnostic) => reportDiagnostic(diagnostic, {
+			action: "javascript",
+			source
+		});
+		const pendingExternal = [];
+		const splitExternal = (output, phase) => output.uiEffects.filter((effect) => {
+			if (effect.kind === "print" || effect.kind === "submitForm") {
+				pendingExternal.push({
+					effect,
+					phase
+				});
+				return false;
+			}
+			return true;
+		});
+		const outcome = await scriptHost.transaction(async (transaction) => {
+			let built = await scriptWorldFor(pageObjectNumber);
+			const boot = await transaction.boot({
+				...built.world,
+				event: {
+					kind: "name-tree-boot",
+					type: "Doc",
+					name: "Open"
+				}
+			});
+			if (boot) {
+				await commitScriptOutput(boot, diagnose);
+				surfaceScriptResult({
+					uiEffects: splitExternal(boot, "boot"),
+					diagnostics: boot.diagnostics,
+					...boot.error ? { error: boot.error } : {},
+					origin: actionContext.origin,
+					phase: "boot",
+					realm: "document",
+					source
+				});
+				if (boot.formEffects.length || boot.annotEffects.length) built = await scriptWorldFor(pageObjectNumber);
+			}
+			const output = await transaction.run(node.script, {
+				...built.world,
+				event: scriptEventFor(actionContext, built.snapshot)
+			});
+			surfaceScriptResult({
+				uiEffects: splitExternal(output, "user"),
+				diagnostics: output.diagnostics,
+				...output.error ? { error: output.error } : {},
+				origin: actionContext.origin,
+				phase: "user",
+				realm: "document",
+				source
+			});
+			if (output.error) return {
+				status: "failed",
+				error: output.error.message
+			};
+			const failure = await commitScriptOutput(output, diagnose);
+			return failure ? {
+				status: "failed",
+				error: failure
+			} : { status: "executed" };
+		});
+		for (const entry of pendingExternal) if (entry.effect.kind === "print") await firePrintThroughAdapter({
+			origin: actionContext.origin,
+			phase: entry.phase
+		}, diagnose);
+		else await performSubmit(intentOfSubmitEffect(entry.effect), actionContext, diagnose);
+		return outcome;
+	});
+}
+//#endregion
+//#region src/scripting/environment.ts
+function createScriptRealmFactory(environment, identity, identityDoc) {
+	const sandboxFactory = environment.sandboxFactory ?? (() => import("@embedpdf/core-js-sandbox").then(({ createQuickJsSandbox }) => createQuickJsSandbox()));
+	const budget = environment.budget ?? DEFAULT_SCRIPT_BUDGET;
+	return {
+		budget,
+		realmFor: (target) => createScriptHost({
+			sandboxFactory,
+			document: () => {
+				const documentInfo = target.document();
+				return {
+					id: target.doc.id,
+					fileName: environment.fileName?.() ?? documentInfo?.name ?? "document.pdf",
+					pageCount: documentInfo?.pageCount ?? 0,
+					pageNumber: 0
+				};
+			},
+			identity: () => resolveScriptIdentity(identityDoc, identity()),
+			environment: (sequence) => {
+				const nowMs = environment.now?.() ?? Date.now();
+				return {
+					nowMs,
+					utcOffsetMinutes: environment.utcOffsetMinutes?.() ?? -new Date(nowMs).getTimezoneOffset(),
+					randomSeed: environment.randomSeed?.() ?? seedFrom(target.doc.id, sequence)
+				};
+			},
+			bootSources: target.bootSources,
+			budget
+		})
+	};
+}
+//#endregion
+//#region src/scripting/realm.ts
+/**
+* The one ScriptHost per document. The `javascript.enabled` setting, as it is
+* when the document opens, decides whether a realm factory exists; the
+* factory carries the session environment and mints this document's own
+* realm here, and detached realms on demand (host lens): one environment, any
+* number of isolated realms.
+*/
+function createRealm(ctx, { catalog, settings }, environment) {
+	const { readDocumentActions } = catalog;
+	const realms = settings.get().javascript.enabled ? createScriptRealmFactory(environment, () => settings.get().javascript.identity ?? void 0, ctx.doc) : null;
+	const scriptHost = realms ? realms.realmFor({
+		doc: ctx.doc,
+		document: () => ctx.document(),
+		bootSources: async () => {
+			return ((await readDocumentActions())?.nameTreeScripts ?? []).map(({ action }) => javaScriptProgramFromActionTree(action));
+		}
+	}) : null;
+	if (scriptHost) ctx.cleanup(() => scriptHost.dispose());
+	return {
+		scriptHost,
+		api: {
+			isScriptingEnabled: () => scriptHost !== null,
+			...scriptHost && realms ? {
+				scriptRealm: {
+					transaction: (body) => scriptHost.transaction(body),
+					budget: realms.budget
+				},
+				createDetachedScriptRealm: (target) => {
+					const host = realms.realmFor(target);
+					return {
+						transaction: (body) => host.transaction(body),
+						budget: realms.budget,
+						dispose: () => host.dispose()
+					};
+				}
+			} : {}
+		}
+	};
+}
+//#endregion
+//#region src/scripting/surface.ts
+function createScriptSurface(services, { performSubmit }) {
+	const { reportDiagnostic, scriptDiagnosticReported, scriptFailed } = services.events;
+	const ports = services.ports.slots;
+	const { allowsPrint } = services.authority;
+	const printLatch = services.printLatch;
+	const surfaceScriptResult = (result) => {
+		const uiContext = {
+			origin: result.origin,
+			phase: result.phase
+		};
+		const source = result.source ?? null;
+		for (const effect of result.uiEffects) {
+			if (result.realm === "detached" && effect.kind !== "alert") {
+				scriptDiagnosticReported.emit({
+					code: "ui-effect-suppressed",
+					message: `script ${effect.kind} request from a detached realm suppressed: no document surface`
+				});
+				continue;
+			}
+			if (effect.kind === "submitForm") {
+				performSubmit(intentOfSubmitEffect(effect), {
+					origin: result.origin,
+					source: result.source ?? { kind: "api" },
+					event: { scope: "activate" }
+				}, (diagnostic) => reportDiagnostic(diagnostic, {
+					action: "javascript",
+					source
+				}));
+				continue;
+			}
+			if (effect.kind === "print" && !allowsPrint()) {
+				scriptDiagnosticReported.emit({
+					code: "ui-effect-suppressed",
+					message: "script print request withheld: doc.print is not allowed"
+				});
+				continue;
+			}
+			if (effect.kind === "print" && printLatch.active) {
+				scriptDiagnosticReported.emit({
+					code: "ui-effect-suppressed",
+					message: "script print request during a document print event — suppressed (reentrant)"
+				});
+				continue;
+			}
+			if (!ports.uiAdapter) {
+				reportDiagnostic({
+					code: "no-adapter",
+					message: `script ${effect.kind}: no UI adapter installed`
+				}, {
+					action: "javascript",
+					source
+				});
+				continue;
+			}
+			if (effect.kind === "alert") ports.uiAdapter.alert?.(effect.message, {
+				...uiContext,
+				icon: effect.icon,
+				...effect.title !== void 0 ? { title: effect.title } : {}
+			});
+			else if (effect.kind === "gotoPage") ports.uiAdapter.gotoPage?.(effect.page, uiContext);
+			else ports.uiAdapter.print(uiContext);
+		}
+		for (const diagnostic of result.diagnostics) scriptDiagnosticReported.emit(diagnostic);
+		if (result.error) scriptFailed.emit({
+			error: result.error,
+			source
+		});
+	};
+	/** A K/V/C/F commit surfaces as up to two results: the boot phase (only
+	*  when it produced effects) and the user phase (always — it carries the
+	*  diagnostics and the error). */
+	const surfaceScriptCommit = (commit, context) => {
+		for (const phase of ["boot", "user"]) {
+			const uiEffects = commit.uiEffects.filter((effect) => effect.phase === phase);
+			if (uiEffects.length === 0 && phase === "boot") continue;
+			surfaceScriptResult({
+				uiEffects,
+				diagnostics: phase === "user" ? commit.diagnostics : [],
+				...phase === "user" && commit.error ? { error: commit.error } : {},
+				origin: context.origin,
+				phase,
+				realm: context.realm,
+				...context.source ? { source: context.source } : {}
+			});
+		}
+	};
+	return {
+		surfaceScriptResult,
+		api: {
+			surfaceScriptResult,
+			surfaceScriptCommit
+		}
+	};
+}
+//#endregion
+//#region src/services/authority.ts
+function createAuthority(ctx) {
+	const allowsPrint = () => ctx.allows("doc.print");
+	return { allowsPrint };
+}
+//#endregion
+//#region src/services/catalog.ts
+/** The ISO 32000-2 Table 200 key for each verb-shaped document trigger event. */
+const DOC_EVENT_TREES = {
+	"will-save": "willSave",
+	"did-save": "didSave",
+	"will-print": "willPrint",
+	"did-print": "didPrint",
+	"will-close": "willClose"
+};
+function createCatalog(ctx) {
+	let snapshotRead = null;
+	const readDocumentActions = () => {
+		if (!snapshotRead) {
+			const service = ctx.doc.actions;
+			const memoized = (service ? Promise.resolve(service.get()) : Promise.resolve(null)).catch((error) => {
+				if (snapshotRead === memoized) snapshotRead = null;
+				throw error;
+			});
+			snapshotRead = memoized;
+		}
+		return snapshotRead;
 	};
-	const releaseBarrier = (fireFallback) => {
-		barrierOpen = true;
-		const report = bufferedReport;
-		bufferedReport = null;
-		try {
-			if (report) emitForReport(report);
-			else if (fireFallback && config.openSequence === "headless") {
-				const first = ctx.document()?.pages[0]?.pageObjectNumber;
-				if (first !== void 0) {
-					lastEmitted = {
-						currentPon: first,
-						visible: lastEmitted.visible
-					};
-					dispatch({
-						scope: "page",
-						event: "open",
-						pon: first
-					});
-				}
-			}
-		} catch (error) {
-			diagnosticHook.emit({
-				code: "trigger-failed",
-				message: `barrier release failed: ${error instanceof Error ? error.message : String(error)}`
+	return {
+		readDocumentActions,
+		DOC_EVENT_TREES
+	};
+}
+//#endregion
+//#region src/services/events.ts
+function createEvents(ctx) {
+	const executed = ctx.events.source();
+	const diagnosticReported = ctx.events.source();
+	return {
+		executed,
+		diagnosticReported,
+		scriptDiagnosticReported: ctx.events.source(),
+		scriptFailed: ctx.events.source(),
+		openSequenceCompleted: ctx.events.source(),
+		/** Fire `onDiagnosticReported` with the action and source it concerns (`null` for none). */
+		reportDiagnostic(diagnostic, place = {}) {
+			diagnosticReported.emit({
+				code: diagnostic.code,
+				action: place.action ?? null,
+				source: place.source ?? null
 			});
 		}
 	};
-	/** The §3.9 sequence body — runs INSIDE the queue (via dispatch or the
-	*  latch's own enqueue; callers guarantee openFired was set). */
-	const runOpenSequenceOp = async () => {
-		const diagnostics = [];
-		const steps = [];
-		const lifecycleCtx = {
-			origin: "lifecycle",
-			source: { kind: "document" },
-			event: {
-				scope: "document",
-				name: "open"
-			}
-		};
-		try {
-			const snapshot = await readDocumentActions();
-			if (snapshot?.openDestination) {
-				const tree = {
-					root: {
-						type: "goto",
-						subtype: "GoTo",
-						destination: snapshot.openDestination,
-						next: []
-					},
-					incomplete: false,
-					warningFlags: 0,
-					warnings: []
+}
+//#endregion
+//#region src/services/form.ts
+function createForm(ctx, ports) {
+	return { read: (read = (task) => task) => {
+		const shown = ports.formReader?.();
+		return shown ? Promise.resolve(shown) : read(ctx.doc.forms.list());
+	} };
+}
+//#endregion
+//#region src/services/ports.ts
+function createPorts({ reportDiagnostic }) {
+	const ports = {
+		executors: /* @__PURE__ */ new Map(),
+		annotCommitSink: null,
+		formCommitSink: null,
+		formReader: null,
+		uiAdapter: null,
+		submitHandler: null,
+		submitResolver: null
+	};
+	return {
+		slots: ports,
+		api: {
+			registerExecutor: (type, executor) => {
+				if (ports.executors.has(type)) reportDiagnostic({
+					code: "duplicate-executor",
+					message: `executor for '${type}' replaced (last-wins)`
+				}, { action: type });
+				ports.executors.set(type, executor);
+				return () => {
+					if (ports.executors.get(type) === executor) ports.executors.delete(type);
+				};
+			},
+			registerAnnotCommitSink: (sink) => {
+				ports.annotCommitSink = sink;
+				return () => {
+					if (ports.annotCommitSink === sink) ports.annotCommitSink = null;
+				};
+			},
+			registerFormCommitSink: (sink) => {
+				ports.formCommitSink = sink;
+				return () => {
+					if (ports.formCommitSink === sink) ports.formCommitSink = null;
+				};
+			},
+			registerFormReader: (reader) => {
+				ports.formReader = reader;
+				return () => {
+					if (ports.formReader === reader) ports.formReader = null;
+				};
+			},
+			setSubmitHandler: (handler) => {
+				ports.submitHandler = handler;
+				return () => {
+					if (ports.submitHandler === handler) ports.submitHandler = null;
+				};
+			},
+			registerSubmitResolver: (resolver) => {
+				ports.submitResolver = resolver;
+				return () => {
+					if (ports.submitResolver === resolver) ports.submitResolver = null;
 				};
-				steps.push({
-					source: { kind: "document" },
-					tree,
-					result: await runAndEmit(tree, lifecycleCtx)
-				});
 			}
-			if (snapshot?.openAction?.root || snapshot?.openAction?.incomplete) steps.push({
-				source: { kind: "document" },
-				tree: snapshot.openAction,
-				result: await runAndEmit(snapshot.openAction, lifecycleCtx)
-			});
-		} catch (error) {
-			const diagnostic = {
-				code: "trigger-failed",
-				message: `open sequence failed: ${error instanceof Error ? error.message : String(error)}`
-			};
-			diagnostics.push(diagnostic);
-			diagnosticHook.emit(diagnostic);
-		} finally {
-			releaseBarrier(true);
 		}
-		return foldSteps(steps, diagnostics);
 	};
-	/**
-	* D1's open-ordering law: catalog `OpenAction` may never run AFTER a
-	* WillSave/WillPrint/WillClose script. Before the first verb-shaped
-	* document event, an armed-but-unfired open sequence runs inline (we are
-	* already inside the queue; `runOpenSequenceOp` never enqueues). It does
-	* NOT wait for the initial page `/O` — the guarantee is catalog-level.
-	*/
-	const ensureOpenSequenceBeforeDocEvent = async () => {
-		if (openFired || config.openSequence === "off") return;
-		openFired = true;
-		await runOpenSequenceOp();
+}
+//#endregion
+//#region src/services/print-latch.ts
+const createPrintLatch = () => ({ active: false });
+//#endregion
+//#region src/services/queue.ts
+function createQueue(ctx) {
+	return {
+		enqueue: ctx.serialQueue("actions"),
+		budget: { scriptNodes: 0 }
+	};
+}
+//#endregion
+//#region src/services/index.ts
+function createServices(ctx) {
+	const events = createEvents(ctx);
+	const ports = createPorts(events);
+	return {
+		settings: ctx.settings(),
+		events,
+		policy: createPolicy(ctx),
+		ports,
+		queue: createQueue(ctx),
+		catalog: createCatalog(ctx),
+		form: createForm(ctx, ports.slots),
+		authority: createAuthority(ctx),
+		printLatch: createPrintLatch()
 	};
+}
+//#endregion
+//#region src/submit/perform.ts
+function createSubmit(ctx, services, environment) {
+	const policy = services.policy;
+	const ports = services.ports.slots;
+	const { reportDiagnostic } = services.events;
+	const nowMs = () => environment.now?.() ?? Date.now();
 	/**
-	* Run ONE catalog lifecycle tree inside the current queue operation —
-	* shared by the dispatch path, `runDocumentVerb`, and the print wrapper.
-	* Never throws: a read/resolution failure degrades to a diagnostic (a
-	* broken script must not cancel the user's save/print — D2).
+	* The one submit door. Sink order: the embedder handler (explicit beats
+	* ambient; its promise is not awaited) → the document's home
+	* (`doc.forms.submit`, engine-asserted and awaited: a real operation with a
+	* real receipt) → blocked with `no-submit-sink`.
 	*/
-	const runDocEventTreeSafe = async (event, diagnose) => {
-		if (config.triggers?.document === false) return null;
-		try {
-			await ensureOpenSequenceBeforeDocEvent();
-			const tree = (await readDocumentActions())?.[DOC_EVENT_TREES[event]];
-			if (!tree?.root && !tree?.incomplete) return null;
-			return {
-				source: { kind: "document" },
-				tree,
-				result: await runAndEmit(tree, {
-					origin: "lifecycle",
-					source: { kind: "document" },
-					event: {
-						scope: "document",
-						name: event
-					}
-				})
-			};
-		} catch (error) {
-			diagnose({
-				code: "trigger-failed",
-				message: `${event}: ${error instanceof Error ? error.message : String(error)}`
+	const performSubmit = async (intent, actionContext, diagnose) => {
+		const decision = policy.current()["submit-form"][actionContext.origin];
+		if (decision !== "adapter" && decision !== "allow") {
+			if (decision === "report") diagnose({
+				code: "blocked",
+				message: `submit-form: policy 'report' for origin '${actionContext.origin}'`
 			});
-			return null;
+			return { status: "blocked" };
 		}
-	};
-	/** The dispatch-path body for a verb-shaped document event. */
-	const runDocumentEventOp = async (event, diagnostics, diagnose) => {
-		const step = await runDocEventTreeSafe(event, diagnose);
-		return foldSteps(step ? [step] : [], diagnostics);
-	};
-	/**
-	* D3: BOTH adapter print invocations (the Named Print verb; script
-	* `doc.print()` effects from the actions plane) go through here — WP →
-	* `uiAdapter.print` exactly once → DP, latch reset in `finally`. While
-	* the latch is held (including `runDocumentVerb('print')`'s body) a
-	* nested request is suppressed with `reentrant-print`. An adapter throw
-	* skips DP (the latch still resets) — named deviation: DP otherwise
-	* fires when the adapter call RETURNS, since a browser cannot observe
-	* dialog completion.
-	*/
-	const firePrintThroughAdapter = async (uiContext, diagnose) => {
-		if (docPrintEventActive) {
+		if (!ports.submitResolver) {
 			diagnose({
-				code: "reentrant-print",
-				message: "print request during a document print event — suppressed (one dialog per request)"
+				code: "no-submit-resolver",
+				message: "submit-form: no dataset resolver registered (form plugin missing?)"
 			});
 			return {
 				status: "blocked",
-				detail: "reentrant print suppressed"
+				detail: "no dataset resolver"
 			};
 		}
-		if (!allowsPrint()) {
+		let request;
+		try {
+			request = await ports.submitResolver(intent, actionContext, diagnose);
+		} catch (error) {
+			const detail = error instanceof Error ? error.message : String(error);
 			diagnose({
-				code: "blocked",
-				message: "print: doc.print is not allowed"
+				code: "executor-failed",
+				message: `submit-form: dataset resolution: ${detail}`
 			});
 			return {
-				status: "blocked",
-				detail: "doc.print is not allowed"
+				status: "failed",
+				detail
 			};
 		}
-		if (!uiAdapter) {
+		const forms = ctx.doc.forms;
+		const homeSubmit = typeof forms.submit === "function" ? () => Promise.resolve(forms.submit(toFormSubmissionRequest(request, new Date(nowMs()).toISOString()))) : null;
+		if (ports.submitHandler) try {
+			const outcome = ports.submitHandler(request, { submitToDocumentHome: homeSubmit });
+			if (outcome && typeof outcome.then === "function") outcome.catch((error) => {
+				reportDiagnostic({
+					code: "executor-failed",
+					message: `submit handler rejected (detached): ${error instanceof Error ? error.message : String(error)}`
+				}, {
+					action: "submit-form",
+					source: actionContext.source
+				});
+			});
+			return { status: "executed" };
+		} catch (error) {
+			const detail = error instanceof Error ? error.message : String(error);
 			diagnose({
-				code: "no-adapter",
-				message: "print: no UI adapter installed"
+				code: "executor-failed",
+				message: `submit handler threw: ${detail}`
 			});
 			return {
-				status: "no-executor",
-				detail: "no UI adapter installed"
+				status: "failed",
+				detail
 			};
 		}
-		docPrintEventActive = true;
-		try {
-			await runDocEventTreeSafe("will-print", diagnose);
-			const adapter = uiAdapter;
-			if (!adapter) return {
-				status: "no-executor",
-				detail: "UI adapter uninstalled mid-print"
-			};
-			if (uiContext) adapter.print(uiContext);
-			else adapter.print();
-			await runDocEventTreeSafe("did-print", diagnose);
+		if (homeSubmit) try {
+			await homeSubmit();
 			return { status: "executed" };
-		} finally {
-			docPrintEventActive = false;
-		}
-	};
-	const maybeFireOpenSequence = () => {
-		if (openFired) return;
-		if (config.openSequence === "off") {
-			openFired = true;
-			releaseBarrier(false);
-			return;
+		} catch (error) {
+			const detail = error instanceof Error ? error.message : String(error);
+			diagnose({
+				code: "executor-failed",
+				message: `document home refused submit: ${detail}`
+			});
+			return {
+				status: "failed",
+				detail
+			};
 		}
-		if (!uiAdapter && config.openSequence !== "headless" && !sawUserActivity) return;
-		openFired = true;
-		enqueue(() => runOpenSequenceOp());
+		diagnose({
+			code: "no-submit-sink",
+			message: "submit-form: no handler installed and the document has no submit-capable home"
+		});
+		return {
+			status: "blocked",
+			detail: "no submit sink"
+		};
 	};
-	const noteUserActivity = () => {
-		cascadeRounds = 0;
-		if (!sawUserActivity) {
-			sawUserActivity = true;
-			maybeFireOpenSequence();
-		}
+	return { performSubmit };
+}
+//#endregion
+//#region src/controller.ts
+/**
+* The actions controller: the composition root. It builds the plugin's
+* services once, wires each area with the services it declares, and
+* assembles the host capability from the areas' API slices. No behavior
+* lives here: every verb and read has a home in `submit/`, `scripting/`,
+* `dispatch/` or `lifecycle/`. The plugin keeps no session state: its rules
+* are its settings, and its live data (ports, queue, latches) are resources
+* of the areas.
+*/
+/**
+* `config` is what the app registered; the settings in it reach the
+* controller through `ctx.settings()`, and only the script environment is
+* read from it here.
+*/
+function createActionsController(ctx, config = {}) {
+	const services = createServices(ctx);
+	const { events, ports, settings } = services;
+	const core = {
+		dispatch: (trigger) => dispatcher.dispatch(trigger),
+		runAndEmit: (tree, actionContext) => dispatcher.runAndEmit(tree, actionContext)
 	};
-	maybeFireOpenSequence();
+	const environment = config.javascript ?? {};
+	const submit = createSubmit(ctx, services, environment);
+	const realm = createRealm(ctx, services, environment);
+	const surface = createScriptSurface(services, submit);
+	const pageLifecycle = createPageLifecycle(ctx, services, core);
+	const openSequence = createOpenSequence(services, pageLifecycle, core);
+	const documentEvents = createDocumentEvents(services, openSequence, core);
+	const triggers = createTriggers(ctx, services);
+	const dispatcher = createDispatcher(ctx, services, createRunner(ctx, services, submit, documentEvents), triggers, openSequence, documentEvents);
+	registerScriptExecutor(ctx, services, environment, realm, submit, surface, documentEvents);
 	return {
-		execute,
-		canExecute,
-		dispatch,
-		canDispatch: (trigger) => triggerEnabled(trigger) && ctx.doc !== null,
-		setUiAdapter: (adapter) => {
-			uiAdapter = adapter;
-			if (adapter) maybeFireOpenSequence();
-			return () => {
-				if (uiAdapter === adapter) uiAdapter = null;
-			};
-		},
-		runDocumentVerb: (verb, operation) => enqueue(async () => {
-			jsNodesThisDispatch = 0;
-			const diagnose = (diagnostic) => diagnosticHook.emit(diagnostic);
-			const before = verb === "save" ? "will-save" : "will-print";
-			const after = verb === "save" ? "did-save" : "did-print";
-			const body = async () => {
-				await runDocEventTreeSafe(before, diagnose);
-				const value = await operation();
-				await runDocEventTreeSafe(after, diagnose);
-				return value;
-			};
-			if (verb !== "print") return body();
-			docPrintEventActive = true;
-			try {
-				return await body();
-			} finally {
-				docPrintEventActive = false;
-			}
-		}),
-		prepareClose: () => dispatch({
-			scope: "document",
-			event: "will-close"
-		}),
-		setSubmitHandler: (handler) => {
-			submitHandler = handler;
-			return () => {
-				if (submitHandler === handler) submitHandler = null;
-			};
-		},
-		onAction: actionHook.on,
-		onDiagnostic: diagnosticHook.on,
-		onScriptDiagnostic: scriptDiagnosticHook.on,
-		onScriptError: scriptErrorHook.on,
-		registerExecutor: (type, executor) => {
-			if (executors.has(type)) diagnosticHook.emit({
-				code: "duplicate-executor",
-				message: `executor for '${type}' replaced (last-wins)`
-			});
-			executors.set(type, executor);
-			return () => {
-				if (executors.get(type) === executor) executors.delete(type);
-			};
-		},
-		registerAnnotCommitSink: (sink) => {
-			annotCommitSink = sink;
-			return () => {
-				if (annotCommitSink === sink) annotCommitSink = null;
-			};
-		},
-		registerFormCommitSink: (sink) => {
-			formCommitSink = sink;
-			return () => {
-				if (formCommitSink === sink) formCommitSink = null;
-			};
-		},
-		...scriptHost && realms ? {
-			scriptRealm: {
-				transaction: (body) => scriptHost.transaction(body),
-				budget: realms.budget
-			},
-			createDetachedScriptRealm: (target) => {
-				const host = realms.realmFor(target);
-				return {
-					transaction: (body) => host.transaction(body),
-					budget: realms.budget,
-					dispose: () => host.dispose()
-				};
+		api: composeApi("actions", [
+			settings.api,
+			ports.api,
+			realm.api,
+			surface.api,
+			pageLifecycle.api,
+			openSequence.api,
+			documentEvents.api,
+			dispatcher.api,
+			{
+				onExecuted: events.executed.on,
+				onDiagnosticReported: events.diagnosticReported.on,
+				onScriptDiagnosticReported: events.scriptDiagnosticReported.on,
+				onScriptFailed: events.scriptFailed.on,
+				onOpenSequenceCompleted: events.openSequenceCompleted.on
 			}
-		} : {},
-		surfaceScriptResult,
-		surfaceScriptCommit,
-		reportPageState,
-		registerSubmitResolver: (resolver) => {
-			submitResolver = resolver;
-			return () => {
-				if (submitResolver === resolver) submitResolver = null;
-			};
+		]),
+		connect() {
+			ctx.listen(ctx.doc.events, (event) => triggers.invalidate(event));
+			openSequence.arm();
+			ctx.aroundDownload((read) => documentEvents.api.runDocumentVerb("save", read));
 		}
 	};
 }
 //#endregion
-//#region src/reducer.ts
-const initialActionsState = () => ({ seq: 0 });
-function actionsReducer(state, action) {
-	switch (action.type) {
-		case "ACTIONS_DISPATCHED": return { seq: state.seq + 1 };
-		default: return state;
-	}
+//#region src/settings.ts
+/** `config` without the script environment, which is no setting: what the settings register. */
+function registeredSettings(config) {
+	if (!config) return void 0;
+	const { javascript } = config;
+	return {
+		policy: config.policy,
+		triggers: config.triggers,
+		openSequence: config.openSequence,
+		javascript: javascript && {
+			enabled: javascript.enabled,
+			identity: javascript.identity
+		}
+	};
 }
 //#endregion
 //#region src/actions.plugin.ts
 /**
-* The action engine: the DEPENDENCY ROOT of the action architecture. It
+* The action engine, the dependency root of the action architecture. It
 * interprets extracted /A and /AA trees; it never detects triggers and never
-* imports another plugin's token — stage, annotation, link, and form
-* optionally depend on ActionsToken and register their executors and sinks
-* at init (the kernel's topological order guarantees this plugin initializes
+* imports another plugin's token: the stage, annotation, link and form
+* plugins optionally depend on it and register their executors and sinks
+* when they connect (the kernel's dependency order creates this plugin
 * first). JavaScript is one registered interpreter among many: Hide,
-* ResetForm, GoTo, and Named work with scripting off.
+* ResetForm, GoTo and Named work with scripting off. Document-scoped and
+* stateless; its settings are what the app registered over
+* {@link ACTIONS_DEFAULTS}.
 */
 const actionsPlugin = (config) => definePlugin({
 	id: "actions",
-	token: ActionsToken,
+	token: ActionsToken$1,
 	scope: "document",
-	initialState: initialActionsState,
-	reduce: actionsReducer,
-	capability: (ctx) => createActionsCapability(ctx, config)
+	settings: {
+		defaults: ACTIONS_DEFAULTS,
+		registered: registeredSettings(config)
+	},
+	create: (ctx) => createActionsController(ctx, config)
 });
 //#endregion
-export { ActionsToken, actionsPlugin, createHoverPump, originOf, submitEntriesToUrlEncoded };
+export { ACTIONS_DEFAULTS, ActionsToken, actionsPlugin, createHoverPump, eventOf, submitEntriesToUrlEncoded, triggerOriginOf };
 
 //# sourceMappingURL=index.js.map