@inkbar/core 0.8.0 → 0.10.0

package/dist/dom.d.mts

@@ -1,4 +1,4 @@
-import { A as DocumentSource, Bn as Point, Ct as AnnotationInput, D as InkStatus, Dt as AnnotationType, E as InkDocument, Hn as Rect, I as FormController, In as PageInfo, K as PluginHistory, Mt as FreeTextAnnotation, O as OpenOptions, R as InkError, Rn as PdfAssets, Sn as FormAction, Vn as Quad, Wt as LineEnding, X as AnnotationStore, Y as AnnotationEdit, Zt as NoteAnnotation, _ as ScopedToolStyle, _t as cssVariableDefaults, a as SignatureOptions, b as StyleProps, bt as Annotation, gt as AnnotationDefaults, h as CurrentStyle, i as SignatureLibrary, j as SearchHit, jn as Readable, mn as TextMarkupAnnotation, nt as RecordChange, o as SignatureStore, rt as RecordStore, s as SignatureTemplate, t as signField, tt as RecordBase, v as StyleGroup, x as ToolStyle, xn as FieldsMode, y as StyleKey, zn as Matrix } from "./sign-47QLNaqQ.mjs";
+import { A as DocumentSource, Bn as Matrix, Cn as FormAction, D as InkStatus, E as InkDocument, Gt as LineEnding, Hn as Quad, L as FormController, Ln as PageInfo, Mn as Readable, Nt as FreeTextAnnotation, O as OpenOptions, Ot as AnnotationType, P as isBlankQuery, Qt as NoteAnnotation, Sn as FieldsMode, Un as Rect, Vn as Point, X as AnnotationEdit, Z as AnnotationStore, _ as ScopedToolStyle, _t as AnnotationDefaults, a as SignatureOptions, b as StyleProps, h as CurrentStyle, hn as TextMarkupAnnotation, i as SignatureLibrary, it as RecordStore, j as SearchHit, nt as RecordBase, o as SignatureStore, q as PluginHistory, rt as RecordChange, s as SignatureTemplate, t as signField, v as StyleGroup, vt as cssVariableDefaults, wt as AnnotationInput, x as ToolStyle, xt as Annotation, y as StyleKey, z as InkError, zn as PdfAssets } from "./sign-BTbtPHbM.mjs";
 import { IconNode } from "@inkbar/icons";
 //#region src/dom/transform.d.ts
 type ViewRotation = 0 | 90 | 180 | 270;
