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

package/dist/runtime/index.d.ts

@@ -1,266 +1,646 @@
 import * as _embedpdf_core from '@embedpdf/core';
-import { Engine, EngineFactory, AnyPlugin, InitialDocument, Kernel, DocInfo, CapabilityToken } from '@embedpdf/core';
+import { Engine, InitialDocument, Identity, ViewerPageSettings, Kernel, AnyPlugin, ViewerSettings, EventHook, CapabilityToken, DeepPartial, SettingsOf, SettingsChangedEvent, StateDeclaration, PageInfo, LockedDocumentInfo, FailedDocumentInfo, DocumentInfo, PageRef } from '@embedpdf/core';
 export * from '@embedpdf/core';
+import { PaintedParts, PagePart, SvgShape, EpdfTheme } from '@embedpdf/web';
+export { EpdfTheme, mountWebFont, saveFile } from '@embedpdf/web';
 import * as i0 from '@angular/core';
-import { OnDestroy, Signal, EnvironmentProviders, InjectionToken, TemplateRef, OnInit } from '@angular/core';
+import { Type, Provider, InjectionToken, Signal, TemplateRef } from '@angular/core';
+import { Observable } from 'rxjs';
 import { PageFrame, PageTransform, Point, Rect } from '@embedpdf/core-geometry';
+import { PageViewDemand } from '@embedpdf/plugin-render/contract';
 
-/** One boot document — the KERNEL's shared `InitialDocument` shape (same as
- *  the React adapter's), aliased under the package's Epdf naming. */
-type EpdfInitialDocument = InitialDocument;
+/** A setup mistake, with its code: `EPDF-101`. */
+declare class EpdfError extends Error {
+    readonly code: `EPDF-${number}`;
+    readonly name = "EpdfError";
+    constructor(code: `EPDF-${number}`, problem: string);
+}
+/** EPDF-101: a service, component or directive of the viewer, with no viewer above it. */
+declare const noViewerError: (what: string) => EpdfError;
+/** EPDF-102: a plugin's service, where no viewer above it has that plugin. */
+declare const noPluginError: (service: string, feature: string) => EpdfError;
+/** EPDF-103: something that draws on a page, outside a page. */
+declare const outsidePageError: (what: string) => EpdfError;
+/** EPDF-104: part of a Stage, outside one. */
+declare const outsideStageError: (what: string) => EpdfError;
+/** EPDF-105: a call that needs the engine, made while rendering on the server. */
+declare const onServerError: (what: string) => EpdfError;
+
+/**
+ * What `provideEmbedPdf(config, ...features)` takes: the config (the engine, the documents to
+ * open, the viewer's settings, or a kernel someone else made) and one feature per plugin
+ * (`withStage()`, `withSearch()`). Both are read once, when the viewer starts.
+ */
+
+/**
+ * The engine: an instance, or a function that makes one.
+ *
+ * - An instance is borrowed: the viewer uses it and never destroys it, so one engine made at
+ *   module scope can serve every viewer and route.
+ * - A function is the viewer's own: the viewer calls it in the browser when it starts, and
+ *   destroys the engine when the component or route that provides the viewer goes away. It may
+ *   return a promise, so `() => import('@embedpdf/engine').then((m) => m.localEngine())` keeps
+ *   the engine out of the page's first download.
+ */
+type EngineSource = Engine | (() => Engine | Promise<Engine>);
 interface EmbedPdfConfig {
+    readonly engine: EngineSource;
     /**
-     * The engine, as an instance or a thunk. Engines construct synchronously and
-     * boot lazily (`localEngine()` allocates nothing until first use), so
-     * ownership follows the SHAPE of what you pass:
-     *
-     *   - An **instance** is BORROWED: used as-is, never destroyed here. The
-     *     common path — a module-scope `const engine = localEngine()` shared
-     *     across viewers and route changes. The host calls `engine.warmup?.()`
-     *     when the kernel materializes so the boot overlaps initialization.
-     *   - A **thunk** (`() => localEngine()`) is HOST-OWNED: the host calls it
-     *     when the kernel materializes and `destroy()`s the result on teardown.
-     *     Use it for per-host isolation.
-     *
-     * Init-only: the kernel is never rebuilt for a new engine — tear the host
-     * down (destroy the viewer / injector) and create a new one.
+     * Documents to open when the viewer starts. Every tab appears at once; the one marked
+     * `active`, else the first, becomes the active document. One that fails shows `error` in its
+     * tab and doesn't stop the others.
+     */
+    readonly initialDocuments?: readonly InitialDocument[];
+    /**
+     * Who the user is, for every document opened without an `identity` of its own. The local
+     * engine only: the cloud engine reads it from the document's token. Change it later with
+     * `inject(EpdfViewer).updateSettings({ identity })`.
+     */
+    readonly identity?: Identity;
+    /**
+     * What the user may do, as permissions, in every document opened without a `scope` of its
+     * own. Left out, they may do everything.
+     */
+    readonly scope?: readonly string[];
+    /** The color every part without a color of its own follows. CSS `--epdf-accent` wins over it. */
+    readonly accent?: string;
+    /** How pages look: `background` before the picture arrives, and the `shadow` under each page. */
+    readonly page?: Partial<ViewerPageSettings>;
+}
+/**
+ * A kernel someone else created and owns, for `provideEmbedPdf({ kernel })`: every service,
+ * component and directive under that injector works against it, and the injector neither starts
+ * nor destroys it. The full viewer's Angular wrapper gives the templates you put in it one of
+ * these, with the viewer's kernel. Its plugins are the kernel's: a feature's `plugins` are not
+ * registered again, while its services, providers and `setup` work as with a kernel of its own.
+ */
+interface EmbedPdfKernelConfig {
+    readonly kernel: Kernel;
+}
+/**
+ * One feature of `provideEmbedPdf()`: the plugins it registers, and the Angular side of them.
+ * A plugin's entry point exports its feature as `withX(options)`.
+ */
+interface EmbedPdfFeature {
+    readonly plugins: readonly AnyPlugin[];
+    /**
+     * The plugin's services (`EpdfSearch`). They are provided next to the viewer, and again
+     * under every `[epdfDocumentScope]`, where they act on that document.
      */
-    engine: Engine | EngineFactory;
-    /** Init-only, like `engine`. */
-    plugins: AnyPlugin[];
-    /** Documents to open on startup (with optional tab names). They open in the
-     *  BACKGROUND after start and stream into the registry — `injectDocuments()`
-     *  is reactive; per-document loading UI is the Stage's job. A source that
-     *  fails to open lands in `error` and does NOT block the ones after it. */
-    initialDocuments?: EpdfInitialDocument[];
+    readonly services?: readonly Type<unknown>[];
+    /** Anything else the feature puts next to the viewer. */
+    readonly providers?: readonly Provider[];
+    /**
+     * Runs once in the browser, right after the viewer is created, in the injection context of
+     * the providers: it may `inject()` services and create effects, which live as long as the
+     * viewer.
+     */
+    readonly setup?: () => void;
+}
+/** What the viewer is doing: starting, running, or failed to start (see `EpdfViewer.error()`). */
+type EpdfViewerStatus = 'starting' | 'ready' | 'error';
+
+/**
+ * The DI tokens the runtime's pieces share, in a file of their own so the pieces that provide
+ * them and the ones that read them never import each other.
+ */
+
+/**
+ * The document a part of the template talks to: `[epdfDocumentScope]`, or a Stage that opened
+ * its own `[document]`. A null id follows the active document.
+ */
+interface EpdfDocumentScopeRef {
+    readonly id: Signal<string | null>;
+}
+declare const EPDF_DOCUMENT_SCOPE: InjectionToken<EpdfDocumentScopeRef>;
+/** What `provideEmbedPdf()` was given, for the viewer it creates. */
+interface EmbedPdfSetup {
+    readonly config: EmbedPdfConfig | EmbedPdfKernelConfig;
+    readonly features: readonly EmbedPdfFeature[];
+}
+declare const EPDF_SETUP: InjectionToken<EmbedPdfSetup>;
+
+/** A plugin's settings, readable and changeable before the kernel exists and after. */
+interface PluginSettingsBinding<T> {
+    readonly current: Signal<T>;
+    update(change: DeepPartial<T>): void;
+    reset(): void;
 }
