@embedpdf/plugin-actions 3.0.0-next.14 → 3.0.0-next.16

package/dist/host-contract-BbODswDs.d.ts

@@ -0,0 +1,165 @@
+import { B as SubmitIntent, T as ActionsCapability, d as ActionOrigin, h as ActionSource, n as ActionContext, r as ActionDiagnostic, v as ActionSubmitRequest } from "./contract-Cn-7mBY8.js";
+import { DocumentMeta, Unsubscribe } from "@embedpdf/core";
+import { DocumentHandle, FormEffect, FormSnapshot, PageRef } from "@embedpdf/engine-core/runtime";
+import { ScriptAnnotEffect, ScriptBudget, ScriptDiagnostic, ScriptExecutionError, ScriptTransaction, ScriptUiEffect } from "@embedpdf/core-acrojs";
+//#region src/host-contract.d.ts
+/**
+ * The stage's page-truth report, the one door into the lifecycle
+ * coordinator. The stage stays authoritative for what page the viewer is on;
+ * the coordinator owns when page-lifecycle triggers fire: reports are
+ * buffered until the document-open sequence has run and diffed against the
+ * last-emitted state, so pre-open motion (a restored view, the open
+ * destination's reveal) never emits close and open churn. `cause` feeds the
+ * cascade budget: consecutive programmatic rounds are capped, and a
+ * user-caused report resets the count.
+ */
+interface PageStateReport {
+  currentPage: PageRef | null;
+  visiblePages: readonly PageRef[];
+  /** False until layout exists; pre-placement reports are ignored. */
+  placed: boolean;
+  cause: 'user' | 'programmatic';
+}
+/** One annotation-effect commit entry. `page` may be absent for bare Hide
+ *  object-number targets: the sink resolves it from its model (`obj:N` is a
+ *  cross-page key there), and entries it cannot resolve fail. */
+interface AnnotCommitEntry {
+  annotObjectNumber: number;
+  page?: PageRef;
+  patch: ScriptAnnotEffect['patch'];
+}
+interface AnnotCommitResult {
+  results: Array<{
+    annotObjectNumber: number;
+    status: 'applied' | 'failed' | 'skipped';
+    error?: string;
+  }>;
+}
+type AnnotCommitSink = (entries: AnnotCommitEntry[]) => Promise<AnnotCommitResult>;
+/**
+ * What the form plugin's commit did: `applied`, the effects are one change on its way (shown at
+ * once; the engine's refusal comes through the change queue); `failed`, none of them is.
+ */
+interface FormCommitSinkResult {
+  status: 'applied' | 'failed';
+  /** Why the change couldn't be made, when it couldn't. */
+  error?: string;
+}
+/** The form plugin's document commit: a script run's form effects, written as one change. */
+type FormCommitSink = (effects: FormEffect[]) => Promise<FormCommitSinkResult>;
+/**
+ * The form as the user sees it: the form plugin's fields and widgets with this session's pending
+ * fills, or `null` before it has read the form. What scripts and dispatch read instead of the
+ * engine, so they see a fill before the engine answers it.
+ */
+type FormReader = () => FormSnapshot | null;
+/**
+ * Which realm produced a script result. `'document'` = this document's own
+ * realm: every effect targets the viewer document. `'detached'` = a realm
+ * minted for a document that is not displayed (a stamp asset): it has no
+ * document surface, so only alerts reach the adapter — print, page
+ * navigation, and submit are suppressed with a diagnostic rather than
+ * acting on the wrong document.
+ */
+type ScriptRealmKind = 'document' | 'detached';
+/** What a script transaction surfaced besides document effects. */
+interface ScriptSurfaceResult {
+  uiEffects: ScriptUiEffect[];
+  diagnostics: ScriptDiagnostic[];
+  error?: ScriptExecutionError;
+  origin: ActionOrigin;
+  phase: 'boot' | 'user';
+  realm: ScriptRealmKind;
+  /** What started the script, when an action did: `onScriptFailed` and diagnostics carry it. */
+  source?: ActionSource;
+}
+/** A K/V/C/F transaction's result as the form controller reports it: effects
+ *  carry their own phase (boot effects belong to the first transaction that
+ *  lazily booted the realm). Structurally the surface half of the form
+ *  plugin's commit result, typed here so the actions plane never imports the
+ *  form package. */
+interface ScriptCommitSurface {
+  uiEffects: Array<ScriptUiEffect & {
+    phase: 'boot' | 'user';
+  }>;
+  diagnostics: ScriptDiagnostic[];
+  error?: ScriptExecutionError;
+}
+/** What a realm is minted for. `doc` is the document the scripts operate on
+ *  (the viewer document, or a detached asset); `document()` is the metadata
+ *  scripts observe (`this.documentFileName` …): for a detached stamp that is
+ *  the target document's, matching Acrobat's dynamic stamps. */
+/** What a script realm reads of the document it runs for. */
+type ScriptDocument = Pick<DocumentMeta, 'name' | 'pageCount' | 'pages'>;
+interface ScriptRealmTarget {
+  doc: DocumentHandle;
+  document(): ScriptDocument | null;
+  /** Name-tree programs, fetched lazily once per realm build. */
+  bootSources(): Promise<string[]>;
+}
+/** The realm transaction port plus the budget consumers apply as their
+ *  transaction aggregate: the same shape whether the realm is this document's
+ *  own (owned by actions) or a detached one (owned by the caller). */
+interface ScriptRealmPort {
+  /** The body must perform prefetch, runs, sink commits and reconciliation
+   *  before returning: commits happen inside the transaction. */
+  transaction<T>(body: (transaction: ScriptTransaction) => Promise<T>): Promise<T>;
+  budget: ScriptBudget;
+}
+/** A detached realm: the caller owns its lifetime. */
+interface DetachedScriptRealm extends ScriptRealmPort {
+  dispose(): void;
+}
+/** The form plugin's dataset resolver, registered on the host lens.
+ *  `diagnose` is the per-entry observability channel: an explicitly listed
+ *  push-button, signature or unsupported value is diagnosed as
+ *  `submit-entry-unsupported`, never silently dropped. */
+type SubmitResolver = (intent: SubmitIntent, actionContext: ActionContext, diagnose: (diagnostic: ActionDiagnostic) => void) => Promise<ActionSubmitRequest>;
+/** The host lens, plugin-to-plugin only: import the token from
+ *  `@embedpdf/plugin-actions/contract/host`, never from application code. */
+interface ActionsHostCapability extends ActionsCapability {
+  /** The annotation plugin's commit sink for script and Hide annotation effects. Identity-safe. */
+  registerAnnotCommitSink(sink: AnnotCommitSink): Unsubscribe;
+  /** The form plugin's commit sink for script and Hide form effects. Identity-safe. */
+  registerFormCommitSink(sink: FormCommitSink): Unsubscribe;
+  /** The form plugin's form, which scripts and dispatch read; without one they read the engine. Identity-safe. */
+  registerFormReader(reader: FormReader): Unsubscribe;
+  /**
+   * This document's realm, present only when `javascript.enabled` (its
+   * presence is the form plugin's "scripting on" signal).
+   */
+  scriptRealm?: ScriptRealmPort;
+  /**
+   * Mint a realm for a detached document under this document's policy and
+   * environment (the same sandbox factory, identity, clock and budget; a
+   * fresh sandbox, so isolated globals). Present only when
+   * `javascript.enabled`, like `scriptRealm`. The caller owns the returned
+   * realm's lifetime and surfaces its results with `realm: 'detached'`.
+   */
+  createDetachedScriptRealm?(target: ScriptRealmTarget): DetachedScriptRealm;
+  /** Surface a script transaction's UI effects, diagnostics and error through
+   *  the one port (the adapter matrix, the authority print gate, the script
+   *  events). */
+  surfaceScriptResult(result: ScriptSurfaceResult): void;
+  /** Surface a K/V/C/F commit result: splits boot-phase and user-phase
+   *  effects into their own surfaces (diagnostics and the error ride the
+   *  user phase); the one place that split lives. */
+  surfaceScriptCommit(commit: ScriptCommitSurface, context: {
+    origin: ActionOrigin;
+    realm: ScriptRealmKind;
+    source?: ActionSource;
+  }): void;
+  /** The stage's page-truth report (see {@link PageStateReport}). */
+  reportPageState(report: PageStateReport): void;
+  /**
+   * The form plugin's dataset resolver: both submit sources (action nodes
+   * and script `doc.submitForm()` effects) normalize to a
+   * {@link SubmitIntent} and resolve through this one door. Identity-safe;
+   * without it every submit blocks with `no-submit-resolver`.
+   */
+  registerSubmitResolver(resolver: SubmitResolver): Unsubscribe;
+}
+declare const ActionsToken: import("@embedpdf/core").CapabilityToken<ActionsHostCapability>;
+//#endregion
+export { SubmitResolver as _, AnnotCommitSink as a, FormCommitSinkResult as c, ScriptCommitSurface as d, ScriptDocument as f, ScriptSurfaceResult as g, ScriptRealmTarget as h, AnnotCommitResult as i, FormReader as l, ScriptRealmPort as m, ActionsToken as n, DetachedScriptRealm as o, ScriptRealmKind as p, AnnotCommitEntry as r, FormCommitSink as s, ActionsHostCapability as t, PageStateReport as u };
+//# sourceMappingURL=host-contract-BbODswDs.d.ts.map

