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

package/dist/annotation/text-box.svelte.js

@@ -0,0 +1,94 @@
+/**
+ * Text boxes you type in. `@embedpdf/web`'s text box editor makes an element the editor of a free
+ * text box (rich text, focus and `contentEditable` following the plugin's `editing`, presses kept
+ * inside the box), and its follower attaches when the element and the capability are there and
+ * takes the box and the scale whenever they change; this binds the follower to Svelte as an
+ * attachment. The layer's own text boxes use it, and so does `useRichTextEditor()`, for a renderer
+ * that draws its text box itself.
+ */
+import { getContext, hasContext, setContext, untrack } from 'svelte';
+import { annotationKey } from '@embedpdf/core';
+// Typing reaches the plugin through its host lens (drafts, the text selection).
+import { AnnotationToken as AnnotationHostToken } from '@embedpdf/plugin-annotation/contract/host';
+import { createTextBoxEditorFollower, cssText, textBoxEditorScaleOf, textBoxStyleOf, } from '@embedpdf/web';
+import { usePage } from '../runtime/page.js';
+import { useOptionalCapability, useOptionalSelector } from '../runtime/readers.svelte.js';
+import { valueOf } from '../runtime/values.svelte.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 function textBoxEditor(item, scale) {
+    const capability = useOptionalCapability(AnnotationHostToken);
+    return (element) => {
+        const follower = createTextBoxEditorFollower();
+        // Another document attaches again; every change of the box or the scale reaches the editor,
+        // which redraws only when the text differs, so the caret never jumps while typing; focus
+        // follows `editing`.
+        $effect(() => {
+            const annotation = capability.current;
+            const current = item();
+            const pixelsPerPoint = scale();
+            untrack(() => follower.follow(element, annotation, current, pixelsPerPoint));
+        });
+        return () => follower.detach();
+    };
+}
+const LOOK_SCALE = Symbol('embedpdf.annotation-look-scale');
+/** For the layer, around a look it scales: how much it scales what the look draws. */
+export function setLookScale(scale) {
+    setContext(LOOK_SCALE, scale);
+}
+/** How much the layer scales the look around this component: 1 outside a look, or in one drawn at its size on screen. */
+function lookScaleOf() {
+    return hasContext(LOOK_SCALE) ? getContext(LOOK_SCALE) : () => 1;
+}
+/**
+ * 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.
+ */
+export function useRichTextEditor(annotation) {
+    const page = usePage();
+    const lookScale = lookScaleOf();
+    const item = useOptionalSelector(AnnotationHostToken, (host) => {
+        const key = annotationKey(valueOf(annotation).ref);
+        const { transform } = page;
+        return (host
+            .listTextItems(page.ref, { zoom: transform.zoom, rotation: transform.rotation })
+            .find((text) => text.ref !== null && annotationKey(text.ref) === key) ?? null);
+    }, null);
+    // Pixels per point where the element is: inside a scaled look, at the annotation's 100% size;
+    // the look's scale does the rest.
+    const scale = $derived(textBoxEditorScaleOf(item.current, page.transform, lookScale()));
+    // While typing, the element takes the pointer (the caret, a drag over words).
+    const style = $derived.by(() => {
+        const text = item.current;
+        if (!text)
+            return '';
+        return cssText({
+            ...textBoxStyleOf(text.css, scale),
+            ...(text.editing ? { pointerEvents: 'auto' } : {}),
+        });
+    });
+    const attach = textBoxEditor(() => item.current, () => scale);
+    return {
+        attach,
+        get style() {
+            return style;
+        },
+        get editing() {
+            return item.current?.editing ?? false;
+        },
+    };
+}

