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

package/dist/contract-Cn-7mBY8.d.ts

@@ -0,0 +1,557 @@
+import { DeepPartial, EventHook, OperationOptions, SettingsApi, Unsubscribe } from "@embedpdf/core";
+import { AnnotationRef, FormFieldRef, FormSubmissionEntry, FormSubmissionReceipt, OutlineItemRef, PageRef, PdfActionNode, PdfActionNode as PdfActionNode$1, PdfActionTargetRef, PdfActionTree, PdfActionTree as PdfActionTree$1, PdfActionType, PdfActionType as PdfActionType$1 } from "@embedpdf/engine-core/runtime";
+import { ScriptBudget, ScriptDiagnostic, ScriptExecutionError, ScriptIdentity, ScriptSandboxFactory } from "@embedpdf/core-acrojs";
+//#region src/token.d.ts
+declare const ActionsToken: import("@embedpdf/core").CapabilityToken<ActionsCapability>;
+//#endregion
+//#region src/hover-pump.d.ts
+/** One hoverable target, as a feed sees it. `events` lets a feed that knows
+ *  which trees exist (a folded model, a fill item) skip the inert half of a
+ *  pair; omitted flags default to true. */
+interface HoverTarget {
+  ref: AnnotationRef;
+  page: PageRef;
+  /** Optional provenance hint forwarded on the trigger (widget/link feeds). */
+  source?: ActionSource;
+  events?: {
+    enter?: boolean;
+    exit?: boolean;
+  };
+}
+interface HoverPump {
+  /** Report where the pointer is now (null = nowhere interesting). */
+  hover(target: HoverTarget | null): void;
+  /** Forget everything without dispatching (teardown; document switch). */
+  reset(): void;
+}
+/**
+ * The one hover state machine every event plane shares: per pointer feed,
+ * `{ delivered, desired, inFlight }`. On each settle it delivers the
+ * transition `delivered → desired` as `Exit(delivered)` then
+ * `Enter(desired)`, submitted back to back synchronously: dispatch takes its
+ * queue slot before returning, so a slow resolution can never split or
+ * reorder the pair. Under pressure intermediate targets are skipped by
+ * design: the pointer sweeping A→B→C while A's exit is in flight delivers
+ * `Exit(A) → Enter(C)`, never a stale `Enter(B)`.
+ */
+declare function createHoverPump(dispatch: (trigger: ActionTrigger) => Promise<ActionTriggerResult>): HoverPump;
+//#endregion
+//#region src/submit-encoding.d.ts
+/**
+ * Encode a resolved submission dataset as `application/x-www-form-urlencoded`
+ * (UTF-8 — the one encoding this helper speaks; a `/CharSet` other than
+ * utf-8 is the handler's problem). A name-only entry (`value === null`, the
+ * IncludeNoValueFields shape) encodes as a bare name; a multi-select list
+ * box repeats the name per value, the HTML-form convention.
+ *
+ * Pure and dependency-free on purpose: a convenience for embedder handlers,
+ * never called by the plugin itself (the plugin never touches a network).
+ */
+declare const submitEntriesToUrlEncoded: (entries: FormSubmissionEntry[]) => string;
+//#endregion
+//#region src/contract.d.ts
+/** Why a dispatch happened: `'user'` for a real activation gesture,
+ *  `'hover'` for pointer enter and exit, `'lifecycle'` for page and document
+ *  events. The policy decides per type and origin. */
+type ActionOrigin = 'user' | 'hover' | 'lifecycle';
+/** Who initiated the dispatch. Fields are required where an executor needs
+ *  them: the JavaScript executor builds `event.target` from the widget
+ *  source's `field`. Provenance only: policy never reads it. */
+type ActionSource = {
+  kind: 'widget';
+  field: FormFieldRef;
+  annotation: AnnotationRef;
+  page: PageRef;
+} | {
+  kind: 'link';
+  annotation?: AnnotationRef;
+  page?: PageRef;
+} |
+/** An outline item the user followed: its /A, run as a link's is. */
+{
+  kind: 'outline';
+  item: OutlineItemRef;
+} |
+/** A non-widget annotation's own /AA event (E/X on squares, stamps, …). */
+{
+  kind: 'annotation';
+  annotation: AnnotationRef;
+  page: PageRef;
+} |
+/** A page /AA tree (O/C) inside a page-trigger fan-out. */
+{
+  kind: 'page';
+  page: PageRef;
+} |
+/** The document-open sequence (openDestination / OpenAction). */
+{
+  kind: 'document';
+} | {
+  kind: 'api';
+};
+/** The document lifecycle vocabulary: `open` (the document-open sequence)
+ *  plus the five catalog `/AA` verbs (ISO 32000-2 Table 200: /WC, /WS, /DS,
+ *  /WP, /DP). Whoever owns the verb dispatches them; `runDocumentVerb` is the
+ *  serialized door for save and print, `prepareClose` for close. */
+type DocumentTriggerEvent = 'open' | 'will-save' | 'did-save' | 'will-print' | 'did-print' | 'will-close';
+/** Trigger provenance, derived beside {@link triggerOriginOf}: the
+ *  executor-visible "which event fired" (cursorEnter and cursorExit are both
+ *  `origin: 'hover'`; this carries the difference). */
+type ActionTriggerEvent = {
+  scope: 'activate';
+} | {
+  scope: 'annotation';
+  name: PdfAnnotationEventKind;
+} | {
+  scope: 'page';
+  name: 'open' | 'close' | 'visible' | 'invisible';
+} | {
+  scope: 'document';
+  name: DocumentTriggerEvent;
+};
+/** The four field-level /AA scripts (ISO Table 198: K F V C). */
+type PdfFieldEventKind = 'keystroke' | 'format' | 'validate' | 'calculate';
+/** The Named verbs the viewer interprets (ISO Table 215's four page verbs
+ *  plus Adobe's `Print`); any other name is accepted and reported inert. */
+type PdfNamedAction = 'NextPage' | 'PrevPage' | 'FirstPage' | 'LastPage' | 'Print' | (string & {});
+/**
+ * Where an action tree lives, for {@link ActionsCapability.getActionTree}.
+ * Each arm names its own event vocabulary; the annotation arm defaults to
+ * the /A click tree, the page and document arms to their open trees.
+ */
+type ActionTreeSource = {
+  kind: 'annotation';
+  annotation: AnnotationRef;
+  page: PageRef;
+  event?: 'activate' | PdfAnnotationEventKind;
+} | {
+  kind: 'field';
+  field: FormFieldRef;
+  event: PdfFieldEventKind;
+} | {
+  kind: 'page';
+  page: PageRef;
+  event?: 'open' | 'close';
+} | {
+  kind: 'document';
+  event?: DocumentTriggerEvent;
+} |
+/** An outline item's /A. */
+{
+  kind: 'outline';
+  item: OutlineItemRef;
+};
+/** The document-open sequence has run (once per document). */
+interface OpenSequenceCompletedEvent {
+  readonly result: ActionTriggerResult;
+}
+interface ActionContext {
+  origin: ActionOrigin;
+  source: ActionSource;
+  event: ActionTriggerEvent;
+}
+/** The six annotation /AA pointer and focus events (ISO 32000-2 Table 197:
+ *  /E /X /D /U /Fo /Bl). The page-lifecycle events (/PO /PC /PV /PI) are not
+ *  here: they fan out from page triggers, never from per-annotation dispatch. */
+type PdfAnnotationEventKind = 'cursorEnter' | 'cursorExit' | 'mouseDown' | 'mouseUp' | 'focus' | 'blur';
+/**
+ * Trigger vocabulary: what a feed reports. The dispatcher resolves trees,
+ * derives the origin ({@link triggerOriginOf}) and fans out. `source` on the
+ * annotation-addressed arms is an optional provenance hint from first-party
+ * feeds (a widget feed passes its field ref so the JavaScript executor can
+ * anchor `event.target`); policy never reads it and it cannot change origin.
+ */
+type ActionTrigger = {
+  scope: 'activate';
+  ref: AnnotationRef;
+  page: PageRef;
+  source?: ActionSource;
+} | {
+  scope: 'annotation';
+  event: PdfAnnotationEventKind;
+  ref: AnnotationRef;
+  page: PageRef;
+  source?: ActionSource;
+} | {
+  scope: 'page';
+  event: 'open' | 'close' | 'visible' | 'invisible';
+  page: PageRef;
+} | {
+  scope: 'document';
+  event: DocumentTriggerEvent;
+};
+/** Trigger → provenance descriptor (the {@link ActionContext.event} axis). */
+declare const eventOf: (trigger: ActionTrigger) => ActionTriggerEvent;
+/** The one origin mapping, derived by the dispatcher and never claimed by a
+ *  caller: a feed cannot launder a hover into a user gesture. */
+declare const triggerOriginOf: (trigger: ActionTrigger) => ActionOrigin;
+type ActionNodeStatus = 'executed' | 'blocked' | 'no-executor' | 'inert' | 'failed' | 'skipped';
+interface ActionNodeResult {
+  /** Node address as child indexes from the root ([] = root, [0] = root.next[0]…). */
+  path: number[];
+  type: PdfActionType;
+  status: ActionNodeStatus;
+  detail?: string;
+}
+interface ActionDiagnostic {
+  code: 'incomplete-tree' | 'blocked' | 'no-executor' | 'no-adapter' | 'no-session-sink' | 'unresolved-target' | 'duplicate-executor' | 'executor-inert' | 'executor-failed' | 'trigger-disabled' | 'no-commit-sink' | 'trigger-failed' | 'cascade-budget' | 'open-sequence-replayed' | 'no-submit-sink' | 'no-submit-resolver' | 'submit-payload-unavailable' | 'submit-entry-unsupported' | 'reentrant-print';
+  message: string;
+}
+/**
+ * One logical dispatch transaction's outcome. Document-lifetime work is not
+ * rolled back: an earlier successful reset or script write survives a later
+ * failure; `status: 'partial'` says so, and `nodes` carries the per-node
+ * truth. `'cancelled'`: the caller's signal fired while the tree ran, so the
+ * walk stopped before its next node and no navigation or external effect
+ * fired.
+ */
+interface ActionDispatchResult {
+  status: 'executed' | 'partial' | 'inert' | 'refused' | 'cancelled';
+  nodes: ActionNodeResult[];
+  diagnostics: ActionDiagnostic[];
+}
+/**
+ * One tree's execution inside a trigger: its true source, its true tree, its
+ * own node results (`path`s are real walk paths, never prefixed).
+ * `onExecuted` fires once per step with exactly this tree and a context
+ * built from this source, so fan-out never merges trees in the event.
+ */
+interface ActionStepResult {
+  source: ActionSource;
+  tree: PdfActionTree;
+  result: ActionDispatchResult;
+}
+/**
+ * What `dispatch(trigger)` returns: the aggregate plus per-step truth. A step
+ * failure never skips sibling steps (a broken annotation /PC must not cancel
+ * the page's /C); deferred navigation and external effects flush per step,
+ * not per trigger.
+ */
+interface ActionTriggerResult {
+  /** `'cancelled'`: the caller's signal fired before or while the trigger ran. */
+  status: 'executed' | 'partial' | 'inert' | 'refused' | 'cancelled';
+  steps: ActionStepResult[];
+  /** Trigger-level diagnostics (disabled family, resolution failure);
+   *  per-node diagnostics live inside each step's `result`. */
+  diagnostics: ActionDiagnostic[];
+}
+/** Actions ran: one tree, whatever started it (a click, a page, the document, your code). */
+interface ActionExecutedEvent {
+  readonly tree: PdfActionTree;
+  readonly result: ActionDispatchResult;
+  /** What started them. */
+  readonly source: ActionSource;
+}
+/**
+ * An action was blocked, reported or couldn't run. `action` is its type and
+ * `source` what started it; both are `null` for a diagnostic about no one
+ * action (a trigger family turned off, an executor replaced). The result of
+ * the run that reported it lists the same diagnostic with its message.
+ */
+interface ActionDiagnosticReportedEvent {
+  readonly code: ActionDiagnostic['code'];
+  readonly action: PdfActionType | null;
+  readonly source: ActionSource | null;
+}
+/**
+ * A script was stopped from doing something, such as reaching the network,
+ * or used something the viewer doesn't support.
+ */
+type ScriptDiagnosticReportedEvent = Readonly<ScriptDiagnostic>;
+/**
+ * A script threw an error. `source` is what started it, or `null` for a
+ * script no action started: a form field's keystroke, format, validate or
+ * calculate script, or a stamp's template.
+ */
+interface ScriptFailedEvent {
+  readonly error: ScriptExecutionError;
+  readonly source: ActionSource | null;
+}
+/** The decision per type and origin. `allow` executes; `adapter` routes
+ *  through the type's port (the UI adapter; for `submit-form`, the sink
+ *  chain: embedder handler → the document's home → blocked); `report`
+ *  records a blocked node without executing; `block` refuses. The `launch`,
+ *  `goto-remote`, `goto-embedded` and media types are fixed `'never'` and
+ *  not configurable. */
+type ActionPolicyDecision = 'allow' | 'adapter' | 'report' | 'block';
+type ActionPolicyRow = Readonly<Record<ActionOrigin, ActionPolicyDecision>>;
+interface ActionPolicy {
+  readonly goto: ActionPolicyRow;
+  readonly named: ActionPolicyRow;
+  readonly hide: ActionPolicyRow;
+  readonly 'reset-form': ActionPolicyRow;
+  readonly javascript: ActionPolicyRow;
+  readonly uri: ActionPolicyRow;
+  /** The Named `Print` verb, owned by policy and the UI adapter, never the
+   *  stage. (An Acrobat-compatible extension: ISO 32000-2 Table 215 defines
+   *  only the four page verbs; an unrecognized name "shall take no action".) */
+  readonly print: ActionPolicyRow;
+  /** SubmitForm: `'adapter'` routes through the sink chain. Default: user
+   *  origin only; hover and lifecycle submits stay blocked. */
+  readonly 'submit-form': ActionPolicyRow;
+}
+/** Who scripts think the user is: fields over the document's user, or a function that returns them. */
+type ActionsScriptIdentity = Partial<ScriptIdentity> | (() => Partial<ScriptIdentity>);
+/**
+ * The actions plugin's settings. `actionsPlugin(config)` registers them over
+ * {@link ACTIONS_DEFAULTS}, and `updateSettings()` changes them for every
+ * document while the app runs. `policy`, `triggers` and
+ * `javascript.identity` apply to the next action; `javascript.enabled`
+ * applies to the documents opened after the change (a document's script
+ * engine starts when it opens); `openSequence` applies until a document's
+ * opening actions have run.
+ */
+interface ActionsSettings {
+  /** The rules: per kind of action and per origin. Rows merge, so a change names only what it changes. */
+  readonly policy: ActionPolicy;
+  /** Run the actions of the `document`, its `page`s, or `annotation`s. A click on a link or button always runs. */
+  readonly triggers: {
+    readonly document: boolean;
+    readonly page: boolean;
+    readonly annotation: boolean;
+  };
+  /**
+   * When the document's opening actions run (the open destination, then the
+   * catalog /OpenAction, then the first page's /O). `'auto'` runs them once
+   * at the first sign of a person: a UI adapter installing, or a first
+   * click; the first page's /O then comes from the Stage's page report.
+   * `'headless'` runs them as the document opens, for an app without a
+   * Stage; `'off'` never runs them.
+   */
+  readonly openSequence: 'auto' | 'headless' | 'off';
+  readonly javascript: {
+    /** Run the document's JavaScript. Off by default: no script engine ever loads. */
+    readonly enabled: boolean;
+    /** Who scripts think the user is, on top of the document's user. `null`: the document's user. */
+    readonly identity: ActionsScriptIdentity | null;
+  };
+}
+/** What the actions settings are when the app registers none. */
+declare const ACTIONS_DEFAULTS: ActionsSettings;
+/**
+ * The script environment, given once when the plugin is registered: not a
+ * setting, because a document's script engine is built with it when the
+ * document opens.
+ */
+interface ActionsScriptEnvironment {
+  /** Override the lazy QuickJS factory (tests or another isolated VM). */
+  readonly sandboxFactory?: ScriptSandboxFactory;
+  readonly fileName?: () => string;
+  /** Injected deterministic transaction environment. */
+  readonly now?: () => number;
+  readonly utcOffsetMinutes?: () => number;
+  readonly randomSeed?: () => number;
+  readonly budget?: ScriptBudget;
+  /**
+   * The deterministic aggregate: the most JavaScript nodes one dispatch may
+   * run (default 16). A /Next chain shares it instead of multiplying the
+   * per-run time budget, and a count stays deterministic where a wall-clock
+   * aggregate would not. Once exhausted, the remaining JavaScript nodes
+   * report inert with a budget reason.
+   */
+  readonly maxScriptNodesPerDispatch?: number;
+}
+/**
+ * What `actionsPlugin(config)` takes: any of the settings, merged over the
+ * defaults, and the script environment beside `javascript`'s settings.
+ */
+interface ActionsConfig extends DeepPartial<Omit<ActionsSettings, 'javascript'>> {
+  readonly javascript?: DeepPartial<ActionsSettings['javascript']> & ActionsScriptEnvironment;
+}
+type ActionExecutorResult = {
+  status: 'executed';
+} | {
+  status: 'inert';
+  reason: string;
+} | {
+  status: 'failed';
+  error: string;
+};
+/** One node of one registered type, executed in dispatch order. Executors
+ *  never see the tree or the capability, so an executor cannot cascade into
+ *  further dispatches. */
+type ActionExecutor = (node: PdfActionNode, actionContext: ActionContext) => Promise<ActionExecutorResult> | ActionExecutorResult;
+/** The origin and phase every script-produced UI request carries: the
+ *  default adapter's visibility matrix keys on it; embedder adapters receive
+ *  everything and decide for themselves. */
+interface ActionUiContext {
+  origin: ActionOrigin;
+  /** Script-model axis: `'boot'` = name-tree/document-open boot scripts. */
+  phase: 'boot' | 'user';
+}
+interface ActionUiAdapter {
+  /** A URI action to open; `isMap` is the /IsMap flag. */
+  openUri(uri: string, options: {
+    isMap: boolean;
+    origin: ActionOrigin;
+  }): void;
+  /** The Named `Print` verb and script `print()` requests (authority-gated
+   *  upstream: `doc.print` refusals never reach the adapter). */
+  print(uiContext?: ActionUiContext): void;
+  /** Script `app.alert`: the one alert port for every script origin. */
+  alert?(message: string, options: ActionUiContext & {
+    icon: number;
+    title?: string;
+  }): void;
+  /** Script `this.pageNum = n` navigation requests. */
+  gotoPage?(page: number, uiContext: ActionUiContext): void;
+}
+/**
+ * A normalized submit intent, one shape for both sources: a SubmitForm action
+ * node's extracted payload, or a script `doc.submitForm()` effect
+ * (include-mode names, `exclude` false). Resolving it into a dataset is the
+ * form plugin's job (it owns the field plane), through the registered
+ * resolver.
+ */
+interface SubmitIntent {
+  url: string | null;
+  /** ISO 32000-2 Table 239 targets (names and object numbers mixed); `null`
+   *  is the whole eligible form. */
+  fields: PdfActionTargetRef[] | null;
+  exclude: boolean;
+  includeNoValueFields: boolean;
+  format: 'fdf' | 'html' | 'xfdf' | 'pdf';
+  method: 'post' | 'get';
+  /** Raw ISO Table 240 word (0 for scripted submits without one). */
+  flagsRaw: number;
+  charSet?: string;
+}
+/**
+ * The resolved dataset a sink receives. Entries carry the ISO semantics
+ * already applied (descendants, the unconditional NoExport veto, push-button
+ * and unsupported exclusion, diagnosed and never silent); the document's
+ * declared routing survives as metadata. The stack never fetches `url`: an
+ * embedder handler that chooses to must validate it (protocol and
+ * destination allowlists) before any network call.
+ */
+interface ActionSubmitRequest {
+  url: string | null;
+  method: 'post' | 'get';
+  format: 'fdf' | 'html' | 'xfdf' | 'pdf';
+  flagsRaw: number;
+  charSet?: string;
+  entries: FormSubmissionEntry[];
+  origin: ActionOrigin;
+  event: ActionTriggerEvent;
+}
+/**
+ * The first sink of the chain: the embedder's application. Installing it is
+ * the consent (it receives nothing the embedder could not already compute
+ * from `forms.list()` under `doc.forms.read`, so no submit scope gates it).
+ * Contract: synchronous acceptance marks the node `executed` ("handed to the
+ * embedder", not "delivered"); a synchronous throw marks it `failed`; a
+ * returned promise is not awaited, and a later rejection only emits a
+ * diagnostic. `submitToDocumentHome` lets a handler compose with the second
+ * sink (present only when the document has a submit-capable home).
+ */
+type ActionSubmitHandler = (request: ActionSubmitRequest, chain: {
+  submitToDocumentHome: (() => Promise<FormSubmissionReceipt>) | null;
+}) => void | Promise<void>;
+/**
+ * The public capability, for embedders and chrome. Each `can*` twin takes the
+ * same arguments as its verb and answers "would the dispatcher accept this
+ * and attempt execution" (per-node truth lives in the result's `nodes`). Its
+ * settings (`getSettings`, `updateSettings`, `resetSettings`,
+ * `onSettingsChanged`) belong to the plugin, not to a document: a change
+ * reaches every open document.
+ */
+interface ActionsCapability extends SettingsApi<ActionsSettings> {
+  /**
+   * Run a resolved tree on the dispatch queue and fire `onExecuted`; a
+   * failing node is reported in the result, not thrown. Rejects
+   * `operation-cancelled` when `options.signal` fires: before the tree
+   * starts, nothing runs; while it runs, it stops before its next node.
+   */
+  execute(tree: PdfActionTree, actionContext: ActionContext, options?: OperationOptions): Promise<ActionDispatchResult>;
+  /** The tree is complete and its root node's policy decision is `allow` or `adapter`. */
+  canExecute(tree: PdfActionTree, actionContext: ActionContext): boolean;
+  /**
+   * Run one Named verb (`NextPage`, `Print`, …) as a user-origin action
+   * without building a tree — the programmatic twin of a Named link click.
+   * `context` overrides the default `{ origin: 'user', source: { kind: 'api' } }`.
+   * Rejects `operation-cancelled` like `execute()`.
+   */
+  executeNamed(name: PdfNamedAction, context?: Partial<ActionContext>, options?: OperationOptions): Promise<ActionDispatchResult>;
+  /**
+   * Whether the rules would run this Named verb from `context` (a click from
+   * your code by default); `'Print'` also needs `doc.print`.
+   */
+  canExecuteNamed(name: PdfNamedAction, context?: Partial<ActionContext>): boolean;
+  /**
+   * Read the /A or /AA tree behind a source straight from the document
+   * (`null` when absent). This is the raw tree: dispatch-time rules such as
+   * ISO 32000-2 Table 197's "/A shadows /AA U" are not applied here. Rejects
+   * `operation-cancelled` when `options.signal` fires.
+   */
+  getActionTree(source: ActionTreeSource, options?: OperationOptions): Promise<PdfActionTree | null>;
+  /** Did `javascript.enabled` take effect — a script realm exists for this
+   *  document. */
+  isScriptingEnabled(): boolean;
+  /**
+   * Report a trigger. Submission is synchronous: the queue slot is taken
+   * before this returns, so two dispatch calls execute in call order even
+   * when their resolutions race; all reads happen inside the queued
+   * operation. Never rejects: resolution failures come back as `refused`
+   * with a `trigger-failed` diagnostic, and a fired `options.signal` as
+   * `cancelled`, so `void dispatch(...)` is safe.
+   */
+  dispatch(trigger: ActionTrigger, options?: OperationOptions): Promise<ActionTriggerResult>;
+  /** The trigger's family is enabled (the `triggers` setting). */
+  canDispatch(trigger: ActionTrigger): boolean;
+  /** Identity-safe port install: the returned disposer clears the slot only
+   *  while this adapter is still current; `null` force-clears. Installing an
+   *  adapter fires an armed document-open sequence. */
+  setUiAdapter(adapter: ActionUiAdapter | null): Unsubscribe;
+  /**
+   * Run one embedder-owned document verb as one serialized queue operation:
+   * the document-open sequence if it is still armed → the before-event tree
+   * (/WS, /WP) → `operation()` → the after-event tree (/DS, /DP). Two
+   * concurrent calls never interleave their phases. A before-event failure
+   * never cancels the operation; `operation()` throwing skips the
+   * after-event and rethrows; the whole body honors `triggers.document:
+   * false` (trees skipped, operation still runs); print verbs hold the
+   * document-print latch, so nested `doc.print()` calls are suppressed with
+   * a `reentrant-print` diagnostic. The queue is held for the operation's
+   * duration on purpose: that is the serialization (/WS mutations are in the
+   * bytes a save operation pulls). `options.signal` firing before
+   * `operation()` starts skips it and rejects `operation-cancelled`; once it
+   * has started, it finishes, and so does the after-event.
+   */
+  runDocumentVerb<T>(verb: 'save' | 'print', operation: () => Promise<T> | T, options?: OperationOptions): Promise<T>;
+  /**
+   * The cooperative /WC door: runs the catalog will-close tree (after the
+   * document-open sequence) and resolves when its effects are committed.
+   * Call `documents.close()` after this resolves. Scripts never run inside
+   * teardown, so closing without this call skips /WC (unlike Acrobat); it is
+   * not an error. Never rejects, like `dispatch()`.
+   */
+  prepareClose(options?: OperationOptions): Promise<ActionTriggerResult>;
+  /**
+   * The first sink of the submit chain (an identity-safe slot like the UI
+   * adapter, but installing it does not fire the document-open sequence).
+   * With no handler and no submit-capable document home, submits block with
+   * a `no-submit-sink` diagnostic.
+   */
+  setSubmitHandler(handler: ActionSubmitHandler | null): Unsubscribe;
+  /**
+   * Interpret (or override) one action type from application code: the same
+   * door the stage and form plugins use for GoTo, Named, Hide and ResetForm.
+   * Deterministic last-wins on duplicates (a `duplicate-executor` diagnostic
+   * is reported); the disposer removes the entry only while it is still the
+   * current one.
+   */
+  registerExecutor(type: PdfActionType, executor: ActionExecutor): Unsubscribe;
+  /** Actions ran, whatever started them: one event per tree. */
+  readonly onExecuted: EventHook<ActionExecutedEvent>;
+  /** An action was blocked, reported or couldn't run; also dispatch, sink and budget problems. */
+  readonly onDiagnosticReported: EventHook<ActionDiagnosticReportedEvent>;
+  /** A script was stopped from doing something, or used something the viewer doesn't support. */
+  readonly onScriptDiagnosticReported: EventHook<ScriptDiagnosticReportedEvent>;
+  /** A script run ended with an error. */
+  readonly onScriptFailed: EventHook<ScriptFailedEvent>;
+  /** The document-open sequence ran (OpenAction / open destination). */
+  readonly onOpenSequenceCompleted: EventHook<OpenSequenceCompletedEvent>;
+}
+//#endregion
+export { DocumentTriggerEvent as A, SubmitIntent as B, ActionUiAdapter as C, ActionsScriptEnvironment as D, ActionsConfig as E, PdfAnnotationEventKind as F, HoverTarget as G, triggerOriginOf as H, PdfFieldEventKind as I, createHoverPump as K, PdfNamedAction as L, PdfActionNode$1 as M, PdfActionTree$1 as N, ActionsScriptIdentity as O, PdfActionType$1 as P, ScriptDiagnosticReportedEvent as R, ActionTriggerResult as S, ActionsCapability as T, submitEntriesToUrlEncoded as U, eventOf as V, HoverPump as W, ActionSubmitHandler as _, ActionDispatchResult as a, ActionTrigger as b, ActionExecutorResult as c, ActionOrigin as d, ActionPolicy as f, ActionStepResult as g, ActionSource as h, ActionDiagnosticReportedEvent as i, OpenSequenceCompletedEvent as j, ActionsSettings as k, ActionNodeResult as l, ActionPolicyRow as m, ActionContext as n, ActionExecutedEvent as o, ActionPolicyDecision as p, ActionsToken as q, ActionDiagnostic as r, ActionExecutor as s, ACTIONS_DEFAULTS as t, ActionNodeStatus as u, ActionSubmitRequest as v, ActionUiContext as w, ActionTriggerEvent as x, ActionTreeSource as y, ScriptFailedEvent as z };
+//# sourceMappingURL=contract-Cn-7mBY8.d.ts.map