@inkbar/svelte 0.6.0 → 0.8.0

package/README.md

@@ -145,6 +145,12 @@ Inside `InkRoot`, `useHistory()` returns the same object. Its `batch(fn)` runs `
 
 `key` identifies the document. Reuse the same key when only the signed URL changes and the document is not reloaded.
 
+## Forms
+
+`InkViewport` fills the PDF's form fields and runs the form's scripts. `useForm()` returns the fields, their values, and `set` and `reset`. Use `bind:fields` to hold the values in your own state. The form never submits, opens a link, sends mail or prints: `onformaction` hands each request to you. `formHighlight={false}` turns off the field tint, and a change applies to the open document in place.
+
+The [forms guide](https://inkbar.dev/docs/guides/forms/) covers controlled fields, form actions, scripts, signature fields and saving values as Gloss.
+
 ## Thread popover
 
 `InkThreadPopover` opens the comment thread of the activated note or text markup (a highlight, underline, strikeout or squiggly). A new note or highlight has no text yet, so the form first writes its own `contents` (labelled "Comment"); after that it adds replies. A highlight with a comment shows a small marker at its end. Replies show in the thread only; the page draws just the note or highlight they answer.
@@ -175,6 +181,12 @@ A plugin from `definePlugin` (in `@inkbar/core/dom`) adds commands, tools, decor
 
 Plugin stores undo with annotations. In controlled mode with `history`, each undo step also snapshots the plugin stores, so accepting something and undoing it restores both.
 
+## Search
+
+`InkFindBar` is the find bar and `InkSearchButton` opens it. Place the bar anywhere inside `InkRoot`, once `InkViewport` is there; Ctrl/Cmd+F opens it while it is mounted. `useSearch()` returns the search `state` and its actions (`open`, `setQuery`, `setMatchCase`, `next`, `previous`, `close`) for your own control. See the [`@inkbar/core` README](https://github.com/inkbar/inkbar/tree/main/packages/core#search) for the API.
+
+The bar handles Escape itself and stops it there, so an `onkeydown` you pass to `InkFindBar` never sees Escape.
+
 ## Custom rendering
 
 Slots are snippets. `InkViewport` takes `loading`, `empty`, `error`, `annotation` and `pageError`. `InkThreadPopover` takes `children` as a snippet that receives the popover's props. `InkToolButton` takes `children` as a snippet of `{ active, label }`, and `InkCommand` one of `{ label, busy }`. The props each receives are typed as `AnnotationSlotProps` and `ThreadPopoverSlotProps`, the same types the Vue and React packages export.
@@ -196,6 +208,7 @@ The scroll area takes focus. From there:
 - With the `highlight` or `redact-area` tool active, `Enter` turns the text selection into a mark.
 - With the `note` tool active, `Enter` places a note at the centre of the current page and opens it.
 - With the `signature` tool active, `Enter` places the chosen signature at the centre of the current page.
+- `Ctrl` or `Cmd` + `Z` undoes. `Ctrl` or `Cmd` + `Shift` + `Z`, or `Ctrl` + `Y`, redoes. `Ctrl` and `Cmd` both work on every platform. The keys do what `InkUndo` and `InkRedo` do, from anywhere in `InkRoot`, toolbars included, and act only while that button is enabled. In a text field or editable content the keys stay with the element, so a field keeps its own text undo. In a `<select>` they are left to the browser, which does nothing with them.
 
 On a focused annotation:
 

package/dist/components/InkFindBar.svelte

@@ -0,0 +1,213 @@
+<script module lang="ts">
+  import type { HTMLAttributes } from 'svelte/elements'
+
+  export type InkFindBarProps = Omit<HTMLAttributes<HTMLDivElement>, 'children'>
+</script>
+
+<script lang="ts">
+  /*
+   * The find bar: a field, the match count, previous and next, a match-case toggle and close,
+   * a view of the root's search state. Place it anywhere inside `InkRoot`: it portals itself
+   * into `[data-ink-viewport-root]`, the positioned ancestor the theme floats it from over the
+   * top-right of the pages (as `InkThreadPopover` anchors to the root's overlay rather than
+   * where it is written). It renders nothing until `InkViewport` has mounted, and is hidden
+   * while the search is closed. While it is mounted it registers with the search controller,
+   * which is what lets Ctrl/Cmd+F open it.
+   *
+   * Enter in the field steps to the next match, Shift+Enter to the previous, Escape closes.
+   * Closing returns focus to where it was before the bar opened, else to the document.
+   */
+  import { findAnnouncer, findCountText } from '@inkbar/core/dom'
+  import { CaseSensitive, ChevronDown, ChevronUp, X } from '@inkbar/icons'
+  import { untrack } from 'svelte'
+
+  import { useInkContext } from '../context.js'
+  import { useSearch } from '../hooks/useSearch.svelte.js'
+  import { useReadable } from '../use-readable.svelte.js'
+
+  import InkIcon from './InkIcon.svelte'
+
+  import type { SearchState } from '@inkbar/core/dom'
+
+  let { class: className, ...rest }: InkFindBarProps = $props()
+
+  const ctx = useInkContext('InkFindBar')
+  const search = useSearch()
+  const scroll = useReadable(() => ctx.viewportEl, null)
+  /** The viewport root: the scroll element's parent, once InkViewport has mounted. */
+  const target = $derived(scroll.current?.parentElement ?? null)
+
+  let bar = $state<HTMLDivElement | null>(null)
+  let field = $state<HTMLInputElement | null>(null)
+  let live = $state<HTMLDivElement | null>(null)
+  /** Where focus was when the bar opened, and whether it was open on the last pass. */
+  let before: HTMLElement | null = null
+  let wasOpen = false
+
+  const open = $derived(search.state.open)
+  const query = $derived(search.state.query)
+
+  // After the update, so the bar is shown (and can take focus) when it opens.
+  $effect(() => {
+    const el = bar
+    const input = field
+    const isOpen = open
+    const text = query
+    if (!el || !input) return
+    untrack(() => {
+      if (isOpen !== wasOpen) {
+        wasOpen = isOpen
+        const doc = el.ownerDocument
+        if (isOpen) {
+          const active = doc.activeElement
+          before =
+            active instanceof HTMLElement && active !== doc.body && !el.contains(active)
+              ? active
+              : null
+          input.focus()
+          input.select()
+        } else {
+          // Focus inside the bar is about to be lost with it; focus elsewhere is left alone.
+          const hadFocus =
+            el.contains(doc.activeElement) || doc.activeElement === doc.body
+          if (hadFocus) {
+            const to =
+              before?.isConnected && !el.contains(before) ? before : scroll.current
+            to?.focus({ preventScroll: true })
+          }
+          before = null
+        }
+      }
+      if (input.value !== text) {
+        input.value = text
+        // A query set from code arrives after the bar opened: keep the new text selected.
+        if (el.ownerDocument.activeElement === input) input.select()
+      }
+    })
+  })
+
+  // Registered while mounted.
+  $effect(() => {
+    const controller = ctx.search
+    if (!controller || !target) return
+    return controller.attachBar()
+  })
+
+  // The live region follows the controller's state change by change, as the vanilla bar does,
+  // and is written directly. An update shows only the last of the changes batched into it, so
+  // two steps in one task that end where they began would otherwise say nothing.
+  $effect(() => {
+    const controller = ctx.search
+    const el = live
+    if (!controller || !el) return
+    return untrack(() => {
+      const announce = findAnnouncer()
+      const say = (s: SearchState): void => {
+        const text = announce(s)
+        if (el.textContent !== text) el.textContent = text
+      }
+      say(controller.state.get())
+      return controller.state.subscribe(say)
+    })
+  })
+
+  // A native listener, so Escape stops at the bar as it does in the vanilla and Vue bars;
+  // Svelte's delegated events would stop it only after the root's own listeners saw it.
+  $effect(() => {
+    const controller = ctx.search
+    const el = bar
+    if (!controller || !el) return
+    const onKeydown = (e: KeyboardEvent): void => {
+      if (e.key !== 'Escape' || e.defaultPrevented || e.isComposing) return
+      e.preventDefault()
+      e.stopPropagation()
+      controller.close()
+    }
+    el.addEventListener('keydown', onKeydown)
+    return () => el.removeEventListener('keydown', onKeydown)
+  })
+
+  /**
+   * Moves the bar itself into the viewport root, leaving nothing where it is written. Svelte
+   * removes it when its own `{#if}` branch goes, but not when an ancestor's block goes and
+   * takes only the nodes still in place, so the cleanup removes it too. A keyed `{#each}` that
+   * reorders would move the bar back to where it is written, so keep `InkFindBar` out of one.
+   */
+  const into = (to: Element) => (el: HTMLElement) => {
+    to.appendChild(el)
+    return () => el.remove()
+  }
+</script>
+
+{#if target}
+  <div
+    {...rest}
+    bind:this={bar}
+    class={['ink-find-bar', className]}
+    data-ink-find-bar=""
+    role="search"
+    hidden={!open}
+    {@attach into(target)}
+  >
+    <input
+      bind:this={field}
+      type="text"
+      aria-label="Find in document"
+      autocomplete="off"
+      spellcheck={false}
+      oninput={(e) => search.setQuery(e.currentTarget.value)}
+      onkeydown={(e) => {
+        if (e.key !== 'Enter' || e.isComposing) return
+        e.preventDefault()
+        if (e.shiftKey) search.previous()
+        else search.next()
+      }}
+    />
+    <span class="ink-find-count" data-ink-find-count=""
+      >{findCountText(search.state)}</span
+    >
+    <button
+      type="button"
+      data-ink-find-previous=""
+      aria-label="Previous match"
+      title="Previous match"
+      onclick={() => search.previous()}
+    >
+      <InkIcon icon={ChevronUp} />
+    </button>
+    <button
+      type="button"
+      data-ink-find-next=""
+      aria-label="Next match"
+      title="Next match"
+      onclick={() => search.next()}
+    >
+      <InkIcon icon={ChevronDown} />
+    </button>
+    <button
+      type="button"
+      data-ink-find-match-case=""
+      aria-label="Match case"
+      title="Match case"
+      aria-pressed={search.state.matchCase}
+      onclick={() => search.setMatchCase(!search.state.matchCase)}
+    >
+      <InkIcon icon={CaseSensitive} />
+    </button>
+    <button
+      type="button"
+      data-ink-find-close=""
+      aria-label="Close find"
+      title="Close find"
+      onclick={() => search.close()}
+    >
+      <InkIcon icon={X} />
+    </button>
+    <div
+      bind:this={live}
+      class="ink-visually-hidden"
+      data-ink-find-status=""
+      aria-live="polite"
+    ></div>
+  </div>
+{/if}

package/dist/components/InkFindBar.svelte.d.ts

@@ -0,0 +1,6 @@
+import type { HTMLAttributes } from 'svelte/elements';
+export type InkFindBarProps = Omit<HTMLAttributes<HTMLDivElement>, 'children'>;
+declare const InkFindBar: import("svelte").Component<InkFindBarProps, {}, "">;
+type InkFindBar = ReturnType<typeof InkFindBar>;
+export default InkFindBar;
+//# sourceMappingURL=InkFindBar.svelte.d.ts.map

package/dist/components/InkFindBar.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InkFindBar.svelte.d.ts","sourceRoot":"","sources":["../../src/lib/components/InkFindBar.svelte.ts"],"names":[],"mappings":"AAGE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAErD,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,UAAU,CAAC,CAC/E;AAmLD,QAAA,MAAM,UAAU,qDAAwC,CAAC;AACzD,KAAK,UAAU,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;AAChD,eAAe,UAAU,CAAC"}

package/dist/components/InkFormAlert.svelte

@@ -0,0 +1,108 @@
+<script lang="ts">
+  /*
+   * A form script's `app.alert`: the message and OK, shown without blocking (no overlay, not
+   * modal), so the form stays usable around it. InkViewport mounts it; hosts compose nothing.
+   * OK, or Escape while focus is in the alert, closes it, and focus goes back where it was. A
+   * press outside leaves it open, and Escape anywhere else stays with the viewer. A new message
+   * replaces the one shown.
+   *
+   * The markup is core's `createFormAlert`, portalled to `<body>`. It is not a Bits UI dialog:
+   * Bits UI's escape layer takes every Escape on the page while it is open (it prevents the
+   * key's default), which would end the viewer's own use of the key.
+   */
+  import { FORM_LABELS } from '@inkbar/core/dom'
+  import { Portal } from 'bits-ui'
+  import { untrack } from 'svelte'
+
+  let {
+    message,
+    shown,
+    fallback,
+    onClose,
+  }: {
+    /** The message to show (text, not markup); `null` while none is. */
+    message: string | null
+    /** Counts the times a message was shown, so the same text shown again takes focus again. */
+    shown: number
+    /** Where focus goes when nothing it can return to is left. */
+    fallback: () => HTMLElement | null
+    onClose: () => void
+  } = $props()
+
+  const uid = $props.id()
+  let panel = $state<HTMLElement | null>(null)
+  let ok = $state<HTMLButtonElement | null>(null)
+  /** Where focus was when the alert opened. */
+  let returnTo: HTMLElement | null = null
+  let wasOpen = false
+  const open = $derived(message !== null)
+
+  // After the alert renders, before anything else moves focus: where focus was is read first.
+  $effect(() => {
+    const showing = open
+    void shown
+    const button = ok
+    if (!showing) {
+      wasOpen = false
+      return
+    }
+    if (!button) return
+    untrack(() => {
+      if (!wasOpen) {
+        wasOpen = true
+        const active = document.activeElement
+        returnTo =
+          active instanceof HTMLElement && active !== document.body ? active : null
+      }
+      button.focus({ preventScroll: true })
+    })
+  })
+
+  function close(): void {
+    // Focus that moved elsewhere while the alert showed stays there.
+    const hadFocus = !!panel?.contains(document.activeElement)
+    const back = returnTo?.isConnected === true ? returnTo : fallback()
+    onClose()
+    if (hadFocus) back?.focus({ preventScroll: true })
+  }
+
+  function onkeydown(e: KeyboardEvent): void {
+    if (e.key !== 'Escape' || e.defaultPrevented) return
+    e.preventDefault()
+    e.stopPropagation()
+    close()
+  }
+</script>
+
+{#if message !== null}
+  <Portal>
+    <div
+      bind:this={panel}
+      role="alertdialog"
+      aria-labelledby="{uid}-title"
+      aria-describedby="{uid}-message"
+      class="ink-dialog ink-form-alert"
+      data-ink-form-alert=""
+      data-state="open"
+      tabindex="-1"
+      {onkeydown}
+    >
+      <h2 id="{uid}-title" class="ink-dialog-title">{FORM_LABELS.alert}</h2>
+      <p id="{uid}-message" class="ink-form-alert-message" data-ink-form-alert-message="">
+        {message}
+      </p>
+      <div class="ink-dialog-actions">
+        <button
+          bind:this={ok}
+          type="button"
+          class="ink-button"
+          data-variant="primary"
+          data-ink-form-alert-ok=""
+          onclick={close}
+        >
+          {FORM_LABELS.ok}
+        </button>
+      </div>
+    </div>
+  </Portal>
+{/if}

package/dist/components/InkFormAlert.svelte.d.ts

@@ -0,0 +1,13 @@
+type $$ComponentProps = {
+    /** The message to show (text, not markup); `null` while none is. */
+    message: string | null;
+    /** Counts the times a message was shown, so the same text shown again takes focus again. */
+    shown: number;
+    /** Where focus goes when nothing it can return to is left. */
+    fallback: () => HTMLElement | null;
+    onClose: () => void;
+};
+declare const InkFormAlert: import("svelte").Component<$$ComponentProps, {}, "">;
+type InkFormAlert = ReturnType<typeof InkFormAlert>;
+export default InkFormAlert;
+//# sourceMappingURL=InkFormAlert.svelte.d.ts.map

package/dist/components/InkFormAlert.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InkFormAlert.svelte.d.ts","sourceRoot":"","sources":["../../src/lib/components/InkFormAlert.svelte.ts"],"names":[],"mappings":"AAkBC,KAAK,gBAAgB,GAAI;IACtB,oEAAoE;IACpE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,4FAA4F;IAC5F,KAAK,EAAE,MAAM,CAAA;IACb,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,WAAW,GAAG,IAAI,CAAA;IAClC,OAAO,EAAE,MAAM,IAAI,CAAA;CACpB,CAAC;AA6EJ,QAAA,MAAM,YAAY,sDAAwC,CAAC;AAC3D,KAAK,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AACpD,eAAe,YAAY,CAAC"}

package/dist/components/InkRoot.svelte

@@ -5,6 +5,9 @@
     AnnotationChange,
     AnnotationDefaults,
     DocumentSource,
+    FieldsChange,
+    FieldValues,
+    FormAction,
     InkDocument,
     InkError,
     InkStatus,
@@ -38,6 +41,21 @@
     annotations?: Annotation[] | undefined
     onAnnotationsChange?: ((next: Annotation[]) => void) | undefined
     onChange?: ((change: AnnotationChange) => void) | undefined
+    /**
+     * Pass (with `bind:`) to put the form's field values under the host's control. A commit
+     * shows at once and is reported after; the host's push wins. The mode is fixed when a
+     * document opens, as for `annotations`.
+     */
+    fields?: FieldValues | undefined
+    /**
+     * Committed field values, in full, with what changed them. Called only while the fields
+     * are controlled, after the bound value is written.
+     */
+    onFieldsChange?: ((next: FieldValues, change: FieldsChange) => void) | undefined
+    /** The form asked to submit, open a link, send mail, print or prompt. Inkbar does none. */
+    onformaction?: ((action: FormAction) => void) | undefined
+    /** Tints fillable form fields. Default true. A change applies to the open document in place. */
+    formHighlight?: boolean | undefined
     tool?: ToolId | undefined
     onToolChange?: ((tool: ToolId) => void) | undefined
     /**
@@ -78,6 +96,11 @@
     /** Undo history. Defaults to on for uncontrolled, off for controlled. */
     history?: boolean | undefined
     onReady?: ((doc: InkDocument) => void) | undefined
+    /**
+     * Opening failed, or later: a form script failed (`FormScriptError`; the form stays
+     * fillable), or a signature field refused its signing (`FieldSigned`, `FieldReadOnly`).
+     * An error from while the document opened comes after `onReady`.
+     */
     onError?: ((error: InkError) => void) | undefined
     onActivate?: ((id: string) => void) | undefined
     /** The root element, for hosts that bind it. */
@@ -102,12 +125,18 @@
     writable,
   } from '@inkbar/core'
   import {
+    attachHistoryKeys,
     createPluginHost,
+    createSearchController,
     createToolOptions,
     cssVariableDefaults,
     FONT_FAMILIES,
+    handleFindKey,
+    keepHistoryFocus,
+    pageSelectionText,
     SIGNATURE_FONTS,
     trackToolStyle,
+    viewerSearchOf,
   } from '@inkbar/core/dom'
   import { DEV } from 'esm-env'
   import { untrack } from 'svelte'
@@ -117,7 +146,12 @@
   import { useReadable } from '../use-readable.svelte.js'
 
   import type { PluginHistory } from '@inkbar/core'
-  import type { PluginHost, ToolController, Viewport } from '@inkbar/core/dom'
+  import type {
+    PluginHost,
+    SearchController,
+    ToolController,
+    Viewport,
+  } from '@inkbar/core/dom'
 
   let {
     src,
@@ -127,6 +161,10 @@
     annotations = $bindable(),
     onAnnotationsChange,
     onChange,
+    fields = $bindable(),
+    onFieldsChange,
+    onformaction,
+    formHighlight,
     tool = $bindable(),
     onToolChange,
     tools: hostTools,
@@ -228,6 +266,7 @@
     let opened: InkDocument | null = null
     /** The snapshot history's hold on a controlled document's store. */
     let detach: () => void = noop
+    let stopFormErrors: () => void = noop
     untrack(() => snapshotHistory.clear())
     const source = untrack(() => src)
     if (source === null) {
@@ -260,6 +299,20 @@
                   },
                 }
               : { mode: 'uncontrolled' as const },
+            fields:
+              fields !== undefined
+                ? {
+                    mode: 'controlled' as const,
+                    initial: fields,
+                    onChange: (next: FieldValues, change: FieldsChange) => {
+                      // As for annotations: a commit made in the tick this root unmounts or
+                      // reopens never reaches the host.
+                      if (cancelled) return
+                      fields = next
+                      onFieldsChange?.(next, change)
+                    },
+                  }
+                : { mode: 'uncontrolled' as const },
           }))
         )
         if (cancelled) {
@@ -271,6 +324,17 @@
         const current = untrack(() => annotations)
         if (doc.annotations.mode === 'controlled' && current !== undefined)
           doc.annotations.setControlledValue(current)
+        // The same for the fields; a document whose fields opened uncontrolled ignores the push.
+        const currentFields = untrack(() => fields)
+        if (currentFields !== undefined) doc.form.setControlledValue(currentFields)
+        // A form script that fails leaves the form fillable; the failure goes to `onError`.
+        // Subscribed before anyone hears of the document, so the form replays the errors from
+        // while it opened here; they are held until `onReady` has run.
+        let held: InkError[] | undefined = []
+        stopFormErrors = doc.form.on('error', (e) => {
+          if (held) held.push(e)
+          else onError?.(e)
+        })
         documentNow = doc
         document = doc
         // Controlled edits run the plugins' reactions inside their own snapshot step.
@@ -281,8 +345,15 @@
         override = null
         setTestHook(ref, doc)
         const s = doc.status.get()
-        if (s.state === 'ready') onReady?.(doc)
-        else if (s.state === 'error') onError?.(s.error)
+        try {
+          if (s.state === 'ready') onReady?.(doc)
+          else if (s.state === 'error') onError?.(s.error)
+        } finally {
+          // A host whose `onReady` throws still hears the held errors and every later one.
+          const early = held
+          held = undefined
+          if (!cancelled) for (const e of early) onError?.(e)
+        }
       } catch (cause) {
         if (cancelled) return
         const error =
@@ -303,6 +374,7 @@
       // Cleared first, so the plugins close their stores while the document is still alive.
       hostDocument.set(null)
       detach()
+      stopFormErrors()
       opened?.destroy()
       documentNow = null
       document = null
@@ -318,6 +390,15 @@
       untrack(() => doc.annotations.setControlledValue(list))
   })
 
