@inkbar/core 0.9.0 → 0.11.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-FuwcsNkA.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;
@@ -108,6 +108,11 @@ interface ViewportOptions {
   minZoom?: number;
   /** Default 8. */
   maxZoom?: number;
+  /**
+   * Zoom the document when two fingers pinch over the container. Default `true`. When false the
+   * viewport leaves `touch-action` alone and the browser zooms the page as it would anyway.
+   */
+  pinchZoom?: boolean;
   onMount(page: number, host: HTMLElement, transform: PageTransform): void;
   onUpdate(page: number, host: HTMLElement, transform: PageTransform): void;
   onUnmount(page: number, host: HTMLElement): void;
@@ -162,6 +167,124 @@ interface ViewportKeysOptions {
  */
 export declare function attachViewportKeys(el: HTMLElement, opts: ViewportKeysOptions): () => void;
 //#endregion
+//#region src/dom/pinch.d.ts
+interface PinchFrame {
+  /** The zoom the pinch has reached, clamped to the viewport's limits. */
+  zoom: number;
+  /** `zoom` over the zoom the pinch started at. */
+  factor: number;
+  /** The midpoint between the fingers when the pinch started. */
+  anchor: Point;
+  /** How far that midpoint has moved since. */
+  pan: Point;
+}
+export declare function pinchFrame(start: readonly [Point, Point], now: readonly [Point, Point], startScale: number, minZoom: number, maxZoom: number): PinchFrame;
+interface ZoomPreview {
+  /** Scales the pages by `factor` around `anchor`, then moves them by `pan`. */
+  show(factor: number, anchor: Point, pan: Point): void;
+  clear(): void;
+  /** Shifts the pages by `offset`, then eases them back to where the layout puts them. */
+  settle(offset: Point): void;
+  destroy(): void;
+}
+/**
+ * The pinch preview: a transform on the pages element, which the browser composites without
+ * laying anything out. `settle` covers what a preview can show but the committed layout
+ * cannot reach (mainly scroll clamped at the content edges): the pages start where the fingers
+ * left them and slide into place.
+ */
+export declare function createZoomPreview(container: HTMLElement, pagesEl: HTMLElement): ZoomPreview;
+interface TouchPinchOptions {
+  container: HTMLElement;
+  preview: ZoomPreview;
+  /** The effective zoom when a pinch starts. */
+  scale(): number;
+  minZoom: number;
+  maxZoom: number;
+  /**
+   * Scrolls the container so the content moves by `delta`, and returns how much of it the
+   * scroll took: less than `delta` where the scroll stops at the content edges.
+   */
+  scrollBy(delta: Point): Point;
+  /**
+   * Called once per pinch, when either finger lifts or is cancelled, after the preview clears.
+   * The frame's `anchor` is where the point that started between the fingers sits now, after
+   * the scrolling, and its `pan` is only the travel the scroll could not take.
+   */
+  commit(frame: PinchFrame): void;
+}
+/**
+ * Tracks touches on the container with touch events, which every touch browser sends as one
+ * stream (pointer events may be cancelled once the browser decides to pan). The first two
+ * fingers down start a pinch; a third is ignored. The pinch ends when either of its fingers
+ * lifts or is cancelled, and any finger still down then starts nothing until every finger has
+ * lifted. While two fingers are down their moves are prevented, so the browser neither pans
+ * nor zooms underneath; one finger's moves never are, so a one-finger scroll stays native. A
+ * move the browser will not let us cancel means it is scrolling natively already: that travel
+ * is left to it, and only what the fingers do after it is scrolled here.
+ * The viewport claims pinch on the container (`touch-action: pan-x pan-y`), which keeps the
+ * page from zooming as well; the tool controller turns off one-finger panning on the pages
+ * element while a drag tool is ready, and two fingers still land here. A finger
+ * that lands alone starts afresh, so an end the browser never sent leaves nothing behind.
+ */
+export declare function attachTouchPinch(opts: TouchPinchOptions): {
+  destroy(): void;
+};
+/**
+ * The zoom factor one wheel event stands for. A trackpad pinch arrives as ctrl+wheel events
+ * with small pixel deltas, which zoom smoothly. A mouse wheel notch with ctrl held arrives in
+ * line or page mode, or as one large pixel delta, and is one small step, whatever its size.
+ */
+export declare function wheelFactor(e: {
+  deltaY: number;
+  deltaMode: number;
+}): number;
+interface TrackpadPinchOptions {
+  container: HTMLElement;
+  preview: ZoomPreview;
+  /** The effective zoom when a pinch starts. */
+  scale(): number;
+  minZoom: number;
+  maxZoom: number;
+  /** Called once per pinch, after the preview clears. */
+  commit(frame: PinchFrame): void;
+}
+/**
+ * A trackpad pinch over the container. Browsers report it as ctrl+wheel events, which are
+ * taken over so the page does not zoom; a run of them is one pinch, anchored at the pointer
+ * where it began and committed once the events stop, or as soon as the container scrolls (a
+ * plain wheel, a scroll bar), so the scroll moves the committed layout and not the preview.
+ * Safari also has gesture events, which give the scale directly; while one of those runs,
+ * ctrl+wheel is ignored so nothing counts twice. Safari on a touch screen sends gesture events
+ * for a touch pinch too, which `attachTouchPinch` already handles: while a finger is down on
+ * the container they are prevented and otherwise ignored. The wheel listener is non-passive
+ * because it has to call `preventDefault`.
+ */
+export declare function attachTrackpadPinch(opts: TrackpadPinchOptions): {
+  destroy(): 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 +508,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 +557,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 +594,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 +672,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;
 }
@@ -579,6 +712,17 @@ interface ToolOptions {
 }
 export declare function createToolOptions(tools?: readonly Tool[]): ToolOptions;
 //#endregion
+//#region src/dom/tools/press.d.ts
+type PressKind = 'press' | 'long-press';
+/** A press on a page that nothing in Inkbar acted on. */
+interface PagePress {
+  /** Zero-based page index. */
+  page: number;
+  /** PDF user space on that page, points, origin bottom-left, before /Rotate. */
+  point: Point;
+  pointerType: 'mouse' | 'touch' | 'pen';
+}
+//#endregion
 //#region src/dom/tools/controller.d.ts
 /** The tools every viewer has. Creation tools are the host's to pass. */
 type CoreToolId = 'select-text' | 'select';
@@ -634,6 +778,12 @@ interface Tool<O extends object = object> {
   /** Default sticky. */
   kind?: ToolKind;
   cursor: string;
+  /**
+   * When true, one finger drags with the tool over the document instead of scrolling it,
+   * while the tool is active (and, for a one-shot tool, until it has made something). Two
+   * fingers still scroll and zoom.
+   */
+  claimsTouch?: boolean;
   /** Style group the tool creates into; select tools have none. */
   styleGroup?: StyleGroup;
   /** Option defaults. Options persist per tool for the viewer's life. */
@@ -684,6 +834,11 @@ interface ToolControllerOptions {
    * rebuild) so options persist; by default the controller keeps its own.
    */
   options?: ToolOptions;
+  /**
+   * A press or long press on a page that nothing in Inkbar acted on (see the top of
+   * controller.ts for which presses count).
+   */
+  onPress?(kind: PressKind, press: PagePress): void;
 }
 /** The mounted page under a client point, with the point in CSS px and user space. */
 export declare function hitFor(ctx: ToolContext, e: {
@@ -802,6 +957,16 @@ interface PluginContext {
    * hits) when the host has no search.
    */
   readonly search: ViewerSearch;
+  /**
+   * A press on a page that nothing in Inkbar acted on. Returns a function that stops listening.
+   * Fires only under the text and rectangle select tools.
+   */
+  onPress(fn: (press: PagePress) => void): () => void;
+  /**
+   * A touch or pen held still on a page that nothing in Inkbar acted on. Returns a function that
+   * stops listening. Fires only under the text and rectangle select tools.
+   */
+  onLongPress(fn: (press: PagePress) => void): () => void;
 }
 /** A factory's parameters: its options, optional only when `O` has no required field. */
 type PluginFactoryArgs<O> = {} extends O ? [options?: O & PluginOptions] : [options: O & PluginOptions];
@@ -876,6 +1041,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[];
@@ -892,7 +1098,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[];
@@ -902,6 +1132,14 @@ interface PluginHost extends LayerSource {
   readonly layers: readonly PluginLayer[];
   /** Calls `listener` on every `ctx.redecorate()`; returns a stop function. */
   watchRedecorate(listener: () => void): () => void;
+  /**
+   * Tells every `onPress` (or, for a long press, `onLongPress`) listener, in the order the
+   * listeners were added, across plugins. A listener that throws is logged and the rest still
+   * run.
+   *
+   * @internal For the viewer engine, which passes the tool controller's presses on.
+   */
+  emitPress(kind: PressKind, press: PagePress): void;
   destroy(): void;
 }
 /**
@@ -1612,6 +1850,8 @@ interface MountViewerOptions {
   rotation?: ViewRotation;
   gap?: number;
   buffer?: number;
+  /** Zoom the document on a two-finger pinch. Default `true`; see `ViewportOptions.pinchZoom`. */
+  pinchZoom?: boolean;
   tool?: ToolId;
   /**
    * The creation tools (`allTools()`, or the ones the host imports); `select-text` and `select`
@@ -1747,6 +1987,7 @@ interface ViewerEngine {
   rebuild(opts: {
     gap?: number;
     buffer?: number;
+    pinchZoom?: boolean;
     customAnnotations?: boolean;
   }): void;
   /**
@@ -1850,6 +2091,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.
@@ -1857,6 +2103,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;
@@ -1885,6 +2143,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
 /**
@@ -1905,6 +2171,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
@@ -1926,6 +2511,16 @@ 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. */
@@ -2203,5 +2798,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 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 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 PagePress, type PageRenderer, type PageRendererOptions, type PageTransform, type Palette, type PinchFrame, type PluginApi, type PluginContext, type PluginHost, type PluginHostOptions, type PluginLayer, type PluginLayerHandle, type PluginLayers, type PluginOptions, type PluginStoreOptions, type Popover, type PopoverOptions, type PressKind, 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 TouchPinchOptions, type TrackpadPinchOptions, type TypedSignatureOptions, type ViewRotation, type Viewer, type ViewerEngine, type ViewerSearch, type Viewport, type ViewportHit, type ViewportKeysOptions, type ViewportOptions, type ZoomPreview, type ZoomValue, cssVariableDefaults, isBlankQuery, signField };
 //# sourceMappingURL=dom.d.mts.map