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

package/dist/selection/readers.svelte.js

@@ -0,0 +1,26 @@
+import { SelectionToken, selectionState } from '@embedpdf/plugin-selection';
+import { useCapability, useCapabilityEvent } from '../runtime/readers.svelte.js';
+import { settingsReader, stateReader } from '../runtime/state.svelte.js';
+/**
+ * The public selection API (`select()`, `readText()`, `canCopy()`, …) for app chrome: toolbars,
+ * context menus, automation. A handle, always the capability of the document in scope.
+ */
+export function useSelection() {
+    return useCapability(SelectionToken);
+}
+/**
+ * The selection's state: whether anything is selected, whether the user is still selecting, the
+ * character range and the pages it's on (declared once in `selectionState`), as a reactive object
+ * (`state.hasSelection`). With a selector, the value it picks as `{ current }`. Empty without a
+ * document.
+ */
+export const useSelectionState = stateReader(selectionState);
+/** The selection settings (`dragThreshold`, `color`, `handles`), with or without a document. */
+export const useSelectionSettings = settingsReader(SelectionToken);
+/**
+ * Subscribe to one selection event while the component lives:
+ * `useSelectionEvent((selection) => selection.onCommitted, handler)`.
+ */
+export function useSelectionEvent(select, handler) {
+    useCapabilityEvent(SelectionToken, select, handler);
+}

package/dist/selection.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @embedpdf/svelte/selection — text selection.
+ *
+ * `<SelectionLayer>` paints the highlight on each page; `<SelectionMenu>` floats over a settled
+ * selection; `<SelectionHandles>` are the touch handles in a Stage's overlay;
+ * `<SelectionClipboard>` wires Ctrl+C / Cmd+C. The readers are the plugin's four:
+ * `useSelection()`, `useSelectionState()`, `useSelectionSettings()` and `useSelectionEvent()`.
+ */
+export * from '@embedpdf/plugin-selection';
+export { copySelection } from '@embedpdf/web';
+export { default as SelectionLayer } from './selection/SelectionLayer.svelte';
+export { default as SelectionMenu } from './selection/SelectionMenu.svelte';
+export { default as SelectionHandles } from './selection/SelectionHandles.svelte';
+export { default as SelectionClipboard } from './selection/SelectionClipboard.svelte';
+export type { SelectionClipboardProps, SelectionHandlesProps, SelectionMenuProps, } from './selection/props.js';
+export { useSelection, useSelectionEvent, useSelectionSettings, useSelectionState, } from './selection/readers.svelte.js';

package/dist/selection.js

@@ -0,0 +1,18 @@
+/**
+ * @embedpdf/svelte/selection — text selection.
+ *
+ * `<SelectionLayer>` paints the highlight on each page; `<SelectionMenu>` floats over a settled
+ * selection; `<SelectionHandles>` are the touch handles in a Stage's overlay;
+ * `<SelectionClipboard>` wires Ctrl+C / Cmd+C. The readers are the plugin's four:
+ * `useSelection()`, `useSelectionState()`, `useSelectionSettings()` and `useSelectionEvent()`.
+ */
+// Registration travels with the UI.
+export * from '@embedpdf/plugin-selection';
+// The clipboard write lives in @embedpdf/web (the plugin has no DOM); it's here too, so app code
+// has one import for the feature.
+export { copySelection } from '@embedpdf/web';
+export { default as SelectionLayer } from './selection/SelectionLayer.svelte';
+export { default as SelectionMenu } from './selection/SelectionMenu.svelte';
+export { default as SelectionHandles } from './selection/SelectionHandles.svelte';
+export { default as SelectionClipboard } from './selection/SelectionClipboard.svelte';
+export { useSelection, useSelectionEvent, useSelectionSettings, useSelectionState, } from './selection/readers.svelte.js';

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

