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

package/dist/types-CfnZ7go6.d.cts

@@ -0,0 +1,1304 @@
+import { Annotation, Attachment, ChangeOp, ChangeResult, CustomMetadata, CustomMetadataPatch, CustomMetadataUpdateResult, DocCapability, DocumentEvent, DocumentEvent as DocumentEvent$1, DocumentHandle, DocumentHandle as DocumentHandle$1, DocumentMetadata, Engine as Engine$1, EngineFactory, EngineRenderPolicy, EventOrigin, FormFieldDTO, Identity as Identity$1, MetadataPatch, MetadataUpdateResult, OpenInput, OpenOptions, OutlineItem, PageDeleteResult, PageDestination, PageInsertBlankSpec, PageInsertResult, PageLayout as PageLayout$1, PageObjectNumber, PagePosition, PageRef, PageReorderResult, PageRotateResult, PdfDestination, PdfRotation, PdfSaveMode, PdfSize, PrintDpi, WidgetAnnotation } from "@embedpdf/engine-core/runtime";
+//#region src/lanes.d.ts
+/** One execution inside a `latest` lane. */
+/** `details` of the `operation-cancelled` error a superseded or cancelled run rejects with. */
+interface LatestCancellation {
+  readonly runId: string;
+  /** `'superseded'`, `'cancelled'`, the caller's abort reason, or `'instance-closed'`. */
+  readonly reason: string;
+}
+interface LatestRun {
+  /** `${lane}#${n}`, unique per run; surfaces in cancellation errors and events. */
+  readonly id: string;
+  /** Aborts when a newer run starts, the caller's signal aborts, or the instance closes. */
+  readonly signal: AbortSignal;
+  /** True once a newer run has started. */
+  readonly superseded: boolean;
+  /** Run `fn` only while this run is still the newest and alive; returns whether it ran. */
+  commit(fn: () => void): boolean;
+}
+/**
+ * Newest wins. Starting a run aborts the previous one; a superseded run cannot
+ * publish (`commit` returns false) and its promise rejects
+ * `operation-cancelled`, whatever its engine call later does.
+ */
+interface LatestLane {
+  readonly running: boolean;
+  run<T>(fn: (run: LatestRun) => Promise<T>, options?: OperationOptions): Promise<T>;
+  /** Cancel the current run, if any. */
+  cancel(reason?: unknown): void;
+}
+declare function createLatestLane(lifetime: AbortSignal, capability: string, name: string): LatestLane;
+//#endregion
+//#region src/errors.d.ts
+/**
+ * The one error vocabulary a plugin capability rejects with. Stable codes so
+ * callers match on `code`, never on message text; the engine's error stays
+ * reachable as `cause`.
+ */
+type PluginErrorCode = 'permission-denied' | 'unsupported' | 'not-found' | 'not-ready' | 'invalid-input' | 'conflict' | 'instance-closed' | 'operation-cancelled' | 'operation-failed';
+declare class PluginError extends Error {
+  readonly name = "PluginError";
+  readonly code: PluginErrorCode;
+  /** The capability (plugin id) that produced the error. */
+  readonly capability: string;
+  /**
+   * The permission the session lacks, named as the engine names it: a document capability
+   * (`'doc.forms.fill'`) or an annotation action (`'annotations:update'`). Set on
+   * `permission-denied` when the refusal names one, whether a plugin's own check refused
+   * (`ctx.assertAllowed`) or the engine did; null otherwise.
+   */
+  readonly permission: string | null;
+  readonly details: unknown;
+  constructor(code: PluginErrorCode, capability: string, message: string, options?: {
+    cause?: unknown;
+    details?: unknown;
+    permission?: string | null;
+  });
+}
+/** The serializable summary of a PluginError, for state and event payloads. */
+interface PluginErrorInfo {
+  readonly code: PluginErrorCode;
+  readonly message: string;
+  readonly capability: string;
+  /** The permission the session lacks (see `PluginError.permission`), or null. */
+  readonly permission: string | null;
+}
+declare function toPluginErrorInfo(error: PluginError): PluginErrorInfo;
+declare function isPluginError(value: unknown, code?: PluginErrorCode): value is PluginError;
+/**
+ * The one boundary mapping from whatever an engine call threw to a
+ * `PluginError`. Idempotent: an existing PluginError passes through.
+ * Cancellation (the kernel's CancelledError, a DOM AbortError, or an engine
+ * abort) is `operation-cancelled`, never `operation-failed`, so callers can
+ * tell "nobody wanted this anymore" from "this broke". A refusal names the
+ * missing permission in `permission`; `details` keeps the rest of what the
+ * engine sent (`anyOf`, `context`).
+ */
+declare function toPluginError(capability: string, error: unknown): PluginError;
+//#endregion
+//#region src/event-hook.d.ts
+/**
+ * Subscribe-only face of a plugin event — the one event shape a capability
+ * exposes (`onX: EventHook<XEvent>`). Events carry occurrences, never state:
+ * a late subscriber that needs the current value uses a query + selector
+ * instead. Payloads are plain serializable objects.
+ */
+type EventHook<T> = (listener: (event: T) => void, options?: {
+  signal?: AbortSignal;
+}) => Unsubscribe;
+/**
+ * The plugin-private pair behind one capability event. Expose `.on` on the
+ * capability; keep `emit`/`dispose` inside the plugin. Because the capability
+ * member is the bare function type, the emitting half is unreachable through
+ * the public contract by construction.
+ */
+interface EventHookSource<T> {
+  readonly on: EventHook<T>;
+  emit(event: T): void;
+  dispose(): void;
+}
+/**
+ * Create one capability event.
+ *
+ * Subscribe with `{ signal }` to tie the subscription to an AbortSignal; a
+ * pre-aborted signal never registers.
+ *
+ * Delivery contract: synchronous fan-out over a snapshot of the listener set
+ * (listeners added or removed during an emit don't affect that emit); a
+ * throwing listener is isolated — reported through `onListenerError`, never
+ * allowed to break the emitting operation or its sibling listeners. After
+ * `dispose()`, `on` returns an inert unsubscribe (teardown races never throw).
+ * No value cache, no replay, no equality — state belongs to the store.
+ */
+declare function createEventHook<T = void>(onListenerError?: (error: unknown) => void): EventHookSource<T>;
+//#endregion
+//#region src/changes.d.ts
+/** What a change is called in history and refusals: an i18n key and its values. */
+interface ChangeLabel {
+  readonly key: string;
+  readonly [value: string]: string | number;
+}
+/** An op a view can predict: the engine's ops, and the ones only an undo brings back. */
+type PredictedOp = ChangeOp | {
+  readonly type: 'annotations.restore';
+  readonly annotation: Annotation;
+  /** Its place among the page's annotations. */
+  readonly index: number;
+} | {
+  readonly type: 'forms.restore';
+  readonly field: FormFieldDTO;
+  /** The rows of its widgets, as they were. */
+  readonly widgets: readonly WidgetAnnotation[];
+} | {
+  readonly type: 'forms.restoreWidget';
+  /** The widget's row, as it was. */
+  readonly widget: WidgetAnnotation;
+  /** Its field as the restore leaves it, with the widget back; `null` when it had none. */
+  readonly field: FormFieldDTO | null;
+} | {
+  readonly type: 'outline.restore';
+  /** The items as they were: the item first, then the items under it, depth first. */
+  readonly items: readonly OutlineItem[];
+  /** The item's place among its parent's children. */
+  readonly index: number;
+} | {
+  readonly type: 'attachments.restore';
+  /** The embedded file as it was, under the key it had. */
+  readonly attachment: Attachment;
+};
+/** One user action, as a plugin stages it. */
+type StagedChange = {
+  readonly label: ChangeLabel;
+  /** The engine's ops, sent as they are. */
+  readonly ops: readonly ChangeOp[];
+  /** What undoing it looks like, as ops the views can predict. Drawing only; never sent. */
+  readonly undo?: readonly PredictedOp[];
+  /** `false`: not a step of the history, such as a recalculation another session caused. */
+  readonly history?: false;
+} | {
+  readonly label: ChangeLabel;
+  /** Undo the change with this `opId`: the engine applies the reverse it recorded. */
+  readonly undoOf: string;
+  /** What the views show until the engine answers. */
+  readonly shows: readonly PredictedOp[];
+};
+/** A change of this session the engine hasn't answered yet. */
+interface PendingChange {
+  /** Its name: what the engine's events carry as `origin.tx.id`, and what `undoOf` names. */
+  readonly opId: string;
+  readonly label: ChangeLabel;
+  /** For an undo: the `opId` of the change it undoes. `null` for a change of ops. */
+  readonly undoOf: string | null;
+  /**
+   * A held change's `merge` key: consecutive changes with the same key are one step of the
+   * history (the pauses of one typing session). `null` for every other change.
+   */
+  readonly merge: string | null;
+  /** What the views show until the engine answers: its ops, or an undo's prediction. */
+  readonly shows: readonly PredictedOp[];
+  /** What undoing it looks like (drawing only); empty when the stager gave none. */
+  readonly undo: readonly PredictedOp[];
+  /** Whether it is a step of the history. An undo isn't: it moves along the history. */
+  readonly history: boolean;
+  /** An open hold: shown, not sent yet. */
+  readonly held: boolean;
+  /** The engine's answer: resolves with what the change did, rejects with why it was refused. */
+  readonly result: Promise<ChangeResult>;
+}
+/** A change the engine answered. */
+type SettledChange = {
+  readonly change: PendingChange;
+  readonly status: 'applied';
+  readonly result: ChangeResult;
+} | {
+  readonly change: PendingChange;
+  readonly status: 'refused';
+  readonly error: PluginError;
+};
+/** How a held change is put in the history. */
+interface HoldOptions {
+  /** Consecutive changes with the same key are one step of the history: typing into one text box. */
+  readonly merge?: string;
+}
+/** A change that can still be amended until it is sent. */
+interface HeldChange {
+  /**
+   * Whether it can still be amended: false once it was sent (by `send`, by a later stage, or
+   * before a download) or cancelled. What comes after goes into a new change.
+   */
+  readonly open: boolean;
+  /** The change it is, once it has ops (its `opId`, its answer); `null` before. */
+  readonly change: PendingChange | null;
+  /** Its ops from now on, and what undoing them looks like. The views show the latest. */
+  set(ops: readonly ChangeOp[], undo?: readonly PredictedOp[]): void;
+  /**
+   * Send it now, after any hold staged before it. A hold is also sent when another change is
+   * staged, and before a download. `null` when nothing was ever set.
+   */
+  send(): PendingChange | null;
+  /** Drop it: the views show the truth again, and nothing is sent. */
+  cancel(): void;
+}
+/** The document's change queue, as a plugin uses it (`ctx.changes`). */
+interface ChangeQueue {
+  /**
+   * Stage one user action. Every mirror's view shows it before this returns, and it is sent
+   * after everything staged before it; an open hold is sent first. Inside a group it joins the
+   * group's change, and the group's change is what it returns.
+   */
+  stage(change: StagedChange): PendingChange;
+  /**
+   * A change that can still be amended until it is sent: typing, or a form commit waiting for
+   * its scripts. It keeps its place in the order from its first `set`. Refused inside a group.
+   */
+  hold(label: ChangeLabel, options?: HoldOptions): HeldChange;
+  /** Send every open hold now, in staging order: what an undo does first, as a download does. */
+  sendHolds(): void;
+  /**
+   * Everything staged while `run` runs, by any plugin, becomes one change: one request, one
+   * undo step. Only what is staged before `run` returns joins; nested groups join the outer
+   * one. When `run` throws, nothing of it is sent.
+   */
+  group<T>(label: ChangeLabel, run: () => T): T;
+  /** A final name for an object this session creates, or `null` when none is held (then `reserve`). */
+  takeObjectNumber(): number | null;
+  /** Resolves once at least `count` names are held. */
+  reserveObjectNumbers(count: number): Promise<void>;
+  /** This session's changes the engine hasn't answered, open holds included, in staging order. */
+  pending(): readonly PendingChange[];
+  hasPending(): boolean;
+  /** Resolves once every change sent so far is answered; open holds aren't waited for. Never rejects. */
+  whenSettled(): Promise<void>;
+  /** A change was staged, or a hold was sent. */
+  readonly onStaged: EventHook<PendingChange>;
+  /** The engine answered a change, or refused it with one it depended on. */
+  readonly onSettled: EventHook<SettledChange>;
+}
+//#endregion
+//#region src/clock.d.ts
+/**
+ * Time, as the host keeps it. Plugins never read timers or frames from the
+ * environment: they ask their context (`ctx.clock`), and the host that built
+ * the kernel says what a timer and a frame are (`createKernel({ clock })`).
+ *
+ * - A browser host passes `browserClock()` from `@embedpdf/web`: timers, and
+ *   frames from `requestAnimationFrame`. The framework viewers do this.
+ * - Without one, the kernel uses {@link timerClock}: timers only, no frames.
+ *   Every JavaScript runtime has timers, so a kernel in Node, a worker or a
+ *   test needs no setup.
+ * - Tests that step time pass `manualClock()` from `@embedpdf/core/testing`.
+ *
+ * What an instance schedules belongs to it ({@link instanceClock}): it is
+ * cancelled when the instance closes, and nothing runs after that.
+ *
+ * This file is the one place in the kernel and the plugins that touches the
+ * environment's timers (the lint rule in `eslint.config.js` says so).
+ */
+/** Cancels what a clock call scheduled. Does nothing once it ran or was cancelled. */
+type Cancel = () => void;
+/** What a host provides: the kernel's only source of time. */
+interface HostClock {
+  /** Milliseconds on a clock that only goes forward. */
+  now(): number;
+  /** Run `run` once, `ms` milliseconds from now. */
+  after(ms: number, run: () => void): Cancel;
+  /**
+   * Run `run` once, just before the host next paints, with the frame's time
+   * on the `now()` clock. Absent on a host that never paints.
+   */
+  nextFrame?(run: (timeMs: number) => void): Cancel;
+}
+/** A plugin instance's clock: `ctx.clock`. */
+interface PluginClock {
+  /** Run `run` once, `ms` milliseconds from now. */
+  after(ms: number, run: () => void): Cancel;
+  /**
+   * Run `run` once, just before the host next paints, with the frame's time in
+   * milliseconds. On a host that never paints: as soon as possible.
+   */
+  nextFrame(run: (timeMs: number) => void): Cancel;
+  /** False on a host that never paints (Node, a worker, most tests): animations jump to their end. */
+  readonly hasFrames: boolean;
+}
+/** Timers only, no frames: the kernel's default. */
+declare const timerClock: HostClock;
+//#endregion
+//#region src/store.d.ts
+/** One committed change of a slice: the value before and after. */
+interface SliceChange<S> {
+  readonly next: S;
+  readonly previous: S;
+}
+/**
+ * A plugin instance's authority over its state slice. Unique per instance:
+ * closing and reopening the same document id yields a new lease, and the old
+ * one is revoked synchronously at the start of close, so a callback retained
+ * by the old instance can never read or write the new instance's state.
+ * Writes return false (and are dropped) once the lease is revoked.
+ */
+interface SliceLease<S = unknown> {
+  readonly key: string;
+  readonly instanceId: string;
+  readonly live: boolean;
+  read(): S;
+  /** Replace the slice's value. Writing the current value is a no-op that returns true. */
+  write(next: S): boolean;
+  /** Fires after every committed change of this slice, once the store's subscribers ran. */
+  readonly onChange: EventHook<SliceChange<S>>;
+  revoke(): void;
+}
+//#endregion
+//#region src/mirror.d.ts
+declare const RELOAD: unique symbol;
+/** What `fold` returns when an event is too coarse to apply: reload everything, or some pages. */
+interface MirrorReload {
+  readonly [RELOAD]: 'all' | readonly PageRef[];
+}
+/** Ask the mirror to reload instead of applying the event. */
+declare function reload(options?: {
+  pages?: readonly PageRef[];
+}): MirrorReload;
+/** One applied change of a mirror, handed to the spec's `changed` callback. */
+interface MirrorChange<V> {
+  /** `load` for loads and reloads, `event` for a folded event. */
+  readonly cause: 'load' | 'event';
+  /** The folded event; null for loads. */
+  readonly event: DocumentEvent | null;
+  /** For loads: every page (`'all'`) or the pages that were reloaded. Null for events. */
+  readonly pages: 'all' | readonly PageRef[] | null;
+  readonly previous: V;
+  readonly next: V;
+}
+interface MirrorSpec<V> {
+  /** Unique within the plugin; names the store cell and appears in errors. */
+  readonly name: string;
+  /** The value before the first load lands. */
+  readonly initial: () => V;
+  /** False: status `forbidden` and no engine read. Asked before every load. */
+  readonly readable?: () => boolean;
+  /**
+   * Load only when asked: the mirror stays `idle`, folding confirmed events into its value,
+   * until `ensureLoaded()` or `refresh()` runs. For data nothing needs when a document opens.
+   * Without it, the first load starts once the plugin is connected.
+   */
+  readonly onDemand?: true;
+  /**
+   * Read the whole value. `cursor` is the newest server event the snapshot
+   * already contains (cloud engines); omit it when the engine has none.
+   */
+  load(doc: DocumentHandle, signal: AbortSignal): Promise<{
+    value: V;
+    cursor?: number | null;
+  }>;
+  /**
+   * Apply one confirmed event. Pure, and the same for every origin. Return
+   * `value` itself when the event does not apply, or `reload(...)` when the
+   * event does not carry enough to apply.
+   */
+  fold(value: V, event: DocumentEvent): V | MirrorReload;
+  /**
+   * Apply one op of a change this session staged and the engine hasn't
+   * answered, as the engine will: the same rules, and absolute, so an op the
+   * value already holds changes nothing. Pure. Return `value` itself for an op
+   * it doesn't concern. Without it, `view()` is `get()`.
+   */
+  predict?(value: V, op: PredictedOp): V;
+  /**
+   * Read some pages and return how to merge them into the value. Required
+   * when `fold` asks for a page-scoped reload; without it such a request
+   * reloads everything.
+   */
+  loadPages?(doc: DocumentHandle, pages: readonly PageRef[], signal: AbortSignal): Promise<(value: V) => V>;
+  /**
+   * Runs after every load (even one that changed nothing) and every event
+   * that changed the value: the one place a plugin emits the events this
+   * data drives.
+   */
+  readonly changed?: (change: MirrorChange<V>) => void;
+}
+interface Mirror<V> {
+  /** What the engine confirmed. */
+  get(): V;
+  /** What the user sees: `get()` with this session's pending changes on top (`predict`). */
+  view(): V;
+  /** `idle` until the first load starts; stays `ready` while a reload runs. */
+  getStatus(): ResourceStatus;
+  /**
+   * Load unless it is loaded or loading: a load in flight is shared, and a loaded mirror
+   * resolves at once. After a failed load it tries again. Rejects when the load fails.
+   */
+  ensureLoaded(): Promise<void>;
+  /** Reload everything. Joins a running load; rejects when the load fails. */
+  refresh(): Promise<void>;
+  /**
+   * Resolves once no load or page reload is running, including reloads
+   * started by events that arrive while it waits. Never rejects.
+   */
+  settled(): Promise<void>;
+}
+//#endregion
+//#region src/page-mirror.d.ts
+/** One applied change of one page, handed to the spec's `changed` callback. */
+interface PageMirrorChange<V> {
+  readonly page: PageRef;
+  /** `load` for reads, `event` for a folded event, `drop` when the page was deleted. */
+  readonly cause: 'load' | 'event' | 'drop';
+  readonly event: DocumentEvent | null;
+  readonly previous: V | undefined;
+  readonly next: V | undefined;
+}
+interface PageMirrorSpec<V> {
+  /** Unique within the plugin; names the store cell and appears in errors. */
+  readonly name: string;
+  /** Read one page's value. */
+  load(doc: DocumentHandle, page: PageRef, signal: AbortSignal): Promise<V>;
+  /**
+   * Which pages an event makes stale: those pages, every loaded page
+   * (`'all'`), or none (`null`). Only pages that are loaded are affected.
+   */
+  affected(event: DocumentEvent): readonly PageRef[] | 'all' | null;
+  /**
+   * Apply an event to an affected page's value instead of re-reading it.
+   * Return `'reload'` to re-read. Without `fold`, affected pages are re-read.
+   */
+  fold?(value: V, event: DocumentEvent, page: PageRef): V | 'reload';
+  /**
+   * Apply one op of a pending change of this session to a loaded page's
+   * value, as the engine will. Pure and absolute, like a mirror's `predict`;
+   * return `value` itself for an op that doesn't concern the page. Without
+   * it, `view(page)` is `get(page)`.
+   */
+  predict?(value: V, op: PredictedOp, page: PageRef): V;
+  /** Runs after every load of a page (even one that changed nothing) and every applied change. */
+  readonly changed?: (change: PageMirrorChange<V>) => void;
+}
+interface PageMirror<V> {
+  /** The page's value, or undefined when it has not loaded. */
+  get(page: PageRef): V | undefined;
+  /** What the user sees on the page: `get(page)` with this session's pending changes on top. */
+  view(page: PageRef): V | undefined;
+  getStatus(page: PageRef): ResourceStatus;
+  /** Load the page unless it is loaded or loading. */
+  ensureLoaded(page: PageRef, options?: OperationOptions): Promise<void>;
+  /** Re-read one page, or every loaded page. */
+  refresh(page?: PageRef): Promise<void>;
+}
+//#endregion
+//#region src/serial-queue.d.ts
+/**
+ * Small promise-tail queue: operations run strictly one at a time, in
+ * submission order, and failures never poison later operations. The shared
+ * serializer for per-document mutation/dispatch pipelines.
+ *
+ * Direction law for nested queues: an operation running on queue A may
+ * enqueue into queue B and await it, but never the reverse on the same pair —
+ * a B-operation enqueueing back into A self-deadlocks behind its caller.
+ */
+interface SerialQueue {
+  /**
+   * Run `operation` once everything queued before it has finished. With
+   * `{ signal }`, an operation whose signal fired while it waited never
+   * starts: it rejects `operation-cancelled`. Once it has started, cancelling
+   * is up to the operation (`ctx.cancellable`).
+   */
+  <T>(operation: () => Promise<T>, options?: OperationOptions): Promise<T>;
+  /** Resolves once every operation queued so far has finished, however it ended. */
+  idle(): Promise<void>;
+}
+/** `capability` names the plugin in the error a skipped operation rejects with. */
+declare function createSerialQueue(capability: string): SerialQueue;
+//#endregion
+//#region src/settings.d.ts
+/** A change to one setting: plain objects go deeper, arrays and functions are given whole. */
+type DeepPartialValue<V> = V extends readonly unknown[] | ((...args: never[]) => unknown) ? V : V extends object ? DeepPartial<V> : V;
+/** Every field optional, down through the plain objects. */
+type DeepPartial<T> = { readonly [K in keyof T]?: DeepPartialValue<T[K]>; };
+declare const noSettings: unique symbol;
+/**
+ * The settings of a plugin whose definition declares none. A type of its own rather than `never`:
+ * a plugin list mixes plugins with and without settings, and `any` stands in for every type but
+ * `never`.
+ */
+interface NoSettings {
+  readonly [noSettings]: true;
+}
+/** A plugin's settings as its definition declares them: `definePlugin({ settings })`. */
+interface SettingsDeclaration<T> {
+  /** Every setting's value when the app registers none. */
+  readonly defaults: T;
+  /** What the app registered, usually the plugin factory's config: merged over `defaults`. */
+  readonly registered?: DeepPartial<T> | undefined;
+  /**
+   * Top-level settings that are one value each, such as a person: a change replaces them
+   * whole instead of merging into them, so nothing of the previous value stays.
+   */
+  readonly whole?: readonly (keyof T & string)[];
+}
+/** What `onSettingsChanged` carries: the settings after the change, and which of them changed. */
+interface SettingsChangedEvent<T> {
+  readonly settings: T;
+  /** The top-level settings whose value changed (`['highlight']` when only a highlight color did). */
+  readonly changed: readonly (keyof T)[];
+}
+/** The four settings calls, spread into a plugin's capability. */
+interface SettingsApi<T> {
+  /** The settings in effect: the same object until a setting changes. */
+  getSettings(): T;
+  /**
+   * Merge `changes` into the settings, for every document: plain objects merge key by key,
+   * arrays and other values replace, and `undefined` leaves a setting as it is. Fires
+   * `onSettingsChanged` once when a setting changed.
+   */
+  updateSettings(changes: DeepPartial<T>): void;
+  /** Go back to what the app registered (not to the plugin's defaults). Fires `onSettingsChanged` when a setting changed. */
+  resetSettings(): void;
+  /** Fires once for each call that changed a setting. */
+  readonly onSettingsChanged: EventHook<SettingsChangedEvent<T>>;
+}
+/** The settings type of a capability that has the settings calls, else `never`. */
+type SettingsOf<Capability> = Capability extends {
+  getSettings(): infer T;
+} ? T : never;
+/** What `ctx.settings()` returns: `get()` for the plugin's own code, `api` for its capability. */
+interface Settings<T> {
+  /** The settings in effect. */
+  get(): T;
+  readonly api: SettingsApi<T>;
+}
+/**
+ * `changes` merged into `settings`, the `whole` ones replaced instead: the merge every settings
+ * store applies, for code that keeps changes before a store exists (an adapter whose engine is
+ * still loading). What a change leaves as it was keeps its object, so a reader that compares by
+ * reference sees only what really changed.
+ */
+declare function mergeSettings<T>(settings: T, changes: DeepPartial<T> | undefined, whole?: readonly string[]): T;
+//#endregion
+//#region src/types.d.ts
+type Unsubscribe = () => void;
+/** The last parameter of every method that does work: cooperative cancellation. */
+interface OperationOptions {
+  readonly signal?: AbortSignal;
+}
+/** Load state of a resource a plugin hydrates from the engine. `forbidden` is a permission refusal, not an empty value. */
+type ResourceStatus = 'idle' | 'loading' | 'ready' | 'forbidden' | 'error';
+/**
+ * The outcome of a best-effort batch (`renderPages`, `createMany`, …): what
+ * was applied, what was skipped with a reason, and what failed with its
+ * error summary. `R` is the input's identity (a `PageRef`, an `AnnotationRef`).
+ */
+interface BatchResult<T, R = unknown> {
+  readonly applied: readonly T[];
+  readonly skipped: readonly {
+    readonly ref: R;
+    readonly reason: string;
+  }[];
+  readonly failed: readonly {
+    readonly ref: R;
+    readonly error: PluginErrorInfo;
+  }[];
+}
+/**
+ * A permission a verb can need, named as the engine names it: a document
+ * capability (`'doc.forms.fill'`), or `'annotations:create'`. Creating is the
+ * one annotation action that needs no target: whether the session may change
+ * or delete an annotation depends on whose it is, so the annotation plugin
+ * asks that per annotation (`doc.security.allowsAnnotation`).
+ */
+type Permission = DocCapability | 'annotations:create';
+/** Anything `ctx.listen` can subscribe to: an EventHook, or an object with `subscribe`. */
+type Subscribable<T> = ((listener: (event: T) => void) => Unsubscribe) | {
+  subscribe(listener: (event: T) => void): Unsubscribe;
+};
+/**
+ * The public name of a page-registry entry: `ref` is the durable identity,
+ * `index` the display order, plus label, size, rotation, userUnit and boxes.
+ * Structurally the engine's `PageLayout`; named for what it is to a developer.
+ */
+type PageInfo = PageLayout$1;
+/** A typed handle to a capability — typed resolution, no string casts. */
+interface CapabilityToken<T> {
+  readonly name: string;
+  /**
+   * Authored remedy shown when a plugin `requires` this capability and no
+   * plugin provides it — the missing-dependency error should contain its own
+   * fix (e.g. "add interactionPlugin() from '@embedpdf/plugin-interaction' to
+   * your plugins list").
+   */
+  readonly hint?: string;
+  /**
+   * The members of the capability that return a promise, by path (`setValue`,
+   * `comments.reply`). Without a document, a framework adapter's stand-in
+   * rejects these with `not-ready`, as the capability would, instead of
+   * throwing (see `standInFor`).
+   */
+  readonly promises?: Readonly<Record<string, true>>;
+  /** phantom — never present at runtime */
+  readonly __type?: T;
+}
+/** The members of an object that return a promise, by name. */
+type PromiseMethodOf<Owner> = { [Key in keyof Owner & string]-?: Owner[Key] extends ((...args: never[]) => infer Result) ? [Result] extends [PromiseLike<unknown>] ? Key : never : never; }[keyof Owner & string];
+/**
+ * The path of every member of `Capability` that returns a promise: its own methods
+ * (`'setValue'`) and those of its namespaces (`'comments.reply'`).
+ */
+type PromiseMemberOf<Capability> = PromiseMethodOf<Capability> | { [Key in keyof Capability & string]-?: Capability[Key] extends ((...args: never[]) => unknown) ? never : Capability[Key] extends object ? `${Key}.${PromiseMethodOf<Capability[Key]>}` : never; }[keyof Capability & string];
+/**
+ * A token's `promises`: one entry for each member of `Capability` that returns a promise. The
+ * type asks for every one of them, and only them, so the list can't fall behind the contract.
+ */
+type PromiseMembers<Capability> = { readonly [Path in PromiseMemberOf<Capability>]: true; };
+/**
+ * What the kernel knows about an open document — the page registry captured at open.
+ * `pages` is the engine's own snapshot (`PageLayout`: index, ref, size,
+ * rotation, label, boxes). `ref` (the page's `PageRef`) is the durable
+ * per-page identity; the array index is only display order.
+ */
+interface DocumentMeta {
+  readonly id: string;
+  /**
+   * Unique per open of this id: closing and reopening the same document id
+   * yields a new instanceId. Events, refs and leases are checked against it,
+   * so nothing produced by a closed instance can be mistaken for the new one.
+   */
+  readonly instanceId: string;
+  readonly name?: string;
+  readonly pageCount: number;
+  readonly pages: readonly PageLayout$1[];
+  /**
+   * Bumps every time the page registry is replaced by a document mutation
+   * event (rotate/move/delete). The registry's monotonic version: anything
+   * caching a derivation of `pages` (e.g. the Stage's laid-out scene) keys
+   * on it so a same-`pageCount` change — like a rotation — still invalidates.
+   */
+  readonly revision: number;
+  /**
+   * The deployment render policy the document's engine advertises — a
+   * document fact like `pages`, materialized by the kernel at open (before
+   * publish), not plugin state. One lifecycle (here), one interpretation
+   * (engine-core's pure `snap*` helpers); any plugin reads it. Engines
+   * without a render service — and failed policy reads — resolve to
+   * `continuous`, so consumers never branch on absence. Naming rule: the
+   * domain appears exactly once — bare `policy()` on the render service,
+   * `renderPolicy` on flat envelopes like this one and `/v1/access`.
+   */
+  readonly renderPolicy: EngineRenderPolicy;
+  /**
+   * Whether the document changed since it was opened or last downloaded. Only an engine whose
+   * changes live in this tab sets it (the local engine); the cloud engine stores every change
+   * as it's made.
+   */
+  readonly hasUnsavedChanges: boolean;
+}
+/**
+ * A tab slot whose document is not (yet) real: still opening, waiting for a
+ * password, or failed. Lives beside `documents`, never inside it — plugins
+ * only ever see ready documents; pending slots are pure registry/UI state.
+ * Request-time lifecycle: `open()` reserves the slot (id, order position,
+ * activation) synchronously; only the content arrives at completion time.
+ */
+interface PendingMeta {
+  readonly id: string;
+  readonly name?: string;
+  readonly status: 'loading' | 'locked' | 'error';
+  /** `locked` only: a password was supplied at open and rejected — the
+   *  prompt should show its "incorrect password" copy, not "required". */
+  readonly passwordProvided?: boolean;
+  /** `error` only: what the open rejected with. Never carries a password. */
+  readonly error?: unknown;
+}
+/** The document registry — what document scope is built on. */
+interface CoreState {
+  readonly documents: Readonly<Record<string, DocumentMeta>>;
+  readonly pending: Readonly<Record<string, PendingMeta>>;
+  /** The tab strip: spans ready docs and pending slots, in request order. */
+  readonly order: readonly string[];
+  /** May point at a pending slot (a loading or locked tab can be selected). */
+  readonly activeId: string | null;
+}
+interface GlobalState {
+  readonly core: CoreState;
+  readonly plugins: Readonly<Record<string, unknown>>;
+}
+type PluginScope = 'workspace' | 'document';
+/**
+ * The context a plugin's `create()` receives. Document-scoped plugins get a
+ * context bound to one document; workspace plugins reach documents through
+ * `forDocument`. Everything here is bound to the instance's lifetime, so a
+ * controller written as plain async code is lifetime-safe by construction.
+ * `S` is the plugin's session state and `T` its settings, `NoSettings` for a
+ * plugin that declares none.
+ */
+interface PluginContext<S = unknown, T extends object = NoSettings> {
+  readonly id: string;
+  /** Unique per open of this document (workspace plugins: `workspace:<id>`). */
+  readonly instanceId: string;
+  /** The bound document (document-scoped plugins only; undefined for workspace). */
+  readonly documentId?: string;
+  readonly engine: Engine$1;
+  /**
+   * The guarded document handle: every call rejects `instance-closed` once the
+   * instance closed, is aborted at close, and throws `PluginError` instead of
+   * raw engine errors. Workspace plugins have no bound document and must use
+   * `forDocument()`; reading `doc` there throws.
+   */
+  readonly doc: DocumentHandle$1;
+  /** Resolve a live engine handle by document id; omitted follows this context's normal active/bound rule. */
+  documentHandle(documentId?: string): DocumentHandle$1 | null;
+  /** The bound document's metadata; for workspace plugins, the active document's, or null. */
+  document(): DocumentMeta | null;
+  /**
+   * The page a `PageRef` or a zero-based index names, or null when it names
+   * no page of this document. What reads use: they run while rendering, and a
+   * page deleted mid-render reads as no page instead of breaking a layer.
+   */
+  getPage(page: PageRef | number): PageInfo | null;
+  /**
+   * A page argument as every verb takes it: a `PageRef`, or a zero-based
+   * index into the document's page list. Throws `not-found` when neither
+   * names a page of this document: a verb refuses a page that isn't there.
+   */
+  pageOf(page: PageRef | number): PageInfo;
+  /** Throw `not-found` unless the ref names a page of this document. */
+  assertPageRef(ref: PageRef): void;
+  /**
+   * Whether the bound document's session holds `permission`: the same answer
+   * the engine enforces with. What every `can<Verb>()` reads.
+   * Document-scoped plugins only: a workspace context has no bound document,
+   * so this throws as reading `doc` does. A workspace plugin asks the `can<Verb>()` of the
+   * document plugin it acts through (`ctx.forDocument(token, documentId)`).
+   */
+  allows(permission: Permission): boolean;
+  /**
+   * Refuse a verb the session may not run, before any engine call: throws
+   * `permission-denied` ("`operation` requires `permission`") with
+   * `error.permission` set. Document-scoped plugins only, like `allows`.
+   */
+  assertAllowed(permission: Permission, operation: string): void;
+  /**
+   * Whether the session may fill in (`fill`) or sign (`sign`) this form
+   * field: a `fields:<action>` permission for its group, or `doc.forms.fill`
+   * (`doc.sign`) for every field. The same answer the engine enforces with.
+   * Document-scoped plugins only, like `allows`.
+   */
+  allowsField(action: 'fill' | 'sign', field: {
+    readonly groupId: string | null;
+  }): boolean;
+  /**
+   * Refuse a write to a field the session may not fill in or sign: throws
+   * `permission-denied` naming what it would take (`fields:fill:group=buyer`).
+   */
+  assertAllowedField(action: 'fill' | 'sign', field: {
+    readonly groupId: string | null;
+  }, operation: string): void;
+  get<T>(token: CapabilityToken<T>): T;
+  tryGet<T>(token: CapabilityToken<T>): T | null;
+  forDocument<T>(token: CapabilityToken<T>, documentId: string): T;
+  /** `forDocument` for an optional dependency: null when the plugin is not
+   *  installed or that document is not ready, never a throw. */
+  tryForDocument<T>(token: CapabilityToken<T>, documentId: string): T | null;
+  /** This instance's session state, changed only through pure transitions. */
+  readonly state: StateCell<S>;
+  /**
+   * The plugin's settings, as its definition declares them (`definePlugin({ settings })`):
+   * what the app registered over the defaults. They belong to the plugin as registered, not to
+   * this instance: the kernel builds them when it plans the plugin list, before any document
+   * opens, and `updateSettings()` reaches every open document and the ones opened later. Spread
+   * `api` into the capability and read `get()` in the controller; the instance's
+   * `onSettingsChanged` listeners go when it closes. The merge rules are in `settings.ts`.
+   * A plugin whose definition declares no settings has none to read: calling it throws.
+   */
+  readonly settings: () => Settings<T>;
+  /**
+   * Wake every reader: something this capability reads outside its state
+   * (a registry, a cache, a resource) changed. A no-op once the instance closed.
+   */
+  notify(): void;
+  /**
+   * Run `handler` whenever `select()` answers differently. For reacting to
+   * state this plugin does not own (the page registry, a sibling's getter);
+   * this plugin's own changes are observed with `state.onChange`.
+   * Unsubscribed when the instance closes.
+   */
+  watch<R>(select: () => R, handler: (value: R, previous: R) => void, isEqual?: (left: R, right: R) => boolean): Unsubscribe;
+  /** Resolve when the predicate holds (checked on every store change); rejects on cancel or close. */
+  waitFor(predicate: () => boolean, options?: OperationOptions): Promise<void>;
+  /**
+   * A local copy of document data the engine owns, kept current from confirmed
+   * document events (every origin) and reloads. Document-scoped plugins only;
+   * loading starts once the plugin is connected.
+   */
+  mirror<V>(spec: MirrorSpec<V>): Mirror<V>;
+  /** Like `mirror`, for data loaded page by page on demand. */
+  pageMirror<V>(spec: PageMirrorSpec<V>): PageMirror<V>;
+  /**
+   * The document's change queue, shared by its plugins: a user action is one change, staged
+   * here, shown by every mirror's `view()` at once, and sent after everything staged before it.
+   * Document-scoped plugins only. The rules are in `docs/conventions/state-and-sync.md`.
+   */
+  readonly changes: ChangeQueue;
+  /** Mint a capability event; disposed with the instance. Expose only `.on`. */
+  readonly events: {
+    source<T>(): {
+      readonly on: EventHook<T>;
+      emit(event: T): void;
+      dispose(): void;
+    };
+  };
+  /** Subscribe for the instance lifetime; the unsubscribe is owned by the kernel. */
+  listen<T>(source: Subscribable<T>, listener: (event: T) => void): void;
+  /**
+   * Register a resource teardown owned by this plugin instance. Document-
+   * scoped callbacks run when that document closes; workspace callbacks run
+   * when the kernel is destroyed. Asynchronous teardowns are awaited.
+   * Registering after the owner is already disposed runs the teardown
+   * immediately instead of dropping it, so a late registration cannot leak.
+   */
+  cleanup(fn: () => void | Promise<void>): void;
+  /**
+   * Time, from the host: `after(ms, run)` and `nextFrame(run)`, each returning
+   * its cancel, and `hasFrames`. What the instance schedules is cancelled when
+   * it closes. Plugins never read timers or frames from the environment.
+   */
+  readonly clock: PluginClock;
+  /**
+   * Register what this plugin holds back from the engine, such as text typed a moment ago or
+   * the writes in its write queue (`() => queue.idle()`). Before anything reads the whole
+   * document (`documents.download()`, `downloadLayer()`), the kernel calls every plugin's `flush` and
+   * waits for it: send what's held back, and resolve once the engine has it. Document-scoped
+   * plugins only; unregistered when the instance closes. The rules are in
+   * `docs/conventions/state-and-sync.md`.
+   */
+  onSettle(flush: (signal: AbortSignal) => Promise<void> | void): void;
+  /**
+   * Run something of the document's own around every download of its file
+   * (`documents.download()`, `downloadLayer()`): `wrap` gets the read and returns its bytes,
+   * doing what comes before and after it. The actions plugin runs the document's save actions
+   * this way. The document has settled before `wrap` is called; the first registered wraps the
+   * others. Document-scoped plugins only; unregistered when the instance closes.
+   */
+  aroundDownload(wrap: (read: () => Promise<Uint8Array>) => Promise<Uint8Array>): void;
+  /**
+   * Run something of the document's own around every print of it (`documents.print()`, a
+   * prepared print's `print()`): `wrap` gets the print and resolves when it did, doing what
+   * comes before and after it. The actions plugin runs the document's print actions this way.
+   * The first registered wraps the others. Document-scoped plugins only; unregistered when the
+   * instance closes.
+   */
+  aroundPrint(wrap: (print: () => Promise<void>) => Promise<void>): void;
+  /** Acquire a resource whose disposal the instance owns; a late arrival after close is disposed, not returned. */
+  acquire<R>(get: (lifetime: AbortSignal) => Promise<R>, dispose: (resource: R) => void | Promise<void>): Promise<R>;
+  /**
+   * Run an engine call the caller can cancel: when `signal` fires, the call is
+   * aborted (if the engine can abort it) and the returned promise rejects
+   * `operation-cancelled` at once. A signal that already fired rejects
+   * straight away; without a signal, `task` is returned as it is.
+   */
+  cancellable<T>(signal: AbortSignal | undefined, task: Promise<T>): Promise<T>;
+  /** Newest-wins lane for reads a newer call should cancel (visible search, validation). */
+  latest(key: string): LatestLane;
+  /**
+   * Per-key submission-order queue for multi-step writes; failures do not
+   * poison later work. An operation queued with `{ signal }` whose signal
+   * fired while it waited is skipped and rejects `operation-cancelled`.
+   */
+  serialQueue(key?: string): SerialQueue;
+}
+/**
+ * A plugin instance's session state. The value is replaced, never mutated:
+ * `update` applies a pure transition, and a transition that returns the
+ * current value changes nothing.
+ */
+interface StateCell<S> {
+  get(): S;
+  update<Args extends unknown[]>(transition: (state: S, ...args: Args) => S, ...args: Args): void;
+  /** Fires synchronously after every committed change of this instance's state. */
+  readonly onChange: EventHook<StateChange<S>>;
+}
+/** One committed state change: the value before and after. */
+interface StateChange<S> {
+  readonly next: S;
+  readonly previous: S;
+}
+/**
+ * A plugin definition. `scope` decides multiplexing:
+ *   'workspace' (default) — one instance; can see every document.
+ *   'document'            — one instance per open document; authored single-document.
+ *
+ * Its types come from its own fields: the state `S` from `state`, the capability
+ * `C` from `token`, the settings `T` from `settings.defaults`. `create` and
+ * `inScope` are checked against them and never name them (`NoInfer`), so a
+ * controller that returns less than the capability is a type error, not a
+ * narrower capability.
+ */
+interface PluginDef<S = unknown, C = unknown, T extends object = NoSettings> {
+  readonly id: string;
+  readonly token?: CapabilityToken<C>;
+  readonly scope?: PluginScope;
+  readonly requires?: ReadonlyArray<CapabilityToken<unknown>>;
+  readonly optional?: ReadonlyArray<CapabilityToken<unknown>>;
+  /**
+   * The plugin resolves capabilities for code the host supplies (the commands
+   * plugin runs command definitions that act on any capability), so it cannot
+   * declare them. Resolving an undeclared token is then allowed; the kernel
+   * neither orders nor validates those dependencies.
+   */
+  readonly resolvesAnyCapability?: true;
+  /** Initial session state, built fresh for every instance. Omit for stateless plugins. */
+  readonly state?: () => S;
+  /**
+   * The plugin's settings: its defaults, and what the app registered (the factory's config).
+   * The kernel builds one store per registration from it when it plans the plugin list, so the
+   * settings can be read and changed before any document opens (`kernel.settingsOf(token)`).
+   * The plugin reads them with `ctx.settings()`. Omit for a plugin without settings.
+   */
+  readonly settings?: SettingsDeclaration<T>;
+  /**
+   * Build the instance's API and, optionally, the connections (subscriptions
+   * to engine events and sibling capabilities) that start once every
+   * dependency is constructed. Runs once per instance.
+   */
+  readonly create: NoInfer<(ctx: PluginContext<S, T>) => {
+    api: C;
+    connect?: () => void;
+  }>;
+  /**
+   * This capability as seen from inside a document's scope: calls that leave out the document
+   * use `documentId` instead of the active one. Workspace plugins only. The kernel builds the
+   * view once per document and hands it out whenever that document is named
+   * (`kernel.capability(token, documentId)`, `ctx.forDocument`, a `<DocumentScope>`).
+   */
+  readonly inScope?: NoInfer<(api: C, documentId: string) => C>;
+}
+type AnyPlugin = PluginDef<any, any, any>;
+/** Where a document is: opening, waiting for its password, open, or failed to open. */
+type DocumentStatus = 'loading' | 'locked' | 'ready' | 'error';
+/**
+ * An open document, as its tab shows it. The same object until one of its fields changes, so a
+ * reader that compares by reference re-renders only for its own document.
+ */
+interface DocumentInfo {
+  /** The document's id, for `close(id)`, `unlock(id, …)` and a document scope. */
+  readonly id: string;
+  /** The name its tab shows, from `open()` or `rename()`. */
+  readonly name?: string;
+  readonly status: DocumentStatus;
+  /** How many pages it has; 0 until it's `ready`. */
+  readonly pageCount: number;
+  /**
+   * Whether it has changes that weren't downloaded yet. Always false on an engine that stores
+   * every change as it's made (the cloud engine).
+   */
+  readonly hasUnsavedChanges: boolean;
+  /** `locked` only: a password was tried and was wrong. */
+  readonly passwordProvided?: boolean;
+  /** `error` only: why it couldn't be opened, in the plugin error vocabulary. */
+  readonly error?: PluginErrorInfo;
+}
+/** A document waiting for its password. */
+interface LockedDocumentInfo extends DocumentInfo {
+  readonly status: 'locked';
+  readonly passwordProvided: boolean;
+}
+/** A document that couldn't be opened, and why. */
+interface FailedDocumentInfo extends DocumentInfo {
+  readonly status: 'error';
+  readonly error: PluginErrorInfo;
+}
+/** A file the viewer downloads itself, with the document's cancel signal: relative to the page, or absolute. */
+interface UrlSource {
+  readonly kind: 'url';
+  readonly url: string;
+}
+/** Options for opening a document: the tab (`name`, `activate`), the engine's `OpenOptions`, and a `signal`. */
+type OpenDocumentOptions = OpenOptions & {
+  /** Make it the active document; true unless given. */
+  readonly activate?: boolean;
+  /** The name its tab shows. */
+  readonly name?: string;
+  /** Cancels the open: the document closes, and `open()` rejects `operation-cancelled`. */
+  readonly signal?: AbortSignal;
+};
+/**
+ * What `open()` accepts: an engine `OpenInput`, a URL the viewer downloads, or a function that
+ * returns one of them. A function runs under the document's loading state, so the tab exists
+ * while it fetches; the `signal` it receives fires when the document is closed first, so pass it
+ * to `fetch()`.
+ */
+type OpenSource = OpenInput | UrlSource | ((signal: AbortSignal) => OpenInput | UrlSource | Promise<OpenInput | UrlSource>);
+/** What `open()` and `retry()` resolve: the document, ready or locked. */
+interface OpenDocumentResult {
+  readonly document: DocumentInfo;
+}
+/** Options for `unlock()`: the password, and a `signal` that stops trying it. */
+interface UnlockOptions extends OperationOptions {
+  readonly password: string;
+}
+/** Options for `download()`. */
+interface DownloadOptions extends OperationOptions {
+  /**
+   * `'incremental'` (the default) appends the changes to the original file, so existing
+   * signatures stay valid; `'rewrite'` writes a fresh file without earlier revisions.
+   */
+  readonly mode?: PdfSaveMode;
+}
+/**
+ * How a print comes out.
+ *
+ * - `'pdf'`: the printer prints a copy of the pages as they print (`pages.extract()` with
+ *   `flatten: { usage: 'print' }`): sharp text and lines. It takes `doc.print.high`, a right to
+ *   keep the copy (`doc.download` or `doc.download.flattened`: every print dialog can save it as
+ *   a file), and a printer that prints a PDF (`HostPrinter.stagePdf`).
+ * - `'images'` otherwise: pictures of the pages, drawn by the print rules, at 150 DPI with
+ *   `doc.print` or 300 DPI with `doc.print.high` (Acrobat's low and high resolution printing).
+ */
+type PrintQuality = {
+  readonly kind: 'pdf';
+} | {
+  readonly kind: 'images';
+  readonly dpi: PrintDpi;
+};
+/** How far preparing a print got. */
+interface PrintProgress {
+  /** Pages that are ready: one at a time as pictures, all at once as a PDF. */
+  readonly pagesRendered: number;
+  /** Pages the print has. */
+  readonly pageCount: number;
+}
+interface PrintOptions extends OperationOptions {
+  /** The pages to print, in this order. Default: every page. */
+  readonly pages?: readonly PageRef[];
+  /**
+   * Print the annotations that print. Default: when the user may read them. Form fields print
+   * when the user may read the form, whatever this says.
+   */
+  readonly includeAnnotations?: boolean;
+  /** Called each time pages are ready, and once before the first. */
+  readonly onProgress?: (progress: PrintProgress) => void;
+}
+/**
+ * A print got ready by `documents.preparePrint()`. Everything slow already happened, so
+ * `print()` opens the print dialog at once.
+ */
+interface PreparedPrint {
+  readonly quality: PrintQuality;
+  /** How many pages it prints. */
+  readonly pageCount: number;
+  /**
+   * Whether `print()` must run inside the user's tap or click: the printer's `needsTap`. Safari
+   * doesn't print what waited for its pages (iOS refuses the dialog, the Mac prints blank pages),
+   * so a dialog that prepared on a tap asks for another once the print is ready. When `false`,
+   * print as soon as it is ready.
+   */
+  readonly needsTap: boolean;
+  /**
+   * Open the print dialog. The document's own print actions run around it, when the actions
+   * plugin is installed; when they, or anyone, change the document after it was prepared, it is
+   * prepared again first. Resolves when the printer has the job. When the printer refuses a
+   * PDF, the same pages print as pictures. Rejects `invalid-input` once disposed,
+   * `operation-cancelled` when `signal` fires before the dialog opens.
+   */
+  print(options?: OperationOptions): Promise<void>;
+  /** Free what preparing took. Closing the document does too. */
+  dispose(): void;
+}
+/** One printed sheet: a picture of a page, and the page's size on paper. */
+interface PrintSheet {
+  /** A PNG of the page, drawn by the print rules. */
+  readonly image: Blob;
+  /** The page's width in points (1/72 inch), as it prints. */
+  readonly widthPt: number;
+  /** The page's height in points. */
+  readonly heightPt: number;
+}
+/** What a printer got ready: `print()` opens the print dialog with it. */
+interface StagedPrint {
+  /** Open the print dialog. Resolves once the printer has the job. */
+  print(): Promise<void>;
+  /** Free what staging took. */
+  dispose(): void;
+}
+/**
+ * Where prints go: the host's print dialog. A browser passes `browserPrinter()` from
+ * `@embedpdf/web`; an app with its own print path (a desktop shell, a native app) passes its
+ * own.
+ */
+interface HostPrinter {
+  /**
+   * `true` when this printer prints only while the user's tap or click is being handled (Safari),
+   * so a print that waited for its pages needs another tap. Default `false`.
+   */
+  readonly needsTap?: boolean;
+  /**
+   * Get the sheets ready to print, so `print()` on what it returns opens the dialog at once.
+   * `name` names the print job. Rejects when `signal` fires.
+   */
+  stage(sheets: readonly PrintSheet[], options: {
+    readonly name: string;
+    readonly signal?: AbortSignal;
+  }): Promise<StagedPrint>;
+  /**
+   * Present when this printer prints a PDF file on this device: a browser whose own PDF viewer
+   * prints it, a desktop shell, a native print API. Gets `pdf`, a copy of the pages as they
+   * print, ready as `stage()` gets sheets ready. A printer without it prints pictures.
+   */
+  stagePdf?(pdf: Uint8Array, options: {
+    readonly name: string;
+    readonly signal?: AbortSignal;
+  }): Promise<StagedPrint>;
+}
+/**
+ * One boot document for `documents.openAll()` — the shared shape every
+ * framework adapter's `initialDocuments` input uses (adapters re-export it,
+ * never redefine it). `active` picks the selected tab (default: the first);
+ * all other open options (name, password, scope, identity, …) pass straight
+ * through to `open()`, so the declarative and imperative paths cannot drift.
+ */
+type InitialDocument = {
+  source: OpenSource;
+  active?: boolean;
+} & Omit<OpenDocumentOptions, 'activate' | 'signal'>;
+interface DocumentOpenedEvent {
+  readonly documentId: string;
+  readonly info: DocumentInfo;
+}
+interface DocumentOpenFailedEvent {
+  readonly documentId: string;
+  readonly error: PluginErrorInfo;
+}
+interface DocumentLockedEvent {
+  readonly documentId: string;
+  readonly passwordProvided: boolean;
+}
+interface DocumentClosedEvent {
+  readonly documentId: string;
+}
+interface DocumentActiveChangedEvent {
+  readonly documentId: string | null;
+  readonly previousDocumentId: string | null;
+}
+interface DocumentPagesChangedEvent {
+  readonly documentId: string;
+  readonly revision: number;
+  readonly pages: readonly PageInfo[];
+}
+interface DocumentUnsavedChangesChangedEvent {
+  readonly documentId: string;
+  readonly hasUnsavedChanges: boolean;
+}
+/**
+ * The document registry. A call that leaves out the document uses the document in scope when
+ * the capability was resolved for one (`kernel.capability(DocumentsToken, documentId)`, a
+ * `<DocumentScope>`), and the active document otherwise. Its verbs reject with `PluginError`.
+ */
+interface DocumentsCapability {
+  /**
+   * Open a document and make it the active one (unless `activate: false`). Its tab exists at
+   * once; the promise resolves `{ document }` once it's ready, or locked with a password.
+   * The document's own `scope` and `identity` replace the viewer's. Rejects with the reason it
+   * couldn't be opened (the tab then shows `error`), or `operation-cancelled` when it was closed
+   * or `signal` fired first.
+   */
+  open(source: OpenSource, options?: OpenDocumentOptions): Promise<OpenDocumentResult>;
+  /**
+   * Whether `open()` can open a file from the user's computer (its bytes, or a URL the viewer
+   * downloads): the engine's `canOpenFiles`. True with the local engine; false with the cloud
+   * engine, whose documents come from your server.
+   */
+  canOpenFiles(): boolean;
+  /**
+   * Open a failed document (`status: 'error'`) again, with the same source and options, in its
+   * own tab: it keeps its id and its place, and the active document stays the active one.
+   * Resolves like `open()`. Rejects `invalid-input` for a document that didn't fail.
+   */
+  retry(id: string, options?: OperationOptions): Promise<OpenDocumentResult>;
+  /** Change the name its tab shows; the file doesn't change. */
+  rename(id: string, name: string): void;
+  /**
+   * Open several documents, as `initialDocuments` does: every tab appears at once, in array
+   * order, and the one marked `active` (else the first) becomes the active one, decided now, so
+   * a slow document never steals the focus. A failure shows in that document's `status`
+   * instead of rejecting. Returns the tabs' ids.
+   */
+  openAll(documents: readonly InitialDocument[]): readonly string[];
+  /**
+   * Unlock a `locked` document with its password; it opens as it would have. Rejects
+   * `permission-denied` on a wrong password, and the document stays locked so you can ask
+   * again; `invalid-input` for a document that isn't locked.
+   */
+  unlock(id: string, options: UnlockOptions): Promise<void>;
+  /** Close a document and free its memory; the next one becomes active. Closing one still opening cancels it. */
+  close(id: string): Promise<void>;
+  /** Close every document. */
+  closeAll(): Promise<void>;
+  /** Make a document the active one: the one every component talks to outside a document scope. */
+  setActive(id: string): void;
+  /** The active document's id, or null with none open. */
+  getActiveId(): string | null;
+  /** The active document's fields, or null with none open. */
+  getActive(): DocumentInfo | null;
+  /** Every open document in tab order, loading, locked and failed ones included; the same array until one changes. */
+  list(): readonly DocumentInfo[];
+  /** A document's fields (the one in scope without an id), or null when it isn't open. */
+  get(id?: string): DocumentInfo | null;
+  /** Whether a document is open. */
+  has(id: string): boolean;
+  /** How many documents are open. */
+  getCount(): number;
+  /** The open documents' ids, in tab order. */
+  getOrder(): readonly string[];
+  /** Put every document in a new order at once; `ids` holds the id of every open document. */
+  setOrder(ids: readonly string[]): void;
+  /** Move a document to another place in the tab order. */
+  move(id: string, toIndex: number): void;
+  /** Swap two documents in the tab order. */
+  swap(id: string, otherId: string): void;
+  /**
+   * The PDF with every change, as bytes. It first waits for changes still on their way (text
+   * typed a moment ago, writes queued), and runs the document's own save actions around the
+   * read when the actions plugin is installed. Afterwards `hasUnsavedChanges` is false, unless
+   * something changed meanwhile. Rejects `permission-denied` without `doc.download`,
+   * `not-ready` with no open document, `operation-cancelled` when `signal` fires.
+   */
+  download(id?: string, options?: DownloadOptions): Promise<Uint8Array>;
+  /**
+   * Only the changes, as a layer artifact you open again over the original
+   * (`{ kind: 'layerBytes', baseBytes, layer: { kind: 'artifact', bytes } }`). Waits and runs the
+   * save actions like `download()`. Rejects `unsupported` when the document wasn't opened with a
+   * layer or the engine keeps layers itself (the cloud engine), and as `download()` does.
+   */
+  downloadLayer(id?: string, options?: OperationOptions): Promise<Uint8Array>;
+  /** Whether the document (the one in scope without an id) may be downloaded: `doc.download`. */
+  canDownload(id?: string): boolean;
+  /**
+   * Get a print of the document ready (the one in scope without an id): wait for changes still
+   * on their way, make the pages as they print (a PDF copy or pictures, as `getPrintQuality()`
+   * says), and hand them to the host's printer. `onProgress` follows the pages. Rejects
+   * `permission-denied` without `doc.print`, `unsupported` when the host gave no printer,
+   * `not-found` for a page the document doesn't have, `invalid-input` for an empty `pages` or a
+   * page named twice, `not-ready` with no open document, `operation-cancelled` when `signal`
+   * fires.
+   */
+  preparePrint(id?: string, options?: PrintOptions): Promise<PreparedPrint>;
+  /**
+   * Prepare a print and print it: `preparePrint()`, then its `print()`. The document's own
+   * print actions run around the dialog when the actions plugin is installed. Rejects as
+   * `preparePrint()` does. A printer that `needsTap` may refuse the dialog once preparing took a
+   * while: there, prepare first and print from a tap.
+   */
+  print(id?: string, options?: PrintOptions): Promise<void>;
+  /** How a print of the document comes out for this user, or null when they can't print it. */
+  getPrintQuality(id?: string): PrintQuality | null;
+  /** Whether the document (the one in scope without an id) may be printed: `doc.print`, and the host gave a printer. */
+  canPrint(id?: string): boolean;
+  /**
+   * The document's pages, in order (the one in scope without an id). The same array until a
+   * page is added, removed, moved or rotated.
+   */
+  listPages(id?: string): readonly PageInfo[];
+  /** One page, by its `PageRef` or its zero-based index, or null when the document doesn't have it. */
+  getPage(page: PageRef | number, id?: string): PageInfo | null;
+  /** A page's position, from 0, or `-1` when the document doesn't have it. */
+  getPageIndex(ref: PageRef, id?: string): number;
+  /** A number that goes up each time pages are added, removed, moved or rotated; `-1` with no document. */
+  getRevision(id?: string): number;
+  /** A document is open and ready. */
+  readonly onOpened: EventHook<DocumentOpenedEvent>;
+  /** A document couldn't be opened; its tab shows `error`. */
+  readonly onOpenFailed: EventHook<DocumentOpenFailedEvent>;
+  /** A document needs its password. */
+  readonly onLocked: EventHook<DocumentLockedEvent>;
+  /** A document was closed, after its resources were released. */
+  readonly onClosed: EventHook<DocumentClosedEvent>;
+  /** Another document became the active one. */
+  readonly onActiveChanged: EventHook<DocumentActiveChangedEvent>;
+  /** Pages were added, removed, moved or rotated. */
+  readonly onPagesChanged: EventHook<DocumentPagesChangedEvent>;
+  /** A document got its first unsaved change, or was downloaded. */
+  readonly onUnsavedChangesChanged: EventHook<DocumentUnsavedChangesChangedEvent>;
+}
+/** Built-in token for the document registry capability (provided by the kernel). */
+declare const DocumentsToken: CapabilityToken<DocumentsCapability>;
+//#endregion
+export { PdfRotation as $, StagedChange as $t, HostPrinter as A, SerialQueue as At, OpenSource as B, SliceChange as Bt, DocumentsToken as C, NoSettings as Ct, EventOrigin as D, SettingsDeclaration as Dt, EngineFactory as E, SettingsChangedEvent as Et, MetadataUpdateResult as F, Mirror as Ft, PageInsertBlankSpec as G, timerClock as Gt, PageDeleteResult as H, Cancel as Ht, OpenDocumentOptions as I, MirrorChange as It, PageObjectNumber as J, HeldChange as Jt, PageInsertResult as K, ChangeLabel as Kt, OpenDocumentResult as L, MirrorReload as Lt, InitialDocument as M, PageMirror as Mt, LockedDocumentInfo as N, PageMirrorChange as Nt, FailedDocumentInfo as O, SettingsOf as Ot, MetadataPatch as P, PageMirrorSpec as Pt, PdfDestination as Q, SettledChange as Qt, OpenInput as R, MirrorSpec as Rt, DocumentsCapability as S, DeepPartial as St, Engine$1 as T, SettingsApi as Tt, PageDestination as U, HostClock as Ut, OperationOptions as V, SliceLease as Vt, PageInfo as W, PluginClock as Wt, PageReorderResult as X, PendingChange as Xt, PagePosition as Y, HoldOptions as Yt, PageRotateResult as Z, PredictedOp as Zt, DocumentOpenFailedEvent as _, StateChange as _t, CustomMetadata as a, PluginErrorInfo as an, PluginDef as at, DocumentStatus as b, Unsubscribe as bt, DocCapability as c, toPluginErrorInfo as cn, PrintOptions as ct, DocumentEvent$1 as d, LatestRun as dn, PrintSheet as dt, EventHook as en, PdfSaveMode as et, DocumentHandle$1 as f, createLatestLane as fn, PromiseMemberOf as ft, DocumentMetadata as g, StateCell as gt, DocumentMeta as h, StagedPrint as ht, CoreState as i, PluginErrorCode as in, PluginContext as it, Identity$1 as j, createSerialQueue as jt, GlobalState as k, mergeSettings as kt, DocumentActiveChangedEvent as l, LatestCancellation as ln, PrintProgress as lt, DocumentLockedEvent as m, ResourceStatus as mt, BatchResult as n, createEventHook as nn, PendingMeta as nt, CustomMetadataPatch as o, isPluginError as on, PluginScope as ot, DocumentInfo as p, PromiseMembers as pt, PageLayout$1 as q, ChangeQueue as qt, CapabilityToken as r, PluginError as rn, Permission as rt, CustomMetadataUpdateResult as s, toPluginError as sn, PreparedPrint as st, AnyPlugin as t, EventHookSource as tn, PdfSize as tt, DocumentClosedEvent as u, LatestLane as un, PrintQuality as ut, DocumentOpenedEvent as v, Subscribable as vt, DownloadOptions as w, Settings as wt, DocumentUnsavedChangesChangedEvent as x, UrlSource as xt, DocumentPagesChangedEvent as y, UnlockOptions as yt, OpenOptions as z, reload as zt };
+//# sourceMappingURL=types-CfnZ7go6.d.cts.map