@inkbar/core 0.6.0 → 0.8.0

package/dist/{signatures-By4B40DP.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,14 +2410,187 @@ declare class InkError extends Error {
 }
 declare function isInkError(value: unknown): value is InkError;
 //#endregion
-//#region src/model/source.d.ts
-type DocumentSource = ArrayBuffer | Uint8Array | Blob | string | {
-  url: string;
-  key: string;
-} | {
-  data: ArrayBuffer | Uint8Array;
-  key: string;
-};
+//#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 {
@@ -2102,12 +2603,69 @@ interface TextItem {
   quad: Quad;
   /** Axis-aligned bounds of `quad`. */
   rect: Rect$1;
+  /**
+   * How far along the run each character boundary lies, as a fraction of its width: `str.length + 1`
+   * entries, from 0 to 1 or a little past it. Taken from where the page draws each glyph when the
+   * glyphs can be matched to the run, else measured in the run's fallback font. Absent when neither
+   * works, in which case every character takes an equal share.
+   */
+  advances?: readonly number[];
+  /**
+   * Where each character's glyph ends, as a fraction of the run's width: `str.length` entries, set
+   * with `advances` when they come from the page's glyphs. Kerning can pull the next character
+   * back over the end of a glyph, so a glyph may end past the next boundary.
+   */
+  glyphEnds?: readonly number[];
 }
 interface TextContent {
   page: number;
   items: TextItem[];
 }
 //#endregion
+//#region src/model/search.d.ts
+interface SearchOptions {
+  /** Defaults to false. Ignored for a `RegExp`, whose own `i` flag rules. */
+  matchCase?: boolean;
+  /** Requires a hit to have no letter, digit or underscore next to it. */
+  wholeWord?: boolean;
+  /** Page indices to search, in the order given. Defaults to every page in order. */
+  pages?: readonly number[];
+  signal?: AbortSignal;
+}
+interface SearchHit {
+  page: number;
+  /** Offsets into `pageText(page)`. */
+  start: number;
+  end: number;
+  /** The page text the hit covers. */
+  text: string;
+  /** One quad per run of text the hit touches. */
+  quads: Quad[];
+  rect: Rect$1;
+  /**
+   * True when every quad is cut where the page draws its glyphs. False when some text could not
+   * be matched to the page's glyphs (right-to-left or vertical text, or an unusual file) and its
+   * quad is cut at estimated widths, which can fall short of the glyphs; pad those before
+   * covering text with them.
+   */
+  exact: boolean;
+  /** Up to `CONTEXT_CHARS` of page text either side of the hit, whitespace collapsed. */
+  before: string;
+  after: string;
+}
+interface SearchResults extends AsyncIterable<SearchHit> {
+  all(): Promise<SearchHit[]>;
+}
+//#endregion
+//#region src/model/source.d.ts
+type DocumentSource = ArrayBuffer | Uint8Array | Blob | string | {
+  url: string;
+  key: string;
+} | {
+  data: ArrayBuffer | Uint8Array;
+  key: string;
+};
+//#endregion
 //#region src/model/document.d.ts
 type DocumentStatus = {
   state: 'loading';
@@ -2137,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;
@@ -2157,8 +2721,13 @@ interface InkDocument {
   readonly pages: readonly PageInfo[];
   readonly info: DocumentInfo;
   text(page: number): Promise<TextContent>;
-  /** The page's text items joined with a single space. */
+  /** The page's text as search sees it: items joined the way the page reads. */
   pageText(page: number): Promise<string>;
+  /**
+   * Finds `query` in the document's text, a page at a time. A string matches ignoring case,
+   * accents and quote style; a `RegExp` runs on the same normalised text.
+   */
+  search(query: string | RegExp, opts?: SearchOptions): SearchResults;
   /**
    * Annotations embedded in the file arrive here as `source: 'pdf'`, `locked: true` before
    * `ready` resolves. They stay in `list` in both modes and cannot be removed; in controlled
@@ -2170,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>;
@@ -2236,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?: {
@@ -2362,5 +2939,21 @@ interface SignatureLibrary {
 }
 declare function createSignatureLibrary(store: SignatureStore): SignatureLibrary;
 //#endregion
-export { createRecordStore as $, QuadSchema as $t, TextItem as A, rectContainsPoint as An, GLOSS_FORMAT$1 as At, PluginHistory as B, LineSchema as Bt, DocumentInfo as C, approxEqual as Cn, ExportedAnnotation as Ct, OpenOptions as D, quadFromRect as Dn, FreeTextSchema as Dt, InkStatus as E, pointsFromFlat as En, FreeTextAnnotation as Et, ImportOptions as F, translateQuad as Fn, InkAnnotation as Ft, StoreMode as G, NoteAnnotation as Gt, AnnotationChange as H, LoupeSchema as Ht, ImportResult as I, translateRect as In, InkSchema as It, deriveRect as J, PointSchema as Jt, StoreOptions as K, NoteIconSchema as Kt, exportAnnotations as L, unionRects as Ln, LineAnnotation as Lt, InkError as M, rectFromQuad as Mn, GLOSS_SCHEMA_ID as Mt, InkErrorCode as N, rectFromQuads as Nn, GLOSS_VERSION$1 as Nt, openDocument as O, quadsFromFlat as On, FreeTextStyle$1 as Ot, isInkError as P, rectsIntersect as Pn, IMAGE_DATA_URL as Pt, RecordStoreOptions as Q, PolylineSchema as Qt, importAnnotations as R, LineEnding$1 as Rt, createToolStyle as S, applyMatrix as Sn, CircleSchema as St, InkDocument as T, multiplyMatrix as Tn, ForeignAnnotation as Tt, AnnotationEdit as U, MaskAnnotation as Ut, createHistory as V, LoupeAnnotation as Vt, AnnotationStore as W, MaskSchema as Wt, RecordChange as X, PolySchema as Xt, RecordBase as Y, PolyAnnotation as Yt, RecordStore as Z, PolygonSchema as Zt, StyleGroup as _, PdfAssets as _n, AnnotationInput as _t, SignatureStore as a, SquareSchema as an, importedId as at, ToolStyle as b, Quad as bn, AnnotationSchema as bt, createInkTemplate as c, TextMarkupAnnotation as cn, Fringe$1 as ct, createSignatureLibrary as d, Writable as dn, cssVariableDefaults as dt, RectSchema as en, EmbeddedFieldPatch as et, normaliseInk as f, derived as fn, normalizeColor as ft, ScopedToolStyle as g, PageRotation as gn, AnnotationDocumentSchema as gt, STYLE_GROUPS as h, PageInfo as hn, AnnotationDocument as ht, SignatureOptions as i, ShapeSchema as in, importEmbeddedPage as it, DocumentSource as j, rectFromPoints as jn, GLOSS_MEDIA_TYPE as jt, TextContent as k, quadsFromRect as kn, FreeTextStyleSchema as kt, createLocalSignatureStore as l, TextMarkupSchema as ln, FringeSchema as lt, CurrentStyle as m, writable as mn, Annotation$1 as mt, SIGNATURE_INK_WIDTH as n, RedactSchema as nn, EmbeddedTarget as nt, SignatureTemplate as o, StampAnnotation as on, pdfColorToHex as ot, placeSignature as p, readonly as pn, staticDefaults as pt, createAnnotationStore as q, NoteSchema as qt, SignatureLibrary as r, ShapeAnnotation as rn, SUPPORTED_SUBTYPES as rt, createImageTemplate as s, StampSchema as sn, summarise as st, DEFAULT_SIGNATURE_WIDTH as t, RedactAnnotation as tn, EmbeddedSummary as tt, createMemorySignatureStore as u, Readable as un, AnnotationDefaults as ut, StyleKey as v, Matrix as vn, AnnotationOfType as vt, DocumentStatus as w, invertMatrix as wn, ExportedAnnotationSchema as wt, ToolStyleDeps as x, Rect$1 as xn, AnnotationType as xt, StyleProps as y, Point$1 as yn, AnnotationPatch as yt, History as z, LineEndingSchema as zt };
-//# sourceMappingURL=signatures-By4B40DP.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