@@ -0,0 +1,40 @@
+/**
+ * The shell plugin's readers. The app owns every surface's DOM; these bind its open and closed
+ * state to the kernel, so commands can drive it and an app can restore it.
+ *
+ * They work without a document: shell state is a document's, and chrome that uses it (panel
+ * buttons, menu anchors) stays mounted while none is open. With no document every surface reads
+ * as closed, no menu as open, and `useSurface`'s verbs do nothing; `useShell()` then reaches the
+ * stand-in, whose calls refuse with `not-ready`.
+ */
+import type { EventHook } from '@embedpdf/core';
+import type { OpenSurfaceOptions, ShellCapability, SurfaceProps } from '@embedpdf/plugin-shell';
+import { type MaybeGetter } from '../runtime/values.svelte.js';
+/** The shell API: open and close panels, dialogs and menus. Without a document its calls refuse with `not-ready`. */
+export declare function useShell(): ShellCapability;
+/** Subscribe to one shell event while the component lives: `useShellEvent((shell) => shell.onSurfaceOpened, handler)`. */
+export declare function useShellEvent<T>(select: (shell: ShellCapability) => EventHook<T>, handler: (event: T) => void): void;
+/**
+ * Which panels, dialogs and menus are open (declared once in `shellState`), as a reactive object
+ * (`useShellState().openMenus`). Takes a selector. Without a document nothing is open.
+ */
+export declare const useShellState: import("../index.js").StateReader<{
+    openSurfaces: readonly import("@embedpdf/plugin-shell").SurfaceState[];
+    openMenus: readonly string[];
+}>;
+/** One surface: whether it's open and its props, read live, and the calls that change it. */
+export interface SurfaceHandle {
+    readonly isOpen: boolean;
+    /** The props the surface was opened with, or updated to; empty when it has none. */
+    readonly props: SurfaceProps;
+    open(options?: OpenSurfaceOptions): void;
+    close(): void;
+    toggle(options?: OpenSurfaceOptions): void;
+}
+/**
+ * One named surface (panel, dialog, overlay) of this component's document: `panel.isOpen` and
+ * `panel.props` update in a template, and `open`, `close` and `toggle` can be passed as handlers
+ * (`onclick={panel.close}`). Pass the id as a function to follow a prop. It reads as closed, and
+ * its calls do nothing, while no document is open.
+ */
+export declare function useSurface(id: MaybeGetter<string>): SurfaceHandle;

package/dist/shell/readers.svelte.js

@@ -0,0 +1,40 @@
+import { ShellToken, shellState } from '@embedpdf/plugin-shell';
+import { useCapability, useCapabilityEvent, useOptionalCapability, useOptionalSelector, } from '../runtime/readers.svelte.js';
+import { stateReader } from '../runtime/state.svelte.js';
+import { valueOf } from '../runtime/values.svelte.js';
+/** The shell API: open and close panels, dialogs and menus. Without a document its calls refuse with `not-ready`. */
+export function useShell() {
+    return useCapability(ShellToken);
+}
+/** Subscribe to one shell event while the component lives: `useShellEvent((shell) => shell.onSurfaceOpened, handler)`. */
+export function useShellEvent(select, handler) {
+    useCapabilityEvent(ShellToken, select, handler);
+}
+/**
+ * Which panels, dialogs and menus are open (declared once in `shellState`), as a reactive object
+ * (`useShellState().openMenus`). Takes a selector. Without a document nothing is open.
+ */
+export const useShellState = stateReader(shellState);
+const NO_PROPS = Object.freeze({});
+/**
+ * One named surface (panel, dialog, overlay) of this component's document: `panel.isOpen` and
+ * `panel.props` update in a template, and `open`, `close` and `toggle` can be passed as handlers
+ * (`onclick={panel.close}`). Pass the id as a function to follow a prop. It reads as closed, and
+ * its calls do nothing, while no document is open.
+ */
+export function useSurface(id) {
+    const shell = useOptionalCapability(ShellToken);
+    const isOpen = useOptionalSelector(ShellToken, (shell) => shell.isOpen(valueOf(id)), false);
+    const props = useOptionalSelector(ShellToken, (shell) => shell.getSurface(valueOf(id))?.props ?? NO_PROPS, NO_PROPS);
+    return {
+        get isOpen() {
+            return isOpen.current;
+        },
+        get props() {
+            return props.current;
+        },
+        open: (options) => shell.current?.open(valueOf(id), options),
+        close: () => shell.current?.close(valueOf(id)),
+        toggle: (options) => shell.current?.toggle(valueOf(id), options),
+    };
+}