package/dist/annotation.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @embedpdf/svelte/annotation — the Svelte view of `@embedpdf/plugin-annotation`.
+ *
+ * `<AnnotationLayer>` draws a page's annotations, the selection's handles, the tool's preview and
+ * the text boxes being typed in, with `renderers` for your own looks and `handle` /
+ * `rotationHandle` snippets for your own handles. `<AnnotationMenu>`, `<AnnotationDraftMenu>` and
+ * `<AnnotationRotationBadge>` float your UI over the selection, a shape being drawn and a turn in
+ * progress.
+ *
+ * The readers follow every plugin's four: `useAnnotation()` (the API), `useAnnotationState()`
+ * (status, selected, hovered, editing), `useAnnotationEvent()` and `useAnnotationSettings()`; the
+ * reads a component follows on their own are `{ current }`: `useAnnotationList()`,
+ * `useAnnotationDefaults()`, `useAnnotationProperties()`, `useAnnotationAnchor()`, and the
+ * comments' `useCommentThreads()` and `useCommentThread()`. `useRichTextEditor()` makes your
+ * element a text box's editor (an attachment), and `useFilePickerProvider()` installs the file
+ * dialog behind click-then-pick tools.
+ *
+ * What isn't Svelte lives in `@embedpdf/web`, the same for every framework: the scene as SVG
+ * elements, the chrome's paint and pixels, the text box editor, which drawing each annotation gets
+ * and the behaviors renderers register, and the object URLs of baked appearances and the stamp
+ * ghost.
+ */
+export * from '@embedpdf/plugin-annotation';
+export type { CreationDraftAnchor, RenderItem, LineEnding, LineEndings, Style, AnnotationFlags, FieldValues, TextAlign, TextStyle, } from '@embedpdf/core-annotation';
+export { default as AnnotationLayer } from './annotation/AnnotationLayer.svelte';
+export { default as AnnotationMenu } from './annotation/AnnotationMenu.svelte';
+export { default as AnnotationDraftMenu } from './annotation/AnnotationDraftMenu.svelte';
+export { default as AnnotationRotationBadge } from './annotation/AnnotationRotationBadge.svelte';
+export type { AnnotationDraftMenuProps, AnnotationFrame, AnnotationInteractiveContext, AnnotationLayerProps, AnnotationMenuProps, AnnotationRenderer, AnnotationRendererProps, AnnotationRotationBadgeProps, BehaviorRendererProps, CommentThreadView, HandleProps, RichTextEditor, RotationHandleProps, } from './annotation/props.js';
+export { useAnnotationSettings, useAnnotationState } from './annotation/state.js';
+export { filePickerProvider, useAnnotation, useAnnotationAnchor, useAnnotationDefaults, useAnnotationEvent, useAnnotationList, useAnnotationProperties, useCommentThread, useCommentThreads, useComments, useFilePickerProvider, } from './annotation/readers.svelte.js';
+export { useRichTextEditor } from './annotation/text-box.svelte.js';

package/dist/annotation.js

@@ -0,0 +1,31 @@
+/**
+ * @embedpdf/svelte/annotation — the Svelte view of `@embedpdf/plugin-annotation`.
+ *
+ * `<AnnotationLayer>` draws a page's annotations, the selection's handles, the tool's preview and
+ * the text boxes being typed in, with `renderers` for your own looks and `handle` /
+ * `rotationHandle` snippets for your own handles. `<AnnotationMenu>`, `<AnnotationDraftMenu>` and
+ * `<AnnotationRotationBadge>` float your UI over the selection, a shape being drawn and a turn in
+ * progress.
+ *
+ * The readers follow every plugin's four: `useAnnotation()` (the API), `useAnnotationState()`
+ * (status, selected, hovered, editing), `useAnnotationEvent()` and `useAnnotationSettings()`; the
+ * reads a component follows on their own are `{ current }`: `useAnnotationList()`,
+ * `useAnnotationDefaults()`, `useAnnotationProperties()`, `useAnnotationAnchor()`, and the
+ * comments' `useCommentThreads()` and `useCommentThread()`. `useRichTextEditor()` makes your
+ * element a text box's editor (an attachment), and `useFilePickerProvider()` installs the file
+ * dialog behind click-then-pick tools.
+ *
+ * What isn't Svelte lives in `@embedpdf/web`, the same for every framework: the scene as SVG
+ * elements, the chrome's paint and pixels, the text box editor, which drawing each annotation gets
+ * and the behaviors renderers register, and the object URLs of baked appearances and the stamp
+ * ghost.
+ */
+// Registration travels with the UI.
+export * from '@embedpdf/plugin-annotation';
+export { default as AnnotationLayer } from './annotation/AnnotationLayer.svelte';
+export { default as AnnotationMenu } from './annotation/AnnotationMenu.svelte';
+export { default as AnnotationDraftMenu } from './annotation/AnnotationDraftMenu.svelte';
+export { default as AnnotationRotationBadge } from './annotation/AnnotationRotationBadge.svelte';
+export { useAnnotationSettings, useAnnotationState } from './annotation/state.js';
+export { filePickerProvider, useAnnotation, useAnnotationAnchor, useAnnotationDefaults, useAnnotationEvent, useAnnotationList, useAnnotationProperties, useCommentThread, useCommentThreads, useComments, useFilePickerProvider, } from './annotation/readers.svelte.js';
+export { useRichTextEditor } from './annotation/text-box.svelte.js';

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

