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

package/dist/annotation/StampGhost.svelte

@@ -0,0 +1,79 @@
+<!--
+  The armed stamp's ghost: a see-through picture of the stamp in the exact box a click would place
+  it (the plugin computes it with the same fit and clamp as placing it). Every other tool's ghost
+  rides the page items like a drawing in progress. The picture's bytes stay in the plugin; this
+  owns only the object URL, keyed on the armed stamp: a new arm swaps the picture, a disarm (or
+  another tool) drops it.
+-->
+<script lang="ts">
+  import { untrack } from 'svelte';
+  import {
+    AnnotationToken as AnnotationHostToken,
+    previewBucket,
+  } from '@embedpdf/plugin-annotation/contract/host';
+  import { ghostOpacity, loadObjectUrl, rectInPixels } from '@embedpdf/web';
+  import type { PageContextValue } from '../runtime/page.js';
+  import { useOptionalCapability, useOptionalSelector } from '../runtime/readers.svelte.js';
+
+  let { page }: { page: PageContextValue } = $props();
+
+  const capability = useOptionalCapability(AnnotationHostToken);
+  const ghost = useOptionalSelector(
+    AnnotationHostToken,
+    (annotation) => annotation.getImageGhost(page.ref),
+    null,
+  );
+  const armed = useOptionalSelector(
+    AnnotationHostToken,
+    (annotation) => annotation.getArmedStamp(),
+    null,
+  );
+  // The ghost is a picture of vector artwork, right at one size: ask for the bucket that covers
+  // the box's device width (points × device pixels per point), so it stays sharp at every zoom
+  // and density. The plugin keeps one picture per bucket.
+  const bucket = $derived(
+    ghost.current ? previewBucket(ghost.current.box.width * page.transform.renderScale) : 0,
+  );
+
+  let url = $state<string | null>(null);
+
+  $effect(() => {
+    const annotation = capability.current;
+    const size = bucket;
+    void armed.current;
+    if (!annotation || !size) {
+      url = null;
+      return;
+    }
+    // The previous bucket's picture stays up until this one arrives: no flicker while a zoom
+    // crosses a bucket boundary.
+    return untrack(() =>
+      loadObjectUrl(
+        () => annotation.renderArmedStampPreview(size),
+        (next) => (url = next),
+      ),
+    );
+  });
+
+  const frame = $derived(ghost.current ? rectInPixels(ghost.current.box, page.transform) : null);
+</script>
+
+{#if ghost.current && frame && url}
+  <!-- The same explicit size as a baked appearance: a global img reset must never clamp it. -->
+  <img
+    src={url}
+    alt=""
+    draggable="false"
+    style:position="absolute"
+    style:left="{frame.left}px"
+    style:top="{frame.top}px"
+    style:width="{frame.width}px"
+    style:height="{frame.height}px"
+    style:max-width="none"
+    style:max-height="none"
+    style:pointer-events="none"
+    style:opacity={ghostOpacity(ghost.current.opacity)}
+    style:transform={ghost.current.rot ? `rotate(${ghost.current.rot}deg)` : undefined}
+    style:transform-origin={ghost.current.rot ? 'center' : undefined}
+  />
+{/if}

package/dist/annotation/StampGhost.svelte.d.ts

@@ -0,0 +1,7 @@
+import type { PageContextValue } from '../runtime/page.js';
+type $$ComponentProps = {
+    page: PageContextValue;
+};
+declare const StampGhost: import("svelte").Component<$$ComponentProps, {}, "">;
+type StampGhost = ReturnType<typeof StampGhost>;
+export default StampGhost;

package/dist/annotation/chrome-paint.svelte.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The selection chrome's paint, following the annotation settings and the viewer's accent live:
+ * every color, width and dash as CSS text for a `style` attribute (`annotationChromePaint` from
+ * `@embedpdf/web` gives them as records, each its `--epdf-annotation-*` variable first).
+ */
+import type { ChromeSettings } from '@embedpdf/plugin-annotation';
+/** The painted chrome, as CSS text per part. */
+export interface ChromePaintCss {
+    /** The selection box. */
+    outline: string;
+    /** The resize and point handles. */
+    handle: string;
+    /** The rotation handle. */
+    rotationHandle: string;
+    /** The rotation handle's stalk: the handle's stroke. */
+    rotationStalk: string;
+    /** A snapped move's alignment guide. */
+    guide: string;
+    /** The reference cross and the angle line while turning. */
+    rotationGuide: string;
+    /** The box dragged to select. */
+    marquee: string;
+    /** The outline color of a text box while someone types in it. */
+    textOutline: string;
+}
+/** The chrome settings and their paint; call it while a component is created. */
+export declare function useChromePaint(): {
+    readonly chrome: ChromeSettings;
+    readonly css: ChromePaintCss;
+};

package/dist/annotation/chrome-paint.svelte.js

@@ -0,0 +1,27 @@
+import { annotationChromePaint, cssText } from '@embedpdf/web';
+import { useViewerSettings } from '../runtime/documents.svelte.js';
+import { useAnnotationSettings } from './state.js';
+const asCss = (painted) => ({
+    outline: cssText(painted.outline),
+    handle: cssText(painted.handle),
+    rotationHandle: cssText(painted.rotationHandle),
+    rotationStalk: cssText({ stroke: painted.rotationHandle.stroke }),
+    guide: cssText(painted.guide),
+    rotationGuide: cssText(painted.rotationGuide),
+    marquee: cssText(painted.marquee),
+    textOutline: painted.textOutline,
+});
+/** The chrome settings and their paint; call it while a component is created. */
+export function useChromePaint() {
+    const chrome = useAnnotationSettings((settings) => settings.chrome);
+    const accent = useViewerSettings((settings) => settings.accent);
+    const css = $derived(asCss(annotationChromePaint(chrome.current, accent.current)));
+    return {
+        get chrome() {
+            return chrome.current;
+        },
+        get css() {
+            return css;
+        },
+    };
+}

package/dist/annotation/props.d.ts

@@ -0,0 +1,181 @@
+/**
+ * The types an app writes against when it draws annotations its own way: a renderer (which
+ * annotations, with which component), the props that component gets, what the layer's `handle`
+ * and `rotationHandle` snippets get, the props of the layer and the menus, and what
+ * `useRichTextEditor()` and `useCommentThreads()` return.
+ */
+import type { Component, Snippet } from 'svelte';
+import type { Attachment } from 'svelte/attachments';
+import type { CreationDraftAnchor, Point, RenderItem, RotationAnchor } from '@embedpdf/core-annotation';
+import type { Annotation, CommentThread, HandleRole } from '@embedpdf/plugin-annotation';
+import type { AnchoredPlacement } from '@embedpdf/web';
+import type { PageContextValue } from '../runtime/page.js';
+/** The box a renderer draws into: the size to draw at, how it's turned, and how it's scaled. */
+export interface AnnotationFrame {
+    /** Its width in pixels at the annotation's 100% size, before its turn: draw at this. */
+    width: number;
+    /** Its height in pixels at the annotation's 100% size, before its turn: draw at this. */
+    height: number;
+    /**
+     * How it's turned on screen, degrees clockwise: the page's turn and the annotation's own. 0 is
+     * upright; turn your content by `-rotation` to keep it upright.
+     */
+    rotation: number;
+    /**
+     * How much the layer scales what you draw, with the page: the zoom, or for an annotation that
+     * keeps its size on screen, the zoom up to 1.
+     */
+    scale: number;
+}
+/**
+ * What a renderer's component gets as props: the annotation, the frame to draw into, and the
+ * layer's own drawing of it to keep or wrap. The layer keeps handling the pointer (select, move,
+ * resize) unless the renderer is `interactive`.
+ */
+export interface AnnotationRendererProps {
+    /** The annotation, as `get()` returns it. */
+    annotation: Annotation;
+    /**
+     * The box you draw into. The layer places, turns and scales it like the annotation's own
+     * drawing, also during a drag, a resize or a turn. Fill it (`width: 100%; height: 100%`) and
+     * draw at the annotation's 100% size: your text and borders scale with the page.
+     */
+    frame: AnnotationFrame;
+    /** The layer's own drawing of it, filling the frame: `{@render native()}` keeps the original look, to add to it. */
+    native: Snippet;
+    /** The engine's picture of the annotation as an image (`url`), or `null`. `native` draws it in place. */
+    appearance: {
+        url: string;
+    } | null;
+    /** True while the pointer is over it. */
+    hovered: boolean;
+    /** True while it's selected. */
+    selected: boolean;
+    /** True when what you draw takes the pointer (see `interactive` on the renderer). */
+    interactive: boolean;
+}
+/**
+ * What a sibling plugin's renderer gets for the annotations its behavior owns (the form plugin's
+ * fill controls). It places its own controls: `item` is the layer's projection of the annotation
+ * (its box, style, text and raster box, in page coordinates), and `page.transform.toPixels()`
+ * turns those into the layer's pixels.
+ */
+export interface BehaviorRendererProps {
+    annotation: Annotation;
+    item: RenderItem;
+    page: PageContextValue;
+    /** The layer's own drawing of it, in its frame where the layer draws it: `{@render native()}`. */
+    native: Snippet;
+    hovered: boolean;
+    selected: boolean;
+    interactive: boolean;
+}
+/** What an `interactive` function is asked: the annotation, and the active tool. */
+export interface AnnotationInteractiveContext {
+    annotation: Annotation;
+    toolId: string;
+}
+/**
+ * One rule: "draw these annotations with this component". `for` gets the annotation with all its
+ * fields; the first renderer that matches wins. Without `interactive` the component only draws:
+ * the layer keeps handling the pointer. With `interactive` (or a function asked whenever it
+ * matters) the component takes the pointer, and the annotation can't be selected or moved while
+ * it does.
+ *
+ * Define the list once, in `<script>`: the layer registers each entry, and a list written inline
+ * in the markup is a new one whenever the markup runs again.
+ *
+ * `{ behavior, component }` draws what a sibling plugin's behavior owns (the form plugin's fill
+ * controls); the plugin decides when it's engaged.
+ */
+export type AnnotationRenderer = {
+    behavior: string;
+    component: Component<BehaviorRendererProps>;
+} | {
+    /** A stable id for the registration (optional; generated). */
+    id?: string;
+    for: (annotation: Annotation) => boolean;
+    component: Component<AnnotationRendererProps>;
+    interactive?: boolean | ((context: AnnotationInteractiveContext) => boolean);
+    /**
+     * Scale what you draw with the page (the default): you draw at the annotation's 100% size.
+     * `false`: you draw at its size on screen, and size things yourself from `frame.scale`.
+     */
+    scale?: boolean;
+};
+/** What the layer's `handle` snippet gets: one handle to draw. */
+export interface HandleProps {
+    /** The handle's center, in pixels on the page. */
+    at: Point;
+    /** The `size` from the settings, px. */
+    size: number;
+    /** The selection's rotation (degrees clockwise), so a square handle can turn with it. */
+    rotation: number;
+    /** A box's `'corner'` or `'side'`, or one `'point'` of a line or a polygon. */
+    kind: HandleRole;
+    /** True while it's being dragged. */
+    active: boolean;
+}
+/** What the layer's `rotationHandle` snippet gets: a handle's props, and where its stalk starts on the box. */
+export interface RotationHandleProps extends Omit<HandleProps, 'kind'> {
+    /** Where the stalk starts on the box, in pixels on the page. */
+    from: Point;
+}
+export interface AnnotationLayerProps {
+    /** Your own look for some annotations ({@link AnnotationRenderer}). Define the list once, in `<script>`. */
+    renderers?: AnnotationRenderer[];
+    /** Draw each handle yourself, in place of the layer's. The viewer still decides where it can be grabbed. */
+    handle?: Snippet<[handle: HandleProps]>;
+    /** Draw the rotation handle yourself, in place of the layer's. */
+    rotationHandle?: Snippet<[handle: RotationHandleProps]>;
+}
+/** What `useRichTextEditor()` gives the element you draw a text box with. */
+export interface RichTextEditor {
+    /** Put it on your element (`{@attach editor.attach}`): it becomes the editor. Render nothing inside it. */
+    readonly attach: Attachment<HTMLElement>;
+    /** The box's body style as CSS (`style={editor.style}`): font, size, color and alignment. While typing it takes the pointer too. */
+    readonly style: string;
+    /** True while someone types in the box. */
+    readonly editing: boolean;
+}
+/**
+ * A {@link CommentThread} with where its page is shown now. Identity stays `page` (like every
+ * annotation surface); these two fields are presentation, following page moves and deletes.
+ */
+export interface CommentThreadView extends CommentThread {
+    /** Current 0-based display index of the thread's page; `-1` when the page is no longer in the document (for the one update before it goes). */
+    pageIndex: number;
+    /** The page's `/PageLabels` label when the PDF declares one ("iv", "A-2"), else the 1-based position as a string: print it as it is. */
+    pageLabel: string;
+}
+export interface AnnotationMenuProps {
+    /** The menu: buttons that call `useAnnotation()`, built from `useAnnotationState()`. */
+    children: Snippet;
+    /** The gap in screen pixels between the selection box and the menu. Default 15. */
+    gap?: number;
+    /** Where the menu sits next to the selection box. Default `'top'`. */
+    placement?: AnchoredPlacement;
+}
+export interface AnnotationDraftMenuProps {
+    /**
+     * The menu, given the shape being drawn (`subtype`, `pointCount`, `minPoints`, `canFinish`, …).
+     * The verbs are capability calls: `useAnnotation().draft.finish()` and `.draft.cancel()`.
+     */
+    children: Snippet<[draft: CreationDraftAnchor]>;
+    /** The gap in screen pixels between the shape being drawn and the menu. Default 8. */
+    gap?: number;
+    /** Where the menu sits next to the shape being drawn. Default `'top'`. */
+    placement?: AnchoredPlacement;
+}
+export interface AnnotationRotationBadgeProps {
+    /**
+     * The badge, given the rotation in progress (`angle`, degrees clockwise, as the commit will
+     * apply it). Without it, the badge shows the angle in the `chrome.readout` colors, when
+     * `chrome.readout.enabled`.
+     */
+    children?: Snippet<[rotation: RotationAnchor]>;
+    /** The gap in screen pixels between the pointer and the badge. Default 16. */
+    gap?: number;
+    /** Where the badge sits next to the pointer. Default `'right'`. */
+    placement?: AnchoredPlacement;
+}

package/dist/annotation/props.js

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

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

@@ -0,0 +1,59 @@
+import type { EventHook } from '@embedpdf/core';
+import { type Annotation, type AnnotationAnchor, type AnnotationCapability, type AnnotationFilter, type AnnotationProperties, type AnnotationRef, type CommentsApi, type FilePickerProvider, type ToolDefaults } from '@embedpdf/plugin-annotation';
+import { type CurrentValue, type MaybeGetter } from '../runtime/values.svelte.js';
+import type { CommentThreadView } from './props.js';
+/** The API: a handle, always the capability of the document in scope. */
+export declare function useAnnotation(): AnnotationCapability;
+/** Listen to one annotation event while the component lives: `useAnnotationEvent((annotation) => annotation.onCreated, handler)`. */
+export declare function useAnnotationEvent<T>(select: (annotation: AnnotationCapability) => EventHook<T>, handler: (event: T) => void): void;
+/**
+ * The annotations matching `filter` (some pages, one kind), in drawing order, as the user sees
+ * them: `list.current`, the same array while they stay the same. Empty without a document.
+ */
+export declare function useAnnotationList(filter?: MaybeGetter<AnnotationFilter | undefined>): CurrentValue<readonly Annotation[]>;
+/**
+ * A tool's defaults (`defaults.current`): the fields its next annotation starts with, over the
+ * engine's. It updates when they change, so a color picker always shows the current color. Empty
+ * without a document.
+ */
+export declare function useAnnotationDefaults(toolId: MaybeGetter<string>): CurrentValue<ToolDefaults>;
+/**
+ * What a style panel shows (`panel.current`): the selection's properties
+ * (`selection.getProperties()`), or, given a tool id, the tool's (`tools.getProperties(id)`). It
+ * updates when they change. Empty without a document.
+ */
+export declare function useAnnotationProperties(toolId?: MaybeGetter<string | undefined>): CurrentValue<AnnotationProperties>;
+/**
+ * An anchor for `<Anchored>` that keeps a card or a badge attached to one annotation
+ * (`anchor.current`): its page and the box around what it shows, following a move as it happens.
+ * `null` for `null`, or an annotation that isn't here. It updates when the annotation moves, not
+ * while people scroll or zoom: a note that keeps its size on screen hands `<Anchored>` its
+ * `boundsIn`.
+ */
+export declare function useAnnotationAnchor(ref: MaybeGetter<AnnotationRef | null>): CurrentValue<AnnotationAnchor | null>;
+/** The comments API: the `comments` part of `useAnnotation()`. Pair it with {@link useCommentThreads} for the threads to show. */
+export declare function useComments(): CommentsApi;
+/**
+ * Every comment thread in the document (`threads.current`), in display order (page position, top
+ * of page, creation date), each with its page's `pageIndex` and `pageLabel`. Annotation writes
+ * (your own, remote ones, the first load) and page moves or deletes update it; the same array
+ * between changes.
+ */
+export declare function useCommentThreads(): CurrentValue<CommentThreadView[]>;
+/** The thread holding any of its annotations (the comment, a reply, a state), or `null`: `thread.current`. */
+export declare function useCommentThread(ref: MaybeGetter<AnnotationRef | null>): CurrentValue<CommentThreadView | null>;
+/**
+ * The default file-picker provider: the browser's file dialog (from `@embedpdf/web`), honouring
+ * the tool's `accept` filter. The adapter fulfils the plugin's DOM-free port; the dialog lives
+ * here, never in the plugin.
+ */
+export declare const filePickerProvider: FilePickerProvider;
+/**
+ * Install the file-picker provider for the document in scope: the one port behind every
+ * click-then-pick tool (a stamp's `'prompt'` source, the file-attachment tool). Call it once, in a
+ * component around the pages (not in a page layer). Without an argument it installs
+ * {@link filePickerProvider}, so those tools work out of the box; pass your own provider (an
+ * asset library, a cloud drive: switch on `request.subtype` / `request.toolId`), or `null` to
+ * make them do nothing. Removed when the component goes away. The provider is read once.
+ */
+export declare function useFilePickerProvider(provider?: FilePickerProvider | null): void;

package/dist/annotation/readers.svelte.js

@@ -0,0 +1,136 @@
+/**
+ * The annotation plugin's readers: the API (`useAnnotation()`), its events, and the reads a
+ * component follows on their own, each `{ current }`: the annotations of a filter, a tool's
+ * defaults, a style panel's properties, an annotation's anchor, and the comment threads.
+ * `useFilePickerProvider()` installs the file dialog behind click-then-pick tools.
+ *
+ * An argument that changes is a function (`useAnnotationAnchor(() => note.ref)`), read again
+ * whenever the value is.
+ */
+import { untrack } from 'svelte';
+import { AnnotationToken, annotationKey, } from '@embedpdf/plugin-annotation';
+// The anchor of one annotation is a host read (the same runtime token, typed wider).
+import { AnnotationToken as AnnotationHostToken } from '@embedpdf/plugin-annotation/contract/host';
+import { enrichCommentThreads, installFilePickerProvider, pickRequestedFile, sameAnnotationAnchor, } from '@embedpdf/web';
+import { devWarn } from '../runtime/dev.js';
+import { shallowArray, useCapability, useCapabilityEvent, useDocumentId, useKernelValue, useOptionalCapability, useOptionalSelector, } from '../runtime/readers.svelte.js';
+import { currentOf, derivedValue, valueOf, } from '../runtime/values.svelte.js';
+/** The API: a handle, always the capability of the document in scope. */
+export function useAnnotation() {
+    return useCapability(AnnotationToken);
+}
+/** Listen to one annotation event while the component lives: `useAnnotationEvent((annotation) => annotation.onCreated, handler)`. */
+export function useAnnotationEvent(select, handler) {
+    useCapabilityEvent(AnnotationToken, select, handler);
+}
+const NO_ANNOTATIONS = Object.freeze([]);
+/**
+ * The annotations matching `filter` (some pages, one kind), in drawing order, as the user sees
+ * them: `list.current`, the same array while they stay the same. Empty without a document.
+ */
+export function useAnnotationList(filter) {
+    return useOptionalSelector(AnnotationToken, (annotation) => annotation.list(valueOf(filter)), NO_ANNOTATIONS, shallowArray);
+}
+const NO_DEFAULTS = Object.freeze({});
+/**
+ * A tool's defaults (`defaults.current`): the fields its next annotation starts with, over the
+ * engine's. It updates when they change, so a color picker always shows the current color. Empty
+ * without a document.
+ */
+export function useAnnotationDefaults(toolId) {
+    return useOptionalSelector(AnnotationToken, (annotation) => annotation.tools.getDefaults(valueOf(toolId)), NO_DEFAULTS);
+}
+const NO_PROPERTIES = Object.freeze({
+    properties: [],
+    values: {},
+    mixed: [],
+});
+/**
+ * What a style panel shows (`panel.current`): the selection's properties
+ * (`selection.getProperties()`), or, given a tool id, the tool's (`tools.getProperties(id)`). It
+ * updates when they change. Empty without a document.
+ */
+export function useAnnotationProperties(toolId) {
+    return useOptionalSelector(AnnotationToken, (annotation) => {
+        const tool = valueOf(toolId);
+        return tool === undefined
+            ? annotation.selection.getProperties()
+            : annotation.tools.getProperties(tool);
+    }, NO_PROPERTIES);
+}
+/**
+ * An anchor for `<Anchored>` that keeps a card or a badge attached to one annotation
+ * (`anchor.current`): its page and the box around what it shows, following a move as it happens.
+ * `null` for `null`, or an annotation that isn't here. It updates when the annotation moves, not
+ * while people scroll or zoom: a note that keeps its size on screen hands `<Anchored>` its
+ * `boundsIn`.
+ */
+export function useAnnotationAnchor(ref) {
+    return useOptionalSelector(AnnotationHostToken, (annotation) => {
+        const target = valueOf(ref);
+        return target ? annotation.getAnnotationAnchor(target) : null;
+    }, null, sameAnnotationAnchor);
+}
+// ── comments ─────────────────────────────────────────────────────────────────
+/** The comments API: the `comments` part of `useAnnotation()`. Pair it with {@link useCommentThreads} for the threads to show. */
+export function useComments() {
+    return useCapability(AnnotationToken).comments;
+}
+const NO_PAGES = Object.freeze([]);
+const NO_THREADS = Object.freeze([]);
+/**
+ * Every comment thread in the document (`threads.current`), in display order (page position, top
+ * of page, creation date), each with its page's `pageIndex` and `pageLabel`. Annotation writes
+ * (your own, remote ones, the first load) and page moves or deletes update it; the same array
+ * between changes.
+ */
+export function useCommentThreads() {
+    const documentId = useDocumentId();
+    const threads = useOptionalSelector(AnnotationToken, (annotation) => annotation.comments.listThreads(), NO_THREADS);
+    const pages = useKernelValue((kernel) => documentId.current ? kernel.documents.listPages(documentId.current) : NO_PAGES);
+    return currentOf(derivedValue(() => enrichCommentThreads(threads.current, pages.current)));
+}
+/** The thread holding any of its annotations (the comment, a reply, a state), or `null`: `thread.current`. */
+export function useCommentThread(ref) {
+    const views = useCommentThreads();
+    const capability = useOptionalCapability(AnnotationToken);
+    return currentOf(derivedValue(() => {
+        // Read first: every annotation write gives new threads, so this runs again.
+        const shown = views.current;
+        const target = valueOf(ref);
+        const annotation = capability.current;
+        if (target == null || !annotation)
+            return null;
+        const thread = annotation.comments.getThread(target);
+        if (!thread)
+            return null;
+        const root = annotationKey(thread.root.ref);
+        return shown.find((view) => annotationKey(view.root.ref) === root) ?? null;
+    }));
+}
+// ── the file picker ──────────────────────────────────────────────────────────
+/**
+ * The default file-picker provider: the browser's file dialog (from `@embedpdf/web`), honouring
+ * the tool's `accept` filter. The adapter fulfils the plugin's DOM-free port; the dialog lives
+ * here, never in the plugin.
+ */
+export const filePickerProvider = pickRequestedFile;
+/**
+ * Install the file-picker provider for the document in scope: the one port behind every
+ * click-then-pick tool (a stamp's `'prompt'` source, the file-attachment tool). Call it once, in a
+ * component around the pages (not in a page layer). Without an argument it installs
+ * {@link filePickerProvider}, so those tools work out of the box; pass your own provider (an
+ * asset library, a cloud drive: switch on `request.subtype` / `request.toolId`), or `null` to
+ * make them do nothing. Removed when the component goes away. The provider is read once.
+ */
+export function useFilePickerProvider(provider = filePickerProvider) {
+    const capability = useOptionalCapability(AnnotationToken);
+    $effect(() => {
+        const annotation = capability.current;
+        if (!annotation)
+            return;
+        // One port per document: a second caller silently replaces the first.
+        return untrack(() => installFilePickerProvider(annotation, provider, () => devWarn('file-picker-provider-twice', 'useFilePickerProvider() is called from two mounted components for the same document — ' +
+            'the later one wins. Call it once, in a component around the pages.')));
+    });
+}

package/dist/annotation/state.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The annotation state: `status` (`'loading'` until every annotation is in, then `'ready'`), the
+ * `selected` annotations, the one `hovered` under the pointer and the text box being typed in
+ * (`editing`). A reactive object (`state.selected`), each field updating on its own; with a
+ * selector, the value it picks as `{ current }`. Empty without a document.
+ */
+export declare const useAnnotationState: import("../index.js").StateReader<{
+    status: import("@embedpdf/core").ResourceStatus;
+    selected: readonly import("@embedpdf/plugin-annotation").Annotation[];
+    hovered: import("@embedpdf/plugin-annotation").Annotation | null;
+    editing: import("@embedpdf/plugin-annotation").Annotation | null;
+}>;
+/**
+ * The annotation settings (`snap`, `chrome`, `afterCreate`, `tools`), or the value `select` picks
+ * as `{ current }`. They belong to the plugin, so they read without a document; change them with
+ * `useAnnotation().updateSettings()`.
+ */
+export declare const useAnnotationSettings: import("../index.js").SettingsReader<import("@embedpdf/plugin-annotation").AnnotationSettings & object>;

package/dist/annotation/state.js

@@ -0,0 +1,20 @@
+/**
+ * The annotation readers other feature entries use too (the form plugin reads the selection),
+ * kept apart so they don't import the whole annotation entry: the state and the settings, each
+ * from its declaration.
+ */
+import { AnnotationToken, annotationState } from '@embedpdf/plugin-annotation/contract';
+import { settingsReader, stateReader } from '../runtime/state.svelte.js';
+/**
+ * The annotation state: `status` (`'loading'` until every annotation is in, then `'ready'`), the
+ * `selected` annotations, the one `hovered` under the pointer and the text box being typed in
+ * (`editing`). A reactive object (`state.selected`), each field updating on its own; with a
+ * selector, the value it picks as `{ current }`. Empty without a document.
+ */
+export const useAnnotationState = stateReader(annotationState);
+/**
+ * The annotation settings (`snap`, `chrome`, `afterCreate`, `tools`), or the value `select` picks
+ * as `{ current }`. They belong to the plugin, so they read without a document; change them with
+ * `useAnnotation().updateSettings()`.
+ */
+export const useAnnotationSettings = settingsReader(AnnotationToken);

package/dist/annotation/text-box.svelte.d.ts

@@ -0,0 +1,28 @@
+import type { Attachment } from 'svelte/attachments';
+import type { Annotation, TextItem } from '@embedpdf/plugin-annotation';
+import { type MaybeGetter } from '../runtime/values.svelte.js';
+import type { RichTextEditor } from './props.js';
+/**
+ * An attachment that makes its element the editor of the text box `item()` gives, at `scale()`
+ * pixels per point. Call it while a component is created. The element must stay empty in the
+ * markup: the editor owns what's inside it.
+ */
+export declare function textBoxEditor(item: () => TextItem | null, scale: () => number): Attachment<HTMLElement>;
+/** For the layer, around a look it scales: how much it scales what the look draws. */
+export declare function setLookScale(scale: () => number): void;
+/**
+ * Make your own element the editor of a text box you draw yourself (a renderer for free text):
+ * it draws the runs, turns typing back into runs, keeps the caret when the style changes, and
+ * handles pasting, input methods and the format shortcuts. The formatting calls
+ * (`text.toggleFormat`, `selection.update`) work on it as they do on the layer's own.
+ *
+ * ```svelte
+ * const editor = useRichTextEditor(() => annotation);
+ * <div {@attach editor.attach} class={['box', editor.editing && 'editing']} style={editor.style}></div>
+ * ```
+ *
+ * `attach` goes on your element (render nothing inside it: the editor owns what's in it); `style`
+ * and `editing` follow the box. `style` fills the element's parent at a legible size: draw the
+ * box's frame on the parent.
+ */
+export declare function useRichTextEditor(annotation: MaybeGetter<Annotation>): RichTextEditor;