@embedpdf/svelte 0.0.0-stage → 3.0.0-next.15

package/dist/runtime/Viewer.svelte

@@ -0,0 +1,124 @@
+<!--
+  The viewer: owns the kernel for as long as it is mounted, and gives it to everything inside.
+
+  The kernel is made in the browser only, when the viewer mounts (an effect, so server rendering
+  makes nothing). Its fallback shows from then on, with the kernel already in context, so a
+  loading screen can use workspace plugins. The content mounts once `start()` resolves, which
+  never touches the engine: the shell is alive while WASM compiles or the transport connects.
+  `initialDocuments` then open in the background; per-document loading is `<DocumentGate>`'s job.
+
+  Engine ownership follows the shape of `engine`: a function is the viewer's own (made on mount,
+  destroyed after the kernel on unmount), an instance is borrowed (warmed up, never destroyed).
+-->
+<script lang="ts">
+  import { untrack } from 'svelte';
+  import { createKernel, isLocalEngine, viewerSettingsOf } from '@embedpdf/core';
+  import type { Engine, EngineFactory, Kernel, ViewerSettings } from '@embedpdf/core';
+  import { browserClock } from '@embedpdf/web';
+  import { KernelBinding, setKernelHolder } from './binding.svelte.js';
+  import { isDev } from './dev.js';
+  import type { ViewerProps } from './props.js';
+
+  let {
+    engine,
+    plugins,
+    initialDocuments,
+    onReady,
+    identity,
+    scope,
+    accent,
+    page,
+    fallback,
+    error: renderError,
+    children,
+  }: ViewerProps = $props();
+
+  type Boot =
+    | { phase: 'booting'; binding: KernelBinding | null }
+    | { phase: 'ready'; binding: KernelBinding }
+    | { phase: 'error'; error: unknown };
+
+  let boot = $state.raw<Boot>({ phase: 'booting', binding: null });
+  setKernelHolder({
+    get binding() {
+      return boot.phase === 'error' ? null : boot.binding;
+    },
+  });
+
+  // The viewer's settings as the props give them: a prop left out is its default.
+  const settings = $derived<ViewerSettings>(viewerSettingsOf({ identity, scope, accent, page }));
+
+  // One kernel per mount. Everything is read untracked, so nothing a prop does later runs this
+  // again: `engine`, `plugins` and `initialDocuments` are read once.
+  $effect(() =>
+    untrack(() => {
+      const ownsEngine = typeof engine === 'function';
+      const created: Engine = ownsEngine ? (engine as EngineFactory)() : (engine as Engine);
+      if (isLocalEngine(created)) created.warmup();
+      let kernel: Kernel;
+      try {
+        kernel = createKernel({ engine: created, plugins, settings, clock: browserClock() });
+      } catch (error) {
+        // A plugin graph that can't be built shows `error`, not an exception mid-render.
+        boot = { phase: 'error', error };
+        if (ownsEngine) void created.destroy();
+        return;
+      }
+      const binding = new KernelBinding(kernel);
+      const documents = initialDocuments ?? [];
+      let alive = true;
+      boot = { phase: 'booting', binding };
+      kernel.start().then(
+        () => {
+          if (!alive) return; // unmounted while starting: open nothing
+          onReady?.(kernel);
+          boot = { phase: 'ready', binding };
+          // Every tab appears at once in order; the `active` entry (else the first) is selected,
+          // and a failure shows as that tab's status.
+          kernel.documents.openAll(documents);
+        },
+        (error: unknown) => {
+          if (alive) boot = { phase: 'error', error };
+        },
+      );
+      return () => {
+        alive = false;
+        binding.dispose();
+        // The kernel first (it closes every document handle), then the engine we own.
+        void kernel.destroy().then(() => {
+          if (ownsEngine) void created.destroy();
+        });
+      };
+    }),
+  );
+
+  // Later settings reach the kernel as they change; settings that didn't change change nothing.
+  $effect(() => {
+    const next = settings;
+    if (boot.phase !== 'error') boot.binding?.kernel.updateSettings(next);
+  });
+
+  // `engine` and `plugins` are read once: say so when they change after the viewer mounted.
+  const mounted = untrack(() => ({ engine, plugins }));
+  let warned = false;
+  $effect(() => {
+    if (warned || !isDev()) return;
+    if (engine !== mounted.engine || plugins !== mounted.plugins) {
+      warned = true;
+      console.warn(
+        '[embedpdf] <Viewer> reads engine and plugins once, when it mounts; a new value is ignored. ' +
+          'To use other ones, mount a new <Viewer>, for example inside a {#key} block.',
+      );
+    }
+  });
+</script>
+
+{#if boot.phase === 'error'}
+  {@render renderError?.(boot.error)}
+{:else if boot.binding}
+  {#if boot.phase === 'ready'}
+    {@render children?.()}
+  {:else}
+    {@render fallback?.()}
+  {/if}
+{/if}

package/dist/runtime/Viewer.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { ViewerProps } from './props.js';
+declare const Viewer: import("svelte").Component<ViewerProps, {}, "">;
+type Viewer = ReturnType<typeof Viewer>;
+export default Viewer;

package/dist/runtime/binding.svelte.d.ts

@@ -0,0 +1,33 @@
+import type { Kernel } from '@embedpdf/core';
+export declare class KernelBinding {
+    #private;
+    readonly kernel: Kernel;
+    constructor(kernel: Kernel);
+    /** Read inside a `$derived` or an effect to run it again after every kernel change. */
+    track(): void;
+    /** Stop following the kernel; the viewer calls it when it unmounts. */
+    dispose(): void;
+}
+/** What `<Viewer>` and `<KernelProvider>` provide: the binding, once the kernel exists. */
+export interface KernelHolder {
+    readonly binding: KernelBinding | null;
+}
+/** For `<Viewer>` and `<KernelProvider>`: provide the kernel to everything inside it. */
+export declare function setKernelHolder(holder: KernelHolder): void;
+/**
+ * The binding of the nearest `<Viewer>` or `<KernelProvider>`. Everything inside one is created
+ * after its kernel, so the binding is there whenever a component inside asks.
+ */
+export declare function useKernelBinding(): KernelBinding;
+/**
+ * The kernel of the nearest `<Viewer>` or `<KernelProvider>`: for code that needs it whole
+ * (`onReady` gives it too).
+ */
+export declare function useKernel(): Kernel;
+/** For `<DocumentScope>`: bind a subtree to the document `id()` names. */
+export declare function setDocumentScope(id: () => string): void;
+/**
+ * The document the nearest `<DocumentScope>` names, as a function readers call each time (so a
+ * changed `id` reaches them), or one that answers null: follow the active document.
+ */
+export declare function documentScopeOf(): () => string | null;

package/dist/runtime/binding.svelte.js

@@ -0,0 +1,71 @@
+/**
+ * The kernel as Svelte sees it, and the two contexts every reader starts from.
+ *
+ * The kernel has one change stream (`kernel.subscribe`). {@link KernelBinding} turns it into one
+ * signal: a version that moves on every change. A reader reads that version inside a `$derived`,
+ * so it computes again after any change and passes a value on only when it differs. The binding
+ * subscribes for the kernel's whole life, so a reader works the same inside a template, an effect
+ * or an event handler.
+ *
+ * `<Viewer>` puts the binding in context (`<KernelProvider>` too, for a kernel it doesn't own);
+ * `<DocumentScope>` puts the document a subtree talks to.
+ */
+import { getContext, hasContext, setContext, untrack } from 'svelte';
+export class KernelBinding {
+    kernel;
+    #version = $state(0);
+    #unsubscribe;
+    constructor(kernel) {
+        this.kernel = kernel;
+        // `untrack`: a change can be announced while a reaction runs (a verb called from an effect),
+        // and the version is a counter nobody reads to decide what to write.
+        this.#unsubscribe = kernel.subscribe(() => untrack(() => this.#version++));
+    }
+    /** Read inside a `$derived` or an effect to run it again after every kernel change. */
+    track() {
+        void this.#version;
+    }
+    /** Stop following the kernel; the viewer calls it when it unmounts. */
+    dispose() {
+        this.#unsubscribe();
+    }
+}
+const KERNEL = Symbol('embedpdf.kernel');
+const DOCUMENT_SCOPE = Symbol('embedpdf.document-scope');
+/** For `<Viewer>` and `<KernelProvider>`: provide the kernel to everything inside it. */
+export function setKernelHolder(holder) {
+    setContext(KERNEL, holder);
+}
+/**
+ * The binding of the nearest `<Viewer>` or `<KernelProvider>`. Everything inside one is created
+ * after its kernel, so the binding is there whenever a component inside asks.
+ */
+export function useKernelBinding() {
+    // Untracked: the binding never changes for a component's lifetime, so nothing re-runs on it.
+    const binding = hasContext(KERNEL)
+        ? untrack(() => getContext(KERNEL).binding)
+        : null;
+    if (!binding) {
+        throw new Error('[embedpdf] This must be used inside <Viewer> or <KernelProvider>.');
+    }
+    return binding;
+}
+/**
+ * The kernel of the nearest `<Viewer>` or `<KernelProvider>`: for code that needs it whole
+ * (`onReady` gives it too).
+ */
+export function useKernel() {
+    return useKernelBinding().kernel;
+}
+/** For `<DocumentScope>`: bind a subtree to the document `id()` names. */
+export function setDocumentScope(id) {
+    setContext(DOCUMENT_SCOPE, id);
+}
+const ACTIVE = () => null;
+/**
+ * The document the nearest `<DocumentScope>` names, as a function readers call each time (so a
+ * changed `id` reaches them), or one that answers null: follow the active document.
+ */
+export function documentScopeOf() {
+    return hasContext(DOCUMENT_SCOPE) ? getContext(DOCUMENT_SCOPE) : ACTIVE;
+}

package/dist/runtime/capability-handle.d.ts

@@ -0,0 +1,6 @@
+/**
+ * A handle over `resolve()`. Members are cached by name, so `stage.zoomIn` is the same function
+ * every time, and a namespace (`annotation.comments`) is itself a handle. A member that is a
+ * plain value is read as it is now.
+ */
+export declare function capabilityHandle<T>(resolve: () => unknown, track: () => void): T;

package/dist/runtime/capability-handle.js

@@ -0,0 +1,71 @@
+/**
+ * What `useStage()`, `useDocuments()` and every other `use<Plugin>()` return: a handle that is
+ * always the capability of the document in scope.
+ *
+ * A component calls `use<Plugin>()` once, when it is created, but the document it talks to can
+ * change (another tab becomes active, a `<DocumentScope id>` changes) and can be missing (none is
+ * open yet). So the handle resolves the capability again on every call. Without a ready document
+ * it reaches the plugin's stand-in (`standInFor` from `@embedpdf/core`), whose calls refuse with
+ * `not-ready`: a method that returns a promise rejects, the others throw.
+ *
+ * Reads follow the capability vocabulary (docs/conventions/naming.md): a member named `get*`,
+ * `list*`, `is*`, `has*` or `can*` reads state, so calling it in a template or a `$derived`
+ * subscribes to the kernel: `{#if annotation.canCreate()}` updates when the answer changes. Every
+ * other member is a verb or an event and subscribes to nothing: an effect that calls
+ * `stage.reveal(index)` runs again only when `index` changes.
+ */
+import { untrack } from 'svelte';
+import { isReadMember } from '@embedpdf/core';
+/**
+ * A handle over `resolve()`. Members are cached by name, so `stage.zoomIn` is the same function
+ * every time, and a namespace (`annotation.comments`) is itself a handle. A member that is a
+ * plain value is read as it is now.
+ */
+export function capabilityHandle(resolve, track) {
+    return memberHandle(resolve, track, null);
+}
+function memberHandle(resolve, track, call) {
+    const members = new Map();
+    // A function target, so a member can be called and can have members of its own.
+    const target = call ? function member() { } : {};
+    return new Proxy(target, {
+        apply: (_target, _this, args) => call(args),
+        has(_target, key) {
+            const value = untrack(resolve);
+            return (typeof value === 'object' || typeof value === 'function') && value !== null
+                ? key in value
+                : false;
+        },
+        get(_target, key) {
+            // Not a thenable, and inspecting it never resolves anything.
+            if (typeof key === 'symbol' || key === 'then')
+                return undefined;
+            const value = untrack(() => resolve()?.[key]);
+            if (typeof value !== 'function' && (typeof value !== 'object' || value === null)) {
+                return value;
+            }
+            let member = members.get(key);
+            if (!member) {
+                const resolveMember = () => resolve()[key];
+                member = memberHandle(resolveMember, track, (args) => invoke(resolve, key, args, track));
+                members.set(key, member);
+            }
+            return member;
+        },
+    });
+}
+/**
+ * Call `key` on what `resolve()` gives now, with it as `this`. `Reflect.apply`, not `.apply`: a
+ * stand-in's member answers every property, `apply` too.
+ */
+function invoke(resolve, key, args, track) {
+    if (isReadMember(key)) {
+        track();
+        const owner = resolve();
+        return Reflect.apply(owner[key], owner, args);
+    }
+    return untrack(() => {
+        const owner = resolve();
+        return Reflect.apply(owner[key], owner, args);
+    });
+}

package/dist/runtime/dev.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Whether this is a development build: `DEV` from `esm-env`, as Svelte and SvelteKit read it.
+ * The app's bundler picks it by its `development` or `production` condition, so in a production
+ * build this is `false` and the warnings behind it compile out.
+ */
+export declare const isDev: () => boolean;
+/** Warn once per key. No-op in production. */
+export declare function devWarn(key: string, message: string): void;
+/** Forget every warning, so a test can assert one fires again. */
+export declare function resetDevWarnings(): void;

package/dist/runtime/dev.js

@@ -0,0 +1,23 @@
+/**
+ * Development-time guardrails. Every warning fires once per process (keyed), says what is wrong
+ * and what to do instead, and compiles out of production builds ({@link isDev}).
+ */
+import { DEV } from 'esm-env';
+const warned = new Set();
+/**
+ * Whether this is a development build: `DEV` from `esm-env`, as Svelte and SvelteKit read it.
+ * The app's bundler picks it by its `development` or `production` condition, so in a production
+ * build this is `false` and the warnings behind it compile out.
+ */
+export const isDev = () => DEV;
+/** Warn once per key. No-op in production. */
+export function devWarn(key, message) {
+    if (!isDev() || warned.has(key))
+        return;
+    warned.add(key);
+    console.warn(`[embedpdf] ${message}`);
+}
+/** Forget every warning, so a test can assert one fires again. */
+export function resetDevWarnings() {
+    warned.clear();
+}

package/dist/runtime/documents.svelte.d.ts

@@ -0,0 +1,34 @@
+import type { DocumentInfo, DocumentsCapability, DocumentsState, EventHook, PageInfo, ViewerSettings } from '@embedpdf/core';
+import { type CurrentValue } from './values.svelte.js';
+/**
+ * The documents API: open, close, unlock, download, and the tabs. Inside a `<DocumentScope>`, the
+ * calls that leave out the document use that one, so `download()` without an id downloads the
+ * document in scope. What to show comes from `useDocument()` and `useDocumentsState()`.
+ */
+export declare function useDocuments(): DocumentsCapability;
+/**
+ * The document this component talks to: the one its `<DocumentScope>` names, or else the active
+ * one. Its `id`, `name`, `status`, `pageCount`, `hasUnsavedChanges`, and why it's locked or
+ * failed. With no document, an empty one that reads as still opening.
+ */
+export declare function useDocument(): Readonly<DocumentInfo>;
+export declare function useDocument<Selected>(select: (document: DocumentInfo) => Selected): CurrentValue<Selected>;
+/** Every open document, in tab order (loading, locked and failed ones too), and the active one's id. */
+export declare function useDocumentsState(): Readonly<DocumentsState>;
+export declare function useDocumentsState<Selected>(select: (state: DocumentsState) => Selected): CurrentValue<Selected>;
+/** Subscribe to one documents event while the component lives: `useDocumentsEvent((documents) => documents.onOpened, handler)`. */
+export declare function useDocumentsEvent<T>(select: (documents: DocumentsCapability) => EventHook<T>, handler: (event: T) => void): void;
+/**
+ * The pages of the document this component talks to, 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.
+ */
+export declare function usePageList(): CurrentValue<readonly PageInfo[]>;
+/**
+ * The viewer's own settings (`<Viewer identity scope accent page>`), or the value `select` picks
+ * from them: the accent every part without a color of its own follows, and how pages look. What
+ * paints a page or an accent reads it here, through `paint()` from `@embedpdf/web`, so a CSS
+ * variable still wins.
+ */
+export declare function useViewerSettings(): Readonly<ViewerSettings>;
+export declare function useViewerSettings<Selected>(select: (settings: ViewerSettings) => Selected): CurrentValue<Selected>;

package/dist/runtime/documents.svelte.js

@@ -0,0 +1,49 @@
+/**
+ * The documents and the viewer's own settings, for components: the documents API, the document
+ * in scope, every open document, its pages, and the settings `<Viewer>` takes as props.
+ */
+import { DocumentsToken, documentState, documentsState, shallowEqual } from '@embedpdf/core';
+import { useKernelBinding } from './binding.svelte.js';
+import { useCapability, useCapabilityEvent, useDocumentId, useKernelValue } from './readers.svelte.js';
+import { declaredState, readRecord } from './state.svelte.js';
+import { derivedValue } from './values.svelte.js';
+/**
+ * The documents API: open, close, unlock, download, and the tabs. Inside a `<DocumentScope>`, the
+ * calls that leave out the document use that one, so `download()` without an id downloads the
+ * document in scope. What to show comes from `useDocument()` and `useDocumentsState()`.
+ */
+export function useDocuments() {
+    return useCapability(DocumentsToken);
+}
+export function useDocument(select) {
+    const binding = useKernelBinding();
+    const whole = declaredState(binding, DocumentsToken, documentState.read, documentState.empty);
+    return readRecord(whole, Object.keys(documentState.empty), select);
+}
+export function useDocumentsState(select) {
+    const binding = useKernelBinding();
+    const whole = declaredState(binding, DocumentsToken, documentsState.read, documentsState.empty);
+    return readRecord(whole, Object.keys(documentsState.empty), select);
+}
+/** Subscribe to one documents event while the component lives: `useDocumentsEvent((documents) => documents.onOpened, handler)`. */
+export function useDocumentsEvent(select, handler) {
+    useCapabilityEvent(DocumentsToken, select, handler);
+}
+const NO_PAGES = Object.freeze([]);
+/**
+ * The pages of the document this component talks to, 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.
+ */
+export function usePageList() {
+    const documentId = useDocumentId();
+    return useKernelValue((kernel) => documentId.current ? kernel.documents.listPages(documentId.current) : NO_PAGES);
+}
+export function useViewerSettings(select) {
+    const binding = useKernelBinding();
+    const whole = derivedValue(() => {
+        binding.track();
+        return binding.kernel.getSettings();
+    }, shallowEqual);
+    return readRecord(whole, ['identity', 'scope', 'accent', 'page'], select);
+}

package/dist/runtime/page-layers.svelte.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The Svelte side of `@embedpdf/web`'s page layers: a layer says, for as long as it lives, 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.
+ */
+import { type PagePart, type PaintedParts } from '@embedpdf/web';
+/**
+ * Say, for as long as this component lives, that it paints `part` of its page (`pageRef()`, the
+ * page context's `ref`; `null` while it paints nothing). Said as the component starts, so a render
+ * layer started alongside knows it by the time it's mounted.
+ */
+export declare function usePaintsPagePart(pageRef: () => object | null, part: PagePart): void;
+/**
+ * Which parts of the page (`pageRef()`, the page context's `ref`) the layers on it paint: `null`
+ * until this component is mounted, when every layer started with it has said what it paints, so
+ * the page's picture is never asked for with a part another layer is about to take.
+ */
+export declare function usePaintedParts(pageRef: () => object): {
+    readonly current: PaintedParts | null;
+};

package/dist/runtime/page-layers.svelte.js

@@ -0,0 +1,40 @@
+/**
+ * The Svelte side of `@embedpdf/web`'s page layers: a layer says, for as long as it lives, 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.
+ */
+import { pageLayersOf } from '@embedpdf/web';
+import { untrack } from 'svelte';
+/**
+ * Say, for as long as this component lives, that it paints `part` of its page (`pageRef()`, the
+ * page context's `ref`; `null` while it paints nothing). Said as the component starts, so a render
+ * layer started alongside knows it by the time it's mounted.
+ */
+export function usePaintsPagePart(pageRef, part) {
+    $effect.pre(() => {
+        const ref = pageRef();
+        if (!ref)
+            return;
+        return untrack(() => pageLayersOf(ref).paint(part));
+    });
+}
+/**
+ * Which parts of the page (`pageRef()`, the page context's `ref`) the layers on it paint: `null`
+ * until this component is mounted, when every layer started with it has said what it paints, so
+ * the page's picture is never asked for with a part another layer is about to take.
+ */
+export function usePaintedParts(pageRef) {
+    let painted = $state.raw(null);
+    $effect(() => {
+        const layers = pageLayersOf(pageRef());
+        return untrack(() => {
+            painted = layers.painted();
+            return layers.subscribe(() => (painted = layers.painted()));
+        });
+    });
+    return {
+        get current() {
+            return painted;
+        },
+    };
+}

package/dist/runtime/page.d.ts

@@ -0,0 +1,10 @@
+import type { PageTransform } from '@embedpdf/core-geometry';
+import type { PageViewDemand } from '@embedpdf/plugin-render/contract';
+import type { PageContext } from '@embedpdf/web';
+export { livePageContext, makePageContext } from '@embedpdf/web';
+/** The page context. Its members are documented on `PageContext` in `@embedpdf/web`. */
+export type PageContextValue = PageContext<PageTransform, PageViewDemand>;
+/** For page surfaces (`<Stage>`'s pages, `<PageView>`): provide the page to everything inside. */
+export declare function setPageContext(page: PageContextValue): void;
+/** The page this layer draws on. Throws outside a page surface. */
+export declare function usePage(): PageContextValue;

package/dist/runtime/page.js

@@ -0,0 +1,23 @@
+/**
+ * The page context: what a layer knows about the page it draws on. A layer depends only on this,
+ * never on the Stage, so the same layer works on a Stage page and on a single `<PageView>`.
+ *
+ * A page surface provides it as a function that returns the current value; `usePage()` gives a
+ * layer an object that reads through that function on every access, so `page.transform` in a
+ * template or a `$derived` follows the zoom.
+ */
+import { getContext, hasContext, setContext } from 'svelte';
+// Built by `makePageContext`, and kept current by `livePageContext`, from `@embedpdf/web`.
+export { livePageContext, makePageContext } from '@embedpdf/web';
+const PAGE = Symbol('embedpdf.page');
+/** For page surfaces (`<Stage>`'s pages, `<PageView>`): provide the page to everything inside. */
+export function setPageContext(page) {
+    setContext(PAGE, page);
+}
+/** The page this layer draws on. Throws outside a page surface. */
+export function usePage() {
+    if (!hasContext(PAGE)) {
+        throw new Error('[embedpdf] usePage() must be used inside <PageView> or a <Stage> page.');
+    }
+    return getContext(PAGE);
+}

package/dist/runtime/props.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The props of the runtime's components: `<Viewer>`, `<KernelProvider>`, `<DocumentGate>` and
+ * `<DocumentScope>`.
+ */
+import type { Snippet } from 'svelte';
+import type { AnyPlugin, Engine, EngineFactory, FailedDocumentInfo, Identity, InitialDocument, Kernel, LockedDocumentInfo, ViewerPageSettings } from '@embedpdf/core';
+export interface ViewerProps {
+    /**
+     * The engine, as an instance or a function. An instance (`{engine}`) is borrowed: the viewer
+     * uses it and never destroys it, so one engine made at module scope serves every viewer; a
+     * local engine is warmed up on mount. A function (`engine={() => localEngine()}`) is the
+     * viewer's own: called on mount, destroyed on unmount. Read once, when the viewer mounts.
+     */
+    engine: Engine | EngineFactory;
+    /** The plugins. Read once, when the viewer mounts. */
+    plugins: AnyPlugin[];
+    /** Documents to open on startup, with optional tab names. Read once. */
+    initialDocuments?: InitialDocument[];
+    /**
+     * Called once the viewer has started, before the content mounts and before `initialDocuments`
+     * open: the door for code that isn't a component (register commands, subscribe to events).
+     */
+    onReady?: (kernel: Kernel) => void;
+    /**
+     * Who the user is, for every document opened without an `identity` of its own. Documents
+     * opened after a change use the new value; open ones keep theirs. The local engine only: the
+     * cloud engine reads it from the document's token.
+     */
+    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. Changes reach the documents opened after them.
+     */
+    scope?: readonly string[];
+    /** The color every part without a color of its own follows. CSS `--epdf-accent` wins over it. */
+    accent?: string;
+    /** How pages look: `background` before the picture arrives, and the `shadow` under each page. */
+    page?: Partial<ViewerPageSettings>;
+    /** Shown while the viewer starts. */
+    fallback?: Snippet;
+    /** Shown when the viewer couldn't start, with why. Without it, a failed start shows nothing. */
+    error?: Snippet<[error: unknown]>;
+    children?: Snippet;
+}
+export interface KernelProviderProps {
+    /** The kernel everything inside reads. Read once: a new kernel takes a new provider. */
+    kernel: Kernel;
+    children?: Snippet;
+}
+export interface DocumentGateProps {
+    /** Shown while this subtree has no document: none is open, or it's still opening. */
+    fallback?: Snippet;
+    /** Shown while the document waits for its password; `fallback` without it. */
+    locked?: Snippet<[document: LockedDocumentInfo]>;
+    /** Shown when the document couldn't be opened, with why; `fallback` without it. */
+    error?: Snippet<[document: FailedDocumentInfo]>;
+    children?: Snippet;
+}
+export interface DocumentScopeProps {
+    /** The document everything inside talks to. */
+    id: string;
+    children?: Snippet;
+}

package/dist/runtime/props.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime/readers.svelte.d.ts

@@ -0,0 +1,47 @@
+import type { CapabilityToken, EventHook, Kernel } from '@embedpdf/core';
+import { type CurrentValue, type MaybeGetter } from './values.svelte.js';
+/** Equal when the two arrays hold the same items in the same order. */
+export declare const shallowArray: <T>(left: readonly T[], right: readonly T[]) => boolean;
+/**
+ * A value derived from the kernel, computed again after every kernel change and passed on only
+ * when `isEqual` says it changed.
+ */
+export declare function useKernelValue<R>(select: (kernel: Kernel) => R, isEqual?: (left: R, right: R) => boolean): CurrentValue<R>;
+/** The active document's id, or null with none open. */
+export declare function useActiveDocumentId(): CurrentValue<string | null>;
+/** The document the nearest `<DocumentScope>` names, or null when this subtree follows the active one. */
+export declare function useDocumentScope(): CurrentValue<string | null>;
+/** The document this subtree talks to: the nearest `<DocumentScope>`'s, else the active one. */
+export declare function useDocumentId(): CurrentValue<string | null>;
+/**
+ * A plugin's capability, as a handle that is always the capability of the document in scope
+ * (see `./capability-handle.ts`). Outside a ready document a document plugin's calls refuse with
+ * `not-ready` (a method that returns a promise rejects), and its settings calls still work. A token no plugin provides throws now: a setup
+ * mistake. The token may be a function, for a component whose token is a prop.
+ */
+export declare function useCapability<T>(token: MaybeGetter<CapabilityToken<T>>): T;
+/**
+ * The capability itself, or null while the token can't resolve (no plugin, no document, or a
+ * document that isn't ready yet). The object is the plugin's own, so it can be handed to code
+ * that keeps it, such as an effect that registers something with it.
+ */
+export declare function useOptionalCapability<T>(token: MaybeGetter<CapabilityToken<T>>): CurrentValue<T | null>;
+/**
+ * A value selected from a capability. Strict: while the token can't resolve, reading it throws
+ * the kernel's reason (no document, the document is loading), for code that knows a document
+ * exists, such as anything inside a `<DocumentGate>`. {@link useOptionalSelector} is its total twin.
+ */
+export declare function useSelector<C, R>(token: MaybeGetter<CapabilityToken<C>>, select: (capability: C) => R, isEqual?: (left: R, right: R) => boolean): CurrentValue<R>;
+/**
+ * A value selected from a capability, or `fallback` while the token can't resolve: for chrome
+ * that stays mounted while no document is open (a zoom readout). A read through a capability
+ * whose document closed a moment ago gives `fallback` too.
+ */
+export declare function useOptionalSelector<C, R>(token: MaybeGetter<CapabilityToken<C>>, select: (capability: C) => R, fallback: R, isEqual?: (left: R, right: R) => boolean): CurrentValue<R>;
+/**
+ * Subscribe to one of a capability's events while the component lives:
+ * `useCapabilityEvent(StageToken, (stage) => stage.onZoomChanged, handler)`. It subscribes again
+ * when the document in scope changes, and not at all without one. Events say what happened;
+ * the current value is a state reader's.
+ */
+export declare function useCapabilityEvent<C, T>(token: MaybeGetter<CapabilityToken<C>>, select: (capability: C) => EventHook<T>, handler: (event: T) => void): void;