@embedpdf/core-acrojs 3.0.0-next.1 → 3.0.0-next.11

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { FormEffect, FormFieldDisplay, FormFieldFamily, FormFieldRef, FormSnapshot, PdfActionTree } from "@embedpdf/engine-core/runtime";
+import { AnnotationRef, DocumentHandle, FormEffect, FormFieldDisplay, FormFieldFamily, FormFieldRef, FormSnapshot, PdfActionTree } from "@embedpdf/engine-core/runtime";
 //#region src/actions.d.ts
 /**
  * Return executable JavaScript in PDF action order (root, then `/Next`
@@ -50,6 +50,15 @@ interface ScriptEnvironment {
 type ScriptEventKind = 'name-tree-boot' | 'widget-activate' | 'field-keystroke' | 'field-validate' | 'field-calculate' | 'field-format';
 interface ScriptEventInput {
   kind: ScriptEventKind;
+  /**
+   * 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,
+   * Acrobat has no event type for plain-annotation events). When omitted the
+   * prelude derives them from `kind` (the K/V/C/F pipeline path).
+   */
+  type?: string;
+  name?: string;
   target?: FormFieldRef;
   source?: FormFieldRef;
   value?: ScriptValue;
@@ -60,12 +69,95 @@ interface ScriptEventInput {
   modifier?: boolean;
   shift?: boolean;
 }
+/**
+ * An Acrobat color: `['T']` transparent, `['G', g]`, `['RGB', r, g, b]`,
+ * `['CMYK', c, m, y, k]` — components 0..1. The wire format scripts read and
+ * write; conversion to renderer/engine colors happens host-side (color.ts).
+ */
+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`
+ * objects; here they are separate event planes). Curated read surface only —
+ * never a raw dictionary.
+ */
+interface ScriptAnnotInput {
+  ref: AnnotationRef;
+  /** `/NM` — the `getAnnot(nPage, name)` key. Empty when the PDF has none. */
+  name: string;
+  /** The engine subtype (e.g. `'square'`). */
+  subtype: string;
+  /** Zero-based page index (Acrobat's `page`). */
+  page: number;
+  /** PDF-space `[llx, lly, urx, ury]`. */
+  rect: [number, number, number, number];
+  contents: string;
+  /** `/T` author and `/Subj` — read-only in v1 (collab identity stamping). */
+  author: string;
+  subject: string;
+  strokeColor: ScriptColorArray;
+  fillColor: ScriptColorArray;
+  opacity: number;
+  /** `/BS /W` border width in points. */
+  width: number;
+  /** Border style: `'S'` solid or `'D'` dashed. */
+  borderStyle: 'S' | 'D';
+  dash: number[];
+  hidden: boolean;
+  print: boolean;
+  readOnly: boolean;
+  locked: boolean;
+  noView: boolean;
+  toggleNoView: boolean;
+  /** True for kinds whose appearance cannot be re-derived from properties
+   *  (stamps, images): appearance writes are refused with a diagnostic. */
+  opaqueBody: boolean;
+}
+/** 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. */
+interface ScriptAnnotEffect {
+  ref: AnnotationRef;
+  patch: {
+    strokeColor?: ScriptColorArray;
+    fillColor?: ScriptColorArray;
+    opacity?: number;
+    width?: number;
+    borderStyle?: 'S' | 'D';
+    dash?: number[];
+    rect?: [number, number, number, number];
+    contents?: string;
+    flags?: Partial<{
+      hidden: boolean;
+      print: boolean;
+      readOnly: boolean;
+      locked: boolean;
+      noView: boolean;
+      toggleNoView: boolean;
+    }>;
+  };
+}
+/**
+ * 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
+ * script-addressable; appearance keys vary by kind.
+ */
+declare const ANNOT_WRITABLE_KEYS: Readonly<Record<string, readonly string[]>>;
 /** Complete input for one deterministic run. No ambient host values are read. */
 interface ScriptInput {
   document: ScriptDocumentInput;
   identity: ScriptIdentity;
   environment: ScriptEnvironment;
   fields: ScriptFieldInput[];
+  /** The prefetched annots plane (page-scoped — see the D6 deviation). */
+  annots?: ScriptAnnotInput[];
+  /** Zero-based page indexes the plane covers. */
+  annotPages?: number[];
+  /** True when annotPages spans the whole document (no scope diagnostic). */
+  annotsCoverDocument?: boolean;
   event: ScriptEventInput;
 }
 type ScriptUiEffect = {
@@ -78,12 +170,36 @@ type ScriptUiEffect = {
 } | {
   kind: 'gotoPage';
   page: number;
+} |
+/** `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. */
+{
+  kind: 'submitForm';
+  url: string | null;
+  fieldNames: string[] | null;
+  includeEmpty: boolean;
+  format?: 'fdf' | 'html' | 'xfdf' | 'pdf';
+  method?: 'post' | 'get';
 };
