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

package/dist/form/readers.svelte.js

@@ -0,0 +1,52 @@
+import { FormToken, formState } from '@embedpdf/plugin-form';
+import { formColorsOf } from '@embedpdf/web';
+import { useViewerSettings } from '../runtime/documents.svelte.js';
+import { useCapability, useCapabilityEvent, useOptionalSelector, } from '../runtime/readers.svelte.js';
+import { settingsReader, stateReader } from '../runtime/state.svelte.js';
+import { currentOf, derivedValue, valueOf, } from '../runtime/values.svelte.js';
+/**
+ * The form API for the document in scope: reading, filling, form data and building. A handle:
+ * always the capability of the document in scope, so keep it whole (`form.setValue(…)`).
+ */
+export function useForm() {
+    return useCapability(FormToken);
+}
+/**
+ * Subscribe to one form event while the component lives:
+ * `useFormEvent((form) => form.onValueChanged, handler)`.
+ */
+export function useFormEvent(select, handler) {
+    useCapabilityEvent(FormToken, select, handler);
+}
+/**
+ * The form's state: every field (`fields`), whether it's read (`status`), what kind of form the
+ * document has (`formKind`), and the field of the selected widget (`selectedField`), declared
+ * once in `formState`. A reactive object (`state.fields`), or with a selector one value as
+ * `{ current }` that changes only when what it picks changes. Empty without a document.
+ */
+export const useFormState = stateReader(formState);
+/**
+ * The form settings (`validation`, `focus`, `fields`), with or without a document. They belong
+ * to the plugin; change them with `useForm().updateSettings()`.
+ */
+export const useFormSettings = settingsReader(FormToken);
+/**
+ * One field's value, in the shape `setValue()` takes, or `null`, as `{ current }`: it changes
+ * only when that field's value changes. Pass a function (`() => ref`) for a field that changes.
+ * `null` without a document.
+ */
+export function useFormValue(ref) {
+    // The plugin keeps one value object per field until the field changes, so a reference
+    // comparison is enough.
+    return useOptionalSelector(FormToken, (form) => form.getValue(valueOf(ref)), null);
+}
+/**
+ * The colors the layer draws fields with: the form settings over the viewer's accent, each a
+ * `var(--epdf-form-*)` first, so CSS wins.
+ */
+export function useFormColors() {
+    const accent = useViewerSettings((settings) => settings.accent);
+    const focus = useFormSettings((settings) => settings.focus);
+    const fields = useFormSettings((settings) => settings.fields);
+    return currentOf(derivedValue(() => formColorsOf({ focus: focus.current, fields: fields.current }, accent.current)));
+}

package/dist/form/widget.d.ts

@@ -0,0 +1,16 @@
+/**
+ * What every control of `<FormLayer>` shares besides its box (`WidgetBox.svelte`): running the
+ * widget's action on a click, and the style of a control that fills the box, as CSS text. A
+ * Svelte `style` attribute is a string, while `@embedpdf/web` hands styles out as records
+ * (`cssText` writes one as text).
+ */
+import type { FormWidgetItem } from '@embedpdf/plugin-form';
+/**
+ * A click on a widget runs its `/A` action. ISO 32000 puts the activate action on the widget,
+ * whatever its field, and many forms ship "buttons" as read-only text fields with an `/A` that
+ * Acrobat runs; a widget without one is inert. The widget's address is read at the click: the
+ * engine gives a widget it has just placed its address later.
+ */
+export declare function useWidgetActivation(annotationRef: () => FormWidgetItem['annotationRef']): () => void;
+/** Fills the box it sits in, as CSS text. */
+export declare const FILL: string;

package/dist/form/widget.js