package/dist/shell/surface-focus.svelte.d.ts

@@ -0,0 +1,16 @@
+import type { Attachment } from 'svelte/attachments';
+import { type SurfaceFocusOptions } from '@embedpdf/web';
+import { type MaybeGetter } from '../runtime/values.svelte.js';
+export type { SurfaceFocusOptions };
+/**
+ * An attachment that puts the cursor in its element when the surface `id` asks for it: on every
+ * `open(id, { focus: true })`, a command whose panel says `focus` among them, and when the
+ * element mounts while the request is up (the panel opened, or its code loaded, because of it).
+ * A plain open never moves it. `select` selects an input's text, so typing replaces it. It reads
+ * the surface of this component's document; pass the id as a function to follow a prop.
+ *
+ * ```svelte
+ * <input {@attach surfaceFocus('search', { select: true })} bind:value={query} />
+ * ```
+ */
+export declare function surfaceFocus(id: MaybeGetter<string>, options?: SurfaceFocusOptions): Attachment<HTMLElement>;

package/dist/shell/surface-focus.svelte.js

@@ -0,0 +1,33 @@
+/**
+ * Putting the cursor in an element when its panel asks for it. `@embedpdf/web`'s surface focus
+ * follower owns the rule (a new request moves the cursor in, and so does mounting while one is
+ * up); this binds it to Svelte as an attachment.
+ */
+import { untrack } from 'svelte';
+import { ShellToken } from '@embedpdf/plugin-shell';
+import { createSurfaceFocusFollower } from '@embedpdf/web';
+import { useOptionalCapability, useOptionalSelector } from '../runtime/readers.svelte.js';
+import { valueOf } from '../runtime/values.svelte.js';
+/**
+ * An attachment that puts the cursor in its element when the surface `id` asks for it: on every
+ * `open(id, { focus: true })`, a command whose panel says `focus` among them, and when the
+ * element mounts while the request is up (the panel opened, or its code loaded, because of it).
+ * A plain open never moves it. `select` selects an input's text, so typing replaces it. It reads
+ * the surface of this component's document; pass the id as a function to follow a prop.
+ *
+ * ```svelte
+ * <input {@attach surfaceFocus('search', { select: true })} bind:value={query} />
+ * ```
+ */
+export function surfaceFocus(id, options = {}) {
+    const shell = useOptionalCapability(ShellToken);
+    const request = useOptionalSelector(ShellToken, (current) => current.getSurface(valueOf(id))?.focusRequest ?? 0, 0);
+    return (element) => {
+        const follower = createSurfaceFocusFollower();
+        $effect(() => {
+            const current = shell.current;
+            const value = request.current;
+            untrack(() => follower.follow(element, current, value, options));
+        });
+    };
+}

package/dist/shell.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @embedpdf/svelte/shell — panels, dialogs and menus.
+ *
+ * Your app draws every surface; the readers bind whether each one is open (and its props) to the
+ * kernel, so commands can open them and a layout can be saved and restored. `surfaceFocus` puts
+ * the cursor in a panel's element when the panel asks for it.
+ */
+export * from '@embedpdf/plugin-shell';
+export { useShell, useShellEvent, useShellState, useSurface } from './shell/readers.svelte.js';
+export type { SurfaceHandle } from './shell/readers.svelte.js';
+export { surfaceFocus } from './shell/surface-focus.svelte.js';
+export type { SurfaceFocusOptions } from './shell/surface-focus.svelte.js';

package/dist/shell.js

@@ -0,0 +1,11 @@
+/**
+ * @embedpdf/svelte/shell — panels, dialogs and menus.
+ *
+ * Your app draws every surface; the readers bind whether each one is open (and its props) to the
+ * kernel, so commands can open them and a layout can be saved and restored. `surfaceFocus` puts
+ * the cursor in a panel's element when the panel asks for it.
+ */
+// Registration travels with the UI.
+export * from '@embedpdf/plugin-shell';
+export { useShell, useShellEvent, useShellState, useSurface } from './shell/readers.svelte.js';
+export { surfaceFocus } from './shell/surface-focus.svelte.js';

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

