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

package/dist/index.d.ts

@@ -1,277 +1,71 @@
-import { AbortablePromise, CONTINUOUS_RENDER_POLICY, DocCapability, DocumentEvent, DocumentHandle, DocumentMetadata, Engine, EngineFactory, EngineRenderPolicy, EngineRenderPolicy as EngineRenderPolicy$1, MetadataPatch, MetadataUpdateResult, OpenInput, OpenOptions, PageDeleteResult, PageHandle, PageImageHandle, PageImageObjectUrl, PageImageOptions, PageInsertBlankSpec, PageInsertResult, PageLayout, PageMoveResult, PageObjectNumber, PageRaster, PageRenderOptions, PageRenderTarget, PageRenderViewport, PageRotateResult, PageRotation, PdfDestination, PdfRect, PdfSaveMode, PdfSize, PermissionDenied, snapAppearanceScale, snapFullPageViewport, snapTileScale } from "@embedpdf/engine-core/runtime";
-//#region src/types.d.ts
-type Unsubscribe = () => void;
-/** Every state transition is a plain, serializable action. */
-interface Action {
-  readonly type: string;
+import { $ as PdfSaveMode, $t as isPluginError, A as Identity, At as MirrorReload, B as OperationOptions, Bt as ChangeQueue, C as DocumentsToken, Ct as SerialQueue, D as EventOrigin, Dt as PageMirrorSpec, E as EngineFactory, Et as PageMirrorChange, F as OpenDocumentOptions, Ft as Cancel, G as PageInsertResult, Gt as SettledChange, H as PageDestination, Ht as HoldOptions, I as OpenDocumentResult, It as HostClock, J as PagePosition, Jt as EventHookSource, K as PageLayout, Kt as StagedChange, L as OpenInput, Lt as PluginClock, M as LockedDocumentInfo, Mt as reload, N as MetadataPatch, Nt as SliceChange, O as FailedDocumentInfo, Ot as Mirror, P as MetadataUpdateResult, Pt as SliceLease, Q as PdfRotation, Qt as PluginErrorInfo, R as OpenOptions, Rt as timerClock, S as DocumentsCapability, St as mergeSettings, T as Engine, Tt as PageMirror, U as PageInfo, Ut as PendingChange, V as PageDeleteResult, Vt as HeldChange, W as PageInsertBlankSpec, Wt as PredictedOp, X as PageRotateResult, Xt as PluginError, Y as PageReorderResult, Yt as createEventHook, Z as PdfDestination, Zt as PluginErrorCode, _ as DocumentOpenFailedEvent, _t as Settings, a as CustomMetadata, an as createLatestLane, at as PluginScope, b as DocumentStatus, bt as SettingsDeclaration, c as DocCapability, ct as ResourceStatus, d as DocumentEvent, dt as Subscribable, en as toPluginError, et as PdfSize, f as DocumentHandle, ft as UnlockOptions, g as DocumentMetadata, gt as NoSettings, h as DocumentMeta, ht as DeepPartial, i as CoreState, in as LatestRun, it as PluginDef, j as InitialDocument, jt as MirrorSpec, k as GlobalState, kt as MirrorChange, l as DocumentActiveChangedEvent, lt as StateCell, m as DocumentLockedEvent, mt as UrlSource, n as BatchResult, nn as LatestCancellation, nt as Permission, o as CustomMetadataPatch, ot as PromiseMemberOf, p as DocumentInfo, pt as Unsubscribe, q as PageObjectNumber, qt as EventHook, r as CapabilityToken, rn as LatestLane, rt as PluginContext, s as CustomMetadataUpdateResult, st as PromiseMembers, t as AnyPlugin, tn as toPluginErrorInfo, tt as PendingMeta, u as DocumentClosedEvent, ut as StateChange, v as DocumentOpenedEvent, vt as SettingsApi, w as DownloadOptions, wt as createSerialQueue, x as DocumentUnsavedChangesChangedEvent, xt as SettingsOf, y as DocumentPagesChangedEvent, yt as SettingsChangedEvent, z as OpenSource, zt as ChangeLabel } from "./types-t-DaU8VK.js";
+import { AbortablePromise, AnnotationAppearanceImage, AnnotationRef, CONTINUOUS_RENDER_POLICY, CallFacts, CallPriority, DocumentHandle as DocumentHandle$1, EngineRenderPolicy, Identity as Identity$1, PageHandle, PageImageHandle, PageImageObjectUrl, PageImageOptions, PageLayerRights, PageRaster, PageRef, PageRenderLayers, PageRenderOptions, PageRenderTarget, PageRenderViewport, PdfRect, PermissionDenied, WorkingSetPage, annotationKey, decodePageKey, encodePageKey, isLocalEngine, pageRefsEqual, resolvePageLayers, snapAppearanceScale, snapFullPageViewport, snapTileScale, toPageRef } from "@embedpdf/engine-core/runtime";
+//#region src/viewer-settings.d.ts
+/** How each page looks before its picture arrives, and around it. */
+interface ViewerPageSettings {
+  /** The page before its picture arrives. */
+  readonly background: string;
+  /** The shadow under each page, as CSS `box-shadow`; `'none'` for none. */
+  readonly shadow: string;
 }
-/** Kernel-emitted document-lifecycle actions; plugins may react via `onAction`. */
-declare const CORE_DOCUMENT_ADDED = "@@core/document-added";
-declare const CORE_DOCUMENT_REMOVED = "@@core/document-removed";
-declare const CORE_ACTIVE_CHANGED = "@@core/active-changed";
-declare const CORE_ORDER_CHANGED = "@@core/order-changed";
-/** A document's page registry was replaced by a mutation event (rotate/move/delete). */
-declare const CORE_DOCUMENT_PAGES_UPDATED = "@@core/document-pages-updated";
-/** A tab slot was reserved: `open()` was called; the document is loading. */
-declare const CORE_DOCUMENT_OPENING = "@@core/document-opening";
-/** The engine reports the document needs a password (`documents.unlock`). */
-declare const CORE_DOCUMENT_LOCKED = "@@core/document-locked";
-/** The open failed; the tab stays with `status: 'error'` until closed. */
-declare const CORE_DOCUMENT_OPEN_FAILED = "@@core/document-open-failed";
-/** A typed handle to a capability — typed resolution, no string casts. */
-interface CapabilityToken<T> {
-  readonly name: string;
+interface ViewerSettings {
   /**
-   * 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").
+   * Who the user is, for every document opened without an `identity` of its own: the author of
+   * the annotations they make, and whom `:self` and `:group` permissions are checked against.
+   * Null for nobody in particular. The local engine only; the cloud reads it from the token.
    */
-  readonly hint?: string;
-  /** phantom — never present at runtime */
-  readonly __type?: T;
-}
-/**
- * What the kernel knows about an open document — the page registry captured at open.
- * `pages` is the engine's own snapshot (`PageLayout`: index, pageObjectNumber, size,
- * rotation, label, boxes). The `pageObjectNumber` (pon) is the durable per-page
- * identity; the array index is only display order.
- */
-interface DocumentMeta {
-  readonly id: string;
-  readonly name?: string;
-  readonly pageCount: number;
-  readonly pages: readonly PageLayout[];
-  /**
-   * 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;
+  readonly identity: Identity$1 | null;
   /**
-   * 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`.
+   * What the user may do, as permissions, in every document opened without a `scope` of its
+   * own. Null for everything. The local engine only; the cloud reads it from the token.
    */
-  readonly renderPolicy: EngineRenderPolicy$1;
-}
-/**
- * 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 receives. Document-scoped plugins get a context bound to a
- * single document — `documentId`, `document()` (metadata), `doc` (the engine handle),
- * and `get()` resolving document-scoped capabilities for it.
- */
-interface PluginContext<S, A extends Action = Action> {
-  readonly id: string;
-  readonly engine: Engine;
-  /** The bound document (document-scoped plugins only; undefined for workspace). */
-  readonly documentId?: string;
-  /** The bound document's engine handle; for workspace plugins, the active doc's handle, or null. */
-  readonly doc: DocumentHandle | null;
-  /** Resolve a live engine handle by document id; omitted follows this context's normal active/bound rule. */
-  documentHandle(documentId?: string): DocumentHandle | null;
-  getState(): S;
-  dispatch(action: A): void;
-  subscribe(listener: () => void): Unsubscribe;
-  core(): CoreState;
-  /** The bound document's metadata; for workspace plugins, the active doc's, or null. */
-  document(): DocumentMeta | null;
-  get<T>(token: CapabilityToken<T>): T;
-  forDocument<T>(token: CapabilityToken<T>, documentId: string): T;
-  tryGet<T>(token: CapabilityToken<T>): T | null;
-  /** `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;
-  /**
-   * 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 — a late registration cannot leak.
-   * Safe for capability-held timers, runtimes, subscriptions, object URLs,
-   * and binary caches.
-   */
-  cleanup(fn: () => void | Promise<void>): void;
-}
-/** Side-effect context: the only place async/IO/cross-plugin reactions live. */
-interface EffectContext<S, A extends Action = Action> extends PluginContext<S, A> {
-  watch<R>(select: () => R, handler: (value: R, previous: R) => void, isEqual?: (a: R, b: R) => boolean): Unsubscribe;
-  onAction(type: string, handler: (action: Action) => void): Unsubscribe;
+  readonly scope: readonly string[] | null;
+  /** The color every part without a color of its own follows. */
+  readonly accent: string;
+  readonly page: ViewerPageSettings;
 }
-/**
- * A plugin definition. `scope` decides multiplexing:
- *   'workspace' (default) — one instance; can see every document.
- *   'document'            — one instance PER open document; authored single-document.
- */
-interface PluginDef<S = unknown, A extends Action = Action, C = unknown> {
-  readonly id: string;
-  readonly token?: CapabilityToken<C>;
-  readonly scope?: PluginScope;
-  readonly requires?: ReadonlyArray<CapabilityToken<unknown>>;
-  readonly optional?: ReadonlyArray<CapabilityToken<unknown>>;
-  readonly initialState?: S | (() => S);
-  readonly reduce?: (state: S, action: A) => S;
-  readonly capability?: (ctx: PluginContext<S, A>) => C;
-  readonly init?: (ctx: PluginContext<S, A>) => void | Promise<void>;
-  readonly effects?: (ctx: EffectContext<S, A>) => void;
-}
-type AnyPlugin = PluginDef<any, any, any>;
-type DocStatus = 'loading' | 'locked' | 'ready' | 'error';
-interface DocInfo {
-  id: string;
-  name?: string;
-  /** Lifecycle state — the tab bar renders directly off this. */
-  status: DocStatus;
-  /** 0 until the document is `ready`. */
-  pageCount: number;
-  /** `locked` only: a supplied password was rejected (show "incorrect"). */
-  passwordProvided?: boolean;
+/** The viewer's settings when the app gives none; the colors are the theming page's defaults. */
+declare const VIEWER_DEFAULTS: ViewerSettings;
+/** An identity is one person: a new one replaces the last instead of merging into it. */
+declare const VIEWER_WHOLE_SETTINGS: readonly ["identity"];
+/** The viewer settings a framework's viewer takes as its props or config; each one is optional. */
+interface ViewerSettingsInput {
+  readonly identity?: Identity$1 | null;
+  readonly scope?: readonly string[] | null;
+  readonly accent?: string;
+  readonly page?: Partial<ViewerPageSettings>;
 }
-/** Field-wise DocInfo equality — the ONE definition every adapter's reactive
- *  `docs` read keys on, so a new lifecycle field can never silently stop
- *  re-rendering one framework's tab bar. */
-declare const docInfoEquals: (a: DocInfo, b: DocInfo) => boolean;
-declare const docInfoListEquals: (a: readonly DocInfo[], b: readonly DocInfo[]) => boolean;
-/** Options for opening a document: kernel concerns (activate/name) + engine OpenOptions. */
-type OpenDocumentOptions = OpenOptions & {
-  activate?: boolean;
-  name?: string;
-};
-/**
- * What `open()` accepts: an engine `OpenInput`, or a thunk producing one.
- * The thunk form makes the FETCH happen under the loading tab — the slot is
- * reserved synchronously, then the thunk runs (network), then the engine
- * opens. Prefer it for anything that isn't already in memory.
- *
- * The thunk receives an AbortSignal that fires if the tab is closed while
- * the fetch is still running — pass it to `fetch()` so a closed tab stops
- * the network work. Zero-argument thunks keep working unchanged.
- */
-type OpenSource = OpenInput | ((signal: AbortSignal) => OpenInput | Promise<OpenInput>);
 /**
- * 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.
+ * The viewer's settings as a framework's viewer component gives them: a setting left out is its
+ * default, and `page` fills in the side it leaves out. Every adapter's viewer starts the kernel
+ * with this and passes it again when its props change.
  */
-type InitialDocument = {
-  source: OpenSource;
-  active?: boolean;
-} & Omit<OpenDocumentOptions, 'activate'>;
-interface DocumentsCapability {
-  open(input: OpenSource, options?: OpenDocumentOptions): Promise<string>;
-  /**
-   * Boot-open a batch: fires every `open()` WITHOUT awaiting, so each tab
-   * slot is reserved synchronously — all tabs exist immediately, in array
-   * order — and exactly ONE is selected (the `active` entry, else the
-   * first), decided at request time so a slow document can never steal
-   * focus. Failures surface as the tab's `error`/`locked` status, never as
-   * unhandled rejections. This is kernel-owned POLICY: adapters call this
-   * one line instead of each re-implementing activation and error handling.
-   */
-  openAll(docs: readonly InitialDocument[]): void;
-  /**
-   * Unlock a `locked` document with a password and promote it to `ready`.
-   * Rejects with the engine's DocPasswordIncorrect on a wrong password —
-   * the document stays locked and unlock can be called again. Identical
-   * behavior on the local (worker loads the parked bytes) and cloud
-   * (/access grant) engines.
-   */
-  unlock(id: string, input: {
-    password: string;
-  }): Promise<void>;
-  close(id: string): Promise<void>;
-  closeAll(): Promise<void>;
-  setActive(id: string): void;
-  activeId(): string | null;
-  list(): DocInfo[];
-  get(id: string): DocInfo | null;
-  has(id: string): boolean;
-  count(): number;
-  order(): string[];
-  /** Move a document (tab) to a new position in the order. */
-  move(id: string, toIndex: number): void;
-  /** Swap two documents (tabs) in the order. */
-  swap(a: string, b: string): void;
-  /**
-   * Save the COMPLETE document (base + layer) to PDF bytes. `mode` is
-   * `'incremental'` (append changes, original bytes preserved) or `'rewrite'`
-   * (flatten to a fresh PDF). Defaults to the active document.
-   */
-  download(id?: string, opts?: {
-    mode?: PdfSaveMode;
-  }): Promise<Uint8Array>;
-  /**
-   * Export JUST the document's LAYER artifact (re-openable via `OpenInputLayerBytes`).
-   * Rejects when the document was opened without a layer, or the engine can't
-   * export one (cloud manages layers server-side — `DocumentHandle.downloadLayer`
-   * is absent there). Defaults to the active document.
-   */
-  downloadLayer(id?: string): Promise<Uint8Array>;
-  /**
-   * Session authority over a document — the sanctioned surface for the ONE
-   * chrome exception in permissions.md: kernel-level features with a 1:1
-   * capability and no owning plugin (print via `'doc.print'`, download via
-   * `'doc.download'` — the verbs live on THIS capability). Everything else
-   * asks the owning plugin's twins, never a raw capability string. Defaults
-   * to the active document; `false` with no (ready) document.
-   */
-  allows(cap: DocCapability, id?: string): boolean;
-}
-/** Built-in token for the document registry capability (provided by the kernel). */
-declare const DocumentsToken: CapabilityToken<DocumentsCapability>;
+declare function viewerSettingsOf({ identity, scope, accent, page }: ViewerSettingsInput): ViewerSettings;
 //#endregion
 //#region src/kernel.d.ts
 /** Kernel lifecycle. Monotonic: created → starting → started, then destroying →
  *  destroyed; `failed` is a terminal branch off starting. */
 type KernelStatus = 'created' | 'starting' | 'started' | 'failed' | 'destroying' | 'destroyed';
-interface Kernel {
+/**
+ * The viewer: the engine, the plugins and the open documents. Its own settings
+ * (`getSettings()`, `updateSettings()`, …) are what every document gets unless it says
+ * otherwise, and what every plugin's colors fall back to (`viewer-settings.ts`).
+ */
+interface Kernel extends SettingsApi<ViewerSettings> {
   readonly engine: Engine;
   readonly documents: DocumentsCapability;
-  /** Resolve a capability. For document-scoped tokens, `documentId` defaults to the active doc. */
+  /**
+   * Resolve a capability. For document-scoped tokens, `documentId` defaults to the active doc.
+   * For a workspace token, a `documentId` gives the capability as seen from that document's
+   * scope (`PluginDef.inScope`; the documents capability too): the same object on every call
+   * while the document is open.
+   */
   capability<T>(token: CapabilityToken<T>, documentId?: string): T;
   /**
    * Total sibling of `capability()`: `null` instead of throwing — no
    * provider, no document, or a document that isn't `ready` yet. This is the
    * method adapters subscribe to (`useKernelValue`-style): resolution is a
-   * VALUE derived from kernel state, not a pure function of its arguments —
+   * value derived from kernel state, not a pure function of its arguments —
    * a pending document's promotion changes the result while the id stays the
    * same, so caching a `capability()` call by id goes stale. The returned
    * instance is reference-stable per (plugin, document), so equality-cached
@@ -280,6 +74,13 @@ interface Kernel {
   tryCapability<T>(token: CapabilityToken<T>, documentId?: string): T | null;
   /** A token's scope — adapters use this to decide whether to bind a document. */
   scopeOf(token: CapabilityToken<unknown>): PluginScope;
+  /**
+   * A plugin's settings calls, with or without a document open: settings belong to the plugin
+   * as the app registered it, not to a document. For adapters (a settings hook renders before
+   * the first document opens) and for an app that changes them before opening one. Throws
+   * when no installed plugin provides `token`, or its plugin declares no settings.
+   */
+  settingsOf<C>(token: CapabilityToken<C>): SettingsApi<SettingsOf<C>>;
   subscribe(listener: () => void): Unsubscribe;
   getState(): GlobalState;
   status(): KernelStatus;
@@ -296,7 +97,10 @@ interface Kernel {
  * Assemble a kernel from an engine + plugins.
  *
  *   planPlugins        — validate dependencies, order them
- *   resolveCapability  — workspace singletons, or per-document instances built lazily
+ *   resolveCapability  — workspace singletons (or their view from a document's scope),
+ *                        or per-document instances built lazily
+ *   settings           — one store per plugin registration, built up front, shared
+ *                        by its instances and readable with no document
  *   document lifecycle — one DocumentSession per document: transactional open
  *                        (publish-last), one idempotent close for every phase
  *   start / destroy    — explicit status machine; destroy closes everything
@@ -304,60 +108,161 @@ interface Kernel {
  * The kernel closes every handle it opened; it never destroys the engine —
  * ownership follows acquisition, and the engine was handed in by the caller.
  */
-declare function createKernel(opts: {
+declare function createKernel(config: {
   engine: Engine;
   plugins: AnyPlugin[];
-  /** Observability seam: teardown/effect/join failures land here. Default: console.error. */
+  /** The viewer's own settings, over `VIEWER_DEFAULTS`: what `resetSettings()` goes back to. */
+  settings?: DeepPartial<ViewerSettings>;
+  /** Observability seam: teardown, listener and join failures land here. Default: console.error. */
   report?: (error: unknown) => void;
+  /**
+   * The host's time: what plugins' `ctx.clock` schedules on. A browser passes
+   * `browserClock()` from `@embedpdf/web`, for frames. Default: `timerClock`,
+   * timers and no frames.
+   */
+  clock?: HostClock;
 }): Kernel;
 //#endregion
-//#region src/event-hook.d.ts
+//#region src/compose.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.
+ * `composeApi`: the composition root's one primitive. A controller builds
+ * its capability from area slices (each `satisfies Partial<Capability>`)
+ * plus the service-owned members (authority twins, event hooks); this spreads
+ * them into one object and refuses a key that two slices both define, so a
+ * new verb can never silently shadow an old one.
+ *
+ *   const api: FormHostCapability = composeApi('form', [
+ *     fields.api,
+ *     values.api,
+ *     { canFill: () => authority.can('doc.forms.fill'), onValueChanged: events.valueChanged.on },
+ *   ]);
  */
-type EventHook<T> = (listener: (event: T) => void) => Unsubscribe;
+type UnionToIntersection<U> = (U extends unknown ? (value: U) => void : never) extends ((value: infer I) => void) ? I : never;
+declare function composeApi<const T extends readonly object[]>(capability: string, slices: T): UnionToIntersection<T[number]>;
+//#endregion
+//#region src/guarded-handle.d.ts
+/** What the guard needs to know about the instance it protects. */
+interface GuardedLifetime {
+  /** Aborted when the instance closes (a document session) or the kernel is destroyed. */
+  readonly signal: AbortSignal;
+  readonly instanceId: string;
+}
 /**
- * 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.
+ * The guarded document handle a controller sees as `ctx.doc`. Every call made
+ * through it is:
+ *
+ *   - refused (rejected `instance-closed`) once the instance has closed,
+ *   - raced against the instance lifetime: a call that is still pending when
+ *     the instance closes rejects `instance-closed`, its late value is dropped,
+ *     and an abortable engine call is aborted so worker-side work stops,
+ *   - mapped through `toPluginError`, so a controller sees one error vocabulary.
+ *
+ * Nested service objects (`doc.annotations`, `doc.page(ref).render`) are
+ * wrapped lazily and cached; synchronous reads (`doc.security.allows`) pass
+ * straight through. Methods run with the raw target as `this`, so classes
+ * with private fields keep working. The returned promises keep an `abort()`
+ * when the engine's promise had one, so caller-side cancellation still works.
  */
-interface EventHookSource<T> {
-  readonly on: EventHook<T>;
-  emit(event: T): void;
-  dispose(): void;
+declare function guardHandle(handle: DocumentHandle$1, lifetime: GuardedLifetime, capability: string): DocumentHandle$1;
+//#endregion
+//#region src/memo.d.ts
+/**
+ * Identity-stable reads. A capability read returns the same object until its
+ * inputs change, so adapter selectors compare with `Object.is` and re-render
+ * only when something really changed. These two helpers are how a plugin
+ * builds such reads: name the inputs, and the result is recomputed only when
+ * one of them is a different value.
+ */
+/** The inputs as `compute` receives them; inferred from `inputs()` only, never from `compute`. */
+type Computed<Inputs extends readonly unknown[]> = { -readonly [K in keyof Inputs]: NoInfer<Inputs[K]>; };
+/**
+ * Recompute `compute(...inputs())` only when an input changes (compared with
+ * `Object.is`, element by element); otherwise return the previous result.
+ */
+declare function memo<const Inputs extends readonly unknown[], Result>(inputs: () => Inputs, compute: (...inputs: Computed<Inputs>) => Result): () => Result;
+/**
+ * `memo` per key: each key keeps its own last inputs and result. Keys are
+ * compared with `Map` semantics, so use primitives (a page object number, an
+ * encoded key), not freshly built objects. `maxEntries` bounds the cache;
+ * the oldest key is evicted first.
+ */
+declare function memoByKey<Key, const Inputs extends readonly unknown[], Result>(inputs: (key: Key) => Inputs, compute: (key: Key, ...inputs: Computed<Inputs>) => Result, options?: {
+  maxEntries?: number;
+}): (key: Key) => Result;
+//#endregion
+//#region src/state.d.ts
+interface StateDeclaration<Capability, State extends object> {
+  /** The capability the state is read from; a document plugin's resolves per document. */
+  readonly token: CapabilityToken<Capability>;
+  /**
+   * Read every field through the capability's getters. A getter returns the
+   * same value while nothing changed, so adapters compare the result field by
+   * field ({@link shallowEqual}) and wake readers only when a field changed.
+   */
+  readonly read: (capability: Capability) => State;
+  /**
+   * The state while the capability can't resolve: no document is open, it
+   * isn't ready yet, or none is in scope. It has exactly `read`'s fields, so
+   * an adapter can list the fields without a capability. Frozen, because every
+   * reader shares it.
+   */
+  readonly empty: State;
+  /**
+   * Start loading what `read` shows, for state the plugin loads on demand. The adapters call it
+   * whenever a hook or service starts reading a document's capability, so it must do nothing
+   * once loaded or loading (an `ensureLoaded()` verb); a failure shows in the state (its
+   * `status`), so they ignore the promise's rejection. Absent for state that is always loaded.
+   */
+  readonly ensure?: (capability: Capability) => Promise<void>;
 }
 /**
- * Create one capability event.
- *
- * 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 a plugin's state. The fields come from `read`, and `empty` is checked
+ * against them (`NoInfer` keeps it out of the inference): a missing field or a
+ * value of the wrong type is a type error. Write `empty` inline, because
+ * TypeScript refuses an extra field only in an object literal.
  */
-declare function createEventHook<T = void>(onListenerError?: (error: unknown) => void): EventHookSource<T>;
+declare function defineState<Capability, State extends object>(token: CapabilityToken<Capability>, declaration: {
+  readonly read: (capability: Capability) => State;
+  readonly empty: NoInfer<State>;
+  readonly ensure?: (capability: NoInfer<Capability>) => Promise<void>;
+}): StateDeclaration<Capability, State>;
+/**
+ * One level of identity: equal when the two values are the same, or are
+ * objects (or arrays) holding the same values under the same keys. Declared
+ * state compares this way, and so does a value a selector picks from it.
+ */
+declare function shallowEqual(left: unknown, right: unknown): boolean;
 //#endregion
-//#region src/serial-queue.d.ts
+//#region src/documents-state.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.
+ * The document in scope (the capability resolved for a document, or else the active one): its
+ * id, name, status, page count, unsaved changes, and why it's locked or failed.
  */
-declare function createSerialQueue(): <T>(operation: () => Promise<T>) => Promise<T>;
+declare const documentState: StateDeclaration<DocumentsCapability, DocumentInfo>;
+/** Every open document, in tab order, and the active one's id. */
+interface DocumentsState {
+  /** Every open document, loading, locked and failed ones included. */
+  readonly documents: readonly DocumentInfo[];
+  /** The active document's id, or null with none open. */
+  readonly activeId: string | null;
+}
+declare const documentsState: StateDeclaration<DocumentsCapability, DocumentsState>;
+//#endregion
+//#region src/capability-handle.d.ts
+/** Whether a capability member named `name` is a read: `get*`, `list*`, `is*`, `has*` or `can*`. */
+declare function isReadMember(name: string): boolean;
+/** Whether the member at `path` (`'setValue'`, `'comments.reply'`) returns a promise, as `token` declares. */
+declare function returnsPromise(token: CapabilityToken<unknown>, path: string): boolean;
+/**
+ * What a framework adapter's API reaches for a document plugin while its part of the app has no
+ * ready document. One per kernel and token, so it is the same object on every read.
+ */
+declare function standInFor<T>(kernel: Kernel, token: CapabilityToken<T>): T;
 //#endregion
 //#region src/scope.d.ts
 /**
  * A lifecycle operation was cancelled — the tab was closed mid-open, or the
- * kernel was destroyed mid-start. NOT a failure: callers that race `open()`
+ * kernel was destroyed mid-start. Not a failure: callers that race `open()`
  * against `close()` should treat this rejection as "the close won".
  */
 declare class CancelledError extends Error {
@@ -370,12 +275,27 @@ declare const isCancelled: (error: unknown) => error is CancelledError;
  * Create a typed capability token. `name` is the token's identity (debugging,
  * error messages); `options.hint` is the authored remedy the kernel appends to
  * the missing-dependency error, so the error contains its own fix.
+ * `options.promises` lists the members that return a promise, so a framework
+ * adapter's stand-in rejects them, rather than throwing, while no document is
+ * open; a document plugin whose capability has such members gives it.
  */
 declare function createCapabilityToken<T>(name: string, options?: {
   hint?: string;
+  promises?: PromiseMembers<T>;
 }): CapabilityToken<T>;
-/** Identity helper that pins a plugin's generics. The real win is inference. */
-declare function definePlugin<S = unknown, A extends Action = Action, C = unknown>(def: PluginDef<S, A, C>): PluginDef<S, A, C>;
+/**
+ * The host lens over a plugin's token: the same runtime object, typed with
+ * the wider capability sibling plugins use. The one place that cast lives.
+ */
+declare function createHostToken<Host>(token: CapabilityToken<unknown>): CapabilityToken<Host>;
+/**
+ * Define a plugin. It returns the definition as it is, and reads the types from it, so a
+ * plugin passes no type arguments: the capability from `token`, the state from `state`, the
+ * settings from `settings.defaults`. `create` receives a `PluginContext<State, Settings>`
+ * and must return the capability. A plugin without `state` is stateless (`void`); one
+ * without `settings` has `NoSettings`, and `ctx.settings()` throws there.
+ */
+declare function definePlugin<State = void, Capability = unknown, Settings extends object = NoSettings>(definition: PluginDef<State, Capability, Settings>): PluginDef<State, Capability, Settings>;
 //#endregion
-export { AbortablePromise, Action, AnyPlugin, CONTINUOUS_RENDER_POLICY, CORE_ACTIVE_CHANGED, CORE_DOCUMENT_ADDED, CORE_DOCUMENT_LOCKED, CORE_DOCUMENT_OPENING, CORE_DOCUMENT_OPEN_FAILED, CORE_DOCUMENT_PAGES_UPDATED, CORE_DOCUMENT_REMOVED, CORE_ORDER_CHANGED, CancelledError, CapabilityToken, CoreState, type DocCapability, DocInfo, DocStatus, type DocumentEvent, type DocumentHandle, DocumentMeta, type DocumentMetadata, DocumentsCapability, DocumentsToken, EffectContext, type Engine, type EngineFactory, type EngineRenderPolicy, EventHook, EventHookSource, GlobalState, InitialDocument, Kernel, KernelStatus, type MetadataPatch, type MetadataUpdateResult, OpenDocumentOptions, type OpenInput, type OpenOptions, OpenSource, type PageDeleteResult, type PageHandle, type PageImageHandle, type PageImageObjectUrl, type PageImageOptions, type PageInsertBlankSpec, type PageInsertResult, type PageLayout, type PageMoveResult, type PageObjectNumber, type PageRaster, type PageRenderOptions, type PageRenderTarget, type PageRenderViewport, type PageRotateResult, type PageRotation, type PdfDestination, type PdfRect, type PdfSaveMode, type PdfSize, PendingMeta, PermissionDenied, PluginContext, PluginDef, PluginScope, Unsubscribe, createCapabilityToken, createEventHook, createKernel, createSerialQueue, definePlugin, docInfoEquals, docInfoListEquals, isCancelled, snapAppearanceScale, snapFullPageViewport, snapTileScale };
+export { AbortablePromise, type AnnotationAppearanceImage, type AnnotationRef, AnyPlugin, BatchResult, CONTINUOUS_RENDER_POLICY, type CallFacts, type CallPriority, type Cancel, CancelledError, CapabilityToken, type ChangeLabel, type ChangeQueue, CoreState, type CustomMetadata, type CustomMetadataPatch, type CustomMetadataUpdateResult, type DeepPartial, type DocCapability, DocumentActiveChangedEvent, DocumentClosedEvent, type DocumentEvent, type DocumentHandle, DocumentInfo, DocumentLockedEvent, DocumentMeta, type DocumentMetadata, DocumentOpenFailedEvent, DocumentOpenedEvent, DocumentPagesChangedEvent, DocumentStatus, DocumentUnsavedChangesChangedEvent, DocumentsCapability, type DocumentsState, DocumentsToken, DownloadOptions, type Engine, type EngineFactory, type EngineRenderPolicy, EventHook, EventHookSource, type EventOrigin, FailedDocumentInfo, GlobalState, type HeldChange, type HoldOptions, type HostClock, type Identity, InitialDocument, Kernel, KernelStatus, type LatestCancellation, type LatestLane, type LatestRun, LockedDocumentInfo, type MetadataPatch, type MetadataUpdateResult, type Mirror, type MirrorChange, type MirrorReload, type MirrorSpec, type NoSettings, OpenDocumentOptions, OpenDocumentResult, type OpenInput, type OpenOptions, OpenSource, OperationOptions, type PageDeleteResult, type PageDestination, type PageHandle, type PageImageHandle, type PageImageObjectUrl, type PageImageOptions, PageInfo, type PageInsertBlankSpec, type PageInsertResult, type PageLayerRights, type PageLayout, type PageMirror, type PageMirrorChange, type PageMirrorSpec, type PageObjectNumber, type PagePosition, type PageRaster, type PageRef, type PageRenderLayers, type PageRenderOptions, type PageRenderTarget, type PageRenderViewport, type PageReorderResult, type PageRotateResult, type PdfDestination, type PdfRect, type PdfRotation, type PdfSaveMode, type PdfSize, type PendingChange, PendingMeta, Permission, PermissionDenied, type PluginClock, PluginContext, PluginDef, PluginError, PluginErrorCode, PluginErrorInfo, PluginScope, type PredictedOp, PromiseMemberOf, PromiseMembers, ResourceStatus, SerialQueue, type Settings, type SettingsApi, type SettingsChangedEvent, type SettingsDeclaration, type SettingsOf, type SettledChange, type SliceChange, type SliceLease, type StagedChange, StateCell, StateChange, type StateDeclaration, Subscribable, UnlockOptions, Unsubscribe, UrlSource, VIEWER_DEFAULTS, VIEWER_WHOLE_SETTINGS, type ViewerPageSettings, type ViewerSettings, type ViewerSettingsInput, type WorkingSetPage, annotationKey, composeApi, createCapabilityToken, createEventHook, createHostToken, createKernel, createLatestLane, createSerialQueue, decodePageKey, definePlugin, defineState, documentState, documentsState, encodePageKey, guardHandle, isCancelled, isLocalEngine, isPluginError, isReadMember, memo, memoByKey, mergeSettings, pageRefsEqual, reload, resolvePageLayers, returnsPromise, shallowEqual, snapAppearanceScale, snapFullPageViewport, snapTileScale, standInFor, timerClock, toPageRef, toPluginError, toPluginErrorInfo, viewerSettingsOf };
 //# sourceMappingURL=index.d.ts.map