@@ -0,0 +1,20 @@
+// The layer's lens on the plugin: the same capability, typed wider for the framework layers.
+import { FormToken as FormHostToken } from '@embedpdf/plugin-form/contract/host';
+import { cssText, FORM_CONTROL_FILL } from '@embedpdf/web';
+import { useCapability } from '../runtime/readers.svelte.js';
+/**
+ * A click on a widget runs its `/A` action. ISO 32000 puts the activate action on the widget,
+ * whatever its field, and many forms ship "buttons" as read-only text fields with an `/A` that
+ * Acrobat runs; a widget without one is inert. The widget's address is read at the click: the
+ * engine gives a widget it has just placed its address later.
+ */
+export function useWidgetActivation(annotationRef) {
+    const form = useCapability(FormHostToken);
+    return () => {
+        const target = annotationRef();
+        if (target)
+            void form.activateWidget(target);
+    };
+}
+/** Fills the box it sits in, as CSS text. */
+export const FILL = cssText(FORM_CONTROL_FILL);

package/dist/form.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @embedpdf/svelte/form — filling and building forms.
+ *
+ * `<FormLayer>` puts a real HTML control over each field of its page, for people to fill in;
+ * `useForm()` reads, fills and builds the form from code; `useFormState()` follows the fields as
+ * a reactive object, `useFormValue()` one field's value as `{ current }`, `useFormSettings()` the
+ * settings, and `useFormEvent()` the plugin's events.
+ */
+export * from '@embedpdf/plugin-form';
+export { default as FormLayer } from './form/FormLayer.svelte';
+export { useForm, useFormEvent, useFormSettings, useFormState, useFormValue, } from './form/readers.svelte.js';

package/dist/form.js

@@ -0,0 +1,12 @@
+/**
+ * @embedpdf/svelte/form — filling and building forms.
+ *
+ * `<FormLayer>` puts a real HTML control over each field of its page, for people to fill in;
+ * `useForm()` reads, fills and builds the form from code; `useFormState()` follows the fields as
+ * a reactive object, `useFormValue()` one field's value as `{ current }`, `useFormSettings()` the
+ * settings, and `useFormEvent()` the plugin's events.
+ */
+// Registration travels with the UI.
+export * from '@embedpdf/plugin-form';
+export { default as FormLayer } from './form/FormLayer.svelte';
+export { useForm, useFormEvent, useFormSettings, useFormState, useFormValue, } from './form/readers.svelte.js';

package/dist/history/readers.d.ts

@@ -0,0 +1,22 @@
+/** The history's readers: the API, the state declared once in `historyState`, and its events. */
+import type { EventHook } from '@embedpdf/core';
+import type { HistoryCapability } from '@embedpdf/plugin-history';
+/**
+ * The history API (`undo`, `redo`, `canUndo`, `canRedo`, the labels, `clear`) of the nearest
+ * `<DocumentScope>`'s document, else the active one. Outside a ready document, every method
+ * throws `not-ready`. `canUndo()` is a read, so `disabled={!history.canUndo()}` updates by itself.
+ */
+export declare function useHistory(): HistoryCapability;
+/**
+ * Whether undo and redo can run, and what they would undo and redo (the page's State table,
+ * declared once in `historyState`), as a reactive object: `state.canUndo`. With a selector, the
+ * value it picks as `{ current }`, which changes only when that value does.
+ */
+export declare const useHistoryState: import("../index.js").StateReader<{
+    canUndo: boolean;
+    canRedo: boolean;
+    undoLabel: import("@embedpdf/core").ChangeLabel | null;
+    redoLabel: import("@embedpdf/core").ChangeLabel | null;
+}>;
+/** Subscribe to one history event while the component lives: `useHistoryEvent((history) => history.onUndone, handler)`. */
+export declare function useHistoryEvent<T>(select: (history: HistoryCapability) => EventHook<T>, handler: (event: T) => void): void;

package/dist/history/readers.js

