@inkbar/core 0.10.0 → 0.12.0

package/dist/dom.d.mts

@@ -1,4 +1,4 @@
-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 { $n as Point, B as isBlankQuery, Bn as Destination, Bt as FreeTextAnnotation, F as OutlineItem, Ft as AnnotationType, I as DocumentSource, In as ViewerAction, K as InkError, L as SearchHit, M as InkStatus, N as OpenOptions, Ot as Annotation, Qn as Matrix, Qt as LineEnding, S as ToolStyle, Sn as TextMarkupAnnotation, T as InkStorage, Tt as cssVariableDefaults, U as PageLink, Vn as LinkTarget, W as FormController, Wn as Readable, Yn as PageInfo, Zn as PdfAssets, a as SignatureOptions, an as NoteAnnotation, b as StyleKey, dt as RecordStore, er as Quad, et as PluginHistory, g as CurrentStyle, i as SignatureLibrary, it as AnnotationStore, j as InkDocument, jt as AnnotationInput, kn as FieldsMode, lt as RecordBase, o as SignatureStore, rt as AnnotationEdit, s as SignatureTemplate, t as signField, tr as Rect, ut as RecordChange, v as ScopedToolStyle, wt as AnnotationDefaults, x as StyleProps, y as StyleGroup } from "./sign-UdMGeqRr.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;
@@ -139,6 +144,31 @@ interface Viewport {
   scrollToRect(page: number, rect: Rect, opts?: {
     behavior?: ScrollBehavior;
   }): void;
+  /**
+   * Scrolls to a PDF destination without touching zoom. The destination's own zoom is ignored.
+   * `xyz` puts (`left`, `top`) at the container's top-left; a missing `left` keeps the horizontal
+   * scroll and a missing `top` lands at the page top as `scrollToPage` does. `fith`/`fitbh` put
+   * `top` at the top, `fitv`/`fitbv` put `left` at the left, `fitr` centres the rect (always
+   * scrolling), and `fit`/`fitb` act as `scrollToPage`. Single-page mode switches page first.
+   * "Top" and "left" are those of the converted point, so a rotated page is framed as it looks.
+   */
+  scrollToDestination(dest: Destination, opts?: {
+    behavior?: ScrollBehavior;
+  }): void;
+  /**
+   * The layout-space CSS y (measured from the pages element, as `readingLine` is) that
+   * `scrollToDestination` puts at the container's top. `undefined` when the page has no box
+   * (another page in single-page mode, or out of range).
+   */
+  destinationY(dest: Destination): number | undefined;
+  /**
+   * Layout-space CSS y of the line one third down the visible area:
+   * `scrollTop + clientHeight / 3`, less where the pages element starts; at the bottom of the
+   * visible area instead while scrolled to the end, so the last destinations can be reached.
+   * Compare it with `destinationY` to tell which destination the reader has reached. Updates
+   * on scroll, resize and layout.
+   */
+  readonly readingLine: Readable<number>;
   transformFor(page: number): PageTransform;
   hostFor(page: number): HTMLElement | undefined;
   /** The mounted page under a viewport (client) point, if any. */
@@ -162,6 +192,103 @@ 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`. */
@@ -208,9 +335,9 @@ interface HistoryKeysTarget {
  */
 export declare function attachHistoryKeys(el: HTMLElement, history: () => HistoryKeysTarget | null | undefined): () => void;
 /**
- * Keeps focus in the viewer when a focused Undo or Redo button inside `el` turns disabled
- * (it undid or redid the last step), which would otherwise drop focus to `<body>`, out of
- * reach of the undo and redo keys. Focus moves to `scroll()`, the viewer's scroll element,
+ * Keeps focus in the viewer when a focused Undo, Redo, Back or Forward button inside `el` turns
+ * disabled (it undid, redid or went back over the last step), which would otherwise drop focus
+ * to `<body>`, out of reach of the viewer's keys. Focus moves to `scroll()`, the viewer's scroll element,
  * without scrolling. Returns a function that removes the listeners.
  *
  * Chrome and Firefox blur the button as it is disabled: its `focusout` comes while the
@@ -610,6 +737,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';
@@ -665,6 +803,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. */
@@ -715,6 +859,24 @@ 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 link at a user-space point on a page, if one is followed there. Asked only under
+   * `select-text` and `select`.
+   */
+  linkAt?(page: number, point: Point): PageLink | undefined;
+  /** A still press or a tap on a link (see the top of controller.ts); it is not an `onPress`. */
+  onLink?(link: PageLink): void;
+  /**
+   * The link a press would follow is now `link`, or none: the pointer moved onto or off it,
+   * left the viewport, or the tool changed. Called once per change, and with `undefined` on
+   * destroy when a link was hovered.
+   */
+  onLinkHover?(link: PageLink | undefined): void;
 }
 /** The mounted page under a client point, with the point in CSS px and user space. */
 export declare function hitFor(ctx: ToolContext, e: {
@@ -812,6 +974,12 @@ interface PluginContext {
    * and `onChange` to load and save it.
    */
   store<T extends RecordBase>(name: string, opts?: PluginStoreOptions<T>): Readable<RecordStore<T> | null>;
+  /**
+   * Settings that outlive the document and the visit, kept in the viewer's `storage` under
+   * `plugin.<id>.<key>` and visible to no other plugin. Use `store()` for records that belong to
+   * a document and undo with edits; use this for preferences such as a panel width.
+   */
+  readonly storage: InkStorage;
   /** Runs for each document that opens; the returned function runs when it closes. */
   onDocument(fn: (doc: InkDocument) => void | (() => void)): void;
   /**
@@ -833,6 +1001,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];
@@ -963,6 +1141,8 @@ interface PluginHostOptions {
   viewport?: () => Viewport | null | undefined;
   /** The viewer's search; without one, `ctx.search` is inert. */
   search?: ViewerSearch;
+  /** Where plugins keep settings, each under `plugin.<id>.`; memory when omitted. */
+  storage?: InkStorage;
 }
 /**
  * A plugin's records as the host app sees them: the plugin's own handle without `annotates`
@@ -998,6 +1178,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;
 }
 /**
@@ -1039,6 +1227,59 @@ interface FormLayer {
   destroy(): void;
 }
 //#endregion
+//#region src/dom/navigation.d.ts
+/** Where a followed target comes from. */
+interface FollowOptions {
+  /**
+   * The page the target was pressed on: a link's own page. Next and previous page run from it,
+   * as the link layer names them; without it they run from the current page, as an outline
+   * item's do.
+   */
+  from?: number;
+}
+interface Navigation {
+  /** Whether `back()` has somewhere to go. */
+  readonly canGoBack: Readable<boolean>;
+  /** Whether `forward()` has somewhere to go. */
+  readonly canGoForward: Readable<boolean>;
+  /** Returns to the position before the last jump, keeping the current one for `forward()`. */
+  back(): void;
+  /** Undoes the last `back()`. */
+  forward(): void;
+  /**
+   * Records where the view is, then goes to `dest`. A page the document lacks does nothing, and
+   * a jump that leaves the view where it was records nothing.
+   */
+  goTo(dest: Destination): void;
+  /**
+   * Resolves and follows any target. URLs go to `report` as `open-url` (only http, https,
+   * mailto and tel); unsupported targets and destinations that resolve to nothing do nothing.
+   */
+  follow(target: LinkTarget, opts?: FollowOptions): Promise<void>;
+  /** Forgets every position, as when another document opens. */
+  clear(): void;
+}
+interface NavigationDeps {
+  viewport: () => Viewport | undefined;
+  document: () => InkDocument | undefined;
+  /** Where the view is now, as a destination to come back to. */
+  here: () => Destination | undefined;
+  /** Hands a URL to the host: Inkbar never opens one itself. */
+  report: (a: ViewerAction) => void;
+}
+//#endregion
+//#region src/dom/link-layer.d.ts
+interface LinkLayer {
+  /** `div.ink-link-layer`, with `data-ink-link-layer`; never takes pointer events. */
+  readonly element: HTMLElement;
+  update(transform: PageTransform): void;
+  /** The links Tab stops at, in the order the file lists them. */
+  tabStops(): HTMLElement[];
+  /** Reads each link's name from the text under it again, once the text layer has mounted. */
+  relabel(): void;
+  destroy(): void;
+}
+//#endregion
 //#region src/dom/search/highlights.d.ts
 /** The highlights of one viewer's pages; see `createSearchHighlights`. */
 interface SearchHighlights {
@@ -1071,6 +1312,8 @@ interface PageMountOptions {
   formActive?(): boolean;
   /** A signature field asked to be signed. */
   onSignField?(req: SignFieldRequest): void;
+  /** A link was activated from the keyboard or by assistive technology. */
+  followLink?(target: LinkTarget, opts: FollowOptions): void;
   /** Plugin layers, mounted above the overlay. The engine passes them for its pages only. */
   layers?: PluginLayers;
   /** Search match highlights, mounted below the overlay. */
@@ -1088,22 +1331,26 @@ interface PageMountOptions {
   onRendered?(layer: PageLayer): void;
 }
 /**
- * The page layers that can fail and recover: the canvas, the text layer and the form layer's
- * canvas of widget appearances.
+ * The page's layers: the canvas, the text layer and the form layer's canvas of widget
+ * appearances, which can fail and recover, and the links, which draw no pixels and never report.
  */
-type PageLayer = 'canvas' | 'text' | 'form';
+type PageLayer = 'canvas' | 'text' | 'links' | 'form';
 interface PageMount {
   readonly renderer: PageRenderer;
   readonly textLayer: TextLayerHandle;
   readonly overlay: Overlay;
   /** The page's form fields; undefined when the document has none. */
   readonly form: FormLayer | undefined;
+  /** The page's links; undefined when the page has none. */
+  readonly links: LinkLayer | undefined;
+  /** The page's fields and links Tab stops at, in the one order they share. */
+  tabStops(): HTMLElement[];
   update(transform: PageTransform): void;
   destroy(): void;
 }
 /**
- * Canvas, text layer, form layer, annotation overlay and any plugin layers for one page, stacked
- * in that order.
+ * Canvas, text layer, links, search highlights, form layer, annotation overlay and any plugin
+ * layers for one page, stacked in that order.
  */
 export declare function createPageMount(opts: PageMountOptions): PageMount;
 //#endregion
@@ -1708,6 +1955,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`
@@ -1741,10 +1990,16 @@ interface MountViewerOptions {
    */
   fonts?: string[];
   /**
-   * Where signature templates live. Default: memory, gone on reload
-   * (`createMemorySignatureStore`). `createLocalSignatureStore` keeps them in the browser.
+   * Where signature templates live. Default: they go in `storage`.
+   *
+   * @deprecated Pass `storage` instead. When both are given, this wins.
    */
   signatures?: SignatureStore;
+  /**
+   * What the viewer keeps between visits, such as saved signatures. Default: memory, gone on
+   * reload (`createMemoryStorage`). `createLocalStorage()` keeps it in the browser.
+   */
+  storage?: InkStorage;
   /**
    * The templates the `signature` tool and the signature controls share. A binding or
    * `createViewer` passes its own, so they outlive one document; it wins over `signatures`.
@@ -1769,10 +2024,12 @@ interface MountViewerOptions {
    */
   onSignField?(req: SignFieldRequest): void;
   /**
-   * The form asked the host to submit, open a link, send mail, print or prompt. Inkbar itself
-   * never does any of these.
+   * The viewer asked the host to do something: a form's submit, mail, print or prompt, or a
+   * link to a URL. Inkbar itself never does any of these.
    */
-  onFormAction?(action: FormAction): void;
+  onAction?(action: ViewerAction): void;
+  /** @deprecated Use `onAction`. Removed in 0.13.0. Ignored when `onAction` is given. */
+  onFormAction?(action: ViewerAction): void;
   /** A form script called `app.alert`: show `message` (text, not markup) without blocking. */
   onFormAlert?(message: string): void;
   /** Annotation content is rendered by the host (custom slots). Changing it needs `rebuild`. */
@@ -1831,9 +2088,17 @@ interface ViewerEngine {
   readonly fonts: readonly string[];
   /** The signature templates: the host's current library, or the engine's own. */
   readonly signatures: SignatureLibrary;
+  /** The `storage` option, or a new memory store. */
+  readonly storage: InkStorage;
   /** The fonts a typed signature offers: the `signatureFonts` option, else `SIGNATURE_FONTS`. */
   readonly signatureFonts: readonly string[];
   readonly pages: ReadonlyMap<number, PageMount>;
+  /**
+   * Back and forward through the document's jumps: links, outline items and form buttons that
+   * go to a page. It lasts as long as the engine, across rebuilds, and starts empty for each
+   * document. URL targets reach `onAction`.
+   */
+  readonly navigation: Navigation;
   /**
    * Recreates the viewport for construction-only options, keeping zoom, page, mode, rotation
    * and tool. The scroll position is kept too: the user-space point at the top-left of the
@@ -1843,6 +2108,7 @@ interface ViewerEngine {
   rebuild(opts: {
     gap?: number;
     buffer?: number;
+    pinchZoom?: boolean;
     customAnnotations?: boolean;
   }): void;
   /**
@@ -1937,6 +2203,23 @@ interface Viewer {
    * in place, and for the documents opened after it.
    */
   setFormHighlight(on: boolean): void;
+  /**
+   * Whether `back()` has somewhere to go: a link, outline item or form button jumped since the
+   * document opened. False while no document is ready.
+   */
+  readonly canGoBack: Readable<boolean>;
+  /** Whether `forward()` has somewhere to go. False while no document is ready. */
+  readonly canGoForward: Readable<boolean>;
+  /** Returns to where the view was before the last jump. History starts over with each document. */
+  back(): void;
+  /** Goes to where the last `back()` left from. */
+  forward(): void;
+  /**
+   * Follows a link target as a click on the link would: a destination or Named page action
+   * scrolls (zoom unchanged) and can be gone back from; a URL reaches `onAction` as
+   * `open-url` and is never opened by the viewer. Does nothing while no document is ready.
+   */
+  follow(target: LinkTarget): Promise<void>;
   /** The plugins' commands by namespaced id (`sandbox.suggest`); place one with `createCommandButton`. */
   readonly commands: {
     get(id: string): Command | undefined;
@@ -2173,6 +2456,19 @@ interface SidebarControllerOptions {
    * and the client. Without it they come from a counter.
    */
   idPrefix?: string;
+  /** Where the width is saved, under `sidebar.<name>.width`. Without it the width lasts the controller's life. */
+  storage?: InkStorage;
+  /** The key's middle part. Default: the side. Give two sidebars on one side different names. */
+  name?: string;
+  /** Default 320, in CSS px. */
+  defaultWidth?: number;
+  /** Default 240. */
+  minWidth?: number;
+  /** Default 480. The shown width also stays within half the sidebar's container. */
+  maxWidth?: number;
+  /** Controlled when given: drags and keys only report through `onWidthChange`, and storage is not read or written. */
+  width?: number;
+  onWidthChange?(width: number): void;
 }
 interface SidebarState {
   layout: SidebarLayout;
@@ -2181,13 +2477,17 @@ interface SidebarState {
   /** The open panels' ids, in panel order: at most one for rail and tabs. */
   open: readonly string[];
   visible: boolean;
+  /** The wanted width: saved, dragged or default. `rootStyle()` gives the shown one. */
+  width: number;
+  /** True while the handle is dragged. */
+  resizing: 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.
+   * goes to `onOpenChange`, controlled or not. `width` given makes the width controlled.
    */
   update(opts: Partial<SidebarControllerOptions>): void;
   /** What activating `id`'s trigger does: rail opens or closes, tabs switch, stack expands or collapses. */
@@ -2199,6 +2499,16 @@ interface SidebarController {
    * `hidden` while it is not `visible`.
    */
   rootAttrs(): Record<string, string>;
+  /** `--ink-sidebar-width` for the root: the shown width in px. */
+  rootStyle(): Record<string, string>;
+  /** The id of the element holding the panels, which the handle's `aria-controls` names. */
+  panelsAttrs(): Record<string, string>;
+  /** The separator's attributes; includes `hidden` while no panel is open or the sidebar is hidden. */
+  handleAttrs(): Record<string, string>;
+  /** Pointer drag, keys and double-click on the handle; observes the sidebar's container. Returns the unbind. */
+  bindHandle(el: HTMLElement): () => void;
+  /** Back to `defaultWidth`; removes the saved key. */
+  resetWidth(): void;
   /** 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`. */
@@ -2218,6 +2528,12 @@ interface SidebarController {
 }
 /** The text a badge shows, or null when it is hidden (empty or 0). */
 export declare function sidebarBadge(badge: string | number | undefined): string | null;
+/** The sidebar's widths in CSS px, unless the host gives its own. */
+export declare const SIDEBAR_WIDTH: {
+  readonly default: 320;
+  readonly min: 240;
+  readonly max: 480;
+};
 export declare function createSidebarController(opts: SidebarControllerOptions): SidebarController;
 //#endregion
 //#region src/dom/sidebar/sidebar.d.ts
@@ -2345,6 +2661,102 @@ export declare function createThumbnailsController(deps: ThumbnailsDeps, initial
  */
 export declare function createThumbnails(viewer: Viewer, opts?: ThumbnailsOptions): HTMLElement;
 //#endregion
+//#region src/dom/outline/controller.d.ts
+interface OutlineControllerDeps {
+  /** The open document; null while none is. */
+  document: Readable<InkDocument | null>;
+  /** The viewport whose reading line marks the current item; null while none is mounted. */
+  viewport: Readable<Viewport | null>;
+  /** Where activated items go, so jumps can be gone back from; null while no document is ready. */
+  navigation: Readable<Navigation | null>;
+  /** Prefix for the items' element ids. Pass one when the markup is rendered on the server. */
+  idPrefix?: string | undefined;
+}
+interface OutlineController {
+  /** The outline's top-level items; `[]` while loading and when the document has none. */
+  readonly items: Readable<readonly OutlineItem[]>;
+  /** True while the open document's outline is being read. */
+  readonly loading: Readable<boolean>;
+  /** The ids of the expanded items. Another document starts from its file's `open` flags. */
+  readonly expanded: Readable<ReadonlySet<string>>;
+  /**
+   * The id of the item marked as where the reader is: the item reached, or its outermost
+   * collapsed ancestor; the item last activated, until the reader scrolls away from it. Null
+   * before the first item's destination.
+   */
+  readonly current: Readable<string | null>;
+  /** The id of the item the user last moved to or activated; null until they do. */
+  readonly focused: Readable<string | null>;
+  /** Expands or collapses an item that has children. */
+  toggle(id: string): void;
+  expandAll(): void;
+  collapseAll(): void;
+  /**
+   * Follows the item: a destination is scrolled to and recorded for Back, a URL goes to the host
+   * through `onAction`, a page action navigates. An unsupported item does nothing.
+   */
+  activate(id: string): void;
+  /** `role="tree"` and its label, for the element holding the items. */
+  treeAttrs(): Record<string, string>;
+  /**
+   * For each item's element: `role="treeitem"`, its `id`, `aria-level`, `aria-setsize`,
+   * `aria-posinset`, `aria-expanded` (items with children), `aria-current="location"` on the
+   * current item, `aria-disabled` on items Inkbar cannot follow, `aria-labelledby` (its title)
+   * and `tabindex` (one item has 0).
+   *
+   * The item element contains its own children, as the WAI-ARIA tree pattern has it, so it is
+   * named by its title rather than by everything inside it:
+   *
+   * ```html
+   * <ul class="ink-outline-tree" {...treeAttrs()} onkeydown>
+   *   <li class="ink-outline-item" {...itemAttrs(id)} style="--ink-outline-level: 0">
+   *     <div class="ink-outline-row" {...rowAttrs(id)}>
+   *       <span class="ink-outline-toggle" aria-hidden="true">chevron</span>
+   *       <span class="ink-outline-title" {...titleAttrs(id)}>Title</span>
+   *     </div>
+   *     <ul class="ink-outline-group" role="group">children, shown only while expanded</ul>
+   *   </li>
+   * </ul>
+   * ```
+   *
+   * An item without children has `ink-outline-spacer` in place of the toggle and no group.
+   * `--ink-outline-level` is its depth, 0 at the top; `data-bold` and `data-italic` go on the
+   * item. A click on the toggle calls `toggle(id)`, anywhere else on the row `activate(id)`.
+   */
+  itemAttrs(id: string): Record<string, string | undefined>;
+  /** The `id` of an item's title element, which names the item. */
+  titleAttrs(id: string): Record<string, string>;
+  /**
+   * The `id` of an item's row (its chevron and title, without its children), which `bindScroll`
+   * measures to keep the current item in view.
+   */
+  rowAttrs(id: string): Record<string, string>;
+  /** The tree's key handler: put it on the element with `treeAttrs()`. */
+  onKeydown(e: KeyboardEvent): void;
+  /** Scrolls the current item into view inside `scroller` unless focus is in the tree. */
+  bindScroll(scroller: HTMLElement): () => void;
+  destroy(): void;
+}
+/**
+ * `role="tree"` and its label, for the element holding an outline's items. The same as a
+ * controller's `treeAttrs()`, without one, so markup rendered on the server has them too.
+ */
+export declare function outlineTreeAttrs(): Record<string, string>;
+export declare function createOutlineController(deps: OutlineControllerDeps): OutlineController;
+//#endregion
+//#region src/dom/outline/outline.d.ts
+interface OutlineOptions {
+  /** Shown when the document has no outline. Default: "This document has no outline". */
+  emptyText?: string | undefined;
+}
+/**
+ * The open document's outline as a tree. Give it a height (it fills its parent's) and place it
+ * anywhere, a sidebar panel for instance. Clicking an item, or Enter on it, follows it and can be
+ * gone back from; its chevron expands and collapses it. The item the reader has reached is
+ * marked and kept in view. It stops when the viewer is destroyed.
+ */
+export declare function createOutline(viewer: Viewer, opts?: OutlineOptions): HTMLElement;
+//#endregion
 //#region src/dom/viewer/controls.d.ts
 /**
  * An `<svg>` drawing `icon` from `@inkbar/icons`, hidden from assistive technology: the
@@ -2380,6 +2792,13 @@ export declare function createPrintButton(viewer: Viewer): HTMLButtonElement;
 export declare function createUndo(viewer: Viewer): HTMLButtonElement;
 /** Redoes the last undone change; disabled when there is none. */
 export declare function createRedo(viewer: Viewer): HTMLButtonElement;
+/**
+ * Returns to where the view was before the last jump (`viewer.back()`): a link, an outline
+ * item or a form button that went to a page. Disabled while there is nowhere to go back to.
+ */
+export declare function createBack(viewer: Viewer): HTMLButtonElement;
+/** Goes forward again after `createBack` (`viewer.forward()`); disabled until Back is used. */
+export declare function createForward(viewer: Viewer): HTMLButtonElement;
 /**
  * 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
@@ -2653,5 +3072,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 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 };
+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 Navigation, type NavigationDeps, type OutlineController, type OutlineControllerDeps, type OutlineOptions, 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