@@ -0,0 +1,43 @@
+/**
+ * The signature plugin's readers: `useSignature()` (the API), the state and the settings,
+ * `useSignatureEvent()`, and `useSignerRows()`, the people whose marks this browser holds, for a
+ * signature picker.
+ */
+import type { EventHook } from '@embedpdf/core';
+import { signatureState } from '@embedpdf/plugin-signature';
+import type { SignatureCapability, SignerRow } from '@embedpdf/plugin-signature';
+import { type StateReader } from '../runtime/state.svelte.js';
+import { type CurrentValue } from '../runtime/values.svelte.js';
+/**
+ * The signature API for the document in scope: sign, place a mark, fill or clear a field, check
+ * the signatures. A handle: keep it whole and call through it (`signature.sign(…)`).
+ */
+export declare function useSignature(): SignatureCapability;
+/**
+ * The signatures' state: the signed fields with their verdicts (`signatures`), what they allow,
+ * the `target`, whether a signing runs (`busy`), a two-step signing in progress, and whether
+ * they're read, declared once in `signatureState`. A reactive object (`state.signatures`), or
+ * with a selector one value as `{ current }`. Empty without a document.
+ *
+ * Typed through the declaration, so the published types name it from `@embedpdf/plugin-signature`, a
+ * dependency of this package, and not from the engine package `protection`'s type comes from, which
+ * isn't one.
+ */
+export declare const useSignatureState: StateReader<ReturnType<typeof signatureState.read>>;
+/**
+ * The signature settings (`key`, `mode`, `trust`, `allowCertify`), with or without a document.
+ * They belong to the plugin; change them with `useSignature().updateSettings()`.
+ */
+export declare const useSignatureSettings: import("../index.js").SettingsReader<import("@embedpdf/plugin-signature").SignatureSettings & object>;
+/**
+ * Subscribe to one signature event while the component lives:
+ * `useSignatureEvent((signature) => signature.onSigned, handler)`.
+ */
+export declare function useSignatureEvent<T>(select: (signature: SignatureCapability) => EventHook<T>, handler: (event: T) => void): void;
+/**
+ * The people whose marks this browser holds, one row per library of kind `signatures`, for a
+ * picker, as `{ current }`: `const rows = useSignerRows()`, then `rows.current`. Derived from the
+ * stamp plugin, so it needs `stampPlugin()`: rename, delete and export are the library verbs, and
+ * nothing is stored beyond the file.
+ */
+export declare function useSignerRows(): CurrentValue<readonly SignerRow[]>;

package/dist/signature/readers.svelte.js