@@ -0,0 +1,21 @@
+import { HistoryToken, historyState } from '@embedpdf/plugin-history';
+import { useCapability, useCapabilityEvent } from '../runtime/readers.svelte.js';
+import { stateReader } from '../runtime/state.svelte.js';
+/**
+ * The history API (`undo`, `redo`, `canUndo`, `canRedo`, the labels, `clear`) of the nearest
+ * `<DocumentScope>`'s document, else the active one. Outside a ready document, every method
+ * throws `not-ready`. `canUndo()` is a read, so `disabled={!history.canUndo()}` updates by itself.
+ */
+export function useHistory() {
+    return useCapability(HistoryToken);
+}
+/**
+ * Whether undo and redo can run, and what they would undo and redo (the page's State table,
+ * declared once in `historyState`), as a reactive object: `state.canUndo`. With a selector, the
+ * value it picks as `{ current }`, which changes only when that value does.
+ */
+export const useHistoryState = stateReader(historyState);
+/** Subscribe to one history event while the component lives: `useHistoryEvent((history) => history.onUndone, handler)`. */
+export function useHistoryEvent(select, handler) {
+    useCapabilityEvent(HistoryToken, select, handler);
+}

package/dist/history.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @embedpdf/svelte/history — undo and redo of what you change through the viewer, one history
+ * per open document. An action shows undone at once, even while it is still on its way:
+ *
+ *   const history = useHistory();
+ *   const state = useHistoryState(); // state.canUndo, state.undoLabel, …
+ *   <button disabled={!state.canUndo} onclick={() => history.undo()}>Undo</button>
+ */
+export * from '@embedpdf/plugin-history';
+export { useHistory, useHistoryEvent, useHistoryState } from './history/readers.js';

package/dist/history.js

@@ -0,0 +1,11 @@
+/**
+ * @embedpdf/svelte/history — undo and redo of what you change through the viewer, one history
+ * per open document. An action shows undone at once, even while it is still on its way:
+ *
+ *   const history = useHistory();
+ *   const state = useHistoryState(); // state.canUndo, state.undoLabel, …
+ *   <button disabled={!state.canUndo} onclick={() => history.undo()}>Undo</button>
+ */
+// Registration travels with the UI.
+export * from '@embedpdf/plugin-history';
+export { useHistory, useHistoryEvent, useHistoryState } from './history/readers.js';

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

@@ -0,0 +1,32 @@
+/**
+ * The i18n plugin's readers. The plugin belongs to the workspace and needs no engine, so they
+ * work from the first frame, before a document opens: a loading screen and a password prompt
+ * translate too.
+ */
+import type { EventHook } from '@embedpdf/core';
+import type { I18nCapability, TranslateOptions } from '@embedpdf/plugin-i18n';
+/** The i18n API: `t`, `setLocale`, `addTranslations`, `registerLocale`, the settings calls. */
+export declare function useI18n(): I18nCapability;
+/** Subscribe to one i18n event while the component lives: `useI18nEvent((i18n) => i18n.onLocaleChanged, handler)`. */
+export declare function useI18nEvent<T>(select: (i18n: I18nCapability) => EventHook<T>, handler: (event: T) => void): void;
+/**
+ * The current language, how it reads, every language you can switch to, and the one loading
+ * (declared once in `i18nState`), as a reactive object (`useI18nState().direction`). Takes a
+ * selector.
+ */
+export declare const useI18nState: import("../index.js").StateReader<{
+    locale: string;
+    direction: import("@embedpdf/plugin-i18n").TextDirection;
+    locales: readonly import("@embedpdf/plugin-i18n").LocaleInfo[];
+    loading: string | null;
+}>;
+/** The i18n settings (`locale`, `fallbackLocale`, `locales`, `loaders`). Takes a selector. */
+export declare const useI18nSettings: import("../index.js").SettingsReader<import("@embedpdf/plugin-i18n").I18nSettings & object>;
+/**
+ * A translate function that reads the current language each time it's called, so a template, a
+ * `$derived` or an effect that calls it updates when the language or the strings change:
+ *
+ *   const t = useT();
+ *   <span>{t('search.results', { params: { count } })}</span>
+ */
+export declare function useT(): (key: string, options?: TranslateOptions) => string;