+  // The host's field values reach the form; the echo of a commit it applied changes nothing.
+  // Read through a derived, so a host that spreads its props pushes only a new value.
+  const pushedFields = $derived(fields)
+  $effect(() => {
+    const values = pushedFields
+    const doc = document
+    if (values && doc) untrack(() => doc.form.setControlledValue(values))
+  })
+
   function setTool(id: ToolId): void {
     // Picking the active tool again starts it afresh, as after a one-shot tool's use.
     if (currentTool === id && tools?.active.get() === id) tools.set(id)
@@ -362,6 +443,21 @@
     react: (fn) => pluginHistory.react(fn),
   }
 
+  // The undo and redo keys anywhere in the root do what InkUndo and InkRedo do. When either
+  // button undoes or redoes the last step and disables itself, focus goes back to the document.
+  $effect(() => {
+    const el = ref
+    if (!el) return
+    const stopKeys = attachHistoryKeys(el, () => inkHistory)
+    const stopFocus = keepHistoryFocus(el, () =>
+      el.querySelector<HTMLElement>('[data-ink-scroll]')
+    )
+    return () => {
+      stopKeys()
+      stopFocus()
+    }
+  })
+
   /**
    * The history the plugins reach, picked by the open document's mode when they call. The host
    * reads it as soon as a document opens, so it goes by `documentNow`, which is set by then.
@@ -393,7 +489,15 @@
   const hostActivated = writable<string | null>(null)
   const viewportEl = writable<HTMLElement | null>(null)
   let pluginHost = $state.raw<PluginHost | null>(null)
+  /** One search controller for the root's life, built with the plugin host that shares it. */
+  let search = $state.raw<SearchController | null>(null)
   $effect(() => {
+    const controller = untrack(() =>
+      createSearchController({
+        document: readonly(hostDocument),
+        viewport: () => viewport,
+      })
+    )
     const host = untrack(() =>
       createPluginHost({
         // Read once, as documented on the prop.
@@ -408,13 +512,33 @@
         root: readonly(viewportEl),
         decorate: () => decorateAnnotation,
         viewport: () => viewport,
+        search: viewerSearchOf(controller),
       })
     )
+    search = controller
     pluginHost = host
     // Destroyed after InkViewport's engine and its plugin layers, as in `createViewer`: Svelte
     // creates a component's effects after its template and tears them down in creation order,
     // so the children's teardowns run first.
-    return () => host.destroy()
+    return () => {
+      host.destroy()
+      controller.destroy()
+    }
+  })
+
+  /*
+   * Ctrl/Cmd+F while focus is in the root and a find bar is mounted; else the browser's. A
+   * native listener: the handler reads the event's `currentTarget`, which is the root here.
+   */
+  $effect(() => {
+    const el = ref
+    const controller = search
+    if (!el || !controller) return
+    const onKeydown = (e: KeyboardEvent): void => {
+      handleFindKey(e, controller, () => pageSelectionText(el))
+    }
+    el.addEventListener('keydown', onKeydown)
+    return () => el.removeEventListener('keydown', onKeydown)
   })
 
   /** The document's tool style; it batches through `inkHistory`, whichever mode is on. */
@@ -455,6 +579,9 @@
     get pluginHost() {
       return pluginHost
     },
+    get search() {
+      return search
+    },
     viewportEl,
     get viewport() {
       return viewport
@@ -505,6 +632,11 @@
       viewport = vp
       tools = tc
     },
+    get formHighlight() {
+      return formHighlight
+    },
+    reportFormAction: (a) => onformaction?.(a),
+    reportError: (e) => onError?.(e),
   }
   setInkContext(context, () => activatedNow)