@embedpdf/plugin-form 3.0.0-next.14 → 3.0.0-next.16

package/dist/index.cjs

@@ -1,28 +1,2520 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_scripting = require("./scripting.cjs");
-const require_types = require("./types-C1uIIYfn.cjs");
-const require_contract = require("./contract.cjs");
+const require_contract = require("./contract-CU0jrI_D.cjs");
+const require_controller = require("./controller-CS6tV2m1.cjs");
+const require_contract_host = require("./contract/host.cjs");
 let _embedpdf_core = require("@embedpdf/core");
 let _embedpdf_plugin_actions_contract = require("@embedpdf/plugin-actions/contract");
-let _embedpdf_plugin_actions_contract_host = require("@embedpdf/plugin-actions/contract/host");
 let _embedpdf_plugin_annotation_contract = require("@embedpdf/plugin-annotation/contract");
-let _embedpdf_plugin_annotation_contract_host = require("@embedpdf/plugin-annotation/contract/host");
-let _embedpdf_plugin_interaction_contract = require("@embedpdf/plugin-interaction/contract");
+let _embedpdf_plugin_interaction_contract_host = require("@embedpdf/plugin-interaction/contract/host");
+let _embedpdf_plugin_render_contract = require("@embedpdf/plugin-render/contract");
 let _embedpdf_engine_core_runtime = require("@embedpdf/engine-core/runtime");
