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

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;

package/dist/stage/Stage.svelte

@@ -0,0 +1,181 @@
+<!--
+  The Stage: lays out the document's pages by the camera, keeps only the visible ones mounted,
+  and draws its content (the `children` snippet) on each; you bring the layers. Pointer, wheel and touch input go
+  through `@embedpdf/web`'s stage surface, so every framework has one feel.
+
+  Everything inside binds to this lens: a `useStageState()` in a page's chrome or a
+  `<Scrollbar>` in the overlay needs no token. The overlay also gets the Stage's projection, so
+  anchored UI follows the camera in the same flush as the pages.
+-->
+<script lang="ts">
+  import { untrack } from 'svelte';
+  import type { CapabilityToken } from '@embedpdf/core';
+  import type { PageFrame } from '@embedpdf/core-geometry';
+  import { createScrollHandler, DEFAULT_SETTINGS, stageState } from '@embedpdf/plugin-stage';
+  import type { VisiblePage } from '@embedpdf/plugin-stage';
+  import type { StageHostCapability } from '@embedpdf/plugin-stage/contract/host';
+  import { InteractionToken as InteractionPublicToken } from '@embedpdf/plugin-interaction/contract';
+  import { InteractionToken } from '@embedpdf/plugin-interaction/contract/host';
+  import { createStageSurface, stageViewProjector } from '@embedpdf/web';
+  import { setProjectorBinding, setShownPages, type ShownPages } from '../anchored/context.js';
+  import {
+    useCapabilityEvent,
+    useDocumentId,
+    useKernelValue,
+    useOptionalCapability,
+    useOptionalSelector,
+  } from '../runtime/readers.svelte.js';
+  import { declaredState } from '../runtime/state.svelte.js';
+  import { useKernelBinding } from '../runtime/binding.svelte.js';
+  import PageSurface from './PageSurface.svelte';
+  import type { StageProps } from './props.js';
+  import { setStageToken, stageTokenOf } from './stage-scope.js';
+  import { syncTwoWay } from './two-way.svelte.js';
+
+  let {
+    children,
+    pageChrome,
+    overlay,
+    tool = $bindable(),
+    onToolChange,
+    page = $bindable(),
+    zoom = $bindable(),
+    token: explicitToken,
+    class: className,
+    style,
+  }: StageProps = $props();
+
+  const token = stageTokenOf(() => explicitToken);
+  setStageToken(token);
+  // The surface is a host of the lens: it reports the viewport size, drives gestures and reads
+  // the lens id. The host contract is the same runtime token, typed wider.
+  const hostToken = () => token() as unknown as CapabilityToken<StageHostCapability>;
+  const stage = useOptionalCapability(hostToken);
+  const interaction = useOptionalCapability(InteractionToken);
+  const documentId = useDocumentId();
+
+  const NO_PAGES: readonly VisiblePage[] = [];
+  // The visible pages already fold in the camera (each carries its snapped screen position and
+  // transform), so panning gives a new list: no separate camera subscription.
+  const pages = useOptionalSelector(hostToken, (lens) => lens.listVisiblePages(), NO_PAGES);
+  const settings = useOptionalSelector(hostToken, (lens) => lens.getSettings(), DEFAULT_SETTINGS);
+  // The reserved bands around every page, compared by side so an equal frame changes nothing.
+  const frame = useOptionalSelector(
+    hostToken,
+    (lens) => lens.getSettings().pageFrame,
+    DEFAULT_SETTINGS.pageFrame,
+    (left: PageFrame, right: PageFrame) =>
+      left.top === right.top &&
+      left.right === right.right &&
+      left.bottom === right.bottom &&
+      left.left === right.left,
+  );
+
+  // How this view takes pointer input is its own settings: routed to the interaction plugin
+  // (which also registers this view's pan-scroll handler, scoped to it, so two Stages on one
+  // document never pan each other), or the Stage's own drag-to-pan without it.
+  const routed = $derived(settings.current.interaction && interaction.current !== null);
+  const panFallback = $derived(settings.current.panFallback);
+  const zoomGestures = $derived(settings.current.zoomGestures);
+  // The cursor the interaction plugin resolves (text, grab, …), on the viewport while routed.
+  const hubCursor = useKernelValue(() => interaction.current?.getCursor() ?? 'default');
+
+  let element: HTMLDivElement | undefined;
+
+  $effect(() => {
+    const lens = stage.current;
+    const hub = routed ? interaction.current : null;
+    const gestures = zoomGestures;
+    const fallback = panFallback;
+    if (!element || !lens) return;
+    return untrack(() => {
+      const detachSurface = createStageSurface(element!, lens, {
+        hub,
+        source: lens.getLensId(),
+        zoomGestures: gestures,
+      });
+      const offScroll = hub
+        ? hub.registerHandler(createScrollHandler(lens, hub, { panFallback: fallback }), {
+            source: lens.getLensId(),
+          })
+        : null;
+      return () => {
+        offScroll?.();
+        detachSurface();
+      };
+    });
+  });
+
+  // ── two-way values ─────────────────────────────────────────────────────────
+
+  // The bound tool wins whenever it's set, again when the document changes.
+  $effect(() => {
+    const wanted = tool;
+    const hub = interaction.current;
+    if (wanted === undefined || !hub) return;
+    untrack(() => {
+      if (hub.getActiveToolId() !== wanted) hub.activateTool(wanted);
+    });
+  });
+  useCapabilityEvent(
+    InteractionPublicToken,
+    (hub) => hub.onToolChanged,
+    (event) => {
+      if (tool !== undefined) tool = event.toolId;
+      onToolChange?.(event.toolId);
+    },
+  );
+
+  const binding = useKernelBinding();
+  const view = declaredState(binding, token, stageState.read, stageState.empty);
+  syncTwoWay({
+    stage: () => view().currentPageIndex,
+    bound: () => page,
+    ready: () => stage.current !== null,
+    write: (value) => (page = value),
+    apply: (value) => stage.current?.goToPage(value),
+  });
+  syncTwoWay({
+    stage: () => view().zoomLevel,
+    bound: () => zoom,
+    ready: () => stage.current !== null,
+    write: (value) => (zoom = value),
+    apply: (value) => stage.current?.zoomTo(value),
+  });
+
+  // ── what the overlay anchors to ───────────────────────────────────────────
+
+  // Anchored UI positions through the camera: pure state, no DOM reads. The visible pages are
+  // the binding's revision, so a camera change moves the pages and every anchored element in
+  // the same flush.
+  const projector = stageViewProjector(() => stage.current);
+  const projectorBinding = $derived({ projector, revision: pages.current });
+  setProjectorBinding(() => projectorBinding);
+  // The pages on screen as one value that changes only when a page comes or goes, so anchored
+  // UI on the other pages sits out every camera frame.
+  const shownKey = $derived(pages.current.map((visible) => visible.ref.objectNumber).join(','));
+  const shownPages: ShownPages = $derived(new Set(shownKey ? shownKey.split(',').map(Number) : []));
+  setShownPages(() => shownPages);
+</script>
+
+<div
+  bind:this={element}
+  class={className}
+  style="position: relative; overflow: hidden; touch-action: none;{routed
+    ? ` cursor: ${hubCursor.current};`
+    : ''}{style ? ` ${style}` : ''}"
+>
+  {#if stage.current}
+    {#each pages.current as visible (visible.ref.objectNumber)}
+      <PageSurface
+        documentId={documentId.current ?? ''}
+        page={visible}
+        frame={frame.current}
+        stage={stage.current}
+        content={children}
+        chrome={pageChrome}
+      />
+    {/each}
+  {/if}
+  {@render overlay?.()}
+</div>

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

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

package/dist/stage/StageScope.svelte

@@ -0,0 +1,14 @@
+<!--
+  Binds everything inside to a stage lens: the stage readers and stage chrome inside use `token`
+  unless they are given one themselves.
+-->
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import { setStageToken, type StageTokenProp } from './stage-scope.js';
+
+  let { token, children }: { token: StageTokenProp; children?: Snippet } = $props();
+
+  setStageToken(() => token);
+</script>
+
+{@render children?.()}

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

@@ -0,0 +1,9 @@
+import type { Snippet } from 'svelte';
+import { type StageTokenProp } from './stage-scope.js';
+type $$ComponentProps = {
+    token: StageTokenProp;
+    children?: Snippet;
+};
+declare const StageScope: import("svelte").Component<$$ComponentProps, {}, "">;
+type StageScope = ReturnType<typeof StageScope>;
+export default StageScope;