@@ -162,6 +162,27 @@ interface ViewportKeysOptions {
  */
 export declare function attachViewportKeys(el: HTMLElement, opts: ViewportKeysOptions): () => void;
 //#endregion
+//#region src/dom/file-actions.d.ts
+interface DownloadOptions {
+  /** The name to save under. Default: the document's `fileName`. */
+  filename?: string;
+}
+/** Saves the document's file through the browser's download. */
+export declare function downloadDocument(doc: InkDocument, opts?: DownloadOptions): Promise<void>;
+/**
+ * Prints the document's file: it loads into a hidden frame and the browser's own PDF viewer
+ * prints it, so text stays sharp. Where a frame cannot print (iOS), the PDF opens in a new tab.
+ * Resolves once the print dialog has been asked for.
+ */
+export declare function printDocument(doc: InkDocument): Promise<void>;
+/**
+ * Ctrl or Cmd+P prints and Ctrl or Cmd+S downloads, for keys pressed anywhere inside `el`,
+ * while `doc()` gives a ready document. Then the key is taken from the browser, which would
+ * print or save the web page; otherwise it is left alone. Returns a function that removes the
+ * listener.
+ */
+export declare function attachFileKeys(el: HTMLElement, doc: () => InkDocument | null | undefined): () => void;
+//#endregion
 //#region src/dom/history-keys.d.ts
 /** A flag as a plain value, or as a readable such as core's `History.canUndo`. */
 type Flag = boolean | {
@@ -385,6 +406,8 @@ interface AnnotationLink<T extends RecordBase> {
 //#endregion
 //#region src/dom/plugins/api/records.d.ts
 interface Records<T extends RecordBase> {
+  /** The store's key, `<plugin>.<name>`. */
+  readonly key: string;
   /** The open document's records; `[]` while none is open. Emits when the document changes. */
   readonly list: Readable<readonly T[]>;
   all(): readonly T[];
@@ -432,6 +455,12 @@ interface CardSpec {
   swatch?: string;
   /** Text under the meta line (`.ink-card-body`). */
   body?: string;
+  /** A line of context with the match marked, after `body` (`.ink-card-excerpt`). */
+  excerpt?: {
+    before: string;
+    match: string;
+    after: string;
+  };
   /**
    * One button per key, in order (`.ink-card-actions`). The first takes focus on open and is
    * styled as the primary action. Each action runs synchronously in one undo step: writes after
@@ -463,9 +492,9 @@ interface MarksOptions<T extends RecordBase & {
   /** Classes every mark gets. */
   className?: string;
   /**
-   * More attributes (`data-*`, `aria-*`). `data-record`, `data-plugin` and `aria-label` stay
-   * core's, and so do `aria-haspopup` and `aria-expanded` on a mark with a card; `style`,
-   * `class` and `type` are skipped (use `style` and `className`).
+   * More attributes (`data-*`, `aria-*`). `data-record`, `data-plugin`, `data-selected` and
+   * `aria-label` stay core's, and so do `aria-haspopup` and `aria-expanded` on a mark with a
+   * card; `style`, `class` and `type` are skipped (use `style` and `className`).
    */
   attrs?(record: T): Record<string, string>;
   /**
@@ -541,6 +570,8 @@ interface ViewerSearch {
   setMatchCase(on: boolean): void;
   next(): void;
   previous(): void;
+  /** Makes hit `index` current and scrolls to it as `next()` does. Out of range or non-integer does nothing. */
+  select(index: number): void;
   /** Hides the bar and clears the hits; the query and match case are kept. */
   close(): void;
 }
@@ -580,9 +611,10 @@ interface ToolOptions {
 export declare function createToolOptions(tools?: readonly Tool[]): ToolOptions;
 //#endregion
 //#region src/dom/tools/controller.d.ts
-type BuiltinToolId = 'select-text' | 'select' | 'highlight' | 'redact-area' | 'note' | 'shape' | 'freetext' | 'draw' | 'sketch' | 'signature';
-/** A built-in tool's id, or any id a host registers its own tool under. */
-type ToolId = BuiltinToolId | (string & {});
+/** The tools every viewer has. Creation tools are the host's to pass. */
+type CoreToolId = 'select-text' | 'select';
+/** A core tool's id, or any id a host registers a tool under. */
+type ToolId = CoreToolId | (string & {});
 /**
  * A one-shot tool switches back to `select-text` once it has made something and the user moves
  * on; a sticky tool stays on. A tool without a kind is sticky.
@@ -875,6 +907,47 @@ interface PluginLayers {
  */
 export declare function createPluginLayers(source: LayerSource): PluginLayers;
 //#endregion
+//#region src/dom/plugins/registry.d.ts
+/** What one `plugin.marks` call drew its records with. */
+interface MarksRegistration<T extends RecordBase & {
+  page: number;
+} = any> {
+  /** The id of the plugin that called `marks`. */
+  plugin: string;
+  /** Whether `record` gets a mark from this call. */
+  where(record: T): boolean;
+  label(record: T): string;
+  rect(record: T): Rect;
+  card?(record: T): CardSpec;
+  className?: string;
+  style?: MarksOptions<T>['style'];
+  /** The plugin's `history.batch`: everything `fn` changes is one undo step. */
+  batch(fn: () => void): void;
+}
+interface MarksRegistry {
+  /** Registers `reg` under `key`; returns a function that removes it. */
+  add(key: string, reg: MarksRegistration): () => void;
+  /** Registrations for `key`, in call order. */
+  of(key: string): readonly MarksRegistration[];
+  /** The first registration whose `where` passes, or undefined. */
+  resolve<T extends RecordBase & {
+    page: number;
+  }>(key: string, record: T): MarksRegistration<T> | undefined;
+  /** Keys that have registrations. */
+  keys(): readonly string[];
+  /** Calls `listener` after every add and remove; returns a stop function. */
+  watch(listener: () => void): () => void;
+}
+interface RecordSelection {
+  /** The selected record's id, or null. */
+  readonly selected: Readable<string | null>;
+  /**
+   * Selects the record with `id`, or clears with null. An id the open document's store lacks,
+   * or whose record resolves to no registration, changes nothing.
+   */
+  select(id: string | null): void;
+}
+//#endregion
 //#region src/dom/plugins/host.d.ts
 interface PluginHostOptions {
   plugins: readonly InkPlugin[];
@@ -891,7 +964,31 @@ interface PluginHostOptions {
   /** The viewer's search; without one, `ctx.search` is inert. */
   search?: ViewerSearch;
 }
+/**
+ * A plugin's records as the host app sees them: the plugin's own handle without `annotates`
+ * (a plugin links its records to marks in `setup`), plus `batch` to make several writes one
+ * undo step. `in(doc)` gives a host handle too.
+ */
+type HostRecords<T extends RecordBase> = Omit<Records<T>, 'annotates' | 'in'> & {
+  /** The same handle bound to `doc`'s store, as `Records.in` binds it. */
+  in(doc: InkDocument): HostRecords<T>;
+  /** Makes everything `fn` changes one undo step. */
+  batch(fn: () => void): void;
+};
 interface PluginHost extends LayerSource {
+  /**
+   * The records a plugin keeps under `key` (`<plugin>.<name>`), following the open document.
+   * The same handle on each call. An unknown key gives an empty handle that ignores writes, and
+   * logs a warning once.
+   */
+  records<T extends RecordBase>(key: string): HostRecords<T>;
+  /** What each `plugin.marks` call drew, by records key. */
+  readonly marks: MarksRegistry;
+  /**
+   * The selected record under `key`, shared by the marks, every list and the host app. The
+   * same object on each call.
+   */
+  selection(key: string): RecordSelection;
   readonly commands: ReadonlyMap<string, Command>;
   command(id: string): Command | undefined;
   readonly tools: readonly Tool[];
@@ -1010,6 +1107,9 @@ interface PageMount {
  */
 export declare function createPageMount(opts: PageMountOptions): PageMount;
 //#endregion
+//#region src/dom/tools/draw.d.ts
+export declare function drawTool(): Tool;
+//#endregion
 //#region src/dom/tools/freetext.d.ts
 /** Width of a box placed with a click or Enter, user-space points. */
 export declare const DEFAULT_FREETEXT_WIDTH = 144;
@@ -1081,12 +1181,28 @@ export declare function shapeTool(): Tool<ShapeOptions>;
 //#region src/dom/tools/signature.d.ts
 export declare function signatureTool(): Tool<SignatureOptions>;
 //#endregion
+//#region src/dom/tools/sketch.d.ts
+export declare function sketchTool(): Tool;
+//#endregion
+//#region src/dom/tools/unknown.d.ts
+/**
+ * The error for a tool id nobody registered, naming the ids that were. The tool controller logs
+ * it rather than throw, so a toolbar naming a missing tool shows the control as it is.
+ */
+export declare function unknownTool(id: ToolId, registered: readonly ToolId[]): InkError;
+//#endregion
 //#region src/dom/tools/index.d.ts
-/** Fresh instances of every built-in tool. */
-export declare function builtinTools(): Tool[];
-/** The built-in tools with a host's tools added, a host tool replacing a built-in by id. */
+/** Fresh instances of every creation tool, in toolbar order. */
+export declare function allTools(): Tool[];
+/**
+ * `select-text` and `select` with a host's tools added by id, a later tool replacing an earlier
+ * one with its id.
+ */
 export declare function withHostTools(host?: readonly Tool[]): Tool[];
-/** Listens on `ctx.root` and routes pointer and key events to the active tool. */
+/**
+ * Listens on `ctx.root` and routes pointer and key events to the active tool. Without `tools`
+ * it has only `select-text` and `select`.
+ */
 export declare function createToolController(opts: Omit<ToolControllerOptions, 'tools'> & {
   tools?: Tool[];
 }): ToolController;
@@ -1097,7 +1213,7 @@ interface ToolStyleTracker {
 }
 /**
  * A `ToolStyle` whose active group is the style group of the active tool among `tools` (the
- * built-ins plus a host's). The engine makes one when it is not handed a style; a binding
+ * select tools plus a host's). The engine makes one when it is not handed a style; a binding
  * makes its own per document, so its style controls work before the viewport mounts.
  */
 export declare function trackToolStyle(opts: {
@@ -1105,15 +1221,15 @@ export declare function trackToolStyle(opts: {
   history: {
     batch(fn: () => void): void;
   };
-  /** Host tools, as passed to `mountViewer`. */
+  /** The creation tools, as passed to `mountViewer`. */
   tools?: readonly Tool[] | undefined;
   tool?: ToolId | undefined;
 }): ToolStyleTracker;
 //#endregion
 //#region src/dom/ui.d.ts
 /**
- * Accessible names of the built-in tools, as the toolbar buttons announce them. A host tool has
- * no entry: its button takes the host's `label`, else the tool id.
+ * Accessible names of the two core select tools, as the toolbar buttons announce them. Every
+ * other tool has no entry: its button takes the tool's own `label`, else the tool id.
  */
 export declare const TOOL_LABELS: Readonly<Partial<Record<ToolId, string>>>;
 /**
@@ -1594,8 +1710,9 @@ interface MountViewerOptions {
   buffer?: number;
   tool?: ToolId;
   /**
-   * Host tools, added to the built-ins. A host tool with a built-in's id replaces it. The same
-   * instances are reused when the engine rebuilds.
+   * The creation tools (`allTools()`, or the ones the host imports); `select-text` and `select`
+   * are always present. A later tool replaces an earlier one with its id, so a host tool can
+   * replace a core one. The same instances are reused when the engine rebuilds.
    */
   tools?: Tool[];
   /**
@@ -1761,8 +1878,21 @@ interface CreateViewerOptions extends Omit<MountViewerOptions, 'container' | 'do
    * Form field values; defaults to uncontrolled, starting from the PDF's. Controlled:
    * `{ mode: 'controlled', initial, onChange }`, where `onChange` hears every commit with the
    * full map and the host pushes back with `viewer.form.get()?.setControlledValue(next)`.
+   * `initial` applies to every document the viewer opens; push your values once the new one is ready.
    */
   fields?: FieldsMode;
+  /**
+   * The annotation list; defaults to uncontrolled. Controlled: `{ mode: 'controlled', initial,
+   * onChange }`, where the host owns the session annotations and `onChange` hears every
+   * proposed list. Nothing shows until the host pushes it back with
+   * `viewer.document.get()?.annotations.setControlledValue(next)`. Embedded annotations stay in
+   * the file and never pass through `onChange`. `initial` applies to every document the viewer
+   * opens, including after `viewer.open()`. A host that keeps its own list pushes it with
+   * `viewer.document.get()?.annotations.setControlledValue(list)` once the new document is
+   * ready (in `onReady`). Undo and redo history is inert in controlled
+   * mode: the host owns the list, so it owns undo too.
+   */
+  annotations?: OpenOptions['annotations'];
   /**
    * Plugins, set up once for the viewer's life. Their tools join the viewer's tools, their
    * decoration and page layers apply to every document, and their commands are placed with
@@ -1816,6 +1946,11 @@ interface Viewer {
    * `open()` runs the search and draws the highlights even when no find bar is mounted.
    */
   readonly search: ViewerSearch;
+  /**
+   * The records a plugin keeps under `key` (`<plugin>.<name>`), following the open document;
+   * the same handle on each call. An unknown key gives an empty handle and logs a warning once.
+   */
+  records<T extends RecordBase>(key: string): HostRecords<T>;
   /**
    * Opens another document in place; the previous one is destroyed. Latest call wins.
    * `password` is used for this load only; without it, the constructor's `password` applies.
@@ -1823,6 +1958,18 @@ interface Viewer {
   open(source: DocumentSource, opts?: {
     password?: string;
   }): void;
+  /**
+   * Saves the open document's file through the browser's download, under its `fileName` or
+   * `opts.filename`. Today that is the file as it was opened, without this session's
+   * annotations. Does nothing while no document is open.
+   */
+  download(opts?: DownloadOptions): Promise<void>;
+  /**
+   * Prints the open document's file with the browser's own PDF viewer; on iOS the PDF opens
+   * in a new tab instead. As with `download`, today that is the file as it was opened. Does
+   * nothing while no document is open.
+   */
+  print(): Promise<void>;
   destroy(): void;
 }
 export declare function createViewer(el: HTMLElement, opts: CreateViewerOptions): Viewer;
@@ -1851,6 +1998,14 @@ export declare function pageSelectionText(root: HTMLElement): string;
  * @internal Shared with the framework bindings.
  */
 export declare function handleFindKey(e: KeyboardEvent, controller: SearchController, selection: () => string): boolean;
+/**
+ * Enter in a search field other than the find bar's (the search results' own): steps to the
+ * next match, Shift+Enter to the previous, as in the find bar. Returns whether it handled the
+ * key; when it did, the default is prevented.
+ *
+ * @internal Shared with the framework bindings.
+ */
+export declare function handleResultsFieldKey(e: KeyboardEvent, search: Pick<ViewerSearch, 'next' | 'previous'>): boolean;
 //#endregion
 //#region src/dom/search/find-text.d.ts
 /**
@@ -1871,6 +2026,325 @@ export declare function findCountText(s: SearchState): string;
  */
 export declare function findAnnouncer(): (s: SearchState) => string;
 //#endregion
+//#region src/dom/records/source.d.ts
+/** One thing a list shows: an id unique in the list, its 0-based page, and where on it. */
+interface ListItem {
+  id: string;
+  page: number;
+  /** In user space. */
+  rect?: Rect;
+}
+interface RecordListSource<I extends ListItem = ListItem> {
+  /** What is listed, filtered and in order. */
+  readonly items: Readable<readonly I[]>;
+  /** The card `item` shows, or null for none. */
+  card(item: I): CardSpec | null;
+  /** The selected item's id, or null. */
+  readonly selected: Readable<string | null>;
+  select(id: string | null): void;
+  /** Scrolls the viewport to the item; for records, to its mark's rect. */
+  reveal(item: I): void;
+  /** Runs an action as one undo step. */
+  run(item: I, fn: () => void): void;
+  /**
+   * Whether the change to `items` being emitted came from undo or redo, or from another
+   * document opening: a change nobody made from the list, which the list does not announce.
+   */
+  readonly replaying: () => boolean;
+  /**
+   * Polite text to announce, in place of the list's own "N items". A source whose items change
+   * as a scan runs announces once it settles.
+   */
+  readonly announcement?: Readable<string>;
+}
+interface RecordsSourceOptions<T> {
+  /** The card each record shows. Default: its mark's card, else its mark's label (or id) and no actions. */
+  card?(record: T): CardSpec;
+  /** Which records to list. Default: those that have a mark, or every record when no `marks` call covers them. */
+  where?(record: T): boolean;
+  /** The order. Default: page, then top to bottom and left to right by the mark's rect. */
+  sort?(a: T, b: T): number;
+}
+interface RecordsSourceDeps {
+  pluginHost: PluginHost;
+  /** The viewport `reveal` scrolls; null while none is mounted. */
+  viewport: Readable<Viewport | null>;
+}
+/**
+ * The records a plugin keeps under `key` (`<plugin>.<name>`), as its marks show them: each
+ * record takes its card, label and rect from the first `marks` registration whose `where` it
+ * passes, and its actions run in that plugin's undo step. Follows the open document. The
+ * selection is the host's for `key`, shared with the marks and every other list.
+ */
+export declare function recordsSource<T extends RecordBase & {
+  page: number;
+}>(deps: RecordsSourceDeps, key: string, opts?: RecordsSourceOptions<T>): RecordListSource<T>;
+export declare function searchSource(search: ViewerSearch): RecordListSource;
+//#endregion
+//#region src/dom/records/list.d.ts
+interface RecordListRow {
+  item: ListItem;
+  card: CardSpec | null;
+  selected: boolean;
+}
+interface RecordListController {
+  /** One per listed item, in order. */
+  readonly rows: Readable<readonly RecordListRow[]>;
+  readonly count: Readable<number>;
+  /** Polite live-region text: "3 items" when a change made from the app adds or removes rows. */
+  readonly announcement: Readable<string>;
+  /**
+   * Binds the element holding the rows: each row is an element with `data-ink-record` set to
+   * its item's id. Handles clicks, arrow keys, Home and End, Enter and Escape inside it, keeps
+   * one row as the Tab stop (it sets the rows' `tabindex`: don't render one), and scrolls the
+   * selected row into view. `el` is where focus goes when the last row goes; it gets
+   * `tabindex="-1"` unless it has one. Attaching another element unbinds the previous one.
+   * Returns the unbind.
+   */
+  attach(el: HTMLElement): () => void;
+  /** Selects the item and scrolls the viewport to it; focus stays where it is. */
+  choose(id: string): void;
+  /** Runs the card action named `action` of item `id` as one undo step. */
+  act(id: string, action: string): void;
+  destroy(): void;
+}
+export declare function createRecordListController(source: RecordListSource): RecordListController;
+/**
+ * The records a plugin keeps under `records` (`<plugin>.<name>`) as a list of cards, the same
+ * cards its marks open, with their actions. Selecting a card selects the record's mark and
+ * scrolls the viewer to it; activating a mark selects its card. Give it a height (it fills its
+ * parent's) and place it anywhere, a sidebar panel for instance. It stops when the viewer is
+ * destroyed.
+ */
+export declare function createRecordList(viewer: Viewer, opts: {
+  records: string;
+} & RecordsSourceOptions<any>): HTMLElement;
+//#endregion
+//#region src/dom/records/search-results.d.ts
+interface SearchResultsOptions {
+  /** Show a query field above the results. Default true; turn it off when a find bar is on the page. */
+  field?: boolean;
+}
+/**
+ * One card per search hit: its page, its place on that page and the text around it. Choosing
+ * a card makes its hit current, as the find bar's next and previous do, and the find bar's
+ * current hit is the selected card. The count shows the scan's progress and "No results". It stops when the
+ * viewer is destroyed.
+ */
+export declare function createSearchResults(viewer: Viewer, opts?: SearchResultsOptions): HTMLElement;
+//#endregion
+//#region src/dom/sidebar/controller.d.ts
+type SidebarLayout = 'rail' | 'tabs' | 'stack';
+type SidebarSide = 'left' | 'right';
+interface SidebarPanelInfo {
+  id: string;
+  label: string;
+  icon?: IconNode;
+  /** Hidden when empty or 0. */
+  badge?: string | number;
+}
+/** rail/tabs: the open id or null; stack: the expanded ids. */
+type SidebarOpen = string | null | readonly string[];
+interface SidebarControllerOptions {
+  /** Default `'rail'`. */
+  layout?: SidebarLayout;
+  /** Default `'left'`. */
+  side?: SidebarSide;
+  panels: readonly SidebarPanelInfo[];
+  /** Controlled when given: `toggle` only reports through `onOpenChange`. */
+  open?: SidebarOpen;
+  onOpenChange?(open: SidebarOpen): void;
+  /**
+   * Default true. False hides the whole sidebar (the root gets `hidden`) and keeps its open
+   * panels, their content and scroll, for when it shows again. Your code decides: a results
+   * sidebar shown only while there are results, for instance.
+   */
+  visible?: boolean;
+  /**
+   * True while a binding's panels are still registering, one by one, before it has mounted.
+   * Meanwhile a controlled `open` id not in `panels` yet is kept rather than taken for a
+   * removed panel, and `rootAttrs()` reports the open state expected once they are all in.
+   * Set it back to false (through `update`) once the panels are in: an id still missing then
+   * falls back as a removed one does.
+   */
+  pending?: boolean;
+  /**
+   * Makes the ids `<idPrefix>-trigger-<id>` and `<idPrefix>-panel-<id>`, the same on the server
+   * and the client. Without it they come from a counter.
+   */
+  idPrefix?: string;
+}
+interface SidebarState {
+  layout: SidebarLayout;
+  side: SidebarSide;
+  panels: readonly SidebarPanelInfo[];
+  /** The open panels' ids, in panel order: at most one for rail and tabs. */
+  open: readonly string[];
+  visible: boolean;
+}
+interface SidebarController {
+  readonly state: Readable<SidebarState>;
+  /**
+   * Takes new options. `open` given makes the sidebar controlled. When the panels no longer
+   * hold an open one, rail and tabs open the first remaining and stack drops it; the new value
+   * goes to `onOpenChange`, controlled or not.
+   */
+  update(opts: Partial<SidebarControllerOptions>): void;
+  /** What activating `id`'s trigger does: rail opens or closes, tabs switch, stack expands or collapses. */
+  toggle(id: string): void;
+  isOpen(id: string): boolean;
+  /**
+   * `data-ink-sidebar`, `data-layout`, `data-side` and `data-state` (`open` while any panel is,
+   * and while pending and uncontrolled, as the first panel will open) for the root, and
+   * `hidden` while it is not `visible`.
+   */
+  rootAttrs(): Record<string, string>;
+  /** ARIA for the element holding the triggers: a tablist for rail and tabs. */
+  tablistAttrs(): Record<string, string>;
+  /** ARIA for the rail button / tab / stack header of `id`. */
+  triggerAttrs(id: string): Record<string, string>;
+  /**
+   * ARIA for `id`'s panel, including `hidden` when closed, and its sidebar's `data-layout`: the
+   * theme shows the panel's title (`.ink-sidebar-panel-title`) in the rail only.
+   */
+  panelAttrs(id: string): Record<string, string>;
+  /**
+   * Roving tabindex, arrow keys, Home and End, and clicks over `[data-ink-sidebar-trigger]`
+   * inside `el`, looked up at event time so re-rendered triggers keep working. Returns the
+   * function that unbinds.
+   */
+  bindTriggers(el: HTMLElement): () => void;
+  destroy(): void;
+}
+/** The text a badge shows, or null when it is hidden (empty or 0). */
+export declare function sidebarBadge(badge: string | number | undefined): string | null;
+export declare function createSidebarController(opts: SidebarControllerOptions): SidebarController;
+//#endregion
+//#region src/dom/sidebar/sidebar.d.ts
+/**
+ * A sidebar of `opts.panels` in `opts.layout` (`'rail'` by default) on `opts.side`, showing
+ * `opts.content[id]` in each panel. Returns the root element and its controller, which opens
+ * panels from code (`toggle`, `update({ open })`) and takes new panels or a new layout.
+ */
+export declare function createSidebar(opts: SidebarControllerOptions & {
+  content: Record<string, HTMLElement>;
+}): {
+  element: HTMLElement;
+  controller: SidebarController;
+};
+//#endregion
+//#region src/dom/thumbnails/thumbnail.d.ts
+/** Width in CSS pixels when neither `width` nor `height` is given; the theme's `--ink-thumbnail-width`. */
+export declare const THUMBNAIL_WIDTH = 120;
+interface ThumbnailDeps {
+  document: Readable<InkDocument | null>;
+  /** Where plugin marks come from. Without it, the thumbnail draws no marks. */
+  pluginHost?: Readable<PluginHost | null>;
+}
+interface ThumbnailOptions {
+  /** Zero-based page index. */
+  page: number;
+  /** Width in CSS pixels; the height follows the page's shape. Wins over `height`. */
+  width?: number | undefined;
+  /** Height in CSS pixels, used when `width` is absent; the width follows the page's shape. */
+  height?: number | undefined;
+  /** Draw the page's annotations. Default true. */
+  annotations?: boolean | undefined;
+  /** Draw plugin marks. Default true. */
+  marks?: boolean | undefined;
+  /** The accessible name. Default "Page N", N being `page + 1`. */
+  label?: string | undefined;
+}
+interface ThumbnailPainter {
+  /** Applies changed options; the others stay as they were. An option given as `undefined` goes back to its default. */
+  update(opts: Partial<ThumbnailOptions>): void;
+  /** Stops painting and removes everything the painter added to the element. */
+  destroy(): void;
+}
+/** CSS size and zoom for `page` fitted to width or height (width wins when both), /Rotate applied. */
+export declare function thumbnailSize(page: PageInfo, size: {
+  width?: number | undefined;
+  height?: number | undefined;
+}): {
+  width: number;
+  height: number;
+  zoom: number;
+};
+/**
+ * Paints page `opts.page` of the open document into `el`. The element keeps its own children
+ * and classes; the painter appends its layers after them.
+ */
+export declare function createThumbnailPainter(el: HTMLElement, deps: ThumbnailDeps, initial: ThumbnailOptions): ThumbnailPainter;
+/**
+ * A thumbnail of page `opts.page` of `viewer`'s open document, with its annotations and plugin
+ * marks. Place it anywhere; it stops when the viewer is destroyed.
+ */
+export declare function createThumbnail(viewer: Viewer, opts: ThumbnailOptions): HTMLElement;
+//#endregion
+//#region src/dom/thumbnails/list.d.ts
+interface ThumbnailsDeps extends ThumbnailDeps {
+  /** The viewport whose current page the list follows; null while none is mounted. */
+  viewport: Readable<Viewport | null>;
+}
+interface ThumbnailsOptions {
+  /** Zero-based pages to list, in this order. Default: every page. Missing pages and repeats are dropped. */
+  pages?: readonly number[] | undefined;
+  /**
+   * Thumbnail width in CSS pixels. Default: the list's width less a 16px gutter on each side,
+   * following the list as it resizes (`THUMBNAIL_WIDTH` until the list is attached and shown).
+   */
+  width?: number | undefined;
+  /** Draw each page's annotations. Default true. */
+  annotations?: boolean | undefined;
+  /** Draw plugin marks. Default true. */
+  marks?: boolean | undefined;
+}
+interface ThumbnailsState {
+  /** What is listed: zero-based pages, in list order. */
+  pages: readonly number[];
+  /** The viewport's current page, -1 with no viewport. */
+  current: number;
+  /** Indexes into `pages` to mount, `end` exclusive. Empty until `attach`. */
+  window: {
+    start: number;
+    end: number;
+  };
+  /** Top of each item in CSS px from the top of the list; the last entry is the total height. */
+  offsets: readonly number[];
+  /** The width each thumbnail is drawn at, in CSS px: `width`, else the measured fit. */
+  width: number;
+}
+interface ThumbnailsController {
+  readonly state: Readable<ThumbnailsState>;
+  /** Applies changed options; the others stay as they were. */
+  update(opts: Partial<ThumbnailsOptions>): void;
+  /**
+   * Binds the list's scroll element: the element that scrolls, with item `i` positioned at
+   * `offsets[i]` from the top of its content. Follows its scrolling and size to move the
+   * window, and handles clicks, keys and the Tab stop over `[data-ink-thumbnail-item]` buttons
+   * inside it (`data-ink-thumbnail-item` is the page). It sets the items' `tabindex`: don't
+   * render one. Attaching another element unbinds the previous one. Returns the unbind.
+   */
+  attach(scroller: HTMLElement): () => void;
+  /**
+   * The attributes of the list item wrapping item `index` (into `pages`): `role="listitem"`
+   * and, as only the window is mounted, `aria-setsize` and `aria-posinset` for its place in
+   * the whole list.
+   */
+  itemAttrs(index: number): Record<string, string>;
+  /** Scrolls the viewport to `page`. */
+  activate(page: number): void;
+  destroy(): void;
+}
+export declare function createThumbnailsController(deps: ThumbnailsDeps, initial?: ThumbnailsOptions): ThumbnailsController;
+/**
+ * A scrolling list of `viewer`'s pages as thumbnails. Give it a height (it fills its parent's)
+ * and place it anywhere, a sidebar panel for instance. Each item is a button that scrolls the
+ * viewer to its page; the current page is marked and kept in view. It stops when the viewer
+ * is destroyed.
+ */
+export declare function createThumbnails(viewer: Viewer, opts?: ThumbnailsOptions): HTMLElement;
+//#endregion
 //#region src/dom/viewer/controls.d.ts
 /**
  * An `<svg>` drawing `icon` from `@inkbar/icons`, hidden from assistive technology: the
@@ -1892,13 +2366,25 @@ export declare function createToolbar(opts?: {
 }): HTMLElement;
 /** A divider between groups of controls in a horizontal toolbar. Not focusable. */
 export declare function createToolbarSeparator(): HTMLDivElement;
+/**
+ * Saves the document's file (`viewer.download()`); disabled until a document is ready. Today
+ * that is the file as it was opened, without this session's annotations.
+ */
+export declare function createDownloadButton(viewer: Viewer, opts?: DownloadOptions): HTMLButtonElement;
+/**
+ * Prints the document's file (`viewer.print()`); disabled until a document is ready. Today
+ * that is the file as it was opened, without this session's annotations.
+ */
+export declare function createPrintButton(viewer: Viewer): HTMLButtonElement;
 /** Undoes the last change to the document's annotations; disabled when there is none. */
 export declare function createUndo(viewer: Viewer): HTMLButtonElement;
 /** Redoes the last undone change; disabled when there is none. */
 export declare function createRedo(viewer: Viewer): HTMLButtonElement;
 /**
- * Sets the tool; pressed while it is the active one. A host or plugin tool's button takes the
- * tool's own `label` and `icon`; `opts.label` wins, and without either it is named by the tool id.
+ * Sets the tool; pressed while it is the active one. A creation, host or plugin tool's button
+ * takes the tool's own `label` and `icon`; `opts.label` wins, and without either it is named by
+ * the tool id. For an id no tool registered it logs `InkError('UnknownTool')` to the console and
+ * returns the same markup disabled, `aria-hidden` and unnamed.
  */
 export declare function createToolButton(viewer: Viewer, tool: ToolId, opts?: {
   label?: string;
@@ -2167,5 +2653,5 @@ interface FormAlert {
  */
 export declare function createFormAlert(root: HTMLElement): FormAlert;
 //#endregion
-export { type AnnotationDecoration, type AnnotationInputOf, type AnnotationLink, type AnnotationLinkSpec, type AnnotationSlotProps, type AnnotationState, type ArrowheadChoice, type BuiltinToolId, type CardSpec, type ColorMenuModel, type ColorMenuOptions, type ColorMenuSwatch, type ColorProperty, type ColorTrigger, type Command, type CommandOptions, type CommandRun, type CommandSpec, type CreateViewerOptions, type CssLayout, type CssLayoutInput, type CssPageBox, type CssRect, type CurrentStyle, type DecorateAnnotation, type EditorCloseReason, type FocusReturn, type FocusReturnOptions, type FormAlert, type FormLayer, type FreeTextEditor, type FreeTextEditorOptions, type HighlightMenuItem, type HighlightMenuModel, type HighlightOptions, type HistoryKeysTarget, type InkPlugin, type LayerEvent, type LayerSource, type LayerSpec, type LayoutMode, type LineStyleMenuItem, type LineStyleMenuModel, type LineStyleMenuSection, type MarksHandle, type MarksOptions, type MarkupKind, type Menu, type MenuOptions, type MountViewerOptions, type Overlay, type OverlayOptions, type PageHit, type PageLayer, type PageLayers, type PageMount, type PageMountOptions, type PageRenderer, type PageRendererOptions, type PageTransform, type Palette, type PluginApi, type PluginContext, type PluginHost, type PluginHostOptions, type PluginLayer, type PluginLayerHandle, type PluginLayers, type PluginOptions, type PluginStoreOptions, type Popover, type PopoverOptions, type Records, type ScopedToolStyle, type SearchController, type SearchControllerOptions, type SearchState, type SelectionQuads, type ShapeKind, type ShapeMenuItem, type ShapeMenuModel, type ShapeOptions, type SignFieldMenu, type SignFieldMenuOptions, type SignFieldRequest, type SignatureDialog, type SignatureDialogOptions, type SignatureDraft, type SignatureDraftState, type SignatureMenuItem, type SignatureMenuModel, type SignatureOptions, type SignaturePad, type SignatureTab, type StyleGroup, type StyleKey, type StyleProps, type TextAlignChoice, type TextAlignKey, type TextLayerHandle, type TextLayerOptions, type TextStyleMenuModel, type TextStyleToggle, type TextToggleKey, type ThreadPopoverSlotProps, type Tool, type ToolContext, type ToolController, type ToolControllerOptions, type ToolId, type ToolKind, type ToolOptions, type ToolStyle, type ToolStyleTracker, type TypedSignatureOptions, type ViewRotation, type Viewer, type ViewerEngine, type ViewerSearch, type Viewport, type ViewportHit, type ViewportKeysOptions, type ViewportOptions, type ZoomValue, cssVariableDefaults, signField };
+export { type AnnotationDecoration, type AnnotationInputOf, type AnnotationLink, type AnnotationLinkSpec, type AnnotationSlotProps, type AnnotationState, type ArrowheadChoice, type CardSpec, type ColorMenuModel, type ColorMenuOptions, type ColorMenuSwatch, type ColorProperty, type ColorTrigger, type Command, type CommandOptions, type CommandRun, type CommandSpec, type CoreToolId, type CreateViewerOptions, type CssLayout, type CssLayoutInput, type CssPageBox, type CssRect, type CurrentStyle, type DecorateAnnotation, type DownloadOptions, type EditorCloseReason, type FocusReturn, type FocusReturnOptions, type FormAlert, type FormLayer, type FreeTextEditor, type FreeTextEditorOptions, type HighlightMenuItem, type HighlightMenuModel, type HighlightOptions, type HistoryKeysTarget, type HostRecords, type InkPlugin, type LayerEvent, type LayerSource, type LayerSpec, type LayoutMode, type LineStyleMenuItem, type LineStyleMenuModel, type LineStyleMenuSection, type ListItem, type MarksHandle, type MarksOptions, type MarksRegistration, type MarksRegistry, type MarkupKind, type Menu, type MenuOptions, type MountViewerOptions, type Overlay, type OverlayOptions, type PageHit, type PageLayer, type PageLayers, type PageMount, type PageMountOptions, type PageRenderer, type PageRendererOptions, type PageTransform, type Palette, type PluginApi, type PluginContext, type PluginHost, type PluginHostOptions, type PluginLayer, type PluginLayerHandle, type PluginLayers, type PluginOptions, type PluginStoreOptions, type Popover, type PopoverOptions, type RecordListController, type RecordListRow, type RecordListSource, type RecordSelection, type Records, type RecordsSourceDeps, type RecordsSourceOptions, type ScopedToolStyle, type SearchController, type SearchControllerOptions, type SearchResultsOptions, type SearchState, type SelectionQuads, type ShapeKind, type ShapeMenuItem, type ShapeMenuModel, type ShapeOptions, type SidebarController, type SidebarControllerOptions, type SidebarLayout, type SidebarOpen, type SidebarPanelInfo, type SidebarSide, type SidebarState, type SignFieldMenu, type SignFieldMenuOptions, type SignFieldRequest, type SignatureDialog, type SignatureDialogOptions, type SignatureDraft, type SignatureDraftState, type SignatureMenuItem, type SignatureMenuModel, type SignatureOptions, type SignaturePad, type SignatureTab, type StyleGroup, type StyleKey, type StyleProps, type TextAlignChoice, type TextAlignKey, type TextLayerHandle, type TextLayerOptions, type TextStyleMenuModel, type TextStyleToggle, type TextToggleKey, type ThreadPopoverSlotProps, type ThumbnailDeps, type ThumbnailOptions, type ThumbnailPainter, type ThumbnailsController, type ThumbnailsDeps, type ThumbnailsOptions, type ThumbnailsState, type Tool, type ToolContext, type ToolController, type ToolControllerOptions, type ToolId, type ToolKind, type ToolOptions, type ToolStyle, type ToolStyleTracker, type TypedSignatureOptions, type ViewRotation, type Viewer, type ViewerEngine, type ViewerSearch, type Viewport, type ViewportHit, type ViewportKeysOptions, type ViewportOptions, type ZoomValue, cssVariableDefaults, isBlankQuery, signField };
 //# sourceMappingURL=dom.d.mts.map