@inkbar/core 0.4.0 → 0.6.0

package/dist/dom.d.mts

@@ -1,4 +1,4 @@
-import { $ as AnnotationDefaults, D as OpenOptions, E as InkStatus, Et as LineEnding, H as AnnotationStore, M as InkError, Nt as NoteAnnotation, Qt as TextMarkupAnnotation, T as InkDocument, Ut as RedactAnnotation, Xt as Suggestion, _ as StyleGroup, a as SignatureStore, at as Annotation, b as ToolStyle, cn as PdfAssets, dn as Quad, et as cssVariableDefaults, fn as Rect, g as ScopedToolStyle, i as SignatureOptions, j as DocumentSource, ln as Matrix, m as CurrentStyle, mt as ConfidenceBucket, o as SignatureTemplate, on as PageInfo, r as SignatureLibrary, tn as Readable, un as Point, v as StyleKey, vt as FreeTextAnnotation, y as StyleProps } from "./signatures-BHYKTwYE.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. */
@@ -256,16 +258,38 @@ interface OverlayOptions {
   document?: InkDocument;
   /** Fixed device pixel ratio for loupes; `window.devicePixelRatio` when omitted. */
   devicePixelRatio?: number;
+  /**
+   * The app's own data attributes, classes and description for an annotation's element, read
+   * whenever the annotations change and on `redecorate`. Core's own attributes and `ink-`
+   * classes win over them.
+   */
+  decorate?: DecorateAnnotation;
+}
+/**
+ * Data attributes, classes and a description an app adds to an annotation's element, to style
+ * or find its own marks. Each `data` key is written as `data-<key>`.
+ */
+interface AnnotationDecoration {
+  /** Written as data-<key>; keys are lower-case kebab (/^[a-z][a-z0-9-]*$/). */
+  data?: Readonly<Record<string, string>>;
+  classes?: readonly string[];
+  /**
+   * Extra words screen readers announce after the element's label, such as "Needs review".
+   * Written as `aria-description`.
+   */
+  description?: string;
 }
+/** Returns the decoration for an annotation's element, or undefined for none. */
+type DecorateAnnotation = (annotation: Annotation) => AnnotationDecoration | undefined;
 interface Overlay {
   readonly element: HTMLElement;
   /** Repositions every element and redraws content for a new zoom or rotation. */
   update(transform: PageTransform): void;
   elementFor(id: string): HTMLElement | undefined;
+  /** Runs `decorate` again for every element, for when its output changed but no annotation did. */
+  redecorate(): void;
   destroy(): void;
 }
-/** The `data-confidence` bucket for a suggested redaction; undefined for everything else. */
-export declare function confidenceAttr(a: Annotation): 'low' | 'medium' | 'high' | undefined;
 export declare function createOverlay(opts: OverlayOptions): Overlay;
 //#endregion
 //#region src/dom/overlay-render.d.ts
@@ -276,41 +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;
-  /** 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 {
@@ -328,6 +495,11 @@ export declare function createToolOptions(tools?: readonly Tool[]): ToolOptions;
 type BuiltinToolId = 'select-text' | 'select' | 'highlight' | 'redact-area' | 'note' | 'shape' | 'freetext' | 'draw' | 'sketch' | 'signature';
 /** A built-in tool's id, or any id a host registers its own tool under. */
 type ToolId = BuiltinToolId | (string & {});
+/**
+ * A one-shot tool switches back to `select-text` once it has made something and the user moves
+ * on; a sticky tool stays on. A tool without a kind is sticky.
+ */
+type ToolKind = 'one-shot' | 'sticky';
 interface PageHit extends ViewportHit {
   /** Pointer position in user space. */
   user: Point;
@@ -356,9 +528,22 @@ interface ToolContext {
   };
   /** The signature templates the `signature` tool places. Without it, it places nothing. */
   signatures?: SignatureLibrary | undefined;
+  /**
+   * A one-shot tool reports what it just made, already added and selected. Does nothing under
+   * a sticky tool or with an empty list.
+   */
+  made(ids: readonly string[]): void;
+  /** Clears the selection and switches to `select-text`. */
+  done(): void;
 }
 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;
   /** Style group the tool creates into; select tools have none. */
   styleGroup?: StyleGroup;