package/dist/host-contract-D22Gz-qt.d.cts

@@ -0,0 +1,165 @@
+import { B as SubmitIntent, T as ActionsCapability, d as ActionOrigin, h as ActionSource, n as ActionContext, r as ActionDiagnostic, v as ActionSubmitRequest } from "./contract-BTPW8b4L.cjs";
+import { DocumentMeta, Unsubscribe } from "@embedpdf/core";
+import { ScriptAnnotEffect, ScriptBudget, ScriptDiagnostic, ScriptExecutionError, ScriptTransaction, ScriptUiEffect } from "@embedpdf/core-acrojs";
+import { DocumentHandle, FormEffect, FormSnapshot, PageRef } from "@embedpdf/engine-core/runtime";
+//#region src/host-contract.d.ts
+/**
+ * The stage's page-truth report, the one door into the lifecycle
+ * coordinator. The stage stays authoritative for what page the viewer is on;
+ * the coordinator owns when page-lifecycle triggers fire: reports are
+ * buffered until the document-open sequence has run and diffed against the
+ * last-emitted state, so pre-open motion (a restored view, the open
+ * destination's reveal) never emits close and open churn. `cause` feeds the
+ * cascade budget: consecutive programmatic rounds are capped, and a
+ * user-caused report resets the count.
+ */
+interface PageStateReport {
+  currentPage: PageRef | null;
+  visiblePages: readonly PageRef[];
+  /** False until layout exists; pre-placement reports are ignored. */
+  placed: boolean;
+  cause: 'user' | 'programmatic';
+}
+/** One annotation-effect commit entry. `page` may be absent for bare Hide
+ *  object-number targets: the sink resolves it from its model (`obj:N` is a
+ *  cross-page key there), and entries it cannot resolve fail. */
+interface AnnotCommitEntry {
+  annotObjectNumber: number;
+  page?: PageRef;
+  patch: ScriptAnnotEffect['patch'];
+}
+interface AnnotCommitResult {
+  results: Array<{
+    annotObjectNumber: number;
+    status: 'applied' | 'failed' | 'skipped';
+    error?: string;
+  }>;
+}
+type AnnotCommitSink = (entries: AnnotCommitEntry[]) => Promise<AnnotCommitResult>;
+/**
+ * What the form plugin's commit did: `applied`, the effects are one change on its way (shown at
+ * once; the engine's refusal comes through the change queue); `failed`, none of them is.
+ */
+interface FormCommitSinkResult {
+  status: 'applied' | 'failed';
+  /** Why the change couldn't be made, when it couldn't. */
+  error?: string;
+}
+/** The form plugin's document commit: a script run's form effects, written as one change. */
+type FormCommitSink = (effects: FormEffect[]) => Promise<FormCommitSinkResult>;
+/**
+ * The form as the user sees it: the form plugin's fields and widgets with this session's pending
+ * fills, or `null` before it has read the form. What scripts and dispatch read instead of the
+ * engine, so they see a fill before the engine answers it.
+ */
+type FormReader = () => FormSnapshot | null;
+/**
+ * Which realm produced a script result. `'document'` = this document's own
+ * realm: every effect targets the viewer document. `'detached'` = a realm
+ * minted for a document that is not displayed (a stamp asset): it has no
+ * document surface, so only alerts reach the adapter — print, page
+ * navigation, and submit are suppressed with a diagnostic rather than
+ * acting on the wrong document.
+ */
+type ScriptRealmKind = 'document' | 'detached';
+/** What a script transaction surfaced besides document effects. */
+interface ScriptSurfaceResult {
+  uiEffects: ScriptUiEffect[];
+  diagnostics: ScriptDiagnostic[];
+  error?: ScriptExecutionError;
+  origin: ActionOrigin;
+  phase: 'boot' | 'user';
+  realm: ScriptRealmKind;
+  /** What started the script, when an action did: `onScriptFailed` and diagnostics carry it. */
+  source?: ActionSource;
+}
+/** A K/V/C/F transaction's result as the form controller reports it: effects
+ *  carry their own phase (boot effects belong to the first transaction that
+ *  lazily booted the realm). Structurally the surface half of the form
+ *  plugin's commit result, typed here so the actions plane never imports the
+ *  form package. */
+interface ScriptCommitSurface {
+  uiEffects: Array<ScriptUiEffect & {
+    phase: 'boot' | 'user';
+  }>;
+  diagnostics: ScriptDiagnostic[];
+  error?: ScriptExecutionError;
+}
+/** What a realm is minted for. `doc` is the document the scripts operate on
+ *  (the viewer document, or a detached asset); `document()` is the metadata
+ *  scripts observe (`this.documentFileName` …): for a detached stamp that is
+ *  the target document's, matching Acrobat's dynamic stamps. */
+/** What a script realm reads of the document it runs for. */
+type ScriptDocument = Pick<DocumentMeta, 'name' | 'pageCount' | 'pages'>;
+interface ScriptRealmTarget {
+  doc: DocumentHandle;
+  document(): ScriptDocument | null;
+  /** Name-tree programs, fetched lazily once per realm build. */
+  bootSources(): Promise<string[]>;
+}
+/** The realm transaction port plus the budget consumers apply as their
+ *  transaction aggregate: the same shape whether the realm is this document's
+ *  own (owned by actions) or a detached one (owned by the caller). */
+interface ScriptRealmPort {
+  /** The body must perform prefetch, runs, sink commits and reconciliation
+   *  before returning: commits happen inside the transaction. */
+  transaction<T>(body: (transaction: ScriptTransaction) => Promise<T>): Promise<T>;
+  budget: ScriptBudget;
+}
+/** A detached realm: the caller owns its lifetime. */
+interface DetachedScriptRealm extends ScriptRealmPort {
+  dispose(): void;
+}
+/** The form plugin's dataset resolver, registered on the host lens.
+ *  `diagnose` is the per-entry observability channel: an explicitly listed
+ *  push-button, signature or unsupported value is diagnosed as
+ *  `submit-entry-unsupported`, never silently dropped. */
+type SubmitResolver = (intent: SubmitIntent, actionContext: ActionContext, diagnose: (diagnostic: ActionDiagnostic) => void) => Promise<ActionSubmitRequest>;
+/** The host lens, plugin-to-plugin only: import the token from
+ *  `@embedpdf/plugin-actions/contract/host`, never from application code. */
+interface ActionsHostCapability extends ActionsCapability {
+  /** The annotation plugin's commit sink for script and Hide annotation effects. Identity-safe. */
+  registerAnnotCommitSink(sink: AnnotCommitSink): Unsubscribe;
+  /** The form plugin's commit sink for script and Hide form effects. Identity-safe. */
+  registerFormCommitSink(sink: FormCommitSink): Unsubscribe;
+  /** The form plugin's form, which scripts and dispatch read; without one they read the engine. Identity-safe. */
+  registerFormReader(reader: FormReader): Unsubscribe;
+  /**
+   * This document's realm, present only when `javascript.enabled` (its
+   * presence is the form plugin's "scripting on" signal).
+   */
+  scriptRealm?: ScriptRealmPort;
+  /**
+   * Mint a realm for a detached document under this document's policy and
+   * environment (the same sandbox factory, identity, clock and budget; a
+   * fresh sandbox, so isolated globals). Present only when
+   * `javascript.enabled`, like `scriptRealm`. The caller owns the returned
+   * realm's lifetime and surfaces its results with `realm: 'detached'`.
+   */
+  createDetachedScriptRealm?(target: ScriptRealmTarget): DetachedScriptRealm;
+  /** Surface a script transaction's UI effects, diagnostics and error through
+   *  the one port (the adapter matrix, the authority print gate, the script
+   *  events). */
+  surfaceScriptResult(result: ScriptSurfaceResult): void;
+  /** Surface a K/V/C/F commit result: splits boot-phase and user-phase
+   *  effects into their own surfaces (diagnostics and the error ride the
+   *  user phase); the one place that split lives. */
+  surfaceScriptCommit(commit: ScriptCommitSurface, context: {
+    origin: ActionOrigin;
+    realm: ScriptRealmKind;
+    source?: ActionSource;
+  }): void;
+  /** The stage's page-truth report (see {@link PageStateReport}). */
+  reportPageState(report: PageStateReport): void;
+  /**
+   * The form plugin's dataset resolver: both submit sources (action nodes
+   * and script `doc.submitForm()` effects) normalize to a
+   * {@link SubmitIntent} and resolve through this one door. Identity-safe;
+   * without it every submit blocks with `no-submit-resolver`.
+   */
+  registerSubmitResolver(resolver: SubmitResolver): Unsubscribe;
+}
+declare const ActionsToken: import("@embedpdf/core").CapabilityToken<ActionsHostCapability>;
+//#endregion
+export { SubmitResolver as _, AnnotCommitSink as a, FormCommitSinkResult as c, ScriptCommitSurface as d, ScriptDocument as f, ScriptSurfaceResult as g, ScriptRealmTarget as h, AnnotCommitResult as i, FormReader as l, ScriptRealmPort as m, ActionsToken as n, DetachedScriptRealm as o, ScriptRealmKind as p, AnnotCommitEntry as r, FormCommitSink as s, ActionsHostCapability as t, PageStateReport as u };
+//# sourceMappingURL=host-contract-D22Gz-qt.d.cts.map