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

package/dist/selection/SelectionClipboard.svelte

@@ -0,0 +1,35 @@
+<!--
+  Copying selected text with the keyboard and the browser's Copy menu. Mount it once per viewer:
+  it fetches the selected text when the selection settles, answers the native `copy` event at
+  once, and falls back to the async Clipboard API for Ctrl+C / Cmd+C when the page has no DOM
+  selection. A selection the user may not copy isn't copied, and `onRefused` is called. It
+  draws nothing, and wires nothing until a document is ready. A Copy button calls
+  `copySelection(useSelection())` from its click instead.
+-->
+<script lang="ts">
+  import { untrack } from 'svelte';
+  import { SelectionToken } from '@embedpdf/plugin-selection';
+  import { wireSelectionClipboard } from '@embedpdf/web';
+  import { useOptionalCapability } from '../runtime/readers.svelte.js';
+  import { valueOf } from '../runtime/values.svelte.js';
+  import type { SelectionClipboardProps } from './props.js';
+
+  let { prefetch, onRefused, target }: SelectionClipboardProps = $props();
+
+  // The capability itself, not a handle: the clipboard wiring keeps it and subscribes to it.
+  const selection = useOptionalCapability(SelectionToken);
+
+  $effect(() => {
+    const current = selection.current;
+    const element = valueOf(target);
+    // Read at the moment of the refusal, so a new callback needs no new wiring.
+    const options = {
+      ...(prefetch === undefined ? {} : { prefetch }),
+      ...(element ? { target: element } : {}),
+      onRefused: () => untrack(() => onRefused)?.(),
+    };
+    // A target that hasn't mounted yet wires nothing; this runs again once it has.
+    if (!current || (target !== undefined && !element)) return;
+    return untrack(() => wireSelectionClipboard(current, options));
+  });
+</script>

package/dist/selection/SelectionClipboard.svelte.d.ts

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

package/dist/selection/SelectionHandles.svelte