@@ -0,0 +1,50 @@
+import type { EventHook } from '@embedpdf/core';
+import type { BoundCommand, CommandId, CommandRefusal, CommandsCapability } from '@embedpdf/plugin-commands';
+import { type CurrentValue, type MaybeGetter } from '../runtime/values.svelte.js';
+/**
+ * The commands every viewer has: zoom, pages, view rotation, `tool:<id>` for every tool, copy,
+ * delete, download and print, with shortcuts and labels in EmbedPDF's eight languages. Spread
+ * them into `commandsPlugin({ commands })`.
+ */
+export declare const standardCommands: readonly (import("@embedpdf/plugin-commands").CommandDef | import("@embedpdf/plugin-commands").CommandFamily)[];
+/** The commands API: `execute`, `searchCommands`, `registerCommand`, the categories, the settings calls. */
+export declare function useCommands(): CommandsCapability;
+/** Subscribe to one commands event while the component lives: `useCommandsEvent((commands) => commands.onExecuted, handler)`. */
+export declare function useCommandsEvent<T>(select: (commands: CommandsCapability) => EventHook<T>, handler: (event: T) => void): void;
+/**
+ * The commands settings (`commands`, `disabledCategories`, `disabledCommands`, `notAllowed`),
+ * with or without a document. Takes a selector.
+ */
+export declare const useCommandsSettings: import("../index.js").SettingsReader<import("@embedpdf/plugin-commands").CommandsSettings & object>;
+/** A shortcut as a tooltip shows it, for this platform: `'⌘K'` on a Mac, `'Ctrl+K'` elsewhere. */
+export declare function formatShortcut(shortcut: string, options?: {
+    isMac?: boolean;
+}): string;
+/**
+ * A command for this component's document (the nearest `<DocumentScope>`, else the active one),
+ * as `{ current }`: its label, icon, state, `run` and `shortcut`. Pass the id as a function to
+ * follow a prop: `useCommand(() => id)`. `current` changes only when what the command shows
+ * does. Always a command: an id no plugin registered is labelled with its id, neither visible
+ * nor enabled, and warns once in development.
+ */
+export declare function useCommand(id: MaybeGetter<string>): CurrentValue<BoundCommand>;
+/** Where {@link useCommandShortcuts} listens, and how it reads `Mod`. */
+export interface CommandShortcutsOptions {
+    /** Whether `Mod` is Cmd (a Mac) or Ctrl. Default: what the browser says. */
+    isMac?: MaybeGetter<boolean | undefined>;
+    /**
+     * Listen only while focus is inside this element, for a page with more than one viewer. Pass a
+     * function (`() => area`, with `bind:this={area}`): the keys work once the element has mounted.
+     */
+    target?: MaybeGetter<HTMLElement | null | undefined>;
+    /** Called when a key's command is turned off or not allowed, with why: say so to the user. */
+    onRefused?: (commandId: CommandId, refusal: CommandRefusal) => void;
+}
+/**
+ * Turn every command's shortcut into a working key, for the active document. Call it once, near
+ * the top of your viewer. Keys typed into text fields are left alone, and so is a key whose
+ * command can't run right now. A command that's turned off or not allowed still takes its key,
+ * and `onRefused` says why. The keys work anywhere on the page; with `target`, only while focus
+ * is inside that element. They stop when the component goes away.
+ */
+export declare function useCommandShortcuts(options?: CommandShortcutsOptions): void;

package/dist/commands/readers.svelte.js