package/dist/i18n/readers.svelte.js

@@ -0,0 +1,30 @@
+import { I18nToken, i18nState } from '@embedpdf/plugin-i18n';
+import { useCapability, useCapabilityEvent, useSelector } from '../runtime/readers.svelte.js';
+import { settingsReader, stateReader } from '../runtime/state.svelte.js';
+/** The i18n API: `t`, `setLocale`, `addTranslations`, `registerLocale`, the settings calls. */
+export function useI18n() {
+    return useCapability(I18nToken);
+}
+/** Subscribe to one i18n event while the component lives: `useI18nEvent((i18n) => i18n.onLocaleChanged, handler)`. */
+export function useI18nEvent(select, handler) {
+    useCapabilityEvent(I18nToken, select, handler);
+}
+/**
+ * The current language, how it reads, every language you can switch to, and the one loading
+ * (declared once in `i18nState`), as a reactive object (`useI18nState().direction`). Takes a
+ * selector.
+ */
+export const useI18nState = stateReader(i18nState);
+/** The i18n settings (`locale`, `fallbackLocale`, `locales`, `loaders`). Takes a selector. */
+export const useI18nSettings = settingsReader(I18nToken);
+/**
+ * A translate function that reads the current language each time it's called, so a template, a
+ * `$derived` or an effect that calls it updates when the language or the strings change:
+ *
+ *   const t = useT();
+ *   <span>{t('search.results', { params: { count } })}</span>
+ */
+export function useT() {
+    const translator = useSelector(I18nToken, (i18n) => i18n.getTranslator());
+    return (key, options) => translator.current(key, options);
+}

package/dist/i18n.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @embedpdf/svelte/i18n — your viewer in the reader's language.
+ *
+ * The readers are the i18n plugin's API, state, settings and events; `useT()` gives a translate
+ * function that follows the language.
+ */
+export * from '@embedpdf/plugin-i18n';
+export { useI18n, useI18nEvent, useI18nSettings, useI18nState, useT } from './i18n/readers.svelte.js';

package/dist/i18n.js

@@ -0,0 +1,9 @@
+/**
+ * @embedpdf/svelte/i18n — your viewer in the reader's language.
+ *
+ * The readers are the i18n plugin's API, state, settings and events; `useT()` gives a translate
+ * function that follows the language.
+ */
+// Registration travels with the UI.
+export * from '@embedpdf/plugin-i18n';
+export { useI18n, useI18nEvent, useI18nSettings, useI18nState, useT } from './i18n/readers.svelte.js';

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @embedpdf/svelte — every entry point at once. Apps import per feature
+ * (`@embedpdf/svelte/stage`), so a plugin they don't use stays out of the bundle.
+ */
+export * from './runtime.js';
+export * from './anchored.js';
+export * from './stage.js';
+export * from './render.js';
+export * from './interaction.js';
+export * from './commands.js';
+export * from './toolbar.js';
+export * from './shell.js';
+export * from './i18n.js';
+export * from './page-view.js';
+export * from './selection.js';
+export * from './search.js';
+export * from './link.js';
+export * from './actions.js';
+export * from './view-manager.js';
+export * from './page-edit.js';
+export * from './metadata.js';
+export * from './history.js';
+export * from './annotation.js';
+export * from './redaction.js';
+export * from './measurement.js';
+export * from './stamp.js';
+export * from './form.js';
+export * from './signature.js';

package/dist/index.js