@@ -0,0 +1,46 @@
+import { signatureState, signerRowsOf, SIGNATURES_LIBRARY_KIND, SignatureToken, } from '@embedpdf/plugin-signature';
+import { useCapability, useCapabilityEvent } from '../runtime/readers.svelte.js';
+import { settingsReader, stateReader } from '../runtime/state.svelte.js';
+import { currentOf, derivedValue } from '../runtime/values.svelte.js';
+import { useStampAssets, useStampLibraries } from '../stamp/readers.svelte.js';
+/**
+ * The signature API for the document in scope: sign, place a mark, fill or clear a field, check
+ * the signatures. A handle: keep it whole and call through it (`signature.sign(…)`).
+ */
+export function useSignature() {
+    return useCapability(SignatureToken);
+}
+/**
+ * The signatures' state: the signed fields with their verdicts (`signatures`), what they allow,
+ * the `target`, whether a signing runs (`busy`), a two-step signing in progress, and whether
+ * they're read, declared once in `signatureState`. A reactive object (`state.signatures`), or
+ * with a selector one value as `{ current }`. Empty without a document.
+ *
+ * Typed through the declaration, so the published types name it from `@embedpdf/plugin-signature`, a
+ * dependency of this package, and not from the engine package `protection`'s type comes from, which
+ * isn't one.
+ */
+export const useSignatureState = stateReader(signatureState);
+/**
+ * The signature settings (`key`, `mode`, `trust`, `allowCertify`), with or without a document.
+ * They belong to the plugin; change them with `useSignature().updateSettings()`.
+ */
+export const useSignatureSettings = settingsReader(SignatureToken);
+/**
+ * Subscribe to one signature event while the component lives:
+ * `useSignatureEvent((signature) => signature.onSigned, handler)`.
+ */
+export function useSignatureEvent(select, handler) {
+    useCapabilityEvent(SignatureToken, select, handler);
+}
+/**
+ * The people whose marks this browser holds, one row per library of kind `signatures`, for a
+ * picker, as `{ current }`: `const rows = useSignerRows()`, then `rows.current`. Derived from the
+ * stamp plugin, so it needs `stampPlugin()`: rename, delete and export are the library verbs, and
+ * nothing is stored beyond the file.
+ */
+export function useSignerRows() {
+    const libraries = useStampLibraries({ kind: SIGNATURES_LIBRARY_KIND });
+    const assets = useStampAssets();
+    return currentOf(derivedValue(() => signerRowsOf(libraries.current, assets.current)));
+}

package/dist/signature.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @embedpdf/svelte/signature — signing.
+ *
+ * Signing for the document in scope (`useSignature()`), its state as a reactive object (the
+ * signatures with their verdicts, what they allow, the target, a two-step signing in progress),
+ * the settings, the events, and the one derivation a signatures panel needs: the people
+ * (libraries of kind `signatures`) with their marks (`useSignerRows()`). The signers
+ * (`personalSigner`, `webCryptoSigner`, `remoteSigner`, `createTestSigner`) come with the plugin.
+ * An empty signature field is "sign here" in `<FormLayer>` (`@embedpdf/svelte/form`).
+ *
+ *   const signature = useSignature();
+ *   await signature.placeMark({ assetId }, { field: target }); // sign, fill or ask, by mode
+ */
+export * from '@embedpdf/plugin-signature';
+export { useSignature, useSignatureEvent, useSignatureSettings, useSignatureState, useSignerRows, } from './signature/readers.svelte.js';

package/dist/signature.js

@@ -0,0 +1,16 @@
+/**
+ * @embedpdf/svelte/signature — signing.
+ *
+ * Signing for the document in scope (`useSignature()`), its state as a reactive object (the
+ * signatures with their verdicts, what they allow, the target, a two-step signing in progress),
+ * the settings, the events, and the one derivation a signatures panel needs: the people
+ * (libraries of kind `signatures`) with their marks (`useSignerRows()`). The signers
+ * (`personalSigner`, `webCryptoSigner`, `remoteSigner`, `createTestSigner`) come with the plugin.
+ * An empty signature field is "sign here" in `<FormLayer>` (`@embedpdf/svelte/form`).
+ *
+ *   const signature = useSignature();
+ *   await signature.placeMark({ assetId }, { field: target }); // sign, fill or ask, by mode
+ */
+// Registration travels with the UI.
+export * from '@embedpdf/plugin-signature';
+export { useSignature, useSignatureEvent, useSignatureSettings, useSignatureState, useSignerRows, } from './signature/readers.svelte.js';

package/dist/stage/PageSurface.svelte