-let _embedpdf_plugin_annotation_authoring = require("@embedpdf/plugin-annotation/authoring");
+let _embedpdf_plugin_actions_contract_host = require("@embedpdf/plugin-actions/contract/host");
+let _embedpdf_plugin_annotation_contract_host = require("@embedpdf/plugin-annotation/contract/host");
+let _embedpdf_core_annotation = require("@embedpdf/core-annotation");
+let _embedpdf_core_form = require("@embedpdf/core-form");
+let _embedpdf_plugin_render_contract_host = require("@embedpdf/plugin-render/contract/host");
+let _embedpdf_engine_core_public = require("@embedpdf/engine-core/public");
+//#region src/tools/definitions.ts
+/** Palette tools keep widgets editable right after placement. */
+const PLACE_TAGS = ["form-place", "annotation-edit"];
+const FIELD_CHROME = {
+	interiorColor: "#ffffff",
+	color: "#6b7280",
+	strokeWidth: 1
+};
+const FORM_TOOLS = [
+	{
+		id: "form-text",
+		family: "text",
+		visualKind: "widget-text",
+		clickCreate: {
+			width: 160,
+			height: 24
+		},
+		defaults: {
+			...FIELD_CHROME,
+			fontSize: 12
+		},
+		cursor: "crosshair"
+	},
+	{
+		id: "form-checkbox",
+		family: "checkbox",
+		visualKind: "widget-toggle",
+		clickCreate: {
+			width: 18,
+			height: 18
+		},
+		defaults: FIELD_CHROME,
+		cursor: "crosshair"
+	},
+	{
+		id: "form-radio",
+		family: "radio",
+		visualKind: "widget-radio",
+		clickCreate: {
+			width: 18,
+			height: 18
+		},
+		defaults: FIELD_CHROME,
+		cursor: "crosshair"
+	},
+	{
+		id: "form-combobox",
+		family: "combobox",
+		visualKind: "widget-choice",
+		clickCreate: {
+			width: 140,
+			height: 24
+		},
+		defaults: {
+			...FIELD_CHROME,
+			fontSize: 12
+		},
+		cursor: "crosshair"
+	},
+	{
+		id: "form-listbox",
+		family: "listbox",
+		visualKind: "widget-choice",
+		clickCreate: {
+			width: 140,
+			height: 72
+		},
+		defaults: {
+			...FIELD_CHROME,
+			fontSize: 12
+		},
+		cursor: "crosshair"
+	},
+	{
+		id: "form-button",
+		family: "pushbutton",
+		visualKind: "widget-button",
+		clickCreate: {
+			width: 100,
+			height: 28
+		},
+		defaults: {
+			...FIELD_CHROME,
+			interiorColor: "#e5e7eb",
+			fontSize: 12
+		},
+		cursor: "crosshair"
+	},
+	{
+		id: "form-signature",
+		family: "signature",
+		visualKind: "widget-box",
+		clickCreate: {
+			width: 160,
+			height: 48
+		},
+		defaults: FIELD_CHROME,
+		cursor: "crosshair"
+	}
+];
+const FORM_TOOL_BY_ID = new Map(FORM_TOOLS.map((tool) => [tool.id, tool]));
+//#endregion
+//#region src/tools/handlers.ts
+/** A name for a field placed with a tool: `text_1`, `text_2`, …, the first one the form doesn't have. */
+function nextFieldName(family, taken) {
+	let count = 1;
+	while (taken.has(`${family}_${count}`)) count++;
+	return `${family}_${count}`;
+}
+/** The part of a box on the page; `null` when too little of it is. */
+function clampToPage(box, page) {
+	const x = Math.max(page.x, Math.min(box.x, page.width));
+	const y = Math.max(page.y, Math.min(box.y, page.height));
+	const clamped = {
+		x,
+		y,
+		width: Math.max(0, Math.min(box.x + box.width, page.width) - x),
+		height: Math.max(0, Math.min(box.y + box.height, page.height) - y)
+	};
+	return clamped.width < 1 || clamped.height < 1 ? null : clamped;
+}
+/**
+* The field a palette tool places: one widget at `widget`, named like
+* `text_1`. A radio button stands for `'Choice1'` and a dropdown or a list
+* starts with two options, as in Acrobat; rename and change them in a
+* settings panel.
+*/
+function toolDraft(tool, name, widget) {
+	switch (tool.family) {
+		case "radio": return {
+			family: "radio",
+			name,
+			widgets: [{
+				...widget,
+				exportValue: "Choice1"
+			}]
+		};
+		case "combobox":
+		case "listbox": return {
+			family: tool.family,
+			name,
+			widgets: [widget],
+			options: [{
+				label: "Option 1",
+				value: "Option 1"
+			}, {
+				label: "Option 2",
+				value: "Option 2"
+			}]
+		};
+		case "pushbutton": return {
+			family: "pushbutton",
+			name,
+			widgets: [{
+				...widget,
+				caption: "Button"
+			}]
+		};
+		default: return {
+			family: tool.family,
+			name,
+			widgets: [widget]
+		};
+	}
+}
+/**
+* Draw-to-place: drag a box or just click. The commit creates the field and
+* its widget through `form.create()`, styled from the tool's live defaults.
+* Where the field goes is `gesturePlacement`, the call the annotation core
+* makes for its own drawings: the dragged box once the gesture is a drag
+* (the shared click ↔ drag threshold), else the tool's `clickCreate` box.
+* What follows is the annotation plugin's `afterCreate` setting, as for
+* every tool: select the new widget, and keep the tool or go back to the
+* default one.
+*
+* With the annotation plugin, the tool's ghost shows the field a click
+* places: this handler's hover puts it where the click would reach it (no
+* widget or annotation under the pointer claims it) and the user may design
+* forms. The gesture reports itself (`previewPlacement`), so once it drags
+* the page paints the field the release places, a radio button round.
+*
+* Gesture rules match the annotation handlers: page-anchored via the sample
+* projection (the box keeps sizing along the edge when the cursor overshoots
+* or crosses a gap), and the up sample is the final point.
+*/
+function createPlaceHandler(form, interaction, annotation) {
+	let origin = null;
+	/** Drop the gesture and what it painted: its placement and the tool's ghost. */
+	const endGesture = () => {
+		origin = null;
+		annotation?.clearPlacementPreview();
+		annotation?.clearGhost();
+	};
+	const place = async (tool, page, box) => {
+		const pageBox = form.getPageBox(page);
+		const rect = pageBox ? clampToPage(box, pageBox) : null;
+		if (!rect) return;
+		const look = (0, _embedpdf_core_annotation.widgetAppearanceOf)(annotation ? annotation.tools.getDefaults(tool.id) : tool.defaults);
+		const name = nextFieldName(tool.family, new Set(form.list().map((field) => field.name)));
+		const created = form.create(toolDraft(tool, name, {
+			page,
+			rect,
+			...look
+		}));
+		const field = form.get({
+			kind: "fqn",
+			name
+		}) ?? (await created).field;
+		if (!annotation || interaction.getActiveToolId() !== tool.id) return;
+		const policy = annotation.getSettings().afterCreate;
+		const widget = field.widgets.find((candidate) => candidate.page?.objectNumber === page.objectNumber);
+		if (policy.select && widget?.ref) annotation.selection.set([widget.ref]);
+		if (policy.tool === "default") interaction.activateTool("form-edit");
+		await created;
+	};
+	return {
+		id: "form-place",
+		priority: 95,
+		enabledFor: (tool) => tool.enables.has("form-place"),
+		onHover: (sample) => {
+			if (!annotation) return;
+			const toolId = interaction.getActiveToolId();
+			if (sample.page && FORM_TOOL_BY_ID.has(toolId) && form.canDesign() && !interaction.hasCursorClaim()) annotation.hoverGhostAt(toolId, sample.page.ref, sample.page.point, sample.page.rotation, sample.page.zoom);
+			else annotation.clearGhost();
+		},
+		onDown: (sample) => {
+			if (!sample.page || !FORM_TOOL_BY_ID.has(interaction.getActiveToolId())) return false;
+			if (!form.canDesign()) return false;
+			origin = {
+				page: sample.page.ref,
+				start: sample.page.point,
+				last: sample.page.point
+			};
+			return true;
+		},
+		onMove: (sample) => {
+			if (!origin) return;
+			const point = (0, _embedpdf_plugin_interaction_contract_host.samplePointOn)(sample, origin.page);
+			if (!point) return;
+			origin.last = point;
+			annotation?.previewPlacement(interaction.getActiveToolId(), origin.page, origin.start, point);
+		},
+		onUp: (sample) => {
+			if (!origin) return;
+			const gesture = origin;
+			endGesture();
+			const tool = FORM_TOOL_BY_ID.get(interaction.getActiveToolId());
+			if (!tool) return;
+			const end = (0, _embedpdf_plugin_interaction_contract_host.samplePointOn)(sample, gesture.page) ?? gesture.last;
+			const placement = (0, _embedpdf_core_annotation.gesturePlacement)("box", gesture.start, end, tool.clickCreate, { pageBox: form.getPageBox(gesture.page) ?? void 0 });
+			if (placement?.kind !== "box") return;
+			place(tool, gesture.page, placement.rect).catch((error) => {
+				globalThis.console?.error("[form] placing the field failed:", error);
+			});
+		},
+		onCancel: endGesture
+	};
+}
+//#endregion
+//#region src/connect.ts
+/**
+* The form plugin's wiring to its siblings, run once every capability exists:
+* its tools and place handler on the interaction hub, its widgets lent to the
+* annotation plugin for design, and the reset executor, commit sink, form
+* reader and submit resolver on the actions plugin. Every registration is released with
+* the document.
+*/
+function connectForm(ctx, form, lender) {
+	const interaction = ctx.get(_embedpdf_plugin_interaction_contract_host.InteractionToken);
+	const annotation = ctx.tryGet(_embedpdf_plugin_annotation_contract_host.AnnotationToken);
+	ctx.cleanup(interaction.registerTool({
+		id: "form-fill",
+		cursor: "default",
+		enables: /* @__PURE__ */ new Set(["form-fill", "link-nav"])
+	}));
+	ctx.cleanup(interaction.registerTool({
+		id: "form-edit",
+		cursor: "default",
+		enables: /* @__PURE__ */ new Set(["annotation-edit", "annotation-marquee"])
+	}));
+	for (const tool of FORM_TOOLS) ctx.cleanup(annotation ? annotation.tools.register({
+		id: tool.id,
+		subtype: tool.visualKind,
+		cursor: tool.cursor,
+		enables: [...PLACE_TAGS],
+		clickCreate: tool.clickCreate,
+		defaults: tool.defaults,
+		ghost: true
+	}) : interaction.registerTool({
+		id: tool.id,
+		cursor: tool.cursor,
+		enables: new Set(PLACE_TAGS)
+	}));
+	ctx.cleanup(interaction.registerHandler(createPlaceHandler(form, interaction, annotation)));
+	if (annotation && ctx.allows("doc.forms.modify")) ctx.cleanup(annotation.lend(lender));
+	const actions = ctx.tryGet(_embedpdf_plugin_actions_contract_host.ActionsToken);
+	if (!actions) return;
+	ctx.cleanup(actions.registerFormCommitSink((effects) => form.commitScriptFormEffects(effects)));
+	ctx.cleanup(actions.registerFormReader(() => form.getSnapshot()));
+	ctx.cleanup(actions.registerSubmitResolver((intent, actionContext, diagnose) => form.resolveSubmitDataset(intent, actionContext, diagnose)));
+	ctx.cleanup(actions.registerExecutor("reset-form", async (node, actionContext) => {
+		if (node.type !== "reset-form") return {
+			status: "inert",
+			reason: "not a reset-form node"
+		};
+		const result = await form.resetFormAction(node.fields, node.exclude, actionContext.origin);
+		if (result.status === "failed") return {
+			status: "failed",
+			error: result.error?.message ?? "reset failed"
+		};
+		if (result.status === "unchanged") return {
+			status: "inert",
+			reason: result.diagnostics[0]?.message ?? "reset-form resolved no fields"
+		};
+		return { status: "executed" };
+	}));
+}
+//#endregion
+//#region src/model.ts
+/**
+* The form plugin's data, all pure:
+*
+* - `FieldIndex` is the form as the engine confirmed it: the field tree and
+*   every widget row, indexed by field key and by widget. It is the value of
+*   the plugin's `fields` mirror and changes only through `foldFormEvent` and
+*   loads; `predictFormOp` (sync/predict.ts) shows this session's changes on
+*   top of it.
+* - `PageWidgets` is one page's widgets, where each is and how it looks,
+*   derived from the index's widget rows (`pageWidgetsOf`).
+*
+* The text being typed in a field is not here: it waits in `write/typing.ts`
+* until it is committed.
+*/
+const fieldKeyOfRef = (ref) => ref.kind === "objectNumber" ? `obj:${ref.objectNumber}` : `fqn:${ref.name}`;
+/** A field's ref is its object number, or its name when it has none. */
+const fieldKeyOf = (field) => fieldKeyOfRef(field.ref);
+const emptyFieldIndex = () => ({
+	snapshot: null,
+	byKey: {},
+	byName: {},
+	byWidget: {},
+	rowByWidget: {},
+	pictureVersions: {}
+});
+function indexFields(snapshot, pictureVersions = {}) {
+	const byKey = {};
+	const byName = {};
+	const byWidget = {};
+	const rowByWidget = {};
+	snapshot.fields.forEach((field, position) => {
+		var _field$name;
+		byKey[fieldKeyOf(field)] = position;
+		byName[_field$name = field.name] ?? (byName[_field$name] = position);
+		for (const widget of field.widgets) if (widget.objectNumber > 0) byWidget[widget.objectNumber] = position;
+	});
+	snapshot.widgets.forEach((row, position) => {
+		if (row.ref.kind === "objectNumber") rowByWidget[row.ref.objectNumber] = position;
+	});
+	return {
+		snapshot,
+		byKey,
+		byName,
+		byWidget,
+		rowByWidget,
+		pictureVersions
+	};
+}
+/** The index of `snapshot`, keeping `index`'s picture versions. */
+const reindex = (index, snapshot) => indexFields(snapshot, index.pictureVersions);
+/**
+* A fresh read of the whole form: every widget's picture version moves past
+* the one it had, so a reload re-fetches every picture (the pictures may
+* have changed while the event stream wasn't trusted). A new widget starts at 0.
+*/
+function indexLoadedFields(previous, snapshot) {
+	const pictureVersions = {};
+	for (const [number, version] of Object.entries(previous.pictureVersions)) pictureVersions[Number(number)] = version + 1;
+	for (const row of snapshot.widgets) {
+		const number = widgetNumber$1(row);
+		if (number > 0) pictureVersions[number] ?? (pictureVersions[number] = 0);
+	}
+	return indexFields(snapshot, pictureVersions);
+}
+/** The picture version of a widget; 0 for one the index has never seen. */
+const pictureVersionOf = (index, annotObjectNumber) => index.pictureVersions[annotObjectNumber] ?? 0;
+/** Replace a field by key, or append it when it is new. */
+function upsertFields(index, fields) {
+	if (!index.snapshot || fields.length === 0) return index;
+	const next = index.snapshot.fields.slice();
+	for (const field of fields) {
+		const position = index.byKey[fieldKeyOf(field)];
+		if (position === void 0) next.push(field);
+		else next[position] = field;
+	}
+	return reindex(index, {
+		...index.snapshot,
+		fields: next
+	});
+}
+const widgetNumber$1 = (widget) => widget.ref.kind === "objectNumber" ? widget.ref.objectNumber : 0;
+/** Replace widget rows by object number, or append the ones that are new. */
+function upsertWidgets(index, rows) {
+	if (!index.snapshot || rows.length === 0) return index;
+	const incoming = new Map(rows.map((row) => [widgetNumber$1(row), row]));
+	const next = index.snapshot.widgets.map((row) => {
+		const replaced = incoming.get(widgetNumber$1(row));
+		if (replaced) incoming.delete(widgetNumber$1(row));
+		return replaced ?? row;
+	});
+	return reindex(index, {
+		...index.snapshot,
+		widgets: [...next, ...incoming.values()]
+	});
+}
+/** The page's widget rows in `order` (bottom to top), in their slots: other pages' keep theirs. */
+function reorderWidgetRows(index, page, order) {
+	if (!index.snapshot) return index;
+	const widgets = (0, _embedpdf_engine_core_runtime.reorderPart)(index.snapshot.widgets, (row) => row.page.objectNumber === page.objectNumber, order.map(_embedpdf_engine_core_runtime.annotationKey), (row) => (0, _embedpdf_engine_core_runtime.annotationKey)(row.ref));
+	return reindex(index, {
+		...index.snapshot,
+		widgets
+	});
+}
+/** Drop the rows of widgets that went (with their field, or with their page). */
+function removeWidgets(index, gone) {
+	if (!index.snapshot || gone.length === 0) return index;
+	const numbers = new Set(gone.map((widget) => widget.objectNumber));
+	const widgets = index.snapshot.widgets.filter((row) => !numbers.has(widgetNumber$1(row)));
+	if (widgets.length === index.snapshot.widgets.length) return index;
+	return reindex(index, {
+		...index.snapshot,
+		widgets
+	});
+}
+function removeField(index, ref) {
+	if (!index.snapshot) return index;
+	const fields = index.snapshot.fields.filter((field) => ref.kind === "objectNumber" ? !(field.ref.kind === "objectNumber" && field.ref.objectNumber === ref.objectNumber) : field.name !== ref.name);
+	if (fields.length === index.snapshot.fields.length) return index;
+	return reindex(index, {
+		...index.snapshot,
+		fields
+	});
+}
+/**
+* Apply one confirmed document event to the field index. Every form event
+* carries the fields and the widget rows it touched as the engine read them
+* back, so the index never needs a re-read except for a repair, whose result
+* reports only counts, and for writes that remove widgets with their pages.
+* The widgets the engine drew again take a new picture version.
+*/
+function foldFormEvent(index, event) {
+	return foldFormFacts(withRedrawnPictures(index, redrawnWidgetsOf(event)), event);
+}
+/**
+* The widgets a confirmed fact drew again: the ones the engine says it
+* redrew (`meta.redrawnWidgets`: a checkbox that only switched its state isn't
+* one), else the ones it changed; the signed widget of a signing.
+*/
+function redrawnWidgetsOf(event) {
+	if (event.type === "signatures.completed") return event.signature.widget ? [event.signature.widget] : [];
+	if (!event.type.startsWith("forms.") || !("meta" in event)) return [];
+	const meta = event.meta;
+	return meta.redrawnWidgets ?? meta.changedWidgets ?? [];
+}
+/** Each widget drawn again takes a new picture version; one named by its page only, all of that page's. */
+function withRedrawnPictures(index, redrawn) {
+	if (redrawn.length === 0) return index;
+	const numbers = /* @__PURE__ */ new Set();
+	for (const widget of redrawn) if (widget.objectNumber) numbers.add(widget.objectNumber);
+	else if (widget.page) {
+		for (const row of index.snapshot?.widgets ?? []) if (row.page.objectNumber === widget.page.objectNumber) numbers.add(widgetNumber$1(row));
+	}
+	if (numbers.size === 0) return index;
+	const pictureVersions = { ...index.pictureVersions };
+	for (const number of numbers) pictureVersions[number] = (pictureVersions[number] ?? 0) + 1;
+	return {
+		...index,
+		pictureVersions
+	};
+}
+/**
+* A merged field split as it took a second widget: its widget half moved to a new number (one
+* of the event's widgets), and the row at the field's own number is gone with it.
+*/
+function withoutSplitRow(index, field) {
+	if (field.ref.kind !== "objectNumber") return index;
+	const own = field.ref.objectNumber;
+	if (field.widgets.some((widget) => widget.objectNumber === own)) return index;
+	const row = widgetRowOf(index, own);
+	return row ? removeWidgets(index, [{
+		ref: row.ref,
+		objectNumber: own,
+		page: row.page
+	}]) : index;
+}
+function foldFormFacts(index, event) {
+	switch (event.type) {
+		case "forms.widgetAdded": return withoutSplitRow(upsertWidgets(upsertFields(index, [event.field]), event.widgets), event.field);
+		case "forms.valueSet":
+		case "forms.widgetRemoved":
+		case "forms.restored": return upsertWidgets(upsertFields(index, [event.field]), event.widgets);
+		case "forms.updated": return withCalculationOrder(upsertWidgets(upsertFields(index, [event.field]), event.widgets), event.calculationOrder);
+		case "forms.created": {
+			const created = upsertWidgets(upsertFields(index, [event.field]), event.widgets);
+			return withCalculationOrder(created.snapshot?.formKind === "none" ? reindex(created, {
+				...created.snapshot,
+				formKind: "acroform"
+			}) : created, event.calculationOrder);
+		}
+		case "forms.calculationsReordered": return withCalculationOrder(index, event.calculationOrder);
+		case "forms.widgetDeleted": {
+			const gone = removeWidgets(index, event.meta.changedWidgets);
+			return event.field ? upsertFields(gone, [event.field]) : gone;
+		}
+		case "forms.widgetRestored": return upsertWidgets(event.field ? upsertFields(index, [event.field]) : index, event.widgets);
+		case "forms.widgetUpdated": return upsertWidgets(index, [event.widget]);
+		case "forms.widgetsReordered": return reorderWidgetRows(index, event.page, event.order);
+		case "forms.deleted": return event.deleted ? withCalculationOrder(removeWidgets(removeField(index, event.deleted), event.meta.changedWidgets), event.calculationOrder) : (0, _embedpdf_core.reload)();
+		case "forms.repaired":
+		case "pages.deleted":
+		case "pages.inserted":
+		case "pages.restored":
+		case "pages.flattened":
+		case "annotations.flattened":
+		case "redaction.applied": return (0, _embedpdf_core.reload)();
+		default: return index;
+	}
+}
+/** Whether any field has a keystroke, validate, calculate or format script. */
+function formHasScripts(index) {
+	return (index.snapshot?.fields ?? []).some(({ actions }) => !!(actions?.keystroke || actions?.validate || actions?.calculate || actions?.format));
+}
+/** The index with the calculation order a write answered, when the write changed it. */
+function withCalculationOrder(index, order) {
+	if (!order || !index.snapshot) return index;
+	return reindex(index, {
+		...index.snapshot,
+		calculationOrder: [...order]
+	});
+}
+const fieldByKey = (index, key) => {
+	const position = index.byKey[key];
+	return position === void 0 ? null : index.snapshot?.fields[position] ?? null;
+};
+/** The field a ref names: by object number, or by full name for `toFieldRef(name)`. */
+function fieldByRef(index, ref) {
+	const position = ref.kind === "fqn" ? index.byName[ref.name] : index.byKey[fieldKeyOfRef(ref)];
+	return position === void 0 ? null : index.snapshot?.fields[position] ?? null;
+}
+/** The key a field is known by, whichever ref names it: a name ref resolves to its field's key. */
+const canonicalKey = (index, ref) => {
+	const field = fieldByRef(index, ref);
+	return field ? fieldKeyOf(field) : fieldKeyOfRef(ref);
+};
+const fieldForWidget = (index, annotObjectNumber) => {
+	const position = index.byWidget[annotObjectNumber];
+	return position === void 0 ? null : index.snapshot?.fields[position] ?? null;
+};
+/** The fields whose value entry differs between two indexes (new fields included). */
+function fieldsWithChangedValues(previous, next) {
+	return (next.snapshot?.fields ?? []).filter((field) => {
+		const before = fieldByKey(previous, fieldKeyOf(field));
+		return !before || JSON.stringify(valueEntryOf(before)) !== JSON.stringify(valueEntryOf(field));
+	});
+}
+const valueEntryOf = (field) => "valueEntry" in field ? field.valueEntry : null;
+/** Whether a widget shows on screen: its `hidden` and `noView` flags hide it. */
+const shownOnScreen = (row) => !row.hidden && !row.noView;
+/** The widgets one page shows, from the form's widget rows. */
+function pageWidgetsOf(index, pageObjectNumber) {
+	const widgets = {};
+	for (const row of index.snapshot?.widgets ?? []) {
+		if (row.page.objectNumber !== pageObjectNumber || row.ref.kind !== "objectNumber") continue;
+		if (!shownOnScreen(row)) continue;
+		widgets[row.ref.objectNumber] = {
+			box: row.rect,
+			look: {
+				border: row.color ?? null,
+				borderWidth: row.strokeWidth ?? 1,
+				borderStyle: row.borderStyle ?? "solid",
+				background: row.interiorColor ?? null,
+				color: row.fontColor ?? null,
+				fontFamily: row.fontFamily ?? null,
+				fontSize: row.fontSize ?? null,
+				textAlign: row.textAlign ?? "left"
+			}
+		};
+	}
+	return widgets;
+}
+const AT_REST = {
+	pending: false,
+	pictureVersion: 0
+};
+/** The widgets one page shows, in the order the page draws them. */
+function shownWidgetsOf(index, pageObjectNumber, lookOf = () => AT_REST) {
+	const shown = [];
+	for (const row of index.snapshot?.widgets ?? []) {
+		if (row.page.objectNumber !== pageObjectNumber || !shownOnScreen(row)) continue;
+		shown.push({
+			ref: row.ref,
+			rect: row.rect,
+			appearanceState: row.appearanceState,
+			...lookOf(row)
+		});
+	}
+	return shown;
+}
+function widgetRowOf(index, annotObjectNumber) {
+	const position = index.rowByWidget[annotObjectNumber];
+	return position === void 0 ? null : index.snapshot?.widgets[position] ?? null;
+}
+const boxContains = (box, point) => point.x >= box.x && point.x <= box.x + box.width && point.y >= box.y && point.y <= box.y + box.height;
+/** The widget under a page-space point; nested widgets resolve to the smallest box. */
+function widgetAt(index, widgets, point) {
+	if (!widgets) return null;
+	let best = null;
+	for (const [key, { box }] of Object.entries(widgets)) {
+		if (!boxContains(box, point)) continue;
+		const annotObjectNumber = Number(key);
+		const field = fieldForWidget(index, annotObjectNumber);
+		if (!field) continue;
+		if (!best || box.width * box.height < best.box.width * best.box.height) best = {
+			annotObjectNumber,
+			field,
+			box
+		};
+	}
+	return best;
+}
+const initialFormState = () => ({});
+//#endregion
+//#region src/read/fields.ts
+/**
+* Reads over the mirrored field tree: fields, values, the joins between a
+* field and its widgets' rows, the field of the selected widget, and the
+* required-field check.
+*/
+const NO_FIELDS$1 = Object.freeze([]);
+const NOTHING_SELECTED = Object.freeze([]);
+/** A widget address as the annotation object number the field index is keyed by. */
+const widgetObjectOf = (widget) => "kind" in widget ? widget.kind === "objectNumber" ? widget.objectNumber : 0 : widget.objectNumber;
+/** A field's value in the write vocabulary, or null for a valueless or unsupported entry. */
+function valueOf$1(field) {
+	const entry = field.valueEntry;
+	if (entry.kind === "none" || entry.kind === "unsupported") return null;
+	switch (field.family) {
+		case "text": return { value: field.value };
+		case "checkbox": return { checked: field.checked };
+		case "radio": return { value: field.value === "Off" ? null : field.value };
+		case "combobox": return { value: field.value === "" ? null : field.value };
+		case "listbox": return { selectedValues: [...field.selectedValues] };
+		default: return null;
+	}
+}
+/** A field's value as plain data: what `exportValues()` gives and `importValues()` takes. */
+function plainValueOf(field) {
+	const value = valueOf$1(field);
+	if (!value) return void 0;
+	if ("checked" in value) return value.checked;
+	if ("selectedValues" in value) return value.selectedValues;
+	return value.value;
+}
+/**
+* The write a plain value makes for a field of this family, or null when the
+* family can't take it (a list given `true`, a value for a push button).
+*/
+function writeOfPlainValue(field, value) {
+	switch (field.family) {
+		case "checkbox":
+			if (typeof value === "boolean") return { checked: value };
+			return typeof value === "string" || value === null ? { value } : null;
+		case "text":
+		case "radio":
+		case "combobox": return typeof value === "string" || value === null ? { value } : null;
+		case "listbox":
+			if (value === null) return { selectedValues: [] };
+			if (typeof value === "string") return { selectedValues: [value] };
+			return Array.isArray(value) ? { selectedValues: [...value] } : null;
+		default: return null;
+	}
+}
+/** Whether a field holds nothing a required check would accept. */
+function isEmpty(field) {
+	switch (field.family) {
+		case "text":
+		case "combobox": return field.value === "";
+		case "checkbox": return !field.checked;
+		case "radio": return field.value === "Off" || field.value === "";
+		case "listbox": return field.selectedValues.length === 0;
+		case "signature": return field.valueEntry.kind === "none";
+		default: return false;
+	}
+}
+function createFieldReads(ctx, { fields, rights, siblings }) {
+	const all = () => fields.view().snapshot?.fields ?? NO_FIELDS$1;
+	const list = (filter) => {
+		if (!filter) return all();
+		const page = filter.page === void 0 ? void 0 : ctx.getPage(filter.page)?.ref;
+		if (filter.page !== void 0 && !page) return NO_FIELDS$1;
+		return all().filter((field) => (!filter.family || field.family === filter.family) && (filter.name === void 0 || field.name === filter.name) && (!page || field.widgets.some((widget) => widget.page && (0, _embedpdf_engine_core_runtime.pageRefsEqual)(widget.page, page))));
+	};
+	const valueByKey = (0, _embedpdf_core.memoByKey)((key) => {
+		const field = fieldByKey(fields.view(), key);
+		return [field ? JSON.stringify(valueOf$1(field)) : null];
+	}, (_key, value) => value === null ? null : JSON.parse(value), { maxEntries: 1024 });
+	const widgetsByKey = (0, _embedpdf_core.memoByKey)((key) => {
+		const index = fields.view();
+		return (fieldByKey(index, key)?.widgets ?? []).map((widget) => widgetRowOf(index, widget.objectNumber));
+	}, (_key, ...rows) => Object.freeze(rows.filter((row) => row !== null)), { maxEntries: 1024 });
+	const exportValues = (0, _embedpdf_core.memo)(() => [fields.view()], (index) => {
+		const values = {};
+		for (const field of index.snapshot?.fields ?? []) {
+			const value = plainValueOf(field);
+			if (value !== void 0) values[field.name] = value;
+		}
+		return values;
+	});
+	/** Where a field first shows: its page's index, then top to bottom, then left to right. */
+	const placeOf = (field) => {
+		const index = fields.view();
+		const row = field.widgets.map((widget) => widgetRowOf(index, widget.objectNumber)).find((candidate) => candidate !== null);
+		return [
+			row ? ctx.getPage(row.page)?.index ?? Infinity : Infinity,
+			row?.rect.y ?? 0,
+			row?.rect.x ?? 0
+		];
+	};
+	const validate = (0, _embedpdf_core.memo)(() => [
+		fields.view(),
+		ctx.document(),
+		rights.key()
+	], (index) => {
+		const missing = (index.snapshot?.fields ?? []).filter((field) => field.required && isEmpty(field) && rights.mayFill(field)).map((field) => ({
+			field,
+			place: placeOf(field)
+		})).sort((left, right) => left.place[0] - right.place[0] || left.place[1] - right.place[1] || left.place[2] - right.place[2]).map(({ field }) => field);
+		return {
+			valid: missing.length === 0,
+			missing
+		};
+	});
+	const getSelectedField = (0, _embedpdf_core.memo)(() => [fields.view(), siblings.annotation()?.selection.list() ?? NOTHING_SELECTED], (index, selected) => {
+		const [annotation] = selected;
+		if (selected.length !== 1 || !annotation?.subtype.startsWith("widget")) return null;
+		return fieldForWidget(index, widgetObjectOf(annotation.ref));
+	});
+	return { api: {
+		getSnapshot: () => fields.view().snapshot,
+		getStatus: fields.getStatus,
+		getFormKind: () => fields.view().snapshot?.formKind ?? "none",
+		refresh: (options) => ctx.cancellable(options?.signal, fields.refresh()),
+		get: (ref) => fieldByRef(fields.view(), ref),
+		getFieldForWidget: (widget) => fieldForWidget(fields.view(), widgetObjectOf(widget)),
+		getWidget: (widget) => widgetRowOf(fields.view(), widgetObjectOf(widget)),
+		getWidgets: (ref) => widgetsByKey(canonicalKey(fields.view(), ref)),
+		list,
+		getValue: (ref) => valueByKey(canonicalKey(fields.view(), ref)),
+		getSelectedField,
+		validate,
+		exportValues
+	} };
+}
+//#endregion
+//#region src/read/settings.ts
+/**
+* A field's settings, described for a settings panel the way an annotation
+* kind describes its look: which settings the field's family has, how each is
+* edited, and its value. `update()` writes them.
+*/
+/** What every field has. */
+const COMMON = [
+	{
+		key: "name",
+		control: "text",
+		label: "Name",
+		labelKey: "form.settings.name"
+	},
+	{
+		key: "alternateName",
+		control: "text",
+		label: "Tooltip",
+		labelKey: "form.settings.tooltip"
+	},
+	{
+		key: "required",
+		control: "flag",
+		label: "Required",
+		labelKey: "form.settings.required"
+	},
+	{
+		key: "readOnly",
+		control: "flag",
+		label: "Read-only",
+		labelKey: "form.settings.readOnly"
+	},
+	{
+		key: "noExport",
+		control: "flag",
+		label: "Don't export",
+		labelKey: "form.settings.noExport"
+	}
+];
+const DEFAULT_VALUE = {
+	label: "Default value",
+	labelKey: "form.settings.defaultValue"
+};
+const OPTIONS = {
+	key: "options",
+	control: "options",
+	label: "Options",
+	labelKey: "form.settings.options"
+};
+/** What each family adds. */
+function familySettings(field) {
+	switch (field.family) {
+		case "text": return [
+			{
+				key: "defaultValue",
+				control: "text",
+				...DEFAULT_VALUE
+			},
+			{
+				key: "maxLength",
+				control: "number",
+				label: "Maximum length",
+				labelKey: "form.settings.maxLength",
+				min: 1
+			},
+			{
+				key: "multiline",
+				control: "flag",
+				label: "Several lines",
+				labelKey: "form.settings.multiline"
+			},
+			{
+				key: "password",
+				control: "flag",
+				label: "Password",
+				labelKey: "form.settings.password"
+			},
+			{
+				key: "comb",
+				control: "flag",
+				label: "One character per box",
+				labelKey: "form.settings.comb"
+			}
+		];
+		case "radio": return [{
+			key: "radiosInUnison",
+			control: "flag",
+			label: "Buttons with one value turn on together",
+			labelKey: "form.settings.radiosInUnison"
+		}, {
+			key: "noToggleToOff",
+			control: "flag",
+			label: "Keep one on",
+			labelKey: "form.settings.keepOneOn"
+		}];
+		case "combobox": return [
+			OPTIONS,
+			{
+				key: "edit",
+				control: "flag",
+				label: "Allow typing",
+				labelKey: "form.settings.allowTyping"
+			},
+			{
+				key: "defaultValue",
+				control: "choice",
+				...DEFAULT_VALUE,
+				options: field.options.map((option) => option.value),
+				free: field.edit
+			}
+		];
+		case "listbox": return [
+			OPTIONS,
+			{
+				key: "multiSelect",
+				control: "flag",
+				label: "Several choices",
+				labelKey: "form.settings.multiSelect"
+			},
+			{
+				key: "defaultValue",
+				control: "choices",
+				...DEFAULT_VALUE,
+				options: field.options.map((option) => option.value)
+			}
+		];
+		default: return [];
+	}
+}
+/** Each setting's value, as the field holds it. */
+function valuesOf(field, settings) {
+	const held = field;
+	const values = {};
+	for (const { key } of settings) if (key === "name") values.name = field.name.slice(field.name.lastIndexOf(".") + 1);
+	else if (key === "alternateName") values.alternateName = field.alternateName ?? "";
+	else values[key] = held[key] ?? null;
+	return values;
+}
+function createFieldSettings({ fields }) {
+	const settingsByKey = (0, _embedpdf_core.memoByKey)((key) => [fieldByKey(fields.view(), key)], (_key, field) => {
+		if (!field) return null;
+		const properties = [...COMMON, ...familySettings(field)];
+		return {
+			properties,
+			values: valuesOf(field, properties)
+		};
+	}, { maxEntries: 256 });
+	return { api: { getFieldSettings: (ref) => settingsByKey(canonicalKey(fields.view(), ref)) } };
+}
+//#endregion
+//#region src/read/fill-items.ts
+/**
+* Project one widget of a field into a fill control; `fillable`: the user may
+* fill the field in (a signature field: sign it). Null for families with no
+* fill control.
+*/
+function projectWidget(field, annotObjectNumber, widget, fillable) {
+	const base = {
+		key: fieldKeyOf(field),
+		fieldRef: field.ref,
+		annotObjectNumber,
+		annotationRef: field.widgets.find((candidate) => candidate.objectNumber === annotObjectNumber)?.ref ?? null,
+		box: widget.box,
+		look: widget.look,
+		disabled: field.readOnly || !fillable,
+		label: field.alternateName ?? field.name
+	};
+	switch (field.family) {
+		case "text": return {
+			...base,
+			control: "text",
+			value: field.value,
+			multiline: field.multiline,
+			password: field.password,
+			maxLength: field.maxLength,
+			comb: field.comb
+		};
+		case "checkbox": {
+			const toggle = field.widgets.find((candidate) => candidate.objectNumber === annotObjectNumber);
+			return {
+				...base,
+				control: "toggle",
+				kind: "checkbox",
+				checked: field.checked,
+				exportValue: toggle && "exportValue" in toggle ? toggle.exportValue : field.exportValue
+			};
+		}
+		case "radio": {
+			const toggle = field.widgets.find((candidate) => candidate.objectNumber === annotObjectNumber);
+			return {
+				...base,
+				control: "toggle",
+				kind: "radio",
+				checked: toggle && "checked" in toggle ? toggle.checked : false,
+				exportValue: toggle && "exportValue" in toggle ? toggle.exportValue : ""
+			};
+		}
+		case "combobox": return {
+			...base,
+			control: "choice",
+			kind: "combo",
+			edit: field.edit,
+			multi: false,
+			options: field.options,
+			selected: field.value === "" ? [] : [field.value]
+		};
+		case "listbox": return {
+			...base,
+			control: "choice",
+			kind: "list",
+			edit: false,
+			multi: field.multiSelect,
+			options: field.options,
+			selected: field.selectedValues
+		};
+		case "pushbutton": return {
+			...base,
+			control: "button"
+		};
+		case "signature": return {
+			...base,
+			control: "signature",
+			signed: field.valueEntry.kind !== "none"
+		};
+		default: return null;
+	}
+}
+/**
+* Project one page's widgets into fill controls, each disabled when the user
+* may not fill its field in, or sign it (`mayFill`). Widgets whose page has not loaded (or
+* that are direct objects with no join key) are skipped; the projection runs
+* again when the page's widgets land.
+*/
+function fillItems(index, pageObjectNumber, widgets, mayFill) {
+	if (!index.snapshot || !widgets) return [];
+	const items = [];
+	for (const field of index.snapshot.fields) for (const widget of field.widgets) {
+		if (widget.page?.objectNumber !== pageObjectNumber) continue;
+		const placed = widgets[widget.objectNumber];
+		if (!placed) continue;
+		const item = projectWidget(field, widget.objectNumber, placed, mayFill(field));
+		if (item) items.push(item);
+	}
+	return items;
+}
+//#endregion
+//#region src/read/widgets.ts
+/**
+* The widgets' reads: each page's widgets (from the form's widget rows), the
+* ones it shows for the form layer to paint (and the painter's scene of each,
+* `services/looks.ts`), the fill projection with the session's fill permission
+* folded in, and the widget hit test.
+*/
+const NO_WIDGETS = Object.freeze([]);
+/** Whether the `fillable` setting lets people fill in a field of this family by hand. */
+const isFillableByHand = (fillable, family) => typeof fillable === "boolean" ? fillable : fillable.includes(family);
+const NOTHING_SHOWN$1 = Object.freeze([]);
+function createWidgetReads(ctx, { fields, rights, looks, pictures }) {
+	/** Every page's widgets come with the form: one read for the document. */
+	const loadWidgets = (_page) => fields.settled();
+	const widgetsOn = (0, _embedpdf_core.memoByKey)((pageObjectNumber) => [fields.view()], (pageObjectNumber, index) => pageWidgetsOf(index, pageObjectNumber));
+	/** The widget under a page point. */
+	const getWidgetAt = (pageArgument, point) => {
+		const page = ctx.getPage(pageArgument)?.ref;
+		if (!page) return null;
+		return widgetAt(fields.view(), widgetsOn(page.objectNumber), point);
+	};
+	const fillable = () => ctx.settings().get().fillable;
+	const mayWrite = (field) => isFillableByHand(fillable(), field.family) && (field.family === "signature" ? rights.maySign(field) : rights.mayFill(field));
+	const widgetsOfPage = (0, _embedpdf_core.memoByKey)((pageObjectNumber) => [
+		fields.view(),
+		widgetsOn(pageObjectNumber),
+		rights.key(),
+		fillable()
+	], (pageObjectNumber, index, widgets) => fillItems(index, pageObjectNumber, widgets, mayWrite));
+	/** The page's content box (`{0, 0, width, height}`), for page-bound placement. */
+	const getPageBox = (page) => {
+		const size = ctx.getPage(page)?.size;
+		return size ? {
+			x: 0,
+			y: 0,
+			width: size.width,
+			height: size.height
+		} : null;
+	};
+	return {
+		getPageBox,
+		api: {
+			listWidgets: (pageArgument) => {
+				const page = ctx.getPage(pageArgument)?.ref;
+				return page ? widgetsOfPage(page.objectNumber) : NO_WIDGETS;
+			},
+			listShownWidgets: (pageArgument) => {
+				const page = ctx.getPage(pageArgument)?.ref;
+				return page ? looks.listShownWidgets(page.objectNumber) : NOTHING_SHOWN$1;
+			},
+			getAppearanceEpoch: pictures.epoch,
+			renderAppearances: pictures.render,
+			getWidgetPainting: looks.getWidgetPainting,
+			getTextEditorLayout: looks.getTextEditorLayout,
+			ensureLoaded: loadWidgets,
+			getWidgetAt,
+			getPageBox
+		}
+	};
+}
+//#endregion
+//#region src/sync/predict.ts
+const widgetNumber = (widget) => widget.ref.kind === "objectNumber" ? widget.ref.objectNumber : 0;
+/** The rows of a field's widgets, in its widget order. */
+function rowsOfField(index, field) {
+	return field.widgets.flatMap((widget) => {
+		const row = widgetRowOf(index, widget.objectNumber);
+		return row ? [row] : [];
+	});
+}
+/** A field and the rows of its widgets, as the index holds them. */
+const withRows = (index, field) => ({
+	field,
+	widgets: rowsOfField(index, field)
+});
+/** Fields and their widget rows put into the index, all at once. */
+function withFields(index, parts) {
+	if (parts.length === 0) return index;
+	return upsertWidgets(upsertFields(index, parts.map((part) => part.field)), parts.flatMap((part) => part.widgets));
+}
+/** The fields a reset of the whole form puts back: the ones that hold a value. */
+const resetTargets = (index) => (index.snapshot?.fields ?? []).filter((field) => RESET_FAMILIES.has(field.family));
+const RESET_FAMILIES = /* @__PURE__ */ new Set([
+	"text",
+	"checkbox",
+	"radio",
+	"combobox",
+	"listbox"
+]);
+/**
+* One op of a change this session staged, shown before the engine answers,
+* by the engine's own rules (`fieldAfterValue`, `fieldAfterReset`,
+* `widgetsAfterDisplay`, `formFieldOfDraft`, `formFieldAfter`,
+* `widgetAfterPatch`): what the fields and their widgets hold after it. An op
+* those rules refuse shows nothing; one whose values only the engine's schemas
+* refuse shows until the engine's refusal takes the change away.
+* A create shows once it names its numbers; taking a widget out of its field
+* shows once the engine answers.
+*
+* The view replays every pending change each time any change is staged; the
+* same op over the same form gives the same form, so a field keeps its object
+* while nothing about it changed.
+*/
+function predictFormOp(index, op) {
+	let byOp = predictions.get(index);
+	const known = byOp?.get(op);
+	if (known) return known;
+	const next = predictOnce(index, op);
+	if (!byOp) predictions.set(index, byOp = /* @__PURE__ */ new WeakMap());
+	byOp.set(op, next);
+	return next;
+}
+const predictions = /* @__PURE__ */ new WeakMap();
+function predictOnce(index, op) {
+	try {
+		switch (op.type) {
+			case "forms.setValue": {
+				const field = fieldByRef(index, op.field);
+				return field ? withFields(index, [(0, _embedpdf_engine_core_runtime.fieldAfterValue)(withRows(index, field), op.value)]) : index;
+			}
+			case "forms.reset": return withFields(index, (op.fields ? op.fields.flatMap((ref) => fieldByRef(index, ref) ?? []) : resetTargets(index)).map((field) => (0, _embedpdf_engine_core_runtime.fieldAfterReset)(withRows(index, field))));
+			case "forms.setDisplay": {
+				const field = fieldByRef(index, op.field);
+				if (!field) return index;
+				return upsertWidgets(index, (0, _embedpdf_engine_core_runtime.widgetsAfterDisplay)(rowsOfField(index, field), op.display));
+			}
+			case "forms.restore": return withFields(index, [op]);
+			case "forms.restoreWidget": {
+				const restored = upsertWidgets(index, [op.widget]);
+				return op.field ? upsertFields(restored, [op.field]) : restored;
+			}
+			case "forms.create": return createdField(index, op);
+			case "forms.update": {
+				const field = fieldByRef(index, op.field);
+				return field ? withFields(index, [(0, _embedpdf_engine_core_runtime.formFieldAfter)(withRows(index, field), op.patch)]) : index;
+			}
+			case "forms.delete": {
+				const field = fieldByRef(index, op.field);
+				if (!field || !index.snapshot) return index;
+				return withCalculationOrder(removeWidgets(removeField(index, field.ref), field.widgets), index.snapshot.calculationOrder.filter((ref) => !sameField(ref, field.ref)));
+			}
+			case "forms.updateWidget": {
+				const row = rowOfRef(index, op.widget);
+				return row ? upsertWidgets(index, [(0, _embedpdf_engine_core_runtime.widgetAfterPatch)(row, op.patch)]) : index;
+			}
+			case "forms.deleteWidget": {
+				const row = rowOfRef(index, op.widget);
+				if (!row) return index;
+				const number = widgetNumber(row);
+				const field = fieldForWidget(index, number);
+				const gone = removeWidgets(index, [{
+					objectNumber: number,
+					page: row.page
+				}]);
+				if (!field) return gone;
+				const widgets = field.widgets.filter((widget) => widget.objectNumber !== number);
+				return upsertFields(gone, [{
+					...field,
+					widgets
+				}]);
+			}
+			case "forms.reorderWidgets": {
+				if (!index.snapshot) return index;
+				const order = (0, _embedpdf_engine_core_runtime.reorderedList)(index.snapshot.widgets.filter((row) => row.page.objectNumber === op.page.objectNumber).map((row) => row.ref), op.widgets, op.position, _embedpdf_engine_core_runtime.annotationKey);
+				return reorderWidgetRows(index, op.page, order);
+			}
+			case "forms.reorderCalculations":
+				if (!index.snapshot) return index;
+				return withCalculationOrder(index, (0, _embedpdf_engine_core_runtime.reorderedList)(index.snapshot.calculationOrder.filter((ref) => ref !== null), op.fields, op.position, fieldKeyOfRef));
+			default: return index;
+		}
+	} catch {
+		return index;
+	}
+}
+/** A widget's row, by its annotation ref. */
+const rowOfRef = (index, ref) => ref.kind === "objectNumber" ? widgetRowOf(index, ref.objectNumber) : null;
+const sameField = (left, right) => left !== null && fieldKeyOfRef(left) === fieldKeyOfRef(right);
+/**
+* `forms.create`, once it names the numbers it takes: the field and its
+* widgets as a read of them returns them, last in the form, and last in the
+* calculation order when it calculates.
+*/
+function createdField(index, op) {
+	const placements = op.draft.widgets ?? [];
+	const numbers = op.widgetObjectNumbers ?? [];
+	if (op.objectNumber === void 0 || numbers.length !== placements.length) return index;
+	const snapshot = index.snapshot;
+	if (!snapshot || fieldByRef(index, {
+		kind: "objectNumber",
+		objectNumber: op.objectNumber
+	})) return index;
+	const created = (0, _embedpdf_engine_core_runtime.formFieldOfDraft)(op.draft, {
+		objectNumber: op.objectNumber,
+		widgets: placements.map((placement, at) => ({
+			kind: "objectNumber",
+			page: placement.page,
+			objectNumber: numbers[at]
+		}))
+	});
+	const next = withFields(snapshot.formKind === "none" ? indexFields({
+		...snapshot,
+		formKind: "acroform"
+	}, index.pictureVersions) : index, [created]);
+	return op.draft.actions?.calculate ? withCalculationOrder(next, [...snapshot.calculationOrder, created.field.ref]) : next;
+}
+/** The fields a change's ops write a value or a look to, each once, in op order. */
+function fieldsNamedBy(index, ops) {
+	const named = /* @__PURE__ */ new Map();
+	const add = (field) => {
+		if (field && !named.has(fieldKeyOf(field))) named.set(fieldKeyOf(field), field);
+	};
+	for (const op of ops) switch (op.type) {
+		case "forms.setValue":
+		case "forms.setDisplay":
+		case "forms.setAppearanceText":
+			add(fieldByRef(index, op.field));
+			break;
+		case "forms.reset":
+			for (const field of op.fields ? op.fields.map((ref) => fieldByRef(index, ref)) : resetTargets(index)) add(field);
+			break;
+		default: break;
+	}
+	return [...named.values()];
+}
+/** `index` with these fields, and their widget rows, as `source` holds them. */
+function withFieldsFrom(index, source, fields) {
+	return withFields(index, fields.flatMap((field) => {
+		const held = fieldByKey(source, fieldKeyOf(field));
+		return held ? [withRows(source, held)] : [];
+	}));
+}
+/** A field and its widgets back as `index` holds them. */
+const restoreOf = (index, field) => ({
+	type: "forms.restore",
+	field,
+	widgets: rowsOfField(index, field)
+});
+/** A widget's row back as `index` holds it, with its field as it is there. */
+const restoreWidgetOf = (index, row) => ({
+	type: "forms.restoreWidget",
+	widget: row,
+	field: fieldForWidget(index, widgetNumber(row))
+});
+/** What undoing one op looks like, over the form it applies to. */
+function undoOfOp(index, op) {
+	switch (op.type) {
+		case "forms.create": return op.objectNumber === void 0 ? [] : [{
+			type: "forms.delete",
+			field: {
+				kind: "objectNumber",
+				objectNumber: op.objectNumber
+			}
+		}];
+		case "forms.update":
+		case "forms.delete": {
+			const field = fieldByRef(index, op.field);
+			return field ? [restoreOf(index, field)] : [];
+		}
+		case "forms.updateWidget":
+		case "forms.deleteWidget": {
+			const row = rowOfRef(index, op.widget);
+			return row ? [restoreWidgetOf(index, row)] : [];
+		}
+		case "forms.removeWidget": {
+			const field = fieldByRef(index, op.field);
+			const row = rowOfRef(index, op.widget);
+			return [...row ? [restoreWidgetOf(index, row)] : [], ...field ? [restoreOf(index, field)] : []];
+		}
+		case "forms.reorderWidgets": {
+			const widgets = (index.snapshot?.widgets ?? []).filter((row) => row.page.objectNumber === op.page.objectNumber).map((row) => row.ref);
+			return [{
+				type: "forms.reorderWidgets",
+				page: op.page,
+				widgets,
+				position: "start"
+			}];
+		}
+		case "forms.reorderCalculations": return [{
+			type: "forms.reorderCalculations",
+			fields: (index.snapshot?.calculationOrder ?? []).filter((ref) => ref !== null),
+			position: "start"
+		}];
+		default: return fieldsNamedBy(index, [op]).map((field) => restoreOf(index, field));
+	}
+}
+/**
+* What undoing `ops` looks like, read off the form they apply to, each over
+* what the ones before it left: the ops that bring the form back, the last
+* op's first. Drawing only: the engine undoes a change by its own record of
+* it.
+*/
+function undoLookOf(before, ops) {
+	const undo = [];
+	let current = before;
+	for (const op of ops) {
+		undo.push(undoOfOp(current, op));
+		current = predictFormOp(current, op);
+	}
+	return undo.reverse().flat();
+}
+//#endregion
+//#region src/sync/fields.ts
+function createFieldsMirror(ctx, events) {
+	const fields = ctx.mirror({
+		name: "fields",
+		initial: emptyFieldIndex,
+		readable: () => ctx.allows("doc.forms.read"),
+		load: async (doc) => ({ value: indexLoadedFields(fields.get(), await doc.forms.list()) }),
+		fold: foldFormEvent,
+		predict: predictFormOp,
+		changed: ({ cause, event, next }) => {
+			if (cause === "load") {
+				if (next.snapshot) events.resynced.emit({ snapshot: next.snapshot });
+				return;
+			}
+			if (!event || !("origin" in event)) return;
+			const { origin } = event;
+			switch (event.type) {
+				case "forms.valueSet":
+					events.valueChanged.emit({
+						field: event.field,
+						origin
+					});
+					return;
+				case "forms.created":
+					events.fieldCreated.emit({
+						field: event.field,
+						origin
+					});
+					return;
+				case "forms.updated":
+				case "forms.widgetAdded":
+				case "forms.widgetRemoved":
+					events.fieldUpdated.emit({
+						field: event.field,
+						origin
+					});
+					return;
+				case "forms.widgetDeleted":
+				case "forms.widgetRestored":
+					if (event.field) events.fieldUpdated.emit({
+						field: event.field,
+						origin
+					});
+					return;
+				case "forms.deleted":
+					if (event.deleted) events.fieldDeleted.emit({
+						ref: event.deleted,
+						origin
+					});
+					return;
+				default: return;
+			}
+		}
+	});
+	return fields;
+}
+//#endregion
+//#region src/services/design.ts
+/**
+* Whether the form's widgets are lent to the annotation plugin now
+* (write/lending.ts): the session may design, the annotation plugin is there,
+* and the active tool doesn't fill. Then the annotation layer draws and edits
+* the widgets, and the form layer leaves them out.
+*/
+function createDesign(ctx, siblings) {
+	const interaction = ctx.tryGet(_embedpdf_plugin_interaction_contract_host.InteractionToken);
+	return { lending: () => siblings.annotation() !== null && interaction !== null && ctx.allows("doc.forms.modify") && !(interaction.getActiveTool()?.enables.has("form-fill") ?? false) };
+}
+//#endregion
+//#region src/services/events.ts
+function createEvents(ctx) {
+	return {
+		valueChanged: ctx.events.source(),
+		fieldCreated: ctx.events.source(),
+		fieldUpdated: ctx.events.source(),
+		fieldDeleted: ctx.events.source(),
+		validationRejected: ctx.events.source(),
+		resynced: ctx.events.source()
+	};
+}
+//#endregion
+//#region src/services/fill-rights.ts
+/**
+* Who may fill in, and sign, which field: the engine's own answer per field
+* (`ctx.allowsField`), so a control gated on it never disagrees with the
+* write. A field's group decides: a `fields:fill` (`fields:sign`) permission
+* for its group, or `doc.forms.fill` (`doc.sign`) for every field.
+*/
+function createFillRights(ctx, fields) {
+	const mayFill = (field) => ctx.allowsField("fill", field);
+	const maySign = (field) => ctx.allowsField("sign", field);
+	/** The form's groups, `null` (no group) among them. */
+	const groups = (0, _embedpdf_core.memo)(() => [fields.view()], (index) => [...new Set((index.snapshot?.fields ?? []).map((field) => field.groupId))]);
+	return {
+		mayFill,
+		maySign,
+		assertMayFill: (field, operation) => ctx.assertAllowedField("fill", field, operation),
+		key: () => groups().map((groupId) => `${mayFill({ groupId }) ? 1 : 0}${maySign({ groupId }) ? 1 : 0}`).join("")
+	};
+}
+//#endregion
+//#region src/services/formatted.ts
+/** The values remembered per field: enough for an undo or two. */
+const KEPT_PER_FIELD = 8;
+const valueOf = (field) => field.family === "text" || field.family === "combobox" ? field.value : null;
+function createFormattedTexts(ctx, fields) {
+	const texts = /* @__PURE__ */ new Map();
+	let version = 0;
+	ctx.listen(ctx.changes.onStaged, (change) => {
+		const view = fields.view();
+		for (const op of change.shows) {
+			if (op.type !== "forms.setAppearanceText") continue;
+			const field = fieldByRef(view, op.field);
+			const value = field ? valueOf(field) : null;
+			if (!field || value === null) continue;
+			const key = fieldKeyOf(field);
+			const kept = texts.get(key) ?? /* @__PURE__ */ new Map();
+			kept.delete(value);
+			kept.set(value, op.text);
+			while (kept.size > KEPT_PER_FIELD) kept.delete(kept.keys().next().value);
+			texts.set(key, kept);
+			version += 1;
+		}
+	});
+	return {
+		textOf(field) {
+			const value = valueOf(field);
+			return value === null ? null : texts.get(fieldKeyOf(field))?.get(value) ?? null;
+		},
+		version: () => version
+	};
+}
+//#endregion
+//#region src/services/looks.ts
+/**
+* What a shown widget looks like now: the engine's picture, or the painter's
+* drawing of it (`@embedpdf/core-form`).
+*
+* A widget's look is everything its picture depends on: its size and turn,
+* its style, and what it shows (the value, as this session formatted it). Its
+* place isn't (a move keeps the look), nor the state a toggle shows (its
+* picture of every state is held). A widget is `pending` while its look in
+* the view isn't its confirmed look: a value typed or calculated, a restyle,
+* a field just placed. The layer then draws the painter's scene, as it does
+* while the picture it holds is older than the widget's look.
+*/
+const NOTHING_SHOWN = Object.freeze([]);
+const numberOf = (ref) => ref.kind === "objectNumber" ? ref.objectNumber : -1;
+function createWidgetLooks({ fields, formatted, design }) {
+	/** What the widget's picture depends on, as one string. */
+	const lookKeyOf = (row, field) => {
+		const box = row.box ?? row.rect;
+		const content = (() => {
+			switch (field?.family) {
+				case "text": return [
+					formatted.textOf(field) ?? field.value,
+					field.multiline,
+					field.password,
+					field.comb,
+					field.maxLength
+				];
+				case "combobox": return [formatted.textOf(field) ?? field.value];
+				case "listbox": return [field.topIndex, field.options.map((option) => [option.label, option.selected])];
+				default: return [field?.family ?? null];
+			}
+		})();
+		return JSON.stringify([
+			box.width,
+			box.height,
+			row.rotation ?? 0,
+			row.color ?? null,
+			row.interiorColor ?? null,
+			row.strokeWidth ?? null,
+			row.borderStyle ?? null,
+			row.dashArray ?? null,
+			row.fontFamily ?? null,
+			row.fontSize ?? null,
+			row.fontColor ?? null,
+			row.textAlign ?? null,
+			row.caption ?? null,
+			row.checkStyle ?? null,
+			content
+		]);
+	};
+	const lookOf = (index, number) => {
+		const row = widgetRowOf(index, number);
+		return row ? lookKeyOf(row, fieldForWidget(index, number)) : null;
+	};
+	const shownOn = (0, _embedpdf_core.memoByKey)((_pageObjectNumber) => [
+		fields.view(),
+		fields.get(),
+		formatted.version(),
+		design.lending()
+	], (pageObjectNumber, view, truth, _formatted, lent) => lent ? NOTHING_SHOWN : shownWidgetsOf(view, pageObjectNumber, (row) => {
+		const number = numberOf(row.ref);
+		return {
+			pending: lookOf(view, number) !== lookOf(truth, number),
+			pictureVersion: pictureVersionOf(truth, number)
+		};
+	}));
+	/** The painter's drawing of `row` (in the view's field, as this session formatted it) at `box`, turned. */
+	const paint = (row, box, rotation) => {
+		const field = fieldForWidget(fields.view(), numberOf(row.ref));
+		if (!field) return null;
+		const text = formatted.textOf(field);
+		const drawing = (0, _embedpdf_core_form.widgetDrawing)({
+			...row,
+			box
+		}, field, text === null ? {} : { text });
+		return drawing && (0, _embedpdf_core_form.widgetScene)(drawing, {
+			box,
+			rotation
+		});
+	};
+	/** The painter's drawing of a widget as the view has it; `null` for one it doesn't draw. */
+	const sceneOf = (0, _embedpdf_core.memoByKey)((number) => {
+		const view = fields.view();
+		const row = widgetRowOf(view, number);
+		const field = row ? fieldForWidget(view, number) : null;
+		return [
+			row,
+			field,
+			field ? formatted.textOf(field) : null
+		];
+	}, (_number, row) => {
+		const scene = row && paint(row, row.box ?? row.rect, row.rotation);
+		return scene ? { scene } : null;
+	});
+	return {
+		listShownWidgets: (pageObjectNumber) => shownOn(pageObjectNumber),
+		getWidgetPainting: (ref) => sceneOf(numberOf(ref)),
+		/** The widget's look in the view isn't its confirmed look yet: it draws live until its picture is. */
+		isPending: (ref) => {
+			const number = numberOf(ref);
+			return lookOf(fields.view(), number) !== lookOf(fields.get(), number);
+		},
+		/**
+		* How the painter draws a widget row live, upright in a box (where a gesture has it); `null`
+		* for one whose field it doesn't draw (a signature).
+		*/
+		painterOf: (row) => {
+			const field = fieldForWidget(fields.view(), numberOf(row.ref));
+			return field && (0, _embedpdf_core_form.paints)(field) ? (box) => paint(row, box, 0) ?? [] : null;
+		},
+		getTextEditorLayout: (ref, text) => {
+			const view = fields.view();
+			const number = numberOf(ref);
+			const row = widgetRowOf(view, number);
+			const field = row ? fieldForWidget(view, number) : null;
+			return row && field ? (0, _embedpdf_core_form.textEditorLayout)(row, field, text) : null;
+		}
+	};
+}
+//#endregion
+//#region src/services/pictures.ts
+/**
+* The engine's pictures of each page's widgets, through the render plugin's
+* one door. The form layer draws them, and the annotation plugin draws the
+* widgets it borrows from the same ones (design mode), so switching modes
+* fetches nothing. A page's pictures depend on its widgets' picture versions
+* (the mirror's) and nothing else: a checkbox that only switches its state
+* fetches nothing.
+*/
+const NO_PICTURES = Object.freeze([]);
+function createWidgetPictures(fields, { render }) {
+	/** The page's widgets, as the engine confirmed them, each at its picture version. */
+	const itemsOn = (0, _embedpdf_core.memoByKey)((_pageObjectNumber) => [fields.get()], (pageObjectNumber, index) => (index.snapshot?.widgets ?? []).flatMap((row) => row.page.objectNumber === pageObjectNumber && row.ref.kind === "objectNumber" ? [{
+		ref: row.ref,
+		version: pictureVersionOf(index, row.ref.objectNumber)
+	}] : []));
+	const epochOn = (0, _embedpdf_core.memoByKey)((pageObjectNumber) => [itemsOn(pageObjectNumber)], (_pageObjectNumber, items) => items.map(({ ref, version }) => `${ref.kind === "objectNumber" ? ref.objectNumber : ""}@${version}`).sort().join("|"));
+	return {
+		epoch: (page) => epochOn(page.objectNumber),
+		render: (page, scale, signal) => {
+			const renderer = render();
+			return renderer ? renderer.renderAppearances(page, {
+				family: "widgets",
+				scale,
+				items: itemsOn(page.objectNumber),
+				...signal ? { signal } : {}
+			}) : Promise.resolve(NO_PICTURES);
+		},
+		versionOf: (widget) => widget.kind === "objectNumber" ? pictureVersionOf(fields.get(), widget.objectNumber) : 0
+	};
+}
+//#endregion
+//#region src/services/scripting.ts
+function createScriptingSeam(ctx, siblings) {
+	let pipeline = null;
+	const pipelineOf = () => {
+		if (pipeline) return pipeline;
+		const realm = siblings.actions()?.scriptRealm ?? null;
+		if (!realm) return null;
+		const made = require_controller.createFormScriptingController({
+			document: () => ctx.document(),
+			transaction: realm.transaction.bind(realm),
+			budget: realm.budget
+		});
+		ctx.cleanup(() => made.dispose());
+		pipeline = made;
+		return made;
+	};
+	const settings = ctx.settings();
+	const controller = () => settings.get().validation === "scripts" ? pipelineOf() : null;
+	let warnedNoRealm = false;
+	const scriptsFor = (form) => {
+		if (!formHasScripts(form)) return null;
+		if (!pipelineOf() && !warnedNoRealm && settings.get().validation === "scripts") {
+			warnedNoRealm = true;
+			console.warn("[form] this form has scripts, but they don't run: add the actions plugin with JavaScript on (`actionsPlugin({ javascript: { enabled: true, sandboxFactory } })`), or set the form's `validation` to 'none' to fill it in without them.");
+		}
+		return controller();
+	};
+	let warmed = false;
+	return {
+		/** The script pipeline when the document's scripts run, else `null`. */
+		controller,
+		/** The script pipeline for a write to this form: `null` too when no field has a script. */
+		scriptsFor,
+		/** Start the realm before the first write needs it, once, when the form has scripts. */
+		warm(form) {
+			if (warmed || !form.snapshot) return;
+			const scripts = scriptsFor(form);
+			if (!scripts) return;
+			warmed = true;
+			scripts.warm(form.snapshot).catch(() => {});
+		},
+		/** Script results (UI effects, diagnostics, errors) are surfaced through the
+		*  actions plugin, with the origin that caused them. */
+		surface: (result, origin) => {
+			siblings.actions()?.surfaceScriptCommit(result, {
+				origin,
+				realm: "document"
+			});
+		}
+	};
+}
+//#endregion
+//#region src/services/siblings.ts
+/** The optional sibling planes, looked up each time they're used, not once
+*  at construction: what a sibling is depends on no creation order. A
+*  fill-only setup may have none; every area guards on null. */
+function resolveSiblings(ctx) {
+	return {
+		/** The annotation plugin: design mode's selection, tools, ghosts and placement previews. */
+		annotation: () => ctx.tryGet(_embedpdf_plugin_annotation_contract_host.AnnotationToken),
+		/** The script realm owner and the one surface port for script results. */
+		actions: () => ctx.tryGet(_embedpdf_plugin_actions_contract_host.ActionsToken),
+		/** The page renderer: the widgets' pictures, shared by the form layer and design mode. */
+		render: () => ctx.tryGet(_embedpdf_plugin_render_contract_host.RenderToken)
+	};
+}
+//#endregion
+//#region src/services/index.ts
+function createServices(ctx) {
+	const siblings = resolveSiblings(ctx);
+	const events = createEvents(ctx);
+	const fields = createFieldsMirror(ctx, events);
+	const design = createDesign(ctx, siblings);
+	const formatted = createFormattedTexts(ctx, fields);
+	return {
+		fields,
+		rights: createFillRights(ctx, fields),
+		events,
+		siblings,
+		scripting: createScriptingSeam(ctx, siblings),
+		design,
+		formatted,
+		pictures: createWidgetPictures(fields, siblings),
+		looks: createWidgetLooks({
+			fields,
+			formatted,
+			design
+		}),
+		enqueue: ctx.serialQueue("writes"),
+		keyOf: (ref) => canonicalKey(fields.view(), ref)
+	};
+}
+//#endregion
+//#region src/write/activation.ts
+/**
+* Widget activation and the widget DOM-event feed into the actions plane.
+* A click first offers the widget's `/A` tree to the dispatcher; only a
+* tree-less widget falls back to the form's own scripted activation.
+*/
+function createActivation(ctx, services, { fill }) {
+	const { fields, scripting } = services;
+	/** The widget's activation action, from its row in the form. */
+	const annotationActivation = async (ref) => {
+		await fields.settled();
+		return (ref.kind === "objectNumber" ? widgetRowOf(fields.view(), ref.objectNumber) : null)?.actions?.activate ?? null;
+	};
+	/** The widget's activation through the form's own scripts: what they change is one fill. */
+	const activateThroughScripts = async (ref, annotationRef, options) => {
+		if (!scripting.controller()) return {
+			status: "unchanged",
+			scripted: false,
+			uiEffects: [],
+			diagnostics: []
+		};
+		const action = await annotationActivation(annotationRef);
+		if (!action) return {
+			status: "unchanged",
+			scripted: true,
+			uiEffects: [],
+			diagnostics: []
+		};
+		const { result } = await fill({
+			ops: [],
+			scripts: {
+				kind: "activate",
+				field: ref,
+				action
+			},
+			origin: "user"
+		}, options);
+		return result;
+	};
+	const widgetSource = (field, annotationRef) => ({
+		kind: "widget",
+		field,
+		annotation: annotationRef,
+		page: annotationRef.page
+	});
+	/**
+	* One shared hover pump (an exit and the next enter delivered as one
+	* ordered pair; intermediate hovers skipped), created on first use.
+	*/
+	let widgetPump = null;
+	const widgetHoverPump = (actions) => {
+		widgetPump ?? (widgetPump = (0, _embedpdf_plugin_actions_contract.createHoverPump)(actions.dispatch));
+		return widgetPump;
+	};
+	const widgetHoverFlags = (annotationRef) => {
+		const row = annotationRef.kind === "objectNumber" ? widgetRowOf(fields.view(), annotationRef.objectNumber) : null;
+		if (!row) return null;
+		return {
+			enter: Boolean(row.actions?.cursorEnter?.root),
+			exit: Boolean(row.actions?.cursorExit?.root)
+		};
+	};
+	return { api: {
+		activateWidget: async (annotationRef, options) => {
+			const field = fieldForWidget(fields.view(), widgetObjectOf(annotationRef));
+			if (!field) throw new _embedpdf_core.PluginError("not-found", "form", "no form field owns this widget");
+			const actions = ctx.tryGet(_embedpdf_plugin_actions_contract.ActionsToken);
+			if (actions) {
+				const result = await ctx.cancellable(options?.signal, actions.dispatch({
+					scope: "activate",
+					ref: annotationRef,
+					page: annotationRef.page,
+					source: widgetSource(field.ref, annotationRef)
+				}));
+				if (!(result.status === "inert" && result.steps.length === 0 && result.diagnostics.length === 0)) return {
+					kind: "dispatched",
+					result
+				};
+			}
+			return {
+				kind: "form",
+				result: await activateThroughScripts(field.ref, annotationRef, options)
+			};
+		},
+		notifyWidgetEvent: (fieldRef, annotationRef, event) => {
+			const actions = ctx.tryGet(_embedpdf_plugin_actions_contract.ActionsToken);
+			if (!actions) return;
+			const source = widgetSource(fieldRef, annotationRef);
+			if (event === "cursorEnter" || event === "cursorExit") {
+				if (event === "cursorExit") {
+					widgetHoverPump(actions).hover(null);
+					return;
+				}
+				const flags = widgetHoverFlags(annotationRef);
+				if (flags && !flags.enter && !flags.exit) return;
+				widgetHoverPump(actions).hover({
+					ref: annotationRef,
+					page: annotationRef.page,
+					source,
+					...flags ? { events: flags } : {}
+				});
+				return;
+			}
+			if (event === "focus") scripting.warm(fields.view());
+			actions.dispatch({
+				scope: "annotation",
+				event,
+				ref: annotationRef,
+				page: annotationRef.page,
+				source
+			});
+		}
+	} };
+}
+//#endregion
+//#region src/services/object-numbers.ts
+function createObjectNumbers(ctx) {
+	const held = [];
+	let watching = false;
+	const watchLost = () => {
+		if (watching || !ctx.doc) return;
+		watching = true;
+		ctx.doc.objectNumbers.onLost(({ numbers }) => {
+			const lost = new Set(numbers);
+			held.splice(0, held.length, ...held.filter((number) => !lost.has(number)));
+		});
+	};
+	const takeNow = (count) => {
+		watchLost();
+		while (held.length < count) {
+			const number = ctx.changes.takeObjectNumber();
+			if (number === null) return null;
+			held.push(number);
+		}
+		return held.splice(0, count);
+	};
+	return {
+		takeNow,
+		async take(count) {
+			for (;;) {
+				const taken = takeNow(count);
+				if (taken) return taken;
+				await ctx.changes.reserveObjectNumbers(count - held.length);
+			}
+		}
+	};
+}
+//#endregion
+//#region src/write/next-in-line.ts
+const fits = (box, page) => box.x >= 0 && box.y >= 0 && box.x + box.width <= page.width && box.y + box.height <= page.height;
+/** The box after `boxes`, the field's widgets on one page in the field's order. */
+function nextInLine(boxes, page) {
+	const last = boxes.at(-1);
+	if (!last) return {
+		x: 0,
+		y: 0,
+		width: 0,
+		height: 0
+	};
+	const { width, height } = last;
+	const previous = boxes.at(-2);
+	const step = previous && (previous.x !== last.x || previous.y !== last.y) ? {
+		x: last.x - previous.x,
+		y: last.y - previous.y
+	} : {
+		x: 0,
+		y: height * 1.5
+	};
+	const next = {
+		x: last.x + step.x,
+		y: last.y + step.y,
+		width,
+		height
+	};
+	if (fits(next, page)) return next;
+	const column = Math.abs(step.y) >= Math.abs(step.x);
+	const left = Math.min(...boxes.map((box) => box.x));
+	const top = Math.min(...boxes.map((box) => box.y));
+	const right = Math.max(...boxes.map((box) => box.x + box.width));
+	const bottom = Math.max(...boxes.map((box) => box.y + box.height));
+	const gap = Math.max(column ? Math.abs(step.y) - height : Math.abs(step.x) - width, 0);
+	const restart = column ? {
+		x: right + (gap || width / 2),
+		y: top,
+		width,
+		height
+	} : {
+		x: left,
+		y: bottom + (gap || height / 2),
+		width,
+		height
+	};
+	if (fits(restart, page)) return restart;
+	return {
+		x: Math.min(Math.max(next.x, 0), Math.max(page.width - width, 0)),
+		y: Math.min(Math.max(next.y, 0), Math.max(page.height - height, 0)),
+		width,
+		height
+	};
+}
+//#endregion
+//#region src/write/fields.ts
+/**
+* Building the form: every design verb is one change on the document's queue
+* (`ctx.changes`). It shows at once (the fields mirror predicts it), it is a
+* step of the history, and it resolves with the engine's answer. A create
+* takes its field's and widgets' object numbers first, so their refs are final
+* from the first frame and the new widget can be selected straight away.
+*/
+/**
+* A widget's look, as `addWidget()` copies it from the field's last widget onto the new one:
+* the engine's widget style fields (`WIDGET_STYLE_NAMES`), and its turn.
+*/
+const LOOK = [
+	"color",
+	"interiorColor",
+	"strokeWidth",
+	"borderStyle",
+	"dashArray",
+	"fontFamily",
+	"fontSize",
+	"fontColor",
+	"textAlign",
+	"caption",
+	"checkStyle",
+	"rotation"
+];
+const lookOf = (widget) => {
+	if (!widget) return {};
+	const held = widget;
+	const look = {};
+	for (const name of LOOK) if (held[name] !== void 0 && held[name] !== null) look[name] = held[name];
+	return look;
+};
+/**
+* The export value a field's new widget gets when none is given: a radio group's next free
+* `Choice<n>` (the radio tool names its first button `Choice1`), a checkbox's own value, so
+* the boxes check together. Other families take none.
+*/
+function exportValueFor(field) {
+	if (field.family === "checkbox") return field.exportValue;
+	if (field.family !== "radio") return void 0;
+	const taken = new Set(field.widgets.map((widget) => widget.exportValue));
+	let n = field.widgets.length + 1;
+	while (taken.has(`Choice${n}`)) n += 1;
+	return `Choice${n}`;
+}
+/** Whether the field's dictionary is its only widget's too, which adding a widget splits. */
+const isMerged = (field) => field.ref.kind === "objectNumber" && field.widgets.some((widget) => widget.objectNumber === field.ref.objectNumber);
+const MODIFY = "doc.forms.modify";
+const SCRIPT = "doc.forms.script";
+function createFieldWrites(ctx, { fields, enqueue }) {
+	const numbers = createObjectNumbers(ctx);
+	/** Refuse up front without `doc.forms.modify`, and without `doc.forms.script` when it writes scripts. */
+	const allow = (operation, scripts = false) => {
+		ctx.assertAllowed(MODIFY, operation);
+		if (scripts) ctx.assertAllowed(SCRIPT, operation);
+	};
+	/** Stage one design op as its own change: it shows at once, and undoing it shows the form as it was. */
+	const stage = (verb, op) => ctx.changes.stage({
+		label: { key: `form.${verb}` },
+		ops: [op],
+		undo: undoLookOf(fields.view(), [op])
+	});
+	/** The engine's answer to a staged design change: its one item. */
+	const answer = async (change, options) => {
+		try {
+			return (await ctx.cancellable(options?.signal, change.result)).items[0];
+		} catch (error) {
+			throw (0, _embedpdf_core.toPluginError)("form", error);
+		}
+	};
+	const create = async (draft, options) => {
+		allow("form.create", (0, _embedpdf_engine_core_runtime.draftWritesScripts)(draft));
+		const count = 1 + (draft.widgets?.length ?? 0);
+		const [objectNumber, ...widgetObjectNumbers] = numbers.takeNow(count) ?? await numbers.take(count);
+		const change = stage("create", {
+			type: "forms.create",
+			draft,
+			objectNumber,
+			widgetObjectNumbers
+		});
+		return { field: (await answer(change, options)).field };
+	};
+	const addWidget = async (ref, placement = {}, options) => {
+		allow("form.addWidget", (0, _embedpdf_engine_core_runtime.writesScripts)(placement.actions));
+		const index = fields.view();
+		const field = fieldByRef(index, ref);
+		if (!field) throw new _embedpdf_core.PluginError("not-found", "form", "no form field has this ref");
+		const rows = field.widgets.map((widget) => widgetRowOf(index, widget.objectNumber)).filter((row) => row !== null);
+		const last = rows.at(-1);
+		const page = placement.page ?? last?.page;
+		if (!page) throw new _embedpdf_core.PluginError("invalid-input", "form", "the field shows on no page: give `page` and `rect`");
+		const size = ctx.getPage(page)?.size;
+		const onPage = rows.filter((row) => row.page.objectNumber === page.objectNumber);
+		const rect = placement.rect ?? placement.box ?? (size && onPage.length > 0 ? nextInLine(onPage.map((row) => row.box), size) : void 0);
+		if (!rect) throw new _embedpdf_core.PluginError("invalid-input", "form", "no widget of the field on that page: give `rect`");
+		const exportValue = placement.exportValue ?? exportValueFor(field);
+		const split = isMerged(field);
+		const [objectNumber, splitObjectNumber] = numbers.takeNow(split ? 2 : 1) ?? await numbers.take(split ? 2 : 1);
+		const change = stage("addWidget", {
+			type: "forms.addWidget",
+			field: field.ref,
+			placement: {
+				...lookOf(last),
+				...placement,
+				page,
+				...placement.box ? {} : { rect },
+				...exportValue === void 0 ? {} : { exportValue }
+			},
+			objectNumber,
+			...split ? { splitObjectNumber } : {}
+		});
+		const item = await answer(change, options);
+		const widget = item.widgets.find((row) => row.ref.kind === "objectNumber" && row.ref.objectNumber === objectNumber) ?? item.widgets.at(-1);
+		return {
+			field: item.field,
+			widget
+		};
+	};
+	return { api: {
+		create,
+		addWidget,
+		update: async (ref, patch, options) => {
+			allow("form.update", (0, _embedpdf_engine_core_runtime.writesScripts)(patch.actions));
+			const change = stage("update", {
+				type: "forms.update",
+				field: ref,
+				patch
+			});
+			return { field: (await answer(change, options)).field };
+		},
+		reorderCalculations: async (fields, position, options) => {
+			allow("form.reorderCalculations");
+			const change = stage("reorderCalculations", {
+				type: "forms.reorderCalculations",
+				fields,
+				position
+			});
+			return { calculationOrder: (await answer(change, options)).calculationOrder };
+		},
+		delete: async (ref, options) => {
+			allow("form.delete");
+			await answer(stage("delete", {
+				type: "forms.delete",
+				field: ref
+			}), options);
+		},
+		removeWidget: async (ref, widget, options) => {
+			allow("form.removeWidget");
+			const change = stage("removeWidget", {
+				type: "forms.removeWidget",
+				field: ref,
+				widget
+			});
+			return { field: (await answer(change, options)).field };
+		},
+		updateWidget: async (widget, patch, options) => {
+			allow("form.updateWidget");
+			const change = stage("updateWidget", {
+				type: "forms.updateWidget",
+				widget,
+				patch
+			});
+			return { widget: (await answer(change, options)).widget };
+		},
+		deleteWidget: async (widget, options) => {
+			allow("form.deleteWidget");
+			const change = stage("deleteWidget", {
+				type: "forms.deleteWidget",
+				widget
+			});
+			return { field: (await answer(change, options)).field };
+		},
+		repair: async (options) => {
+			allow("form.repair");
+			const { signal, ...repair } = options ?? {};
+			const run = () => options ? ctx.doc.forms.repair(repair) : ctx.doc.forms.repair();
+			return enqueue(() => ctx.cancellable(signal, run()), options);
+		}
+	} };
+}
+//#endregion
+//#region src/write/fill.ts
+/**
+* Filling the form in. Every fill is one change, whatever started it: a value, a batch of
+* values, a reset, a widget's activation, a script's or an action's effects.
+*
+*   1. What the user did shows at once: the change is held with the user's own ops.
+*   2. When its turn comes, the form's scripts run against the view, in one realm transaction.
+*   3. Inside that transaction the change gets every op the scripts asked for, and is sent.
+*
+* Fills take turns up to their send, not their answer: the next fill's scripts read this one in
+* the view while the engine answers it. A validation refusal cancels the change. A change the
+* engine refuses leaves the view, and the calculations run again against what is left, outside
+* the history: the fills after it were calculated with its values.
+*/
+/** A refused value writes only what the document's open scripts did, outside the history. */
+const SCRIPTS_LABEL = { key: "form.scripts" };
+/** The calculations again, outside the history: after a refused fill, or a stale one. */
+const RECALCULATE_LABEL = { key: "form.recalculate" };
+/** The changes that, refused, leave calculations made with their values. */
+const FILLS = /* @__PURE__ */ new Set(["form.fill", "form.reset"]);
+const sameOp = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+const sameValue = (left, right) => JSON.stringify(left?.valueEntry ?? null) === JSON.stringify(right?.valueEntry ?? null);
+function createFill(ctx, { fields, scripting, enqueue }) {
+	const labelOf = (request, index, ops) => request.label ?? {
+		key: "form.fill",
+		count: fieldsNamedBy(index, ops).length
+	};
+	/** Step 1: what the user did shows at once. */
+	const begin = (request) => {
+		const before = fields.view();
+		const shown = request.ops.reduce(predictFormOp, before);
+		if (request.ops.length === 0) return {
+			request,
+			before,
+			shown,
+			hold: null
+		};
+		const hold = ctx.changes.hold(labelOf(request, before, request.ops));
+		hold.set(request.ops, undoLookOf(before, request.ops));
+		return {
+			request,
+			before,
+			shown,
+			hold
+		};
+	};
+	/**
+	* The form the change is undone to: as it is now, with the user's own fields as they were
+	* before the user's ops showed.
+	*/
+	const baseOf = ({ request, before }) => withFieldsFrom(fields.view(), before, fieldsNamedBy(before, request.ops));
+	/** Whether the hold went with the user's ops before the scripts finished. */
+	const sentEarly = ({ hold }) => hold !== null && !hold.open && !!hold.change;
+	/** Whether the form still shows the values the user's ops wrote: the scripts ran for those. */
+	const stillShown = ({ request, shown }) => {
+		const now = fields.view();
+		return fieldsNamedBy(shown, request.ops).every((field) => sameValue(fieldByKey(now, fieldKeyOf(field)), field));
+	};
+	/** Step 3: the change with all its ops, sent. */
+	const send = (begun, ops, script) => {
+		const { request, hold } = begun;
+		if (ops.length === 0) {
+			hold?.cancel();
+			return {
+				script,
+				changes: [],
+				after: fields.view()
+			};
+		}
+		if (!hold) {
+			const label = labelOf(request, fields.view(), ops);
+			return {
+				script,
+				changes: [ctx.changes.stage({
+					label,
+					ops,
+					undo: undoLookOf(baseOf(begun), ops)
+				})],
+				after: fields.view()
+			};
+		}
+		if (hold.open) {
+			hold.set(ops, undoLookOf(baseOf(begun), ops));
+			const change = hold.send();
+			return {
+				script,
+				changes: change ? [change] : [],
+				after: fields.view()
+			};
+		}
+		const sent = hold.change;
+		const rest = ops.filter((op) => !sent?.shows.some((shown) => sameOp(shown, op)));
+		const changes = sent ? [sent] : [];
+		if (rest.length > 0) {
+			const label = labelOf(request, fields.view(), rest);
+			changes.push(ctx.changes.stage({
+				label,
+				ops: rest,
+				undo: undoLookOf(fields.view(), rest)
+			}));
+		}
+		return {
+			script,
+			changes,
+			after: fields.view()
+		};
+	};
+	/** The user's ops went on their own and the scripts refused them: their fields are written back. */
+	const takeBack = ({ request, before }) => {
+		const ops = fieldsNamedBy(before, request.ops).flatMap((field) => {
+			const value = (0, _embedpdf_engine_core_runtime.fieldValueOf)(field);
+			return value ? [{
+				type: "forms.setValue",
+				field: field.ref,
+				value
+			}] : [];
+		});
+		if (ops.length === 0) return;
+		ctx.changes.stage({
+			label: labelOf(request, before, ops),
+			ops,
+			history: false
+		});
+	};
+	/** The calculations again, against what the form shows now: one change, outside the history. */
+	const recalculateNow = async (scripts, origin) => {
+		const shown = fields.view().snapshot;
+		if (!shown) return;
+		const script = await scripts.recalculate(shown);
+		scripting.surface(script, origin);
+		if (script.status !== "accepted" || script.effects.length === 0) return;
+		ctx.changes.stage({
+			label: RECALCULATE_LABEL,
+			ops: (0, _embedpdf_engine_core_runtime.formEffectOps)(script.effects),
+			history: false
+		});
+	};
+	/** Step 2: the scripts, against the view. */
+	const runScripts = (scripts, begun, plan) => {
+		const shown = fields.view().snapshot;
+		if (!shown) return null;
+		switch (plan.kind) {
+			case "commit": {
+				const form = baseOf(begun).snapshot ?? shown;
+				return scripts.commit(form, plan.field, plan.value);
+			}
+			case "activate": return scripts.activate(shown, plan.field, plan.action);
+			case "recalculate": return scripts.recalculate(shown);
+		}
+	};
+	/** Steps 2 and 3, when the fill's turn comes. */
+	const finish = async (begun) => {
+		const { request, hold } = begun;
+		const plan = request.scripts;
+		const pipeline = !plan ? null : plan.kind === "activate" ? scripting.controller() : scripting.scriptsFor(fields.view());
+		if (!plan || !pipeline) return send(begun, request.ops, null);
+		if (!fields.view().snapshot) await fields.settled();
+		try {
+			return await pipeline.transaction(async (scripts) => {
+				const running = runScripts(scripts, begun, plan);
+				if (!running) return send(begun, request.ops, null);
+				const script = await running;
+				scripting.surface(script, request.origin);
+				const early = sentEarly(begun);
+				if (script.status !== "accepted") {
+					hold?.cancel();
+					if (early) takeBack(begun);
+					if (script.status === "rejected" && script.bootEffects.length > 0) ctx.changes.stage({
+						label: SCRIPTS_LABEL,
+						ops: (0, _embedpdf_engine_core_runtime.formEffectOps)(script.bootEffects),
+						history: false
+					});
+					return {
+						script,
+						changes: [],
+						after: fields.view()
+					};
+				}
+				if (early && !stillShown(begun)) {
+					await recalculateNow(scripts, request.origin);
+					return {
+						script,
+						changes: [hold.change],
+						after: fields.view()
+					};
+				}
+				const effects = (0, _embedpdf_engine_core_runtime.formEffectOps)(script.effects);
+				return send(begun, plan.kind === "recalculate" ? [...request.ops, ...effects] : effects, script);
+			});
+		} catch (error) {
+			hold?.cancel();
+			throw error;
+		}
+	};
+	/** What a sent fill did, once the engine answered. */
+	const answered = async (begun, sent) => {
+		const { script } = sent;
+		const reported = {
+			scripted: script !== null,
+			uiEffects: script?.uiEffects ?? [],
+			diagnostics: script?.diagnostics ?? [],
+			...script?.error ? { error: script.error } : {}
+		};
+		const outcome = (status) => ({
+			result: {
+				status,
+				...reported
+			},
+			before: begun.before,
+			after: sent.after
+		});
+		if (script?.status === "failed") return outcome("failed");
+		if (script?.status === "rejected") return outcome("rejected");
+		let undoable = false;
+		for (const change of sent.changes) try {
+			undoable = (await change.result).meta.undoable || undoable;
+		} catch (error) {
+			throw (0, _embedpdf_core.toPluginError)("form", error);
+		}
+		return outcome(undoable ? "applied" : "unchanged");
+	};
+	/**
+	* Fill the form in: shown at once, sent when its turn comes; resolves once the engine
+	* answered. A change the engine refuses rejects.
+	*/
+	const fill = async (request, options) => {
+		const begun = begin(request);
+		let sent;
+		try {
+			sent = await enqueue(() => finish(begun), options);
+		} catch (error) {
+			begun.hold?.cancel();
+			throw (0, _embedpdf_core.toPluginError)("form", error);
+		}
+		return ctx.cancellable(options?.signal, answered(begun, sent));
+	};
+	/**
+	* Fill the form in without waiting: what a script's effects need, written while its own
+	* transaction still runs. A failure is reported as the scripts' error.
+	*/
+	const fillSoon = (request) => {
+		const begun = begin(request);
+		enqueue(() => finish(begun)).catch((error) => {
+			begun.hold?.cancel();
+			const message = (0, _embedpdf_core.toPluginError)("form", error).message;
+			scripting.surface({
+				uiEffects: [],
+				diagnostics: [],
+				error: require_controller.scriptError(message)
+			}, request.origin);
+		});
+	};
+	let recalculating = false;
+	const recalculate = () => enqueue(async () => {
+		recalculating = false;
+		const pipeline = scripting.controller();
+		if (pipeline) await pipeline.transaction((scripts) => recalculateNow(scripts, "user"));
+	});
+	ctx.changes.onSettled((settled) => {
+		if (settled.status !== "refused" || settled.change.undoOf !== null) return;
+		if (!FILLS.has(settled.change.label.key) || recalculating) return;
+		const order = fields.view().snapshot?.calculationOrder ?? [];
+		if (!scripting.controller() || !order.some((ref) => ref !== null)) return;
+		recalculating = true;
+		recalculate().catch(() => {});
+	});
+	ctx.onSettle(async () => {
+		await enqueue.idle();
+		await ctx.changes.whenSettled();
+	});
+	return {
+		fill,
+		fillSoon
+	};
+}
+/** A fill that failed in the form's own scripts, as the verbs report it. */
+function failedFill(result) {
+	return new _embedpdf_core.PluginError("operation-failed", "form", result.error?.message ?? result.diagnostics[0]?.message ?? "the write failed");
+}
+//#endregion
+//#region src/write/interchange.ts
+function createInterchange(ctx, services) {
+	const { enqueue, siblings } = services;
+	const exportBundle = async (selection = {}, options) => {
+		ctx.assertAllowed("doc.forms.read", "form.export");
+		ctx.assertAllowed("doc.download", "form.export");
+		const pages = selection.pages?.map((page) => ctx.pageOf(page).ref);
+		return enqueue(() => ctx.cancellable(options?.signal, ctx.doc.forms.export({
+			...selection.fields ? { fields: selection.fields } : {},
+			...pages ? { pages } : {}
+		})), options);
+	};
+	const importBundle = async (bundle, options = {}) => {
+		const { signal, ...importOptions } = options;
+		ctx.assertAllowed("doc.forms.modify", "form.import");
+		if ((importOptions.attribution ?? "restore") === "restore") ctx.assertAllowed("doc.forms.import", "form.import");
+		return enqueue(async () => {
+			const result = await ctx.cancellable(signal, ctx.doc.forms.import(bundle, importOptions));
+			const annotationHost = siblings.annotation();
+			if (annotationHost) await annotationHost.whenSynced();
+			return {
+				fields: result.fields,
+				refMap: result.refMap,
+				dropped: result.dropped
+			};
+		}, options);
+	};
+	return { api: {
+		export: exportBundle,
+		import: importBundle
+	} };
+}
+//#endregion
+//#region src/write/lending.ts
+/**
+* Design mode: the form's widgets, lent to the annotation plugin
+* (`AnnotationLender`, its host contract). While the session may design and
+* the active tool doesn't fill, the annotation plugin shows the widgets among
+* its records and edits them with its tools: select, move, resize, restyle,
+* reorder, delete. Each edit comes back here as the form's ops, in the same
+* change as the rest of it. While the tool fills, nothing is lent, and the
+* form layer draws and fills every widget.
+*/
+const objectNumberOf = (ref) => ref.kind === "objectNumber" ? ref.objectNumber : -1;
+function createWidgetLender(ctx, { fields, design, pictures, looks }) {
+	const records = (0, _embedpdf_core.memo)(() => [
+		design.lending(),
+		fields.get().snapshot,
+		fields.view().snapshot
+	], (lending, confirmed, shown) => lending && confirmed && shown ? {
+		confirmed: confirmed.widgets,
+		shown: shown.widgets
+	} : null);
+	/**
+	* Deleted widgets, as the form's ops: a widget leaves its field
+	* (`deleteWidget`), and a field whose every widget goes is deleted whole
+	* (a merged field and widget among them).
+	*/
+	const deleteOps = (deleted) => {
+		const index = fields.view();
+		const ops = [];
+		const byField = /* @__PURE__ */ new Map();
+		for (const row of deleted) {
+			const field = fieldForWidget(index, objectNumberOf(row.ref));
+			if (!field) {
+				ops.push({
+					type: "forms.deleteWidget",
+					widget: row.ref
+				});
+				continue;
+			}
+			const entry = byField.get(fieldKeyOf(field)) ?? {
+				field,
+				widgets: []
+			};
+			entry.widgets.push(row);
+			byField.set(fieldKeyOf(field), entry);
+		}
+		for (const { field, widgets } of byField.values()) {
+			const going = new Set(widgets.map((row) => objectNumberOf(row.ref)));
+			if (field.widgets.every((widget) => going.has(widget.objectNumber))) ops.push({
+				type: "forms.delete",
+				field: field.ref
+			});
+			else ops.push(...widgets.map((row) => ({
+				type: "forms.deleteWidget",
+				widget: row.ref
+			})));
+		}
+		return ops;
+	};
+	return {
+		owner: "form",
+		records,
+		opsOf(effects, model, before) {
+			const ops = [];
+			const deleted = [];
+			for (const effect of effects) if (effect.type === "patch") {
+				const ref = (0, _embedpdf_core_annotation.refOf)(model.byId[effect.id]);
+				if (!ref) continue;
+				const { subtype: _subtype, ...patch } = effect.patch;
+				ops.push({
+					type: "forms.updateWidget",
+					widget: ref,
+					patch
+				});
+			} else if (effect.type === "delete") {
+				const record = before.byId[effect.id];
+				if (record) deleted.push(record.annotation);
+			}
+			return [...ops, ...deleteOps(deleted)];
+		},
+		undoOf: (ops) => undoLookOf(fields.view(), ops),
+		reorderOps: (page, refs, position) => [{
+			type: "forms.reorderWidgets",
+			page,
+			widgets: [...refs],
+			position
+		}],
+		authority: () => {
+			const may = ctx.allows("doc.forms.modify");
+			return {
+				update: may,
+				delete: may
+			};
+		},
+		pictureEpoch: pictures.epoch,
+		pictureVersion: pictures.versionOf,
+		renderAppearances: pictures.render,
+		pending: looks.isPending,
+		painter: (record) => record.subtype === "widget" ? looks.painterOf(record) : null
+	};
+}
+//#endregion
 //#region src/field-selection.ts
 /**
-* ISO field selection, written ONCE for ResetForm (Tables 241/242) and
-* SubmitForm (Tables 239/240): a NAME target selects the field AND its
+* ISO field selection, written once for ResetForm (Tables 241/242) and
+* SubmitForm (Tables 239/240): a name target selects the field and its
 * descendants (FQN dot-prefix — `parent` selects `parent.c1`, the rule the
 * old exact-match resolution violated); an objectNumber target selects that
 * field dictionary. Include mode keeps the selection; exclude mode keeps
 * the complement (a name excludes its subtree the same way it includes
-* it). `targets === null` (the key ABSENT) selects everything and the flag
-* is ignored; `[]` + include selects NOTHING while `[]` + exclude selects
+* it). `targets === null` (the key absent) selects everything and the flag
+* is ignored; `[]` + include selects nothing while `[]` + exclude selects
 * everything — presence and emptiness are different states.
 *
-* `listed` reports whether a field was ADDRESSED by the target list
+* `listed` reports whether a field was addressed by the target list
 * (directly or through its subtree) — the "explicitly listed" predicate the
 * submit honesty diagnostics key on.
 */