@@ -0,0 +1,28 @@
+/**
+ * @embedpdf/svelte — every entry point at once. Apps import per feature
+ * (`@embedpdf/svelte/stage`), so a plugin they don't use stays out of the bundle.
+ */
+export * from './runtime.js';
+export * from './anchored.js';
+export * from './stage.js';
+export * from './render.js';
+export * from './interaction.js';
+export * from './commands.js';
+export * from './toolbar.js';
+export * from './shell.js';
+export * from './i18n.js';
+export * from './page-view.js';
+export * from './selection.js';
+export * from './search.js';
+export * from './link.js';
+export * from './actions.js';
+export * from './view-manager.js';
+export * from './page-edit.js';
+export * from './metadata.js';
+export * from './history.js';
+export * from './annotation.js';
+export * from './redaction.js';
+export * from './measurement.js';
+export * from './stamp.js';
+export * from './form.js';
+export * from './signature.js';

package/dist/interaction/PagePointerSource.svelte

@@ -0,0 +1,37 @@
+<!--
+  The one pointer listener per page: it turns pointer events into page points through the page
+  context and hands them to the interaction plugin. It binds only to the page context, so it
+  works the same on a Stage page and on a `<PageView>`. Features never listen to the pointer
+  themselves: they register handlers with the interaction plugin, and a tool of your own brings
+  its pointer methods (`registerTool`).
+-->
+<script lang="ts">
+  import { untrack } from 'svelte';
+  import { InteractionToken } from '@embedpdf/plugin-interaction/contract/host';
+  import { attachPagePointer } from '@embedpdf/web';
+  import { usePage } from '../runtime/page.js';
+  import { useOptionalCapability, useOptionalSelector } from '../runtime/readers.svelte.js';
+
+  const page = usePage();
+  // The pointer source is a host of the interaction plugin: it dispatches samples.
+  const interaction = useOptionalCapability(InteractionToken);
+  const cursor = useOptionalSelector(InteractionToken, (hub) => hub.getCursor(), 'default');
+
+  let element: HTMLDivElement | undefined;
+
+  // The listener is `@embedpdf/web`'s, shared with every framework. It reads the page when an
+  // event arrives: a zoom changes it, and a drag carries on through it.
+  $effect(() => {
+    const hub = interaction.current;
+    const target = element;
+    if (!hub || !target) return;
+    return untrack(() => attachPagePointer(target, hub, () => page));
+  });
+</script>
+
+<!-- On top, as the page's event surface; the drawing layers below take no pointer events. -->
+<div
+  bind:this={element}
+  style="position: absolute; inset: 0; touch-action: none"
+  style:cursor={cursor.current}
+></div>

package/dist/interaction/PagePointerSource.svelte.d.ts

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

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

@@ -0,0 +1,26 @@
+import type { EventHook } from '@embedpdf/core';
+import type { InteractionCapability } from '@embedpdf/plugin-interaction';
+import { type ToolCursorSpec } from '@embedpdf/web';
+import { type MaybeGetter } from '../runtime/values.svelte.js';
+/** The interaction API: switch tools, add your own, set their cursors. */
+export declare function useInteraction(): InteractionCapability;
+/** Subscribe to one interaction event while the component lives: `useInteractionEvent((interaction) => interaction.onToolChanged, handler)`. */
+export declare function useInteractionEvent<T>(select: (interaction: InteractionCapability) => EventHook<T>, handler: (event: T) => void): void;
+/**
+ * The tools' state: the active tool's id and every tool you can switch to (declared once in
+ * `interactionState`). Without a document there is no active tool (`null`) and no tool.
+ */
+export declare const useInteractionState: import("../index.js").StateReader<{
+    activeToolId: import("@embedpdf/plugin-interaction").ToolId | null;
+    tools: readonly import("@embedpdf/plugin-interaction").Tool[];
+}>;
+/** The interaction settings (`defaultTool`, `tools`), with or without a document. */
+export declare const useInteractionSettings: import("../index.js").SettingsReader<import("@embedpdf/plugin-interaction").InteractionSettings & object>;
+/**
+ * Give a tool image cursors: the armed-tool indicator. The interaction plugin already decides
+ * which cursor shows (hover claims over annotations and text win, page gaps show the tool's
+ * `gapCursor`), so nothing chases the pointer in the DOM. Pass a function, so the cursor follows
+ * what it reads (a color); `null` installs nothing. Going away restores the tool's own cursors.
+ * Without a document it installs nothing until one is ready.
+ */
+export declare function useToolCursor(spec: MaybeGetter<ToolCursorSpec | null>): void;

