@inkbar/core 0.5.0 → 0.6.0

package/dist/dom.d.mts

@@ -1,4 +1,4 @@
-import { D as OpenOptions, E as InkStatus, H as AnnotationStore, M as InkError, Rt as NoteAnnotation, T as InkDocument, _ as StyleGroup, a as SignatureStore, b as ToolStyle, cn as PageInfo, dn as Matrix, fn as Point, g as ScopedToolStyle, i as SignatureOptions, it as cssVariableDefaults, j as DocumentSource, jt as LineEnding, m as CurrentStyle, mn as Rect, o as SignatureTemplate, pn as Quad, r as SignatureLibrary, rn as Readable, rt as AnnotationDefaults, st as Annotation, tn as TextMarkupAnnotation, un as PdfAssets, v as StyleKey, y as StyleProps, yt as FreeTextAnnotation } from "./signatures-BwaXi7C8.mjs";
+import { B as PluginHistory, D as OpenOptions, E as InkStatus, Et as FreeTextAnnotation, Gt as NoteAnnotation, M as InkError, Rt as LineEnding, T as InkDocument, U as AnnotationEdit, W as AnnotationStore, X as RecordChange, Y as RecordBase, Z as RecordStore, _ as StyleGroup, _n as PdfAssets, _t as AnnotationInput, a as SignatureStore, b as ToolStyle, bn as Quad, cn as TextMarkupAnnotation, dt as cssVariableDefaults, g as ScopedToolStyle, hn as PageInfo, i as SignatureOptions, j as DocumentSource, m as CurrentStyle, mt as Annotation, o as SignatureTemplate, r as SignatureLibrary, un as Readable, ut as AnnotationDefaults, v as StyleKey, vn as Matrix, xn as Rect, xt as AnnotationType, y as StyleProps, yn as Point } from "./signatures-By4B40DP.mjs";
 import { IconNode } from "@inkbar/icons";
 //#region src/dom/transform.d.ts
 type ViewRotation = 0 | 90 | 180 | 270;
@@ -136,7 +136,9 @@ interface Viewport {
     behavior?: ScrollBehavior;
   }): void;
   /** Scrolls so `rect` (user space on `page`) is visible, centring it when it was not. */
-  scrollToRect(page: number, rect: Rect): void;
+  scrollToRect(page: number, rect: Rect, opts?: {
+    behavior?: ScrollBehavior;
+  }): void;
   transformFor(page: number): PageTransform;
   hostFor(page: number): HTMLElement | undefined;
   /** The mounted page under a viewport (client) point, if any. */
@@ -298,43 +300,184 @@ export declare function createOverlay(opts: OverlayOptions): Overlay;
  */
 export declare function renderAnnotationContent(el: HTMLElement, a: Annotation, t: PageTransform): void;
 //#endregion