@@ -395,8 +580,11 @@ interface ToolController {
   destroy(): void;
 }
 interface ToolControllerOptions {
-  /** The controller adds `options`; `toolStyle` defaults to one of the controller's own. */
-  ctx: Omit<ToolContext, 'toolStyle' | 'options'> & {
+  /**
+   * The controller adds `options`, `made` and `done`; `toolStyle` defaults to one of the
+   * controller's own.
+   */
+  ctx: Omit<ToolContext, 'toolStyle' | 'options' | 'made' | 'done'> & {
     toolStyle?: ToolStyle;
   };
   /** Default `'select-text'`. */
@@ -414,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;
@@ -628,9 +1071,11 @@ interface ColorMenuModel {
 }
 /**
  * What a colour menu shows for a style: the palette with the matching swatch checked, "No fill"
- * for `fill`, and the trigger's swatch. Shared by the bindings and the vanilla menu.
+ * for `fill`, and the trigger's swatch. Shared by the bindings and the vanilla menu. `fallback`
+ * is the colour new annotations get while the style leaves it unset: the trigger shows it
+ * rather than an empty swatch.
  */
-export declare function colorMenuModel(property: ColorProperty, current: CurrentStyle, supported: ReadonlySet<StyleKey>): ColorMenuModel;
+export declare function colorMenuModel(property: ColorProperty, current: CurrentStyle, supported: ReadonlySet<StyleKey>, fallback?: string): ColorMenuModel;
 /** A typed size as the menu stores it: a whole number of points within the range. */
 export declare function clampFontSize(size: number): number;
 type TextToggleKey = 'bold' | 'italic' | 'underline';
@@ -739,10 +1184,6 @@ interface AnnotationSlotProps {
   locked: boolean;
   select: () => void;
   remove: () => void;
-  /** Turns a suggested redaction into the user's own. No-op for anything else. */
-  accept: () => void;
-  /** Removes a suggested redaction. No-op for anything else. */
-  dismiss: () => void;
 }
 /** The thread popover's accessible name: "Note thread" for a note, "Comment thread" for markup. */
 export declare function threadPopoverLabel(root: Pick<Annotation, 'type'>): string;
@@ -760,15 +1201,6 @@ interface ThreadPopoverSlotProps {
   remove: () => void;
   close: () => void;
 }
-/** What a host-rendered suggestion card receives. */
-interface SuggestionCardSlotProps {
-  annotation: RedactAnnotation;
-  suggestion: Suggestion | undefined;
-  bucket: ConfidenceBucket | undefined;
-  accept: () => void;
-  dismiss: () => void;
-  close: () => void;
-}
 /** The signature controls' words, shared so every binding announces the same names. */
 export declare const SIGNATURE_LABELS: {
   /** The menu's group and main button. */
@@ -828,19 +1260,30 @@ interface FreeTextEditor {
   /** Closes the editor, handing its text to `commit` (true) or calling `cancel` (false). */
   close(commit: boolean): void;
 }
+/**
+ * What closed an editor: Escape, a press outside it, focus leaving it, or a call to `close`
+ * (a redraw, the page unmounting, the box being removed, a tool switch).
+ */
+type EditorCloseReason = 'escape' | 'press' | 'focus' | 'api';
 interface FreeTextEditorOptions {
   transform: PageTransform;
   /**
    * The edited text and the box's rect, grown to fit it (`grownFreeText`), in user space.
    * `grown` is the growth alone, in CSS px (0 when the box kept its height), for a caller whose
-   * box may have moved or been resized while the editor was open.
+   * box may have moved or been resized while the editor was open. `how` says what closed it.
    */
-  commit(contents: string, rect: Rect, grown: number): void;
+  commit(contents: string, rect: Rect, grown: number, how: EditorCloseReason): void;
   cancel(): void;
+  /** Where to put the caret, a client point (a click on the box); at the end when absent. */
+  caret?: {
+    clientX: number;
+    clientY: number;
+  } | undefined;
 }
 /**
  * Opens an editor on `el`, the overlay element showing `a` (or a stand-in for a box not in the
- * store yet). `Escape` commits; a press outside the editor, or focus leaving it, commits too.
+ * store yet), with the caret at `opts.caret` or after the text. `Escape` commits; a press
+ * outside the editor, or focus leaving it, commits too.
  * Closing while the editor has focus hands focus to `el`. Keys typed in the
  * editor stop there, so no viewport or tool shortcut sees them. Opening a second editor on the
  * same element commits the first.
@@ -908,6 +1351,63 @@ interface FocusReturn {
 }
 export declare function createFocusReturn(opts: FocusReturnOptions): FocusReturn;
 //#endregion
+//#region src/dom/viewer/popover.d.ts
+/** Options for `createPopover`. */
+interface PopoverOptions {
+  /** The viewer root (`[data-ink-root]`): anchors are looked up and focus returns inside it. */
+  root: HTMLElement;
+  /**
+   * Attributes for the panel, such as `class`, `aria-label` or the app's own `data-*` keys.
+   * `role` and `data-ink-popover` are always set by `createPopover`.
+   */
+  attrs: Record<string, string>;
+  /** Where focus goes when the panel hides: `createFocusReturn` over the same root. */
+  focusReturn: FocusReturn;
+  /**
+   * Called on Escape inside the panel or the viewer, and on a press outside the panel that will
+   * not activate another annotation. Hide the panel (or clear the activation) here.
+   */
+  onDismiss(): void;
+}
+/** 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 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. */
+  destroy(): void;
+}
+/**
+ * Positions `panel` (fixed) below the `anchor` rectangle, or above it when only that fits,
+ * kept inside the window. For panels anchored to something other than an annotation.
+ */
+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`), 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.
+ */
+export declare function createPopover(opts: PopoverOptions): Popover;
+//#endregion
 //#region src/dom/viewer-engine.d.ts
 interface MountViewerOptions {
   container: HTMLElement;
@@ -968,6 +1468,20 @@ interface MountViewerOptions {
   signatureFonts?: string[];
   /** Annotation content is rendered by the host (custom slots). Changing it needs `rebuild`. */
   customAnnotations?: boolean;
+  /**
+   * The app's own data attributes, classes and description for each annotation element, to
+   * style or find its marks: `{ data: { 'my-flag': 'on' } }` writes `data-my-flag="on"`.
+   * Decorations re-apply whenever the annotations change; when the function's output changes
+   * for another reason (app state it reads), call `redecorate()`. Core's attributes and `ink-`
+   * 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
@@ -1017,6 +1531,12 @@ interface ViewerEngine {
     buffer?: number;
     customAnnotations?: boolean;
   }): void;
+  /**
+   * 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;
 }
 export declare function mountViewer(opts: MountViewerOptions): ViewerEngine;
@@ -1027,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. */
@@ -1035,10 +1555,14 @@ 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;
-  /** Suggested-redaction card. Default true. */
-  suggestions?: boolean;
   onReady?(this: void, doc: InkDocument): void;
   onError?(this: void, error: InkError): void;
 }
@@ -1055,6 +1579,22 @@ interface Viewer {
    */
   readonly viewport: Readable<Viewport | null>;
   readonly tools: Readable<ToolController | null>;
+  /**
+   * The activated annotation's id: the one last clicked, or activated with Enter or Space.
+   * The note thread opens from it, and an app can anchor its own popover (`createPopover`) to
+   * it. `null` when none is, and again once that annotation is removed or the document closes.
+   */
+  readonly activated: Readable<string | null>;
+  /**
+   * Activates annotation `id`, or clears the activation with `null` (closing the thread
+   * popover). Unlike a click, it does not select the annotation or call `onActivate`. An id
+   * 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.
@@ -1087,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. */
@@ -1123,6 +1671,8 @@ interface ColorMenuOptions {
    * colour whatever tool is active, and recolours the selection only when it is all in the group.
    */
   group?: StyleGroup;
+  /** The colour new annotations get while the style leaves it unset; the trigger shows it. */
+  fallback?: Readable<string | undefined>;
 }
 /** A button that opens a colour menu for one colour property of the selection or tool. */
 export declare function createColorMenu(viewer: Viewer, opts: ColorMenuOptions): HTMLButtonElement;
@@ -1156,6 +1706,8 @@ interface MenuOptions {
    * focusable one.
    */
   role?: 'menu' | 'dialog';
+  /** The element the panel lines up under. Default `trigger`; a split button passes itself. */
+  anchor?: HTMLElement;
   /**
    * Whether `target` belongs to a menu nested in this one (its panel sits outside this panel
    * in the DOM). Presses, focus and Escape inside it neither dismiss this menu nor close it.
@@ -1295,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 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 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 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 SuggestionCardSlotProps, 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 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