-type ScriptDiagnosticCode = 'blocked-network' | 'unsupported-api' | 'invalid-field-value' | 'script-error';
+type ScriptDiagnosticCode = 'blocked-network' | 'unsupported-api' | 'invalid-field-value' | 'script-error' | 'ui-effect-suppressed';
 interface ScriptDiagnostic {
   code: ScriptDiagnosticCode;
   message: string;
 }
+/** One isolated, stateful Acrobat-JavaScript realm for one PDF document. */
+interface ScriptSandbox {
+  /** True after explicit disposal or a resource/runtime fault. */
+  readonly disposed: boolean;
+  /** Evaluate document name-tree sources once. Top-level effects are returned
+   *  so the orchestrator can include them in the first transaction. */
+  boot(sources: string[], input: ScriptInput, budget?: ScriptBudget): ScriptOutput;
+  /** Run one event program against the realm's persistent globals. */
+  run(source: string, input: ScriptInput, budget?: ScriptBudget): ScriptOutput;
+  /** Release the realm. Idempotent. */
+  dispose(): void;
+}
+type ScriptSandboxFactory = () => Promise<ScriptSandbox>;
 interface ScriptExecutionError {
   kind: 'exception' | 'budget' | 'invalid-output';
   message: string;
@@ -96,10 +212,16 @@ interface ScriptEventOutput {
   selStart: number;
   selEnd: number;
 }
-/** Effects are committed only by the originating client's orchestrator. */
+/**
+ * Effects are committed only by the originating client's orchestrator, in
+ * 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.
+ */
 interface ScriptOutput {
   event: ScriptEventOutput;
   formEffects: FormEffect[];
+  annotEffects: ScriptAnnotEffect[];
   uiEffects: ScriptUiEffect[];
   diagnostics: ScriptDiagnostic[];
   error?: ScriptExecutionError;
@@ -112,19 +234,29 @@ interface ScriptBudget {
   maxOutputBytes: number;
 }
 declare const DEFAULT_SCRIPT_BUDGET: Readonly<ScriptBudget>;
-/** V1 security posture. The only configurable switch is explicit opt-in. */
+/**
+ * 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
+ * configurable switch is explicit opt-in.
+ */
 interface ScriptSecurityPolicy {
   enabled: boolean;
   executionOwner: 'originating-client-only';
   nameTreeBoot: 'lazy-first-transaction';
-  submitForm: 'blocked';
-  openAction: 'preserve-only';
-  pageActions: 'preserve-only';
-  catalogLifecycleActions: 'preserve-only';
-  annotationActions: 'widget-activate-only';
+  /** 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. */
+  catalogLifecycleActions: 'execute-on-verb';
+  annotationActions: 'execute-full-matrix';
 }
 declare const DEFAULT_SCRIPT_SECURITY_POLICY: Readonly<ScriptSecurityPolicy>;
-/** Frozen V1 dispatch matrix; extracted actions outside it remain data only. */
+/** The shipped dispatch matrix; extracted actions outside it remain data
+ *  only. (Historical note: v1 froze everything beyond K/V/C/F as
+ *  preserve-only; phases 1–4 executed the rest.) */
 declare const SCRIPT_EVENT_MATRIX: Readonly<{
   readonly nameTree: "lazy-first-originating-field-transaction";
   readonly field: Readonly<{
@@ -133,14 +265,14 @@ declare const SCRIPT_EVENT_MATRIX: Readonly<{
     calculate: "execute-in-calculation-order";
     format: "execute-after-value-calculation";
   }>;
-  readonly openAction: "preserve-only";
-  readonly page: "preserve-only";
-  readonly catalogLifecycle: "preserve-only";
+  readonly openAction: "execute-lifecycle";
+  readonly page: "execute-lifecycle";
+  readonly catalogLifecycle: "execute-on-verb";
   readonly annotation: Readonly<{
     widgetActivate: "execute-on-originating-client";
-    other: "preserve-only";
+    other: "execute-full-matrix";
   }>;
-  readonly submitForm: "blocked";
+  readonly submitForm: "sink-chain";
 }>;
 /** Functions installed into the isolated VM global by `PRELUDE_SOURCE`. */
 interface AcroJsVmGlobal {
@@ -148,6 +280,99 @@ interface AcroJsVmGlobal {
   __acrojsRun(source: string, input: ScriptInput, budget?: Pick<ScriptBudget, 'maxEffects'>): ScriptOutput;
 }
 //#endregion
+//#region src/color.d.ts
+/**
+ * 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
+ * self-contained); `prelude.test.ts` pins the two implementations together.
+ *
+ * Conversion vectors (the documented Acrobat semantics):
+ *   G → RGB: replicate the gray component.
+ *   CMYK → RGB: component = 1 − min(1, channel + k).
+ *   RGB → G: luminosity 0.3r + 0.59g + 0.11b.
+ *   RGB → CMYK: k = 1 − max(r,g,b); channels = 1 − component − k.
+ *   T (transparent) converts to itself only.
+ */
+declare function scriptColorToRgb(color: ScriptColorArray): {
+  r: number;
+  g: number;
+  b: number;
+} | null;
+/** Acrobat array → CSS hex, or null for transparent. */
+declare function scriptColorToCss(color: ScriptColorArray): string | null;
+/** CSS hex (#rgb/#rrggbb) → Acrobat RGB array; null/undefined → transparent. */
+declare function cssToScriptColor(css: string | null | undefined): ScriptColorArray;
+/** Structural validation for values scripts assign. */
+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
+ *  plane, the event). Document/identity/environment come from the host. */
+interface ScriptWorldInput {
+  fields: ScriptFieldInput[];
+  annots?: ScriptAnnotInput[];
+  annotPages?: number[];
+  annotsCoverDocument?: boolean;
+  /** Zero-based current page for `this.pageNum` — overrides the host's
+   *  document input (the form pipeline anchors it on the target field). */
+  pageNumber?: number;
+  event: ScriptEventInput;
+}
+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 —
+   * 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. */
+  run(program: string, world: ScriptWorldInput, budget?: ScriptBudget): Promise<ScriptOutput>;
+}
+interface ScriptHostOptions {
+  sandboxFactory: ScriptSandboxFactory;
+  document: () => ScriptDocumentInput;
+  identity: () => ScriptIdentity;
+  /** Deterministic environment per run; `sequence` is the host's monotonic
+   *  run counter (seed derivation — see {@link seedFrom}). */
+  environment: (sequence: number) => ScriptEnvironment;
+  /** Name-tree programs, fetched lazily once per realm build. */
+  bootSources: () => Promise<string[]>;
+  budget?: ScriptBudget;
+}
+/**
+ * The ONE realm per document (umbrella law #5): 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
+ * for one logical script transaction — world prefetch, VM run(s), document
+ * 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,
+ * and commit sinks called inside the body never re-enter it.
+ *
+ * Fault ladder: a sandbox that reports itself disposed (interrupt/memory
+ * faults) poisons the realm for the REST of the current transaction; the
+ * next transaction rebuilds it lazily and re-runs the boot. Boot errors
+ * degrade (diagnose, continue) — they never brick scripting.
+ */
+interface ScriptHost {
+  transaction<T>(body: (txn: ScriptTransaction) => Promise<T>): Promise<T>;
+  dispose(): void;
+}
+/** FNV-1a over `documentId:sequence` — the deterministic default random seed
+ *  (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. */
+declare function resolveScriptIdentity(doc: DocumentHandle, overrides?: Partial<ScriptIdentity> | (() => Partial<ScriptIdentity>)): ScriptIdentity;
+declare function createScriptHost(options: ScriptHostOptions): ScriptHost;
+//#endregion
 //#region src/input.d.ts
 /** Build the VM's detached field view from the engine's lossless snapshot. */
 declare function scriptFieldsFromSnapshot(snapshot: FormSnapshot): ScriptFieldInput[];
@@ -164,5 +389,5 @@ declare function installAcroJs(g: Record<string, unknown>): void;
 /** The exact self-contained source evaluated in Node parity tests and QuickJS. */
 declare const PRELUDE_SOURCE: string;
 //#endregion
-export { type AcroJsVmGlobal, DEFAULT_SCRIPT_BUDGET, DEFAULT_SCRIPT_SECURITY_POLICY, PRELUDE_SOURCE, SCRIPT_EVENT_MATRIX, type ScriptBudget, type ScriptDiagnostic, type ScriptDiagnosticCode, type ScriptDocumentInput, type ScriptEnvironment, type ScriptEventInput, type ScriptEventKind, type ScriptEventOutput, type ScriptExecutionError, type ScriptFieldInput, type ScriptFieldOption, type ScriptIdentity, type ScriptInput, type ScriptOutput, type ScriptSecurityPolicy, type ScriptUiEffect, type ScriptValue, installAcroJs, javaScriptProgramFromActionTree, javaScriptSourcesFromActionTree, scriptFieldsFromSnapshot };
+export { ANNOT_WRITABLE_KEYS, type AcroJsVmGlobal, DEFAULT_SCRIPT_BUDGET, DEFAULT_SCRIPT_SECURITY_POLICY, PRELUDE_SOURCE, SCRIPT_EVENT_MATRIX, type ScriptAnnotEffect, type ScriptAnnotInput, type ScriptBudget, type ScriptColorArray, type ScriptDiagnostic, type ScriptDiagnosticCode, type ScriptDocumentInput, type ScriptEnvironment, type ScriptEventInput, type ScriptEventKind, type ScriptEventOutput, type ScriptExecutionError, type ScriptFieldInput, type ScriptFieldOption, type ScriptHost, type ScriptHostOptions, type ScriptIdentity, type ScriptInput, type ScriptOutput, type ScriptSandbox, type ScriptSandboxFactory, type ScriptSecurityPolicy, type ScriptTransaction, type ScriptUiEffect, type ScriptValue, type ScriptWorldInput, createScriptHost, cssToScriptColor, installAcroJs, isScriptColorArray, javaScriptProgramFromActionTree, javaScriptSourcesFromActionTree, resolveScriptIdentity, scriptColorToCss, scriptColorToRgb, scriptFieldsFromSnapshot, seedFrom };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { FormEffect, FormFieldDisplay, FormFieldFamily, FormFieldRef, FormSnapshot, PdfActionTree } from "@embedpdf/engine-core/runtime";
+import { AnnotationRef, DocumentHandle, FormEffect, FormFieldDisplay, FormFieldFamily, FormFieldRef, FormSnapshot, PdfActionTree } from "@embedpdf/engine-core/runtime";
 //#region src/actions.d.ts
 /**
  * Return executable JavaScript in PDF action order (root, then `/Next`
@@ -50,6 +50,15 @@ interface ScriptEnvironment {
 type ScriptEventKind = 'name-tree-boot' | 'widget-activate' | 'field-keystroke' | 'field-validate' | 'field-calculate' | 'field-format';
 interface ScriptEventInput {
   kind: ScriptEventKind;
+  /**
+   * 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,
+   * Acrobat has no event type for plain-annotation events). When omitted the
+   * prelude derives them from `kind` (the K/V/C/F pipeline path).
+   */
+  type?: string;
+  name?: string;
   target?: FormFieldRef;
   source?: FormFieldRef;
   value?: ScriptValue;
@@ -60,12 +69,95 @@ interface ScriptEventInput {
   modifier?: boolean;
   shift?: boolean;
 }
+/**
+ * An Acrobat color: `['T']` transparent, `['G', g]`, `['RGB', r, g, b]`,
+ * `['CMYK', c, m, y, k]` — components 0..1. The wire format scripts read and
+ * write; conversion to renderer/engine colors happens host-side (color.ts).
+ */
+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`
+ * objects; here they are separate event planes). Curated read surface only —
+ * never a raw dictionary.
+ */
+interface ScriptAnnotInput {
+  ref: AnnotationRef;
+  /** `/NM` — the `getAnnot(nPage, name)` key. Empty when the PDF has none. */
+  name: string;
+  /** The engine subtype (e.g. `'square'`). */
+  subtype: string;
+  /** Zero-based page index (Acrobat's `page`). */
+  page: number;
+  /** PDF-space `[llx, lly, urx, ury]`. */
+  rect: [number, number, number, number];
+  contents: string;
+  /** `/T` author and `/Subj` — read-only in v1 (collab identity stamping). */
+  author: string;
+  subject: string;
+  strokeColor: ScriptColorArray;
+  fillColor: ScriptColorArray;
+  opacity: number;
+  /** `/BS /W` border width in points. */
+  width: number;
+  /** Border style: `'S'` solid or `'D'` dashed. */
+  borderStyle: 'S' | 'D';
+  dash: number[];
+  hidden: boolean;
+  print: boolean;
+  readOnly: boolean;
+  locked: boolean;
+  noView: boolean;
+  toggleNoView: boolean;
+  /** True for kinds whose appearance cannot be re-derived from properties
+   *  (stamps, images): appearance writes are refused with a diagnostic. */
+  opaqueBody: boolean;
+}
+/** 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. */
+interface ScriptAnnotEffect {
+  ref: AnnotationRef;
+  patch: {
+    strokeColor?: ScriptColorArray;
+    fillColor?: ScriptColorArray;
+    opacity?: number;
+    width?: number;
+    borderStyle?: 'S' | 'D';
+    dash?: number[];
+    rect?: [number, number, number, number];
+    contents?: string;
+    flags?: Partial<{
+      hidden: boolean;
+      print: boolean;
+      readOnly: boolean;
+      locked: boolean;
+      noView: boolean;
+      toggleNoView: boolean;
+    }>;
+  };
+}
+/**
+ * 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
+ * script-addressable; appearance keys vary by kind.
+ */
+declare const ANNOT_WRITABLE_KEYS: Readonly<Record<string, readonly string[]>>;
 /** Complete input for one deterministic run. No ambient host values are read. */
 interface ScriptInput {
   document: ScriptDocumentInput;
   identity: ScriptIdentity;
   environment: ScriptEnvironment;
   fields: ScriptFieldInput[];
+  /** The prefetched annots plane (page-scoped — see the D6 deviation). */
+  annots?: ScriptAnnotInput[];
+  /** Zero-based page indexes the plane covers. */
+  annotPages?: number[];
+  /** True when annotPages spans the whole document (no scope diagnostic). */
+  annotsCoverDocument?: boolean;
   event: ScriptEventInput;
 }
 type ScriptUiEffect = {
@@ -78,12 +170,36 @@ type ScriptUiEffect = {
 } | {
   kind: 'gotoPage';
   page: number;
+} |
+/** `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. */
+{
+  kind: 'submitForm';
+  url: string | null;
+  fieldNames: string[] | null;
+  includeEmpty: boolean;
+  format?: 'fdf' | 'html' | 'xfdf' | 'pdf';
+  method?: 'post' | 'get';
 };
-type ScriptDiagnosticCode = 'blocked-network' | 'unsupported-api' | 'invalid-field-value' | 'script-error';
+type ScriptDiagnosticCode = 'blocked-network' | 'unsupported-api' | 'invalid-field-value' | 'script-error' | 'ui-effect-suppressed';
 interface ScriptDiagnostic {
   code: ScriptDiagnosticCode;
   message: string;
 }
+/** One isolated, stateful Acrobat-JavaScript realm for one PDF document. */
+interface ScriptSandbox {
+  /** True after explicit disposal or a resource/runtime fault. */
+  readonly disposed: boolean;
+  /** Evaluate document name-tree sources once. Top-level effects are returned
+   *  so the orchestrator can include them in the first transaction. */
+  boot(sources: string[], input: ScriptInput, budget?: ScriptBudget): ScriptOutput;
+  /** Run one event program against the realm's persistent globals. */
+  run(source: string, input: ScriptInput, budget?: ScriptBudget): ScriptOutput;
+  /** Release the realm. Idempotent. */
+  dispose(): void;
+}
+type ScriptSandboxFactory = () => Promise<ScriptSandbox>;
 interface ScriptExecutionError {
   kind: 'exception' | 'budget' | 'invalid-output';
   message: string;
@@ -96,10 +212,16 @@ interface ScriptEventOutput {
   selStart: number;
   selEnd: number;
 }
-/** Effects are committed only by the originating client's orchestrator. */
+/**
+ * Effects are committed only by the originating client's orchestrator, in
+ * 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.
+ */
 interface ScriptOutput {
   event: ScriptEventOutput;
   formEffects: FormEffect[];
+  annotEffects: ScriptAnnotEffect[];
   uiEffects: ScriptUiEffect[];
   diagnostics: ScriptDiagnostic[];
   error?: ScriptExecutionError;
@@ -112,19 +234,29 @@ interface ScriptBudget {
   maxOutputBytes: number;
 }
 declare const DEFAULT_SCRIPT_BUDGET: Readonly<ScriptBudget>;
-/** V1 security posture. The only configurable switch is explicit opt-in. */
+/**
+ * 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
+ * configurable switch is explicit opt-in.
+ */
 interface ScriptSecurityPolicy {
   enabled: boolean;
   executionOwner: 'originating-client-only';
   nameTreeBoot: 'lazy-first-transaction';
-  submitForm: 'blocked';
-  openAction: 'preserve-only';
-  pageActions: 'preserve-only';
-  catalogLifecycleActions: 'preserve-only';
-  annotationActions: 'widget-activate-only';
+  /** 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. */
+  catalogLifecycleActions: 'execute-on-verb';
+  annotationActions: 'execute-full-matrix';
 }
 declare const DEFAULT_SCRIPT_SECURITY_POLICY: Readonly<ScriptSecurityPolicy>;
-/** Frozen V1 dispatch matrix; extracted actions outside it remain data only. */
+/** The shipped dispatch matrix; extracted actions outside it remain data
+ *  only. (Historical note: v1 froze everything beyond K/V/C/F as
+ *  preserve-only; phases 1–4 executed the rest.) */
 declare const SCRIPT_EVENT_MATRIX: Readonly<{
   readonly nameTree: "lazy-first-originating-field-transaction";
   readonly field: Readonly<{
@@ -133,14 +265,14 @@ declare const SCRIPT_EVENT_MATRIX: Readonly<{
     calculate: "execute-in-calculation-order";
     format: "execute-after-value-calculation";
   }>;
-  readonly openAction: "preserve-only";
-  readonly page: "preserve-only";
-  readonly catalogLifecycle: "preserve-only";
+  readonly openAction: "execute-lifecycle";
+  readonly page: "execute-lifecycle";
+  readonly catalogLifecycle: "execute-on-verb";
   readonly annotation: Readonly<{
     widgetActivate: "execute-on-originating-client";
-    other: "preserve-only";
+    other: "execute-full-matrix";
   }>;
-  readonly submitForm: "blocked";
+  readonly submitForm: "sink-chain";
 }>;
 /** Functions installed into the isolated VM global by `PRELUDE_SOURCE`. */
 interface AcroJsVmGlobal {
@@ -148,6 +280,99 @@ interface AcroJsVmGlobal {
   __acrojsRun(source: string, input: ScriptInput, budget?: Pick<ScriptBudget, 'maxEffects'>): ScriptOutput;
 }
 //#endregion
+//#region src/color.d.ts
+/**
+ * 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
+ * self-contained); `prelude.test.ts` pins the two implementations together.
+ *
+ * Conversion vectors (the documented Acrobat semantics):
+ *   G → RGB: replicate the gray component.
+ *   CMYK → RGB: component = 1 − min(1, channel + k).
+ *   RGB → G: luminosity 0.3r + 0.59g + 0.11b.
+ *   RGB → CMYK: k = 1 − max(r,g,b); channels = 1 − component − k.
+ *   T (transparent) converts to itself only.
+ */
+declare function scriptColorToRgb(color: ScriptColorArray): {
+  r: number;
+  g: number;
+  b: number;
+} | null;
+/** Acrobat array → CSS hex, or null for transparent. */
+declare function scriptColorToCss(color: ScriptColorArray): string | null;
+/** CSS hex (#rgb/#rrggbb) → Acrobat RGB array; null/undefined → transparent. */
+declare function cssToScriptColor(css: string | null | undefined): ScriptColorArray;
+/** Structural validation for values scripts assign. */
+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
+ *  plane, the event). Document/identity/environment come from the host. */
+interface ScriptWorldInput {
+  fields: ScriptFieldInput[];
+  annots?: ScriptAnnotInput[];
+  annotPages?: number[];
+  annotsCoverDocument?: boolean;
+  /** Zero-based current page for `this.pageNum` — overrides the host's
+   *  document input (the form pipeline anchors it on the target field). */
+  pageNumber?: number;
+  event: ScriptEventInput;
+}
+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 —
+   * 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. */
+  run(program: string, world: ScriptWorldInput, budget?: ScriptBudget): Promise<ScriptOutput>;
+}
+interface ScriptHostOptions {
+  sandboxFactory: ScriptSandboxFactory;
+  document: () => ScriptDocumentInput;
+  identity: () => ScriptIdentity;
+  /** Deterministic environment per run; `sequence` is the host's monotonic
+   *  run counter (seed derivation — see {@link seedFrom}). */
+  environment: (sequence: number) => ScriptEnvironment;
+  /** Name-tree programs, fetched lazily once per realm build. */
+  bootSources: () => Promise<string[]>;
+  budget?: ScriptBudget;
+}
+/**
+ * The ONE realm per document (umbrella law #5): 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
+ * for one logical script transaction — world prefetch, VM run(s), document
+ * 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,
+ * and commit sinks called inside the body never re-enter it.
+ *
+ * Fault ladder: a sandbox that reports itself disposed (interrupt/memory
+ * faults) poisons the realm for the REST of the current transaction; the
+ * next transaction rebuilds it lazily and re-runs the boot. Boot errors
+ * degrade (diagnose, continue) — they never brick scripting.
+ */
+interface ScriptHost {
+  transaction<T>(body: (txn: ScriptTransaction) => Promise<T>): Promise<T>;
+  dispose(): void;
+}
+/** FNV-1a over `documentId:sequence` — the deterministic default random seed
+ *  (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. */
+declare function resolveScriptIdentity(doc: DocumentHandle, overrides?: Partial<ScriptIdentity> | (() => Partial<ScriptIdentity>)): ScriptIdentity;
+declare function createScriptHost(options: ScriptHostOptions): ScriptHost;
+//#endregion
 //#region src/input.d.ts
 /** Build the VM's detached field view from the engine's lossless snapshot. */
 declare function scriptFieldsFromSnapshot(snapshot: FormSnapshot): ScriptFieldInput[];
@@ -164,5 +389,5 @@ declare function installAcroJs(g: Record<string, unknown>): void;
 /** The exact self-contained source evaluated in Node parity tests and QuickJS. */
 declare const PRELUDE_SOURCE: string;
 //#endregion
-export { type AcroJsVmGlobal, DEFAULT_SCRIPT_BUDGET, DEFAULT_SCRIPT_SECURITY_POLICY, PRELUDE_SOURCE, SCRIPT_EVENT_MATRIX, type ScriptBudget, type ScriptDiagnostic, type ScriptDiagnosticCode, type ScriptDocumentInput, type ScriptEnvironment, type ScriptEventInput, type ScriptEventKind, type ScriptEventOutput, type ScriptExecutionError, type ScriptFieldInput, type ScriptFieldOption, type ScriptIdentity, type ScriptInput, type ScriptOutput, type ScriptSecurityPolicy, type ScriptUiEffect, type ScriptValue, installAcroJs, javaScriptProgramFromActionTree, javaScriptSourcesFromActionTree, scriptFieldsFromSnapshot };
+export { ANNOT_WRITABLE_KEYS, type AcroJsVmGlobal, DEFAULT_SCRIPT_BUDGET, DEFAULT_SCRIPT_SECURITY_POLICY, PRELUDE_SOURCE, SCRIPT_EVENT_MATRIX, type ScriptAnnotEffect, type ScriptAnnotInput, type ScriptBudget, type ScriptColorArray, type ScriptDiagnostic, type ScriptDiagnosticCode, type ScriptDocumentInput, type ScriptEnvironment, type ScriptEventInput, type ScriptEventKind, type ScriptEventOutput, type ScriptExecutionError, type ScriptFieldInput, type ScriptFieldOption, type ScriptHost, type ScriptHostOptions, type ScriptIdentity, type ScriptInput, type ScriptOutput, type ScriptSandbox, type ScriptSandboxFactory, type ScriptSecurityPolicy, type ScriptTransaction, type ScriptUiEffect, type ScriptValue, type ScriptWorldInput, createScriptHost, cssToScriptColor, installAcroJs, isScriptColorArray, javaScriptProgramFromActionTree, javaScriptSourcesFromActionTree, resolveScriptIdentity, scriptColorToCss, scriptColorToRgb, scriptFieldsFromSnapshot, seedFrom };
 //# sourceMappingURL=index.d.ts.map