@inkbar/svelte 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Redactr Platforms Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,155 @@
-# Temporary Holding Version
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/inkbar/inkbar/main/.github/assets/inkbar-mark-on-dark.svg">
+    <img src="https://raw.githubusercontent.com/inkbar/inkbar/main/.github/assets/inkbar-mark-on-light.svg" alt="Inkbar" width="72" height="72">
+  </picture>
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h1 align="center">@inkbar/svelte</h1>
+
+<p align="center">
+  A PDF viewer and editor for Svelte 5. No licence fee.
+</p>
+
+<p align="center">
+  <a href="https://inkbar.dev">Website</a> ·
+  <a href="https://inkbar.dev/docs/">Docs</a> ·
+  <a href="https://sandbox.inkbar.dev">Sandbox</a> ·
+  <a href="https://github.com/inkbar/inkbar">GitHub</a>
+</p>
+
+---
+
+Drop a PDF viewer into your Svelte app and let people highlight text, leave notes with replies and review redactions. `@inkbar/svelte` gives you a default toolbar and popovers styled by `@inkbar/theme`, plus the unstyled components and hooks they are made from, so you can keep the defaults or build your own UI.
+
+Annotations are plain typed objects. Bind them with `bind:annotations` to keep them in your own state, or let Inkbar hold them with undo and redo.
+
+## Install
+
+```sh
+pnpm add @inkbar/svelte @inkbar/core @inkbar/theme
+```
+
+Svelte 5.46.4 or later is a peer dependency. Add the Vite plugin from `@inkbar/core/vite` so the PDF engine can load its worker and fonts; the [`@inkbar/core` README](https://github.com/inkbar/inkbar/tree/main/packages/core#serving-pdfjs-assets) covers it. The package ships `.svelte` sources, so your bundler compiles them for your target, including the server.
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import {
+    InkRoot,
+    InkViewport,
+    DefaultToolbar,
+    InkNotePopover,
+    InkSuggestionCard,
+  } from '@inkbar/svelte'
+  import type { Annotation } from '@inkbar/core'
+  import { assets } from 'virtual:inkbar-assets'
+  import '@inkbar/theme/theme.css'
+
+  let { signedUrl, documentId }: { signedUrl: string; documentId: string } = $props()
+
+  let annotations = $state.raw<Annotation[]>([])
+</script>
+
+<InkRoot src={{ url: signedUrl, key: documentId }} {assets} bind:annotations>
+  <DefaultToolbar />
+  <InkViewport />
+  <InkNotePopover />
+  <InkSuggestionCard />
+</InkRoot>
+```
+
+`bind:annotations` makes your list the source of truth. Leave it off and Inkbar keeps the state itself, with undo and redo.
+
+## Controlled mode
+
+With `bind:annotations`, Inkbar proposes each change by writing the binding and shows whatever list it holds. To change annotations yourself, replace the array: `annotations = [...annotations, next]`. In-place mutation (`push`, `splice`, editing an item) is not observed, so the viewer never sees it. Declare the list with `$state.raw`, since Inkbar replaces it whole.
+
+To decide on each proposal before it applies, use a function binding. The setter receives the proposed list; apply it, change it or drop it:
+
+```svelte
+<InkRoot
+  src={{ url: signedUrl, key: documentId }}
+  {assets}
+  bind:annotations={() => annotations, (next) => (annotations = next.filter(allowed))}
+>
+  <InkViewport />
+</InkRoot>
+```
+
+`onAnnotationsChange` fires alongside the binding, and `onChange` carries the change itself. An `annotations` prop passed without a binding is overridden inside the component as proposals arrive, so bind it to keep control.
+
+Undo and redo are off in controlled mode unless you pass `history={true}`. Inkbar then keeps a stack of your list's past values and applies undo and redo through the binding. Every change to the list is a step, including the list you load from your server when the document opens. Clear the history once that load has reached the viewer, so the first undo does not empty the list:
+
+```svelte
+<script lang="ts">
+  import { tick } from 'svelte'
+  import { InkRoot, InkViewport } from '@inkbar/svelte'
+  import type { InkRootHandle } from '@inkbar/svelte'
+  import type { Annotation, InkDocument } from '@inkbar/core'
+  import { assets } from 'virtual:inkbar-assets'
+
+  let { signedUrl, documentId }: { signedUrl: string; documentId: string } = $props()
+
+  let annotations = $state.raw<Annotation[]>([])
+  let root = $state<InkRootHandle | undefined>()
+
+  async function onReady(doc: InkDocument) {
+    annotations = await loadAnnotations(doc.key)
+    await tick()
+    root?.history.clear()
+  }
+</script>
+
+<InkRoot
+  bind:this={root}
+  bind:annotations
+  history={true}
+  src={{ url: signedUrl, key: documentId }}
+  {assets}
+  {onReady}
+>
+  <InkViewport />
+</InkRoot>
+```
+
+Inside `InkRoot`, `useHistory()` returns the same object. Its `batch(fn)` runs `fn` and records what it changes as one undo step. With `history={true}` on a controlled list, you still get one write to `bind:annotations` per add. The step lands when the current task ends, and `canUndo` updates then. Any other change you apply to the list in that window joins the step. In both modes, `fn` must be synchronous. The instance also exposes `getDocument()` and `getStatus()`, and `bind:ref` gives you the root element.
+
+`key` identifies the document. Reuse the same key when only the signed URL changes and the document is not reloaded.
+
+## Note popover
+
+`InkNotePopover` opens the thread of the activated note. A new note has no text yet, so the form first writes the note's own text (labelled "Comment"); after that it adds replies.
+
+A root note with no text and no replies is removed when its popover closes, or when activation moves to another annotation, so abandoned notes do not stay on the page. Locked notes are never removed. If you add notes yourself (`add({ type: 'note', ... })`), give them `contents`, or they will be removed the first time someone opens and closes them.
+
+## Custom rendering
+
+Slots are snippets. `InkViewport` takes `loading`, `empty`, `error`, `annotation` and `pageError`. `InkNotePopover` and `InkSuggestionCard` take `children` as a snippet that receives the popover's props. `InkToolButton` takes `children` as a snippet of `{ active, label }`. The props each receives are typed as `AnnotationSlotProps`, `NotePopoverSlotProps` and `SuggestionCardSlotProps`, the same types the Vue and React packages export.
+
+`InkRoot`, `InkToolbar`, `InkToolButton`, `InkZoomIn` and `InkZoomOut` take a `child` snippet to render your own element. Spread the `props` it gives you on that element. The snippet type is exported as `ChildSnippet`.
+
+```svelte
+<InkToolbar>
+  {#snippet child({ props })}
+    <nav {...props} class="my-toolbar">…</nav>
+  {/snippet}
+</InkToolbar>
+```
+
+## Keyboard
+
+The scroll element takes focus. With the highlight or redact tool active, `Enter` turns the text selection into a mark; with the note tool, `Enter` places a note in the middle of the current page and opens it. On a focused annotation, `Enter` or `Space` selects and activates it (a note opens its thread and a suggested redaction its card; other types are only selected), `ArrowUp` and `ArrowDown` move between annotations, `Shift` + arrow moves it by 1 pt (add `Alt` for 10 pt), `Ctrl` or `Cmd` + `Shift` + arrow resizes an area mark, and `Delete` removes it. The full table is in the [`@inkbar/core` README](https://github.com/inkbar/inkbar/tree/main/packages/core#tools-and-keyboard).
+
+## Styling
+
+Components carry state on data attributes, for example `[data-annotation][data-state="selected"]` and `[data-tool="highlight"][data-state="on"]`. `@inkbar/theme` gives a default look. Your own CSS overrides it without `!important`. `InkRoot`, `InkViewport`, `DefaultToolbar` and the toolbar controls accept `class`.
+
+## Hooks
+
+`useDocument`, `useAnnotations`, `useTool`, `useSelection`, `useZoom`, `usePage`, `useHistory` and `useEmbedded` read the state of the nearest `InkRoot`. Call them during component initialisation, as you would `getContext`. Each returns an object whose reactive members are getters: read `useZoom().zoom` in your template or an effect and it tracks; destructure it (`const { zoom } = useZoom()`) and you copy the value once. Keep the object and read through it.
+
+## Licence
+
+[MIT](https://github.com/inkbar/inkbar/blob/main/LICENSE). From the team behind [Redactr](https://redactr.io).

package/dist/class-names.d.ts

@@ -0,0 +1,3 @@
+/** Joins class names, dropping empties. */
+export declare function cx(...parts: (string | undefined | null | false)[]): string | undefined;
+//# sourceMappingURL=class-names.d.ts.map

package/dist/class-names.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"class-names.d.ts","sourceRoot":"","sources":["../src/lib/class-names.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAC3C,wBAAgB,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,KAAK,CAAC,EAAE,GAAG,MAAM,GAAG,SAAS,CAGtF"}

package/dist/class-names.js

@@ -0,0 +1,5 @@
+/** Joins class names, dropping empties. */
+export function cx(...parts) {
+    const out = parts.filter(Boolean).join(' ');
+    return out === '' ? undefined : out;
+}

package/dist/components/InkAnnotation.svelte

@@ -0,0 +1,73 @@
+<script module lang="ts">
+  import type { Annotation } from '@inkbar/core'
+  import type { AnnotationSlotProps } from '@inkbar/core/dom'
+  import type { Snippet } from 'svelte'
+
+  export interface InkAnnotationProps {
+    annotation: Annotation
+    /** The overlay element; its `data-state` (which includes hover) drives `state`. */
+    element?: HTMLElement | undefined
+    children: Snippet<[AnnotationSlotProps]>
+  }
+</script>
+
+<script lang="ts">
+  /*
+   * Slot props for one annotation. It renders only its children: the overlay already draws the
+   * default visual for every annotation that is not custom, so this never draws a second one.
+   * InkPage portals it into the annotation's overlay element.
+   */
+  import { acceptSuggestion } from '@inkbar/core'
+
+  import { useInkContext } from '../context.js'
+
+  import type { AnnotationState } from '@inkbar/core/dom'
+
+  let { annotation, element, children }: InkAnnotationProps = $props()
+
+  const ctx = useInkContext('InkAnnotation')
+
+  function readState(el: HTMLElement): AnnotationState | null {
+    const s = el.dataset.state
+    return s === 'idle' || s === 'hover' || s === 'selected' ? s : null
+  }
+
+  let observed = $state.raw<AnnotationState | null>(null)
+  const observedEl = $derived(element)
+  $effect(() => {
+    const el = observedEl
+    if (!el) {
+      observed = null
+      return
+    }
+    observed = readState(el)
+    const observer = new MutationObserver(() => {
+      observed = readState(el)
+    })
+    observer.observe(el, { attributes: true, attributeFilter: ['data-state'] })
+    return () => observer.disconnect()
+  })
+
+  const isSuggestion = $derived(
+    annotation.type === 'redact' && annotation.origin === 'suggested'
+  )
+  const locked = $derived(annotation.locked === true)
+  const selected = $derived(ctx.selection.includes(annotation.id))
+  const store = () => ctx.document?.annotations
+  const slotProps = $derived<AnnotationSlotProps>({
+    annotation,
+    state: observed ?? (selected ? 'selected' : 'idle'),
+    locked,
+    select: () => store()?.select([annotation.id]),
+    remove: () => void store()?.remove(annotation.id),
+    accept: () => {
+      const s = store()
+      if (s && isSuggestion) acceptSuggestion(s, annotation.id)
+    },
+    dismiss: () => {
+      if (isSuggestion) store()?.remove(annotation.id)
+    },
+  })
+</script>
+
+{@render children(slotProps)}

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

@@ -0,0 +1,13 @@
+import type { Annotation } from '@inkbar/core';
+import type { AnnotationSlotProps } from '@inkbar/core/dom';
+import type { Snippet } from 'svelte';
+export interface InkAnnotationProps {
+    annotation: Annotation;
+    /** The overlay element; its `data-state` (which includes hover) drives `state`. */
+    element?: HTMLElement | undefined;
+    children: Snippet<[AnnotationSlotProps]>;
+}
+declare const InkAnnotation: import("svelte").Component<InkAnnotationProps, {}, "">;
+type InkAnnotation = ReturnType<typeof InkAnnotation>;
+export default InkAnnotation;
+//# sourceMappingURL=InkAnnotation.svelte.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"InkAnnotation.svelte.d.ts","sourceRoot":"","sources":["../../src/lib/components/InkAnnotation.svelte.ts"],"names":[],"mappings":"AAGE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAC9C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAC3D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAA;AAErC,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,UAAU,CAAA;IACtB,mFAAmF;IACnF,OAAO,CAAC,EAAE,WAAW,GAAG,SAAS,CAAA;IACjC,QAAQ,EAAE,OAAO,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAA;CACzC;AA2EH,QAAA,MAAM,aAAa,wDAAwC,CAAC;AAC5D,KAAK,aAAa,GAAG,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC;AACtD,eAAe,aAAa,CAAC"}

package/dist/components/InkNotePopover.svelte

@@ -0,0 +1,193 @@
+<script module lang="ts">
+  import type { NotePopoverSlotProps } from '@inkbar/core/dom'
+  import type { Snippet } from 'svelte'
+
+  export interface InkNotePopoverProps {
+    children?: Snippet<[NotePopoverSlotProps]> | undefined
+  }
+</script>
+
+<script lang="ts">
+  /*
+   * The thread for the activated note, anchored to the note's overlay element. Activating a
+   * reply opens the whole thread from its root. Closing (Close, Escape, a press outside) clears
+   * `activated`.
+   *
+   * A new note has no text. While its root is empty (and unlocked) the default form writes the
+   * root's own `contents`, labelled "Comment", and the thread list stays hidden until there is
+   * something in it; after that the form adds replies. Closing a root that is still empty and
+   * has no replies removes it, so an abandoned note does not stay on the page.
+   */
+  import { isAbandonedNote, threadOf, threadRoot } from '@inkbar/core'
+  import { Popover } from 'bits-ui'
+  import { untrack } from 'svelte'
+
+  import { useInkContext } from '../context.js'
+  import { useAnnotations } from '../hooks/useAnnotations.svelte.js'
+
+  import { useAnnotationElement } from './annotation-element.svelte.js'
+  import { keepOpenOnAnnotation, useFocusReturn } from './popover-focus.js'
+  import ThreadForm from './ThreadForm.svelte'
+
+  import type { Annotation, NoteAnnotation } from '@inkbar/core'
+
+  let { children }: InkNotePopoverProps = $props()
+
+  const ctx = useInkContext('InkNotePopover')
+  const store = useAnnotations()
+
+  const note = $derived.by<NoteAnnotation | null>(() => {
+    const a = ctx.activated
+      ? store.annotations.find((x) => x.id === ctx.activated)
+      : undefined
+    return a?.type === 'note' ? threadRoot(store.annotations, a) : null
+  })
+  const anchorRef = useAnnotationElement(
+    () => ctx.rootEl,
+    () => note?.id ?? null
+  )
+  const anchor = $derived(anchorRef.current)
+  const focusReturn = useFocusReturn(ctx)
+  const open = $derived(note !== null && anchor !== null)
+  /** The root, then every reply below it, depth first, each level in creation order. */
+  const thread = $derived<Annotation[]>(note ? threadOf(store.annotations, note) : [])
+  /** True while the default form writes the root note's own text rather than a reply. */
+  const editingRoot = $derived(note !== null && !note.locked && !note.contents?.trim())
+
+  /**
+   * Notes this popover wrote text or a reply for. In controlled mode the write is a proposal
+   * the host may not have applied yet, so the applied list still shows the note empty; these
+   * are never dropped as abandoned. Bookkeeping only: nothing renders from it.
+   */
+  // eslint-disable-next-line svelte/prefer-svelte-reactivity
+  const written = new Set<string>()
+  /** Notes this popover has already asked to remove, so a slow host is asked once. */
+  // eslint-disable-next-line svelte/prefer-svelte-reactivity
+  const dropped = new Set<string>()
+
+  /** Removes an unlocked root note with no text and no replies. True when it did. */
+  function dropIfEmpty(id: string): boolean {
+    if (dropped.has(id) || written.has(id) || !isAbandonedNote(store.annotations, id))
+      return false
+    dropped.add(id)
+    store.remove(id)
+    return true
+  }
+
+  // Activation moved on from a note that never got any text: drop it.
+  let previousId: string | undefined
+  $effect(() => {
+    const id = note?.id
+    const previous = previousId
+    if (previous === id) return
+    previousId = id
+    if (previous !== undefined) untrack(() => dropIfEmpty(previous))
+  })
+
+  function reply(text: string): void {
+    const root = note
+    const contents = text.trim()
+    if (!root || !contents) return
+    written.add(root.id)
+    store.add({
+      type: 'note',
+      page: root.page,
+      rect: root.rect,
+      contents,
+      inReplyTo: root.id,
+    })
+  }
+  function isEmptyRoot(root: NoteAnnotation): boolean {
+    return (
+      !written.has(root.id) &&
+      !root.locked &&
+      !root.contents?.trim() &&
+      thread.length === 1
+    )
+  }
+  function close(): void {
+    const root = note
+    if (root && store.annotations.some((a) => a.id === root.id) && isEmptyRoot(root)) {
+      focusReturn.beforeRemove(anchor)
+      dropIfEmpty(root.id)
+    }
+    ctx.setActivated(null)
+  }
+  function updateContents(contents: string): void {
+    if (!note || note.locked) return
+    if (contents.trim()) written.add(note.id)
+    store.update(note.id, { contents })
+  }
+  /** Locked notes cannot be removed: removing one does nothing and keeps the popover. */
+  function removeThread(): void {
+    const root = note
+    if (!root || root.locked) return
+    focusReturn.beforeRemove(anchor)
+    // Under a slow controlled host the note stays listed for a while; it is not asked for again.
+    dropped.add(root.id)
+    store.remove(root.id)
+    ctx.setActivated(null)
+  }
+  function onOpenChange(next: boolean): void {
+    if (!next) close()
+  }
+</script>
+
+<Popover.Root bind:open={() => open, onOpenChange}>
+  <Popover.Portal>
+    {#if note && anchor}
+      <Popover.Content
+        class="ink-note-popover"
+        data-ink-note-popover=""
+        role="dialog"
+        side="right"
+        sideOffset={8}
+        collisionPadding={8}
+        aria-label="Note thread"
+        customAnchor={anchor}
+        onInteractOutside={keepOpenOnAnnotation}
+        onOpenAutoFocus={focusReturn.onOpenAutoFocus}
+        onCloseAutoFocus={(e) => focusReturn.onCloseAutoFocus(e, anchor)}
+      >
+        {#if children}
+          {@render children({
+            note,
+            replies: thread.slice(1),
+            reply,
+            update: updateContents,
+            remove: removeThread,
+            close,
+          })}
+        {:else}
+          {#if !editingRoot || thread.length > 1}
+            <ol class="ink-thread" data-ink-thread="">
+              {#each thread as item (item.id)}
+                <li
+                  class="ink-thread-item"
+                  data-ink-thread-item=""
+                  data-reply={item.inReplyTo ? '' : undefined}
+                >
+                  <span class="ink-thread-author">{item.author ?? 'Anonymous'}</span>
+                  <time class="ink-thread-time" datetime={item.createdAt}>
+                    {new Date(item.createdAt).toLocaleString()}
+                  </time>
+                  <p class="ink-thread-text">{item.contents}</p>
+                </li>
+              {/each}
+            </ol>
+          {/if}
+          <!-- Keyed by note: moving to another note starts with an empty draft at once. -->
+          {#key note.id}
+            <ThreadForm
+              {editingRoot}
+              locked={!!note.locked}
+              onSubmit={(text) => (editingRoot ? updateContents(text) : reply(text))}
+              onRemove={removeThread}
+              onClose={close}
+            />
+          {/key}
+        {/if}
+      </Popover.Content>
+    {/if}
+  </Popover.Portal>
+</Popover.Root>

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

@@ -0,0 +1,9 @@
+import type { NotePopoverSlotProps } from '@inkbar/core/dom';
+import type { Snippet } from 'svelte';
+export interface InkNotePopoverProps {
+    children?: Snippet<[NotePopoverSlotProps]> | undefined;
+}
+declare const InkNotePopover: import("svelte").Component<InkNotePopoverProps, {}, "">;
+type InkNotePopover = ReturnType<typeof InkNotePopover>;
+export default InkNotePopover;
+//# sourceMappingURL=InkNotePopover.svelte.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"InkNotePopover.svelte.d.ts","sourceRoot":"","sources":["../../src/lib/components/InkNotePopover.svelte.ts"],"names":[],"mappings":"AAGE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AAC5D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAA;AAErC,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,OAAO,CAAC,CAAC,oBAAoB,CAAC,CAAC,GAAG,SAAS,CAAA;CACvD;AAwLH,QAAA,MAAM,cAAc,yDAAwC,CAAC;AAC7D,KAAK,cAAc,GAAG,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC;AACxD,eAAe,cAAc,CAAC"}

package/dist/components/InkPage.svelte

@@ -0,0 +1,125 @@
+<script module lang="ts">
+  import type { InkError } from '@inkbar/core'
+  import type { AnnotationSlotProps, PageMount } from '@inkbar/core/dom'
+  import type { Snippet } from 'svelte'
+
+  export interface InkPageProps {
+    page: number
+    host: HTMLElement
+    /** The engine's page mount in `host`. */
+    mount: PageMount
+    /** The engine's error for this page, `null` while it renders. */
+    error: InkError | null
+    /** Fixed for the life of the mount: the engine rebuilds when it changes. */
+    customAnnotations?: boolean
+    annotation?: Snippet<[AnnotationSlotProps]> | undefined
+    pageError?: Snippet<[{ error: InkError; page: number }]> | undefined
+  }
+</script>
+
+<script lang="ts">
+  /*
+   * One page the viewer engine mounted. Renders nothing visible in place; the portal attachment
+   * moves the page error into the host and each custom annotation's content into its overlay
+   * element.
+   *
+   * The overlay creates and removes those elements as the annotation list changes, outside
+   * Svelte. So the portal targets come from a list read after every overlay render: this
+   * component subscribes to the store after the overlay does (the engine created the mount
+   * first), and core notifies subscribers in order, so the elements already exist when the list
+   * arrives here.
+   *
+   * The engine tracks page errors and sets `data-state="error"` on the host; this component
+   * portals the page error into it while `error` is set.
+   */
+  import { untrack } from 'svelte'
+
+  import { useInkContext } from '../context.js'
+
+  import InkAnnotation from './InkAnnotation.svelte'
+  import { portal } from './portal.js'
+
+  import type { Annotation } from '@inkbar/core'
+
+  let {
+    page,
+    host,
+    mount,
+    error,
+    customAnnotations = false,
+    annotation,
+    pageError,
+  }: InkPageProps = $props()
+
+  interface Target {
+    annotation: Annotation
+    el: HTMLElement
+  }
+
+  function sameTargets(a: readonly Target[], b: readonly Target[]): boolean {
+    return (
+      a.length === b.length &&
+      a.every((t, i) => t.annotation === b[i]!.annotation && t.el === b[i]!.el)
+    )
+  }
+
+  const ctx = useInkContext('InkPage')
+  let targets = $state.raw<Target[]>([])
+
+  // Targets are read from the current mount, and read again when InkViewport hands this page a
+  // new one (the page left and came back within one tick, under the same key). The props are
+  // read through deriveds, which notify only when the value changes: InkViewport replaces this
+  // page's whole entry when its error changes, and that invalidates every prop without
+  // changing the mount.
+  const listPage = $derived(page)
+  const listMount = $derived(mount)
+  const listCustom = $derived(customAnnotations)
+  $effect(() => {
+    const p = listPage
+    const m = listMount
+    const custom = listCustom
+    const doc = untrack(() => ctx.document)
+    if (!doc || !custom) {
+      if (untrack(() => targets).length > 0) targets = []
+      return
+    }
+    const read = (): void => {
+      const next = doc.annotations.byPage(p).flatMap((a) => {
+        const el = m.overlay.elementFor(a.id)
+        return el ? [{ annotation: a, el }] : []
+      })
+      // A change elsewhere in the document leaves this page's targets as they were. The
+      // first read runs inside the effect, which must not come to depend on its own list.
+      if (
+        !sameTargets(
+          untrack(() => targets),
+          next
+        )
+      )
+        targets = next
+    }
+    const stop = doc.annotations.list.subscribe(read)
+    read()
+    return stop
+  })
+</script>
+
+{#if error}
+  <div hidden {@attach portal(host)}>
+    <div class="ink-page-error" data-ink-page-error="" role="alert">
+      {#if pageError}
+        {@render pageError({ error, page })}
+      {:else}
+        <p>Page {page + 1} could not be shown.</p>
+        <code class="ink-error-code">{error.code}</code>
+      {/if}
+    </div>
+  </div>
+{/if}
+{#if annotation}
+  {#each targets as t (t.annotation.id)}
+    <div hidden {@attach portal(t.el)}>
+      <InkAnnotation annotation={t.annotation} element={t.el} children={annotation} />
+    </div>
+  {/each}
+{/if}

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

@@ -0,0 +1,22 @@
+import type { InkError } from '@inkbar/core';
+import type { AnnotationSlotProps, PageMount } from '@inkbar/core/dom';
+import type { Snippet } from 'svelte';
+export interface InkPageProps {
+    page: number;
+    host: HTMLElement;
+    /** The engine's page mount in `host`. */
+    mount: PageMount;
+    /** The engine's error for this page, `null` while it renders. */
+    error: InkError | null;
+    /** Fixed for the life of the mount: the engine rebuilds when it changes. */
+    customAnnotations?: boolean;
+    annotation?: Snippet<[AnnotationSlotProps]> | undefined;
+    pageError?: Snippet<[{
+        error: InkError;
+        page: number;
+    }]> | undefined;
+}
+declare const InkPage: import("svelte").Component<InkPageProps, {}, "">;
+type InkPage = ReturnType<typeof InkPage>;
+export default InkPage;
+//# sourceMappingURL=InkPage.svelte.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"InkPage.svelte.d.ts","sourceRoot":"","sources":["../../src/lib/components/InkPage.svelte.ts"],"names":[],"mappings":"AAGE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AAC5C,OAAO,KAAK,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AACtE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAA;AAErC,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,WAAW,CAAA;IACjB,yCAAyC;IACzC,KAAK,EAAE,SAAS,CAAA;IAChB,iEAAiE;IACjE,KAAK,EAAE,QAAQ,GAAG,IAAI,CAAA;IACtB,4EAA4E;IAC5E,iBAAiB,CAAC,EAAE,OAAO,CAAA;IAC3B,UAAU,CAAC,EAAE,OAAO,CAAC,CAAC,mBAAmB,CAAC,CAAC,GAAG,SAAS,CAAA;IACvD,SAAS,CAAC,EAAE,OAAO,CAAC,CAAC;QAAE,KAAK,EAAE,QAAQ,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,GAAG,SAAS,CAAA;CACrE;AA4HH,QAAA,MAAM,OAAO,kDAAwC,CAAC;AACtD,KAAK,OAAO,GAAG,UAAU,CAAC,OAAO,OAAO,CAAC,CAAC;AAC1C,eAAe,OAAO,CAAC"}

package/dist/components/InkPageCount.svelte

@@ -0,0 +1,20 @@
+<script module lang="ts">
+  import type { HTMLAttributes } from 'svelte/elements'
+
+  export type InkPageCountProps = Omit<HTMLAttributes<HTMLSpanElement>, 'children'>
+</script>
+
+<script lang="ts">
+  import { usePage } from '../hooks/usePage.svelte.js'
+
+  let { class: className, ...rest }: InkPageCountProps = $props()
+
+  const page = usePage()
+</script>
+
+<span
+  class={['ink-page-count', className]}
+  data-ink-page-count=""
+  aria-live="polite"
+  {...rest}>of {page.count}</span
+>