@@ -0,0 +1,192 @@
+<!--
+  Draggable selection handles, the way phones draw them: a thin caret bar that is the selection's
+  own start or end edge (the boundary glyph's edge, so turned text and turned pages carry the
+  handle with them), capped by a circle that keeps its size on screen, above the first line at
+  the start and below the last line at the end.
+
+  On touch, where nothing can drag a caret, the handles grow or shrink a selection: a long press
+  selects a word, then each handle extends from the opposite end, snapping to glyphs and crossing
+  pages like a pointer drag. A handle drag is the same selection gesture, so the highlight, the
+  menu and the commit events behave the same.
+
+  Mount it in a `<Stage>`'s overlay, next to `<SelectionMenu>`. Outside a Stage it draws nothing
+  (a `<PageView>` has no camera to project the handles through). A press on a handle never pans
+  the Stage. Painted in the plugin's `handles` setting, which the `--epdf-text-selection-handle`
+  and `--epdf-text-selection-handle-shadow` CSS variables win over.
+
+  The policy is shared: the view over the Stage, the endpoints, the geometry and the armed drag
+  come from the selection plugin's `handles` module, the listener mechanics from
+  `@embedpdf/web`'s `attachSelectionHandle`. This file keeps the subscriptions and the markup.
+-->
+<script lang="ts">
+  import {
+    HANDLE_BAR,
+    HANDLE_HEAD,
+    HANDLE_PAD,
+    armSelectionHandle,
+    selectionHandleEndpointsOf,
+    selectionHandleGeom,
+    selectionHandleViewOf,
+    type SelectionHandleGeom,
+  } from '@embedpdf/plugin-selection';
+  import { SelectionToken } from '@embedpdf/plugin-selection/contract/host';
+  import { attachSelectionHandle, paint, sameSelectionEndpoints } from '@embedpdf/web';
+  import { useOptionalProjectorBinding } from '../anchored/context.js';
+  import { devWarn } from '../runtime/dev.js';
+  import { useViewerSettings } from '../runtime/documents.svelte.js';
+  import {
+    useCapability,
+    useKernelValue,
+    useOptionalCapability,
+    useOptionalSelector,
+  } from '../runtime/readers.svelte.js';
+  import { stageTokenOf } from '../stage/stage-scope.js';
+  import type { SelectionHandlesProps } from './props.js';
+  import { useSelectionSettings, useSelectionState } from './readers.svelte.js';
+
+  type Role = 'start' | 'end';
+
+  let { token }: SelectionHandlesProps = $props();
+
+  const host = useCapability(SelectionToken);
+  const stage = useOptionalCapability(stageTokenOf(() => token));
+
+  // Outside a Stage there is no camera to project through: say so instead of drawing nothing
+  // without a word.
+  const surface = useOptionalProjectorBinding();
+  if (!surface || surface().projector.space !== 'overlay') {
+    devWarn(
+      'selection-handles-outside-stage',
+      '<SelectionHandles> draws nothing here: put it in the <Stage> overlay snippet ' +
+        '(a <PageView> has no camera to project the handles through).',
+    );
+  }
+
+  const selecting = useSelectionState((selectionState) => selectionState.isSelecting);
+  const visible = useOptionalSelector(SelectionToken, (lens) => lens.isHighlightVisible(), false);
+  const handles = useSelectionSettings((settings) => settings.handles);
+  const accent = useViewerSettings((settings) => settings.accent);
+  const endpoints = useOptionalSelector(
+    SelectionToken,
+    (lens) => selectionHandleEndpointsOf(lens.getSnapshot()),
+    null,
+    sameSelectionEndpoints,
+  );
+  // The handles are placed by projecting the endpoints through the camera, so they move whenever
+  // it does: the visible pages are the Stage's value for exactly that, the same one its pages
+  // move on, so handle and highlight move in one frame.
+  const camera = useKernelValue(() => stage.current?.listVisiblePages() ?? null);
+
+  const geometry = $derived.by((): Record<Role, SelectionHandleGeom | null> | null => {
+    void camera.current;
+    const lens = stage.current;
+    const ends = endpoints.current;
+    if (!lens || !ends) return null;
+    const view = selectionHandleViewOf(lens);
+    return {
+      start: selectionHandleGeom(view, ends.start, 'start'),
+      end: selectionHandleGeom(view, ends.end, 'end'),
+    };
+  });
+
+  // The handle being dragged: it keeps its handles shown while the selection is mid-gesture.
+  let dragging = $state<Role | null>(null);
+
+  /**
+   * Arm a drag at the press. It reads the stage and the endpoints as they are now, not as they
+   * were when the listener was attached.
+   */
+  function arm(role: Role) {
+    const lens = stage.current;
+    const ends = endpoints.current;
+    if (!lens || !ends) return null;
+    const armed = armSelectionHandle(host, selectionHandleViewOf(lens), ends, role);
+    if (!armed) return null;
+    dragging = role;
+    return {
+      // The point the user grabbed: the bar's midpoint.
+      base: armed.base,
+      session: {
+        move: armed.drag.move,
+        end: () => {
+          armed.drag.end(); // settles the selection: the menu shows again, onCommitted fires
+          dragging = null;
+        },
+      },
+    };
+  }
+
+  /** The handle's listeners, as an attachment: a native press listener, so the Stage never sees it. */
+  const bindHandle = (role: Role) => (element: HTMLElement) =>
+    attachSelectionHandle(element, { arm: () => arm(role) });
+
+  // Each is its CSS variable first, then the setting; an unset color is the accent.
+  const color = $derived(paint('text-selection-handle', handles.current.color ?? accent.current));
+  const shadow = $derived(paint('text-selection-handle-shadow', handles.current.shadow));
+
+  // Hidden while a pointer drag selects (like the menu), but a handle drag is itself a selection
+  // gesture, so it keeps its handles.
+  const shown = $derived(
+    stage.current !== null &&
+      endpoints.current !== null &&
+      visible.current &&
+      (!selecting.current || dragging !== null),
+  );
+</script>
+
+<!--
+  One handle, laid out upright in its own frame (a bar as long as the edge, the head above it at
+  the start or below it at the end), then turned onto the projected edge. The pivot is the bar's
+  ascent-side tip, the one point that must land exactly on the glyph's corner. Upright text
+  carries no transform.
+-->
+{#snippet handle(role: Role, at: SelectionHandleGeom)}
+  {@const barTop = HANDLE_PAD + (role === 'start' ? HANDLE_HEAD : 0)}
+  {@const pivotX = HANDLE_PAD + HANDLE_BAR / 2}
+  <div
+    {@attach bindHandle(role)}
+    style:position="absolute"
+    style:left="{at.bar.from.x - pivotX}px"
+    style:top="{at.bar.from.y - barTop}px"
+    style:width="{HANDLE_BAR + 2 * HANDLE_PAD}px"
+    style:height="{at.length + HANDLE_HEAD + 2 * HANDLE_PAD}px"
+    style:transform={at.upright ? undefined : `rotate(${at.rotation}deg)`}
+    style:transform-origin={at.upright ? undefined : `${pivotX}px ${barTop}px`}
+    style:touch-action="none"
+    style:cursor="grab"
+    style:pointer-events="auto"
+  >
+    <!-- The caret bar: the selection's own edge, as tall as the glyph's ink, at any tilt. -->
+    <div
+      style:position="absolute"
+      style:left="{HANDLE_PAD}px"
+      style:top="{barTop}px"
+      style:width="{HANDLE_BAR}px"
+      style:height="{at.length}px"
+      style:background={color}
+      style:border-radius="{HANDLE_BAR / 2}px"
+    ></div>
+    <!-- The head, against the bar: past the ascent at the start, past the baseline at the end,
+         in the text's frame. -->
+    <div
+      style:position="absolute"
+      style:left="{pivotX - HANDLE_HEAD / 2}px"
+      style:top="{role === 'start' ? HANDLE_PAD : HANDLE_PAD + at.length}px"
+      style:width="{HANDLE_HEAD}px"
+      style:height="{HANDLE_HEAD}px"
+      style:border-radius="50%"
+      style:background={color}
+      style:box-shadow={shadow}
+    ></div>
+  </div>
+{/snippet}
+
+{#if shown && geometry}
+  <!-- A handle whose page isn't laid out right now draws nothing. -->
+  {#if geometry.start}
+    {@render handle('start', geometry.start)}
+  {/if}
+  {#if geometry.end}
+    {@render handle('end', geometry.end)}
+  {/if}
+{/if}

package/dist/selection/SelectionHandles.svelte.d.ts

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

package/dist/selection/SelectionLayer.svelte

@@ -0,0 +1,67 @@
+<!--
+  The highlight of the selected text on one page. It only paints: it warms the page's text
+  geometry when it mounts, reads the page-space highlight from the plugin and maps each piece
+  through the page's transform, in the plugin's `color` setting, which the
+  `--epdf-text-selection` CSS variable wins over. Pointer input is `<PagePointerSource>`'s.
+
+  It reads the host lens (`/contract/host`: geometry warming, the highlight handshake), which
+  exists for exactly this; app code gets the public lens from `useSelection()`.
+-->
+<script lang="ts">
+  import { SelectionToken } from '@embedpdf/plugin-selection/contract/host';
+  import type { SelectionSegment } from '@embedpdf/plugin-selection';
+  import { mixAccent, paint, quadInPixels, svgPoints } from '@embedpdf/web';
+  import { useViewerSettings } from '../runtime/documents.svelte.js';
+  import { usePage } from '../runtime/page.js';
+  import {
+    shallowArray,
+    useOptionalCapability,
+    useOptionalSelector,
+  } from '../runtime/readers.svelte.js';
+  import { useSelectionSettings } from './readers.svelte.js';
+
+  const NO_SEGMENTS: readonly SelectionSegment[] = Object.freeze([]);
+
+  const page = usePage();
+  const selection = useOptionalCapability(SelectionToken);
+  const segments = useOptionalSelector(
+    SelectionToken,
+    (lens) => lens.listSegments(page.ref),
+    NO_SEGMENTS,
+    shallowArray,
+  );
+  // Code that draws its own selection (a markup tool's preview) can take the highlight over;
+  // then this draws nothing, so the two never overlap.
+  const visible = useOptionalSelector(SelectionToken, (lens) => lens.isHighlightVisible(), false);
+  // Settings need no document; without the selection plugin this throws now, with the fix.
+  const color = useSelectionSettings((settings) => settings.color);
+  // An unset color follows the viewer's accent, behind the `--epdf-accent` variable.
+  const accent = useViewerSettings((settings) => settings.accent);
+
+  // Warm this page's text geometry as soon as it's on screen, so the first press can hit-test
+  // without waiting for the engine. Nothing warms without the `doc.text.select` permission.
+  $effect(() => {
+    const lens = selection.current;
+    const ref = page.ref;
+    if (!lens) return;
+    void lens.ensureLoaded(ref);
+  });
+
+  // Unset, the color is the accent at 35%, the accent variables included.
+  const fill = $derived(
+    paint('text-selection', color.current ?? mixAccent('text-selection', accent.current)),
+  );
+</script>
+
+{#if visible.current}
+  <svg
+    style="position: absolute; inset: 0; width: 100%; height: 100%; overflow: visible; pointer-events: none"
+  >
+    {#each segments.current as segment, index (index)}
+      <!-- Page space to the page layer's pixels, which turn with the page: mapping the four
+           corners is exact, for turned text too. The fill is in `style`: an SVG attribute
+           doesn't read var(). -->
+      <polygon points={svgPoints(quadInPixels(segment.quad, page.transform))} style:fill />
+    {/each}
+  </svg>
+{/if}

package/dist/selection/SelectionLayer.svelte.d.ts

@@ -0,0 +1,3 @@
+declare const SelectionLayer: import("svelte").Component<Record<string, never>, {}, "">;
+type SelectionLayer = ReturnType<typeof SelectionLayer>;
+export default SelectionLayer;

package/dist/selection/SelectionMenu.svelte

@@ -0,0 +1,36 @@
+<!--
+  A menu over the text selection, once the selection settles. One anchor for the whole
+  selection, even across pages: it sits on the page the gesture ended on. Hidden while the user
+  is still dragging, it appears when the pointer lifts; a selection made from code shows it at
+  once. It works in a `<Stage>`'s overlay and in a `<PageView>` alike: the surface gives the
+  projection.
+
+  For UI that follows the selection during the drag, use `<Anchored>` with
+  `useSelection().getAnchor()` yourself: this component is that, plus the hiding.
+-->
+<script lang="ts">
+  import { SelectionToken } from '@embedpdf/plugin-selection';
+  import { samePageBounds } from '@embedpdf/web';
+  import Anchored from '../anchored/Anchored.svelte';
+  import { useOptionalSelector } from '../runtime/readers.svelte.js';
+  import type { SelectionMenuProps } from './props.js';
+  import { useSelectionState } from './readers.svelte.js';
+
+  let { children, gap = 8, placement = 'top' }: SelectionMenuProps = $props();
+
+  const selecting = useSelectionState((selectionState) => selectionState.isSelecting);
+  // Every read gives a new anchor: compared by page and box, so the menu moves only when the
+  // selection did.
+  const anchor = useOptionalSelector(
+    SelectionToken,
+    (selection) => selection.getAnchor(),
+    null,
+    samePageBounds,
+  );
+</script>
+
+{#if !selecting.current && anchor.current}
+  <Anchored anchor={anchor.current} {placement} {gap}>
+    {@render children()}
+  </Anchored>
+{/if}

package/dist/selection/SelectionMenu.svelte.d.ts

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

package/dist/selection/props.d.ts

@@ -0,0 +1,26 @@
+/** The props of the selection components. */
+import type { Snippet } from 'svelte';
+import type { AnchoredPlacement, SelectionClipboardOptions } from '@embedpdf/web';
+import type { MaybeGetter } from '../runtime/values.svelte.js';
+import type { StageTokenProp } from '../stage/stage-scope.js';
+export interface SelectionMenuProps {
+    /** The menu: buttons that call `useSelection()`, `copySelection()`, an annotation's markup. */
+    children: Snippet;
+    /** The gap in screen pixels between the selection and the menu. Default 8. */
+    gap?: number;
+    /** Where the menu sits next to the selection. Default `'top'`. */
+    placement?: AnchoredPlacement;
+}
+export interface SelectionHandlesProps {
+    /** The stage lens this overlay is on: the enclosing `<Stage>`'s by default. */
+    token?: StageTokenProp;
+}
+/** The props of `<SelectionClipboard>`. */
+export interface SelectionClipboardProps extends Pick<SelectionClipboardOptions, 'prefetch' | 'onRefused'> {
+    /**
+     * Copy only while focus is inside this element, for a page with more than one viewer. Pass a
+     * function (`() => area`, with `bind:this={area}`): copying works once the element has mounted.
+     * Default: anywhere on the page.
+     */
+    target?: MaybeGetter<HTMLElement | null | undefined>;
+}

package/dist/selection/props.js

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

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

@@ -0,0 +1,31 @@
+/**
+ * The selection plugin's readers: `useSelection()` (the API), `useSelectionState()`,
+ * `useSelectionSettings()` and `useSelectionEvent()`. App code gets the public lens; the layers
+ * in this folder read the host lens themselves.
+ */
+import type { EventHook } from '@embedpdf/core';
+import type { SelectionCapability } from '@embedpdf/plugin-selection';
+/**
+ * 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 declare function useSelection(): SelectionCapability;
+/**
+ * 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 declare const useSelectionState: import("../index.js").StateReader<{
+    hasSelection: boolean;
+    isSelecting: boolean;
+    range: import("@embedpdf/plugin-selection").TextRange | null;
+    pages: readonly import("@embedpdf/core").PageRef[];
+}>;
+/** The selection settings (`dragThreshold`, `color`, `handles`), with or without a document. */
+export declare const useSelectionSettings: import("../index.js").SettingsReader<import("@embedpdf/plugin-selection").SelectionSettings & object>;
+/**
+ * Subscribe to one selection event while the component lives:
+ * `useSelectionEvent((selection) => selection.onCommitted, handler)`.
+ */
+export declare function useSelectionEvent<T>(select: (selection: SelectionCapability) => EventHook<T>, handler: (event: T) => void): void;

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';