@@ -0,0 +1,126 @@
+<!--
+  One visible page of a Stage: placed where the camera puts it, with its drop shadow, the page
+  content (which turns with the page) and the page chrome (which never turns). It provides the
+  page context to every layer inside.
+
+  All geometry comes from the page's transform: the display footprint (`viewWidth`/`viewHeight`,
+  already swapped for a quarter turn and snapped to device pixels) and the unturned content box
+  (`contentWidth`/`contentHeight`). Nothing here multiplies by the zoom or the pixel ratio.
+-->
+<script lang="ts">
+  import { untrack, type Snippet } from 'svelte';
+  import { toPageRef } from '@embedpdf/core';
+  import type { PageFrame } from '@embedpdf/core-geometry';
+  import type { VisiblePage } from '@embedpdf/plugin-stage';
+  import type { StageHostCapability } from '@embedpdf/plugin-stage/contract/host';
+  import type { PageViewDemand } from '@embedpdf/plugin-render/contract';
+  import {
+    livePageContext,
+    makePageContext,
+    pageSurfaceLayout,
+    paint,
+    stagePageDemand,
+  } from '@embedpdf/web';
+  import { useViewerSettings } from '../runtime/documents.svelte.js';
+  import { setPageContext, type PageContextValue } from '../runtime/page.js';
+
+  let {
+    documentId,
+    page,
+    frame,
+    stage,
+    content,
+    chrome,
+  }: {
+    documentId: string;
+    /** This page as the stage places it now: a new object on every camera frame. */
+    page: VisiblePage;
+    /** The bands reserved around the page, in screen pixels; the layout left room for them. */
+    frame: PageFrame;
+    stage: StageHostCapability;
+    content: Snippet<[page: PageContextValue]>;
+    chrome?: Snippet<[page: PageContextValue]>;
+  } = $props();
+
+  let contentElement: HTMLDivElement | undefined;
+
+  // The viewer's `page` settings; `--epdf-page-*` CSS variables win over them.
+  const look = useViewerSettings((settings) => settings.page);
+
+  // The Stage keys its pages by object number, so this surface's number never changes: one
+  // PageRef for its lifetime, safe for layers to key their work on.
+  const pageRef = toPageRef(untrack(() => page.ref.objectNumber));
+  // Each its own derived value, so the context below changes only when one of them does, not on
+  // every camera frame.
+  const pageIndex = $derived(page.pageIndex);
+  const transform = $derived(page.transform);
+
+  /**
+   * How much of this page the view wants, for raster planning: read live from the stage, a zero
+   * box while the page is off screen. It reads `page` first, so a reaction that asks (the tile
+   * plane) asks again on every camera frame.
+   */
+  function viewDemand(): PageViewDemand {
+    const placed = page;
+    return stagePageDemand(stage, pageRef.objectNumber, placed.transform.deviceWidth);
+  }
+
+  const context = $derived(
+    makePageContext(
+      documentId,
+      // The hosting lens: raster planning keys tiles by it, so a thumbnail rail and the main
+      // view never fight over one plan.
+      stage.getLensId(),
+      pageRef,
+      pageIndex,
+      frame,
+      transform,
+      () => contentElement!.getBoundingClientRect(),
+      viewDemand,
+    ),
+  );
+  const live = livePageContext(() => context);
+  setPageContext(live);
+
+  // The outer box (one frame further out than the footprint, so the content keeps its place),
+  // the shadow at the footprint, and the content box centred on it and turned about its centre.
+  const layout = $derived(
+    pageSurfaceLayout(transform, frame, { x: page.screenX, y: page.screenY }),
+  );
+</script>
+
+<div
+  style:position="absolute"
+  style:left="{layout.outer.left}px"
+  style:top="{layout.outer.top}px"
+  style:width="{layout.outer.width}px"
+  style:height="{layout.outer.height}px"
+>
+  <!-- The drop shadow only: at the content box, with no fill, so it never shows behind the
+       picture, and it stays put while the page turns. -->
+  <div
+    style:position="absolute"
+    style:left="{layout.shadow.left}px"
+    style:top="{layout.shadow.top}px"
+    style:width="{layout.shadow.width}px"
+    style:height="{layout.shadow.height}px"
+    style:box-shadow={paint('page-shadow', look.current.shadow)}
+  ></div>
+  <!-- The page: its background and its layers as one box, the only thing the rotation turns.
+       Native text and image selection is off: the selection layer draws its own. -->
+  <div
+    bind:this={contentElement}
+    style="user-select: none; -webkit-user-select: none"
+    style:position="absolute"
+    style:left="{layout.content.left}px"
+    style:top="{layout.content.top}px"
+    style:width="{layout.content.width}px"
+    style:height="{layout.content.height}px"
+    style:background={paint('page-background', look.current.background)}
+    style:transform={layout.turn ?? undefined}
+  >
+    {@render content(live)}
+  </div>
+  <!-- The page chrome fills the outer box and never turns. -->
+  {@render chrome?.(live)}
+</div>