-/** `starting` covers construction through `kernel.start()`; `ready` means the
- *  workspace is live (documents may still be opening in the background). */
-type EpdfKernelStatus = 'starting' | 'ready' | 'error';
-declare class EpdfKernelHost implements OnDestroy {
-    private readonly browser;
-    private config;
-    private _kernel;
-    /** The engine backing the kernel, and whether WE created it (a recipe) and
-     *  therefore must destroy it. A borrowed instance is left untouched. */
-    private _engine;
+declare class EpdfKernelHost {
+    private readonly setup;
+    private readonly injector;
+    /** Whether this is a browser. On the server the host creates no kernel. */
+    readonly browser: boolean;
+    /** The kernel `provideEmbedPdf({ kernel })` was given: someone else's, used as it is. */
+    private readonly given;
+    /** Every plugin the features register, in their order: none for a kernel given, which has its own. */
+    readonly plugins: readonly AnyPlugin[];
+    private readonly kernelState;
+    private readonly revisionState;
+    private readonly statusState;
+    private readonly errorState;
+    private readonly listeners;
+    private readonly viewerSettingsBeforeStart;
+    private readonly pluginSettings;
+    private readonly pluginSettingsBeforeStart;
+    private engine;
     private ownsEngine;
-    private unsubscribe;
-    private initialDocuments;
-    private booted;
+    private stopListening;
     private destroyed;
-    /** Bumped on every kernel notification — THE bridge from kernel-world to signals. */
-    private readonly tick;
-    /** Boot lifecycle. `ready`/`error` are derived sugar over it. */
-    readonly status: i0.WritableSignal<EpdfKernelStatus>;
-    /** The STARTUP failure, if any. Per-document open failures are tab state
-     *  (`DocInfo.status === 'error'`), not host state. */
-    readonly error: i0.WritableSignal<unknown>;
-    /** True once `kernel.start()` resolved — which never touches the engine, so
-     *  the shell (and every workspace capability: i18n, view-manager, …) is alive
-     *  while WASM compiles or the transport connects. Workspace chrome may render
-     *  before this; gate on it (or on the document gate) where it matters. */
-    readonly ready: Signal<boolean>;
-    /** Register the (deferred) config. Called exactly once, by `EpdfViewer`'s
-     *  constructor or `provideEmbedPdf`'s factory. */
-    connect(config: () => EmbedPdfConfig): void;
-    /** The kernel — materialized on first read (see the construction rule above). */
-    get kernel(): Kernel;
-    /** Start the kernel and open initial documents in the background. Idempotent;
-     *  a no-op on the server and after destroy. */
-    boot(): void;
-    /** Read a value derived from the kernel, cached by equality — Angular's
-     *  `useKernelValue`. The selector re-runs per kernel notification (cheap);
-     *  `equal` decides whether dependents ever see it. */
-    value<R>(select: (kernel: Kernel) => R, equal?: (a: R, b: R) => boolean): Signal<R>;
-    ngOnDestroy(): void;
+    /**
+     * The kernel, once it exists: null while a lazily loaded engine is on its way, and on the
+     * server, where only a kernel given is there.
+     */
+    readonly kernel: Signal<Kernel | null>;
+    /** Goes up on every change of the kernel's state. */
+    readonly revision: Signal<number>;
+    /** A kernel given says it itself: someone else starts it. */
+    readonly status: Signal<EpdfViewerStatus>;
+    /** Why the viewer failed to start, when `status()` is `'error'`. */
+    readonly error: Signal<unknown>;
+    /** The viewer's own settings, before the kernel exists and after. */
+    readonly viewerSettings: Signal<ViewerSettings>;
+    constructor();
+    /**
+     * A value read from the kernel, as a signal: `select` runs again after each change of the
+     * kernel's state, and the signal changes only when `equal` says the value did. `empty` is its
+     * value while there is no kernel.
+     */
+    read<R>(select: (kernel: Kernel) => R, empty: () => R, equal?: (left: R, right: R) => boolean): Signal<R>;
+    /** Call `listener` after each change of the kernel's state, and once when the kernel arrives. */
+    subscribe(listener: () => void): () => void;
+    /**
+     * An event of the kernel itself (its settings, a plugin's settings store), as an RxJS
+     * stream. A subscription made before the kernel exists starts listening when it arrives.
+     */
+    stream<T>(pick: (kernel: Kernel) => EventHook<T>): Observable<T>;
+    /** Whether a plugin of this viewer provides `token` (the documents are always there). */
+    provides(token: CapabilityToken<unknown>): boolean;
+    /** Whether the plugin of this viewer that provides `token` has settings. */
+    hasSettings(token: CapabilityToken<unknown>): boolean;
+    /**
+     * The kernel, for `call` (`'zoomIn()'`) on `capability` (`'stage'`), which needs it now:
+     * `not-ready` while the engine is still on its way, EPDF-105 on the server.
+     */
+    requireKernel(capability: string, call: string): Kernel;
+    updateViewerSettings(change: DeepPartial<ViewerSettings>): void;
+    resetViewerSettings(): void;
+    /**
+     * A plugin's settings, with or without a document, and before the kernel too: they belong to
+     * the plugin as the app registered it. One binding per plugin, shared by every service.
+     */
+    settingsOf<T extends object>(token: CapabilityToken<unknown>): PluginSettingsBinding<T>;
+    /** A registered plugin's settings, kept from before the kernel exists. */
+    private registeredSettingsOf;
+    /** A plugin's settings in a kernel given, which is there from the start. */
+    private givenSettingsOf;
+    private pluginFor;
+    /** Follow a kernel someone else made: its changes, and nothing of its lifetime. */
+    private adopt;
+    private start;
+    /** Create and start the kernel over `engine`. An engine this viewer made is destroyed with it. */
+    private attach;
+    private changed;
+    private fail;
+    private runFeatureSetups;
+    private destroy;
     static ɵfac: i0.ɵɵFactoryDeclaration<EpdfKernelHost, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<EpdfKernelHost>;
 }
+
 /**
- * Host the kernel in an environment injector (route or application providers).
- * The kernel's lifetime is the injector's — a route-level workspace tears down
- * when the route does. Unlocks chrome OUTSIDE any viewer subtree: a toolbar in
- * the app header and the stage in the main outlet share this one kernel.
+ * How the adapter reaches a plugin: its capability token, resolved for one document (the one in
+ * scope, else the active one) after every change of the kernel. A `CapabilityBinding` turns that
+ * into what Angular code wants: signals for values, late-bound methods for calls, and RxJS
+ * streams for events. Services, the Stage and the page layers are all built on it.
+ *
+ * Resolution is a read, not a cache: a document becomes resolvable when it's ready, while its
+ * id stays the same, so a capability looked up once by id would go stale.
  */
-declare function provideEmbedPdf(config: EmbedPdfConfig): EnvironmentProviders;
 
+/** The viewer above this injection context; EPDF-101, naming `what`, when there is none. */
+declare function injectKernelHost(what: string): EpdfKernelHost;
 /**
- * DI tokens shared by the runtime's primitives and directives — split out so
- * `inject.ts` (consumers) and `scope.ts` (providers) never import each other.
+ * The document this injection context talks to: the id the nearest `[epdfDocumentScope]` (or a
+ * Stage with a `[document]`) gives, or null to follow the active document.
  */
-
-/** The document a subtree is bound to (provided by `[epdfDocumentScope]`).
- *  Absent => the subtree follows the ACTIVE document. */
-interface EpdfDocumentScopeRef {
-    readonly id: Signal<string>;
+declare function injectDocumentScope(): Signal<string | null>;
+/**
+ * A plugin's capability for this injection context's document, as a signal: null while it
+ * can't resolve (no such plugin, no document, or one that isn't ready yet). For plugin authors;
+ * apps use a plugin's service (`inject(EpdfSearch)`). Call it in an injection context.
+ */
+declare function injectCapability<Capability>(token: CapabilityToken<Capability>): Signal<Capability | null>;
+/** One capability token, for one document, as signals, calls and streams. */
+declare class CapabilityBinding<Capability> {
+    readonly host: EpdfKernelHost;
+    private readonly token;
+    private readonly documentId;
+    /** The capability, or null while it can't resolve. */
+    readonly capability: Signal<Capability | null>;
+    /**
+     * @param token the token to resolve; a function, because a component's token is an input
+     * @param documentId the document to resolve it for, or null for the active one
+     */
+    constructor(host: EpdfKernelHost, token: () => CapabilityToken<Capability>, documentId: () => string | null);
+    /**
+     * A value read through the capability, as a signal that changes only when `equal` says the
+     * value did. `empty` while the capability can't resolve, and for the one read that can land
+     * between a document closing and its capability going away.
+     */
+    select<R>(read: (capability: Capability) => R, empty: R, equal?: (left: R, right: R) => boolean): Signal<R>;
+    /**
+     * The capability, for `call`, which needs it now. Without a document a document plugin
+     * refuses with `not-ready` ("no document is open"), the same refusal every framework's
+     * stand-in gives (`standInFor` in `@embedpdf/core`); a token no plugin provides throws the
+     * kernel's reason, because that is a setup mistake.
+     */
+    require(call: string): Capability;
+    /**
+     * The capability's method `name`, looked up when it's called, so a method kept in a field
+     * acts on the document current at that moment. The same function for the binding's lifetime.
+     *
+     * A read (a method named `get*`, `list*`, `is*`, `has*` or `can*`: `canUpdate()`,
+     * `getZoomLevel()`) is state too: called in a template, a `computed()` or an `effect()`, it's
+     * read again after each change of the kernel and of the document in scope, and wakes its
+     * reader only when its answer changes. So a button it disables follows the selection, the
+     * active document and its permissions. Other methods track nothing: an `effect()` that calls a
+     * verb doesn't run again because the verb changed the document.
+     *
+     * Without a document a method refuses with `not-ready`: one that returns a promise (the token's
+     * `promises`) returns the refusal as a rejected promise, so `.catch()` sees it; others throw.
+     */
+    method<Name extends keyof Capability>(name: Name): Capability[Name];
+    /**
+     * The method `name` of the capability's namespace `namespace` (`custom.update()`), late-bound
+     * the way {@link method} is. A service gives a namespace an object of its own
+     * (`metadata.custom`), built from these, {@link select} and {@link stream}.
+     */
+    namespaceMethod<Key extends keyof Capability, Name extends keyof Capability[Key]>(namespace: Key, name: Name): Capability[Key][Name];
+    /**
+     * One of the capability's events, as an RxJS stream. A subscription follows the document:
+     * when it changes (another tab, a document that opens or closes), it moves to the new
+     * document's capability. Nothing is emitted while there is none.
+     */
+    stream<T>(pick: (capability: Capability) => EventHook<T>): Observable<T>;
+    private resolve;
+    /** `owner(capability)[name]`, looked up when called; a read tracks what its answer reads. */
+    private late;
 }
-declare const EPDF_DOCUMENT_SCOPE: InjectionToken<EpdfDocumentScopeRef>;
 
 /**
- * The inject* primitives — Angular's spelling of the React runtime hooks
- * (`use*` → `inject*`, plain values → signals, same names otherwise).
+ * One service per plugin: `inject(EpdfSearch)` has the plugin's methods, every value of its
+ * State table as a signal (`search.hitCount()`), its events as RxJS streams
+ * (`search.completed$`), and, when the plugin has settings, `settings()`, `getSettings()`,
+ * `updateSettings()`, `resetSettings()` and `settingsChanged$`. `pluginService()` builds all of that from what the
+ * plugin declares already, so a plugin's service is a few lines; the package README's "Adding a
+ * plugin binding" shows one.
  *
- * All of them must run in an injection context (a constructor / field
- * initializer, like `inject()` itself). None of them read `host.kernel` during
- * construction — they return signals or lazy methods, so they are safe in
- * component-hosted mode where the kernel materializes after construction.
+ * A service acts on the document of the injector that created it: under `[epdfDocumentScope]`
+ * that document, else the active one. Its methods are looked up when they're called, so a
+ * method kept in a field acts on the document current at that moment.
  */
 
-declare const shallowArray: <T>(a: readonly T[], b: readonly T[]) => boolean;
-declare function injectKernelHost(): EpdfKernelHost;
-/** The raw kernel — materializes it immediately. Do NOT call while a component
- *  is being constructed in component-hosted mode (inputs are not set yet);
- *  prefer the signal-returning primitives, which defer the first kernel read. */
-declare function injectKernel(): Kernel;
-/** Read a value derived from the kernel, cached by equality — `useKernelValue`. */
-declare function injectKernelValue<R>(select: (kernel: Kernel) => R, equal?: (a: R, b: R) => boolean): Signal<R>;
-declare function injectActiveDocumentId(): Signal<string | null>;
-/** The document id for this injector subtree: the nearest `[epdfDocumentScope]`,
- *  else the active document. */
-declare function injectDocumentId(): Signal<string | null>;
+/** The names of a capability's events: its `on…` members. */
+type EventName<Capability> = {
+    [Key in keyof Capability]-?: Key extends `on${string}` ? Capability[Key] extends EventHook<infer _Payload> ? Key : never : never;
+}[keyof Capability];
+/** An event's stream on a service: `onCompleted` is `completed$`. */
+type StreamName<Event> = Event extends `on${infer Name}` ? `${Uncapitalize<Name>}$` : never;
+type EventOf<Hook> = Hook extends EventHook<infer Event> ? Event : never;
+/** The settings members, for a capability that has the settings calls. */
+type SettingsMembers<Capability> = [SettingsOf<Capability>] extends [never] ? unknown : {
+    /** The plugin's settings, with or without a document. */
+    readonly settings: Signal<SettingsOf<Capability>>;
+    /** Fires once for each call that changed a setting. */
+    readonly settingsChanged$: Observable<SettingsChangedEvent<SettingsOf<Capability>>>;
+} & Pick<Capability, ('getSettings' | 'updateSettings' | 'resetSettings') & keyof Capability>;
+/** What a plugin service built by `pluginService()` has, on top of the members its class adds. */
+type PluginServiceMembers<Capability, State extends object, Method extends keyof Capability, Event extends EventName<Capability>> = {
+    readonly [Key in Method]-?: Capability[Key];
+} & {
+    readonly [Key in keyof State]-?: Signal<State[Key]>;
+} & {
+    readonly [Key in Event as StreamName<Key>]: Observable<EventOf<Capability[Key]>>;
+} & SettingsMembers<Capability>;
 /**
- * Resolve a capability against a REACTIVE token — for components that take the
- * token as an input (`injectCapability` is the fixed-token sugar). Resolution
- * is a REACTIVE read (`tryCapability` through the kernel's one change
- * stream), not a computed over the document id — under the request-time
- * lifecycle a document can become resolvable while its id stays the same, so
- * any id-keyed cache goes stale; subscribing makes staleness structurally
- * impossible. Fail-fast like React's `useCapability`: while unresolvable,
- * this re-runs the strict resolver so the kernel's truthful reason (`no
- * capability` / `no document` / `document is loading|locked`) is what throws.
+ * The class `pluginService()` returns, which a plugin's service extends. It has a name so the
+ * built declarations say `PluginServiceClass<SearchCapability, …>` and the app's compiler works
+ * out each member from the plugin's own types, instead of spelling out every member's type,
+ * which would name packages the app may not have installed.
  */
-declare function injectCapabilityFor<T>(token: () => CapabilityToken<T>): Signal<T>;
-declare function injectCapability<T>(token: CapabilityToken<T>): Signal<T>;
-/** Like `injectCapabilityFor`, but null while the token can't resolve (no
- *  plugin, no document, or a document that isn't ready yet). */
-declare function injectOptionalCapabilityFor<T>(token: () => CapabilityToken<T>): Signal<T | null>;
-declare function injectOptionalCapability<T>(token: CapabilityToken<T>): Signal<T | null>;
-/** Subscribe to a selector over a (document-resolved) capability. */
-declare function injectSelectorFor<C, R>(token: () => CapabilityToken<C>, select: (cap: C) => R, equal?: (a: R, b: R) => boolean): Signal<R>;
-declare function injectSelector<C, R>(token: CapabilityToken<C>, select: (cap: C) => R, equal?: (a: R, b: R) => boolean): Signal<R>;
+type PluginServiceClass<Capability, State extends object, Method extends keyof Capability, Event extends EventName<Capability>> = abstract new () => EpdfPluginService<Capability> & PluginServiceMembers<Capability, State, Method, Event>;
+interface PluginServiceSpec<Capability, State extends object, Method extends keyof Capability, Event extends EventName<Capability>> {
+    /** The service's class name, as errors show it: `'EpdfSearch'`. */
+    readonly name: string;
+    /**
+     * The feature that registers the plugin, as errors show it: `'withSearch()'`. Left out for
+     * the viewer's own services, which `provideEmbedPdf()` always has.
+     */
+    readonly feature?: string;
+    readonly token: CapabilityToken<Capability>;
+    /** The plugin's State table (`defineState`): each field becomes a signal of the same name. */
+    readonly state?: StateDeclaration<Capability, State>;
+    /**
+     * For a plugin that loads its state on demand: the verb that loads it (its declaration's
+     * `ensure`), called once a ready document's capability is in scope, for every document the
+     * service comes to read. Taken from `state` when the spec has one.
+     */
+    readonly ensure?: (capability: Capability) => Promise<void>;
+    /** The plugin's Methods table: each becomes a method of the same name. */
+    readonly methods: readonly Method[];
+    /** The plugin's events: `onCompleted` becomes the stream `completed$`. */
+    readonly events?: readonly Event[];
+}
+/**
+ * The base every plugin service extends. Its members are for the service's own class, which
+ * adds what the generic part can't: a signal with arguments (`hitsOn(page)`), a namespace
+ * (`custom.fields()`), a helper that needs the caller's injection context.
+ */
+declare abstract class EpdfPluginService<Capability> {
+    /** The plugin's capability for this service's document. */
+    protected readonly binding: CapabilityBinding<Capability>;
+    protected constructor(spec: {
+        name: string;
+        feature?: string;
+        token: CapabilityToken<Capability>;
+    });
+}
+/**
+ * The base class of a plugin's service, built from the plugin's declarations:
+ *
+ *   @Injectable({ providedIn: 'root' })
+ *   export class EpdfSearch extends pluginService({
+ *     name: 'EpdfSearch',
+ *     feature: 'withSearch()',
+ *     token: SearchToken,
+ *     state: searchState,
+ *     methods: ['search', 'clear', 'goToHit'],
+ *     events: ['onCompleted'],
+ *   }) {}
+ *
+ * `providedIn: 'root'` is only the fallback that turns a missing viewer into EPDF-102: the
+ * service's feature provides it next to the viewer, and `[epdfDocumentScope]` again.
+ */
+declare function pluginService<Capability, State extends object = Record<never, never>, Method extends keyof Capability = never, Event extends EventName<Capability> = never>(spec: PluginServiceSpec<Capability, State, Method, Event>): PluginServiceClass<Capability, State, Method, Event>;
+
 /**
- * Null-safe `injectSelector`: `fallback` whenever the token can't resolve — no
- * provider, or a document-scoped token with no document. For chrome that stays
- * mounted across the empty-workspace state (a zoom readout, a mode band).
- * `injectSelector` stays strict (fail-fast) for code that KNOWS a document
- * exists — e.g. anything behind the document gate.
+ * The viewer itself: its settings, and whether it started. The config given to
+ * `provideEmbedPdf()` is read once; what may change while the app runs changes here:
+ *
+ *   effect(() => viewer.updateSettings({ identity: auth.identity() }));
  *
- * The `select` guard also swallows reads through a capability whose document
- * closed between the store notification and this read — that teardown race
- * resolves to `fallback` for one frame, then recomputes against the new state.
+ * Documents opened after a change of `identity` or `scope` use the new value; open ones keep
+ * theirs.
+ */
+declare class EpdfViewer {
+    private readonly host;
+    /** The viewer's settings: `identity`, `scope`, `accent` and `page`. */
+    readonly settings: Signal<ViewerSettings>;
+    /** `'starting'`, `'ready'`, or `'error'` when the engine or a plugin failed to start. */
+    readonly status: Signal<EpdfViewerStatus>;
+    /** Why the viewer failed to start, when `status()` is `'error'`. */
+    readonly error: Signal<unknown>;
+    /** Fires once for each call that changed a setting. */
+    readonly settingsChanged$: Observable<SettingsChangedEvent<ViewerSettings>>;
+    /** Merge `changes` into the viewer's settings: `page` merges, `identity` and `scope` replace. */
+    updateSettings(changes: DeepPartial<ViewerSettings>): void;
+    /** Go back to the settings `provideEmbedPdf()` was given. */
+    resetSettings(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<EpdfViewer, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<EpdfViewer>;
+}
+declare const EpdfDocuments_base: PluginServiceClass<_embedpdf_core.DocumentsCapability, _embedpdf_core.DocumentsState, "print" | "open" | "preparePrint" | "download" | "downloadLayer" | "close" | "move" | "canOpenFiles" | "openAll" | "retry" | "rename" | "unlock" | "closeAll" | "setActive" | "getActiveId" | "getActive" | "list" | "get" | "has" | "getCount" | "getOrder" | "setOrder" | "swap" | "getPrintQuality" | "canDownload" | "canPrint" | "listPages" | "getPage" | "getPageIndex" | "getRevision", "onOpened" | "onOpenFailed" | "onLocked" | "onClosed" | "onActiveChanged" | "onPagesChanged" | "onUnsavedChangesChanged">;
+/**
+ * The documents: open, close, unlock, retry and download them, and every tab with the active
+ * one as signals (`documents()`, `activeId()`). Under `[epdfDocumentScope]` the calls that
+ * leave out the document use that one: `download()` downloads the document in scope.
+ */
+declare class EpdfDocuments extends EpdfDocuments_base {
+    static ɵfac: i0.ɵɵFactoryDeclaration<EpdfDocuments, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<EpdfDocuments>;
+}
+declare const EpdfDocument_base: PluginServiceClass<_embedpdf_core.DocumentsCapability, _embedpdf_core.DocumentInfo, never, never>;
+/**
+ * The document this part of the template talks to: the one `[epdfDocumentScope]` names, else
+ * the active one. Its fields are signals (`id()`, `name()`, `status()`, `pageCount()`,
+ * `hasUnsavedChanges()`, `passwordProvided()`, `error()`), and `pages()` its pages. With no
+ * document it reads as one still on its way: an empty `id` and `status() === 'loading'`.
  */
-declare function injectOptionalSelectorFor<C, R>(token: () => CapabilityToken<C>, select: (cap: C) => R, fallback: R, equal?: (a: R, b: R) => boolean): Signal<R>;
-declare function injectOptionalSelector<C, R>(token: CapabilityToken<C>, select: (cap: C) => R, fallback: R, equal?: (a: R, b: R) => boolean): Signal<R>;
-/** The document registry (open/close/active/list), reactive — `useDocuments`.
- *  Methods late-bind the kernel, so this is construction-safe. */
-interface EpdfDocuments {
-    docs: Signal<DocInfo[]>;
-    activeId: Signal<string | null>;
-    open: Kernel['documents']['open'];
-    unlock: Kernel['documents']['unlock'];
-    close: Kernel['documents']['close'];
-    setActive: Kernel['documents']['setActive'];
-    move: Kernel['documents']['move'];
-    swap: Kernel['documents']['swap'];
-    download: Kernel['documents']['download'];
-    downloadLayer: Kernel['documents']['downloadLayer'];
+declare class EpdfDocument extends EpdfDocument_base {
+    /**
+     * The document's pages, in order: each with its `ref`, `index`, `label`, size and rotation.
+     * Needs no Stage. The same array until a page is added, removed, moved or rotated; empty
+     * with no document.
+     */
+    readonly pages: Signal<readonly PageInfo[]>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<EpdfDocument, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<EpdfDocument>;
 }
-declare function injectDocuments(): EpdfDocuments;
 
+/**
+ * `provideEmbedPdf(config, ...features)`: the viewer as Angular providers, in Angular's own
+ * style (`provideRouter(routes, withViewTransitions())`).
+ *
+ *   providers: [provideEmbedPdf({ engine }, withStage(), withRender(), withSearch())]
+ *
+ * It works in a component's `providers` (that component and everything in its template share
+ * one viewer, and the component can inject its services itself), in a route's `providers`, and
+ * in the app config. Each injector that provides it gets its own viewer, created in the browser
+ * and destroyed with the injector. `provideEmbedPdf({ kernel })` gives the injector a kernel
+ * someone else made instead, which it neither starts nor destroys.
+ */
+
+/**
+ * Every service that acts on one document: the viewer's own, and each feature's, added when a
+ * `provideEmbedPdf()` call names the feature. `[epdfDocumentScope]` and a Stage list this array
+ * in their `providers`, so a service injected under them acts on their document.
+ *
+ * It is one array that grows, not a copy: Angular reads a directive's providers when its
+ * template is first created, which is after the `provideEmbedPdf()` calls in decorators and the
+ * app config ran. A service whose feature is first named later (a lazily loaded route's
+ * providers) is still provided by its viewer, and acts on the active document there.
+ */
+declare const EPDF_SCOPED_SERVICES: Provider[];
+/** The viewer, with the plugins its features register; or the viewer of a kernel given. */
+declare function provideEmbedPdf(config: EmbedPdfConfig | EmbedPdfKernelConfig, ...features: EmbedPdfFeature[]): Provider[];
+
+/**
+ * Binds everything inside the element to one document: services injected there, the Stage
+ * and its layers act on it instead of the active document.
+ */
 declare class EpdfDocumentScope implements EpdfDocumentScopeRef {
+    /** The document's id. */
     readonly id: i0.InputSignal<string>;
     static ɵfac: i0.ɵɵFactoryDeclaration<EpdfDocumentScope, never>;
     static ɵdir: i0.ɵɵDirectiveDeclaration<EpdfDocumentScope, "[epdfDocumentScope]", never, { "id": { "alias": "epdfDocumentScope"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
 }
+/** What the gate's content gets: `let document` is the ready document. */
+interface EpdfDocumentGateContext {
+    $implicit: DocumentInfo;
+}
+/** What the `locked` template gets: `let-document` is the document waiting for its password. */
+interface EpdfLockedDocumentContext {
+    $implicit: LockedDocumentInfo;
+}
+/** What the `error` template gets: `let-document` is the document that failed, with `error`. */
+interface EpdfFailedDocumentContext {
+    $implicit: FailedDocumentInfo;
+}
 /**
- * Render the host template only while this subtree has a document — the
- * structural way to say "this UI is defined over a document". Sibling of
- * `[epdfDocumentScope]`, which picks WHICH document; this one handles WHETHER.
+ * Renders its content only while this part of the template has a ready document, with that
+ * document as `let document`. Otherwise it renders `locked` for a document waiting for its
+ * password, `error` for one that couldn't be opened, and `fallback` for everything else (none
+ * open yet, still opening), each with the document as `let-document`. Without `locked` or
+ * `error` those states show `fallback` too.
  *
- *   <section *epdfDocumentGate="; fallback: empty">…document UI…</section>
- *   <ng-template #empty>Drop a PDF to get started</ng-template>
+ *   <epdf-stage *epdfDocumentGate="let document; fallback: opening; locked: locked; error: failed">
+ *   <ng-template #opening>Opening…</ng-template>
+ *   <ng-template #locked let-document><app-password-form [document]="document" /></ng-template>
  *
- * The subtree stays mounted across a CHANGE of document (active-tab switch) —
- * only the has-a-document boolean creates/destroys it.
+ * The content stays mounted when another ready document becomes the active one; only its
+ * `document` changes.
  */
 declare class EpdfDocumentGate {
-    /** Shown while this subtree has NO document (empty workspace, docs still opening). */
-    readonly fallback: i0.InputSignal<TemplateRef<unknown> | null>;
+    /** Shown while there is no ready document: none is open, or it's still opening. */
+    readonly fallback: i0.InputSignal<TemplateRef<unknown> | null | undefined>;
+    /** Shown while the document waits for its password; `fallback` without it. */
+    readonly locked: i0.InputSignal<TemplateRef<EpdfLockedDocumentContext> | null | undefined>;
+    /** Shown when the document couldn't be opened; `fallback` without it. */
+    readonly error: i0.InputSignal<TemplateRef<EpdfFailedDocumentContext> | null | undefined>;
+    static ngTemplateContextGuard(_gate: EpdfDocumentGate, context: unknown): context is EpdfDocumentGateContext;
     constructor();
+    private templateFor;
     static ɵfac: i0.ɵɵFactoryDeclaration<EpdfDocumentGate, never>;
-    static ɵdir: i0.ɵɵDirectiveDeclaration<EpdfDocumentGate, "[epdfDocumentGate]", never, { "fallback": { "alias": "epdfDocumentGateFallback"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
-}
-
-declare class EpdfViewer implements OnInit {
-    /** The engine, as an instance OR a thunk ({@link EngineFactory}). An
-     *  instance is borrowed (never destroyed here); a thunk is host-owned
-     *  (constructed then destroyed with the viewer). See EmbedPdfConfig.
-     *  Init-only: the kernel is built once from the first values; recreate the
-     *  viewer (e.g. with @if) to swap it. */
-    readonly engine: i0.InputSignal<Engine | EngineFactory>;
-    readonly plugins: i0.InputSignal<AnyPlugin[]>;
-    readonly initialDocuments: i0.InputSignal<_embedpdf_core.InitialDocument[] | undefined>;
-    /** The host this viewer provides — exposed so a template reference can read
-     *  `viewer.host.ready()` / `.status()` without extra imports. */
-    readonly host: EpdfKernelHost;
-    constructor();
-    ngOnInit(): void;
-    static ɵfac: i0.ɵɵFactoryDeclaration<EpdfViewer, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<EpdfViewer, "epdf-viewer", never, { "engine": { "alias": "engine"; "required": true; "isSignal": true; }; "plugins": { "alias": "plugins"; "required": true; "isSignal": true; }; "initialDocuments": { "alias": "initialDocuments"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<EpdfDocumentGate, "[epdfDocumentGate]", never, { "fallback": { "alias": "epdfDocumentGateFallback"; "required": false; "isSignal": true; }; "locked": { "alias": "epdfDocumentGateLocked"; "required": false; "isSignal": true; }; "error": { "alias": "epdfDocumentGateError"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
 /**
- * PageContext — the seam. A layer depends ONLY on this, never on the Stage, so
- * the same layer works inside a virtualized `<epdf-stage>` page and a future
- * standalone `<epdf-page-view>`.
+ * The page context: what a layer drawn on a page knows about that page. A layer reads only
+ * this, never the Stage, so the same layer works on a Stage's page and on a standalone page
+ * view. Inside `<ng-template epdfPage>`, `let-page` gives it to the template and `injectPage()`
+ * to a component.
  *
- * THE STABILITY INVARIANT (the one performance rule of this adapter): a page's
- * context is ONE STABLE OBJECT per mounted surface — identity never changes;
- * the volatile parts (`transform`, `frame`, `pageIndex`) are signals INSIDE it.
- * The per-page injector providing `EPDF_PAGE` is likewise created once. Camera
- * frames then flow as signal writes — `NgTemplateOutlet` never recreates the
- * embedded views, in-flight renders survive, and updates stay per-binding.
- * Never rebuild the context or the injector per frame.
+ * One context per page on screen, for as long as the page is shown: its identity never
+ * changes, and what moves (`pageIndex`, `frame`, `transform`) are signals inside it. The
+ * template outlet then keeps every layer while the camera moves, and a camera frame updates
+ * only the bindings that read the transform. Never build a new context per frame.
  *
- * Coordinate math lives in `@embedpdf/core-geometry`'s `PageTransform` — verified
- * once, not re-derived per framework adapter (`toContentPoint` mirrors React's
- * `makePageContext` exactly).
+ * The coordinate math is `PageTransform` from `@embedpdf/core-geometry`, and the client-space
+ * conversions are `pageClientSpace` from `@embedpdf/web`, both shared by every framework.
  */
 
 interface EpdfPageContext {
     readonly documentId: string;
-    /** Durable page identity (PDF object number) — use for keys / render / annotations. */
-    readonly pon: number;
-    /** Display index (page N) — can shift under page reorders, hence a signal. */
+    /**
+     * The page's address, the same for as long as the page is shown: use it for keys and calls.
+     * An `<epdf-page-view>` whose `[page]` changes shows another page in the same context; its
+     * `ref` and `documentId` are read through signals there, so a `computed()` or an `effect()`
+     * that reads them follows.
+     */
+    readonly ref: PageRef;
+    /** The page's place in the document, from 0. It moves when pages are reordered. */
     readonly pageIndex: Signal<number>;
-    /** Reserved chrome bands around the page (screen px per side). */
+    /** The bands reserved around the page for labels and buttons, in screen pixels per side. */
     readonly frame: Signal<PageFrame>;
-    /** The single bridge between PDF points, view px, and device px for this
-     *  page. Layers do ALL coordinate work through it — never re-derive
-     *  `x * scale` or `* dpr`. Updates per camera frame. */
+    /**
+     * Between PDF points, view pixels and device pixels on this page: `pageToViewRect` places
+     * something on the page, `renderScale` and `deviceWidth` size a picture of it. Changes with
+     * every camera frame.
+     */
     readonly transform: Signal<PageTransform>;
-    /** Client (screen) point → the viewer's coordinates (content point) — the
-     *  one platform-bound hit-test. */
-    toContentPoint(clientX: number, clientY: number): Point;
-    /** Content point → client (screen) px — the exact inverse of `toContentPoint`. */
-    toClientPoint(p: Point): Point;
-    /** Content rect → client (screen) px AABB. */
+    /**
+     * Which view shows the page (a Stage's lens id). Per-view work, such as which tiles to draw,
+     * is kept per view, so a thumbnail strip never disturbs the main view.
+     */
+    readonly view: string;
+    /** A point on the screen (client pixels) to a point on the page: the one hit test. */
+    toPagePoint(clientX: number, clientY: number): Point;
+    /** A point on the page to client pixels: the exact inverse of `toPagePoint`. */
+    toClientPoint(point: Point): Point;
+    /** A box on the page to the client-pixel box around it. */
     toClientRect(rect: Rect): Rect;
+    /**
+     * How much of the page the view wants drawn, read when asked: a Stage gives the part on
+     * screen (an empty rect when the page left the screen); a standalone page view gives none,
+     * which means the whole page.
+     */
+    readonly getViewDemand?: () => PageViewDemand;
 }
 declare const EPDF_PAGE: InjectionToken<EpdfPageContext>;
-declare function injectPage(): EpdfPageContext;
-/** Build a page context from its reactive parts. `documentId`/`pon` are thunks
- *  because inputs aren't readable at construction — both are stable per surface. */
+/** The page this component is drawn on; EPDF-103, naming `what`, outside a page. */
+declare function injectPage(what?: string): EpdfPageContext;
+/**
+ * A page context from its parts. `documentId` and `ref` are functions because a component's
+ * inputs aren't set yet when it's constructed; both stay the same for the page's lifetime.
+ */
 declare function createPageContext(parts: {
     documentId: () => string;
-    pon: () => number;
+    ref: () => PageRef;
+    view: () => string;
     pageIndex: Signal<number>;
     frame: Signal<PageFrame>;
     transform: Signal<PageTransform>;
-    /** The rotated content wrapper's LIVE bounding box (the page's display box). */
+    /** The page's box on screen: the turned content box's bounding box. */
     getRect: () => DOMRect;
+    getViewDemand?: () => PageViewDemand;
 }): EpdfPageContext;
 
-export { EPDF_DOCUMENT_SCOPE, EPDF_PAGE, EpdfDocumentGate, EpdfDocumentScope, EpdfKernelHost, EpdfViewer, createPageContext, injectActiveDocumentId, injectCapability, injectCapabilityFor, injectDocumentId, injectDocuments, injectKernel, injectKernelHost, injectKernelValue, injectOptionalCapability, injectOptionalCapabilityFor, injectOptionalSelector, injectOptionalSelectorFor, injectPage, injectSelector, injectSelectorFor, provideEmbedPdf, shallowArray };
-export type { EmbedPdfConfig, EpdfDocumentScopeRef, EpdfDocuments, EpdfInitialDocument, EpdfKernelStatus, EpdfPageContext };
+/**
+ * The Angular side of `@embedpdf/web`'s page layers: a layer says, for as long as it's there,
+ * which part of its page it paints, and the render layer reads which parts are painted, to leave
+ * them out of the page's picture.
+ */
+
+/**
+ * Say, for as long as this component is there, that it paints `part` of its page (`pageRef()`,
+ * the page context's `ref`; `null` while it paints nothing). Call it in an injection context.
+ */
+declare function paintsPagePart(pageRef: () => object | null, part: PagePart): void;
+/**
+ * Which parts of the page (`pageRef()`, the page context's `ref`) the layers on it paint: `null`
+ * until the first render is done, when every layer made with this one has said what it paints,
+ * so the page's picture is never asked for with a part another layer is about to take. Call it
+ * in an injection context.
+ */
+declare function injectPaintedParts(pageRef: () => object): Signal<PaintedParts | null>;
+
+/**
+ * An SVG element's attributes from a record of SVG names (`stroke-width`), as `@embedpdf/web`
+ * describes a scene node (templates can't spread). Set again when the record changes; an
+ * attribute that left the record is removed.
+ */
+declare class EpdfSvgAttributes {
+    readonly attributes: i0.InputSignal<Readonly<Record<string, string | number>>>;
+    constructor();
+    static ɵfac: i0.ɵɵFactoryDeclaration<EpdfSvgAttributes, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<EpdfSvgAttributes, "[epdfSvgAttributes]", never, { "attributes": { "alias": "epdfSvgAttributes"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+/** The shapes, in drawing order, in the `<svg:g>` it's on, and the faces their text draws in. */
+declare class EpdfSvgShapes {
+    readonly shapes: i0.InputSignal<readonly SvgShape[]>;
+    constructor();
+    static ɵfac: i0.ɵɵFactoryDeclaration<EpdfSvgShapes, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<EpdfSvgShapes, "g[epdfSvgShapes]", never, { "shapes": { "alias": "epdfSvgShapes"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/** Warn once per key. Quiet in production. */
+declare function devWarn(key: string, message: string): void;
+/** For tests: forget every warning, so one can fire again. */
+declare function resetDevWarnings(): void;
+
+/**
+ * `epdfTheme()`: a theme written with setting names, as the CSS variables for the element
+ * around your viewer. The variables and their lookup are framework-free (`@embedpdf/web`); this
+ * types the result for Angular's `[style]` binding, which sets custom properties as they are.
+ */
+
+/**
+ * The CSS variables of a theme: `<div [style]="theme()">` with
+ * `theme = computed(() => epdfTheme({ accent: this.accent() }))`. Everything inside follows
+ * them, and a CSS variable set in a stylesheet still wins over a setting.
+ */
+declare function epdfTheme(theme: EpdfTheme): Record<string, string>;
+
+export { CapabilityBinding, EPDF_DOCUMENT_SCOPE, EPDF_PAGE, EPDF_SCOPED_SERVICES, EPDF_SETUP, EpdfDocument, EpdfDocumentGate, EpdfDocumentScope, EpdfDocuments, EpdfError, EpdfKernelHost, EpdfPluginService, EpdfSvgAttributes, EpdfSvgShapes, EpdfViewer, createPageContext, devWarn, epdfTheme, injectCapability, injectDocumentScope, injectKernelHost, injectPage, injectPaintedParts, noPluginError, noViewerError, onServerError, outsidePageError, outsideStageError, paintsPagePart, pluginService, provideEmbedPdf, resetDevWarnings };
+export type { EmbedPdfConfig, EmbedPdfFeature, EmbedPdfKernelConfig, EmbedPdfSetup, EngineSource, EpdfDocumentGateContext, EpdfDocumentScopeRef, EpdfFailedDocumentContext, EpdfLockedDocumentContext, EpdfPageContext, EpdfViewerStatus, EventName, PluginServiceClass, PluginServiceMembers, PluginServiceSpec, PluginSettingsBinding, StreamName };