@@ -0,0 +1,83 @@
+/**
+ * The commands plugin's readers: its API, settings and events, a command as a button needs it,
+ * and keyboard shortcuts. A command's state is derived from live state on read, so `useCommand`
+ * reads it again after every kernel change and passes it on only when what it shows changed.
+ */
+import { untrack } from 'svelte';
+import { formatShortcut as formatKeys } from '@embedpdf/core-ui';
+import { CommandsToken, boundCommandOf, resolvedCommandsEqual, unknownCommandWarning, unregisteredCommand, } from '@embedpdf/plugin-commands';
+import { CommandsToken as CommandsHostToken } from '@embedpdf/plugin-commands/contract/host';
+import { createStandardCommands } from '@embedpdf/plugin-commands/standard';
+import { bindCommandShortcuts, isMacPlatform, standardCommandsBrowser } from '@embedpdf/web';
+import { useCapability, useCapabilityEvent, useDocumentId, useKernelValue, } from '../runtime/readers.svelte.js';
+import { devWarn } from '../runtime/dev.js';
+import { settingsReader } from '../runtime/state.svelte.js';
+import { currentOf, derivedValue, valueOf, } from '../runtime/values.svelte.js';
+/**
+ * The commands every viewer has: zoom, pages, view rotation, `tool:<id>` for every tool, copy,
+ * delete, download and print, with shortcuts and labels in EmbedPDF's eight languages. Spread
+ * them into `commandsPlugin({ commands })`.
+ */
+export const standardCommands = /* @__PURE__ */ createStandardCommands(standardCommandsBrowser);
+/** The commands API: `execute`, `searchCommands`, `registerCommand`, the categories, the settings calls. */
+export function useCommands() {
+    return useCapability(CommandsToken);
+}
+/** Subscribe to one commands event while the component lives: `useCommandsEvent((commands) => commands.onExecuted, handler)`. */
+export function useCommandsEvent(select, handler) {
+    useCapabilityEvent(CommandsToken, select, handler);
+}
+/**
+ * The commands settings (`commands`, `disabledCategories`, `disabledCommands`, `notAllowed`),
+ * with or without a document. Takes a selector.
+ */
+export const useCommandsSettings = settingsReader(CommandsToken);
+/** A shortcut as a tooltip shows it, for this platform: `'⌘K'` on a Mac, `'Ctrl+K'` elsewhere. */
+export function formatShortcut(shortcut, options = {}) {
+    return formatKeys(shortcut, { isMac: options.isMac ?? isMacPlatform() });
+}
+/**
+ * A command for this component's document (the nearest `<DocumentScope>`, else the active one),
+ * as `{ current }`: its label, icon, state, `run` and `shortcut`. Pass the id as a function to
+ * follow a prop: `useCommand(() => id)`. `current` changes only when what the command shows
+ * does. Always a command: an id no plugin registered is labelled with its id, neither visible
+ * nor enabled, and warns once in development.
+ */
+export function useCommand(id) {
+    const commands = useCapability(CommandsToken);
+    const documentId = useDocumentId();
+    const resolved = useKernelValue(() => commands.resolveCommand(valueOf(id), documentId.current ?? undefined), resolvedCommandsEqual);
+    // A new object only when the resolved command or the document changes.
+    return currentOf(derivedValue(() => {
+        const command = resolved.current;
+        const requested = valueOf(id);
+        if (command === null) {
+            devWarn(`useCommand:${requested}`, `useCommand(): ${unknownCommandWarning(requested, commands.listCommandIds())}`);
+        }
+        const scope = documentId.current ?? undefined;
+        return boundCommandOf(command ?? unregisteredCommand(requested), (commandId) => commands.execute(commandId, { documentId: scope }), { isMac: isMacPlatform() });
+    }));
+}
+/**
+ * Turn every command's shortcut into a working key, for the active document. Call it once, near
+ * the top of your viewer. Keys typed into text fields are left alone, and so is a key whose
+ * command can't run right now. A command that's turned off or not allowed still takes its key,
+ * and `onRefused` says why. The keys work anywhere on the page; with `target`, only while focus
+ * is inside that element. They stop when the component goes away.
+ */
+export function useCommandShortcuts(options = {}) {
+    const commands = useCapability(CommandsHostToken);
+    const scoped = options.target !== undefined;
+    $effect(() => {
+        const isMac = valueOf(options.isMac);
+        const target = valueOf(options.target);
+        // A target that hasn't mounted yet binds nothing; this runs again once it has.
+        if (scoped && !target)
+            return;
+        return untrack(() => bindCommandShortcuts(commands, {
+            isMac,
+            target: target ?? undefined,
+            onRefused: (commandId, refusal) => options.onRefused?.(commandId, refusal),
+        }));
+    });
+}

