@embedpdf/engine-core 3.0.0-next.13 → 3.0.0-next.15

package/dist/value-Dhc8eYcx.js

@@ -0,0 +1,340 @@
+import { h as EngineError, i as encodeFieldRefKey, m as annotationKey, u as encodePageKey, y as EngineErrorCode } from "./format-Dgg428Kb.js";
+//#region src/dto/PdfAction.ts
+/**
+* The one Table-240 decode, shared by the reader, the schema's producers,
+* and tests — so bit semantics cannot fork.
+*/
+const decodeSubmitFormFlags = (raw) => {
+	const bit = (n) => (raw & 1 << n - 1) !== 0;
+	const format = bit(9) ? "pdf" : bit(6) ? "xfdf" : bit(3) ? "html" : "fdf";
+	return {
+		raw,
+		exclude: bit(1),
+		includeNoValueFields: bit(2),
+		format,
+		method: bit(4) && (format === "html" || format === "pdf") ? "get" : "post",
+		submitCoordinates: bit(5),
+		includeAppendSaves: bit(7),
+		includeAnnotations: bit(8),
+		canonicalFormat: bit(10),
+		exclNonUserAnnots: bit(11),
+		exclFKey: bit(12),
+		embedForm: bit(14)
+	};
+};
+/**
+* Whether writing `action` puts code or a way out of the viewer into the
+* document, which takes `doc.forms.script`: a JavaScript, submit-form or URI
+* action anywhere in its tree.
+*/
+function needsScriptRight(action) {
+	return action.type === "javascript" || action.type === "submit-form" || action.type === "uri" || (action.next ?? []).some(needsScriptRight);
+}
+/**
+* Whether writing actions, a field's or a widget's, takes `doc.forms.script`:
+* an event gets a tree holding a JavaScript, submit-form or URI action.
+* Removing actions (`null`) never does, and neither does a widget's read sent
+* back: its trees are kept unchanged or refused, never written.
+*/
+function writesScripts(actions) {
+	return Object.values(actions ?? {}).some((action) => action != null && !("root" in action) && needsScriptRight(action));
+}
+/**
+* The write of a read action tree: what a copy writes. `null` when the tree
+* is incomplete, or holds a type a write can't make (a submit-form whose
+* payload the read dropped included).
+*/
+function actionWriteOf(tree) {
+	if (tree.incomplete || !tree.root) return null;
+	return nodeWriteOf(tree.root);
+}
+/**
+* A widget's read actions as a patch writes them: `null` for an event
+* without one. An event whose actions a write can't make is left out, so
+* writing the patch back never removes it.
+*/
+function widgetActionsOf(actions) {
+	const patch = {};
+	for (const event of WIDGET_ACTION_EVENTS) {
+		const tree = actions?.[event];
+		if (!tree) {
+			patch[event] = null;
+			continue;
+		}
+		const write = actionWriteOf(tree);
+		if (write) patch[event] = write;
+	}
+	return patch;
+}
+/** Every event a widget's actions run on, in `EPDF_ANNOT_ACTION_*` order. */
+const WIDGET_ACTION_EVENTS = [
+	"activate",
+	"cursorEnter",
+	"cursorExit",
+	"mouseDown",
+	"mouseUp",
+	"focus",
+	"blur",
+	"pageOpen",
+	"pageClose",
+	"pageVisible",
+	"pageInvisible"
+];
+/** The field script of a read tree: `null` unless it is JavaScript all through. */
+function fieldScriptOf(tree) {
+	const write = actionWriteOf(tree);
+	return write && isFieldScript(write) ? write : null;
+}
+/** Whether `action` is JavaScript all through: what a field event takes. */
+function isFieldScript(action) {
+	return action.type === "javascript" && (action.next ?? []).every(isFieldScript);
+}
+function nodeWriteOf(node) {
+	const next = [];
+	for (const child of node.next) {
+		const write = nodeWriteOf(child);
+		if (!write) return null;
+		next.push(write);
+	}
+	const tail = next.length > 0 ? { next } : {};
+	switch (node.type) {
+		case "javascript": return {
+			type: "javascript",
+			script: node.script,
+			...tail
+		};
+		case "goto": return {
+			type: "goto",
+			destination: node.destination,
+			...tail
+		};
+		case "uri": return {
+			type: "uri",
+			uri: node.uri,
+			...tail
+		};
+		case "named": return {
+			type: "named",
+			name: node.name,
+			...tail
+		};
+		case "hide": return {
+			type: "hide",
+			targets: node.targets,
+			hide: node.hide,
+			...tail
+		};
+		case "reset-form": return {
+			type: "reset-form",
+			fields: node.fields,
+			exclude: node.exclude,
+			...tail
+		};
+		case "submit-form": return node.payload ? {
+			type: "submit-form",
+			url: node.payload.url,
+			fields: node.payload.fields,
+			flags: node.payload.flags.raw,
+			...tail
+		} : null;
+		default: return null;
+	}
+}
+//#endregion
+//#region src/transfer/formExport.ts
+/**
+* The rows an export of `snapshot` takes for `selection`, in the form's
+* order: whole fields, each with every widget it has, whatever page they're
+* on; the fields' widget rows, in their fields' order; and the calculation
+* order among them. A field the form doesn't export (`noExport`) goes
+* without its value and who filled it, a signature field unsigned. `pages`
+* is the document's pages; a selected field or page the document doesn't
+* have is refused with `NotFound`.
+*/
+function formExportRowsOf(snapshot, selection, pages) {
+	const chosen = /* @__PURE__ */ new Set();
+	for (const ref of selection.fields ?? []) {
+		const field = snapshot.fields.find((candidate) => fieldMatches(candidate, ref));
+		if (!field) throw new EngineError(EngineErrorCode.NotFound, `export: the form has no field ${ref.kind === "fqn" ? ref.name : encodeFieldRefKey(ref)}`);
+		chosen.add(field);
+	}
+	const inDocument = new Set(pages.map(encodePageKey));
+	const selectedPages = /* @__PURE__ */ new Set();
+	for (const page of selection.pages ?? []) {
+		if (!inDocument.has(encodePageKey(page))) throw new EngineError(EngineErrorCode.NotFound, `export: the document has no page ${encodePageKey(page)}`);
+		selectedPages.add(encodePageKey(page));
+	}
+	for (const field of snapshot.fields) if (field.widgets.some((widget) => widget.page && selectedPages.has(encodePageKey(widget.page)))) chosen.add(field);
+	const everyField = !selection.fields && !selection.pages;
+	const fields = snapshot.fields.filter((field) => everyField || chosen.has(field));
+	const rowByKey = new Map(snapshot.widgets.map((row) => [annotationKey(row.ref), row]));
+	const widgets = fields.flatMap((field) => field.widgets.flatMap((widget) => {
+		const row = widget.ref ? rowByKey.get(annotationKey(widget.ref)) : void 0;
+		return row ? [row] : [];
+	}));
+	const exported = new Set(fields.map((field) => encodeFieldRefKey(field.ref)));
+	const calculationOrder = snapshot.calculationOrder.filter((ref) => ref !== null && exported.has(encodeFieldRefKey(ref)));
+	return {
+		fields: fields.map(exportedField),
+		widgets,
+		calculationOrder
+	};
+}
+/** Whether `field` is the one `ref` names, by its object number or its full name. */
+function fieldMatches(field, ref) {
+	return ref.kind === "fqn" ? field.name === ref.name : field.ref.kind === "objectNumber" && field.ref.objectNumber === ref.objectNumber;
+}
+/**
+* A field as an export carries it: one the form doesn't export without its
+* value and who filled it, and a signature field without its signature.
+*/
+function exportedField(field) {
+	if (field.family === "signature") return {
+		...field,
+		valueEntry: { kind: "none" }
+	};
+	if (!field.noExport) return field;
+	const unfilled = {
+		...field,
+		valueEntry: { kind: "none" },
+		filledBy: null,
+		filledByName: null,
+		filledAt: null
+	};
+	switch (field.family) {
+		case "text":
+		case "combobox": return {
+			...unfilled,
+			family: field.family,
+			value: ""
+		};
+		case "checkbox": return {
+			...unfilled,
+			family: "checkbox",
+			checked: false,
+			widgets: field.widgets.map((widget) => ({
+				...widget,
+				checked: false
+			}))
+		};
+		case "radio": return {
+			...unfilled,
+			family: "radio",
+			value: "Off",
+			widgets: field.widgets.map((widget) => ({
+				...widget,
+				checked: false
+			}))
+		};
+		case "listbox": return {
+			...unfilled,
+			family: "listbox",
+			selectedValues: [],
+			options: field.options.map((option) => ({
+				...option,
+				selected: false
+			}))
+		};
+		default: return unfilled;
+	}
+}
+//#endregion
+//#region src/mutation/FormMutationResults.ts
+/**
+* A reset as one value write per changed field: each field with the part of
+* the meta that is its own. A reset's `forms.valueSet` events carry these.
+*/
+function formResetFacts(result) {
+	return result.fields.map((field) => {
+		const own = new Set(field.widgets.map((widget) => widget.objectNumber));
+		const changedWidgets = result.meta.changedWidgets.filter((widget) => own.has(widget.objectNumber));
+		const widgets = result.widgets.filter((widget) => widget.ref.kind === "objectNumber" && own.has(widget.ref.objectNumber));
+		const pages = new Set(changedWidgets.flatMap((widget) => widget.page ? [widget.page.objectNumber] : []));
+		return {
+			field,
+			widgets,
+			meta: {
+				affectedPages: result.meta.affectedPages.filter((page) => pages.has(page.objectNumber)),
+				cacheDelta: null,
+				opId: result.meta.opId,
+				undoable: result.meta.undoable,
+				changedFields: [field.ref],
+				changedWidgets,
+				redrawnWidgets: result.meta.redrawnWidgets.filter((widget) => own.has(widget.objectNumber))
+			}
+		};
+	});
+}
+/** What a delete removed, as its event names it: the field in `meta.changedFields`. */
+function deletedFieldOf(result) {
+	return result.meta.changedFields[0] ?? null;
+}
+//#endregion
+//#region src/transfer/formImport.ts
+/** The flags a widget row has, which a copy keeps. */
+const WIDGET_FLAG_NAMES = [
+	"invisible",
+	"hidden",
+	"print",
+	"noZoom",
+	"noRotate",
+	"noView",
+	"readOnly",
+	"locked",
+	"toggleNoView",
+	"lockedContents"
+];
+/**
+* The facts a design import committed: one `forms.created` per field, in
+* bundle order, each with its own widgets and the part of the meta that is
+* its own. The calculation order, when the import changed it, rides on the
+* last.
+*/
+function formImportFacts(result) {
+	const last = result.fields.length - 1;
+	return result.fields.map((field, index) => {
+		const own = new Set(field.widgets.map((widget) => widget.objectNumber));
+		const widgets = result.widgets.filter((row) => row.ref.kind === "objectNumber" && own.has(row.ref.objectNumber));
+		const changedWidgets = result.meta.changedWidgets.filter((widget) => own.has(widget.objectNumber));
+		const pages = new Set(changedWidgets.flatMap((widget) => widget.page ? [widget.page.objectNumber] : []));
+		return {
+			field,
+			widgets,
+			...index === last && result.calculationOrder ? { calculationOrder: result.calculationOrder } : {},
+			meta: {
+				affectedPages: result.meta.affectedPages.filter((page) => pages.has(page.objectNumber)),
+				cacheDelta: index === last ? result.meta.cacheDelta : null,
+				opId: result.meta.opId,
+				undoable: result.meta.undoable,
+				changedFields: [field.ref],
+				changedWidgets,
+				redrawnWidgets: result.meta.redrawnWidgets.filter((widget) => own.has(widget.objectNumber))
+			}
+		};
+	});
+}
+/** The facts a values import committed: one `forms.valueSet` per field it filled, as a reset's. */
+function formValuesImportFacts(result) {
+	return formResetFacts(result);
+}
+//#endregion
+//#region src/forms/value.ts
+/**
+* The value `field` holds, as a value write takes it: writing it to the
+* same field changes nothing. `null` for a field whose value a write can't
+* set (a push button, a signature, a family the engine doesn't know).
+*/
+function fieldValueOf(field) {
+	switch (field.family) {
+		case "checkbox": return { checked: field.checked };
+		case "listbox": return { selectedValues: field.selectedValues };
+		case "radio": return { value: field.value === "Off" ? null : field.value };
+		case "text":
+		case "combobox": return { value: field.value };
+		default: return null;
+	}
+}
+//#endregion
+export { deletedFieldOf as a, formExportRowsOf as c, decodeSubmitFormFlags as d, fieldScriptOf as f, writesScripts as g, widgetActionsOf as h, formValuesImportFacts as i, WIDGET_ACTION_EVENTS as l, needsScriptRight as m, WIDGET_FLAG_NAMES as n, formResetFacts as o, isFieldScript as p, formImportFacts as r, fieldMatches as s, fieldValueOf as t, actionWriteOf as u };
+
+//# sourceMappingURL=value-Dhc8eYcx.js.map