@@ -31,17 +2523,17 @@ const resolveFieldSelection = (all, targets, exclude) => {
 		selected: [...all],
 		listed: () => false
 	};
-	const names = targets.filter((t) => t.kind === "name").map((t) => t.name);
-	const objectNumbers = new Set(targets.filter((t) => t.kind === "objectNumber").map((t) => t.objectNumber));
-	const listed = (field) => field.ref.kind === "objectNumber" && objectNumbers.has(field.ref.fieldObjectNumber) || names.some((name) => field.name === name || field.name.startsWith(`${name}.`));
+	const names = targets.filter((target) => target.kind === "name").map((target) => target.name);
+	const objectNumbers = new Set(targets.filter((target) => target.kind === "objectNumber").map((target) => target.objectNumber));
+	const listed = (field) => field.ref.kind === "objectNumber" && objectNumbers.has(field.ref.objectNumber) || names.some((name) => field.name === name || field.name.startsWith(`${name}.`));
 	return {
-		selected: exclude ? all.filter((f) => !listed(f)) : all.filter(listed),
+		selected: exclude ? all.filter((field) => !listed(field)) : all.filter(listed),
 		listed
 	};
 };
 /**
 * Build the resolved submission dataset from a live field list (Tables
-* 239/240 semantics; pure — the capability supplies a FRESH engine read so
+* 239/240 semantics; pure — the capability supplies a fresh engine read so
 * no model-lag class exists):
 *
 * - the unconditional **NoExport veto** — even an explicit include cannot
@@ -49,11 +2541,11 @@ const resolveFieldSelection = (all, targets, exclude) => {
 *   observable, silent when swept in implicitly);
 * - **push-buttons and signatures** never contribute entries in v1 —
 *   ISO's explicit-pushbutton-`/AP`-in-FDF rule is unrepresentable in the
-*   current DTO, so an EXPLICITLY listed one is diagnosed
+*   current DTO, so an explicitly listed one is diagnosed
 *   (`submit-entry-unsupported`), never silently dropped;
 * - an **unsupported `/V` shape** is always diagnosed (silent omission
 *   would be data loss);
-* - a valueless field becomes a NAME-ONLY entry (`value: null`) only under
+* - a valueless field becomes a name-only entry (`value: null`) only under
 *   IncludeNoValueFields, else it is skipped (the ISO default);
 * - values are entry-faithful: scalar → string, array (multi-select list
 *   box) → string[]; the submitted name is the fully qualified name.
@@ -71,7 +2563,7 @@ const buildSubmitEntries = (fields, intent, diagnose) => {
 			});
 			continue;
 		}
-		if (field.flags.noExport) {
+		if (field.noExport) {
 			if (explicit) diagnose({
 				code: "submit-entry-unsupported",
 				message: `submit: '${field.name}' carries the NoExport flag — the veto is unconditional (ISO 12.7.6.2), skipped`
@@ -100,1241 +2592,461 @@ const buildSubmitEntries = (fields, intent, diagnose) => {
 	return entries;
 };
 //#endregion
-//#region src/core/model.ts
-const fieldKeyOf = (field) => field.fieldObjectNumber > 0 ? `obj:${field.fieldObjectNumber}` : `fqn:${field.name}`;
-const initialModel = () => ({
-	snapshot: null,
-	byKey: {},
-	byWidget: {},
-	writing: {},
-	geom: {},
-	seq: 0
-});
-function index(snapshot) {
-	const byKey = {};
-	const byWidget = {};
-	snapshot.fields.forEach((field, i) => {
-		byKey[fieldKeyOf(field)] = i;
-		for (const w of field.widgets) if (w.annotObjectNumber > 0) byWidget[w.annotObjectNumber] = i;
-	});
-	return {
-		byKey,
-		byWidget
-	};
-}
-function update(model, msg) {
-	switch (msg.t) {
-		case "snapshot": return {
-			...model,
-			snapshot: msg.snapshot,
-			...index(msg.snapshot),
-			writing: {},
-			seq: model.seq + 1
-		};
-		case "writeStart": return {
-			...model,
-			writing: {
-				...model.writing,
-				[msg.key]: true
-			},
-			seq: model.seq + 1
-		};
-		case "writeDone": {
-			if (!model.snapshot) return model;
-			const i = model.byKey[msg.key];
-			if (i === void 0) return model;
-			const fields = model.snapshot.fields.slice();
-			fields[i] = msg.field;
-			const { [msg.key]: _done, ...writing } = model.writing;
-			const snapshot = {
-				...model.snapshot,
-				fields
-			};
-			return {
-				...model,
-				snapshot,
-				...index(snapshot),
-				writing,
-				seq: model.seq + 1
-			};
-		}
-		case "writeFailed": {
-			const { [msg.key]: _failed, ...writing } = model.writing;
-			return {
-				...model,
-				writing,
-				seq: model.seq + 1
-			};
-		}
-		case "pageGeom": return {
-			...model,
-			geom: {
-				...model.geom,
-				[msg.pageObjectNumber]: msg.boxes
-			},
-			seq: model.seq + 1
-		};
-		case "clearGeom": {
-			if (msg.pageObjectNumber === void 0) return {
-				...model,
-				geom: {},
-				seq: model.seq + 1
-			};
-			const geom = { ...model.geom };
-			delete geom[msg.pageObjectNumber];
-			return {
-				...model,
-				geom,
-				seq: model.seq + 1
-			};
-		}
-	}
-}
-const fieldByKey = (model, key) => {
-	const i = model.byKey[key];
-	return i === void 0 ? null : model.snapshot?.fields[i] ?? null;
-};
-const fieldForWidget = (model, annotObjectNumber) => {
-	const i = model.byWidget[annotObjectNumber];
-	return i === void 0 ? null : model.snapshot?.fields[i] ?? null;
-};
-const contains = (b, p) => p.x >= b.x && p.x <= b.x + b.width && p.y >= b.y && p.y <= b.y + b.height;
-/**
-* The widget under a content-space point, from the model's loaded geometry
-* for that page (null when the page's geometry has not arrived, or nothing
-* is there). Nested widgets resolve to the smallest containing box.
-*/
-const widgetAt = (model, pageObjectNumber, point) => {
-	const geom = model.geom[pageObjectNumber];
-	if (!geom) return null;
-	let best = null;
-	for (const [key, box] of Object.entries(geom)) {
-		if (!contains(box, point)) continue;
-		const annotObjectNumber = Number(key);
-		const field = fieldForWidget(model, annotObjectNumber);
-		if (!field) continue;
-		if (!best || box.width * box.height < best.box.width * best.box.height) best = {
-			annotObjectNumber,
-			field,
-			box
-		};
-	}
-	return best;
+//#region src/write/reset.ts
+/** A reset of no fields: what the executor reports as inert. */
+const NOTHING_RESET = {
+	status: "unchanged",
+	scripted: false,
+	uiEffects: [],
+	diagnostics: []
 };
-//#endregion
-//#region src/core/fill-items.ts
-const ZERO_BOX = {
-	x: 0,
-	y: 0,
-	width: 0,
-	height: 0
+/** A field ref as an action's target: by object number, or by full name. */
+const targetOf = (ref) => ref.kind === "objectNumber" ? {
+	kind: "objectNumber",
+	objectNumber: ref.objectNumber
+} : {
+	kind: "name",
+	name: ref.name
 };
-/**
-* Project ONE widget of a field into a fill control. `box` is supplied by the
-* caller: the page projection reads the model's widget geometry; a consumer
-* that already owns a live box (the annotation plane's RenderItem) passes it —
-* or nothing, when only the semantics matter. Null for families with no fill
-* control (unknown: rendered by the annotation plane only).
-*/
-function projectWidget(model, field, annotObjectNumber, box = ZERO_BOX) {
-	const key = fieldKeyOf(field);
-	const base = {
-		key,
-		annotObjectNumber,
-		box,
-		disabled: field.flags.readOnly || model.writing[key] === true,
-		label: field.alternateName ?? field.name
+function createResetWrites(_ctx, services, { fill }) {
+	const { fields, rights } = services;
+	/**
+	* Whether a reset puts this field back: the engine refuses push button and
+	* signature refs, and another signer's fields are theirs.
+	*/
+	const resettable = (field) => field.family !== "pushbutton" && field.family !== "signature" && rights.mayFill(field);
+	/**
+	* Reset the selected fields, then recalculate, as one change. `origin` is carried through to
+	* the surfaced recalculation results, so a ResetForm run by a page or hover trigger never
+	* reports its alerts as a user action. `null` when it selects nothing; a refused reset throws:
+	* none of it was written.
+	*/
+	const resetSelection = async (targets, exclude, origin, options) => {
+		if (!fields.view().snapshot) await fields.settled();
+		const { selected } = resolveFieldSelection(fields.view().snapshot?.fields ?? [], targets, exclude);
+		const refs = selected.filter(resettable).map((field) => field.ref);
+		if (refs.length === 0) return null;
+		return fill({
+			label: {
+				key: "form.reset",
+				count: refs.length
+			},
+			ops: [{
+				type: "forms.reset",
+				fields: refs
+			}],
+			scripts: { kind: "recalculate" },
+			origin
+		}, options);
 	};
-	switch (field.family) {
-		case "text": return {
-			...base,
-			control: "text",
-			value: field.value,
-			multiline: field.multiline,
-			password: field.password,
-			maxLength: field.maxLength,
-			comb: field.comb
-		};
-		case "checkbox": {
-			const toggle = field.widgets.find((w) => w.annotObjectNumber === annotObjectNumber);
-			return {
-				...base,
-				control: "toggle",
-				kind: "checkbox",
-				checked: field.checked,
-				onState: toggle && "onState" in toggle ? toggle.onState : "Yes"
-			};
+	const reset = async (refs, options) => {
+		for (const ref of refs ?? []) {
+			const field = fieldByRef(fields.view(), ref);
+			if (field) rights.assertMayFill(field, "form.reset");
 		}
-		case "radio": {
-			const toggle = field.widgets.find((w) => w.annotObjectNumber === annotObjectNumber);
-			return {
-				...base,
-				control: "toggle",
-				kind: "radio",
-				checked: toggle && "checked" in toggle ? toggle.checked : false,
-				onState: toggle && "onState" in toggle ? toggle.onState : ""
-			};
+		if (refs && refs.length === 0) return { fields: [] };
+		const outcome = await resetSelection(refs ? refs.map(targetOf) : null, false, "user", options);
+		return { fields: outcome ? fieldsWithChangedValues(outcome.before, outcome.after) : [] };
+	};
+	return { api: {
+		reset,
+		resetFormAction: async (targets, exclude, origin = "user") => {
+			const outcome = await resetSelection(targets, exclude, origin);
+			if (!outcome) return NOTHING_RESET;
+			const { result } = outcome;
+			return result.status === "unchanged" ? {
+				...result,
+				status: "applied"
+			} : result;
 		}
-		case "combobox": return {
-			...base,
-			control: "choice",
-			kind: "combo",
-			edit: field.edit,
-			multi: false,
-			options: field.options,
-			selected: field.value === "" ? [] : [field.value]
-		};
-		case "listbox": return {
-			...base,
-			control: "choice",
-			kind: "list",
-			edit: false,
-			multi: field.multiSelect,
-			options: field.options,
-			selected: field.selectedValues
-		};
-		case "pushbutton": return {
-			...base,
-			control: "button"
-		};
-		case "signature": return {
-			...base,
-			control: "signature",
-			signed: field.valueEntry.kind !== "none"
-		};
-		default: return null;
-	}
-}
-/**
-* Project one page's widgets into fill controls. Widgets whose geometry has
-* not arrived yet (or that are direct objects with no join key) are skipped —
-* the shell re-runs the projection when `pageGeom` lands.
-*/
-function fillItems(model, pageObjectNumber) {
-	const snapshot = model.snapshot;
-	const geom = model.geom[pageObjectNumber];
-	if (!snapshot || !geom) return [];
-	const items = [];
-	for (const field of snapshot.fields) for (const widget of field.widgets) {
-		if (widget.pageObjectNumber !== pageObjectNumber) continue;
-		const box = geom[widget.annotObjectNumber];
-		if (!box) continue;
-		const item = projectWidget(model, field, widget.annotObjectNumber, box);
-		if (item) items.push(item);
-	}
-	return items;
-}
-/**
-* Project a SINGLE widget by its annotation object number — the join the
-* annotation-plane render layer uses (it owns a live box already, so the
-* model's cached geometry is used only when it happens to be loaded; the
-* item's semantics never depend on it). Null while the snapshot hasn't
-* landed, or for families with no fill control.
-*/
-function fillItemForWidget(model, annotObjectNumber) {
-	const field = fieldForWidget(model, annotObjectNumber);
-	if (!field) return null;
-	const widget = field.widgets.find((w) => w.annotObjectNumber === annotObjectNumber);
-	if (!widget) return null;
-	const box = model.geom[widget.pageObjectNumber]?.[annotObjectNumber];
-	return projectWidget(model, field, annotObjectNumber, box);
+	} };
 }
 //#endregion
-//#region src/mutationQueue.ts
-/** The core serial queue under its historical form-plugin name. */
-const createSerialMutationQueue = _embedpdf_core.createSerialQueue;
-//#endregion
-//#region src/capability.ts
-/** PDF user-space rect (y-up) → content-space box (y-down, crop-relative). */
-const toBox = (rect, crop) => ({
-	x: rect.left - crop.left,
-	y: crop.top - rect.top,
-	width: rect.right - rect.left,
-	height: rect.top - rect.bottom
-});
-const sameAnnotationRef = (left, right) => {
-	if (left.kind !== right.kind || left.pageObjectNumber !== right.pageObjectNumber) return false;
-	if (left.kind === "objectNumber" && right.kind === "objectNumber") return left.annotObjectNumber === right.annotObjectNumber;
-	if (left.kind === "nm" && right.kind === "nm") return left.nm === right.nm;
-	return left.kind === "index" && right.kind === "index" && left.index === right.index && left.revision === right.revision;
-};
+//#region src/write/script-effects.ts
 /**
-* The form shell. Pure `update` runs here; the resulting model is dispatched
-* to the store; engine calls happen around it. Every read the frameworks do
-* goes through memoized projections keyed on `model.seq`.
+* The actions plugin's seams into the form plugin: the form-effects commit
+* sink (script `setValue`, `setDisplay` and reset effects are written through
+* the plugin that owns the fields, as one fill with the calculations they
+* cause) and the submit dataset resolver.
 */
-function createFormCapability(ctx, options = {}) {
-	const model = () => ctx.getState().model;
-	const apply = (msg) => {
-		ctx.dispatch({
-			type: "SET_MODEL",
-			model: update(model(), msg)
-		});
-	};
-	const refKeyOf = (key) => {
-		if (key.startsWith("obj:")) return {
-			kind: "objectNumber",
-			fieldObjectNumber: Number(key.slice(4))
-		};
-		return {
-			kind: "fqn",
-			name: key.slice(4)
-		};
-	};
-	const enqueueMutation = createSerialMutationQueue();
-	const actionsHost = ctx.tryGet(_embedpdf_plugin_actions_contract_host.ActionsToken);
-	const realm = actionsHost?.scriptRealm ?? null;
-	const scripting = realm && ctx.doc ? require_scripting.createFormScriptingController({
-		doc: ctx.doc,
-		document: () => ctx.document(),
-		transaction: realm.transaction.bind(realm),
-		budget: realm.budget
-	}) : null;
-	if (scripting) ctx.cleanup(() => scripting.dispose());
-	/** Every script surface (UI effects, diagnostics, errors) flows through
-	*  the actions plugin's ONE port — origin/phase attached (D9). */
-	const surfaceViaActions = (result, origin) => {
-		actionsHost?.surfaceScriptCommit(result, {
-			origin,
-			realm: "document"
-		});
-	};
-	const can = (cap) => ctx.doc?.security.allows(cap) ?? false;
-	let refreshPromise = null;
-	const refresh = async (force = false) => {
-		const doc = ctx.doc;
-		if (!doc) return;
-		if (!can("doc.forms.read")) return;
-		if (refreshPromise) {
-			await refreshPromise;
-			if (!force) return;
-		}
-		refreshPromise = doc.forms.list().then((snapshot) => apply({
-			t: "snapshot",
-			snapshot
-		})).catch((err) => {
-			console.warn("[form] form snapshot failed to load", err);
-		}).finally(() => {
-			refreshPromise = null;
-		});
-		return refreshPromise;
-	};
-	const geomLoading = /* @__PURE__ */ new Set();
-	const ensureGeom = (pon) => {
-		const doc = ctx.doc;
-		if (!doc || geomLoading.has(pon) || model().geom[pon]) return;
-		const crop = ctx.document()?.pages.find((p) => p.pageObjectNumber === pon)?.boxes.crop;
-		if (!crop) return;
-		geomLoading.add(pon);
-		doc.page(pon).annotations.list().then(({ annotations }) => {
-			const boxes = {};
-			for (const dto of annotations) {
-				if (dto.subtype !== "widget") continue;
-				const objectNumber = dto.ref.kind === "objectNumber" ? dto.ref.annotObjectNumber : 0;
-				if (objectNumber > 0) boxes[objectNumber] = toBox(dto.rect, crop);
-			}
-			apply({
-				t: "pageGeom",
-				pageObjectNumber: pon,
-				boxes
-			});
-		}).finally(() => {
-			geomLoading.delete(pon);
-		});
-	};
-	const widgetAt$1 = (pon, point) => {
-		const m = model();
-		ensureGeom(pon);
-		if (m.geom[pon]) return widgetAt(m, pon, point);
-		if (!annotationHost) return null;
-		let best = null;
-		for (const item of annotationHost.pageItems(pon)) {
-			if (!item.subtype.startsWith("widget") || item.ref?.kind !== "objectNumber") continue;
-			const box = item.box;
-			if (!(point.x >= box.x && point.x <= box.x + box.width && point.y >= box.y && point.y <= box.y + box.height)) continue;
-			const field = fieldForWidget(m, item.ref.annotObjectNumber);
-			if (!field) continue;
-			if (!best || box.width * box.height < best.box.width * best.box.height) best = {
-				annotObjectNumber: item.ref.annotObjectNumber,
-				field,
-				box
-			};
-		}
-		return best;
-	};
-	const fuseFill = (item, fillable) => item === null || fillable || item.disabled ? item : {
-		...item,
-		disabled: true
-	};
-	const fillCache = /* @__PURE__ */ new Map();
-	const fillItems$1 = (pon) => {
-		const m = model();
-		const fillable = can("doc.forms.fill");
-		const hit = fillCache.get(pon);
-		if (hit && hit.seq === m.seq && hit.fillable === fillable) return hit.items;
-		const items = fillItems(m, pon).map((item) => fuseFill(item, fillable));
-		fillCache.set(pon, {
-			seq: m.seq,
-			fillable,
-			items
-		});
-		return items;
-	};
-	const fillItemCache = /* @__PURE__ */ new Map();
-	const fillItem = (annotObjectNumber) => {
-		const m = model();
-		const fillable = can("doc.forms.fill");
-		const hit = fillItemCache.get(annotObjectNumber);
-		if (hit && hit.seq === m.seq && hit.fillable === fillable) return hit.item;
-		const item = fuseFill(fillItemForWidget(m, annotObjectNumber), fillable);
-		fillItemCache.set(annotObjectNumber, {
-			seq: m.seq,
-			fillable,
-			item
-		});
-		return item;
-	};
-	const commitValueNow = async (ref, value) => {
-		const doc = ctx.doc;
-		if (!doc) throw new Error("no document");
-		if (scripting) {
-			const result = await scripting.commit(ref, value);
-			surfaceViaActions(result, "user");
-			if (result.effectsResult !== null) await refresh(true);
-			return result;
-		}
-		const result = await doc.forms.setValue(ref, value);
-		await refresh(true);
-		return {
-			status: result.changedWidgets.length > 0 ? "applied" : "unchanged",
-			scripted: false,
-			effectsResult: null,
-			uiEffects: [],
-			diagnostics: []
-		};
-	};
-	const write = (key, value) => {
-		if (!can("doc.forms.fill")) return Promise.reject(new _embedpdf_engine_core_runtime.PermissionDenied("doc.forms.fill", "form.fill"));
-		return enqueueMutation(async () => {
-			if (!ctx.doc) return;
-			apply({
-				t: "writeStart",
-				key
-			});
-			try {
-				const result = await commitValueNow(refKeyOf(key), value);
-				if (result.status === "rejected" || result.status === "failed") apply({
-					t: "writeFailed",
-					key
-				});
-				else if (result.effectsResult === null && result.scripted) apply({
-					t: "writeFailed",
-					key
-				});
-			} catch (err) {
-				apply({
-					t: "writeFailed",
-					key
-				});
-				throw err;
-			}
-		});
-	};
-	const annotationHost = ctx.tryGet(_embedpdf_plugin_annotation_contract_host.AnnotationToken);
-	const annotationActivation = async (ref) => {
-		const doc = ctx.doc;
-		if (!doc) return null;
-		const loaded = annotationHost?.get(ref);
-		if (loaded?.subtype === "widget") return loaded.actions?.activate ?? null;
-		const { annotations } = await doc.page(ref.pageObjectNumber).annotations.list();
-		const annotation = annotations.find((candidate) => sameAnnotationRef(candidate.ref, ref));
-		return annotation?.subtype === "widget" ? annotation.actions?.activate ?? null : null;
-	};
-	const activateWidgetNow = async (key, annotationRef) => {
-		if (!ctx.doc) throw new Error("no document");
-		if (!scripting) return {
-			status: "unchanged",
-			scripted: false,
-			effectsResult: null,
-			uiEffects: [],
-			diagnostics: []
-		};
-		const action = await annotationActivation(annotationRef);
-		if (!action) return {
-			status: "unchanged",
-			scripted: true,
-			effectsResult: null,
-			uiEffects: [],
-			diagnostics: []
-		};
-		const result = await scripting.activate(refKeyOf(key), action);
-		surfaceViaActions(result, "user");
-		if (result.effectsResult !== null) await refresh(true);
-		return result;
-	};
-	const NOT_SCRIPTED = {
-		status: "unchanged",
-		scripted: false,
-		effectsResult: null,
-		uiEffects: [],
-		diagnostics: []
-	};
-	/**
-	* The shared reset core: one effects batch → refresh → V/C/F
-	* recalculation when the transaction port is present. Ridden by BOTH
-	* doors — the /ResetForm executor and the public `reset(key)` — so the
-	* two can never diverge again (the "reset() asymmetry" fix). `origin` is
-	* PRESERVED through recalculation surfacing: a lifecycle/hover ResetForm
-	* can no longer launder its alerts into user origin.
-	*/
-	const applyResetBatch = async (refs, origin) => {
-		const doc = ctx.doc;
-		if (!doc) throw new Error("no document");
-		if (!doc.forms.applyEffects) {
-			const result = {
-				...NOT_SCRIPTED,
-				diagnostics: [{
-					code: "unsupported-api",
-					message: "this engine has no form-effects batch door"
-				}]
-			};
-			surfaceViaActions(result, origin);
-			return result;
-		}
-		if (refs.length === 0) return NOT_SCRIPTED;
-		const effectsResult = await doc.forms.applyEffects([{
-			kind: "reset",
-			refs
-		}]);
-		const resetFailed = effectsResult.results.some((entry) => entry.status === "failed" || entry.status === "rejected");
-		await refresh(true);
-		if (resetFailed) return {
-			status: "failed",
-			scripted: false,
-			effectsResult,
-			uiEffects: [],
-			diagnostics: []
-		};
-		let recalc = null;
-		if (scripting) {
-			recalc = await scripting.recalculate();
-			surfaceViaActions(recalc, origin);
-			if (recalc.effectsResult !== null) await refresh(true);
-		}
-		return {
-			status: "applied",
-			scripted: recalc !== null,
-			effectsResult,
-			uiEffects: recalc?.uiEffects ?? [],
-			diagnostics: recalc?.diagnostics ?? [],
-			...recalc?.error ? { error: recalc.error } : {}
-		};
-	};
-	const resetFormAction = (targets, exclude, origin = "user") => enqueueMutation(async () => {
-		const doc = ctx.doc;
-		if (!doc) throw new Error("no document");
-		const { selected } = resolveFieldSelection((await doc.forms.list()).fields, targets, exclude);
-		const resettable = selected.filter((f) => f.family !== "pushbutton" && f.family !== "signature");
-		return applyResetBatch(resettable.map((f) => f.ref), origin);
-	});
+/** The fields a script's effects write to. */
+const refsOf = (effects) => effects.flatMap((effect) => effect.kind === "reset" ? effect.refs : [effect.ref]);
+function createScriptEffects(ctx, { fields, rights, enqueue }, { fillSoon }) {
 	/**
-	* The submit dataset resolver (Phase 4, D7): a FRESH engine read — never
-	* the cached model, so no staleness class exists — then the pure ISO
-	* builder. Selection/veto/value semantics live in `field-selection.ts`;
-	* this door only supplies the live fields and assembles the request.
+	* The submit dataset: the fields as the user sees them once every fill on its way is
+	* answered, then the pure ISO builder. Selection, veto and value semantics live in
+	* `field-selection.ts`; this only supplies the fields and assembles the request.
 	*/
-	const resolveSubmitDataset = async (intent, actionCtx, diagnose) => {
-		const doc = ctx.doc;
-		if (!doc) throw new Error("no document");
-		const snapshot = await doc.forms.list();
+	const resolveSubmitDataset = async (intent, actionContext, diagnose) => {
+		await enqueue.idle();
+		await ctx.changes.whenSettled();
+		if (!fields.view().snapshot) await fields.settled();
 		return {
 			url: intent.url,
-			method: intent.method,
-			format: intent.format,
-			flagsRaw: intent.flagsRaw,
-			...intent.charSet === void 0 ? {} : { charSet: intent.charSet },
-			entries: buildSubmitEntries(snapshot.fields, intent, diagnose),
-			origin: actionCtx.origin,
-			event: actionCtx.event
-		};
-	};
-	const widgetSource = (key, annotationRef) => ({
-		kind: "widget",
-		field: refKeyOf(key),
-		annotation: annotationRef,
-		pon: annotationRef.pageObjectNumber
-	});
-	/** One shared hover pump (Exit→Enter as one ordered pair; intermediates
-	*  skipped), created on first use against the resolved actions capability. */
-	let widgetPump = null;
-	const widgetHoverPump = (actions) => {
-		widgetPump ?? (widgetPump = (0, _embedpdf_plugin_actions_contract.createHoverPump)(actions.dispatch));
-		return widgetPump;
-	};
-	const widgetHoverFlags = (annotationRef) => {
-		const loaded = annotationHost?.get(annotationRef);
-		if (loaded?.subtype !== "widget") return null;
-		return {
-			enter: Boolean(loaded.actions?.cursorEnter?.root),
-			exit: Boolean(loaded.actions?.cursorExit?.root)
-		};
-	};
-	const nudgeAnnotations = (pons) => {
-		if (!annotationHost) return;
-		for (const pon of new Set(pons)) annotationHost.reloadPage(pon);
-	};
-	/** Content-space box → PDF rect (inverse of `toBox`). */
-	const toPdfRect = (box, crop) => ({
-		left: box.x + crop.left,
-		top: crop.top - box.y,
-		right: box.x + crop.left + box.width,
-		bottom: crop.top - box.y - box.height
-	});
-	/** The page's content box (`{0,0,w,h}`), for page-bound placement math. */
-	const pageBox = (pon) => {
-		const crop = ctx.document()?.pages.find((p) => p.pageObjectNumber === pon)?.boxes.crop;
-		return crop ? {
-			x: 0,
-			y: 0,
-			width: crop.right - crop.left,
-			height: crop.top - crop.bottom
-		} : null;
-	};
-	/** Deterministic, collision-free auto-name: `text_1`, `text_2`, … counted
-	*  against the CURRENT snapshot (rename in the field panel). */
-	const autoName = (family) => {
-		const names = new Set((model().snapshot?.fields ?? []).map((f) => f.name));
-		let n = 1;
-		while (names.has(`${family}_${n}`)) n++;
-		return `${family}_${n}`;
-	};
-	const placeFieldNow = async (input) => {
-		const doc = ctx.doc;
-		const pon = input.pageObjectNumber;
-		const crop = ctx.document()?.pages.find((p) => p.pageObjectNumber === pon)?.boxes.crop;
-		if (!doc || !crop) throw new Error("[form] placeField: document/page not ready");
-		const page = pageBox(pon);
-		const x = Math.max(page.x, Math.min(input.box.x, page.width));
-		const y = Math.max(page.y, Math.min(input.box.y, page.height));
-		const box = {
-			x,
-			y,
-			width: Math.max(0, Math.min(input.box.x + input.box.width, page.width) - x),
-			height: Math.max(0, Math.min(input.box.y + input.box.height, page.height) - y)
-		};
-		if (box.width < 1 || box.height < 1) throw new Error("[form] placeField: degenerate box (size the box before placing)");
-		const { family, appearance } = input;
-		const name = autoName(family);
-		const placement = {
-			pageObjectNumber: pon,
-			rect: toPdfRect(box, crop),
-			...appearance ? { appearance } : {}
-		};
-		const draft = family === "radio" ? {
-			family,
-			name,
-			widgets: [{
-				...placement,
-				onState: "option1"
-			}]
-		} : family === "combobox" || family === "listbox" ? {
-			family,
-			name,
-			widget: placement,
-			options: [{
-				label: "Option 1",
-				value: "Option 1"
-			}, {
-				label: "Option 2",
-				value: "Option 2"
-			}]
-		} : {
-			family,
-			name,
-			widget: placement
-		};
-		const result = await doc.forms.createField(draft);
-		await refresh(true);
-		apply({
-			t: "clearGeom",
-			pageObjectNumber: pon
-		});
-		if (annotationHost) await annotationHost.reloadPage(pon);
-		const widget = result.field.widgets.find((w) => w.pageObjectNumber === pon) ?? null;
-		return {
-			field: result.field,
-			widget
+			method: intent.method,
+			format: intent.format,
+			flagsRaw: intent.flagsRaw,
+			...intent.charSet === void 0 ? {} : { charSet: intent.charSet },
+			entries: buildSubmitEntries(fields.view().snapshot?.fields ?? [], intent, diagnose),
+			origin: actionContext.origin,
+			event: actionContext.event
 		};
 	};
-	const updateFieldNow = async (key, patch) => {
-		const doc = ctx.doc;
-		if (!doc) return;
-		await doc.forms.updateField(refKeyOf(key), patch);
-		await refresh(true);
-	};
-	const deleteFieldNow = async (key) => {
-		const doc = ctx.doc;
-		if (!doc) return;
-		const pons = fieldByKey(model(), key)?.widgets.map((w) => w.pageObjectNumber).filter((p) => p > 0) ?? [];
-		await doc.forms.deleteField(refKeyOf(key));
-		await refresh(true);
-		for (const pon of new Set(pons)) apply({
-			t: "clearGeom",
-			pageObjectNumber: pon
-		});
-		nudgeAnnotations(pons);
-	};
-	const detachWidgetNow = async (key, annotObjectNumber) => {
-		const doc = ctx.doc;
-		if (!doc) return;
-		const widget = fieldByKey(model(), key)?.widgets.find((w) => w.annotObjectNumber === annotObjectNumber);
-		await doc.forms.detachWidget(refKeyOf(key), {
-			annotObjectNumber,
-			pageObjectNumber: widget?.pageObjectNumber ?? 0
-		});
-		await refresh(true);
-		if (widget && widget.pageObjectNumber > 0) {
-			apply({
-				t: "clearGeom",
-				pageObjectNumber: widget.pageObjectNumber
-			});
-			nudgeAnnotations([widget.pageObjectNumber]);
-		}
-	};
-	refresh();
-	return {
-		snapshot: () => model().snapshot,
-		refresh,
-		fillItems: fillItems$1,
-		fillItem,
-		ensureGeom,
-		field: (key) => fieldByKey(model(), key),
-		fieldForWidget: (annotObjectNumber) => fieldForWidget(model(), annotObjectNumber),
-		widgetAt: widgetAt$1,
-		setText: (key, value) => write(key, {
-			type: "text",
-			value
-		}),
-		toggle: (key, onState) => write(key, {
-			type: "toggle",
-			state: onState
-		}),
-		choose: (key, values) => write(key, {
-			type: "choice",
-			values
-		}),
-		reset: (key) => {
-			if (!can("doc.forms.fill")) return Promise.reject(new _embedpdf_engine_core_runtime.PermissionDenied("doc.forms.fill", "form.reset"));
-			return enqueueMutation(async () => {
-				const doc = ctx.doc;
-				if (!doc) return;
-				apply({
-					t: "writeStart",
-					key
-				});
-				try {
-					if (doc.forms.applyEffects) {
-						const result = await applyResetBatch([refKeyOf(key)], "user");
-						if (result.status === "failed") throw new Error(result.effectsResult?.results.find((entry) => entry.status === "failed" || entry.status === "rejected")?.error?.message ?? "reset failed");
-						const field = fieldByKey(model(), key);
-						if (field) apply({
-							t: "writeDone",
-							key,
-							field
-						});
-						else apply({
-							t: "writeFailed",
-							key
-						});
-					} else {
-						const result = await doc.forms.reset(refKeyOf(key));
-						apply({
-							t: "writeDone",
-							key,
-							field: result.field
-						});
-					}
-				} catch (err) {
-					apply({
-						t: "writeFailed",
-						key
-					});
-					throw err;
-				}
-			});
-		},
-		commitValue: (ref, value) => enqueueMutation(() => commitValueNow(ref, value)),
-		activateWidget: async (key, annotationRef) => {
-			const actions = ctx.tryGet(_embedpdf_plugin_actions_contract.ActionsToken);
-			if (actions) {
-				const result = await actions.dispatch({
-					scope: "activate",
-					ref: annotationRef,
-					pon: annotationRef.pageObjectNumber,
-					source: widgetSource(key, annotationRef)
-				});
-				if (!(result.status === "inert" && result.steps.length === 0 && result.diagnostics.length === 0)) return {
-					kind: "dispatched",
-					result
-				};
-			}
-			return {
-				kind: "form",
-				result: await enqueueMutation(() => activateWidgetNow(key, annotationRef))
-			};
-		},
-		notifyWidgetEvent: (key, annotationRef, event) => {
-			const actions = ctx.tryGet(_embedpdf_plugin_actions_contract.ActionsToken);
-			if (!actions) return;
-			const source = widgetSource(key, annotationRef);
-			if (event === "cursorEnter" || event === "cursorExit") {
-				if (event === "cursorExit") {
-					widgetHoverPump(actions).hover(null);
-					return;
-				}
-				const flags = widgetHoverFlags(annotationRef);
-				if (flags && !flags.enter && !flags.exit) return;
-				widgetHoverPump(actions).hover({
-					ref: annotationRef,
-					pon: annotationRef.pageObjectNumber,
-					source,
-					...flags ? { events: flags } : {}
-				});
-				return;
-			}
-			actions.dispatch({
-				scope: "annotation",
-				event,
-				ref: annotationRef,
-				pon: annotationRef.pageObjectNumber,
-				source
-			});
-		},
-		resetFormAction,
+	return { api: {
 		resolveSubmitDataset,
 		commitScriptFormEffects: async (effects) => {
-			const doc = ctx.doc;
-			if (!doc?.forms.applyEffects) return {
-				results: effects.map((_, index) => ({
-					index,
-					status: "failed",
-					fields: [],
-					changedWidgets: [],
-					error: {
-						code: "NotSupported",
-						message: "no form-effects batch door"
-					}
-				})),
-				changedWidgets: [],
-				meta: null
-			};
-			let result;
 			try {
-				result = await doc.forms.applyEffects(effects);
+				for (const ref of refsOf(effects)) {
+					const field = fieldByRef(fields.view(), ref);
+					if (field) rights.assertMayFill(field, "form.fill");
+				}
+				const recalculates = effects.some((effect) => effect.kind === "setValue" || effect.kind === "reset");
+				fillSoon({
+					ops: (0, _embedpdf_engine_core_runtime.formEffectOps)(effects),
+					scripts: recalculates ? { kind: "recalculate" } : null,
+					origin: "user"
+				});
+				return { status: "applied" };
 			} catch (error) {
-				const message = error instanceof Error ? error.message : String(error);
 				return {
-					results: effects.map((_, index) => ({
-						index,
-						status: "failed",
-						fields: [],
-						changedWidgets: [],
-						error: {
-							code: "Refused",
-							message
-						}
-					})),
-					changedWidgets: [],
-					meta: null
+					status: "failed",
+					error: (0, _embedpdf_engine_core_runtime.serializeError)(error).message
 				};
 			}
-			await refresh(true);
-			if (annotationHost) {
-				const pons = new Set(result.changedWidgets.map((widget) => widget.pageObjectNumber).filter((pon) => pon > 0));
-				for (const pon of pons) await annotationHost.reloadPage(pon);
-			}
-			return result;
-		},
-		setValue: (ref, value) => enqueueMutation(async () => {
-			const doc = ctx.doc;
-			if (!doc) throw new Error("no document");
-			const result = await doc.forms.setValue(ref, value);
-			await refresh(true);
-			return result;
-		}),
-		exportData: async (format = "xfdf") => {
-			const doc = ctx.doc;
-			if (!doc) throw new Error("no document");
-			return doc.forms.exportData(format);
-		},
-		importData: (data, format) => enqueueMutation(async () => {
-			const doc = ctx.doc;
-			if (!doc) throw new Error("no document");
-			const result = await doc.forms.importData(data, format);
-			apply({
-				t: "snapshot",
-				snapshot: result.snapshot
-			});
-			return result;
-		}),
-		repair: (repairOptions) => enqueueMutation(async () => {
-			const doc = ctx.doc;
-			if (!doc) throw new Error("no document");
-			const result = await doc.forms.repair(repairOptions);
-			await refresh(true);
-			return result;
-		}),
-		placeField: (input) => enqueueMutation(() => placeFieldNow(input)),
-		pageBox,
-		updateField: (key, patch) => enqueueMutation(() => updateFieldNow(key, patch)),
-		deleteField: (key) => enqueueMutation(() => deleteFieldNow(key)),
-		detachWidget: (key, annotObjectNumber) => enqueueMutation(() => detachWidgetNow(key, annotObjectNumber)),
-		canRead: () => can("doc.forms.read"),
-		canFill: () => can("doc.forms.fill"),
-		canDesign: () => can("doc.forms.modify")
-	};
+		}
+	} };
 }
 //#endregion
-//#region src/effects.ts
-const STRUCTURAL = /* @__PURE__ */ new Set([
-	"form.fieldCreated",
-	"form.fieldUpdated",
-	"form.fieldDeleted",
-	"form.widgetAttached",
-	"form.widgetDetached",
-	"form.repaired"
-]);
-function registerFormEffects(ctx) {
-	const doc = ctx.doc;
-	if (!doc) return;
-	let refreshing = false;
-	const refresh = async () => {
-		if (refreshing) return;
-		refreshing = true;
-		try {
-			const snapshot = await doc.forms.list();
-			ctx.dispatch({
-				type: "SET_MODEL",
-				model: update(ctx.getState().model, {
-					t: "snapshot",
-					snapshot
-				})
-			});
-		} finally {
-			refreshing = false;
-		}
+//#region src/write/typing.ts
+function createTyping(ctx, { keyOf }, setText) {
+	/** The text typed in each field and not written yet, by field key. */
+	const drafts = /* @__PURE__ */ new Map();
+	/** Write the field's draft, if it has one; `null` when there is nothing to write. */
+	const commitDraftText = async (field) => {
+		const key = keyOf(field);
+		const draft = drafts.get(key);
+		if (!draft) return null;
+		drafts.delete(key);
+		return setText(draft.field, draft.text);
 	};
-	const unsubscribe = doc.events.subscribe((event) => {
-		if (event.type === "stream.desynced") {
-			refresh();
-			return;
-		}
-		if (event.type === "document.versioned" || event.type === "signature.completed") {
-			refresh();
-			return;
-		}
-		if (!event.type.startsWith("form.") || !("origin" in event)) return;
-		const structural = STRUCTURAL.has(event.type);
-		if (event.origin.kind !== "remote" && !structural) return;
-		if (structural) ctx.dispatch({
-			type: "SET_MODEL",
-			model: update(ctx.getState().model, { t: "clearGeom" })
-		});
-		refresh();
+	ctx.onSettle(async () => {
+		await Promise.all([...drafts.values()].map((draft) => commitDraftText(draft.field)));
 	});
-	ctx.cleanup(unsubscribe);
-}
-//#endregion
-//#region src/tools.ts
-/** Palette tools keep widgets editable right after placement. */
-const PLACE_TAGS = ["form-place", "annotation-edit"];
-const FIELD_CHROME = {
-	interiorColor: "#ffffff",
-	color: "#6b7280",
-	strokeWidth: 1
-};
-const FORM_TOOLS = [
-	{
-		id: "form-text",
-		family: "text",
-		visualKind: "widget-text",
-		clickCreate: {
-			width: 160,
-			height: 24
-		},
-		defaults: {
-			...FIELD_CHROME,
-			fontSize: 12
-		},
-		cursor: "crosshair"
-	},
-	{
-		id: "form-checkbox",
-		family: "checkbox",
-		visualKind: "widget-toggle",
-		clickCreate: {
-			width: 18,
-			height: 18
-		},
-		defaults: FIELD_CHROME,
-		cursor: "crosshair"
-	},
-	{
-		id: "form-radio",
-		family: "radio",
-		visualKind: "widget-toggle",
-		clickCreate: {
-			width: 18,
-			height: 18
-		},
-		defaults: FIELD_CHROME,
-		cursor: "crosshair"
-	},
-	{
-		id: "form-combobox",
-		family: "combobox",
-		visualKind: "widget-choice",
-		clickCreate: {
-			width: 140,
-			height: 24
-		},
-		defaults: {
-			...FIELD_CHROME,
-			fontSize: 12
-		},
-		cursor: "crosshair"
-	},
-	{
-		id: "form-listbox",
-		family: "listbox",
-		visualKind: "widget-choice",
-		clickCreate: {
-			width: 140,
-			height: 72
-		},
-		defaults: {
-			...FIELD_CHROME,
-			fontSize: 12
-		},
-		cursor: "crosshair"
-	},
-	{
-		id: "form-signature",
-		family: "signature",
-		visualKind: "widget-box",
-		clickCreate: {
-			width: 160,
-			height: 48
+	return { api: {
+		draftText: (field, text) => {
+			drafts.set(keyOf(field), {
+				field,
+				text
+			});
 		},
-		defaults: FIELD_CHROME,
-		cursor: "crosshair"
-	}
-];
-const FORM_TOOL_BY_ID = new Map(FORM_TOOLS.map((t) => [t.id, t]));
+		commitDraftText,
+		discardDraftText: (field) => {
+			drafts.delete(keyOf(field));
+		}
+	} };
+}
 //#endregion
-//#region src/handler.ts
-const rectFrom = (a, b) => ({
-	x: Math.min(a.x, b.x),
-	y: Math.min(a.y, b.y),
-	width: Math.abs(b.x - a.x),
-	height: Math.abs(b.y - a.y)
-});
+//#region src/write/values.ts
 /**
-* Draw-to-place: drag a box (live placement preview through the annotation
-* plane's ghost pipeline) or just click (the tool's `clickCreate` policy,
-* resolved by the SAME `resolveClickPlacement` the annotation core uses) —
-* the commit creates field + widget through `doc.forms.placeField`, styled
-* from the tool's live defaults. The tool stays active for repeat placement
-* (v2 rubber-stamp feel) and the fresh widget is auto-selected.
-*
-* Gesture rules match the annotation handlers: page-anchored via the sample
-* projection (the box keeps sizing along the edge when the cursor overshoots
-* or crosses a gap), the UP sample is the final point, and a CLICK means
-* width AND height under the shared threshold — a thin 100×2 drag is a drag.
+* Value writes, each one fill (write/fill.ts): one field through the form's scripts (when the
+* `validation` setting runs them), and the batch verbs, whose plain values go as one change
+* with one recalculation, as a script's `field.value` assignments do in Acrobat.
 */
-function createPlaceHandler(form, interaction, annotation) {
-	let origin = null;
-	return {
-		id: "form-place",
-		priority: 95,
-		enabledFor: (t) => t.enables.has("form-place"),
-		onDown: (s) => {
-			if (!s.page || !FORM_TOOL_BY_ID.has(interaction.activeToolId())) return false;
-			if (!form.canDesign()) return false;
-			origin = {
-				pon: s.page.pon,
-				start: s.page.point,
-				last: s.page.point
+/** A batch that stops when its caller cancels it. */
+function throwIfCancelled(options) {
+	if (options?.signal?.aborted) throw new _embedpdf_core.PluginError("operation-cancelled", "form", "operation cancelled", { cause: options.signal.reason });
+}
+const setValueOp = (field, value) => ({
+	type: "forms.setValue",
+	field,
+	value
+});
+function createValueWrites(_ctx, services, { fill }) {
+	const { validationRejected } = services.events;
+	const { fields, rights } = services;
+	/** One field's value through its scripts: shown at once, written as one change. */
+	const commit = async (ref, value, operation, options) => {
+		const known = fieldByRef(fields.view(), ref);
+		if (known) rights.assertMayFill(known, operation);
+		const { result } = await fill({
+			ops: [setValueOp(ref, value)],
+			scripts: {
+				kind: "commit",
+				field: ref,
+				value
+			},
+			origin: "user"
+		}, options);
+		if (result.status === "failed") throw failedFill(result);
+		const field = fieldByRef(fields.get(), ref);
+		if (!field) throw new _embedpdf_core.PluginError("not-found", "form", "no form field has this ref");
+		if (result.status === "rejected") {
+			validationRejected.emit({
+				field,
+				issues: result.diagnostics
+			});
+			return {
+				field,
+				status: "rejected"
 			};
-			return true;
-		},
-		onMove: (s) => {
-			if (!origin) return;
-			const point = (0, _embedpdf_plugin_interaction_contract.samplePointOn)(s, origin.pon);
-			if (!point) return;
-			origin.last = point;
-			const box = rectFrom(origin.start, point);
-			if (annotation) if (Math.max(box.width, box.height) >= _embedpdf_plugin_annotation_authoring.MIN_DRAG) annotation.setPlacementPreview(interaction.activeToolId(), origin.pon, box);
-			else annotation.clearPlacementPreview();
-		},
-		onUp: (s) => {
-			if (!origin) return;
-			const o = origin;
-			origin = null;
-			annotation?.clearPlacementPreview();
-			const toolId = interaction.activeToolId();
-			const tool = FORM_TOOL_BY_ID.get(toolId);
-			if (!tool) return;
-			const end = (0, _embedpdf_plugin_interaction_contract.samplePointOn)(s, o.pon) ?? o.last;
-			const dragged = rectFrom(o.start, end);
-			const isClick = dragged.width < _embedpdf_plugin_annotation_authoring.MIN_DRAG && dragged.height < _embedpdf_plugin_annotation_authoring.MIN_DRAG;
-			const pageBox = form.pageBox(o.pon);
-			const box = isClick ? boxOfClick(o.start, tool.clickCreate, pageBox) : dragged;
-			form.placeField({
-				family: tool.family,
-				pageObjectNumber: o.pon,
-				box,
-				appearance: (0, _embedpdf_plugin_annotation_authoring.widgetAppearanceFromProps)(annotation ? annotation.currentDefaults(toolId) : tool.defaults)
-			}).then((placed) => {
-				if (!annotation || interaction.activeToolId() !== toolId) return;
-				const widget = placed.widget;
-				if (!widget || widget.annotObjectNumber <= 0) return;
-				annotation.select({
-					kind: "objectNumber",
-					annotObjectNumber: widget.annotObjectNumber,
-					pageObjectNumber: o.pon
+		}
+		return {
+			field,
+			status: result.status
+		};
+	};
+	/**
+	* Plain values for several fields, as one change with one recalculation. A value its field
+	* can't take, or a field the session may not fill in, fails on its own; the rest go together,
+	* and fail together when the engine refuses them.
+	*/
+	const fillPlain = async (entries, options) => {
+		if (!fields.view().snapshot) await fields.settled();
+		const index = fields.view();
+		const accepted = [];
+		const failed = [];
+		for (const entry of entries) try {
+			const field = fieldByRef(index, entry.ref);
+			if (!field) throw new _embedpdf_core.PluginError("not-found", "form", "no form field has this ref");
+			rights.assertMayFill(field, "form.setValues");
+			(0, _embedpdf_engine_core_runtime.fieldValueWriteOf)(field, entry.value);
+			accepted.push({
+				ref: field.ref,
+				value: entry.value
+			});
+		} catch (error) {
+			failed.push({
+				ref: entry.ref,
+				error: (0, _embedpdf_core.toPluginErrorInfo)((0, _embedpdf_core.toPluginError)("form", error))
+			});
+		}
+		if (accepted.length === 0) return {
+			applied: [],
+			failed
+		};
+		throwIfCancelled(options);
+		try {
+			const { result } = await fill({
+				ops: accepted.map((entry) => setValueOp(entry.ref, entry.value)),
+				scripts: { kind: "recalculate" },
+				origin: "user"
+			}, options);
+			if (result.status === "failed") throw failedFill(result);
+			return {
+				applied: accepted.map((entry) => entry.ref),
+				failed
+			};
+		} catch (error) {
+			const info = (0, _embedpdf_core.toPluginErrorInfo)((0, _embedpdf_core.toPluginError)("form", error));
+			return {
+				applied: [],
+				failed: [...failed, ...accepted.map(({ ref }) => ({
+					ref,
+					error: info
+				}))]
+			};
+		}
+	};
+	const setValues = async (entries, options) => {
+		throwIfCancelled(options);
+		const { applied, failed } = await fillPlain(entries, options);
+		return {
+			applied,
+			skipped: [],
+			failed
+		};
+	};
+	const importValues = async (values, options) => {
+		throwIfCancelled(options);
+		if (!fields.view().snapshot) await fields.settled();
+		const index = fields.view();
+		const skipped = [];
+		const entries = [];
+		const names = /* @__PURE__ */ new Map();
+		for (const [name, plain] of Object.entries(values)) {
+			const field = fieldByRef(index, {
+				kind: "fqn",
+				name
+			});
+			if (!field) {
+				skipped.push({
+					ref: name,
+					reason: "the form has no field with this name"
+				});
+				continue;
+			}
+			if (!rights.mayFill(field)) {
+				skipped.push({
+					ref: name,
+					reason: "you may not fill in this field"
+				});
+				continue;
+			}
+			const value = writeOfPlainValue(field, plain);
+			if (!value) {
+				skipped.push({
+					ref: name,
+					reason: `a ${field.family} field can't take this value`
 				});
-			}).catch((err) => {
-				globalThis.console?.error("[form] placeField failed:", err);
+				continue;
+			}
+			entries.push({
+				ref: field.ref,
+				value
 			});
+			names.set(JSON.stringify(field.ref), name);
 		}
+		const { applied, failed } = await fillPlain(entries, options);
+		return {
+			applied,
+			skipped,
+			failed: failed.map(({ ref, error }) => ({
+				ref: names.get(JSON.stringify(ref)) ?? "",
+				error
+			}))
+		};
 	};
-}
-/** The click-create box through the SHARED placement layer (fields are boxes;
-*  the policy anchor + page clamp are exactly the annotation click's). */
-function boxOfClick(point, policy, pageBox) {
-	const placement = (0, _embedpdf_plugin_annotation_authoring.resolveClickPlacement)(point, policy, { pageBox: pageBox ?? void 0 });
-	return placement.kind === "box" ? placement.rect : {
-		x: point.x,
-		y: point.y,
-		width: policy.width,
-		height: policy.height
+	return {
+		/** A text field's write, for the text being typed (write/typing.ts). */
+		setText: (ref, text) => commit(ref, { value: text }, "form.setValue"),
+		api: {
+			setValue: (ref, value, options) => commit(ref, value, "form.setValue", options),
+			setValues,
+			importValues
+		}
 	};
 }
 //#endregion
-//#region src/reducer.ts
-const initialFormState = () => ({ model: initialModel() });
-/** Dumb store: the pure core computes the next model; the shell dispatches it. */
-const formReducer = (state, action) => action.type === "SET_MODEL" ? { model: action.model } : state;
+//#region src/controller.ts
+/**
+* The form 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 `read/`, `write/` or `sync/`.
+*/
+function createFormController(ctx) {
+	const services = createServices(ctx);
+	const { events, rights } = services;
+	const settings = ctx.settings();
+	const fields = createFieldReads(ctx, services);
+	const widgets = createWidgetReads(ctx, services);
+	const settingsReads = createFieldSettings(services);
+	const fills = createFill(ctx, services);
+	const values = createValueWrites(ctx, services, fills);
+	const typing = createTyping(ctx, services, values.setText);
+	const resets = createResetWrites(ctx, services, fills);
+	const design = createFieldWrites(ctx, services);
+	const interchange = createInterchange(ctx, services);
+	const activation = createActivation(ctx, services, fills);
+	const scripts = createScriptEffects(ctx, services, fills);
+	const api = (0, _embedpdf_core.composeApi)("form", [
+		settings.api,
+		fields.api,
+		widgets.api,
+		settingsReads.api,
+		values.api,
+		typing.api,
+		resets.api,
+		design.api,
+		interchange.api,
+		activation.api,
+		scripts.api,
+		{
+			canRead: () => ctx.allows("doc.forms.read"),
+			canFill: (ref) => {
+				const field = fieldByRef(services.fields.view(), ref);
+				return field !== null && rights.mayFill(field);
+			},
+			canDesign: () => ctx.allows("doc.forms.modify"),
+			canRestoreAttribution: () => ctx.allows("doc.forms.import"),
+			canWriteScripts: () => ctx.allows("doc.forms.script"),
+			onValueChanged: events.valueChanged.on,
+			onFieldCreated: events.fieldCreated.on,
+			onFieldUpdated: events.fieldUpdated.on,
+			onFieldDeleted: events.fieldDeleted.on,
+			onValidationRejected: events.validationRejected.on,
+			onResynced: events.resynced.on
+		}
+	]);
+	return {
+		api,
+		connect: () => connectForm(ctx, api, createWidgetLender(ctx, services))
+	};
+}
 //#endregion
 //#region src/form.plugin.ts
 /**
-* The form plugin: the FIELD plane. Document-scoped; requires the
-* interaction hub. Fill mode works with no annotation plugin at all —
-* geometry is read from the engine's widget DTOs. When the annotation
-* plugin IS present, a Behavior keeps widgets geometry-inert while the
-* active tool carries 'form-fill' (the built-in pointer/pan tools do, so
-* filling is the resting state) and stands the fill controls down under
-* every other tool — the single-active-tool hub IS the mode switch.
-* Design mode = the 'form-edit' / palette tools: no 'form-fill' tag, so
-* widgets become ordinary editable annotations.
+* The form plugin: the field plane. Document-scoped; requires the
+* interaction hub. Filling works without the annotation plugin, because
+* widget geometry is read from the engine's widget records. The active tool
+* is the mode switch: while it carries 'form-fill' (the built-in pointer and
+* pan tools do, so filling is the resting state), the form layer draws and
+* fills every widget. Design mode is the 'form-edit' and palette tools: with
+* the annotation plugin present, the form lends it the widgets, which its
+* tools then select, move, restyle and delete. The render plugin draws the
+* widgets' pictures in both modes. `config` is the settings the app
+* registers, over {@link FORM_DEFAULTS}.
 */
-const formPlugin = (options = {}) => (0, _embedpdf_core.definePlugin)({
+const formPlugin = (config) => (0, _embedpdf_core.definePlugin)({
 	id: "form",
-	token: require_types.FormToken,
+	token: require_contract_host.FormToken,
 	scope: "document",
-	requires: [_embedpdf_plugin_interaction_contract.InteractionToken],
-	optional: [_embedpdf_plugin_annotation_contract.AnnotationToken, _embedpdf_plugin_actions_contract.ActionsToken],
-	initialState: initialFormState,
-	reduce: formReducer,
-	capability: (ctx) => createFormCapability(ctx, options),
-	effects: registerFormEffects,
-	init: (ctx) => {
-		const interaction = ctx.get(_embedpdf_plugin_interaction_contract.InteractionToken);
-		const form = ctx.get(require_types.FormToken);
-		interaction.registerTool({
-			id: "form-fill",
-			cursor: "default",
-			enables: /* @__PURE__ */ new Set(["form-fill", "link-nav"])
-		});
-		interaction.registerTool({
-			id: "form-edit",
-			cursor: "default",
-			enables: /* @__PURE__ */ new Set(["annotation-edit", "annotation-marquee"])
-		});
-		const annotation = ctx.tryGet(_embedpdf_plugin_annotation_contract_host.AnnotationToken);
-		for (const t of FORM_TOOLS) if (annotation) annotation.registerTool({
-			id: t.id,
-			subtype: t.visualKind,
-			cursor: t.cursor,
-			enables: [...PLACE_TAGS],
-			clickCreate: t.clickCreate,
-			defaults: t.defaults
-		});
-		else interaction.registerTool({
-			id: t.id,
-			cursor: t.cursor,
-			enables: new Set(PLACE_TAGS)
-		});
-		interaction.registerHandler(createPlaceHandler(form, interaction, annotation));
-		if (annotation) annotation.registerBehavior({
-			id: "form-widgets",
-			matches: (a) => a.subtype.startsWith("widget"),
-			engaged: () => interaction.activeTool()?.enables.has("form-fill") ?? false
-		});
-		const actions = ctx.tryGet(_embedpdf_plugin_actions_contract_host.ActionsToken);
-		if (actions) {
-			ctx.cleanup(actions.registerFormCommitSink((effects) => {
-				const formHost = ctx.tryGet(require_types.FormToken);
-				if (!formHost) return Promise.resolve({
-					results: effects.map((_, index) => ({
-						index,
-						status: "failed",
-						fields: [],
-						changedWidgets: []
-					})),
-					changedWidgets: [],
-					meta: null
-				});
-				return formHost.commitScriptFormEffects(effects);
-			}));
-			ctx.cleanup(actions.registerSubmitResolver((intent, actionCtx, diagnose) => {
-				const formHost = ctx.tryGet(require_types.FormToken);
-				if (!formHost) throw new Error("form plugin unavailable");
-				return formHost.resolveSubmitDataset(intent, actionCtx, diagnose);
-			}));
-			ctx.cleanup(actions.registerExecutor("reset-form", async (node, actionCtx) => {
-				if (node.type !== "reset-form") return {
-					status: "inert",
-					reason: "not a reset-form node"
-				};
-				const formHost = ctx.tryGet(require_types.FormToken);
-				if (!formHost) return {
-					status: "inert",
-					reason: "form plugin unavailable"
-				};
-				const result = await formHost.resetFormAction(node.fields, node.exclude, actionCtx.origin);
-				if (result.status === "failed") return {
-					status: "failed",
-					error: result.error?.message ?? "reset failed"
-				};
-				if (result.effectsResult === null) return {
-					status: "inert",
-					reason: result.diagnostics[0]?.message ?? "reset-form resolved no fields"
-				};
-				return { status: "executed" };
-			}));
-		}
+	requires: [_embedpdf_plugin_interaction_contract_host.InteractionToken],
+	optional: [
+		_embedpdf_plugin_annotation_contract.AnnotationToken,
+		_embedpdf_plugin_actions_contract.ActionsToken,
+		_embedpdf_plugin_render_contract.RenderToken
+	],
+	state: initialFormState,
+	settings: {
+		defaults: require_contract.FORM_DEFAULTS,
+		registered: config
+	},
+	create: createFormController
+});
+//#endregion
+//#region src/state.ts
+/**
+* The form page's State table as code: what `useFormState()` returns, and the
+* same fields in every other framework. One field's value has its own hook
+* (`useFormValue(ref)`), so a total in your own UI re-renders only when that
+* field changes.
+*/
+const NO_FIELDS = Object.freeze([]);
+const formState = (0, _embedpdf_core.defineState)(require_contract.FormToken, {
+	read: (form) => ({
+		fields: form.list(),
+		status: form.getStatus(),
+		formKind: form.getFormKind(),
+		selectedField: form.getSelectedField()
+	}),
+	empty: {
+		fields: NO_FIELDS,
+		status: "idle",
+		formKind: "none",
+		selectedField: null
 	}
 });
 //#endregion
+exports.FORM_DEFAULTS = require_contract.FORM_DEFAULTS;
 exports.FORM_TOOLS = FORM_TOOLS;
 exports.FORM_TOOL_BY_ID = FORM_TOOL_BY_ID;
-exports.FormScriptingController = require_scripting.FormScriptingController;
+exports.FormScriptingController = require_controller.FormScriptingController;
 exports.FormToken = require_contract.FormToken;
-exports.createFormScriptingController = require_scripting.createFormScriptingController;
-exports.createSerialMutationQueue = createSerialMutationQueue;
-exports.fieldKeyOf = fieldKeyOf;
+Object.defineProperty(exports, "FormTransfer", {
+	enumerable: true,
+	get: function() {
+		return _embedpdf_engine_core_public.FormTransfer;
+	}
+});
+exports.createFormScriptingController = require_controller.createFormScriptingController;
 exports.formPlugin = formPlugin;
+exports.formState = formState;
+Object.defineProperty(exports, "toFieldRef", {
+	enumerable: true,
+	get: function() {
+		return _embedpdf_engine_core_runtime.toFieldRef;
+	}
+});
 
 //# sourceMappingURL=index.cjs.map