package/dist/interaction/readers.svelte.js

@@ -0,0 +1,47 @@
+/** The interaction plugin's readers: its API, state, settings and events, and tool cursors. */
+import { untrack } from 'svelte';
+import { InteractionToken, interactionState } from '@embedpdf/plugin-interaction';
+import { InteractionToken as InteractionHostToken } from '@embedpdf/plugin-interaction/contract/host';
+import { toolCursorsOf } from '@embedpdf/web';
+import { useCapability, useCapabilityEvent, useOptionalCapability, } from '../runtime/readers.svelte.js';
+import { settingsReader, stateReader } from '../runtime/state.svelte.js';
+import { valueOf } from '../runtime/values.svelte.js';
+/** The interaction API: switch tools, add your own, set their cursors. */
+export function useInteraction() {
+    return useCapability(InteractionToken);
+}
+/** Subscribe to one interaction event while the component lives: `useInteractionEvent((interaction) => interaction.onToolChanged, handler)`. */
+export function useInteractionEvent(select, handler) {
+    useCapabilityEvent(InteractionToken, select, handler);
+}
+/**
+ * The tools' state: the active tool's id and every tool you can switch to (declared once in
+ * `interactionState`). Without a document there is no active tool (`null`) and no tool.
+ */
+export const useInteractionState = stateReader(interactionState);
+/** The interaction settings (`defaultTool`, `tools`), with or without a document. */
+export const useInteractionSettings = settingsReader(InteractionToken);
+/**
+ * Give a tool image cursors: the armed-tool indicator. The interaction plugin already decides
+ * which cursor shows (hover claims over annotations and text win, page gaps show the tool's
+ * `gapCursor`), so nothing chases the pointer in the DOM. Pass a function, so the cursor follows
+ * what it reads (a color); `null` installs nothing. Going away restores the tool's own cursors.
+ * Without a document it installs nothing until one is ready.
+ */
+export function useToolCursor(spec) {
+    const interaction = useOptionalCapability(InteractionHostToken);
+    // By value: a function builds a fresh object every time, and an identical one must not
+    // replace the cursor.
+    const key = $derived.by(() => {
+        const current = valueOf(spec);
+        return current ? JSON.stringify(current) : null;
+    });
+    $effect(() => {
+        const host = interaction.current;
+        if (!host || key === null)
+            return;
+        const cursorSpec = untrack(() => valueOf(spec));
+        untrack(() => host.setToolCursor(cursorSpec.toolId, toolCursorsOf(cursorSpec.cursors)));
+        return () => host.setToolCursor(cursorSpec.toolId, null);
+    });
+}

package/dist/interaction.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @embedpdf/svelte/interaction — pointer input and tools.
+ *
+ * `<PagePointerSource>` is the one pointer listener per page; the readers are the interaction
+ * plugin's API, state, settings and events, and `useToolCursor()` gives a tool its cursors.
+ */
+export * from '@embedpdf/plugin-interaction';
+export { createClickCounter, svgCursor, vibrationFeedback, wkFeedback } from '@embedpdf/web';
+export type { SvgCursorOptions, ToolCursorImage, ToolCursorSpec } from '@embedpdf/web';
+export { default as PagePointerSource } from './interaction/PagePointerSource.svelte';
+export { useInteraction, useInteractionEvent, useInteractionSettings, useInteractionState, useToolCursor, } from './interaction/readers.svelte.js';

package/dist/interaction.js