package/dist/commands.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @embedpdf/svelte/commands — commands as buttons, shortcuts and a palette.
+ *
+ * The readers are the commands plugin's API, settings and events; `useCommand()` gives a command
+ * with everything a button needs, and `useCommandShortcuts()` turns every shortcut into a key.
+ */
+export * from '@embedpdf/plugin-commands';
+export { formatShortcut, standardCommands, useCommand, useCommandShortcuts, useCommands, useCommandsEvent, useCommandsSettings, } from './commands/readers.svelte.js';
+export type { CommandShortcutsOptions } from './commands/readers.svelte.js';

package/dist/commands.js

@@ -0,0 +1,9 @@
+/**
+ * @embedpdf/svelte/commands — commands as buttons, shortcuts and a palette.
+ *
+ * The readers are the commands plugin's API, settings and events; `useCommand()` gives a command
+ * with everything a button needs, and `useCommandShortcuts()` turns every shortcut into a key.
+ */
+// Registration travels with the UI.
+export * from '@embedpdf/plugin-commands';
+export { formatShortcut, standardCommands, useCommand, useCommandShortcuts, useCommands, useCommandsEvent, useCommandsSettings, } from './commands/readers.svelte.js';

package/dist/form/ButtonControl.svelte

@@ -0,0 +1,38 @@
+<!--
+  A push button: a transparent native `<button>` over the field's picture that runs the widget's
+  action. It never has an edge: the picture is the button.
+-->
+<script lang="ts">
+  import type { FormWidgetItem } from '@embedpdf/plugin-form';
+  import type { FormColors } from '@embedpdf/web';
+  import { FILL, useWidgetActivation } from './widget.js';
+  import WidgetBox from './WidgetBox.svelte';
+
+  let {
+    item,
+    colors,
+  }: { item: Extract<FormWidgetItem, { control: 'button' }>; colors: FormColors } = $props();
+
+  const activate = useWidgetActivation(() => item.annotationRef);
+</script>
+
+<WidgetBox
+  {item}
+  {colors}
+  edge={false}
+  style="cursor: {item.disabled ? 'default' : 'pointer'}"
+>
+  <!-- The box is the event surface: a disabled button must not swallow the pointer. -->
+  <button
+    type="button"
+    aria-label={item.label}
+    disabled={item.disabled}
+    onclick={activate}
+    style={FILL}
+    style:padding="0"
+    style:border="0"
+    style:background="transparent"
+    style:cursor="inherit"
+    style:pointer-events={item.disabled ? 'none' : 'auto'}
+  ></button>
+</WidgetBox>

package/dist/form/ButtonControl.svelte.d.ts

@@ -0,0 +1,11 @@
+import type { FormWidgetItem } from '@embedpdf/plugin-form';
+import type { FormColors } from '@embedpdf/web';
+type $$ComponentProps = {
+    item: Extract<FormWidgetItem, {
+        control: 'button';
+    }>;
+    colors: FormColors;
+};
+declare const ButtonControl: import("svelte").Component<$$ComponentProps, {}, "">;
+type ButtonControl = ReturnType<typeof ButtonControl>;
+export default ButtonControl;

package/dist/form/ComboControl.svelte

