@embedpdf/plugin-form 2.15.0 → 3.0.0-next.0

package/dist/index.d.cts

@@ -0,0 +1,277 @@
+import { AnnotationRef, DocumentHandle, FormDataExport, FormDataFormat, FormEffectsResult, FormFieldDTO, FormFieldDTO as FormFieldDTO$1, FormFieldFamily, FormFieldOption, FormFieldPatch, FormFieldPatch as FormFieldPatch$1, FormFieldRef, FormFieldValue, FormImportResult, FormRepairOptions, FormRepairResult, FormSetValueResult, FormSnapshot, PdfActionTree, WidgetAppearance, WidgetAppearance as WidgetAppearance$1 } from "@embedpdf/engine-core/runtime";
+import { ScriptBudget, ScriptDiagnostic, ScriptExecutionError, ScriptIdentity, ScriptUiEffect } from "@embedpdf/core-acrojs";
+import { ScriptSandboxFactory } from "@embedpdf/core-js-sandbox";
+import { DocumentMeta } from "@embedpdf/core";
+import { AnnotationPropsPatch, ClickCreate } from "@embedpdf/plugin-annotation";
+//#region src/core/model.d.ts
+/** A content-space box (top-left origin, y-down, PDF points). */
+interface Box {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+/** Stable client key for a field: object number when durable, else FQN. */
+type FieldKey = string;
+declare const fieldKeyOf: (field: {
+  fieldObjectNumber: number;
+  name: string;
+}) => FieldKey;
+interface Model {
+  /** Engine truth; replaced wholesale on refresh, patched on write-backs. */
+  snapshot: FormSnapshot | null;
+  /** fieldKey → index into snapshot.fields. */
+  byKey: Record<FieldKey, number>;
+  /** annotObjectNumber → index into snapshot.fields (widget → field join). */
+  byWidget: Record<number, number>;
+  /** Fields with an in-flight engine write (disables their controls). */
+  writing: Record<FieldKey, true>;
+  /**
+   * Widget geometry per page: annotObjectNumber → content-space box. Fed by
+   * the shell from the WIDGET plane (one annotations read per page); value
+   * writes never move widgets, so this survives snapshot refreshes and is
+   * only cleared on structural form events.
+   */
+  geom: Record<number, Record<number, Box> | undefined>;
+  /** Bumped on every change — cheap equality for memoized projections. */
+  seq: number;
+}
+//#endregion
+//#region src/core/fill-items.d.ts
+interface FillItemBase {
+  key: FieldKey;
+  /** Widget identity — joins to the annotation plane. */
+  annotObjectNumber: number;
+  box: Box;
+  /** Read-only field or write in flight: render, don't accept input. */
+  disabled: boolean;
+  /** Accessible name: /TU when present, else the fully qualified name. */
+  label: string;
+}
+type FillItem = FillItemBase & ({
+  control: 'text';
+  value: string;
+  multiline: boolean;
+  password: boolean;
+  maxLength: number | null;
+  comb: boolean;
+} | {
+  control: 'toggle';
+  kind: 'checkbox' | 'radio';
+  checked: boolean;
+  onState: string;
+} | {
+  control: 'choice';
+  kind: 'combo' | 'list';
+  edit: boolean;
+  multi: boolean;
+  options: FormFieldOption[];
+  selected: string[];
+} | {
+  control: 'button';
+});
+//#endregion
+//#region src/types.d.ts
+interface FormState {
+  model: Model;
+}
+interface FormScriptingOptions {
+  /** Explicit opt-in. PDF JavaScript remains inert when false/omitted. */
+  enabled: boolean;
+  /** Override the lazy QuickJS factory (tests or another isolated VM). */
+  sandboxFactory?: ScriptSandboxFactory;
+  /** Optional embedder identity fields layered over engine/JWT identity. */
+  identity?: Partial<ScriptIdentity> | (() => Partial<ScriptIdentity>);
+  /** Target document filename exposed as `this.documentFileName`. */
+  fileName?: () => string;
+  /** Injected deterministic transaction environment. */
+  now?: () => number;
+  utcOffsetMinutes?: () => number;
+  randomSeed?: () => number;
+  budget?: ScriptBudget;
+  /** Framework/application port for app.alert, print, and page navigation. */
+  onUiEffect?: (effect: ScriptUiEffect) => void;
+  onDiagnostic?: (diagnostic: ScriptDiagnostic) => void;
+  onError?: (error: ScriptExecutionError) => void;
+}
+interface FormPluginOptions {
+  scripting?: FormScriptingOptions;
+}
+type FormCommitStatus = 'applied' | 'unchanged' | 'rejected' | 'failed';
+interface FormCommitResult {
+  status: FormCommitStatus;
+  scripted: boolean;
+  effectsResult: FormEffectsResult | null;
+  uiEffects: FormUiEffect[];
+  diagnostics: ScriptDiagnostic[];
+  error?: ScriptExecutionError;
+}
+/**
+ * One DOM-free UI request produced by the curated Acrobat scripting surface.
+ * `phase` says WHO asked: `'boot'` = a document-open script (Adobe's
+ * version-check boilerplate lives here — embedders typically suppress these
+ * nags), `'user'` = a script triggered by the user's own interaction (a
+ * validation alert — show it).
+ */
+type FormUiEffect = ScriptUiEffect & {
+  phase: 'boot' | 'user';
+};
+/** Runtime adapter for alerts, print requests, and zero-based page navigation. */
+type FormUiEffectProvider = (effect: FormUiEffect) => void;
+/** Input for {@link FormCapability.placeField}. */
+interface PlaceFieldInput {
+  family: Exclude<FormFieldFamily, 'pushbutton' | 'signature' | 'unknown'>;
+  pageObjectNumber: number;
+  /** Content-space LOGICAL field box (no visual padding semantics). */
+  box: Box;
+  /** Widget styling in the engine vocabulary (`WidgetAppearance`). Convert a
+   *  tool's flat CSS defaults with `widgetAppearanceFromProps` from
+   *  `@embedpdf/plugin-annotation`. Omitted → the engine's bare defaults. */
+  appearance?: WidgetAppearance$1;
+}
+/** What {@link FormCapability.placeField} created. */
+interface PlacedField {
+  field: FormFieldDTO$1;
+  /** The widget placed on the requested page (join key to the annotation
+   *  plane for auto-selection), or null when the engine reported none. */
+  widget: FormFieldDTO$1['widgets'][number] | null;
+}
+type FormAction = {
+  type: 'SET_MODEL';
+  model: Model;
+};
+/**
+ * The form plugin's public capability: the FIELD plane. Widgets stay
+ * annotations (geometry/appearance live there); this surface owns values,
+ * interchange, and the fill-mode projection.
+ */
+interface FormCapability {
+  /** The current reconciled form state (null until the first load lands). */
+  snapshot(): FormSnapshot | null;
+  /** Re-read the form from the engine (imports/repair/remote bursts). */
+  refresh(): Promise<void>;
+  /** Fill controls for one page — content-space, framework-agnostic. */
+  fillItems(pageObjectNumber: number): FillItem[];
+  /**
+   * The fill control for ONE widget, by annotation object number — the join
+   * the annotation-plane render layer uses (its RenderItem carries the live
+   * box, so this item's `box` is advisory). Reference-stable per model change.
+   * Null until the snapshot lands, or for families with no fill control.
+   */
+  fillItem(annotObjectNumber: number): FillItem | null;
+  /** Make sure a page's widget geometry is loaded (idempotent, lazy). */
+  ensureGeom(pageObjectNumber: number): void;
+  field(key: FieldKey): FormFieldDTO$1 | null;
+  fieldForWidget(annotObjectNumber: number): FormFieldDTO$1 | null;
+  /** Commit a text value (call on blur/Enter — keystrokes stay local). */
+  setText(key: FieldKey, value: string): Promise<void>;
+  /** Toggle a checkbox/radio widget by its on-state; null clears the group. */
+  toggle(key: FieldKey, onState: string | null): Promise<void>;
+  /** Select choice options by export value. */
+  choose(key: FieldKey, values: string[]): Promise<void>;
+  /** Commit one originating-client value transaction, including K/V/C/F scripts when enabled. */
+  commitValue(ref: FormFieldRef, value: FormFieldValue): Promise<FormCommitResult>;
+  /** Execute one widget's `/A` activation action (and `/Next`) when scripting is enabled. */
+  activateWidget(key: FieldKey, annotationRef: AnnotationRef): Promise<FormCommitResult>;
+  /** Install the framework/application adapter for script-produced UI requests. */
+  setUiEffectProvider(provider: FormUiEffectProvider | null): void;
+  /** Restore a field to its /DV default. */
+  reset(key: FieldKey): Promise<void>;
+  /** Raw engine passthrough for anything the sugar above doesn't cover. */
+  setValue(ref: FormFieldRef, value: FormFieldValue): Promise<FormSetValueResult>;
+  exportData(format?: FormDataFormat): Promise<FormDataExport>;
+  importData(data: Uint8Array | ArrayBuffer, format?: FormDataFormat): Promise<FormImportResult>;
+  repair(options?: FormRepairOptions): Promise<FormRepairResult>;
+  /**
+   * Create a field of `family` with one styled widget at a content-space box
+   * — the palette tools' commit, and the programmatic authoring entry (works
+   * with NO annotation plugin: a pure `doc.forms` call). The box is clamped
+   * to the page; sizing policy (click default vs drag rect) is the caller's.
+   * The field gets a deterministic auto-name (`text_1`, …; rename in the
+   * field panel). Resolves AFTER the annotation plane (when present) has
+   * re-read the page, so the returned widget is immediately selectable.
+   */
+  placeField(input: PlaceFieldInput): Promise<PlacedField>;
+  /** The page's content box (`{0,0,w,h}`) — page-bound placement math. */
+  pageBox(pageObjectNumber: number): Box | null;
+  /** Field-plane properties: name, required, options, default value. */
+  updateField(key: FieldKey, patch: FormFieldPatch$1): Promise<void>;
+  /** Delete the field and every widget of it (cascades on the page). */
+  deleteField(key: FieldKey): Promise<void>;
+  /** Unlink one widget: it stays as an inert annotation, the field survives. */
+  detachWidget(key: FieldKey, annotObjectNumber: number): Promise<void>;
+  /** UI mirror of the engine gates (`doc.forms.fill` / `doc.forms.modify`). */
+  canFill(): boolean;
+  canModify(): boolean;
+}
+declare const FormToken: import("@embedpdf/core").CapabilityToken<FormCapability>;
+//#endregion
+//#region src/form.plugin.d.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.
+ */
+declare const formPlugin: (options?: FormPluginOptions) => import("@embedpdf/core").PluginDef<FormState, FormAction, FormCapability>;
+//#endregion
+//#region src/scripting.d.ts
+interface FormScriptingControllerOptions {
+  doc: DocumentHandle;
+  document(): DocumentMeta | null;
+  config: FormScriptingOptions;
+  sandboxFactory: ScriptSandboxFactory;
+}
+declare class FormScriptingController {
+  private readonly options;
+  private sandboxPromise;
+  private booted;
+  private disposed;
+  private sequence;
+  constructor(options: FormScriptingControllerOptions);
+  dispose(): void;
+  commit(snapshot: FormSnapshot, ref: FormFieldRef, proposed: FormFieldValue): Promise<FormCommitResult>;
+  /** Execute one originating widget's activation action (`/A`, including `/Next`). */
+  activate(snapshot: FormSnapshot, ref: FormFieldRef, action: PdfActionTree): Promise<FormCommitResult>;
+  /** Run lazy document boot plus the `/CO` chain without a user field change. */
+  recalculate(snapshot: FormSnapshot): Promise<FormCommitResult>;
+  private transact;
+  private sandbox;
+  private failed;
+  private finishRejected;
+}
+declare function createFormScriptingController(options: FormScriptingControllerOptions): FormScriptingController;
+//#endregion
+//#region src/mutationQueue.d.ts
+/** Small promise-tail queue: failures never poison later mutations. */
+declare function createSerialMutationQueue(): <T>(operation: () => Promise<T>) => Promise<T>;
+//#endregion
+//#region src/tools.d.ts
+/** The families the palette can author (no pushbutton/signature tools). */
+type AuthorableFormFamily = Exclude<FormFieldFamily, 'pushbutton' | 'signature' | 'unknown'>;
+interface FormToolDef {
+  id: string;
+  /** The field family `placeField` commits (the FORM plane's vocabulary). */
+  family: AuthorableFormFamily;
+  /** The client kind the ANNOTATION registry routes on (props panel).
+   *  Not a PDF subtype — every widget is PDF `widget`; this is the view. */
+  visualKind: 'widget-text' | 'widget-choice' | 'widget-toggle';
+  /** What a bare click places (box policies only — fields are boxes). */
+  clickCreate: Extract<ClickCreate, {
+    width: number;
+  }>;
+  /** Seed drawing defaults: a placed field is VISIBLE (white box, gray
+   *  border) and restylable per tool through the shared style panel. */
+  defaults: AnnotationPropsPatch;
+  cursor: string;
+}
+declare const FORM_TOOLS: readonly FormToolDef[];
+declare const FORM_TOOL_BY_ID: ReadonlyMap<string, FormToolDef>;
+//#endregion
+export { type AuthorableFormFamily, type Box, FORM_TOOLS, FORM_TOOL_BY_ID, type FieldKey, type FillItem, type FormAction, type FormCapability, type FormCommitResult, type FormCommitStatus, type FormFieldDTO, type FormFieldPatch, type FormPluginOptions, FormScriptingController, type FormScriptingOptions, type FormState, FormToken, type FormToolDef, type FormUiEffect, type FormUiEffectProvider, type PlaceFieldInput, type PlacedField, type WidgetAppearance, createFormScriptingController, createSerialMutationQueue, fieldKeyOf, formPlugin };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -1 +1,277 @@
-export * from './lib';
+import { DocumentMeta } from "@embedpdf/core";
+import { AnnotationPropsPatch, ClickCreate } from "@embedpdf/plugin-annotation";
+import { ScriptBudget, ScriptDiagnostic, ScriptExecutionError, ScriptIdentity, ScriptUiEffect } from "@embedpdf/core-acrojs";
+import { AnnotationRef, DocumentHandle, FormDataExport, FormDataFormat, FormEffectsResult, FormFieldDTO, FormFieldDTO as FormFieldDTO$1, FormFieldFamily, FormFieldOption, FormFieldPatch, FormFieldPatch as FormFieldPatch$1, FormFieldRef, FormFieldValue, FormImportResult, FormRepairOptions, FormRepairResult, FormSetValueResult, FormSnapshot, PdfActionTree, WidgetAppearance, WidgetAppearance as WidgetAppearance$1 } from "@embedpdf/engine-core/runtime";
+import { ScriptSandboxFactory } from "@embedpdf/core-js-sandbox";
+//#region src/core/model.d.ts
+/** A content-space box (top-left origin, y-down, PDF points). */
+interface Box {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+/** Stable client key for a field: object number when durable, else FQN. */
+type FieldKey = string;
+declare const fieldKeyOf: (field: {
+  fieldObjectNumber: number;
+  name: string;
+}) => FieldKey;
+interface Model {
+  /** Engine truth; replaced wholesale on refresh, patched on write-backs. */
+  snapshot: FormSnapshot | null;
+  /** fieldKey → index into snapshot.fields. */
+  byKey: Record<FieldKey, number>;
+  /** annotObjectNumber → index into snapshot.fields (widget → field join). */
+  byWidget: Record<number, number>;
+  /** Fields with an in-flight engine write (disables their controls). */
+  writing: Record<FieldKey, true>;
+  /**
+   * Widget geometry per page: annotObjectNumber → content-space box. Fed by
+   * the shell from the WIDGET plane (one annotations read per page); value
+   * writes never move widgets, so this survives snapshot refreshes and is
+   * only cleared on structural form events.
+   */
+  geom: Record<number, Record<number, Box> | undefined>;
+  /** Bumped on every change — cheap equality for memoized projections. */
+  seq: number;
+}
+//#endregion
+//#region src/core/fill-items.d.ts
+interface FillItemBase {
+  key: FieldKey;
+  /** Widget identity — joins to the annotation plane. */
+  annotObjectNumber: number;
+  box: Box;
+  /** Read-only field or write in flight: render, don't accept input. */
+  disabled: boolean;
+  /** Accessible name: /TU when present, else the fully qualified name. */
+  label: string;
+}
+type FillItem = FillItemBase & ({
+  control: 'text';
+  value: string;
+  multiline: boolean;
+  password: boolean;
+  maxLength: number | null;
+  comb: boolean;
+} | {
+  control: 'toggle';
+  kind: 'checkbox' | 'radio';
+  checked: boolean;
+  onState: string;
+} | {
+  control: 'choice';
+  kind: 'combo' | 'list';
+  edit: boolean;
+  multi: boolean;
+  options: FormFieldOption[];
+  selected: string[];
+} | {
+  control: 'button';
+});
+//#endregion
+//#region src/types.d.ts
+interface FormState {
+  model: Model;
+}
+interface FormScriptingOptions {
+  /** Explicit opt-in. PDF JavaScript remains inert when false/omitted. */
+  enabled: boolean;
+  /** Override the lazy QuickJS factory (tests or another isolated VM). */
+  sandboxFactory?: ScriptSandboxFactory;
+  /** Optional embedder identity fields layered over engine/JWT identity. */
+  identity?: Partial<ScriptIdentity> | (() => Partial<ScriptIdentity>);
+  /** Target document filename exposed as `this.documentFileName`. */
+  fileName?: () => string;
+  /** Injected deterministic transaction environment. */
+  now?: () => number;
+  utcOffsetMinutes?: () => number;
+  randomSeed?: () => number;
+  budget?: ScriptBudget;
+  /** Framework/application port for app.alert, print, and page navigation. */
+  onUiEffect?: (effect: ScriptUiEffect) => void;
+  onDiagnostic?: (diagnostic: ScriptDiagnostic) => void;
+  onError?: (error: ScriptExecutionError) => void;
+}
+interface FormPluginOptions {
+  scripting?: FormScriptingOptions;
+}
+type FormCommitStatus = 'applied' | 'unchanged' | 'rejected' | 'failed';
+interface FormCommitResult {
+  status: FormCommitStatus;
+  scripted: boolean;
+  effectsResult: FormEffectsResult | null;
+  uiEffects: FormUiEffect[];
+  diagnostics: ScriptDiagnostic[];
+  error?: ScriptExecutionError;
+}
+/**
+ * One DOM-free UI request produced by the curated Acrobat scripting surface.
+ * `phase` says WHO asked: `'boot'` = a document-open script (Adobe's
+ * version-check boilerplate lives here — embedders typically suppress these
+ * nags), `'user'` = a script triggered by the user's own interaction (a
+ * validation alert — show it).
+ */
+type FormUiEffect = ScriptUiEffect & {
+  phase: 'boot' | 'user';
+};
+/** Runtime adapter for alerts, print requests, and zero-based page navigation. */
+type FormUiEffectProvider = (effect: FormUiEffect) => void;
+/** Input for {@link FormCapability.placeField}. */
+interface PlaceFieldInput {
+  family: Exclude<FormFieldFamily, 'pushbutton' | 'signature' | 'unknown'>;
+  pageObjectNumber: number;
+  /** Content-space LOGICAL field box (no visual padding semantics). */
+  box: Box;
+  /** Widget styling in the engine vocabulary (`WidgetAppearance`). Convert a
+   *  tool's flat CSS defaults with `widgetAppearanceFromProps` from
+   *  `@embedpdf/plugin-annotation`. Omitted → the engine's bare defaults. */
+  appearance?: WidgetAppearance$1;
+}
+/** What {@link FormCapability.placeField} created. */
+interface PlacedField {
+  field: FormFieldDTO$1;
+  /** The widget placed on the requested page (join key to the annotation
+   *  plane for auto-selection), or null when the engine reported none. */
+  widget: FormFieldDTO$1['widgets'][number] | null;
+}
+type FormAction = {
+  type: 'SET_MODEL';
+  model: Model;
+};
+/**
+ * The form plugin's public capability: the FIELD plane. Widgets stay
+ * annotations (geometry/appearance live there); this surface owns values,
+ * interchange, and the fill-mode projection.
+ */
+interface FormCapability {
+  /** The current reconciled form state (null until the first load lands). */
+  snapshot(): FormSnapshot | null;
+  /** Re-read the form from the engine (imports/repair/remote bursts). */
+  refresh(): Promise<void>;
+  /** Fill controls for one page — content-space, framework-agnostic. */
+  fillItems(pageObjectNumber: number): FillItem[];
+  /**
+   * The fill control for ONE widget, by annotation object number — the join
+   * the annotation-plane render layer uses (its RenderItem carries the live
+   * box, so this item's `box` is advisory). Reference-stable per model change.
+   * Null until the snapshot lands, or for families with no fill control.
+   */
+  fillItem(annotObjectNumber: number): FillItem | null;
+  /** Make sure a page's widget geometry is loaded (idempotent, lazy). */
+  ensureGeom(pageObjectNumber: number): void;
+  field(key: FieldKey): FormFieldDTO$1 | null;
+  fieldForWidget(annotObjectNumber: number): FormFieldDTO$1 | null;
+  /** Commit a text value (call on blur/Enter — keystrokes stay local). */
+  setText(key: FieldKey, value: string): Promise<void>;
+  /** Toggle a checkbox/radio widget by its on-state; null clears the group. */
+  toggle(key: FieldKey, onState: string | null): Promise<void>;
+  /** Select choice options by export value. */
+  choose(key: FieldKey, values: string[]): Promise<void>;
+  /** Commit one originating-client value transaction, including K/V/C/F scripts when enabled. */
+  commitValue(ref: FormFieldRef, value: FormFieldValue): Promise<FormCommitResult>;
+  /** Execute one widget's `/A` activation action (and `/Next`) when scripting is enabled. */
+  activateWidget(key: FieldKey, annotationRef: AnnotationRef): Promise<FormCommitResult>;
+  /** Install the framework/application adapter for script-produced UI requests. */
+  setUiEffectProvider(provider: FormUiEffectProvider | null): void;
+  /** Restore a field to its /DV default. */
+  reset(key: FieldKey): Promise<void>;
+  /** Raw engine passthrough for anything the sugar above doesn't cover. */
+  setValue(ref: FormFieldRef, value: FormFieldValue): Promise<FormSetValueResult>;
+  exportData(format?: FormDataFormat): Promise<FormDataExport>;
+  importData(data: Uint8Array | ArrayBuffer, format?: FormDataFormat): Promise<FormImportResult>;
+  repair(options?: FormRepairOptions): Promise<FormRepairResult>;
+  /**
+   * Create a field of `family` with one styled widget at a content-space box
+   * — the palette tools' commit, and the programmatic authoring entry (works
+   * with NO annotation plugin: a pure `doc.forms` call). The box is clamped
+   * to the page; sizing policy (click default vs drag rect) is the caller's.
+   * The field gets a deterministic auto-name (`text_1`, …; rename in the
+   * field panel). Resolves AFTER the annotation plane (when present) has
+   * re-read the page, so the returned widget is immediately selectable.
+   */
+  placeField(input: PlaceFieldInput): Promise<PlacedField>;
+  /** The page's content box (`{0,0,w,h}`) — page-bound placement math. */
+  pageBox(pageObjectNumber: number): Box | null;
+  /** Field-plane properties: name, required, options, default value. */
+  updateField(key: FieldKey, patch: FormFieldPatch$1): Promise<void>;
+  /** Delete the field and every widget of it (cascades on the page). */
+  deleteField(key: FieldKey): Promise<void>;
+  /** Unlink one widget: it stays as an inert annotation, the field survives. */
+  detachWidget(key: FieldKey, annotObjectNumber: number): Promise<void>;
+  /** UI mirror of the engine gates (`doc.forms.fill` / `doc.forms.modify`). */
+  canFill(): boolean;
+  canModify(): boolean;
+}
+declare const FormToken: import("@embedpdf/core").CapabilityToken<FormCapability>;
+//#endregion
+//#region src/form.plugin.d.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.
+ */
+declare const formPlugin: (options?: FormPluginOptions) => import("@embedpdf/core").PluginDef<FormState, FormAction, FormCapability>;
+//#endregion
+//#region src/scripting.d.ts
+interface FormScriptingControllerOptions {
+  doc: DocumentHandle;
+  document(): DocumentMeta | null;
+  config: FormScriptingOptions;
+  sandboxFactory: ScriptSandboxFactory;
+}
+declare class FormScriptingController {
+  private readonly options;
+  private sandboxPromise;
+  private booted;
+  private disposed;
+  private sequence;
+  constructor(options: FormScriptingControllerOptions);
+  dispose(): void;
+  commit(snapshot: FormSnapshot, ref: FormFieldRef, proposed: FormFieldValue): Promise<FormCommitResult>;
+  /** Execute one originating widget's activation action (`/A`, including `/Next`). */
+  activate(snapshot: FormSnapshot, ref: FormFieldRef, action: PdfActionTree): Promise<FormCommitResult>;
+  /** Run lazy document boot plus the `/CO` chain without a user field change. */
+  recalculate(snapshot: FormSnapshot): Promise<FormCommitResult>;
+  private transact;
+  private sandbox;
+  private failed;
+  private finishRejected;
+}
+declare function createFormScriptingController(options: FormScriptingControllerOptions): FormScriptingController;
+//#endregion
+//#region src/mutationQueue.d.ts
+/** Small promise-tail queue: failures never poison later mutations. */
+declare function createSerialMutationQueue(): <T>(operation: () => Promise<T>) => Promise<T>;
+//#endregion
+//#region src/tools.d.ts
+/** The families the palette can author (no pushbutton/signature tools). */
+type AuthorableFormFamily = Exclude<FormFieldFamily, 'pushbutton' | 'signature' | 'unknown'>;
+interface FormToolDef {
+  id: string;
+  /** The field family `placeField` commits (the FORM plane's vocabulary). */
+  family: AuthorableFormFamily;
+  /** The client kind the ANNOTATION registry routes on (props panel).
+   *  Not a PDF subtype — every widget is PDF `widget`; this is the view. */
+  visualKind: 'widget-text' | 'widget-choice' | 'widget-toggle';
+  /** What a bare click places (box policies only — fields are boxes). */
+  clickCreate: Extract<ClickCreate, {
+    width: number;
+  }>;
+  /** Seed drawing defaults: a placed field is VISIBLE (white box, gray
+   *  border) and restylable per tool through the shared style panel. */
+  defaults: AnnotationPropsPatch;
+  cursor: string;
+}
+declare const FORM_TOOLS: readonly FormToolDef[];
+declare const FORM_TOOL_BY_ID: ReadonlyMap<string, FormToolDef>;
+//#endregion
+export { type AuthorableFormFamily, type Box, FORM_TOOLS, FORM_TOOL_BY_ID, type FieldKey, type FillItem, type FormAction, type FormCapability, type FormCommitResult, type FormCommitStatus, type FormFieldDTO, type FormFieldPatch, type FormPluginOptions, FormScriptingController, type FormScriptingOptions, type FormState, FormToken, type FormToolDef, type FormUiEffect, type FormUiEffectProvider, type PlaceFieldInput, type PlacedField, type WidgetAppearance, createFormScriptingController, createSerialMutationQueue, fieldKeyOf, formPlugin };
+//# sourceMappingURL=index.d.ts.map