-//#region src/dom/page-mount.d.ts
-interface PageMountOptions {
-  document: InkDocument;
-  /** Zero-based page index. */
+//#region src/dom/plugins/api/command.d.ts
+interface CommandOptions {
+  icon?: IconNode;
+  /** Default: a document is open and ready. */
+  enabled?: Readable<boolean>;
+  /** The status after a failure. Default: "Something went wrong." */
+  errorStatus?: string;
+}
+type CommandRun = (run: {
+  /** The document open when the command started. */
+  doc: InkDocument;
+  /** Aborts when that document closes or another opens. */
+  signal: AbortSignal;
+}) => string | void | Promise<string | void>;
+//#endregion
+//#region src/dom/plugins/api/links.d.ts
+/** What `add` takes for annotations of type `K`. */
+type AnnotationInputOf<K extends AnnotationType> = AnnotationInput extends (infer I) ? I extends {
+  type: infer U;
+} ? K extends U ? I & {
+  type: K;
+} : never : never : never;
+type OmitEach<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+interface AnnotationLinkSpec<T extends RecordBase, K extends AnnotationType> {
+  /** The annotation's fields for `record`. Without a colour it gets the type's default. */
+  from(record: T): OmitEach<AnnotationInputOf<K>, 'type' | 'color'> & {
+    color?: string;
+  };
+  /** Runs once per linked annotation the user removes, inside that edit's undo step. */
+  onRemoved?(record: T, annotation: Annotation): void;
+  /** Runs for each user update of a linked annotation, inside that edit's undo step. */
+  onChanged?(record: T, annotation: Annotation): void;
+}
+interface AnnotationLink<T extends RecordBase> {
+  /** Adds an annotation made from `record` and linked to it; `undefined` with no document open. */
+  add(record: T): Annotation | undefined;
+  /** The annotations of this link's type linked to `record`, in document order. */
+  of(record: T): Annotation[];
+}
+//#endregion
+//#region src/dom/plugins/api/records.d.ts
+interface Records<T extends RecordBase> {
+  /** The open document's records; `[]` while none is open. Emits when the document changes. */
+  readonly list: Readable<readonly T[]>;
+  all(): readonly T[];
+  find(id: string): T | undefined;
+  has(id: string): boolean;
+  /** Records whose fields equal (===) every field of `match`, or that pass it. */
+  where(match: Partial<T> | ((record: T) => boolean)): T[];
+  /**
+   * Returns the stored record, or `undefined` with no document open. Throws
+   * `InkError('DuplicateId')` when the id is taken; `addMissing` skips taken ids.
+   *
+   * Every write is one undo step, and `plugin.batch` makes several one step. A write after an
+   * `await` goes to whatever document is open then: inside a command, write through `in(doc)`.
+   */
+  add(record: T): T | undefined;
+  /** Adds the records whose ids are not present yet, in one undo step; returns those added. */
+  addMissing(records: readonly T[]): T[];
+  update(id: string, patch: Partial<Omit<T, 'id'>>): T | undefined;
+  remove(id: string): T | undefined;
+  /**
+   * The same handle bound to `doc`'s store, as it is when called. Empty and inert once `doc`
+   * closes, and from the start when `doc` is not the open document.
+   */
+  in(doc: InkDocument): Records<T>;
+  /** The underlying store, or null; for anything the handle lacks. */
+  store(): RecordStore<T> | null;
+  /**
+   * Links these records to the `type` annotations made from them, as
+   * `custom.<plugin>.<records name> = <record id>`. A record may have several. Each call listens
+   * for annotation edits for the viewer's lifetime: call it in `setup`.
+   */
+  annotates<K extends AnnotationType>(type: K, spec: AnnotationLinkSpec<T, K>): AnnotationLink<T>;
+}
+//#endregion
+//#region src/dom/plugins/api/card.d.ts
+/** What a mark's card shows. The theme styles it; `className` adds a class of your own. */
+interface CardSpec {
+  /** The card's heading (`.ink-card-title`). */
+  title: string;
+  /** The dialog's accessible name. Default: `title`. */
+  label?: string;
+  /** A short line under the title (`.ink-card-meta`). */
+  meta?: string;
+  /** A CSS colour for a dot before `meta` (`.ink-card-swatch`). */
+  swatch?: string;
+  /** Text under the meta line (`.ink-card-body`). */
+  body?: 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
+   * an `await` fall outside it. When an action removes the mark, focus moves to the next of this
+   * `marks()` handle's marks, else the previous, else the viewport.
+   */
+  actions: Record<string, () => void>;
+  /** Classes added to the card. */
+  className?: string;
+}
+//#endregion
+//#region src/dom/plugins/api/marks.d.ts
+interface MarksOptions<T extends RecordBase & {
   page: number;
-  /** The page host (`div.ink-page`) from the viewport's `onMount`. */
-  host: HTMLElement;
-  transform: PageTransform;
-  store: AnnotationStore;
-  onActivate?(id: string): void;
-  isCustom?(a: Annotation): boolean;
-  /** The app's data attributes and classes for each annotation element (see `OverlayOptions`). */
-  decorate?: DecorateAnnotation;
-  /** Defaults to `window.devicePixelRatio`. */
-  devicePixelRatio?: number;
+}> {
+  /** Where the record's mark goes on its page, in user space. */
+  rect(record: T): Rect;
+  /** The mark's accessible name. */
+  label(record: T): string;
+  /** Only records that pass get a mark. Default: all. */
+  where?(record: T): boolean;
   /**
-   * Canvas and text layer failures, with the layer that failed (cancellations are not
-   * reported).
+   * Inline style for the mark, camel-case properties and `--custom` properties alike. Core draws
+   * nothing else: the look is the plugin's CSS.
    */
-  onError?(error: unknown, layer: PageLayer): void;
+  style?(record: T): Partial<CSSStyleDeclaration> & {
+    [property: `--${string}`]: string;
+  };
+  /** Classes every mark gets. */
+  className?: string;
   /**
-   * A layer finished without error: the canvas painted, or the text layer mounted or applied
-   * an update. Pair it with `onError` to tell when a failed layer has recovered.
+   * 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`).
    */
-  onRendered?(layer: PageLayer): void;
+  attrs?(record: T): Record<string, string>;
+  /**
+   * The card a mark opens when activated: a popover next to it, styled by the theme. Each
+   * action is one undo step. The mark gets `aria-haspopup="dialog"`, and `aria-expanded` true
+   * while its card is open.
+   */
+  card?(record: T): CardSpec;
+  /** Runs when the mark is clicked, or activated with Enter or Space, after `card` opens. */
+  onActivate?(record: T, mark: HTMLButtonElement): void;
 }
-/** The page layers that can fail and recover: the canvas and the text layer. */
-type PageLayer = 'canvas' | 'text';
-interface PageMount {
-  readonly renderer: PageRenderer;
-  readonly textLayer: TextLayerHandle;
-  readonly overlay: Overlay;
-  update(transform: PageTransform): void;
-  destroy(): void;
+interface MarksHandle {
+  /** Redraws every mark, for marks that read state outside the records. */
+  refresh(): void;
+  /**
+   * From now on, when records start to get a mark (added, or changed to pass `where`), the
+   * viewer scrolls to the first of them in reading order, unless it is in view already. Records
+   * a document opens with, and undo and redo, never scroll. Focus stays where it is. Returns
+   * the handle.
+   */
+  scrollToFirst(): MarksHandle;
+}
+//#endregion
+//#region src/dom/plugins/api/api.d.ts
+interface PluginOptions {
+  /** Store options by records name; `plugin.records(name)` picks them up. */
+  records?: Record<string, PluginStoreOptions<any>>;
+}
+interface PluginApi extends PluginContext {
+  /**
+   * A handle on the store `<plugin>.<name>` that follows the open document. Its options are
+   * `opts` when given, else the host's `options.records[name]`. Call it once per name in
+   * setup and keep the handle: a second call for the same name throws `InkError('DuplicateId')`.
+   */
+  records<T extends RecordBase>(name: string, opts?: PluginStoreOptions<T>): Records<T>;
+  /** Makes everything `fn` changes one undo step: `history.batch`. */
+  batch(fn: () => void): void;
+  /**
+   * Registers `<plugin>.<id>`. `run` gets the document open when it started and a signal that
+   * aborts when that document closes or another opens. A returned string becomes the command's
+   * status and `undefined` clears it; a failure is logged once and sets `errorStatus` (default
+   * "Something went wrong."). The status clears when the document changes.
+   *
+   * Inside a command, write through `records.in(doc)`.
+   */
+  command(id: string, label: string, run: CommandRun, opts?: CommandOptions): Command;
+  /**
+   * Draws a `<button>` for each record that passes `where`, on page `record.page` at
+   * `rect(record)`, in a layer of its own. The marks redraw when the records change; call
+   * `refresh()` when they read state of your own that changed.
+   */
+  marks<T extends RecordBase & {
+    page: number;
+  }>(records: Records<T>, opts: MarksOptions<T>): MarksHandle;
 }
-/** Canvas, text layer and annotation overlay for one page, stacked in that order. */
-export declare function createPageMount(opts: PageMountOptions): PageMount;
 //#endregion
 //#region src/dom/tools/options.d.ts
 interface ToolOptions {
@@ -395,6 +538,10 @@ interface ToolContext {
 }
 interface Tool<O extends object = object> {
   id: ToolId;
+  /** The accessible name a toolbar button shows for a tool core has no label for. */
+  label?: string;
+  /** The icon a toolbar button shows for a tool core has no icon for. */
+  icon?: IconNode;
   /** Default sticky. */
   kind?: ToolKind;
   cursor: string;
@@ -455,6 +602,261 @@ export declare function hitFor(ctx: ToolContext, e: {
   clientY: number;
 }): PageHit | undefined;
 //#endregion
+//#region src/dom/plugins/define.d.ts
+interface InkPlugin {
+  /** Lower-case kebab (/^[a-z][a-z0-9-]*$/); the namespace for everything the plugin adds. */
+  readonly id: string;
+  /** Runs once per viewer. The returned function runs when the viewer is destroyed. */
+  setup(ctx: PluginContext): void | (() => void);
+}
+interface CommandSpec {
+  /** Namespaced to `<plugin>.<id>`. */
+  id: string;
+  /** Names the command's button; must not be empty (`InkError('InvalidCommandLabel')`). */
+  label: string;
+  icon?: IconNode;
+  /** Default: a document is open and ready. */
+  enabled?: Readable<boolean>;
+  /** A short progress or result message, announced in a live region by the command button. */
+  status?: Readable<string>;
+  /** May be async: the command is busy until the promise settles. */
+  run(): void | Promise<void>;
+}
+interface Command {
+  /** `<plugin>.<spec id>`. */
+  readonly id: string;
+  readonly label: string;
+  readonly icon: IconNode | undefined;
+  /** The spec's `enabled` (or a ready document), and not busy. */
+  readonly enabled: Readable<boolean>;
+  /** True while the promise `run` returned is pending. */
+  readonly busy: Readable<boolean>;
+  /** The spec's status, or `''` without one. */
+  readonly status: Readable<string>;
+  /**
+   * Does nothing while busy or disabled. Never rejects: a failure is logged, and one caused by
+   * the document closing mid-run (`DocumentDestroyed`) is dropped silently.
+   */
+  run(): Promise<void>;
+}
+interface LayerSpec {
+  /** Draw into `el` for `page`. Called on mount, on every transform change and on invalidate. */
+  render(el: HTMLElement, page: number, transform: PageTransform): void;
+  /** Optional teardown when the page unmounts. */
+  destroy?(el: HTMLElement, page: number): void;
+}
+interface PluginLayerHandle {
+  /** Redraws `page`, or every mounted page without one. */
+  invalidate(page?: number): void;
+}
+interface PluginStoreOptions<T extends RecordBase> {
+  /** The records a store starts with, called once for each document that opens. */
+  initial?: (doc: InkDocument) => readonly T[];
+  /** Called after every change with the list as it now stands. */
+  onChange?: (list: readonly T[], change: RecordChange<T>) => void;
+}
+interface PluginContext {
+  /** The plugin's id. */
+  readonly id: string;
+  readonly document: Readable<InkDocument | null>;
+  /**
+   * The viewer's active history. `batch` makes everything `fn` changes, annotations and plugin
+   * records alike, one undo step. Stores from `store` are tracked for you, and `onAnnotationEdit`
+   * runs inside the edit's step.
+   */
+  readonly history: {
+    batch(fn: () => void): void;
+  };
+  /** The id of the activated annotation, or null. */
+  readonly activated: Readable<string | null>;
+  setActivated(id: string | null): void;
+  /** The viewport container, or null while none is mounted. */
+  readonly root: Readable<HTMLElement | null>;
+  commands: {
+    add(spec: CommandSpec): Command;
+  };
+  /** The tool's id becomes `<plugin>.<id>`. */
+  tools: {
+    add(tool: Tool): void;
+  };
+  /** Composed after the host's own decoration and earlier plugins'; earlier ones win per key. */
+  decorate(fn: DecorateAnnotation): void;
+  /**
+   * Runs every decoration again for the open document's annotations. Decorations re-apply when
+   * the annotations change; call this when one reads state of your own that changed instead.
+   */
+  redecorate(): void;
+  /**
+   * A record store keyed `<plugin>.<name>`, created for each document that opens and tracked by
+   * its history; null while no document is open. Inkbar keeps no plugin data: pass `initial`
+   * and `onChange` to load and save it.
+   */
+  store<T extends RecordBase>(name: string, opts?: PluginStoreOptions<T>): Readable<RecordStore<T> | null>;
+  /** Runs for each document that opens; the returned function runs when it closes. */
+  onDocument(fn: (doc: InkDocument) => void | (() => void)): void;
+  /**
+   * Runs for every user add, update and remove of an annotation, inside that edit's undo step,
+   * so store changes made here undo with it. Never runs for undo and redo.
+   */
+  onAnnotationEdit(fn: (edit: AnnotationEdit) => void): void;
+  /** Adds a layer drawn on every mounted page, above the annotations. */
+  layer(spec: LayerSpec): PluginLayerHandle;
+  /**
+   * Scrolls the viewer so `rect` (user space on `page`) is in view, centring it when it was
+   * not. Moves no focus. Does nothing while no document is shown.
+   */
+  scrollTo(page: number, rect: Rect, opts?: {
+    behavior?: ScrollBehavior;
+  }): 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];
+/**
+ * Checks the plugin's id and returns the plugin unchanged. Throws `InkError('InvalidPluginId')`
+ * for an id that is not lower-case kebab.
+ */
+export declare function definePlugin(plugin: InkPlugin): InkPlugin;
+/**
+ * Checks the id now and returns a factory: `factory(options)` is a plugin whose setup receives
+ * the plugin API and those options. Each call makes an independent plugin. The options may be
+ * left out only when every field of `O` is optional.
+ */
+export declare function definePlugin<O extends object = object>(id: string, setup: (plugin: PluginApi, options: O & PluginOptions) => void | (() => void)): (...args: PluginFactoryArgs<O>) => InkPlugin;
+//#endregion
+//#region src/dom/plugins/commands.d.ts
+/**
+ * The error for a command id no plugin registered, naming the ids that were. Bindings log it
+ * rather than throw, and show the control as it is before the plugins are set up.
+ */
+export declare function unknownCommand(id: string, registered: readonly string[]): InkError;
+//#endregion
+//#region src/dom/plugins/layer.d.ts
+/** A layer as the host keeps it: the plugin's spec and the id of the plugin that added it. */
+type PluginLayer = LayerSpec & {
+  readonly plugin: string;
+};
+/**
+ * What a layer source reports: a layer was added, or one asked to redraw.
+ *
+ * @internal For bindings, which mount plugin layers; not for plugin authors.
+ */
+type LayerEvent = {
+  type: 'add';
+  layer: PluginLayer;
+} | {
+  type: 'invalidate';
+  layer: PluginLayer;
+  page?: number | undefined;
+};
+/**
+ * Where page layers come from: a plugin host.
+ *
+ * @internal For bindings, which mount plugin layers; not for plugin authors.
+ */
+interface LayerSource {
+  readonly layers: readonly PluginLayer[];
+  /** Calls `listener` for every layer added and every invalidate; returns a stop function. */
+  watchLayers(listener: (event: LayerEvent) => void): () => void;
+}
+/**
+ * One page's plugin layers, made by `PluginLayers.mount`.
+ *
+ * @internal For bindings, which mount plugin layers; not for plugin authors.
+ */
+interface PageLayers {
+  update(transform: PageTransform): void;
+  destroy(): void;
+}
+/** The plugin layers of one viewer's pages; see `createPluginLayers`. */
+interface PluginLayers {
+  mount(page: number, host: HTMLElement, transform: PageTransform): PageLayers;
+  /** Stops following the source. Pages still mounted keep their layers until they unmount. */
+  destroy(): void;
+}
+/**
+ * Mounts `source`'s layers on the pages the engine mounts, and follows it: a layer added later
+ * is drawn on every mounted page, and an invalidate redraws its page, or all of them.
+ *
+ * @internal For bindings, which mount plugin layers; plugin authors add a layer with
+ * `ctx.layer`.
+ */
+export declare function createPluginLayers(source: LayerSource): PluginLayers;
+//#endregion
+//#region src/dom/plugins/host.d.ts
+interface PluginHostOptions {
+  plugins: readonly InkPlugin[];
+  document: Readable<InkDocument | null>;
+  /** The binding's active history, read when a document opens. */
+  history: () => PluginHistory;
+  activated: Readable<string | null>;
+  setActivated(id: string | null): void;
+  root: Readable<HTMLElement | null>;
+  /** The host's own decoration, read on each call. */
+  decorate?: () => DecorateAnnotation | undefined;
+  /** The viewer's viewport, read on each call; without one, `ctx.scrollTo` does nothing. */
+  viewport?: () => Viewport | null | undefined;
+}
+interface PluginHost extends LayerSource {
+  readonly commands: ReadonlyMap<string, Command>;
+  command(id: string): Command | undefined;
+  readonly tools: readonly Tool[];
+  /** The host's decoration first, then each plugin's in order; earlier ones win per key. */
+  decorate: DecorateAnnotation;
+  /** Every layer added so far; `watchLayers` reports the ones added later and invalidates. */
+  readonly layers: readonly PluginLayer[];
+  /** Calls `listener` on every `ctx.redecorate()`; returns a stop function. */
+  watchRedecorate(listener: () => void): () => void;
+  destroy(): void;
+}
+/**
+ * @internal For bindings and `createViewer`, which place a viewer's plugins; plugin authors use
+ * `definePlugin` and never call it.
+ */
+export declare function createPluginHost(opts: PluginHostOptions): PluginHost;
+//#endregion
+//#region src/dom/page-mount.d.ts
+interface PageMountOptions {
+  document: InkDocument;
+  /** Zero-based page index. */
+  page: number;
+  /** The page host (`div.ink-page`) from the viewport's `onMount`. */
+  host: HTMLElement;
+  transform: PageTransform;
+  store: AnnotationStore;
+  onActivate?(id: string): void;
+  isCustom?(a: Annotation): boolean;
+  /** The app's data attributes and classes for each annotation element (see `OverlayOptions`). */
+  decorate?: DecorateAnnotation;
+  /** Defaults to `window.devicePixelRatio`. */
+  devicePixelRatio?: number;
+  /** Plugin layers, mounted above the overlay. The engine passes them for its pages only. */
+  layers?: PluginLayers;
+  /**
+   * Canvas and text layer failures, with the layer that failed (cancellations are not
+   * reported).
+   */
+  onError?(error: unknown, layer: PageLayer): void;
+  /**
+   * A layer finished without error: the canvas painted, or the text layer mounted or applied
+   * an update. Pair it with `onError` to tell when a failed layer has recovered.
+   */
+  onRendered?(layer: PageLayer): void;
+}
+/** The page layers that can fail and recover: the canvas and the text layer. */
+type PageLayer = 'canvas' | 'text';
+interface PageMount {
+  readonly renderer: PageRenderer;
+  readonly textLayer: TextLayerHandle;
+  readonly overlay: Overlay;
+  update(transform: PageTransform): void;
+  destroy(): void;
+}
+/**
+ * Canvas, text layer, annotation overlay and any plugin layers for one page, stacked in that
+ * order.
+ */
+export declare function createPageMount(opts: PageMountOptions): PageMount;
+//#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;
@@ -967,17 +1369,26 @@ interface PopoverOptions {
    */
   onDismiss(): void;
 }
-/** A panel anchored to one annotation at a time; see `createPopover`. */
+/** A panel anchored to one annotation, or one element, at a time; see `createPopover`. */
 interface Popover {
   /** The panel element, on `<body>`. Fill it with the card's content. */
   readonly panel: HTMLElement;
-  /** The anchored annotation's element, or null while it is not in the DOM (page unmounted). */
+  /**
+   * The anchored annotation's element (or the element passed to `showAt`), or null while it is
+   * not in the DOM (page unmounted).
+   */
   readonly anchor: HTMLElement | null;
   /**
    * Anchors the panel to annotation `id`. The panel shows whenever that annotation's element
    * is in the DOM, and follows it when it is replaced.
    */
   show(id: string): void;
+  /**
+   * Anchors the panel to `el`, for anchors that are not annotations (a plugin layer's mark).
+   * The panel shows while `el` is under the viewer root and hides while it is not. On hide,
+   * focus returns to `el` when it is still connected, else through `focusReturn`.
+   */
+  showAt(el: HTMLElement): void;
   /** Hides the panel, then returns focus through `focusReturn`. */
   hide(): void;
   /** Removes the panel and its listeners. */
@@ -991,7 +1402,7 @@ export declare function placePanel(panel: HTMLElement, anchor: DOMRect): void;
 /**
  * Creates a non-modal `role="dialog"` panel on `<body>`, marked `data-ink-popover` so the theme
  * gives it its tokens, that an app anchors to an annotation with `show(id)` (for instance on
- * `viewer.activated`). The panel follows the annotation's element as pages mount and unmount:
+ * `viewer.activated`), or to any element in the viewer with `showAt(el)`. The panel follows the annotation's element as pages mount and unmount:
  * it hides while the element is gone and comes back with it. Tab loops inside the panel, and
  * Escape or a press outside calls `onDismiss`. Call `destroy` when done.
  */
@@ -1065,6 +1476,12 @@ interface MountViewerOptions {
    * classes cannot be overridden.
    */
   decorateAnnotation?: DecorateAnnotation;
+  /**
+   * The viewer's plugins. Their tools join `tools`, their layers are drawn on every page the
+   * engine mounts, and the host's `decorate` replaces `decorateAnnotation`: build the host with
+   * the app's decoration (its `decorate` option) so the two compose.
+   */
+  plugins?: PluginHost;
   onActivate?(id: string): void;
   /**
    * After every (re)build: subscribe to the new viewport and controller here. It fires inside
@@ -1115,8 +1532,9 @@ interface ViewerEngine {
     customAnnotations?: boolean;
   }): void;
   /**
-   * Runs `decorateAnnotation` again for every mounted annotation element, without re-rendering
-   * anything else. Call it when the decorations would change but no annotation did.
+   * Runs `decorateAnnotation` (or the plugins' `decorate`) again for every mounted annotation
+   * element, without re-rendering anything else. Call it when the decorations would change but
+   * no annotation did.
    */
   redecorate(): void;
   destroy(): void;
@@ -1129,7 +1547,7 @@ export declare function mountViewer(opts: MountViewerOptions): ViewerEngine;
  * (bound to one document's store, so each engine makes its own), and the tool options and
  * signature library (one for the viewer's life).
  */
-interface CreateViewerOptions extends Omit<MountViewerOptions, 'container' | 'document' | 'toolStyle' | 'toolHistory' | 'toolOptions' | 'signatureLibrary'> {
+interface CreateViewerOptions extends Omit<MountViewerOptions, 'container' | 'document' | 'toolStyle' | 'toolHistory' | 'toolOptions' | 'signatureLibrary' | 'plugins'> {
   source: DocumentSource;
   assets: PdfAssets;
   /** User password for encrypted files. `open` can pass its own for one load. */
@@ -1137,6 +1555,12 @@ interface CreateViewerOptions extends Omit<MountViewerOptions, 'container' | 'do
   /** Default: read from the theme's CSS variables on the viewer root. */
   defaults?: AnnotationDefaults;
   history?: OpenOptions['history'];
+  /**
+   * 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
+   * `createCommandButton`.
+   */
+  plugins?: readonly InkPlugin[];
   /** The thread popover for notes and text markup. Default true. */
   threads?: boolean;
   onReady?(this: void, doc: InkDocument): void;
@@ -1167,6 +1591,10 @@ interface Viewer {
    * not in the open document's annotations is ignored.
    */
   setActivated(id: string | null): void;
+  /** The plugins' commands by namespaced id (`sandbox.suggest`); place one with `createCommandButton`. */
+  readonly commands: {
+    get(id: string): Command | undefined;
+  };
   /**
    * 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.
@@ -1199,12 +1627,20 @@ 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 tool's button has no icon (append
- * your own) and is named by `label`, else by the tool id.
+ * 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.
  */
 export declare function createToolButton(viewer: Viewer, tool: ToolId, opts?: {
   label?: string;
 }): HTMLButtonElement;
+/**
+ * A plugin command as a button with its status text beside it. The button is named by the
+ * command's label and disabled while the command is, except while it runs: then it keeps focus,
+ * with `aria-busy` and `aria-disabled`, and a press does nothing. The status is a live region. A command without an icon shows its label as the button's text. For an id no
+ * plugin registered it logs `InkError('UnknownCommand')` to the console and returns the same
+ * markup disabled, `aria-hidden` and unnamed.
+ */
+export declare function createCommandButton(viewer: Viewer, id: string): HTMLElement;
 export declare function createZoomIn(viewer: Viewer): HTMLButtonElement;
 export declare function createZoomOut(viewer: Viewer): HTMLButtonElement;
 /** Fit width, fit page and the zoom levels; a zoom between levels gets an option of its own. */
@@ -1411,5 +1847,5 @@ export declare function createSignatureDialog(viewer: Viewer, opts?: SignatureDi
 export declare function createSignaturePreview(t: SignatureTemplate): HTMLElement;
 export declare function createSignatureMenu(viewer: Viewer, opts?: SignatureDialogOptions): HTMLElement;
 //#endregion
-export { type AnnotationDecoration, type AnnotationSlotProps, type AnnotationState, type ArrowheadChoice, type BuiltinToolId, type ColorMenuModel, type ColorMenuOptions, type ColorMenuSwatch, type ColorProperty, type ColorTrigger, type CreateViewerOptions, type CssLayout, type CssLayoutInput, type CssPageBox, type CssRect, type CurrentStyle, type DecorateAnnotation, type EditorCloseReason, type FocusReturn, type FocusReturnOptions, type FreeTextEditor, type FreeTextEditorOptions, type HighlightMenuItem, type HighlightMenuModel, type HighlightOptions, type LayoutMode, type LineStyleMenuItem, type LineStyleMenuModel, type LineStyleMenuSection, type MarkupKind, type Menu, type MenuOptions, type MountViewerOptions, type Overlay, type OverlayOptions, type PageHit, type PageLayer, type PageMount, type PageMountOptions, type PageRenderer, type PageRendererOptions, type PageTransform, type Palette, type Popover, type PopoverOptions, type ScopedToolStyle, type SelectionQuads, type ShapeKind, type ShapeMenuItem, type ShapeMenuModel, type ShapeOptions, 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 Viewport, type ViewportHit, type ViewportKeysOptions, type ViewportOptions, type ZoomValue, cssVariableDefaults };
+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 FreeTextEditor, type FreeTextEditorOptions, type HighlightMenuItem, type HighlightMenuModel, type HighlightOptions, 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 SelectionQuads, type ShapeKind, type ShapeMenuItem, type ShapeMenuModel, type ShapeOptions, 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 Viewport, type ViewportHit, type ViewportKeysOptions, type ViewportOptions, type ZoomValue, cssVariableDefaults };
 //# sourceMappingURL=dom.d.mts.map