package/dist/stage/PageSurface.svelte.d.ts

@@ -0,0 +1,18 @@
+import { type Snippet } from 'svelte';
+import type { PageFrame } from '@embedpdf/core-geometry';
+import type { VisiblePage } from '@embedpdf/plugin-stage';
+import type { StageHostCapability } from '@embedpdf/plugin-stage/contract/host';
+import { type PageContextValue } from '../runtime/page.js';
+type $$ComponentProps = {
+    documentId: string;
+    /** This page as the stage places it now: a new object on every camera frame. */
+    page: VisiblePage;
+    /** The bands reserved around the page, in screen pixels; the layout left room for them. */
+    frame: PageFrame;
+    stage: StageHostCapability;
+    content: Snippet<[page: PageContextValue]>;
+    chrome?: Snippet<[page: PageContextValue]>;
+};
+declare const PageSurface: import("svelte").Component<$$ComponentProps, {}, "">;
+type PageSurface = ReturnType<typeof PageSurface>;
+export default PageSurface;

package/dist/stage/Scrollbar.svelte

@@ -0,0 +1,148 @@
+<!--
+  A scrollbar for a Stage lens that you style yourself: a view of `stage.getScrollMetrics()`.
+
+  Thumb drag with pointer capture and a kept grab point, track paging with press-and-hold repeat
+  that stops at the pointer, a minimum thumb length on long documents, and macOS-style auto-hide.
+  On an unbounded stage the metrics already carry the union of content and view, so the bar
+  shrinks as you pan away; the mapping is frozen during a thumb drag, so the thumb never chases
+  itself while that union changes.
+
+  Geometry and behavior live here, looks in your CSS, against
+    [data-embedpdf-scrollbar][data-axis="y"][data-state="visible|hidden"]
+    [data-embedpdf-scrollbar][data-dragging]
+    [data-embedpdf-scrollbar-thumb]
+  Unstyled, it's a transparent track at the viewport's edge with a `--epdf-scrollbar-thumb` pill.
+  Build anything else (a minimap, a progress ring) from `useScrollMetrics()` and `stage.scrollTo()`.
+-->
+<script lang="ts">
+  import {
+    createScrollbarPresses,
+    paintDefault,
+    scrollbarLayout,
+    type ScrollbarTrack,
+  } from '@embedpdf/web';
+  import { useCapability } from '../runtime/readers.svelte.js';
+  import type { ScrollbarProps } from './props.js';
+  import { asHost, scrollMetricsOf } from './readers.svelte.js';
+  import { stageTokenOf } from './stage-scope.js';
+
+  let {
+    axis,
+    token: explicitToken,
+    autoHide = 1200,
+    minThumbSize = 24,
+    trackPress = 'page',
+    class: className,
+    style,
+    thumbClass,
+    thumbStyle,
+  }: ScrollbarProps = $props();
+
+  const lens = stageTokenOf(() => explicitToken);
+  const stage = useCapability(() => asHost(lens()));
+  const metrics = scrollMetricsOf(lens);
+
+  const vertical = $derived(axis === 'y');
+  const scrollable = $derived(vertical ? metrics.scrollableY : metrics.scrollableX);
+
+  let track: HTMLDivElement | undefined = $state();
+  let trackPx = $state(0);
+  let dragging = $state(false);
+  let hovered = $state(false);
+  let active = $state(true); // the view moved recently
+
+  // The thumb along the track: one formula for drawing, dragging and paging, shared with every
+  // framework.
+  const layout = $derived(scrollbarLayout(metrics, vertical, trackPx, minThumbSize));
+
+  // ── auto-hide: any metrics change shows the bar and starts the fade again ──
+  const hideAfter = $derived(autoHide === false ? 0 : autoHide);
+  $effect(() => {
+    // Every number, so any movement counts.
+    void [metrics.scrollTop, metrics.scrollLeft, metrics.scrollHeight, metrics.scrollWidth];
+    void [metrics.clientHeight, metrics.clientWidth];
+    if (!hideAfter) return;
+    active = true;
+    const timer = setTimeout(() => (active = false), hideAfter);
+    return () => clearTimeout(timer);
+  });
+  const shown = $derived(!hideAfter || active || hovered || dragging);
+
+  // ── the track's length, which the pixel mapping needs ──
+  $effect(() => {
+    const element = track;
+    const isVertical = vertical;
+    if (!element) return;
+    const measure = () => (trackPx = isVertical ? element.clientHeight : element.clientWidth);
+    const observer = new ResizeObserver(measure);
+    observer.observe(element);
+    measure();
+    return () => observer.disconnect();
+  });
+
+  // ── input: `@embedpdf/web`'s press handling (thumb drags, track paging and jumps), handed the
+  //    bar as it is now on every event. ──
+  const presses = createScrollbarPresses((value) => (dragging = value));
+  const pressedTrack = (): ScrollbarTrack => ({
+    stage,
+    vertical,
+    element: track!,
+    layout,
+    // Fresh geometry for paging steps, from the capability rather than the last drawn frame.
+    liveLayout: () => scrollbarLayout(stage.getScrollMetrics(), vertical, trackPx, minThumbSize),
+  });
+
+  // No repeat timer outlives the bar.
+  $effect(() => () => presses.release());
+
+  const trackDefaults = $derived(
+    vertical
+      ? 'position: absolute; top: 0; right: 0; bottom: 0; width: 12px;'
+      : 'position: absolute; left: 0; right: 0; bottom: 0; height: 12px;',
+  );
+  const thumbDefaults = $derived(
+    vertical
+      ? `position: absolute; left: 2px; right: 2px; top: ${layout.thumbPosition}px; height: ${layout.thumbLength}px;`
+      : `position: absolute; top: 2px; bottom: 2px; left: ${layout.thumbPosition}px; width: ${layout.thumbLength}px;`,
+  );
+</script>
+
+{#if scrollable}
+  <!-- The bar drives the Stage, which is no single element to name in aria-controls, and the
+       pointer is its input: like a native overlay scrollbar, it takes no focus. -->
+  <!-- svelte-ignore a11y_role_has_required_aria_props, a11y_interactive_supports_focus -->
+  <div
+    bind:this={track}
+    role="scrollbar"
+    aria-orientation={vertical ? 'vertical' : 'horizontal'}
+    aria-valuemin={0}
+    aria-valuemax={Math.round(layout.maxOffset)}
+    aria-valuenow={Math.round(layout.offset)}
+    data-embedpdf-scrollbar=""
+    data-axis={axis}
+    data-state={shown ? 'visible' : 'hidden'}
+    data-dragging={dragging ? '' : undefined}
+    class={className}
+    style="{trackDefaults} touch-action: none; user-select: none; opacity: {shown
+      ? 1
+      : 0}; transition: opacity 200ms; pointer-events: {shown ? 'auto' : 'none'};{style
+      ? ` ${style}`
+      : ''}"
+    onpointerdown={(event) => presses.pressTrack(event, pressedTrack(), trackPress)}
+    onpointermove={(event) => presses.move(event, pressedTrack())}
+    onpointerup={() => presses.release()}
+    onpointercancel={() => presses.release()}
+    onpointerenter={() => (hovered = true)}
+    onpointerleave={() => (hovered = false)}
+  >
+    <!-- svelte-ignore a11y_no_static_element_interactions -->
+    <div
+      data-embedpdf-scrollbar-thumb=""
+      class={thumbClass}
+      style="{thumbDefaults} border-radius: 6px; background: {paintDefault(
+        'scrollbar-thumb',
+      )};{thumbStyle ? ` ${thumbStyle}` : ''}"
+      onpointerdown={(event) => presses.pressThumb(event, pressedTrack())}
+    ></div>
+  </div>
+{/if}

package/dist/stage/Scrollbar.svelte.d.ts

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