@inkbar/core 0.2.0 → 0.4.0

package/dist/dom.d.mts

@@ -1,4 +1,4 @@
-import { $ as NoteAnnotation, Ct as Matrix, Et as Rect, L as Annotation, M as cssVariableDefaults, St as PdfAssets, Tt as Quad, W as ConfidenceBucket, a as OpenOptions, b as AnnotationStore, bt as PageInfo, ht as Readable, i as InkStatus, j as AnnotationDefaults, l as DocumentSource, ot as RedactAnnotation, r as InkDocument, u as InkError, ut as Suggestion, wt as Point } from "./document-Cywnv8Sz.mjs";
+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 { IconNode } from "@inkbar/icons";
 //#region src/dom/transform.d.ts
 type ViewRotation = 0 | 90 | 180 | 270;
@@ -249,6 +249,13 @@ interface OverlayOptions {
   onActivate?(id: string): void;
   /** Return true to render only the positioned shell; the host (e.g. a Vue slot) fills it. */
   isCustom?(annotation: Annotation): boolean;
+  /**
+   * The document the page belongs to. Loupes magnify its page content; without it they show
+   * only their rim.
+   */
+  document?: InkDocument;
+  /** Fixed device pixel ratio for loupes; `window.devicePixelRatio` when omitted. */
+  devicePixelRatio?: number;
 }
 interface Overlay {
   readonly element: HTMLElement;
@@ -305,8 +312,22 @@ interface PageMount {
 /** 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 {
+  /** The tool's current options. Throws a `RangeError` for an id no tool registered. */
+  readable(id: ToolId): Readable<object>;
+  get(id: ToolId): object;
+  /** Merges `patch` into the tool's options. */
+  merge(id: ToolId, patch: object): void;
+  /** Registers tools not seen yet, seeded from their `defaultOptions`; known ids keep theirs. */
+  register(tools: readonly Tool[]): void;
+}
+export declare function createToolOptions(tools?: readonly Tool[]): ToolOptions;
+//#endregion
 //#region src/dom/tools/controller.d.ts
-type ToolId = 'view' | 'select' | 'highlight' | 'redact-area' | 'note';
+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 & {});
 interface PageHit extends ViewportHit {
   /** Pointer position in user space. */
   user: Point;
@@ -322,18 +343,36 @@ interface ToolContext {
   selectionQuads(): SelectionQuads[];
   clearSelection(): void;
   onActivate?(id: string): void;
+  /** The style each group creates with, shared with the style controls. */
+  toolStyle: ToolStyle;
+  /** The active tool's current options. */
+  options<O extends object>(): O;
+  /**
+   * Groups a gesture's changes into one undo step (a group move). Without it each change is
+   * its own step.
+   */
+  history?: {
+    batch(fn: () => void): void;
+  };
+  /** The signature templates the `signature` tool places. Without it, it places nothing. */
+  signatures?: SignatureLibrary | undefined;
 }
-interface Tool {
+interface Tool<O extends object = object> {
   id: ToolId;
   cursor: string;
+  /** Style group the tool creates into; select tools have none. */
+  styleGroup?: StyleGroup;
+  /** Option defaults. Options persist per tool for the viewer's life. */
+  defaultOptions?: O;
   activate(ctx: ToolContext): void;
   deactivate(): void;
   /**
    * Runs in the capture phase, before the overlay sees the press. `annotationId` is set when
-   * the press landed on an annotation; the overlay then selects and activates it, so tools
-   * other than `select` should ignore such presses. Calling `e.stopPropagation()` here keeps
-   * the overlay from handling it. Return true when the press starts a gesture: the controller
-   * then captures the pointer until it is released or cancelled.
+   * the press landed on an annotation; the overlay then selects and activates it (text markup
+   * on a click, other types on the press), so tools other than the select tools should ignore
+   * such presses. Calling `e.stopPropagation()` here keeps the overlay from handling it.
+   * Return true when the press starts a gesture: the controller then captures the pointer
+   * until it is released or cancelled.
    */
   onPointerDown?(e: PointerEvent, hit: PageHit | undefined, annotationId?: string): boolean | void;
   /**
@@ -348,14 +387,26 @@ interface Tool {
 }
 interface ToolController {
   readonly active: Readable<ToolId>;
-  set(id: ToolId): void;
+  /** Switches to the tool, first merging `options` into its options. */
+  set(id: ToolId, options?: object): void;
+  /** Merges `patch` into a tool's options without switching to it. */
+  setOptions(id: ToolId, patch: object): void;
+  options(id: ToolId): Readable<object>;
   destroy(): void;
 }
 interface ToolControllerOptions {
-  ctx: ToolContext;
-  /** Default `'view'`. */
+  /** The controller adds `options`; `toolStyle` defaults to one of the controller's own. */
+  ctx: Omit<ToolContext, 'toolStyle' | 'options'> & {
+    toolStyle?: ToolStyle;
+  };
+  /** Default `'select-text'`. */
   initial?: ToolId;
   tools: Tool[];
+  /**
+   * Where options live. Pass the same registry to each controller that replaces another (a
+   * rebuild) so options persist; by default the controller keeps its own.
+   */
+  options?: ToolOptions;
 }
 /** The mounted page under a client point, with the point in CSS px and user space. */
 export declare function hitFor(ctx: ToolContext, e: {
@@ -363,12 +414,27 @@ export declare function hitFor(ctx: ToolContext, e: {
   clientY: number;
 }): PageHit | undefined;
 //#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;
+export declare function freetextTool(): Tool;
+//#endregion
 //#region src/dom/tools/highlight.d.ts
+type MarkupKind = TextMarkupAnnotation['type'];
+/** The text markup kinds, in menu order. */
+export declare const MARKUP_KINDS: readonly MarkupKind[];
+interface HighlightOptions {
+  /** Which text markup the tool makes. */
+  kind: MarkupKind;
+}
+export declare const DEFAULT_HIGHLIGHT_OPTIONS: Readonly<HighlightOptions>;
 /**
- * Turns the text selection into one highlight per page when the pointer is released, or on
- * Enter in the viewport (a keyboard selection). Without a selection both do nothing.
+ * Turns the text selection into one markup of the chosen kind per page when the pointer is
+ * released, or on Enter in the viewport (a keyboard selection), and selects what it made.
+ * Without a selection both do nothing. The markup's `contents` is left for a comment: hosts
+ * read the marked text with `doc.text(page)`.
  */
-export declare function highlightTool(): Tool;
+export declare function highlightTool(): Tool<HighlightOptions>;
 //#endregion
 //#region src/dom/tools/note.d.ts
 /**
@@ -381,25 +447,286 @@ export declare function noteTool(): Tool;
 export declare function redactAreaTool(): Tool;
 //#endregion
 //#region src/dom/tools/select.d.ts
+/**
+ * Rectangle select: a drag on empty space draws a marquee that selects the annotations it
+ * touches (`Shift` adds to the selection). Presses on annotations select, move and resize them
+ * as `select-text` does (selection-edit.ts).
+ */
 export declare function selectTool(): Tool;
 //#endregion
-//#region src/dom/tools/view.d.ts
-/** Reading only: text selection stays native and the overlay still selects annotations. */
-export declare function viewTool(): Tool;
+//#region src/dom/tools/select-text.d.ts
+/**
+ * The default tool. Text selection stays native: presses on text, and drags across text
+ * markup, select text. Presses on other annotations select them, and drags move and resize
+ * them (selection-edit.ts). There is no marquee.
+ */
+export declare function selectTextTool(): Tool;
+//#endregion
+//#region src/model/annotations/shape-geometry.d.ts
+/** Every kind the shape menu can offer. Kinds without a creator yet are not in `SHAPE_KINDS`. */
+type ShapeKind = 'line' | 'arrow' | 'rectangle' | 'roundedRectangle' | 'ellipse' | 'bubble' | 'star' | 'polygon' | 'loupe' | 'mask' | 'ovalMask';
+interface ShapeOptions {
+  kind: ShapeKind;
+  /** Points of a star. */
+  points: number;
+  /** Sides of a polygon. */
+  sides: number;
+}
+/** The kinds the shape menu offers today, in menu order. Later kinds extend this. */
+export declare const SHAPE_KINDS: readonly ShapeKind[];
+/** Side of the shape a click or Enter places, in points. */
+export declare const DEFAULT_SHAPE_SIZE = 72;
+/** Corner radius of a new rounded rectangle, in points. */
+export declare const DEFAULT_CORNER_RADIUS = 8;
+//#endregion
+//#region src/dom/tools/shape.d.ts
+export declare function shapeTool(): Tool<ShapeOptions>;
+//#endregion
+//#region src/dom/tools/signature.d.ts
+export declare function signatureTool(): Tool<SignatureOptions>;
 //#endregion
 //#region src/dom/tools/index.d.ts
 /** Fresh instances of every built-in tool. */
 export declare function builtinTools(): Tool[];
+/** The built-in tools with a host's tools added, a host tool replacing a built-in by id. */
+export declare function withHostTools(host?: readonly Tool[]): Tool[];
 /** Listens on `ctx.root` and routes pointer and key events to the active tool. */
 export declare function createToolController(opts: Omit<ToolControllerOptions, 'tools'> & {
   tools?: Tool[];
 }): ToolController;
+interface ToolStyleTracker {
+  readonly toolStyle: ToolStyle;
+  /** Call when the active tool changes: the style's active group follows it. */
+  setTool(id: ToolId): void;
+}
+/**
+ * A `ToolStyle` whose active group is the style group of the active tool among `tools` (the
+ * built-ins plus a host's). The engine makes one when it is not handed a style; a binding
+ * makes its own per document, so its style controls work before the viewport mounts.
+ */
+export declare function trackToolStyle(opts: {
+  store: AnnotationStore;
+  history: {
+    batch(fn: () => void): void;
+  };
+  /** Host tools, as passed to `mountViewer`. */
+  tools?: readonly Tool[] | undefined;
+  tool?: ToolId | undefined;
+}): ToolStyleTracker;
 //#endregion
 //#region src/dom/ui.d.ts
-/** Accessible names of the built-in tools, as the toolbar buttons announce them. */
-export declare const TOOL_LABELS: Readonly<Record<ToolId, string>>;
+/**
+ * Accessible names of the built-in tools, as the toolbar buttons announce them. A host tool has
+ * no entry: its button takes the host's `label`, else the tool id.
+ */
+export declare const TOOL_LABELS: Readonly<Partial<Record<ToolId, string>>>;
+/**
+ * The font families a text box offers by default: the PDF standard families, which a PDF
+ * writer can use without embedding a font. Hosts pass their own list as `fonts`.
+ */
+export declare const FONT_FAMILIES: readonly string[];
+/**
+ * The fonts a typed signature offers by default: the browser's own handwriting family. Hosts
+ * load handwriting fonts and pass them as `signatureFonts`.
+ */
+export declare const SIGNATURE_FONTS: readonly string[];
 /** Zoom levels the zoom select offers, as scale factors. */
 export declare const ZOOM_LEVELS: readonly number[];
+/** Stroke weights the line style menu offers, in points. */
+export declare const LINE_WEIGHTS: readonly number[];
+/** The dash pattern the menu's dashed choice writes, in points. */
+export declare const DASH_PATTERN: readonly number[];
+/** The ending the menu's arrowhead choices draw. */
+export declare const ARROWHEAD_ENDING: LineEnding;
+type ArrowheadChoice = 'none' | 'start' | 'end' | 'both';
+/** The arrowhead choices in menu order, with the style each one writes (`head` is the start). */
+export declare const ARROWHEAD_CHOICES: readonly {
+  value: ArrowheadChoice;
+  label: string;
+  patch: Pick<StyleProps, 'head' | 'tail'>;
+}[];
+/**
+ * Which arrowhead choice a style shows, `'mixed'` when the selection disagrees, else `undefined`.
+ * Only an ending Inkbar draws counts: one it does not know draws as `None`.
+ */
+export declare function arrowheadChoice(head: LineEnding | 'mixed' | undefined, tail: LineEnding | 'mixed' | undefined): ArrowheadChoice | 'mixed' | undefined;
+interface LineStyleMenuItem {
+  key: string;
+  label: string;
+  checked: boolean;
+  /** What choosing the item writes through the tool style. */
+  patch: StyleProps;
+}
+interface LineStyleMenuSection {
+  label: string;
+  /** The selection or active tool supports none of the section's props. */
+  disabled: boolean;
+  items: LineStyleMenuItem[];
+}
+interface LineStyleMenuModel {
+  /** False when nothing supports weight, pattern or endings: the trigger disables. */
+  enabled: boolean;
+  /** The selection disagrees on weight, pattern or endings. */
+  mixed: boolean;
+  sections: LineStyleMenuSection[];
+}
+/**
+ * What the line style menu shows for a style: sections of checkable items, each section
+ * disabled when `supported` lacks its props. A section whose value is mixed checks nothing.
+ * Shared by the bindings and the vanilla menu so they cannot drift apart.
+ */
+export declare function lineStyleMenuModel(current: CurrentStyle, supported: ReadonlySet<StyleKey>): LineStyleMenuModel;
+/** The colour props a colour menu can set. */
+type ColorProperty = 'border' | 'fill' | 'textColor';
+/** Accessible names of the colour menus, by property. */
+export declare const COLOR_LABELS: Readonly<Record<ColorProperty, string>>;
+/** Columns of the swatch grid: the arrow keys move by this much between rows. */
+export declare const COLOR_COLUMNS = 12;
+interface ColorMenuSwatch {
+  /** Unique within the menu. */
+  key: string;
+  /** The swatch's accessible name: its hex value. */
+  label: string;
+  color: string;
+  checked: boolean;
+  patch: StyleProps;
+}
+/** What the trigger's swatch shows. */
+type ColorTrigger = {
+  kind: 'color';
+  color: string;
+} |
+/** No fill. */
+{
+  kind: 'none';
+} |
+/** The selection disagrees. */
+{
+  kind: 'mixed';
+} |
+/** Nothing to show: the menu is disabled or the style has no value. */
+{
+  kind: 'empty';
+};
+interface ColorMenuModel {
+  label: string;
+  /** False when nothing supports the property: the trigger disables. */
+  enabled: boolean;
+  mixed: boolean;
+  trigger: ColorTrigger;
+  /** Common colours, greys, then the tonal grid, `COLOR_COLUMNS` to a row. */
+  swatches: ColorMenuSwatch[];
+  /** The "No fill" choice, for `fill` only. */
+  noFill: {
+    checked: boolean;
+    patch: StyleProps;
+  } | null;
+  /** The colour the custom picker starts on. */
+  customValue: string;
+  /** What picking `hex` in the custom picker writes. */
+  custom(hex: string): StyleProps;
+}
+/**
+ * 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.
+ */
+export declare function colorMenuModel(property: ColorProperty, current: CurrentStyle, supported: ReadonlySet<StyleKey>): 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';
+type TextAlignKey = 'left' | 'center' | 'right' | 'justify';
+interface TextStyleToggle {
+  key: TextToggleKey;
+  label: string;
+  /** `'mixed'` when the selection disagrees. */
+  pressed: boolean | 'mixed';
+  /** What pressing writes: the opposite of `pressed`, and on for a mix. */
+  patch: StyleProps;
+}
+interface TextAlignChoice {
+  key: TextAlignKey;
+  label: string;
+  checked: boolean;
+  /** The one radio in the Tab order: the checked one, else the first. */
+  tabStop: boolean;
+  patch: StyleProps;
+}
+interface TextStyleMenuModel {
+  label: string;
+  /** False when nothing supports text style: the trigger disables. */
+  enabled: boolean;
+  mixed: boolean;
+  font: {
+    label: string;
+    /** The family, or `''` when the selection disagrees. */
+    value: string;
+    /** The families on offer, each once; a current family outside the list is added. */
+    options: string[];
+    patch(family: string): StyleProps;
+  };
+  size: {
+    label: string;
+    /** The size, the default when the style sets none, or `null` when the selection disagrees. */
+    value: number | null;
+    min: number;
+    max: number;
+    step: number;
+    /** What committing a typed size writes, or `null` when it changes nothing. */
+    commit(raw: number): StyleProps | null;
+    /** What a stepper press writes, or `null` at the end of the range. */
+    nudge(direction: 1 | -1): StyleProps | null;
+  };
+  toggles: TextStyleToggle[];
+  align: {
+    label: string;
+    choices: TextAlignChoice[];
+  };
+}
+/**
+ * What the text style menu shows for a style: the font, size, bold/italic/underline and
+ * alignment, each with the patch choosing it. `fonts` is the list the host offers.
+ */
+export declare function textStyleMenuModel(current: CurrentStyle, supported: ReadonlySet<StyleKey>, fonts: readonly string[]): TextStyleMenuModel;
+/** Accessible names of the shape kinds, as the shape menu announces them. */
+export declare const SHAPE_LABELS: Readonly<Record<ShapeKind, string>>;
+/** Accessible names of the text markup kinds, as the highlight menu announces them. */
+export declare const MARKUP_LABELS: Readonly<Record<MarkupKind, string>>;
+interface HighlightMenuItem {
+  kind: MarkupKind;
+  label: string;
+  checked: boolean;
+}
+interface HighlightMenuModel {
+  /** The kind the main button makes. */
+  kind: MarkupKind;
+  /** The main button's accessible name. */
+  label: string;
+  /** The kinds on offer, in menu order, with the current one checked. */
+  items: HighlightMenuItem[];
+}
+/** What the highlight menu shows for the highlight tool's options. */
+export declare function highlightMenuModel(options: Partial<HighlightOptions>, kinds: readonly MarkupKind[]): HighlightMenuModel;
+/** Columns of the shape grid: the arrow keys move by this much between rows. */
+export declare const SHAPE_COLUMNS = 2;
+interface ShapeMenuItem {
+  kind: ShapeKind;
+  label: string;
+  checked: boolean;
+}
+interface ShapeMenuModel {
+  /** The kind the main button draws. */
+  kind: ShapeKind;
+  /** The main button's accessible name. */
+  label: string;
+  /** The kinds on offer, in menu order, with the current one checked. */
+  items: ShapeMenuItem[];
+}
+/**
+ * What the shape menu shows for the shape tool's options, over the kinds in `kinds`
+ * (`SHAPE_KINDS`). A kind that is not on offer falls back to `rectangle` when that is offered,
+ * else to the first.
+ */
+export declare function shapeMenuModel(options: Partial<ShapeOptions>, kinds: readonly ShapeKind[]): ShapeMenuModel;
 /** The overlay's per-annotation state, as on its `data-state` attribute. */
 type AnnotationState = 'idle' | 'hover' | 'selected';
 /**
@@ -417,9 +744,16 @@ interface AnnotationSlotProps {
   /** Removes a suggested redaction. No-op for anything else. */
   dismiss: () => void;
 }
-/** What a host-rendered note thread receives. */
-interface NotePopoverSlotProps {
-  note: NoteAnnotation;
+/** The thread popover's accessible name: "Note thread" for a note, "Comment thread" for markup. */
+export declare function threadPopoverLabel(root: Pick<Annotation, 'type'>): string;
+/**
+ * The thread popover's delete button. It removes the root and its replies, so on text markup
+ * it says it deletes the highlight, not only the comment.
+ */
+export declare function threadDeleteLabel(root: Pick<Annotation, 'type'>): string;
+/** What a host-rendered comment thread receives: a note's, or text markup's. */
+interface ThreadPopoverSlotProps {
+  root: NoteAnnotation | TextMarkupAnnotation;
   replies: Annotation[];
   reply: (text: string) => void;
   update: (contents: string) => void;
@@ -435,6 +769,109 @@ interface SuggestionCardSlotProps {
   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. */
+  readonly sign: "Sign";
+  readonly trigger: "Choose signature";
+  readonly menu: "Signatures";
+  readonly saved: "Saved signatures";
+  readonly create: "Create signature";
+  /** The dialog's title. */
+  readonly dialog: "Create signature";
+  readonly tabs: "Signature source";
+  readonly draw: "Draw";
+  readonly type: "Type";
+  readonly image: "Image";
+  readonly pad: "Signature pad";
+  readonly clear: "Clear";
+  readonly name: "Name";
+  readonly namePlaceholder: "Your name";
+  readonly fonts: "Font";
+  readonly file: "Image file";
+  readonly cancel: "Cancel";
+  readonly save: "Save";
+};
+/** The dialog's tabs, in order. */
+export declare const SIGNATURE_TABS: readonly ["draw", "type", "image"];
+type SignatureTab = (typeof SIGNATURE_TABS)[number];
+interface SignatureMenuItem {
+  id: string;
+  /** `Signature 1`, `Signature 2`… in saved order. */
+  label: string;
+  /** The remove button's accessible name. */
+  removeLabel: string;
+  checked: boolean;
+  template: SignatureTemplate;
+}
+interface SignatureMenuModel {
+  /** The template the tool places, when it is still saved. */
+  selected: SignatureTemplate | undefined;
+  items: SignatureMenuItem[];
+}
+/** What the signature menu shows for the saved templates and the signature tool's options. */
+export declare function signatureMenuModel(templates: readonly SignatureTemplate[], options: SignatureOptions): SignatureMenuModel;
+//#endregion
+//#region src/dom/palette.d.ts
+interface Palette {
+  /** 12 swatches, the top row. */
+  readonly common: readonly string[];
+  /** 12 greys, white to black. */
+  readonly greys: readonly string[];
+  /** 8 rows of 12 hue columns (red round to rose in 30 degree steps), dark to light. */
+  readonly grid: readonly (readonly string[])[];
+}
+export declare const PALETTE: Palette;
+//#endregion
+//#region src/dom/freetext-editor.d.ts
+interface FreeTextEditor {
+  /** Closes the editor, handing its text to `commit` (true) or calling `cancel` (false). */
+  close(commit: boolean): void;
+}
+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.
+   */
+  commit(contents: string, rect: Rect, grown: number): void;
+  cancel(): void;
+}
+/**
+ * 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.
+ * 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.
+ */
+export declare function editFreeText(el: HTMLElement, a: FreeTextAnnotation, opts: FreeTextEditorOptions): FreeTextEditor;
+//#endregion
+//#region src/dom/menu-keys.d.ts
+/** The menu's enabled items in document order. */
+export declare function menuItems(root: ParentNode): HTMLElement[];
+/** Focuses the first checked item, else the first enabled one. */
+export declare function focusInitialMenuItem(root: ParentNode): void;
+/**
+ * ArrowDown and ArrowUp move between enabled items and wrap; Home and End go to the ends.
+ * Inside a grid the arrow keys move in both directions.
+ */
+export declare function handleMenuKeys(e: KeyboardEvent, root: ParentNode): void;
+/**
+ * Arrow keys inside a `role="radiogroup"`: the next (or previous) enabled `role="radio"`
+ * takes focus and is chosen, wrapping at the ends, as a native radio group does.
+ */
+export declare function handleRadioKeys(e: KeyboardEvent, group: ParentNode): void;
+/**
+ * Arrow keys, Home and End inside a `role="tablist"`: the next (or previous) enabled
+ * `role="tab"` takes focus and is chosen, wrapping at the ends.
+ */
+export declare function handleTabKeys(e: KeyboardEvent, tablist: ParentNode): void;
+/**
+ * Keeps Tab inside `container`, a modal: Tab from its last stop goes to its first, and
+ * Shift+Tab from the first to the last.
+ */
+export declare function trapTab(e: KeyboardEvent, container: HTMLElement): void;
 //#endregion
 //#region src/dom/annotation-element.d.ts
 /** The overlay element drawn for annotation `id` under `root`, if it is in the DOM. */
@@ -482,6 +919,53 @@ interface MountViewerOptions {
   gap?: number;
   buffer?: number;
   tool?: ToolId;
+  /**
+   * Host tools, added to the built-ins. A host tool with a built-in's id replaces it. The same
+   * instances are reused when the engine rebuilds.
+   */
+  tools?: Tool[];
+  /**
+   * The tools' options (the shape kind, the highlight kind…). A binding or `createViewer` passes
+   * one it keeps for its own life, so options persist across documents, as for the life of the
+   * viewer. By default the engine makes one, which lasts as long as the engine.
+   */
+  toolOptions?: ToolOptions;
+  /**
+   * The style the tools create with. A binding passes its own, made with `trackToolStyle` and
+   * its own history (and keeps its active group in step with the tool). By default the engine
+   * makes one over the document's history.
+   */
+  toolStyle?: ToolStyle;
+  /**
+   * The history the tools group a gesture's changes with (a group move, a sketch's swap to its
+   * shape). A binding passes its own, so a controlled host's undo steps match the gesture. By
+   * default the document's history.
+   */
+  toolHistory?: {
+    batch(fn: () => void): void;
+  };
+  /**
+   * The font families text boxes offer, replacing the default `FONT_FAMILIES` (the PDF
+   * standard families). Fonts beyond those are the PDF writer's to embed.
+   */
+  fonts?: string[];
+  /**
+   * Where signature templates live. Default: memory, gone on reload
+   * (`createMemorySignatureStore`). `createLocalSignatureStore` keeps them in the browser.
+   */
+  signatures?: SignatureStore;
+  /**
+   * 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`.
+   * A function is read each time the library is needed, so a host that swaps its library
+   * after mount reaches the tool too.
+   */
+  signatureLibrary?: SignatureLibrary | (() => SignatureLibrary);
+  /**
+   * The handwriting fonts a typed signature offers. The host loads them (`@font-face`).
+   * Default `SIGNATURE_FONTS`.
+   */
+  signatureFonts?: string[];
   /** Annotation content is rendered by the host (custom slots). Changing it needs `rebuild`. */
   customAnnotations?: boolean;
   onActivate?(id: string): void;
@@ -510,6 +994,17 @@ interface MountViewerOptions {
 interface ViewerEngine {
   readonly viewport: Viewport;
   readonly tools: ToolController;
+  /**
+   * The style each group creates with, shared by the tools and the style controls. It lives as
+   * long as the engine, across rebuilds.
+   */
+  readonly toolStyle: ToolStyle;
+  /** The font families text boxes offer: the `fonts` option, else `FONT_FAMILIES`. */
+  readonly fonts: readonly string[];
+  /** The signature templates: the host's current library, or the engine's own. */
+  readonly signatures: SignatureLibrary;
+  /** The fonts a typed signature offers: the `signatureFonts` option, else `SIGNATURE_FONTS`. */
+  readonly signatureFonts: readonly string[];
   readonly pages: ReadonlyMap<number, PageMount>;
   /**
    * Recreates the viewport for construction-only options, keeping zoom, page, mode, rotation
@@ -527,7 +1022,12 @@ interface ViewerEngine {
 export declare function mountViewer(opts: MountViewerOptions): ViewerEngine;
 //#endregion
 //#region src/dom/viewer/create-viewer.d.ts
-interface CreateViewerOptions extends Omit<MountViewerOptions, 'container' | 'document'> {
+/**
+ * The engine options, less what the viewer owns: the container, the document, the tool style
+ * (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'> {
   source: DocumentSource;
   assets: PdfAssets;
   /** User password for encrypted files. `open` can pass its own for one load. */
@@ -535,8 +1035,8 @@ interface CreateViewerOptions extends Omit<MountViewerOptions, 'container' | 'do
   /** Default: read from the theme's CSS variables on the viewer root. */
   defaults?: AnnotationDefaults;
   history?: OpenOptions['history'];
-  /** Note thread popover. Default true. */
-  notes?: boolean;
+  /** 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;
@@ -586,7 +1086,10 @@ export declare function createToolbarSeparator(): HTMLDivElement;
 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. */
+/**
+ * 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.
+ */
 export declare function createToolButton(viewer: Viewer, tool: ToolId, opts?: {
   label?: string;
 }): HTMLButtonElement;
@@ -606,5 +1109,191 @@ export declare function createPrevPage(viewer: Viewer): HTMLButtonElement;
 /** Disabled on the last page. */
 export declare function createNextPage(viewer: Viewer): HTMLButtonElement;
 //#endregion
-export { type AnnotationSlotProps, type AnnotationState, type CreateViewerOptions, type CssLayout, type CssLayoutInput, type CssPageBox, type CssRect, type FocusReturn, type FocusReturnOptions, type LayoutMode, type MountViewerOptions, type NotePopoverSlotProps, type Overlay, type OverlayOptions, type PageHit, type PageLayer, type PageMount, type PageMountOptions, type PageRenderer, type PageRendererOptions, type PageTransform, type SelectionQuads, type SuggestionCardSlotProps, type TextLayerHandle, type TextLayerOptions, type Tool, type ToolContext, type ToolController, type ToolControllerOptions, type ToolId, type ViewRotation, type Viewer, type ViewerEngine, type Viewport, type ViewportHit, type ViewportKeysOptions, type ViewportOptions, type ZoomValue, cssVariableDefaults };
+//#region src/dom/viewer/style-menu.d.ts
+/** A button that opens the line style menu: weight, solid or dashed, and arrowheads. */
+export declare function createLineStyleMenu(viewer: Viewer): HTMLButtonElement;
+//#endregion
+//#region src/dom/viewer/color-menu.d.ts
+interface ColorMenuOptions {
+  property: ColorProperty;
+  /** Accessible name; defaults to "Border colour", "Fill colour" or "Text colour". */
+  label?: string;
+  /**
+   * Scopes the menu to one style group (`ToolStyle.scoped`): it shows and sets that group's
+   * colour whatever tool is active, and recolours the selection only when it is all in the group.
+   */
+  group?: StyleGroup;
+}
+/** 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;
+//#endregion
+//#region src/dom/viewer/text-style-menu.d.ts
+/** A button that opens the text style menu: font, size, colour, emphasis and alignment. */
+export declare function createTextStyleMenu(viewer: Viewer): HTMLButtonElement;
+//#endregion
+//#region src/dom/viewer/shape-menu.d.ts
+/** A split button: the main part draws with the current shape kind, the chevron picks the kind. */
+export declare function createShapeMenu(viewer: Viewer): HTMLElement;
+//#endregion
+//#region src/dom/viewer/highlight-menu.d.ts
+/** A split button: the main part marks text with the current kind, the chevron picks it. */
+export declare function createHighlightMenu(viewer: Viewer): HTMLElement;
+//#endregion
+//#region src/dom/shape-icons.d.ts
+export declare const SHAPE_ICONS: Readonly<Record<ShapeKind, IconNode>>;
+//#endregion
+//#region src/dom/markup-icons.d.ts
+export declare const MARKUP_ICONS: Readonly<Record<MarkupKind, IconNode>>;
+//#endregion
+//#region src/dom/viewer/menu.d.ts
+interface MenuOptions {
+  label: string;
+  /** Extra attributes for the panel. */
+  attrs?: Record<string, string>;
+  /**
+   * The panel's role. `menu` (the default) is a list of items with arrow-key movement; `dialog`
+   * is for a panel of mixed widgets, which take Tab and their own keys, and opens on the first
+   * focusable one.
+   */
+  role?: 'menu' | 'dialog';
+  /**
+   * 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.
+   */
+  owns?(target: Node): boolean;
+  /** Builds the items on first call and updates them in place after; called on open and `refresh`. */
+  render(menu: HTMLElement): void;
+}
+interface Menu {
+  readonly isOpen: boolean;
+  /** Re-renders an open menu, and closes it if the trigger has become disabled. */
+  refresh(): void;
+  close(restoreFocus?: boolean): void;
+}
+export declare function createMenu(trigger: HTMLButtonElement, opts: MenuOptions): Menu;
+//#endregion
+//#region src/dom/signature-pad.d.ts
+interface SignaturePad {
+  /** The drawing surface, `svg.ink-signature-pad`, filling the host. */
+  readonly element: SVGSVGElement;
+  /** True while nothing is drawn. */
+  readonly empty: Readable<boolean>;
+  clear(): void;
+  /** The drawing as an ink template with a new id; undefined while the pad is empty. */
+  toTemplate(): SignatureTemplate | undefined;
+  destroy(): void;
+}
+/**
+ * A drawing pad in `host`. Each press-drag-release is a stroke; the theme colours it through
+ * `path.ink-stroke` (`fill: currentColor` by default).
+ */
+export declare function createSignaturePad(host: HTMLElement): SignaturePad;
+/** `font` as a CSS font-family value: quoted unless it is a generic family. */
+export declare function fontFamilyValue(font: string): string;
+interface TypedSignatureOptions {
+  /** The image's height in pixels. Default 96. */
+  height?: number;
+  /** The ink colour. Default `#151820`, the theme's ink. */
+  color?: string;
+}
+/**
+ * `name` drawn in `font` on a transparent canvas, as a PNG data URL. Waits for the font to load
+ * (`document.fonts.load`) first. Rejects with a RangeError for an empty name.
+ */
+export declare function renderTypedSignature(name: string, font: string, opts?: TypedSignatureOptions): Promise<string>;
+/** A typed signature as an image template, with a new id. */
+export declare function createTypedSignature(name: string, font: string, opts?: TypedSignatureOptions): Promise<SignatureTemplate>;
+/** The image types a signature image may be. */
+export declare const SIGNATURE_IMAGE_TYPES: readonly string[];
+/** The longest side, in pixels, an image signature is stored at. */
+export declare const SIGNATURE_IMAGE_MAX_SIDE = 1000;
+/**
+ * The longest data URL, in characters, an image signature may be once scaled. Templates live
+ * in host storage (`localStorage` holds about 5 MB) and are copied into every placed stamp.
+ */
+export declare const SIGNATURE_IMAGE_MAX_LENGTH = 3000000;
+/**
+ * An image file (a scan of a signature) as an image template. The image is drawn again at no
+ * more than `SIGNATURE_IMAGE_MAX_SIDE` pixels on its long side, as a PNG (a JPEG stays a JPEG,
+ * as photos compress far better that way), so a phone photo does not fill the store. Rejects
+ * with a TypeError for anything but a PNG or JPEG, and a RangeError when the result is still
+ * longer than `SIGNATURE_IMAGE_MAX_LENGTH`.
+ */
+export declare function createImageSignature(file: Blob): Promise<SignatureTemplate>;
+/**
+ * An ink template drawn for a menu: one filled outline per stroke (the `draw` renderer) in a
+ * `viewBox` of the template's aspect, with room for the stroke. Paint `paths` with
+ * `fill: currentColor`.
+ */
+export declare function signaturePreview(t: SignatureTemplate & {
+  kind: 'ink';
+}): {
+  viewBox: string;
+  paths: string[];
+};
+//#endregion
+//#region src/dom/signature-draft.d.ts
+interface SignatureDraftState {
+  tab: SignatureTab;
+  /** True while the pad has nothing on it. */
+  padEmpty: boolean;
+  name: string;
+  font: string;
+  /** The chosen image, read and checked. */
+  image: SignatureTemplate | undefined;
+  /** Why the chosen file was refused, for the Image tab to show. */
+  imageError: string | undefined;
+  /** Why the last save failed (the store refused it, full or offline), for the dialog to show. */
+  saveError: string | undefined;
+  /** True when the open tab has something to save. */
+  canSave: boolean;
+  saving: boolean;
+}
+interface SignatureDraft {
+  readonly state: Readable<SignatureDraftState>;
+  readonly fonts: readonly string[];
+  setTab(tab: SignatureTab): void;
+  setName(name: string): void;
+  setFont(font: string): void;
+  /** Mounts the pad in `host`; returns its teardown. One pad at a time. */
+  attachPad(host: HTMLElement): () => void;
+  clearPad(): void;
+  /** Reads an image file for the Image tab. */
+  chooseFile(file: Blob | undefined): Promise<void>;
+  /**
+   * Builds the open tab's template and saves it to `library`. Resolves with it, or undefined
+   * when there is nothing to save, the save failed (setting `saveError`), or the draft was
+   * destroyed before the save finished.
+   */
+  save(library: SignatureLibrary): Promise<SignatureTemplate | undefined>;
+  /** Back to an empty Draw tab. */
+  reset(): void;
+  destroy(): void;
+}
+export declare function createSignatureDraft(opts?: {
+  fonts?: readonly string[];
+}): SignatureDraft;
+//#endregion
+//#region src/dom/viewer/signature-dialog.d.ts
+interface SignatureDialogOptions {
+  /** The fonts the Type tab offers. Default: the viewer's `signatureFonts`. */
+  fonts?: string[];
+}
+interface SignatureDialog {
+  readonly isOpen: boolean;
+  /** Opens the dialog. On close, focus goes to `returnFocus`, else to what had it before. */
+  open(opts?: {
+    returnFocus?: HTMLElement | null;
+  }): void;
+  close(): void;
+  destroy(): void;
+}
+export declare function createSignatureDialog(viewer: Viewer, opts?: SignatureDialogOptions): SignatureDialog;
+//#endregion
+//#region src/dom/viewer/signature-menu.d.ts
+/** A template drawn small: ink as an SVG of filled outlines, an image as an `<img>`. */
+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 };
 //# sourceMappingURL=dom.d.mts.map