@inkbar/core 0.7.0 → 0.8.0

package/dist/{signatures-CalOktkf.d.mts → sign-47QLNaqQ.d.mts}

@@ -76,9 +76,6 @@ interface PdfjsAnnotationData {
   name?: string;
   /** The intent (`/IT`), a PDF name. PDF.js 6.4 does not pass FreeText `/CL`, `/RD` or `/LE`. */
   it?: string;
-  borderStyle?: {
-    width: number;
-  } | null;
   lineCoordinates?: [number, number, number, number];
   vertices?: Float32Array | number[];
   inkLists?: Array<Float32Array | number[]>;
@@ -95,6 +92,55 @@ interface PdfjsAnnotationData {
   hasAppearance?: boolean;
   hidden?: boolean;
   noView?: boolean;
+  /** `/F`, the annotation flags. */
+  annotationFlags?: number;
+  fieldName?: string;
+  fieldType?: string | null;
+  fieldValue?: string | string[] | null;
+  defaultFieldValue?: string | string[] | null;
+  fieldFlags?: number;
+  checkBox?: boolean;
+  radioButton?: boolean;
+  pushButton?: boolean;
+  /** A checkbox's on value, mapped through `/Opt`. */
+  exportValue?: string | null;
+  /** A radio widget's on value, mapped through `/Opt`. */
+  buttonValue?: string | null;
+  options?: {
+    exportValue: string;
+    displayValue: string;
+  }[];
+  combo?: boolean;
+  multiSelect?: boolean;
+  multiLine?: boolean;
+  password?: boolean;
+  comb?: boolean;
+  maxLen?: number | null;
+  /** `/Q`: 0 left, 1 centre, 2 right. */
+  textAlignment?: number | null;
+  borderStyle?: {
+    width: number;
+    style?: number;
+  } | null;
+  borderColor?: Uint8ClampedArray | null;
+  backgroundColor?: Uint8ClampedArray | null;
+  /** `/TU`. */
+  alternativeText?: string;
+  /** `/MK /R`. */
+  rotation?: number;
+  /** JavaScript actions by event name; null when there are none. */
+  actions?: Map<string, string[]> | Record<string, string[]> | null;
+  resetForm?: {
+    fields: string[];
+    refs: string[];
+    include: boolean;
+  };
+  url?: string;
+  /** `app.launchURL`'s second argument, for a `url` PDF.js read out of a JavaScript `/A`. */
+  newWindow?: boolean;
+  /** A Named action's name. */
+  action?: string;
+  dest?: string | unknown[];
 }
 interface PdfAssets {
   /** URL (or file path in Node) of `pdf.worker(.min).mjs`. */
@@ -142,6 +188,250 @@ declare function writable<T>(initial: T): Writable<T>;
 declare function derived<T, U>(source: Readable<T>, fn: (value: T) => U): Readable<U>;
 declare function readonly<T>(w: Writable<T>): Readable<T>;
 //#endregion
+//#region src/model/form/types.d.ts
+/**
+ * A field's value: a string (text, combo, single-select list, and the appearance-state name of a
+ * checkbox or radio, `"Off"` included), the selected options of a multi-select list in option
+ * order, or the id of the annotation that visually signs a signature field.
+ */
+type FieldValue = string | readonly string[] | {
+  readonly signature: string;
+};
+/** Values keyed by full field name (`/T` parts joined with `.`). */
+type FieldValues = Readonly<Record<string, FieldValue>>;
+type FormFieldType = 'text' | 'checkbox' | 'radio' | 'combo' | 'list' | 'button' | 'signature';
+/** `/Ff` bits, each false where it does not apply to the field's type. */
+interface FieldFlags {
+  readOnly: boolean;
+  required: boolean;
+  noExport: boolean;
+  multiline: boolean;
+  password: boolean;
+  comb: boolean;
+  fileSelect: boolean;
+  doNotSpellCheck: boolean;
+  doNotScroll: boolean;
+  multiSelect: boolean;
+  editable: boolean;
+  radiosInUnison: boolean;
+}
+/**
+ * For a choice field, `value` is the export value and `label` the display text. For a checkbox
+ * or radio, `value` is a widget's appearance-state name and `label` its export value.
+ */
+interface FieldOption {
+  value: string;
+  label: string;
+}
+interface WidgetAppearance {
+  font?: {
+    family: string;
+    fontWeight?: 'bold';
+    fontStyle?: 'italic';
+  };
+  /** Points; 0 means auto size. */
+  fontSize: number;
+  /** Upper-case `#RRGGBB`, as `pdfColorToHex` gives it. */
+  color?: string;
+  align: 'left' | 'center' | 'right';
+  border?: {
+    /** Upper-case `#RRGGBB`. */
+    color?: string;
+    width: number;
+    style: 'solid' | 'dashed' | 'beveled' | 'inset' | 'underline';
+  };
+  /** Upper-case `#RRGGBB`. */
+  background?: string;
+  /** A push button's `/MK /CA`. */
+  caption?: string;
+  /** A checkbox or radio's `/MK /CA`: the ZapfDingbats character drawn when on. */
+  checkStyle?: string;
+  /** A checkbox or radio widget has its own on appearance: `/AP /N` holds its on state. */
+  onAppearance?: boolean;
+  /** A checkbox or radio widget has its own off appearance: `/AP /N` holds `Off`. */
+  offAppearance?: boolean;
+  /**
+   * The file has an `/AP /N` appearance for the widget (a checkbox or radio: for its current
+   * `/AS`). Without one, PDF.js draws nothing for it unless it makes one from the value.
+   */
+  fileAppearance?: boolean;
+}
+type WidgetAction = {
+  kind: 'reset';
+  fields: string[];
+  include: boolean;
+} | {
+  kind: 'submit';
+  url: string;
+  fields: string[];
+  include: boolean;
+  format: 'fdf' | 'xfdf' | 'html' | 'pdf';
+  method?: 'GET' | 'POST';
+} | {
+  kind: 'uri';
+  url: string;
+  newWindow?: boolean;
+} | {
+  kind: 'named';
+  name: string;
+} | {
+  kind: 'goto';
+  page: number;
+};
+/**
+ * A page's `/Tabs`: rows, columns, structure, widgets first (PDF 2.0; Inkbar's fields come
+ * before annotations anyway) or annotation array order (PDF 2.0).
+ */
+type TabsOrder = 'R' | 'C' | 'S' | 'W' | 'A';
+interface FormWidget {
+  /** The PDF.js annotation id, such as `12R`. */
+  id: string;
+  page: number;
+  /**
+   * Its place among the page's widgets in the page's `/Annots`, from 0. Widgets paint in this
+   * order, and Tab follows it unless the page's `/Tabs` reads rows or columns.
+   */
+  order?: number;
+  /** User space, before the page's /Rotate. */
+  rect: Rect$1;
+  /** `/MK /R`. */
+  rotation: 0 | 90 | 180 | 270;
+  /** A checkbox or radio widget's on appearance state. */
+  onState?: string;
+  /** Not drawn on screen: `/F` Hidden or NoView, or a barcode field Inkbar cannot draw. */
+  hidden: boolean;
+  /** `/F` NoView with Print: drawn only when printed. Such a widget is also `hidden`. */
+  printOnly: boolean;
+  appearance: WidgetAppearance;
+  action?: WidgetAction;
+  /**
+   * The URL a JavaScript `/A`'s `app.launchURL` opens, as PDF.js reads it out of the script.
+   * Followed on Action only when the form runs no scripts, such as when the sandbox failed to
+   * load; with scripts running, the script opens it itself.
+   */
+  fallback?: WidgetAction;
+  /**
+   * The GoTo, URI, Named, ResetForm and SubmitForm actions in the `/A`'s `/Next` chain, in
+   * order. They run on Action after the widget's scripts and its own action, whether or not
+   * scripts run, in the same undo step. JavaScript anywhere in the chain runs first, with the
+   * widget's other Action scripts (PDF.js collects them into one), so its position in the
+   * chain is not kept: a GoTo whose `/Next` is JavaScript runs the script, then the GoTo.
+   */
+  next?: readonly WidgetAction[];
+  hasScripts: boolean;
+}
+interface FormField {
+  /** Full name: `/T` parts joined with `.`. */
+  name: string;
+  type: FormFieldType;
+  flags: FieldFlags;
+  maxLength?: number;
+  options: readonly FieldOption[];
+  defaultValue?: FieldValue;
+  value?: FieldValue;
+  /** `/TU`. */
+  tooltip?: string;
+  /** In page order, as the file lists them. */
+  widgets: readonly FormWidget[];
+  signed?: 'certificate';
+  /** Nothing may change the value: certificate-signed, locked by a signature, or unsupported. */
+  locked: boolean;
+}
+/** Script-driven state for one widget. Absent keys leave the PDF's own state. */
+interface WidgetOverride {
+  hidden?: boolean;
+  readOnly?: boolean;
+  required?: boolean;
+  /** Lower-case `#rrggbb`, or `transparent` for none. */
+  textColor?: string;
+  fillColor?: string;
+  strokeColor?: string;
+  /** Points; 0 means auto size. */
+  textSize?: number;
+}
+/** An event the form layer sends a widget's scripts. */
+interface FormEvent {
+  widget: string;
+  name: 'Keystroke' | 'Format' | 'Validate' | 'Focus' | 'Blur' | 'Mouse Enter' | 'Mouse Exit' | 'Mouse Down' | 'Mouse Up' | 'Action';
+  value?: string | string[];
+  change?: string;
+  selStart?: number;
+  selEnd?: number;
+  willCommit?: boolean;
+  commitKey?: number;
+}
+/** Something a form asks the host to do. Inkbar itself never sends, opens, mails or prints. */
+type FormAction = {
+  kind: 'submit';
+  url: string;
+  fields: FieldValues;
+  format: 'fdf' | 'xfdf' | 'html' | 'pdf';
+  method?: 'GET' | 'POST';
+} | {
+  kind: 'open-url';
+  url: string;
+  newWindow: boolean;
+} | {
+  kind: 'mail';
+  to?: string;
+  cc?: string;
+  bcc?: string;
+  subject?: string;
+  body?: string;
+  withData: boolean;
+} | {
+  kind: 'print';
+} | {
+  kind: 'prompt';
+  message: string;
+};
+/**
+ * What changed the values reported to a controlled host, and the fields it changed. Undo
+ * history needs uncontrolled fields and annotations, so a controlled host never hears of an
+ * undo or redo, and no change has a `history` kind.
+ *
+ * - `commit`: a person, `set` or a signature committed values; `names` lists the fields
+ *   committed, including fields a calculation changed.
+ * - `reset`: a reset (the API's or a reset button's) restored defaults, with what it
+ *   calculated.
+ * - `import`: a Gloss import set values, with what it calculated.
+ * - `calculate`: a script set values outside a commit or reset (a timer, a page's open or close
+ *   script, a widget's event script), or calculated after a host's push.
+ */
+type FieldsChange = {
+  kind: 'commit';
+  names: string[];
+} | {
+  kind: 'reset';
+  names: string[];
+} | {
+  kind: 'import';
+  names: string[];
+} | {
+  kind: 'calculate';
+  names: string[];
+};
+/**
+ * Defaults to uncontrolled, starting from the PDF's values with `initial` over them. In
+ * controlled mode a change applies at once and is then reported with the full map; the host's
+ * push wins.
+ */
+type FieldsMode = {
+  mode: 'uncontrolled';
+  initial?: FieldValues;
+} | {
+  mode: 'controlled';
+  initial: FieldValues;
+  onChange(next: FieldValues, change: FieldsChange): void;
+};
+interface FormSetResult {
+  applied: string[];
+  rejected: {
+    name: string;
+    reason: 'unknown' | 'readOnly' | 'invalid' | 'script';
+  }[];
+}
+//#endregion
 //#region src/model/annotations/types.d.ts
 declare const PointSchema: z.ZodObject<{
   x: z.ZodNumber;
@@ -1729,6 +2019,7 @@ declare const AnnotationDocumentSchema: z.ZodObject<{
   version: z.ZodLiteral<1>;
   documentKey: z.ZodOptional<z.ZodString>;
   annotations: z.ZodArray<z.ZodUnknown>;
+  fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>;
 /**
  * An item whose `type` this version does not know, such as one from a newer writer. It is kept
@@ -1741,6 +2032,8 @@ interface AnnotationDocument {
   version: GlossDocument['version'];
   documentKey?: string;
   annotations: Array<Annotation | ForeignAnnotation>;
+  /** Form field values by full name: each field that has one and is not no-export. */
+  fields?: Record<string, FieldValue>;
 }
 //#endregion
 //#region src/model/annotations/defaults.d.ts
@@ -1776,6 +2069,7 @@ interface EmbeddedSummary {
   count: number;
   supported: boolean;
 }
+/** An RGB colour in 0–255 as upper-case `#RRGGBB`; `fallback` when it has fewer than three parts. */
 declare function pdfColorToHex(c: ArrayLike<number> | null | undefined, fallback: string): string;
 /**
  * Imported ids are `pdf:<page>:<pdfjsId>` (page is 0-based, pdfjsId is the annotation's object
@@ -1966,6 +2260,17 @@ interface AnnotationStore {
    * not applied yet: the list `update` and `remove` build on.
    */
   _getProposed(id: string): Annotation$1 | undefined;
+  /**
+   * @internal Pins annotations to what they fill (a signature to its signature field): a
+   * pinned annotation takes patches only to `contents` and to `custom` outside its `inkbar`
+   * key, and refuses any other (no move, resize, restyle, new image or new author), while
+   * `remove` still works. Replaces the whole set.
+   */
+  _setPinned(ids: ReadonlySet<string>): void;
+  /** @internal Whether `_setPinned` pinned `id`. */
+  _isPinned(id: string): boolean;
+  /** @internal The pinned ids, for the overlay. */
+  readonly _pinned: Readable<ReadonlySet<string>>;
   completeInput(input: AnnotationInput): Annotation$1;
   on(event: 'change', fn: (change: AnnotationChange) => void): () => void;
   /**
@@ -1991,8 +2296,8 @@ interface PluginHistory {
   batch(fn: () => void): void;
   /**
    * Makes the store's changes undo steps: on their own, or joining the open batch or edit. The
-   * returned function stops tracking; existing entries keep their snapshot of the store but undo
-   * and redo no longer replay it.
+   * returned function stops tracking: existing entries forget the store, so undo and redo never
+   * replay it again, even once it is tracked again, and an entry left with nothing is dropped.
    */
   track(store: RecordStore<RecordBase>): () => void;
   /**
@@ -2018,6 +2323,14 @@ interface History extends PluginHistory {
    * history this only runs `fn`, and a history destroyed inside `fn` records nothing.
    */
   batch(fn: () => void): void;
+  /**
+   * Runs `fn` and records none of what it changes in the tracked record stores: each changed
+   * record becomes part of the baseline, written into every step on both stacks (and the open
+   * step), so undo and redo leave it as `fn` left it. A step left with nothing else to replay is
+   * dropped. Nested calls, and calls inside a batch, work the same way. Annotation changes inside
+   * `fn` are recorded as usual. On a controlled or destroyed history this only runs `fn`.
+   */
+  baseline(fn: () => void): void;
   /** Unsubscribes from the store and empties both stacks; undo and redo become no-ops. */
   destroy(): void;
 }
@@ -2032,6 +2345,13 @@ declare function createHistory(store: AnnotationStore, opts?: {
   limit?: number;
 }): History;
 //#endregion
+//#region src/model/form/gloss.d.ts
+/** A Gloss value the form could not apply. No script runs on one, so none is `script`. */
+interface GlossRejection {
+  name: string;
+  reason: 'unknown' | 'readOnly' | 'invalid';
+}
+//#endregion
 //#region src/model/annotations/json.d.ts
 interface ImportResult {
   imported: number;
@@ -2044,6 +2364,11 @@ interface ImportResult {
     index: number;
     issues: string[];
   }[];
+  /** The document's `fields` names that were applied, and the ones that were not, with why. */
+  fields: {
+    applied: string[];
+    rejected: GlossRejection[];
+  };
 }
 interface ImportOptions {
   /** `replace` drops every session annotation first; `merge` overwrites by id and keeps the rest. */
@@ -2061,19 +2386,22 @@ interface ImportOptions {
  * under `custom.inkbar`, with loupes and masks as the circle or square they draw. Every other key
  * under `custom` goes out as it is.
  *
+ * `fields`, when given and not empty, goes out as the document's `fields` (see `fieldsToGloss`).
+ *
  * The result validates against the Gloss schema (`gloss-format/schema.json`). Foreign items
  * validate as unknown annotations while their type is one Gloss does not define.
  */
-declare function exportAnnotations(store: AnnotationStore, preserved?: readonly ForeignAnnotation[], documentKey?: string): AnnotationDocument;
+declare function exportAnnotations(store: AnnotationStore, preserved?: readonly ForeignAnnotation[], documentKey?: string, fields?: Readonly<Record<string, FieldValue>>): AnnotationDocument;
 /**
  * Validates the envelope (throws a TypeError when it is not a gloss v1 document),
  * then each item on its own. Embedded annotations are never touched; imported items become
- * session annotations.
+ * session annotations. With no form to apply them to, every `fields` name is reported as
+ * unknown; `InkDocument.importAnnotations` applies them to the document's form.
  */
 declare function importAnnotations(store: AnnotationStore, data: AnnotationDocument | string, opts: ImportOptions): ImportResult;
 //#endregion
 //#region src/model/errors.d.ts
-type InkErrorCode = 'PasswordRequired' | 'InvalidPdf' | 'SourceFetchFailed' | 'AssetConfigMissing' | 'AssetLoadFailed' | 'EngineUnavailable' | 'ControlledMutationIgnored' | 'DocumentDestroyed' | 'PageOutOfRange' | 'DuplicateId' | 'DuplicatePlugin' | 'InvalidPluginId' | 'InvalidCommandLabel' | 'UnknownCommand';
+type InkErrorCode = 'PasswordRequired' | 'InvalidPdf' | 'SourceFetchFailed' | 'AssetConfigMissing' | 'AssetLoadFailed' | 'EngineUnavailable' | 'ControlledMutationIgnored' | 'DocumentDestroyed' | 'PageOutOfRange' | 'DuplicateId' | 'DuplicatePlugin' | 'InvalidPluginId' | 'InvalidCommandLabel' | 'UnknownCommand' | 'FormScriptError' | 'UnknownField' | 'NotSignatureField' | 'FieldReadOnly' | 'FieldSigned';
 declare class InkError extends Error {
   readonly name = "InkError";
   readonly code: InkErrorCode;
@@ -2082,6 +2410,188 @@ declare class InkError extends Error {
 }
 declare function isInkError(value: unknown): value is InkError;
 //#endregion
+//#region src/model/form/controller.d.ts
+interface FieldRecord {
+  readonly id: string;
+  readonly value: FieldValue;
+}
+interface FormController {
+  /** Structure, read once on load. */
+  readonly fields: Readable<readonly FormField[]>;
+  /** What the screen and the sandbox hold, keyed by full name. */
+  readonly values: Readable<FieldValues>;
+  /** Formatted text per field, for display when not focused; set by scripts. */
+  readonly formatted: Readable<Readonly<Record<string, string>>>;
+  /** Script-driven widget state: hidden, readOnly, required, colours, by widget id. */
+  readonly widgetState: Readable<Readonly<Record<string, WidgetOverride>>>;
+  /**
+   * Whether the form has JavaScript: a widget's scripts, or document-level or page scripts
+   * running in the sandbox.
+   */
+  readonly hasScripts: boolean;
+  get(name: string): FieldValue | undefined;
+  /**
+   * Commits `values` as a person would: each runs its validate and calculate scripts, and the
+   * whole call is one undo step. A value that is unknown, read-only, invalid for the field or
+   * rejected by a script is left out and listed in `rejected`. In controlled mode the full map
+   * is reported once afterwards, as a `commit` naming the fields set and the fields a
+   * calculation changed.
+   */
+  set(values: FieldValues): FormSetResult;
+  /**
+   * Restores the PDF's default values of `names`, or of every field. Read-only fields reset
+   * too, as in Acrobat; locked fields keep theirs.
+   */
+  reset(names?: readonly string[]): void;
+  /**
+   * Controlled mode only: the host pushes its values. Names it leaves out keep their value.
+   * Pushing what the form already holds does nothing; otherwise calculate scripts run, and a
+   * calculation that changes more is reported once. Before the fields load, the push waits for
+   * them.
+   */
+  setControlledValue(next: FieldValues): void;
+  on(event: 'action', fn: (a: FormAction) => void): () => void;
+  on(event: 'alert', fn: (message: string) => void): () => void;
+  /**
+   * A script failed. The document keeps working; the form layer shows or logs it. Errors from
+   * before the first listener (a sandbox that failed to start while the document opened) go to
+   * that listener once, as it subscribes.
+   */
+  on(event: 'error', fn: (e: InkError) => void): () => void;
+  /** A script asked to move focus to this widget (by id). */
+  on(event: 'focus', fn: (widgetId: string) => void): () => void;
+  /** A widget's `/GoTo` action ran: show this page (zero-based). */
+  on(event: 'goto', fn: (page: number) => void): () => void;
+  /** @internal The scripting seam and the form layer. */
+  readonly _store: RecordStore<FieldRecord>;
+  _attachScripting(s: FormScripting): void;
+  _emitAction(a: FormAction): void;
+  /**
+   * Runs the widget's scripts for `event`, and on `Action` its non-script action (reset,
+   * submit, URI, named Print, GoTo). A Blur drops the widget's uncommitted text.
+   */
+  _dispatch(event: FormEvent): void;
+  /**
+   * @internal Runs `fn` as one undo step, so a widget's activation (its new value, its Mouse Up
+   * and its Action, with the scripts and reset they run) undoes at once.
+   */
+  _step(fn: () => void): void;
+  /**
+   * Applies a keystroke to the widget's text as typed so far (its uncommitted text, else the
+   * field's value as shown: a combo's option label for its export value). Without scripting it
+   * accepts every keystroke. The uncommitted text is dropped when the field's value changes or
+   * the widget blurs.
+   */
+  _keystroke(widget: string, change: string, selStart: number, selEnd: number): KeystrokeResult;
+  /**
+   * @internal Drops the widget's uncommitted text (Escape in a text field), and the sandbox,
+   * which saw each keystroke, goes back to the stored value. Its next keystroke builds on that.
+   */
+  _revert(widget: string): void;
+  /**
+   * @internal The viewer's current page became `page` (`PageOpen`) or another (`PageClose`):
+   * runs the page's open or close scripts. Resolves once they ran; nothing runs without scripts.
+   */
+  _pageEvent(page: number, name: PageEventName): Promise<void>;
+  /** @internal Sets a field's formatted text; `undefined` clears it. */
+  _setFormatted(name: string, text: string | undefined): void;
+  /** @internal Merges into a widget's override; `undefined` clears it. */
+  _setWidgetState(widgetId: string, override: WidgetOverride | undefined): void;
+  /** @internal Reports a script error to `onError` and the `error` listeners. */
+  _error(e: InkError): void;
+  /** @internal A script's `app.alert`. */
+  _alert(message: string): void;
+  /** @internal A script moved focus to a widget. */
+  _focus(widgetId: string): void;
+  /**
+   * @internal Values a script set (a calculation, or a script assigning a field). Read-only
+   * fields take them; locked fields and values that do not suit the field are skipped. Inside
+   * a commit, reset or widget event they join its undo step. Outside one (a timer, a page's
+   * open or close script, a keystroke script) they are no undo step: they become the history's
+   * baseline, so undo never rewinds them. A controlled host hears of them as `calculate`.
+   */
+  _scriptValues(values: FieldValues): void;
+  /** @internal Each page's `/Tabs`, for pages that set one; set with the fields. */
+  readonly _tabs: ReadonlyMap<number, TabsOrder>;
+  /**
+   * @internal For each page whose `/Tabs` is `S`, its annotation ids in structure-tree order;
+   * set with the fields.
+   */
+  readonly _structure: ReadonlyMap<number, readonly string[]>;
+  /** @internal Sets the structure once the file's fields are read, applying any waiting push. */
+  _load(fields: readonly FormField[], tabs?: ReadonlyMap<number, TabsOrder>, structure?: ReadonlyMap<number, readonly string[]>): void;
+  /**
+   * @internal Applies values already checked by `fieldsFromGloss`, as an import: neither the
+   * values nor what they calculate are an undo step. A controlled host hears of both as one
+   * `import`.
+   */
+  _import(values: FieldValues): void;
+  /**
+   * @internal Keeps signature fields and the annotations that sign them in step, from now
+   * until `_destroy`. Each signing annotation is pinned in the store. Removing one (by a person,
+   * an import, a controlled host that drops it, or undo) clears its field, and clearing the
+   * field (a reset, a host's push of another value, an import) removes the annotation.
+   */
+  _linkAnnotations(link: SignatureLink): void;
+  /**
+   * @internal Signs signature field `name` with annotation `id`, reported to a controlled
+   * host as a `commit`. When the annotation is not in the list yet (a controlled host has it
+   * proposed), the field is signed once it arrives, and stays empty if the host drops it.
+   */
+  _signWith(name: string, id: string): void;
+  /**
+   * @internal Whether `name` waits for a signature a controlled host has proposed and not
+   * applied or dropped yet.
+   */
+  _awaitingSignature(name: string): boolean;
+  /**
+   * @internal `set` or `reset` gave these fields a value, whether or not it differs from the
+   * one they held. The form layer clears a refused commit's mark on them. A host's push is not
+   * reported: it clears a mark only where it changes the value.
+   */
+  _onPut(fn: (names: readonly string[]) => void): () => void;
+  /** @internal Destroys the scripting and drops every listener. */
+  _destroy(): void;
+}
+/** What `_linkAnnotations` needs from the document. */
+interface SignatureLink {
+  store: AnnotationStore;
+  /** The history's `react`: runs inside a person's edit, so the field clears in the same step. */
+  react(fn: (edit: AnnotationEdit) => void): () => void;
+  /**
+   * True when undo and redo replay the field values together with the annotations, so an
+   * annotation replay leaves the fields to theirs.
+   */
+  replays: boolean;
+}
+/** A page event a page's scripts may handle. */
+type PageEventName = 'PageOpen' | 'PageClose';
+interface KeystrokeResult {
+  accepted: boolean;
+  value: string;
+  selStart: number;
+  selEnd: number;
+}
+interface FormScripting {
+  /**
+   * Runs validate for `name` with `value`, then calculate. Synchronous. Returns the value to
+   * store (a script may change it), or `undefined` when a script rejected it.
+   */
+  commit(name: string, value: FieldValue): FieldValue | undefined;
+  /** After values change without a user commit (host push, import, reset, undo). */
+  sync(values: FieldValues, calculate: boolean): void;
+  /** Runs a widget event's scripts. Synchronous. */
+  dispatch(event: FormEvent): void;
+  /**
+   * Runs the widget's keystroke scripts on `text`, the text typed so far. `undefined` when the
+   * widget has no field in the sandbox.
+   */
+  keystroke(widget: string, text: string, change: string, selStart: number, selEnd: number): KeystrokeResult | undefined;
+  /** Runs `page`'s (zero-based) open or close scripts; resolves once they ran. */
+  pageEvent(page: number, name: PageEventName): Promise<void>;
+  destroy(): void;
+}
+//#endregion
 //#region src/model/text.d.ts
 interface TextItem {
   str: string;
@@ -2185,11 +2695,17 @@ interface OpenOptions {
    * in `list` whatever the host pushes back.
    */
   annotations?: StoreMode | undefined;
+  /**
+   * Form field values; defaults to uncontrolled, starting from the PDF's. In controlled mode a
+   * commit applies at once and is reported with the full map, and the host's push wins.
+   */
+  fields?: FieldsMode | undefined;
   /** Colour defaults. Pass `cssVariableDefaults(element)` from the DOM layer to read theme variables. */
   defaults?: AnnotationDefaults | undefined;
   /**
    * Undo history, on by default. `false` disables it. In controlled mode history is always
-   * inert: the host owns the list, so it owns undo too.
+   * inert: the host owns the list, so it owns undo too. Field values join it only while both
+   * annotations and fields are uncontrolled.
    */
   history?: boolean | {
     limit?: number | undefined;
@@ -2223,9 +2739,17 @@ interface InkDocument {
   /** What the file contained, by PDF subtype, including subtypes Inkbar does not show. */
   readonly embedded: readonly EmbeddedSummary[];
   readonly history: History;
-  /** Session annotations only, plus unknown-type items kept from earlier imports. */
+  /** The form's fields and values; empty when the file has no fields. */
+  readonly form: FormController;
+  /**
+   * Session annotations only, plus unknown-type items kept from earlier imports, and `fields`
+   * with every field value that is not no-export.
+   */
   exportAnnotations(format: 'json'): AnnotationDocument;
-  /** Defaults to `{ mode: 'replace' }`. Embedded annotations are never touched. */
+  /**
+   * Defaults to `{ mode: 'replace' }`. Embedded annotations are never touched. `fields`, when
+   * present, sets the values it names and leaves the rest; that is not an undo step.
+   */
   importAnnotations(data: AnnotationDocument | string, opts?: ImportOptions): ImportResult;
   /** Writes the document with its annotations. Needs @inkbar/engine; rejects with EngineUnavailable otherwise. */
   save(): Promise<Uint8Array>;
@@ -2289,7 +2813,7 @@ interface ToolStyle {
    * Updates the active tool's group, or under a select tool (no active group) the group that
    * owns each prop on each selected annotation (a speech bubble's outline is `shape`'s, its
    * text `text`'s). With `apply` it also updates every selected, unlocked annotation that has
-   * the props, in one history step. `apply` defaults to true under a select tool, and to
+   * the props, in one history step; a pinned one keeps its style. `apply` defaults to true under a select tool, and to
    * whether the selection is wholly in the group otherwise. `group` names the group explicitly.
    */
   set(patch: StyleProps, opts?: {
@@ -2415,5 +2939,21 @@ interface SignatureLibrary {
 }
 declare function createSignatureLibrary(store: SignatureStore): SignatureLibrary;
 //#endregion
-export { RecordChange as $, PolySchema as $t, SearchHit as A, quadFromRect as An, FreeTextSchema as At, exportAnnotations as B, unionRects as Bn, LineAnnotation as Bt, DocumentInfo as C, Quad as Cn, AnnotationSchema as Ct, OpenOptions as D, invertMatrix as Dn, ExportedAnnotationSchema as Dt, InkStatus as E, approxEqual as En, ExportedAnnotation as Et, InkError as F, rectFromQuad as Fn, GLOSS_SCHEMA_ID as Ft, AnnotationChange as G, LoupeSchema as Gt, History as H, LineEndingSchema as Ht, InkErrorCode as I, rectFromQuads as In, GLOSS_VERSION$1 as It, StoreMode as J, NoteAnnotation as Jt, AnnotationEdit as K, MaskAnnotation as Kt, isInkError as L, rectsIntersect as Ln, IMAGE_DATA_URL as Lt, SearchResults as M, quadsFromRect as Mn, FreeTextStyleSchema as Mt, TextContent as N, rectContainsPoint as Nn, GLOSS_FORMAT$1 as Nt, openDocument as O, multiplyMatrix as On, ForeignAnnotation as Ot, TextItem as P, rectFromPoints as Pn, GLOSS_MEDIA_TYPE as Pt, RecordBase as Q, PolyAnnotation as Qt, ImportOptions as R, translateQuad as Rn, InkAnnotation as Rt, createToolStyle as S, Point$1 as Sn, AnnotationPatch as St, InkDocument as T, applyMatrix as Tn, CircleSchema as Tt, PluginHistory as U, LineSchema as Ut, importAnnotations as V, LineEnding$1 as Vt, createHistory as W, LoupeAnnotation as Wt, createAnnotationStore as X, NoteSchema as Xt, StoreOptions as Y, NoteIconSchema as Yt, deriveRect as Z, PointSchema as Zt, StyleGroup as _, writable as _n, Annotation$1 as _t, SignatureStore as a, RedactSchema as an, EmbeddedTarget as at, ToolStyle as b, PdfAssets as bn, AnnotationInput as bt, createInkTemplate as c, SquareSchema as cn, importedId as ct, createSignatureLibrary as d, TextMarkupAnnotation as dn, Fringe$1 as dt, PolygonSchema as en, RecordStore as et, normaliseInk as f, TextMarkupSchema as fn, FringeSchema as ft, ScopedToolStyle as g, readonly as gn, staticDefaults as gt, STYLE_GROUPS as h, derived as hn, normalizeColor as ht, SignatureOptions as i, RedactAnnotation as in, EmbeddedSummary as it, SearchOptions as j, quadsFromFlat as jn, FreeTextStyle$1 as jt, DocumentSource as k, pointsFromFlat as kn, FreeTextAnnotation as kt, createLocalSignatureStore as l, StampAnnotation as ln, pdfColorToHex as lt, CurrentStyle as m, Writable as mn, cssVariableDefaults as mt, SIGNATURE_INK_WIDTH as n, QuadSchema as nn, createRecordStore as nt, SignatureTemplate as o, ShapeAnnotation as on, SUPPORTED_SUBTYPES as ot, placeSignature as p, Readable as pn, AnnotationDefaults as pt, AnnotationStore as q, MaskSchema as qt, SignatureLibrary as r, RectSchema as rn, EmbeddedFieldPatch as rt, createImageTemplate as s, ShapeSchema as sn, importEmbeddedPage as st, DEFAULT_SIGNATURE_WIDTH as t, PolylineSchema as tn, RecordStoreOptions as tt, createMemorySignatureStore as u, StampSchema as un, summarise as ut, StyleKey as v, PageInfo as vn, AnnotationDocument as vt, DocumentStatus as w, Rect$1 as wn, AnnotationType as wt, ToolStyleDeps as x, Matrix as xn, AnnotationOfType as xt, StyleProps as y, PageRotation as yn, AnnotationDocumentSchema as yt, ImportResult as z, translateRect as zn, InkSchema as zt };
-//# sourceMappingURL=signatures-CalOktkf.d.mts.map
+//#region src/model/form/sign.d.ts
+/**
+ * Signs signature field `field` on its widget `widget` with template `t`, and returns the new
+ * annotation's id. The signature (ink for a drawn one, a stamp for an image, `subject:
+ * 'Signature'`) is fitted and centred in the widget's rect, upright as the page's `/Rotate`
+ * shows it, and the field's value becomes `{ signature: id }`: one undo step, and in controlled
+ * mode one change of each. A controlled host gets the annotation proposed, and the field is
+ * signed once the host applies it.
+ *
+ * The signature is pinned to the field: it can be deleted, which clears the field, but not
+ * moved or resized. Throws an `InkError`: `UnknownField` for a field or widget the form does
+ * not have, `NotSignatureField` for another type, `FieldReadOnly` for a read-only or locked
+ * field (one signed with a certificate included), and `FieldSigned` when it is already signed.
+ */
+declare function signField(doc: InkDocument, field: string, widget: string, t: SignatureTemplate): string;
+//#endregion
+export { createAnnotationStore as $, rectFromQuad as $n, NoteSchema as $t, DocumentSource as A, WidgetOverride as An, ExportedAnnotationSchema as At, isInkError as B, Point$1 as Bn, IMAGE_DATA_URL as Bt, createToolStyle as C, FormEvent as Cn, AnnotationInput as Ct, InkStatus as D, FormWidget as Dn, AnnotationType as Dt, InkDocument as E, FormSetResult as En, AnnotationSchema as Et, TextItem as F, writable as Fn, FreeTextStyleSchema as Ft, History as G, invertMatrix as Gn, LineEndingSchema as Gt, ImportResult as H, Rect$1 as Hn, InkSchema as Ht, FormController as I, PageInfo as In, GLOSS_FORMAT$1 as It, AnnotationChange as J, quadFromRect as Jn, LoupeSchema as Jt, PluginHistory as K, multiplyMatrix as Kn, LineSchema as Kt, FormScripting as L, PageRotation as Ln, GLOSS_MEDIA_TYPE as Lt, SearchOptions as M, Writable as Mn, FreeTextAnnotation as Mt, SearchResults as N, derived as Nn, FreeTextSchema as Nt, OpenOptions as O, WidgetAction as On, CircleSchema as Ot, TextContent as P, readonly as Pn, FreeTextStyle$1 as Pt, StoreOptions as Q, rectFromPoints as Qn, NoteIconSchema as Qt, InkError as R, PdfAssets as Rn, GLOSS_SCHEMA_ID as Rt, ToolStyleDeps as S, FormAction as Sn, AnnotationDocumentSchema as St, DocumentStatus as T, FormFieldType as Tn, AnnotationPatch as Tt, exportAnnotations as U, applyMatrix as Un, LineAnnotation as Ut, ImportOptions as V, Quad as Vn, InkAnnotation as Vt, importAnnotations as W, approxEqual as Wn, LineEnding$1 as Wt, AnnotationStore as X, quadsFromRect as Xn, MaskSchema as Xt, AnnotationEdit as Y, quadsFromFlat as Yn, MaskAnnotation as Yt, StoreMode as Z, rectContainsPoint as Zn, NoteAnnotation as Zt, ScopedToolStyle as _, FieldOption as _n, cssVariableDefaults as _t, SignatureOptions as a, QuadSchema as an, createRecordStore as at, StyleProps as b, FieldsChange as bn, Annotation$1 as bt, createImageTemplate as c, RedactSchema as cn, EmbeddedTarget as ct, createMemorySignatureStore as d, SquareSchema as dn, importedId as dt, PointSchema as en, rectFromQuads as er, deriveRect as et, createSignatureLibrary as f, StampAnnotation as fn, pdfColorToHex as ft, STYLE_GROUPS as g, FieldFlags as gn, AnnotationDefaults as gt, CurrentStyle as h, TextMarkupSchema as hn, FringeSchema as ht, SignatureLibrary as i, PolylineSchema as in, unionRects as ir, RecordStoreOptions as it, SearchHit as j, Readable as jn, ForeignAnnotation as jt, openDocument as k, WidgetAppearance as kn, ExportedAnnotation as kt, createInkTemplate as l, ShapeAnnotation as ln, SUPPORTED_SUBTYPES as lt, placeSignature as m, TextMarkupAnnotation as mn, Fringe$1 as mt, DEFAULT_SIGNATURE_WIDTH as n, PolySchema as nn, translateQuad as nr, RecordChange as nt, SignatureStore as o, RectSchema as on, EmbeddedFieldPatch as ot, normaliseInk as p, StampSchema as pn, summarise as pt, createHistory as q, pointsFromFlat as qn, LoupeAnnotation as qt, SIGNATURE_INK_WIDTH as r, PolygonSchema as rn, translateRect as rr, RecordStore as rt, SignatureTemplate as s, RedactAnnotation as sn, EmbeddedSummary as st, signField as t, PolyAnnotation as tn, rectsIntersect as tr, RecordBase as tt, createLocalSignatureStore as u, ShapeSchema as un, importEmbeddedPage as ut, StyleGroup as v, FieldValue as vn, normalizeColor as vt, DocumentInfo as w, FormField as wn, AnnotationOfType as wt, ToolStyle as x, FieldsMode as xn, AnnotationDocument as xt, StyleKey as y, FieldValues as yn, staticDefaults as yt, InkErrorCode as z, Matrix as zn, GLOSS_VERSION$1 as zt };
+//# sourceMappingURL=sign-47QLNaqQ.d.mts.map