@@ -0,0 +1,13 @@
+/**
+ * @embedpdf/svelte/interaction — pointer input and tools.
+ *
+ * `<PagePointerSource>` is the one pointer listener per page; the readers are the interaction
+ * plugin's API, state, settings and events, and `useToolCursor()` gives a tool its cursors.
+ */
+// Registration travels with the UI.
+export * from '@embedpdf/plugin-interaction';
+// The browser helpers live in @embedpdf/web (the plugin has no DOM); they're here too, so app
+// code has one import for the feature.
+export { createClickCounter, svgCursor, vibrationFeedback, wkFeedback } from '@embedpdf/web';
+export { default as PagePointerSource } from './interaction/PagePointerSource.svelte';
+export { useInteraction, useInteractionEvent, useInteractionSettings, useInteractionState, useToolCursor, } from './interaction/readers.svelte.js';

package/dist/link/LinkLayer.svelte

@@ -0,0 +1,164 @@
+<!--
+  The links on one page: one absolutely placed `<a>` per clickable area. Real anchors on purpose:
+  a website gets an `href`, so a middle click, "copy link", the status-bar preview and keyboard
+  focus work as in any page. A click or a key follows the link through the plugin's `activate()`,
+  so every way of following one fires `onActivated`; the plugin opens websites through the opener
+  this binding registers.
+
+  The layer stands down while the active tool doesn't enable `link-nav`: the annotation layer
+  owns links then (select, move, resize). While a tool can edit annotations, a link attached to
+  another annotation is that annotation's, and its anchor stands down too.
+-->
+<script lang="ts">
+  import { ActionsToken, createHoverPump } from '@embedpdf/plugin-actions/contract';
+  import { InteractionToken } from '@embedpdf/plugin-interaction/contract/host';
+  import { LinkToken, type Link } from '@embedpdf/plugin-link';
+  import { LinkToken as LinkHostToken } from '@embedpdf/plugin-link/contract/host';
+  import {
+    hoverLink,
+    isModifiedClick,
+    isolatePointerDown,
+    linkActivateContextOf,
+    linkAnchorOf,
+    navigableLinksOf,
+    sendLinkEvent,
+    type LinkAnchorEvent,
+  } from '@embedpdf/web';
+  import { usePage } from '../runtime/page.js';
+  import {
+    shallowArray,
+    useCapability,
+    useOptionalCapability,
+    useOptionalSelector,
+  } from '../runtime/readers.svelte.js';
+  import { stageTokenOf } from '../stage/stage-scope.js';
+  import type { LinkLayerProps } from './props.js';
+  import { useUriOpener } from './readers.svelte.js';
+
+  const NO_LINKS: readonly Link[] = Object.freeze([]);
+
+  let { link: drawLink }: LinkLayerProps = $props();
+
+  const page = usePage();
+  // The API for following a link (a handle: always this document's), and the plugin's own object
+  // for the reads here, which then wake nothing but a new document.
+  const links = useCapability(LinkToken);
+  const capability = useOptionalCapability(LinkToken);
+  useUriOpener();
+  // A page destination moves the view this page is shown in.
+  const stage = useOptionalCapability(stageTokenOf());
+  // The links' own /AA events (enter, exit, down, up, focus, blur) can only fire from here: while
+  // a link navigates, its pixels are these anchors. One hover pump per layer; crossing layers
+  // still orders Exit before Enter, since both sides submit in DOM event order.
+  const actions = useOptionalCapability(ActionsToken);
+  const pump = $derived(actions.current ? createHoverPump(actions.current.dispatch) : null);
+
+  const items = useOptionalSelector(
+    LinkToken,
+    (lens) => lens.listLinks(page.ref),
+    NO_LINKS,
+    shallowArray,
+  );
+  const engaged = useOptionalSelector(LinkHostToken, (lens) => lens.isNavigationEngaged(), false);
+  // One owner per pixel: while the active tool can edit annotations, a link attached to another
+  // annotation belongs to it, and its anchor stands down. Standalone links navigate under any
+  // tool that enables `link-nav`.
+  const editEnabled = useOptionalSelector(
+    InteractionToken,
+    (interaction) => interaction.activeToolEnables('annotation-edit'),
+    false,
+  );
+  const visible = $derived(
+    engaged.current && items.current.length > 0
+      ? navigableLinksOf(items.current, editEnabled.current)
+      : NO_LINKS,
+  );
+
+  $effect(() => {
+    const lens = capability.current;
+    const ref = page.ref;
+    if (!lens) return;
+    void lens.ensureLoaded(ref);
+  });
+
+  /** Follow `item` through the plugin, which moves the view or opens a website. */
+  function follow(item: Link) {
+    links.activate(item, linkActivateContextOf(item, page.ref, stage.current));
+  }
+
+  /** The link's own /AA event for a press, a release or focus, with the actions plugin. */
+  function notify(item: Link, event: LinkAnchorEvent) {
+    sendLinkEvent(actions.current, item, page.ref, event);
+  }
+
+  function onClick(href: string | null, item: Link, event: MouseEvent) {
+    // A modified click on a real `href` keeps the browser's own behavior (a background tab, a
+    // new window). Every other click follows the link through the plugin.
+    if (href && isModifiedClick(event)) return;
+    event.preventDefault();
+    follow(item);
+  }
+
+  function onKeyDown(item: Link, event: KeyboardEvent) {
+    if (event.key !== 'Enter' && event.key !== ' ') return;
+    event.preventDefault();
+    follow(item);
+  }
+
+  /**
+   * A press inside a link must not reach the Stage (it would start the active tool's gesture, or
+   * end an edit as a click outside). Svelte hands `onpointerdown` to the root, after the Stage
+   * saw the press, so the press stops on a native listener on the anchor, which also sends the
+   * link's "mouse down" action.
+   */
+  const isolate = (item: () => Link) => (element: HTMLElement) =>
+    isolatePointerDown(element, () => notify(item(), 'mouseDown'));
+</script>
+
+{#if visible.length > 0}
+  <div style="position: absolute; inset: 0; pointer-events: none">
+    {#each visible as item (item.id)}
+      {@const { box, href, label } = linkAnchorOf(
+        item,
+        page.transform,
+        (link) => capability.current?.getLabel(link) ?? '',
+      )}
+      <!-- Its box, its label, and a native `href` only for a website with nothing chained after
+           it. -->
+      <!-- The layer's own anchor; a `link` snippet draws around it. -->
+      {#snippet native()}
+        <!-- `role` stays: an anchor without `href` (a page destination) has no role of its own. -->
+        <!-- svelte-ignore a11y_no_redundant_roles -->
+        <a
+          {@attach isolate(() => item)}
+          href={href ?? undefined}
+          target="_blank"
+          rel="noopener noreferrer"
+          role="link"
+          tabindex="0"
+          title={label}
+          aria-label={label}
+          onclick={(event) => onClick(href, item, event)}
+          onkeydown={(event) => onKeyDown(item, event)}
+          onpointerenter={() => hoverLink(pump, item, page.ref)}
+          onpointerleave={() => pump?.hover(null)}
+          onpointerup={() => notify(item, 'mouseUp')}
+          onfocus={() => notify(item, 'focus')}
+          onblur={() => notify(item, 'blur')}
+          style:position="absolute"
+          style:left="{box.left}px"
+          style:top="{box.top}px"
+          style:width="{box.width}px"
+          style:height="{box.height}px"
+          style:cursor="pointer"
+          style:pointer-events="auto"
+        ></a>
+      {/snippet}
+      {#if drawLink}
+        {@render drawLink({ link: item, native })}
+      {:else}
+        {@render native()}
+      {/if}
+    {/each}
+  </div>
+{/if}

package/dist/link/LinkLayer.svelte.d.ts

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