package/dist/value-Dhc8eYcx.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"value-Dhc8eYcx.js","names":[],"sources":["../src/dto/PdfAction.ts","../src/transfer/formExport.ts","../src/mutation/FormMutationResults.ts","../src/transfer/formImport.ts","../src/forms/value.ts"],"sourcesContent":["import type { PageDestination } from './PdfDestination';\n\n/** Normalized values of an action dictionary's `/S` name. */\nexport type PdfActionType = PdfActionNode['type'];\n\n/**\n * One Hide `/T` or ResetForm `/Fields` entry. Deliberately unscoped: a\n * dictionary reference carries no page, so resolution (a name to widgets, an\n * object number to an annotation or field) is the interpreter's job — never\n * the extractor's.\n */\nexport type PdfActionTargetRef =\n  | { kind: 'name'; name: string }\n  | { kind: 'objectNumber'; objectNumber: number };\n\n/**\n * Decoded SubmitForm `/Flags` word (ISO 32000-2:2020 Table 240) plus the raw\n * value. `exclude` is derived from bit 1 — never stored separately, so the\n * two cannot disagree. Note the two easily-missed positions verified against\n * the spec: bit 12 is `ExclFKey` (not \"ExclFDFTemplate\") and bit 13 is\n * reserved/undefined, so `EmbedForm` is bit 14.\n */\nexport interface SubmitFormFlags {\n  raw: number;\n  /** Bit 1: set → `fields` lists excluded fields. */\n  exclude: boolean;\n  /** Bit 2: submit designated valueless fields too, as name-only entries. */\n  includeNoValueFields: boolean;\n  /** Bits 3/6/9 folded into one verdict: bit 9 SubmitPDF dominates (\"all\n   *  other flags shall be ignored except GetMethod\"), else bit 6 XFDF, else\n   *  bit 3 HTML Form format, else FDF (the Table 240 default). */\n  format: 'fdf' | 'html' | 'xfdf' | 'pdf';\n  /** Bit 4. ISO makes GetMethod meaningful only with ExportFormat set, and\n   *  the bit-9 rule keeps it alive for SubmitPDF — so `'get'` only for\n   *  `'html'` and `'pdf'`; everything else posts. */\n  method: 'post' | 'get';\n  /** Bit 5 (meaningful only with ExportFormat; passed through — this stack\n   *  does not capture click coordinates). */\n  submitCoordinates: boolean;\n  /** Bit 7 (FDF only): include incremental updates via FDF `Differences`. */\n  includeAppendSaves: boolean;\n  /** Bit 8 (FDF only): include markup annotations. */\n  includeAnnotations: boolean;\n  /** Bit 10: convert date-like values to the standard date format. */\n  canonicalFormat: boolean;\n  /** Bit 11 (FDF, with IncludeAnnotations): only the current user's\n   *  annotations. */\n  exclNonUserAnnots: boolean;\n  /** Bit 12: the submitted FDF excludes its `F` entry. */\n  exclFKey: boolean;\n  /** Bit 14 (bit 13 is reserved): the FDF `F` entry embeds the source PDF. */\n  embedForm: boolean;\n}\n\n/**\n * The one Table-240 decode, shared by the reader, the schema's producers,\n * and tests — so bit semantics cannot fork.\n */\nexport const decodeSubmitFormFlags = (raw: number): SubmitFormFlags => {\n  const bit = (n: number): boolean => (raw & (1 << (n - 1))) !== 0;\n  const format = bit(9) ? 'pdf' : bit(6) ? 'xfdf' : bit(3) ? 'html' : 'fdf';\n  return {\n    raw,\n    exclude: bit(1),\n    includeNoValueFields: bit(2),\n    format,\n    method: bit(4) && (format === 'html' || format === 'pdf') ? 'get' : 'post',\n    submitCoordinates: bit(5),\n    includeAppendSaves: bit(7),\n    includeAnnotations: bit(8),\n    canonicalFormat: bit(10),\n    exclNonUserAnnots: bit(11),\n    exclFKey: bit(12),\n    embedForm: bit(14),\n  };\n};\n\n/**\n * SubmitForm's extracted intent. Atomic on purpose: either every required\n * component resolved (a complete, executable payload) or the node carries no\n * payload at all — partial states are unrepresentable. An unreadable\n * required component (`/F`) degrades the whole node to `unknown` +\n * `payload-dropped` at read time instead.\n */\nexport interface SubmitFormPayload {\n  /** Resolved `/F` URL — a `<< /FS /URL >>` file specification (7.11.5,\n   *  `/UF` preferred over `/F` per 7.11.2); a bare string `/F` is accepted\n   *  as a producer-compat extension. */\n  url: string;\n  /**\n   * `null` = `/Fields` absent → Include/Exclude is ignored and every field\n   * except NoExport-flagged ones is submitted (Table 239). `[]` =\n   * present-but-empty: include mode submits nothing, exclude mode submits\n   * everything eligible — presence and emptiness are different states.\n   */\n  fields: PdfActionTargetRef[] | null;\n  flags: SubmitFormFlags;\n  /** `/CharSet` (PDF 2.0), extracted but not encoded by this stack. */\n  charSet?: string;\n}\n\ninterface PdfActionNodeCommon<Destination> {\n  /** Raw `/S` name, retained for unknown and future action types. */\n  subtype: string;\n  /** Normalized `/Next` children in PDF order. */\n  next: PdfActionNode<Destination>[];\n}\n\n/**\n * One detached node in a normalized PDF action tree, discriminated on the\n * interpreter that would execute it. Every executable arm carries its full\n * payload — a `goto` without a destination or a `uri` without a URI is\n * unrepresentable. A payload the reader cannot materialize degrades the node\n * to `unknown` (original `/S` kept on `subtype`) and appends the tree-level\n * `'payload-dropped'` warning. A `goto` goes to a {@link PageDestination};\n * the engine's own readers, which work in the file's coordinates, use\n * `PdfActionNode<PdfDestination>`.\n */\nexport type PdfActionNode<Destination = PageDestination> = PdfActionNodeCommon<Destination> &\n  (\n    | { type: 'javascript'; script: string }\n    | { type: 'goto'; destination: Destination }\n    | { type: 'uri'; uri: string; isMap: boolean }\n    | { type: 'named'; name: string }\n    | { type: 'hide'; targets: PdfActionTargetRef[]; hide: boolean }\n    | {\n        type: 'reset-form';\n        /**\n         * `null` = `/Fields` absent → reset every field (`exclude` is\n         * meaningless). `[]` = present-but-empty: with `exclude` false reset\n         * nothing, with `exclude` true reset everything — PDFium's executor\n         * branches on presence first.\n         */\n        fields: PdfActionTargetRef[] | null;\n        exclude: boolean;\n      }\n    /** Reported, never executed. */\n    | { type: 'goto-remote'; filePath: string }\n    | { type: 'goto-embedded'; filePath: string }\n    | { type: 'launch'; filePath: string }\n    /** ISO allows `/Rendition` to carry `/JS`; preserved, not collected. */\n    | { type: 'rendition'; script?: string }\n    /** Recognized; executable only when `payload` is present. Absent payload\n     *  = extracted by a runtime without the SubmitForm getters (version\n     *  skew) — the node stays recognized-inert. */\n    | { type: 'submit-form'; payload?: SubmitFormPayload }\n    | { type: 'thread' }\n    | { type: 'sound' }\n    | { type: 'movie' }\n    | { type: 'import-data' }\n    | { type: 'set-ocg-state' }\n    | { type: 'transition' }\n    | { type: 'goto-3d-view' }\n    | { type: 'unknown' }\n  );\n\nexport type PdfActionWarning =\n  | 'cycle-dropped'\n  | 'malformed-next'\n  | 'incomplete'\n  /** A node's payload could not be read; that node degraded to `unknown`. */\n  | 'payload-dropped';\n\n/**\n * One extracted action root plus the native reader's safety verdict.\n * Consumers must never execute a tree whose `incomplete` flag is true.\n */\nexport interface PdfActionTree<Destination = PageDestination> {\n  /** Null when the model was valid but its root exceeded a safety bound. */\n  root: PdfActionNode<Destination> | null;\n  incomplete: boolean;\n  /** Raw native bits, retained so newer warnings survive older SDKs.\n   *  TS-detected warnings (`payload-dropped`) appear only in `warnings`. */\n  warningFlags: number;\n  warnings: PdfActionWarning[];\n}\n\nexport interface PdfFieldActions<Destination = PageDestination> {\n  keystroke?: PdfActionTree<Destination>;\n  format?: PdfActionTree<Destination>;\n  validate?: PdfActionTree<Destination>;\n  calculate?: PdfActionTree<Destination>;\n}\n\nexport interface PdfPageActions<Destination = PageDestination> {\n  open?: PdfActionTree<Destination>;\n  close?: PdfActionTree<Destination>;\n}\n\nexport interface PdfAnnotationActions<Destination = PageDestination> {\n  activate?: PdfActionTree<Destination>;\n  cursorEnter?: PdfActionTree<Destination>;\n  cursorExit?: PdfActionTree<Destination>;\n  mouseDown?: PdfActionTree<Destination>;\n  mouseUp?: PdfActionTree<Destination>;\n  focus?: PdfActionTree<Destination>;\n  blur?: PdfActionTree<Destination>;\n  pageOpen?: PdfActionTree<Destination>;\n  pageClose?: PdfActionTree<Destination>;\n  pageVisible?: PdfActionTree<Destination>;\n  pageInvisible?: PdfActionTree<Destination>;\n}\n\nexport interface NamedJavaScriptAction<Destination = PageDestination> {\n  /** Name-tree key. Array order is the PDF boot order. */\n  name: string;\n  action: PdfActionTree<Destination>;\n}\n\n/** Catalog-owned actions. Page actions stay on their owning PageLayout. */\nexport interface DocumentActionsSnapshot<Destination = PageDestination> {\n  nameTreeScripts: NamedJavaScriptAction<Destination>[];\n  /** Action-form `/OpenAction`. Mutually exclusive with `openDestination` —\n   *  `/OpenAction` is one entry, a dictionary or an array. */\n  openAction: PdfActionTree<Destination> | null;\n  /** Destination-form `/OpenAction` — the initial view, not an action.\n   *  Optional on the wire for skew tolerance (absent ≡ null); the schema\n   *  defaults it, so parsed snapshots always carry the key. */\n  openDestination?: Destination | null;\n  willClose?: PdfActionTree<Destination>;\n  willSave?: PdfActionTree<Destination>;\n  didSave?: PdfActionTree<Destination>;\n  willPrint?: PdfActionTree<Destination>;\n  didPrint?: PdfActionTree<Destination>;\n}\n\n/**\n * Aggregate guard applied across every action model read by one job. Native\n * limits are per model; this prevents a document containing many models from\n * creating an unbounded detached snapshot.\n */\nexport interface ActionReadBudget {\n  maxModels: number;\n  maxNodes: number;\n  maxScriptCodeUnits: number;\n  /** Hide `/T` + ResetForm/SubmitForm `/Fields` entries, aggregate across\n   *  the job. */\n  maxTargetEntries: number;\n  /** Payload string code units (URIs, submit URLs/CharSets, names, file\n   *  paths, name-tree script names), aggregate across the job. Reserved\n   *  before allocation. */\n  maxPayloadCodeUnits: number;\n}\n\n// ── writing actions ──\n\n/**\n * An action to write: the read shape ({@link PdfActionNode}) of a type a\n * write can make, without what only a read reports (`subtype`, a tree's\n * warnings). `next` runs after it, in order. A write makes JavaScript,\n * go-to, URI, named, hide, reset-form and submit-form actions; a `uri`'s\n * `isMap` and a submit's `charSet` are read, never written.\n */\nexport type PdfActionWrite<Destination = PageDestination> = {\n  next?: PdfActionWrite<Destination>[];\n} & (\n  | { type: 'javascript'; script: string }\n  | { type: 'goto'; destination: Destination }\n  | { type: 'uri'; uri: string }\n  | { type: 'named'; name: string }\n  | { type: 'hide'; targets: PdfActionTargetRef[]; hide: boolean }\n  | {\n      type: 'reset-form';\n      /** As read: `null` resets every field, `[]` with `exclude` false resets none. */\n      fields: PdfActionTargetRef[] | null;\n      exclude: boolean;\n    }\n  | {\n      type: 'submit-form';\n      url: string;\n      /** As read: `null` submits every field the form exports. */\n      fields: PdfActionTargetRef[] | null;\n      /** The raw `/Flags` word (ISO 32000-2 Table 240); 0 when left out. */\n      flags?: number;\n    }\n);\n\n/**\n * A field event's script: JavaScript, with more scripts to run after it.\n * A field's events (keystroke, format, validate, calculate) take JavaScript\n * only: every viewer runs them as script hooks.\n */\nexport interface FieldScriptWrite {\n  type: 'javascript';\n  script: string;\n  next?: FieldScriptWrite[];\n}\n\n/** The events a field's scripts run on. */\nexport type FieldScriptEvent = keyof PdfFieldActions;\n\n/** The events a widget's actions run on: `activate` (`/A`, a click) and its `/AA` events. */\nexport type WidgetActionEvent = keyof PdfAnnotationActions;\n\n/**\n * A widget's actions to write, by event: an action sets the event's, `null`\n * removes it, and an event left out keeps what it has. Any type a write\n * makes; a JavaScript, submit-form or URI action anywhere in a tree takes\n * `doc.forms.script` too.\n */\nexport type WidgetActionsPatch<Destination = PageDestination> = {\n  [Event in WidgetActionEvent]?: PdfActionWrite<Destination> | null;\n};\n\n/**\n * A field's scripts to write, by event: a script sets the event's, `null`\n * removes it, and an event left out keeps what it has. A `calculate` script\n * puts the field in the form's calculation order (at the end, when it isn't\n * there yet); removing it takes the field out.\n */\nexport type FieldActionsPatch = { [Event in FieldScriptEvent]?: FieldScriptWrite | null };\n\n/**\n * Whether writing `action` puts code or a way out of the viewer into the\n * document, which takes `doc.forms.script`: a JavaScript, submit-form or URI\n * action anywhere in its tree.\n */\nexport function needsScriptRight(action: PdfActionWrite<unknown>): boolean {\n  return (\n    action.type === 'javascript' ||\n    action.type === 'submit-form' ||\n    action.type === 'uri' ||\n    (action.next ?? []).some(needsScriptRight)\n  );\n}\n\n/**\n * Whether writing actions, a field's or a widget's, takes `doc.forms.script`:\n * an event gets a tree holding a JavaScript, submit-form or URI action.\n * Removing actions (`null`) never does, and neither does a widget's read sent\n * back: its trees are kept unchanged or refused, never written.\n */\nexport function writesScripts(\n  actions:\n    | FieldActionsPatch\n    | WidgetActionsPatch<unknown>\n    | PdfAnnotationActions<unknown>\n    | null\n    | undefined,\n): boolean {\n  return Object.values(actions ?? {}).some(\n    (action: PdfActionWrite<unknown> | PdfActionTree<unknown> | null | undefined) =>\n      action != null && !('root' in action) && needsScriptRight(action),\n  );\n}\n\n/**\n * The write of a read action tree: what a copy writes. `null` when the tree\n * is incomplete, or holds a type a write can't make (a submit-form whose\n * payload the read dropped included).\n */\nexport function actionWriteOf<Destination>(\n  tree: PdfActionTree<Destination>,\n): PdfActionWrite<Destination> | null {\n  if (tree.incomplete || !tree.root) return null;\n  return nodeWriteOf(tree.root);\n}\n\n/**\n * A widget's read actions as a patch writes them: `null` for an event\n * without one. An event whose actions a write can't make is left out, so\n * writing the patch back never removes it.\n */\nexport function widgetActionsOf<Destination>(\n  actions: PdfAnnotationActions<Destination> | null,\n): WidgetActionsPatch<Destination> {\n  const patch: WidgetActionsPatch<Destination> = {};\n  for (const event of WIDGET_ACTION_EVENTS) {\n    const tree = actions?.[event];\n    if (!tree) {\n      patch[event] = null;\n      continue;\n    }\n    const write = actionWriteOf(tree);\n    if (write) patch[event] = write;\n  }\n  return patch;\n}\n\n/** Every event a widget's actions run on, in `EPDF_ANNOT_ACTION_*` order. */\nexport const WIDGET_ACTION_EVENTS = [\n  'activate',\n  'cursorEnter',\n  'cursorExit',\n  'mouseDown',\n  'mouseUp',\n  'focus',\n  'blur',\n  'pageOpen',\n  'pageClose',\n  'pageVisible',\n  'pageInvisible',\n] as const satisfies readonly WidgetActionEvent[];\n\n/** The field script of a read tree: `null` unless it is JavaScript all through. */\nexport function fieldScriptOf(tree: PdfActionTree<unknown>): FieldScriptWrite | null {\n  const write = actionWriteOf(tree);\n  return write && isFieldScript(write) ? write : null;\n}\n\n/** Whether `action` is JavaScript all through: what a field event takes. */\nexport function isFieldScript(action: PdfActionWrite<unknown>): action is FieldScriptWrite {\n  return action.type === 'javascript' && (action.next ?? []).every(isFieldScript);\n}\n\nfunction nodeWriteOf<Destination>(\n  node: PdfActionNode<Destination>,\n): PdfActionWrite<Destination> | null {\n  const next: PdfActionWrite<Destination>[] = [];\n  for (const child of node.next) {\n    const write = nodeWriteOf(child);\n    if (!write) return null;\n    next.push(write);\n  }\n  const tail = next.length > 0 ? { next } : {};\n  switch (node.type) {\n    case 'javascript':\n      return { type: 'javascript', script: node.script, ...tail };\n    case 'goto':\n      return { type: 'goto', destination: node.destination, ...tail };\n    case 'uri':\n      return { type: 'uri', uri: node.uri, ...tail };\n    case 'named':\n      return { type: 'named', name: node.name, ...tail };\n    case 'hide':\n      return { type: 'hide', targets: node.targets, hide: node.hide, ...tail };\n    case 'reset-form':\n      return { type: 'reset-form', fields: node.fields, exclude: node.exclude, ...tail };\n    case 'submit-form':\n      return node.payload\n        ? {\n            type: 'submit-form',\n            url: node.payload.url,\n            fields: node.payload.fields,\n            flags: node.payload.flags.raw,\n            ...tail,\n          }\n        : null;\n    default:\n      return null;\n  }\n}\n","import type { WidgetAnnotation } from '../annotation/kinds/widget';\nimport { EngineError } from '../errors/EngineError';\nimport { EngineErrorCode } from '../errors/EngineErrorCode';\nimport type { FormFieldDTO } from '../forms/field';\nimport type { FormSnapshot } from '../forms/snapshot';\nimport { annotationKey } from '../identity/annotationKey';\nimport { encodeFieldRefKey, type FormFieldRef } from '../identity/FormFieldRef';\nimport { encodePageKey, type PageRef } from '../identity/PageRef';\nimport type { Coordinates } from '../pageSpace/coordinates';\n\n/** Which fields an export takes, each whole. Without `fields` or `pages`, every field. */\nexport interface FormExportSelection {\n  readonly fields?: readonly FormFieldRef[];\n  /** Every field with a widget on one of these pages, with all of its widgets. */\n  readonly pages?: readonly PageRef[];\n}\n\n/** What an export of a form takes: its rows, before the page table and resources. */\nexport interface FormExportRows<C extends Coordinates> {\n  readonly fields: FormFieldDTO<C>[];\n  readonly widgets: WidgetAnnotation<C>[];\n  readonly calculationOrder: FormFieldRef[];\n}\n\n/**\n * The rows an export of `snapshot` takes for `selection`, in the form's\n * order: whole fields, each with every widget it has, whatever page they're\n * on; the fields' widget rows, in their fields' order; and the calculation\n * order among them. A field the form doesn't export (`noExport`) goes\n * without its value and who filled it, a signature field unsigned. `pages`\n * is the document's pages; a selected field or page the document doesn't\n * have is refused with `NotFound`.\n */\nexport function formExportRowsOf<C extends Coordinates>(\n  snapshot: FormSnapshot<C>,\n  selection: FormExportSelection,\n  pages: readonly PageRef[],\n): FormExportRows<C> {\n  const chosen = new Set<FormFieldDTO<C>>();\n  for (const ref of selection.fields ?? []) {\n    const field = snapshot.fields.find((candidate) => fieldMatches(candidate, ref));\n    if (!field) {\n      throw new EngineError(\n        EngineErrorCode.NotFound,\n        `export: the form has no field ${ref.kind === 'fqn' ? ref.name : encodeFieldRefKey(ref)}`,\n      );\n    }\n    chosen.add(field);\n  }\n  const inDocument = new Set(pages.map(encodePageKey));\n  const selectedPages = new Set<string>();\n  for (const page of selection.pages ?? []) {\n    if (!inDocument.has(encodePageKey(page))) {\n      throw new EngineError(\n        EngineErrorCode.NotFound,\n        `export: the document has no page ${encodePageKey(page)}`,\n      );\n    }\n    selectedPages.add(encodePageKey(page));\n  }\n  for (const field of snapshot.fields) {\n    if (\n      field.widgets.some((widget) => widget.page && selectedPages.has(encodePageKey(widget.page)))\n    ) {\n      chosen.add(field);\n    }\n  }\n  const everyField = !selection.fields && !selection.pages;\n  const fields = snapshot.fields.filter((field) => everyField || chosen.has(field));\n\n  const rowByKey = new Map(snapshot.widgets.map((row) => [annotationKey(row.ref), row]));\n  const widgets = fields.flatMap((field) =>\n    field.widgets.flatMap((widget) => {\n      const row = widget.ref ? rowByKey.get(annotationKey(widget.ref)) : undefined;\n      return row ? [row] : [];\n    }),\n  );\n  const exported = new Set(fields.map((field) => encodeFieldRefKey(field.ref)));\n  const calculationOrder = snapshot.calculationOrder.filter(\n    (ref): ref is FormFieldRef => ref !== null && exported.has(encodeFieldRefKey(ref)),\n  );\n  return { fields: fields.map(exportedField), widgets, calculationOrder };\n}\n\n/** Whether `field` is the one `ref` names, by its object number or its full name. */\nexport function fieldMatches(\n  field: { ref: FormFieldRef; name: string },\n  ref: FormFieldRef,\n): boolean {\n  return ref.kind === 'fqn'\n    ? field.name === ref.name\n    : field.ref.kind === 'objectNumber' && field.ref.objectNumber === ref.objectNumber;\n}\n\n/**\n * A field as an export carries it: one the form doesn't export without its\n * value and who filled it, and a signature field without its signature.\n */\nfunction exportedField<C extends Coordinates>(field: FormFieldDTO<C>): FormFieldDTO<C> {\n  if (field.family === 'signature') return { ...field, valueEntry: { kind: 'none' } };\n  if (!field.noExport) return field;\n  const unfilled = {\n    ...field,\n    valueEntry: { kind: 'none' },\n    filledBy: null,\n    filledByName: null,\n    filledAt: null,\n  } as const;\n  switch (field.family) {\n    case 'text':\n    case 'combobox':\n      return { ...unfilled, family: field.family, value: '' } as FormFieldDTO<C>;\n    case 'checkbox':\n      return {\n        ...unfilled,\n        family: 'checkbox',\n        checked: false,\n        widgets: field.widgets.map((widget) => ({ ...widget, checked: false })),\n      } as FormFieldDTO<C>;\n    case 'radio':\n      return {\n        ...unfilled,\n        family: 'radio',\n        value: 'Off',\n        widgets: field.widgets.map((widget) => ({ ...widget, checked: false })),\n      } as FormFieldDTO<C>;\n    case 'listbox':\n      return {\n        ...unfilled,\n        family: 'listbox',\n        selectedValues: [],\n        options: field.options.map((option) => ({ ...option, selected: false })),\n      } as FormFieldDTO<C>;\n    default:\n      return unfilled as FormFieldDTO<C>;\n  }\n}\n","import type { MutationMeta } from './MutationMeta';\nimport type { AppearanceOutcome } from '../annotation/appearance';\nimport type { WidgetAnnotation } from '../annotation/kinds/widget';\nimport type { FormFieldDTO } from '../forms/field';\nimport type { AnnotationRef } from '../identity/AnnotationRef';\nimport type { FormFieldRef, FormWidget } from '../identity/FormFieldRef';\nimport type { PageRef } from '../identity/PageRef';\nimport type { Coordinates, PageCoordinates } from '../pageSpace/coordinates';\n\n/**\n * A single-field write's meta: the page envelope plus what changed — the\n * field (for a delete, the field that went) and every widget whose look\n * changed or that went with it. A field's widgets can live on several\n * pages, so use `changedWidgets` to invalidate page renders and appearance\n * caches. An idempotent write (the same value again) lists no widgets.\n */\nexport interface FormMutationMeta extends MutationMeta {\n  /** The fields written, by object number. */\n  changedFields: FormFieldRef[];\n  changedWidgets: FormWidget[];\n  /**\n   * The widgets of `changedWidgets` whose look was drawn again (a text or\n   * choice value, a new look): their pictures changed. A checkbox or radio\n   * button whose value only switched its state isn't one, nor is a widget\n   * shown or hidden: their pictures are the ones they had.\n   */\n  redrawnWidgets: FormWidget[];\n}\n\n/**\n * The widget rows a form write changed, read back after it: each widget of\n * `meta.changedWidgets` that is still on a page, as `doc.forms.list()` shows\n * it. A form's mirror folds them without a read.\n */\nexport interface FormWidgetRows<C extends Coordinates = PageCoordinates> {\n  widgets: WidgetAnnotation<C>[];\n}\n\n/** Result of a value write (`setValue` / `reset`): the field read back after the write. */\nexport interface FormSetValueResult<\n  C extends Coordinates = PageCoordinates,\n> extends FormWidgetRows<C> {\n  field: FormFieldDTO<C>;\n  meta: FormMutationMeta;\n}\n\n/**\n * Result of `reset`: the fields that changed, read back, and one meta for\n * all of them. An empty `fields` means every field was already at its\n * default.\n */\nexport interface FormResetResult<\n  C extends Coordinates = PageCoordinates,\n> extends FormWidgetRows<C> {\n  fields: FormFieldDTO<C>[];\n  meta: FormMutationMeta;\n}\n\n/**\n * A reset as one value write per changed field: each field with the part of\n * the meta that is its own. A reset's `forms.valueSet` events carry these.\n */\nexport function formResetFacts<C extends Coordinates>(\n  result: FormResetResult<C>,\n): FormSetValueResult<C>[] {\n  return result.fields.map((field) => {\n    const own = new Set(field.widgets.map((widget) => widget.objectNumber));\n    const changedWidgets = result.meta.changedWidgets.filter((widget) =>\n      own.has(widget.objectNumber),\n    );\n    const widgets = result.widgets.filter(\n      (widget) => widget.ref.kind === 'objectNumber' && own.has(widget.ref.objectNumber),\n    );\n    const pages = new Set(\n      changedWidgets.flatMap((widget) => (widget.page ? [widget.page.objectNumber] : [])),\n    );\n    return {\n      field,\n      widgets,\n      meta: {\n        affectedPages: result.meta.affectedPages.filter((page) => pages.has(page.objectNumber)),\n        cacheDelta: null,\n        opId: result.meta.opId,\n        undoable: result.meta.undoable,\n        changedFields: [field.ref],\n        changedWidgets,\n        redrawnWidgets: result.meta.redrawnWidgets.filter((widget) => own.has(widget.objectNumber)),\n      },\n    };\n  });\n}\n\n/** Result of `create`: the field read back, and its widget rows. */\nexport interface FormFieldCreateResult<\n  C extends Coordinates = PageCoordinates,\n> extends FormWidgetRows<C> {\n  field: FormFieldDTO<C>;\n  /** The form's calculation order, when the write changed it (a `calculate` script). */\n  calculationOrder?: FormFieldRef[];\n  meta: FormMutationMeta;\n}\n\n/** Result of `update` and `setSignatureAppearance`. */\nexport interface FormFieldUpdateResult<\n  C extends Coordinates = PageCoordinates,\n> extends FormWidgetRows<C> {\n  field: FormFieldDTO<C>;\n  /** The form's calculation order, when the write changed it (a `calculate` script). */\n  calculationOrder?: FormFieldRef[];\n  meta: FormMutationMeta;\n}\n\n/**\n * Result of `updateWidget`: the widget read back after the patch, and the\n * engine's appearance verdict (see `AnnotationUpdateResult.appearance`).\n */\nexport interface FormWidgetUpdateResult<C extends Coordinates = PageCoordinates> {\n  widget: WidgetAnnotation<C>;\n  appearance: AppearanceOutcome;\n  meta: FormMutationMeta;\n}\n\n/**\n * Result of `reorderWidgets`: the page's widgets in their new paint order,\n * whole, as refs. Widgets paint above every annotation, in this order.\n */\nexport interface FormWidgetsReorderResult {\n  page: PageRef;\n  /** Every widget of the page, bottom to top. */\n  order: AnnotationRef[];\n  /** `meta.changedWidgets` names the widgets that moved, in the order given. */\n  meta: FormMutationMeta;\n}\n\n/**\n * Result of `delete`: nothing exists after it, so only `meta`. The field's\n * widgets are deleted from their pages as part of the cascade; `meta` names\n * the field and lists them, so caches can invalidate.\n */\nexport interface FormFieldDeleteResult {\n  /** The form's calculation order, when the field was in it. */\n  calculationOrder?: FormFieldRef[];\n  meta: FormMutationMeta;\n}\n\n/**\n * Result of `reorderCalculations`: the form's calculation order, whole: the\n * fields whose calculate scripts run, in the order they run.\n */\nexport interface FormCalculationsReorderResult {\n  calculationOrder: FormFieldRef[];\n  /** `meta.changedFields` names the fields that moved, in the order given. */\n  meta: FormMutationMeta;\n}\n\n/** What a delete removed, as its event names it: the field in `meta.changedFields`. */\nexport function deletedFieldOf(result: FormFieldDeleteResult): FormFieldRef | null {\n  return result.meta.changedFields[0] ?? null;\n}\n\n/**\n * Result of `addWidget` / `removeWidget`: the field read back, and the\n * widget's row (a removed widget stays on its page, in no field).\n */\nexport interface FormWidgetLinkResult<\n  C extends Coordinates = PageCoordinates,\n> extends FormWidgetRows<C> {\n  field: FormFieldDTO<C>;\n  meta: FormMutationMeta;\n}\n\n/**\n * Result of `deleteWidget`: the widget is gone from its page, and from its\n * field when it had one. `field` is that field read back, `null` for a widget\n * in no field.\n */\nexport interface FormWidgetDeleteResult<C extends Coordinates = PageCoordinates> {\n  widget: AnnotationRef;\n  page: PageRef;\n  field: FormFieldDTO<C> | null;\n  meta: FormMutationMeta;\n}\n\n/**\n * What an undo of `deleteWidget` answers: the widget's row, back on its page\n * at its place, and its field with it again (`null` for a widget in no field).\n */\nexport interface FormWidgetRestoreResult<\n  C extends Coordinates = PageCoordinates,\n> extends FormWidgetRows<C> {\n  field: FormFieldDTO<C> | null;\n  meta: FormMutationMeta;\n}\n\n/**\n * Result of a repair pass. Repair is validate-then-apply and idempotent:\n * when there is nothing to fix, every counter is zero and the document is\n * untouched.\n */\nexport interface FormRepairResult {\n  /** A missing /AcroForm dictionary was created (with /DR and /DA). */\n  acroformCreated: boolean;\n  /** Recovered field roots appended to /AcroForm /Fields. */\n  fieldsLinked: number;\n  /** Stray widgets appended to their parent field's /Kids. */\n  widgetsLinked: number;\n  /** Direct-object fields that cannot be referenced and stay recovered. */\n  fieldsUnrepairable: number;\n  /** Widgets whose appearance stream was (re)generated. */\n  appearancesBaked: number;\n  /** /NeedAppearances was cleared after re-baking. */\n  needsAppearancesCleared: boolean;\n  meta: MutationMeta;\n}\n","import type { BundleImportPages } from './bundle';\nimport type { FormBundle } from './FormBundle';\nimport type { WidgetAnnotation, WidgetPatch } from '../annotation/kinds/widget';\nimport type { FormFieldDTO } from '../forms/field';\nimport type { AnnotationRef } from '../identity/AnnotationRef';\nimport type { FormFieldRef } from '../identity/FormFieldRef';\nimport {\n  formResetFacts,\n  type FormFieldCreateResult,\n  type FormMutationMeta,\n  type FormSetValueResult,\n} from '../mutation/FormMutationResults';\nimport type { WriteOptions } from '../mutation/WriteOptions';\nimport type { Coordinates, PageCoordinates } from '../pageSpace/coordinates';\n\n/**\n * How to import a form's design (`doc.forms.import`). The `opId` names the\n * import: its events share it as `origin.tx.id`, `doc.apply({ undoOf })`\n * undoes it, and a retry with the same id applies once.\n */\nexport interface FormImportOptions extends WriteOptions {\n  /** Default `'same'`. A page a widget is on or points at that maps nowhere refuses the import. */\n  readonly pages?: BundleImportPages;\n  /**\n   * `'restore'` (the default) writes who created and filled each field as\n   * the bundle has them, and the session as `importedBy`; it needs\n   * `doc.forms.import`. `'stamp'` makes the fields the session's, as\n   * `create` does.\n   */\n  readonly attribution?: 'restore' | 'stamp';\n  /** Whether each field gets the value the bundle holds. Default `true`. */\n  readonly values?: boolean;\n}\n\n/**\n * How to fill a form again from a bundle (`doc.forms.importValues`): each\n * field the bundle holds a value for, by its full name.\n */\nexport interface FormValuesImportOptions extends WriteOptions {\n  /**\n   * `'restore'` (the default) writes who filled each field as the bundle\n   * has it, and needs `doc.forms.import`; `'stamp'` makes the session the\n   * filler, as `setValue` does.\n   */\n  readonly attribution?: 'restore' | 'stamp';\n}\n\n/**\n * An import as it travels to a server: the bundle without its bytes (each\n * resource is a part of its own) and the options, apart from the `opId`,\n * which is the request's `Idempotency-Key`.\n */\nexport interface FormImportBody {\n  readonly bundle: Omit<FormBundle, 'resources'>;\n  readonly options: Omit<FormImportOptions, 'opId'>;\n}\n\n/** A values import as it travels to a server (see {@link FormImportBody}). */\nexport interface FormValuesImportBody {\n  readonly bundle: Omit<FormBundle, 'resources'>;\n  readonly options: Omit<FormValuesImportOptions, 'opId'>;\n}\n\n/** Why a design import left a field, a widget, or one of their actions out. */\nexport type FormImportDropReason =\n  /** Its full name is a field's of the document already, or an earlier one's of the bundle. */\n  | 'name-conflict'\n  /** A widget whose field isn't in the bundle. */\n  | 'no-field'\n  /** A field of a family the engine doesn't model (`family: 'unknown'`). */\n  | 'unsupported-family'\n  /** A script, submit or link, and the session lacks `doc.forms.script`. */\n  | 'script-not-allowed'\n  /** Actions a write can't make, or that were read incomplete. */\n  | 'unsupported-action';\n\nexport interface FormImportDrop {\n  /** The field, as the bundle names it; for a widget in no field of the bundle, the field it names. */\n  readonly ref: FormFieldRef | null;\n  /** Set when a widget, or one of its actions, was left out. */\n  readonly widget?: AnnotationRef;\n  /** Set when only this member was left out, as `actions.calculate`: the rest was imported. */\n  readonly field?: string;\n  readonly reason: FormImportDropReason;\n}\n\n/** Why a values import left a field's value out. */\nexport type FormValuesImportDropReason =\n  /** The document has no field of that full name. */\n  | 'no-field'\n  /** The document's field of that name is of another family. */\n  | 'wrong-family'\n  /** The field can't take the value: an option it doesn't have, a button it lacks. */\n  | 'value-not-allowed'\n  /** A signature locked the field. */\n  | 'locked'\n  /** The session may not fill the field in: its group is one the session's scopes don't reach. */\n  | 'fill-not-allowed';\n\nexport interface FormValuesImportDrop {\n  /** The field, as the bundle names it. */\n  readonly ref: FormFieldRef;\n  readonly reason: FormValuesImportDropReason;\n}\n\nexport interface FormImportResult<C extends Coordinates = PageCoordinates> {\n  /** The fields the import made, in bundle order, each as it is now. */\n  fields: FormFieldDTO<C>[];\n  /** Their widgets' rows. */\n  widgets: WidgetAnnotation<C>[];\n  /** Each imported field's ref in the bundle, and its ref in this document. */\n  refMap: Array<{ from: FormFieldRef; to: FormFieldRef }>;\n  /** What was left out, in bundle order. */\n  dropped: FormImportDrop[];\n  /** The form's whole calculation order, when the import changed it. */\n  calculationOrder?: FormFieldRef[];\n  meta: FormMutationMeta;\n}\n\nexport interface FormValuesImportResult<C extends Coordinates = PageCoordinates> {\n  /** The fields whose value changed, in bundle order, each as it is now. */\n  fields: FormFieldDTO<C>[];\n  /** The rows of the widgets whose look changed. */\n  widgets: WidgetAnnotation<C>[];\n  /** What was left out, in bundle order. */\n  dropped: FormValuesImportDrop[];\n  meta: FormMutationMeta;\n}\n\n/** The flags a widget row has, which a copy keeps. */\nexport const WIDGET_FLAG_NAMES = [\n  'invisible',\n  'hidden',\n  'print',\n  'noZoom',\n  'noRotate',\n  'noView',\n  'readOnly',\n  'locked',\n  'toggleNoView',\n  'lockedContents',\n] as const;\n\n/** A widget's flags, as its row has them. */\nexport type WidgetFlags = Pick<WidgetPatch, (typeof WIDGET_FLAG_NAMES)[number]>;\n\n/**\n * The facts a design import committed: one `forms.created` per field, in\n * bundle order, each with its own widgets and the part of the meta that is\n * its own. The calculation order, when the import changed it, rides on the\n * last.\n */\nexport function formImportFacts<C extends Coordinates>(\n  result: FormImportResult<C>,\n): FormFieldCreateResult<C>[] {\n  const last = result.fields.length - 1;\n  return result.fields.map((field, index) => {\n    const own = new Set(field.widgets.map((widget) => widget.objectNumber));\n    const widgets = result.widgets.filter(\n      (row) => row.ref.kind === 'objectNumber' && own.has(row.ref.objectNumber),\n    );\n    const changedWidgets = result.meta.changedWidgets.filter((widget) =>\n      own.has(widget.objectNumber),\n    );\n    const pages = new Set(\n      changedWidgets.flatMap((widget) => (widget.page ? [widget.page.objectNumber] : [])),\n    );\n    return {\n      field,\n      widgets,\n      ...(index === last && result.calculationOrder\n        ? { calculationOrder: result.calculationOrder }\n        : {}),\n      meta: {\n        affectedPages: result.meta.affectedPages.filter((page) => pages.has(page.objectNumber)),\n        cacheDelta: index === last ? result.meta.cacheDelta : null,\n        opId: result.meta.opId,\n        undoable: result.meta.undoable,\n        changedFields: [field.ref],\n        changedWidgets,\n        redrawnWidgets: result.meta.redrawnWidgets.filter((widget) => own.has(widget.objectNumber)),\n      },\n    };\n  });\n}\n\n/** The facts a values import committed: one `forms.valueSet` per field it filled, as a reset's. */\nexport function formValuesImportFacts<C extends Coordinates>(\n  result: FormValuesImportResult<C>,\n): FormSetValueResult<C>[] {\n  return formResetFacts(result);\n}\n","import type { FormFieldDTO } from './field';\nimport type { Coordinates } from '../pageSpace/coordinates';\n\n/**\n * A value to write to one field, in the fields a read of it returns:\n *\n * - `{ value }`: a text field's text; a radio group's or a checkbox's\n *   choice, by the export value of the widget to check (`'Off'` or `null`\n *   clears it); a dropdown's option value (or free text when it allows\n *   editing; `null` clears it). `null` empties a text field.\n * - `{ checked }`: a checkbox. `true` checks its first widget.\n * - `{ selectedValues }`: a list's option values; `[]` clears it.\n *\n * A shape the field's family doesn't take fails with `InvalidArg`.\n */\nexport type FormFieldValue =\n  | { value: string | null }\n  | { checked: boolean }\n  | { selectedValues: string[] };\n\n/**\n * The value `field` holds, as a value write takes it: writing it to the\n * same field changes nothing. `null` for a field whose value a write can't\n * set (a push button, a signature, a family the engine doesn't know).\n */\nexport function fieldValueOf(field: FormFieldDTO<Coordinates>): FormFieldValue | null {\n  switch (field.family) {\n    case 'checkbox':\n      return { checked: field.checked };\n    case 'listbox':\n      return { selectedValues: field.selectedValues };\n    case 'radio':\n      return { value: field.value === 'Off' ? null : field.value };\n    case 'text':\n    case 'combobox':\n      return { value: field.value };\n    default:\n      return null;\n  }\n}\n"],"mappings":";;;;;;AA0DA,MAAa,yBAAyB,QAAiC;CACrE,MAAM,OAAO,OAAwB,MAAO,KAAM,IAAI,OAAS;CAC/D,MAAM,SAAS,IAAI,CAAC,IAAI,QAAQ,IAAI,CAAC,IAAI,SAAS,IAAI,CAAC,IAAI,SAAS;CACpE,OAAO;EACL;EACA,SAAS,IAAI,CAAC;EACd,sBAAsB,IAAI,CAAC;EAC3B;EACA,QAAQ,IAAI,CAAC,MAAM,WAAW,UAAU,WAAW,SAAS,QAAQ;EACpE,mBAAmB,IAAI,CAAC;EACxB,oBAAoB,IAAI,CAAC;EACzB,oBAAoB,IAAI,CAAC;EACzB,iBAAiB,IAAI,EAAE;EACvB,mBAAmB,IAAI,EAAE;EACzB,UAAU,IAAI,EAAE;EAChB,WAAW,IAAI,EAAE;CACnB;AACF;;;;;;AAkPA,SAAgB,iBAAiB,QAA0C;CACzE,OACE,OAAO,SAAS,gBAChB,OAAO,SAAS,iBAChB,OAAO,SAAS,UACf,OAAO,QAAQ,CAAC,EAAA,CAAG,KAAK,gBAAgB;AAE7C;;;;;;;AAQA,SAAgB,cACd,SAMS;CACT,OAAO,OAAO,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC,MACjC,WACC,UAAU,QAAQ,EAAE,UAAU,WAAW,iBAAiB,MAAM,CACpE;AACF;;;;;;AAOA,SAAgB,cACd,MACoC;CACpC,IAAI,KAAK,cAAc,CAAC,KAAK,MAAM,OAAO;CAC1C,OAAO,YAAY,KAAK,IAAI;AAC9B;;;;;;AAOA,SAAgB,gBACd,SACiC;CACjC,MAAM,QAAyC,CAAC;CAChD,KAAK,MAAM,SAAS,sBAAsB;EACxC,MAAM,OAAO,UAAU;EACvB,IAAI,CAAC,MAAM;GACT,MAAM,SAAS;GACf;EACF;EACA,MAAM,QAAQ,cAAc,IAAI;EAChC,IAAI,OAAO,MAAM,SAAS;CAC5B;CACA,OAAO;AACT;;AAGA,MAAa,uBAAuB;CAClC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF;;AAGA,SAAgB,cAAc,MAAuD;CACnF,MAAM,QAAQ,cAAc,IAAI;CAChC,OAAO,SAAS,cAAc,KAAK,IAAI,QAAQ;AACjD;;AAGA,SAAgB,cAAc,QAA6D;CACzF,OAAO,OAAO,SAAS,iBAAiB,OAAO,QAAQ,CAAC,EAAA,CAAG,MAAM,aAAa;AAChF;AAEA,SAAS,YACP,MACoC;CACpC,MAAM,OAAsC,CAAC;CAC7C,KAAK,MAAM,SAAS,KAAK,MAAM;EAC7B,MAAM,QAAQ,YAAY,KAAK;EAC/B,IAAI,CAAC,OAAO,OAAO;EACnB,KAAK,KAAK,KAAK;CACjB;CACA,MAAM,OAAO,KAAK,SAAS,IAAI,EAAE,KAAK,IAAI,CAAC;CAC3C,QAAQ,KAAK,MAAb;EACE,KAAK,cACH,OAAO;GAAE,MAAM;GAAc,QAAQ,KAAK;GAAQ,GAAG;EAAK;EAC5D,KAAK,QACH,OAAO;GAAE,MAAM;GAAQ,aAAa,KAAK;GAAa,GAAG;EAAK;EAChE,KAAK,OACH,OAAO;GAAE,MAAM;GAAO,KAAK,KAAK;GAAK,GAAG;EAAK;EAC/C,KAAK,SACH,OAAO;GAAE,MAAM;GAAS,MAAM,KAAK;GAAM,GAAG;EAAK;EACnD,KAAK,QACH,OAAO;GAAE,MAAM;GAAQ,SAAS,KAAK;GAAS,MAAM,KAAK;GAAM,GAAG;EAAK;EACzE,KAAK,cACH,OAAO;GAAE,MAAM;GAAc,QAAQ,KAAK;GAAQ,SAAS,KAAK;GAAS,GAAG;EAAK;EACnF,KAAK,eACH,OAAO,KAAK,UACR;GACE,MAAM;GACN,KAAK,KAAK,QAAQ;GAClB,QAAQ,KAAK,QAAQ;GACrB,OAAO,KAAK,QAAQ,MAAM;GAC1B,GAAG;EACL,IACA;EACN,SACE,OAAO;CACX;AACF;;;;;;;;;;;;ACxZA,SAAgB,iBACd,UACA,WACA,OACmB;CACnB,MAAM,yBAAS,IAAI,IAAqB;CACxC,KAAK,MAAM,OAAO,UAAU,UAAU,CAAC,GAAG;EACxC,MAAM,QAAQ,SAAS,OAAO,MAAM,cAAc,aAAa,WAAW,GAAG,CAAC;EAC9E,IAAI,CAAC,OACH,MAAM,IAAI,YACR,gBAAgB,UAChB,iCAAiC,IAAI,SAAS,QAAQ,IAAI,OAAO,kBAAkB,GAAG,GACxF;EAEF,OAAO,IAAI,KAAK;CAClB;CACA,MAAM,aAAa,IAAI,IAAI,MAAM,IAAI,aAAa,CAAC;CACnD,MAAM,gCAAgB,IAAI,IAAY;CACtC,KAAK,MAAM,QAAQ,UAAU,SAAS,CAAC,GAAG;EACxC,IAAI,CAAC,WAAW,IAAI,cAAc,IAAI,CAAC,GACrC,MAAM,IAAI,YACR,gBAAgB,UAChB,oCAAoC,cAAc,IAAI,GACxD;EAEF,cAAc,IAAI,cAAc,IAAI,CAAC;CACvC;CACA,KAAK,MAAM,SAAS,SAAS,QAC3B,IACE,MAAM,QAAQ,MAAM,WAAW,OAAO,QAAQ,cAAc,IAAI,cAAc,OAAO,IAAI,CAAC,CAAC,GAE3F,OAAO,IAAI,KAAK;CAGpB,MAAM,aAAa,CAAC,UAAU,UAAU,CAAC,UAAU;CACnD,MAAM,SAAS,SAAS,OAAO,QAAQ,UAAU,cAAc,OAAO,IAAI,KAAK,CAAC;CAEhF,MAAM,WAAW,IAAI,IAAI,SAAS,QAAQ,KAAK,QAAQ,CAAC,cAAc,IAAI,GAAG,GAAG,GAAG,CAAC,CAAC;CACrF,MAAM,UAAU,OAAO,SAAS,UAC9B,MAAM,QAAQ,SAAS,WAAW;EAChC,MAAM,MAAM,OAAO,MAAM,SAAS,IAAI,cAAc,OAAO,GAAG,CAAC,IAAI,KAAA;EACnE,OAAO,MAAM,CAAC,GAAG,IAAI,CAAC;CACxB,CAAC,CACH;CACA,MAAM,WAAW,IAAI,IAAI,OAAO,KAAK,UAAU,kBAAkB,MAAM,GAAG,CAAC,CAAC;CAC5E,MAAM,mBAAmB,SAAS,iBAAiB,QAChD,QAA6B,QAAQ,QAAQ,SAAS,IAAI,kBAAkB,GAAG,CAAC,CACnF;CACA,OAAO;EAAE,QAAQ,OAAO,IAAI,aAAa;EAAG;EAAS;CAAiB;AACxE;;AAGA,SAAgB,aACd,OACA,KACS;CACT,OAAO,IAAI,SAAS,QAChB,MAAM,SAAS,IAAI,OACnB,MAAM,IAAI,SAAS,kBAAkB,MAAM,IAAI,iBAAiB,IAAI;AAC1E;;;;;AAMA,SAAS,cAAqC,OAAyC;CACrF,IAAI,MAAM,WAAW,aAAa,OAAO;EAAE,GAAG;EAAO,YAAY,EAAE,MAAM,OAAO;CAAE;CAClF,IAAI,CAAC,MAAM,UAAU,OAAO;CAC5B,MAAM,WAAW;EACf,GAAG;EACH,YAAY,EAAE,MAAM,OAAO;EAC3B,UAAU;EACV,cAAc;EACd,UAAU;CACZ;CACA,QAAQ,MAAM,QAAd;EACE,KAAK;EACL,KAAK,YACH,OAAO;GAAE,GAAG;GAAU,QAAQ,MAAM;GAAQ,OAAO;EAAG;EACxD,KAAK,YACH,OAAO;GACL,GAAG;GACH,QAAQ;GACR,SAAS;GACT,SAAS,MAAM,QAAQ,KAAK,YAAY;IAAE,GAAG;IAAQ,SAAS;GAAM,EAAE;EACxE;EACF,KAAK,SACH,OAAO;GACL,GAAG;GACH,QAAQ;GACR,OAAO;GACP,SAAS,MAAM,QAAQ,KAAK,YAAY;IAAE,GAAG;IAAQ,SAAS;GAAM,EAAE;EACxE;EACF,KAAK,WACH,OAAO;GACL,GAAG;GACH,QAAQ;GACR,gBAAgB,CAAC;GACjB,SAAS,MAAM,QAAQ,KAAK,YAAY;IAAE,GAAG;IAAQ,UAAU;GAAM,EAAE;EACzE;EACF,SACE,OAAO;CACX;AACF;;;;;;;AC1EA,SAAgB,eACd,QACyB;CACzB,OAAO,OAAO,OAAO,KAAK,UAAU;EAClC,MAAM,MAAM,IAAI,IAAI,MAAM,QAAQ,KAAK,WAAW,OAAO,YAAY,CAAC;EACtE,MAAM,iBAAiB,OAAO,KAAK,eAAe,QAAQ,WACxD,IAAI,IAAI,OAAO,YAAY,CAC7B;EACA,MAAM,UAAU,OAAO,QAAQ,QAC5B,WAAW,OAAO,IAAI,SAAS,kBAAkB,IAAI,IAAI,OAAO,IAAI,YAAY,CACnF;EACA,MAAM,QAAQ,IAAI,IAChB,eAAe,SAAS,WAAY,OAAO,OAAO,CAAC,OAAO,KAAK,YAAY,IAAI,CAAC,CAAE,CACpF;EACA,OAAO;GACL;GACA;GACA,MAAM;IACJ,eAAe,OAAO,KAAK,cAAc,QAAQ,SAAS,MAAM,IAAI,KAAK,YAAY,CAAC;IACtF,YAAY;IACZ,MAAM,OAAO,KAAK;IAClB,UAAU,OAAO,KAAK;IACtB,eAAe,CAAC,MAAM,GAAG;IACzB;IACA,gBAAgB,OAAO,KAAK,eAAe,QAAQ,WAAW,IAAI,IAAI,OAAO,YAAY,CAAC;GAC5F;EACF;CACF,CAAC;AACH;;AAkEA,SAAgB,eAAe,QAAoD;CACjF,OAAO,OAAO,KAAK,cAAc,MAAM;AACzC;;;;AC5BA,MAAa,oBAAoB;CAC/B;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF;;;;;;;AAWA,SAAgB,gBACd,QAC4B;CAC5B,MAAM,OAAO,OAAO,OAAO,SAAS;CACpC,OAAO,OAAO,OAAO,KAAK,OAAO,UAAU;EACzC,MAAM,MAAM,IAAI,IAAI,MAAM,QAAQ,KAAK,WAAW,OAAO,YAAY,CAAC;EACtE,MAAM,UAAU,OAAO,QAAQ,QAC5B,QAAQ,IAAI,IAAI,SAAS,kBAAkB,IAAI,IAAI,IAAI,IAAI,YAAY,CAC1E;EACA,MAAM,iBAAiB,OAAO,KAAK,eAAe,QAAQ,WACxD,IAAI,IAAI,OAAO,YAAY,CAC7B;EACA,MAAM,QAAQ,IAAI,IAChB,eAAe,SAAS,WAAY,OAAO,OAAO,CAAC,OAAO,KAAK,YAAY,IAAI,CAAC,CAAE,CACpF;EACA,OAAO;GACL;GACA;GACA,GAAI,UAAU,QAAQ,OAAO,mBACzB,EAAE,kBAAkB,OAAO,iBAAiB,IAC5C,CAAC;GACL,MAAM;IACJ,eAAe,OAAO,KAAK,cAAc,QAAQ,SAAS,MAAM,IAAI,KAAK,YAAY,CAAC;IACtF,YAAY,UAAU,OAAO,OAAO,KAAK,aAAa;IACtD,MAAM,OAAO,KAAK;IAClB,UAAU,OAAO,KAAK;IACtB,eAAe,CAAC,MAAM,GAAG;IACzB;IACA,gBAAgB,OAAO,KAAK,eAAe,QAAQ,WAAW,IAAI,IAAI,OAAO,YAAY,CAAC;GAC5F;EACF;CACF,CAAC;AACH;;AAGA,SAAgB,sBACd,QACyB;CACzB,OAAO,eAAe,MAAM;AAC9B;;;;;;;;ACtKA,SAAgB,aAAa,OAAyD;CACpF,QAAQ,MAAM,QAAd;EACE,KAAK,YACH,OAAO,EAAE,SAAS,MAAM,QAAQ;EAClC,KAAK,WACH,OAAO,EAAE,gBAAgB,MAAM,eAAe;EAChD,KAAK,SACH,OAAO,EAAE,OAAO,MAAM,UAAU,QAAQ,OAAO,MAAM,MAAM;EAC7D,KAAK;EACL,KAAK,YACH,OAAO,EAAE,OAAO,MAAM,MAAM;EAC9B,SACE,OAAO;CACX;AACF"}