@@ -0,0 +1,52 @@
+<!--
+  A dropdown: an invisible native `<select>` over the field's picture. The browser owns the
+  dropdown, the engine the resting pixels.
+-->
+<script lang="ts">
+  import type { FormWidgetItem } from '@embedpdf/plugin-form';
+  import { FormToken as FormHostToken } from '@embedpdf/plugin-form/contract/host';
+  import type { FormColors } from '@embedpdf/web';
+  import { useCapability } from '../runtime/readers.svelte.js';
+  import FormFocusRing from './FormFocusRing.svelte';
+  import { FILL, useWidgetActivation } from './widget.js';
+  import WidgetBox from './WidgetBox.svelte';
+
+  let {
+    item,
+    colors,
+  }: { item: Extract<FormWidgetItem, { control: 'choice' }>; colors: FormColors } = $props();
+
+  const form = useCapability(FormHostToken);
+  const activate = useWidgetActivation(() => item.annotationRef);
+  let focused = $state(false);
+
+  function onChange(event: Event & { currentTarget: HTMLSelectElement }) {
+    void form.setValue(item.fieldRef, { value: event.currentTarget.value || null });
+  }
+</script>
+
+<WidgetBox {item} {colors} onclick={activate}>
+  <!--
+    See-through over the picture. One-way: it shows the field's selection whenever that changes;
+    between changes the browser owns it, and a change writes through the plugin. A disabled
+    select must not swallow the box's clicks.
+  -->
+  <select
+    value={item.selected[0] ?? ''}
+    aria-label={item.label}
+    disabled={item.disabled}
+    onfocus={() => (focused = true)}
+    onblur={() => (focused = false)}
+    onchange={onChange}
+    style={FILL}
+    style:opacity="0"
+    style:cursor={item.disabled ? 'default' : 'pointer'}
+    style:pointer-events={item.disabled ? 'none' : undefined}
+  >
+    {#if item.selected.length === 0}<option value=""></option>{/if}
+    {#each item.options as option, index (index)}
+      <option value={option.value}>{option.label}</option>
+    {/each}
+  </select>
+  <FormFocusRing visible={focused} color={colors.focus} />
+</WidgetBox>

package/dist/form/ComboControl.svelte.d.ts

@@ -0,0 +1,11 @@
+import type { FormWidgetItem } from '@embedpdf/plugin-form';
+import type { FormColors } from '@embedpdf/web';
+type $$ComponentProps = {
+    item: Extract<FormWidgetItem, {
+        control: 'choice';
+    }>;
+    colors: FormColors;
+};
+declare const ComboControl: import("svelte").Component<$$ComponentProps, {}, "">;
+type ComboControl = ReturnType<typeof ComboControl>;
+export default ComboControl;

package/dist/form/FieldPictures.svelte

@@ -0,0 +1,145 @@
+<!--
+  The page's fields as they look now. Each widget shows its picture, as the engine draws it (the
+  form plugin's, every state loaded, so a check box shows its new state at once), or the painter's
+  drawing while its look is pending or its picture is of an older version (`pictureOrPainting`): a
+  value, a calculation, a restyle shows at once. Hidden widgets aren't drawn.
+-->
+<script lang="ts">
+  import { untrack } from 'svelte';
+  import { annotationKey } from '@embedpdf/core';
+  import { MITER_LIMIT } from '@embedpdf/core-annotation';
+  import {
+    FormToken as FormHostToken,
+    type ShownWidget,
+  } from '@embedpdf/plugin-form/contract/host';
+  import { RenderToken } from '@embedpdf/plugin-render/contract/host';
+  import {
+    createShownUrls,
+    loadAppearanceUrls,
+    pictureOrPainting,
+    rectInPixels,
+    shownAppearance,
+    svgShapesOf,
+    type AppearanceUrl,
+    type PixelRect,
+    type SvgShape,
+  } from '@embedpdf/web';
+  import { usePage } from '../runtime/page.js';
+  import {
+    shallowArray,
+    useOptionalCapability,
+    useOptionalSelector,
+  } from '../runtime/readers.svelte.js';
+  import SvgShapes from '../runtime/SvgShapes.svelte';
+
+  const NO_WIDGETS: readonly ShownWidget[] = Object.freeze([]);
+
+  /** A widget as the template draws it: its picture, or the painter's shapes in its box. */
+  interface ShownLook {
+    key: string;
+    frame: PixelRect;
+    url: string | null;
+    painting: { viewBox: string; shapes: SvgShape[] } | null;
+  }
+
+  const page = usePage();
+  const form = useOptionalCapability(FormHostToken);
+  // The same list until a widget on this page changes.
+  const widgets = useOptionalSelector(
+    FormHostToken,
+    (form) => form.listShownWidgets(page.ref),
+    NO_WIDGETS,
+    shallowArray,
+  );
+  // Loaded again when one of the page's widgets is drawn again, and at appearance-scale crossings.
+  const epoch = useOptionalSelector(FormHostToken, (form) => form.getAppearanceEpoch(page.ref), '');
+  const scale = useOptionalSelector(
+    RenderToken,
+    (renderer) => renderer.getAppearanceScale(page.transform.renderScale),
+    0,
+  );
+
+  // `null` until the page's first pictures arrive.
+  let urls = $state.raw<Record<string, AppearanceUrl> | null>(null);
+  // The pictures shown stay valid until the next ones are shown.
+  const shown = createShownUrls();
+  $effect(() => () => shown.release());
+  $effect(() => {
+    const host = form.current;
+    const ref = page.ref;
+    const at = scale.current;
+    void epoch.current;
+    if (!host || !at) return;
+    return untrack(() =>
+      loadAppearanceUrls(
+        shown,
+        (signal) => host.renderAppearances(ref, at, signal),
+        annotationKey,
+        (loaded) => (urls = loaded),
+      ),
+    );
+  });
+
+  const looks = $derived(
+    widgets.current.flatMap((widget): ShownLook[] => {
+      const key = annotationKey(widget.ref);
+      const look = pictureOrPainting({
+        pending: widget.pending,
+        picture: urls && shownAppearance(urls, key, widget.appearanceState),
+        version: widget.pictureVersion,
+        loaded: urls !== null,
+        paint: () => form.current?.getWidgetPainting(widget.ref) ?? null,
+      });
+      if (!look) return [];
+      if (look.kind === 'picture') {
+        return [
+          {
+            key,
+            url: look.picture.url,
+            painting: null,
+            frame: rectInPixels(look.picture.box, page.transform),
+          },
+        ];
+      }
+      const { x, y, width, height } = widget.rect;
+      return [
+        {
+          key,
+          url: null,
+          painting: {
+            viewBox: `${x} ${y} ${width} ${height}`,
+            shapes: svgShapesOf(look.painting.scene, { miterLimit: MITER_LIMIT }),
+          },
+          frame: rectInPixels(widget.rect, page.transform),
+        },
+      ];
+    }),
+  );
+</script>
+
+{#each looks as look (look.key)}
+  {#if look.painting}
+    <svg
+      viewBox={look.painting.viewBox}
+      style="position: absolute; overflow: visible; pointer-events: none"
+      style:left="{look.frame.left}px"
+      style:top="{look.frame.top}px"
+      style:width="{look.frame.width}px"
+      style:height="{look.frame.height}px"
+    >
+      <SvgShapes shapes={look.painting.shapes} />
+    </svg>
+  {:else if look.url}
+    <!-- A global `img { max-width: 100% }` reset would clamp a picture: the sizes are explicit. -->
+    <img
+      src={look.url}
+      alt=""
+      draggable="false"
+      style="position: absolute; max-width: none; max-height: none; pointer-events: none"
+      style:left="{look.frame.left}px"
+      style:top="{look.frame.top}px"
+      style:width="{look.frame.width}px"
+      style:height="{look.frame.height}px"
+    />
+  {/if}
+{/each}

package/dist/form/FieldPictures.svelte.d.ts

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

package/dist/form/FormFocusRing.svelte

@@ -0,0 +1,25 @@
+<!--
+  The focus ring of a field, painted above the field's picture and its see-through native
+  control. An inset outline on the box itself would sit under an opaque child, so rectangular
+  checkboxes and dropdowns would look unfocused while they are active in the native Tab order.
+-->
+<script lang="ts">
+  import { cssText, formFocusRingStyleOf } from '@embedpdf/web';
+
+  let {
+    visible,
+    color,
+  }: {
+    visible: boolean;
+    /** The ring's CSS color: the form's `focus.color` setting, through its CSS variable. */
+    color: string;
+  } = $props();
+</script>
+
+{#if visible}
+  <span
+    aria-hidden="true"
+    data-embedpdf-form-focus-ring=""
+    style={cssText(formFocusRingStyleOf(color))}
+  ></span>
+{/if}

package/dist/form/FormFocusRing.svelte.d.ts

@@ -0,0 +1,8 @@
+type $$ComponentProps = {
+    visible: boolean;
+    /** The ring's CSS color: the form's `focus.color` setting, through its CSS variable. */
+    color: string;
+};
+declare const FormFocusRing: import("svelte").Component<$$ComponentProps, {}, "">;
+type FormFocusRing = ReturnType<typeof FormFocusRing>;
+export default FormFocusRing;