@embedpdf/core-acrojs 3.0.0-next.14 → 3.0.0-next.16

package/dist/index.d.cts

@@ -2,11 +2,12 @@ import { AnnotationRef, DocumentHandle, FormEffect, FormFieldDisplay, FormFieldF
 //#region src/actions.d.ts
 /**
  * Return executable JavaScript in PDF action order (root, then `/Next`
- * depth-first). A poisoned native snapshot is never partially executed.
+ * depth-first). A poisoned native snapshot is never partially executed. Any
+ * kind of destination will do: only the scripts are read.
  */
-declare function javaScriptSourcesFromActionTree(tree: PdfActionTree): string[];
+declare function javaScriptSourcesFromActionTree<Destination>(tree: PdfActionTree<Destination>): string[];
 /** One event source that preserves the tree's shared field overlay. */
-declare function javaScriptProgramFromActionTree(tree: PdfActionTree): string;
+declare function javaScriptProgramFromActionTree<Destination>(tree: PdfActionTree<Destination>): string;
 //#endregion
 //#region src/types.d.ts
 /** JSON-safe value vocabulary exposed through Acrobat's `event` and `Field`. */
@@ -26,6 +27,8 @@ interface ScriptFieldInput {
   readOnly: boolean;
   required: boolean;
   options?: ScriptFieldOption[];
+  /** A checkbox's or radio group's widget export values, in widget order (Acrobat `exportValues`). */
+  exportValues?: string[];
 }
 interface ScriptIdentity {
   /** Acrobat `identity.name`. Empty when the embedder did not configure it. */
@@ -53,7 +56,7 @@ interface ScriptEventInput {
   /**
    * Explicit Acrobat `event.type` / `event.name` overrides for action-driven
    * runs (built from the dispatcher's trigger provenance — `Field` × `Mouse
-   * Enter`, `Page` × `Open`, …; the `Annot` type is an EmbedPDF EXTENSION,
+   * Enter`, `Page` × `Open`, …; the `Annot` type is an EmbedPDF extension,
    * Acrobat has no event type for plain-annotation events). When omitted the
    * prelude derives them from `kind` (the K/V/C/F pipeline path).
    */
@@ -77,7 +80,7 @@ interface ScriptEventInput {
 type ScriptColorArray = ['T'] | ['G', number] | ['RGB', number, number, number] | ['CMYK', number, number, number, number];
 /**
  * One script-addressable annotation in the prefetched world — every subtype
- * EXCEPT link and widget (Acrobat serves those through `Link`/`Field`
+ * except link and widget (Acrobat serves those through `Link`/`Field`
  * objects; here they are separate event planes). Curated read surface only —
  * never a raw dictionary.
  */
@@ -113,10 +116,10 @@ interface ScriptAnnotInput {
    *  (stamps, images): appearance writes are refused with a diagnostic. */
   opaqueBody: boolean;
 }
-/** The curated WRITE patch one script staged for one annotation — a
+/** The curated write patch one script staged for one annotation — a
  *  canonical per-annot diff (last-write-wins per key, derived at run end
  *  exactly like form effects). Visibility keys ride `flags` so the commit
- *  sink maps them onto ONE engine flags patch. */
+ *  sink maps them onto one engine flags patch. */
 interface ScriptAnnotEffect {
   ref: AnnotationRef;
   patch: {
@@ -139,10 +142,10 @@ interface ScriptAnnotEffect {
   };
 }
 /**
- * The writable-property validity matrix, keyed by engine subtype — the ONE
+ * The writable-property validity matrix, keyed by engine subtype — the one
  * exported table (the prelude inlines an identical copy; a parity test pins
  * them together, and plugin-annotation drift-guards this against the kind
- * registry's PropSpecs). Flags + contents are writable everywhere
+ * registry's FieldSpecs). Flags + contents are writable everywhere
  * script-addressable; appearance keys vary by kind.
  */
 declare const ANNOT_WRITABLE_KEYS: Readonly<Record<string, readonly string[]>>;
@@ -152,7 +155,8 @@ interface ScriptInput {
   identity: ScriptIdentity;
   environment: ScriptEnvironment;
   fields: ScriptFieldInput[];
-  /** The prefetched annots plane (page-scoped — see the D6 deviation). */
+  /** The prefetched annots plane. It covers only the pages in `annotPages`;
+   *  `getAnnots` reports a compatibility deviation for any other page. */
   annots?: ScriptAnnotInput[];
   /** Zero-based page indexes the plane covers. */
   annotPages?: number[];
@@ -171,7 +175,7 @@ type ScriptUiEffect = {
   kind: 'gotoPage';
   page: number;
 } |
-/** `doc.submitForm(...)` — a submit INTENT, resolved and sink-routed
+/** `doc.submitForm(...)` — a submit intent, resolved and sink-routed
  *  outside the VM (never a network call from here). `fieldNames` are
  *  include-mode (Acrobat's aFields); `null` = the whole eligible form. */
 {
@@ -214,9 +218,9 @@ interface ScriptEventOutput {
 }
 /**
  * Effects are committed only by the originating client's orchestrator, in
- * the DECLARED cross-plane order: `formEffects` first (field order — matching
+ * the declared cross-plane order: `formEffects` first (field order — matching
  * the derive-by-diff model), then `annotEffects` (annot order); the first
- * failing effect marks every later effect in BOTH streams skipped.
+ * failing effect marks every later effect in both streams skipped.
  */
 interface ScriptOutput {
   event: ScriptEventOutput;
@@ -237,19 +241,19 @@ declare const DEFAULT_SCRIPT_BUDGET: Readonly<ScriptBudget>;
 /**
  * The shipped security posture (updated per phase — the live authority for
  * per-type × origin decisions is the actions plugin's policy; these
- * constants DOCUMENT the posture, they do not enforce it). The only
+ * constants document the posture, they do not enforce it). The only
  * configurable switch is explicit opt-in.
  */
 interface ScriptSecurityPolicy {
   enabled: boolean;
   executionOwner: 'originating-client-only';
   nameTreeBoot: 'lazy-first-transaction';
-  /** Submit is a sink chain — embedder handler → the document's HOME
+  /** Submit is a sink chain — embedder handler → the document's home
    *  (`doc.forms.submit`, engine-asserted) → blocked. Never auto-network. */
   submitForm: 'sink-chain';
   openAction: 'execute-lifecycle';
   pageActions: 'execute-lifecycle';
-  /** WC/WS/DS/WP/DP run when the VERB OWNER dispatches them. */
+  /** WC/WS/DS/WP/DP run when the verb owner dispatches them. */
   catalogLifecycleActions: 'execute-on-verb';
   annotationActions: 'execute-full-matrix';
 }
@@ -284,7 +288,7 @@ interface AcroJsVmGlobal {
 /**
  * Host-side Acrobat color-array conversions — the commit sinks and world
  * builders cross the Acrobat-array ↔ renderer-color boundary through these.
- * The PRELUDE inlines its own identical formulas (it must stay
+ * The prelude inlines its own identical formulas (it must stay
  * self-contained); `prelude.test.ts` pins the two implementations together.
  *
  * Conversion vectors (the documented Acrobat semantics):
@@ -307,7 +311,7 @@ declare function cssToScriptColor(css: string | null | undefined): ScriptColorAr
 declare function isScriptColorArray(value: unknown): value is ScriptColorArray;
 //#endregion
 //#region src/host.d.ts
-/** The per-run world a CALLER supplies (fields snapshot, prefetched annots
+/** The per-run world a caller supplies (fields snapshot, prefetched annots
  *  plane, the event). Document/identity/environment come from the host. */
 interface ScriptWorldInput {
   fields: ScriptFieldInput[];
@@ -322,14 +326,14 @@ interface ScriptWorldInput {
 interface ScriptTransaction {
   /**
    * Run the name-tree boot if it has not run in this realm yet; returns the
-   * boot output exactly ONCE (its effects belong to the first transaction —
+   * boot output exactly once (its effects belong to the first transaction —
    * commit them, tag their UI effects `phase: 'boot'`), null thereafter.
    */
   boot(world: ScriptWorldInput, budget?: ScriptBudget): Promise<ScriptOutput | null>;
   /** One deterministic run against the shared realm. Auto-boots defensively
    *  (that boot's output is then returned by the next `boot()` call).
    *  `budget` overrides the host default per run — the form pipeline slices
-   *  ONE transaction-wide time budget across its K/V/C/F passes. */
+   *  one transaction-wide time budget across its K/V/C/F passes. */
   run(program: string, world: ScriptWorldInput, budget?: ScriptBudget): Promise<ScriptOutput>;
 }
 interface ScriptHostOptions {
@@ -344,12 +348,12 @@ interface ScriptHostOptions {
   budget?: ScriptBudget;
 }
 /**
- * The ONE realm per document (umbrella law #5): a name-tree function must be
+ * The one realm per document: a name-tree function must be
  * callable from a page-open script and a field calculate alike.
  *
- * `transaction(body)` is the realm mutex, and the body performs EVERYTHING
+ * `transaction(body)` is the realm mutex, and the body performs everything
  * for one logical script transaction — world prefetch, VM run(s), document
- * commits through the owner sinks, model reconciliation — BEFORE the mutex
+ * commits through the owner sinks, model reconciliation — before the mutex
  * releases, so the next transaction always prefetches post-commit truth
  * (the commit-inside-the-boundary law). Lock hierarchy: caller queues
  * (actions dispatch / form mutation) acquire this queue, never the reverse,
@@ -368,8 +372,8 @@ interface ScriptHost {
  *  (ported verbatim from the form controller; exported for callers building
  *  `ScriptHostOptions.environment`). */
 declare function seedFrom(documentId: string, sequence: number): number;
-/** Engine JWT/session identity composed under embedder overrides — the
- *  standard `ScriptHostOptions.identity` builder. */
+/** The session's identity, as Acrobat JavaScript's `identity` object, under
+ *  embedder overrides — the standard `ScriptHostOptions.identity` builder. */
 declare function resolveScriptIdentity(doc: DocumentHandle, overrides?: Partial<ScriptIdentity> | (() => Partial<ScriptIdentity>)): ScriptIdentity;
 declare function createScriptHost(options: ScriptHostOptions): ScriptHost;
 //#endregion
@@ -385,7 +389,7 @@ declare function scriptFieldsFromSnapshot(snapshot: FormSnapshot): ScriptFieldIn
  * values. The sandbox ships `installAcroJs.toString()` into QuickJS, while
  * tests execute the same source in a Node VM. Types disappear at build time.
  */
-declare function installAcroJs(g: Record<string, unknown>): void;
+declare function installAcroJs(globalObject: Record<string, unknown>): void;
 /** The exact self-contained source evaluated in Node parity tests and QuickJS. */
 declare const PRELUDE_SOURCE: string;
 //#endregion

package/dist/index.d.ts

@@ -2,11 +2,12 @@ import { AnnotationRef, DocumentHandle, FormEffect, FormFieldDisplay, FormFieldF
 //#region src/actions.d.ts
 /**
  * Return executable JavaScript in PDF action order (root, then `/Next`
- * depth-first). A poisoned native snapshot is never partially executed.
+ * depth-first). A poisoned native snapshot is never partially executed. Any
+ * kind of destination will do: only the scripts are read.
  */
-declare function javaScriptSourcesFromActionTree(tree: PdfActionTree): string[];
+declare function javaScriptSourcesFromActionTree<Destination>(tree: PdfActionTree<Destination>): string[];
 /** One event source that preserves the tree's shared field overlay. */
-declare function javaScriptProgramFromActionTree(tree: PdfActionTree): string;
+declare function javaScriptProgramFromActionTree<Destination>(tree: PdfActionTree<Destination>): string;
 //#endregion
 //#region src/types.d.ts
 /** JSON-safe value vocabulary exposed through Acrobat's `event` and `Field`. */
@@ -26,6 +27,8 @@ interface ScriptFieldInput {
   readOnly: boolean;
   required: boolean;
   options?: ScriptFieldOption[];
+  /** A checkbox's or radio group's widget export values, in widget order (Acrobat `exportValues`). */
+  exportValues?: string[];
 }
 interface ScriptIdentity {
   /** Acrobat `identity.name`. Empty when the embedder did not configure it. */
@@ -53,7 +56,7 @@ interface ScriptEventInput {
   /**
    * Explicit Acrobat `event.type` / `event.name` overrides for action-driven
    * runs (built from the dispatcher's trigger provenance — `Field` × `Mouse
-   * Enter`, `Page` × `Open`, …; the `Annot` type is an EmbedPDF EXTENSION,
+   * Enter`, `Page` × `Open`, …; the `Annot` type is an EmbedPDF extension,
    * Acrobat has no event type for plain-annotation events). When omitted the
    * prelude derives them from `kind` (the K/V/C/F pipeline path).
    */
@@ -77,7 +80,7 @@ interface ScriptEventInput {
 type ScriptColorArray = ['T'] | ['G', number] | ['RGB', number, number, number] | ['CMYK', number, number, number, number];
 /**
  * One script-addressable annotation in the prefetched world — every subtype
- * EXCEPT link and widget (Acrobat serves those through `Link`/`Field`
+ * except link and widget (Acrobat serves those through `Link`/`Field`
  * objects; here they are separate event planes). Curated read surface only —
  * never a raw dictionary.
  */
@@ -113,10 +116,10 @@ interface ScriptAnnotInput {
    *  (stamps, images): appearance writes are refused with a diagnostic. */
   opaqueBody: boolean;
 }
-/** The curated WRITE patch one script staged for one annotation — a
+/** The curated write patch one script staged for one annotation — a
  *  canonical per-annot diff (last-write-wins per key, derived at run end
  *  exactly like form effects). Visibility keys ride `flags` so the commit
- *  sink maps them onto ONE engine flags patch. */
+ *  sink maps them onto one engine flags patch. */
 interface ScriptAnnotEffect {
   ref: AnnotationRef;
   patch: {
@@ -139,10 +142,10 @@ interface ScriptAnnotEffect {
   };
 }
 /**
- * The writable-property validity matrix, keyed by engine subtype — the ONE
+ * The writable-property validity matrix, keyed by engine subtype — the one
  * exported table (the prelude inlines an identical copy; a parity test pins
  * them together, and plugin-annotation drift-guards this against the kind
- * registry's PropSpecs). Flags + contents are writable everywhere
+ * registry's FieldSpecs). Flags + contents are writable everywhere
  * script-addressable; appearance keys vary by kind.
  */
 declare const ANNOT_WRITABLE_KEYS: Readonly<Record<string, readonly string[]>>;
@@ -152,7 +155,8 @@ interface ScriptInput {
   identity: ScriptIdentity;
   environment: ScriptEnvironment;
   fields: ScriptFieldInput[];
-  /** The prefetched annots plane (page-scoped — see the D6 deviation). */
+  /** The prefetched annots plane. It covers only the pages in `annotPages`;
+   *  `getAnnots` reports a compatibility deviation for any other page. */
   annots?: ScriptAnnotInput[];
   /** Zero-based page indexes the plane covers. */
   annotPages?: number[];
@@ -171,7 +175,7 @@ type ScriptUiEffect = {
   kind: 'gotoPage';
   page: number;
 } |
-/** `doc.submitForm(...)` — a submit INTENT, resolved and sink-routed
+/** `doc.submitForm(...)` — a submit intent, resolved and sink-routed
  *  outside the VM (never a network call from here). `fieldNames` are
  *  include-mode (Acrobat's aFields); `null` = the whole eligible form. */
 {
@@ -214,9 +218,9 @@ interface ScriptEventOutput {
 }
 /**
  * Effects are committed only by the originating client's orchestrator, in
- * the DECLARED cross-plane order: `formEffects` first (field order — matching
+ * the declared cross-plane order: `formEffects` first (field order — matching
  * the derive-by-diff model), then `annotEffects` (annot order); the first
- * failing effect marks every later effect in BOTH streams skipped.
+ * failing effect marks every later effect in both streams skipped.
  */
 interface ScriptOutput {
   event: ScriptEventOutput;
@@ -237,19 +241,19 @@ declare const DEFAULT_SCRIPT_BUDGET: Readonly<ScriptBudget>;
 /**
  * The shipped security posture (updated per phase — the live authority for
  * per-type × origin decisions is the actions plugin's policy; these
- * constants DOCUMENT the posture, they do not enforce it). The only
+ * constants document the posture, they do not enforce it). The only
  * configurable switch is explicit opt-in.
  */
 interface ScriptSecurityPolicy {
   enabled: boolean;
   executionOwner: 'originating-client-only';
   nameTreeBoot: 'lazy-first-transaction';
-  /** Submit is a sink chain — embedder handler → the document's HOME
+  /** Submit is a sink chain — embedder handler → the document's home
    *  (`doc.forms.submit`, engine-asserted) → blocked. Never auto-network. */
   submitForm: 'sink-chain';
   openAction: 'execute-lifecycle';
   pageActions: 'execute-lifecycle';
-  /** WC/WS/DS/WP/DP run when the VERB OWNER dispatches them. */
+  /** WC/WS/DS/WP/DP run when the verb owner dispatches them. */
   catalogLifecycleActions: 'execute-on-verb';
   annotationActions: 'execute-full-matrix';
 }
@@ -284,7 +288,7 @@ interface AcroJsVmGlobal {
 /**
  * Host-side Acrobat color-array conversions — the commit sinks and world
  * builders cross the Acrobat-array ↔ renderer-color boundary through these.
- * The PRELUDE inlines its own identical formulas (it must stay
+ * The prelude inlines its own identical formulas (it must stay
  * self-contained); `prelude.test.ts` pins the two implementations together.
  *
  * Conversion vectors (the documented Acrobat semantics):
@@ -307,7 +311,7 @@ declare function cssToScriptColor(css: string | null | undefined): ScriptColorAr
 declare function isScriptColorArray(value: unknown): value is ScriptColorArray;
 //#endregion
 //#region src/host.d.ts
-/** The per-run world a CALLER supplies (fields snapshot, prefetched annots
+/** The per-run world a caller supplies (fields snapshot, prefetched annots
  *  plane, the event). Document/identity/environment come from the host. */
 interface ScriptWorldInput {
   fields: ScriptFieldInput[];
@@ -322,14 +326,14 @@ interface ScriptWorldInput {
 interface ScriptTransaction {
   /**
    * Run the name-tree boot if it has not run in this realm yet; returns the
-   * boot output exactly ONCE (its effects belong to the first transaction —
+   * boot output exactly once (its effects belong to the first transaction —
    * commit them, tag their UI effects `phase: 'boot'`), null thereafter.
    */
   boot(world: ScriptWorldInput, budget?: ScriptBudget): Promise<ScriptOutput | null>;
   /** One deterministic run against the shared realm. Auto-boots defensively
    *  (that boot's output is then returned by the next `boot()` call).
    *  `budget` overrides the host default per run — the form pipeline slices
-   *  ONE transaction-wide time budget across its K/V/C/F passes. */
+   *  one transaction-wide time budget across its K/V/C/F passes. */
   run(program: string, world: ScriptWorldInput, budget?: ScriptBudget): Promise<ScriptOutput>;
 }
 interface ScriptHostOptions {
@@ -344,12 +348,12 @@ interface ScriptHostOptions {
   budget?: ScriptBudget;
 }
 /**
- * The ONE realm per document (umbrella law #5): a name-tree function must be
+ * The one realm per document: a name-tree function must be
  * callable from a page-open script and a field calculate alike.
  *
- * `transaction(body)` is the realm mutex, and the body performs EVERYTHING
+ * `transaction(body)` is the realm mutex, and the body performs everything
  * for one logical script transaction — world prefetch, VM run(s), document
- * commits through the owner sinks, model reconciliation — BEFORE the mutex
+ * commits through the owner sinks, model reconciliation — before the mutex
  * releases, so the next transaction always prefetches post-commit truth
  * (the commit-inside-the-boundary law). Lock hierarchy: caller queues
  * (actions dispatch / form mutation) acquire this queue, never the reverse,
@@ -368,8 +372,8 @@ interface ScriptHost {
  *  (ported verbatim from the form controller; exported for callers building
  *  `ScriptHostOptions.environment`). */
 declare function seedFrom(documentId: string, sequence: number): number;
-/** Engine JWT/session identity composed under embedder overrides — the
- *  standard `ScriptHostOptions.identity` builder. */
+/** The session's identity, as Acrobat JavaScript's `identity` object, under
+ *  embedder overrides — the standard `ScriptHostOptions.identity` builder. */
 declare function resolveScriptIdentity(doc: DocumentHandle, overrides?: Partial<ScriptIdentity> | (() => Partial<ScriptIdentity>)): ScriptIdentity;
 declare function createScriptHost(options: ScriptHostOptions): ScriptHost;
 //#endregion
@@ -385,7 +389,7 @@ declare function scriptFieldsFromSnapshot(snapshot: FormSnapshot): ScriptFieldIn
  * values. The sandbox ships `installAcroJs.toString()` into QuickJS, while
  * tests execute the same source in a Node VM. Types disappear at build time.
  */
-declare function installAcroJs(g: Record<string, unknown>): void;
+declare function installAcroJs(globalObject: Record<string, unknown>): void;
 /** The exact self-contained source evaluated in Node parity tests and QuickJS. */
 declare const PRELUDE_SOURCE: string;
 //#endregion