@toclocoinc/lattice-grid 1.1.1 → 1.4.2

package/lattice-grid.d.ts

@@ -1,5 +1,5 @@
 /*!
- * Lattice Grid 1.1.0 — type declarations
+ * Lattice Grid 1.4.0 — type declarations
  * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
  * https://latticegrid.dev
  */
@@ -18,11 +18,29 @@
 
 export type TypeName =
   | 'text' | 'number' | 'boolean' | 'date' | 'dateString' | 'object' | 'lookup'
+  | 'image'
   | (string & {});
 
-export type Align = 'start' | 'center' | 'end';
-export type Density = 'compact' | 'comfortable';
-export type Theme = 'light' | 'dark' | (string & {});
+/**
+ * Cell and header alignment.
+ *
+ * `left` and `right` are accepted and normalised to `start` and `end`. The grid
+ * has no RTL handling today, so the two pairs are exact synonyms; if direction
+ * support lands, `start`/`end` will follow the text direction while
+ * `left`/`right` stay physical. `centre` is accepted alongside `center`.
+ */
+export type Align = 'start' | 'center' | 'end' | 'left' | 'right' | 'centre';
+/**
+ * A named preset, or a raw scale where 1 is `standard`. Row heights are
+ * 23.8 / 28 / 42 / 56px for the four presets; a number scales 28px.
+ */
+export type Density = 'compact' | 'standard' | 'comfortable' | 'spacious' | number;
+/**
+ * A shipped theme, or your own name — the value is written to `data-theme` on
+ * the grid's root, so `.lattice[data-theme="mine"]` is all a custom one needs.
+ * Unset follows the viewer's `prefers-color-scheme`.
+ */
+export type Theme = 'light' | 'dark' | 'high-contrast' | 'terminal' | (string & {});
 export type ColumnRef = string;
 export type Comparator = (
   a: unknown, b: unknown, rowA?: Row, rowB?: Row, descending?: boolean,
@@ -68,10 +86,27 @@ export interface RowChange {
   remove?: unknown[] | string[];
 }
 
+/** A row a change could not apply, and why. Reported, never thrown. */
+export interface RejectedRow {
+  operation: 'add' | 'update' | 'remove';
+  id: string;
+  /**
+   * `unknown-id` — no row with that key. `duplicate-id` — a row with that key
+   * already exists; admitting a second would corrupt every structure that
+   * resolves one key to one row.
+   */
+  reason: 'unknown-id' | 'duplicate-id';
+}
+
 export interface ChangeResult {
   added: Row[];
   updated: Row[];
   removed: string[];
+  /**
+   * Rows that could not be applied. A batch of a thousand containing three bad
+   * ones applies the other 997 and lists the three here.
+   */
+  rejected?: RejectedRow[];
 }
 
 // ---------------------------------------------------------------------------
@@ -175,6 +210,8 @@ export interface DataType {
     editor?: EditorName;
     total?: TotalName;
     align?: Align;
+    /** The cell renderer this type's values are drawn with by default. */
+    render?: RendererName;
   };
   storage?: 'float64' | 'int32' | 'bitset' | 'dictionary' | 'object';
   excel?: string;
@@ -270,7 +307,24 @@ export interface Editor {
   destroy?(): void;
 }
 export type EditorCtor = new () => Editor;
-export type EditorName = 'text' | 'textarea' | 'number' | 'date' | 'checkbox' | 'select' | 'multiSelect' | (string & {});
+/** The built-in tool panels, addressable by name from configuration. */
+export type ToolPanelName = 'columns' | 'filters' | 'views' | 'quick' | 'formatting' | (string & {});
+
+/**
+ * The built-in cell renderers, addressable by name through `cell.render`.
+ * Anything registered through `components` is also valid here.
+ */
+export type RendererName =
+  | 'area' | 'bullet' | 'checkbox' | 'colour' | 'column' | 'delta' | 'detailExpander'
+  | 'donut' | 'gauge' | 'group' | 'icon' | 'image' | 'line' | 'link' | 'pie' | 'pill'
+  | 'progress' | 'qrcode' | 'range' | 'rating' | 'skeleton' | 'stacked' | 'twoline'
+  | 'winloss' | (string & {});
+
+export type EditorName =
+  | 'checkbox' | 'code' | 'colour' | 'date' | 'datetime' | 'duration' | 'iconPicker'
+  | 'ipaddress' | 'multiSelect' | 'number' | 'objectPicker' | 'password' | 'radix'
+  | 'rating' | 'segmented' | 'select' | 'slider' | 'text' | 'textarea' | 'time'
+  | 'treeSelect' | 'unit' | (string & {});
 
 export interface EditorParams extends CellParams {
   stop(cancel?: boolean): void;
@@ -424,6 +478,8 @@ export interface ColumnGroup {
   showWhen?: 'open' | 'closed' | 'always';
   marryChildren?: boolean;
   header?: { render?: string | RendererCtor; props?: Record<string, unknown>; class?: string | string[] };
+  /** This column's histogram. `true` turns it on with the grid's settings. */
+  facet?: ColumnFacetConfig | boolean;
 }
 
 /** A column after presets, type defaults and grid defaults are folded in. */
@@ -570,6 +626,15 @@ export interface StreamSourceConfig {
     context: unknown;
     signal: AbortSignal;
   }): AsyncIterable<Chunk>;
+  /**
+   * The most rows to keep. A stream has no end, so an unbounded grid dies
+   * overnight; this makes it a sliding window and the oldest rows are dropped.
+   * Omit for no limit.
+   *
+   * Set on the source, not passed to `open` — it bounds what the grid retains
+   * rather than what the producer sends.
+   */
+  maxRows?: number;
   promoteToMemoryBelow?: number;
   coalesceMs?: number;
 }
@@ -587,6 +652,10 @@ export interface TreeConfig {
   orphans?: 'root' | string;
   hasChildren?: (row: unknown) => boolean;
   loadChildren?: (row: Row, signal: AbortSignal) => Promise<unknown[]>;
+  /** Where the generated tree column takes its text from: a field or a function. */
+  label?: string | ((data: unknown, row: Row) => unknown);
+  /** The tree column's heading. Defaults to the label column's own title. */
+  title?: string;
 }
 
 export interface DetailConfig {
@@ -596,7 +665,22 @@ export interface DetailConfig {
   rows?: (row: Row) => unknown[] | Promise<unknown[]>;
   height?: number | 'auto' | ((row: Row) => number);
   cacheLimit?: number;
-  isMaster?: (row: unknown) => boolean;
+  isMaster?: (data: unknown, row: Row) => boolean;
+  /**
+   * Render the detail into this element instead of into a row beneath its
+   * master. A selector or an element. Exactly one detail is open at a time in
+   * this placement (§13).
+   */
+  target?: string | HTMLElement;
+  /** Handed the nested grid as it is created, for whatever the forwarded events do not cover. */
+  onCreate?: (grid: Grid, masterRow: Row) => void;
+  /**
+   * The property of the master's record the detail rows live on, so an edit in
+   * the detail is reported as a path on the master — `ports.1.vlan`. Inferred
+   * by identity when `rows(row)` returns an array already on the record, which
+   * is the usual shape; set this when it does not (§13).
+   */
+  path?: string;
 }
 
 export interface SelectionConfig {
@@ -616,6 +700,28 @@ export interface EditConfig {
   start?: 'single' | 'double' | 'key';
   enterMovesDown?: boolean;
   undoDepth?: number;
+  commit?: (write: PendingWrite) => unknown;
+  confirm?: 'auto' | 'manual';
+  pendingTimeout?: number;
+}
+
+export interface PendingWrite {
+  id: string;
+  key: string;
+  colId: string;
+  value: unknown;
+  before: unknown;
+  row?: Row;
+}
+
+export interface OpenWrite {
+  id: string;
+  key: string;
+  colId: string;
+  value: unknown;
+  before: unknown;
+  state: 'pending' | 'superseded';
+  age: number;
 }
 
 export interface PaginationConfig {
@@ -633,6 +739,8 @@ export interface GridConfig {
   columnDefaults?: Column;
   columnPresets?: Record<string, Column>;
   dataTypes?: Record<string, DataType>;
+  /** Values sampled per undeclared column when inferring its type. Default 100. */
+  sampleSize?: number;
   components?: Record<string, RendererCtor | EditorCtor | FilterCtor>;
   pipes?: Record<string, (value: unknown, ...args: string[]) => string>;
   totalFns?: Record<string, TotalFn>;
@@ -653,24 +761,95 @@ export interface GridConfig {
   rowHeight?: number | ((row: Row) => number);
   headerHeight?: number;
   overscan?: number;
+  /**
+   * Size rows to their content rather than to the density token.
+   *
+   * Only rows that are actually rendered are ever measured, in both settings —
+   * the grid does not lay out rows you cannot see. The difference is what
+   * happens on a large grid: `true` gives up above ten thousand rows and falls
+   * back to fixed heights, because a cumulative offset array being patched as
+   * you scroll a million rows is not worth the result. `'visible'` keeps
+   * measuring at any size, accepting that the scrollbar shifts as rows are
+   * measured on the way past.
+   *
+   * The name is historical and reads as though it were about which rows are
+   * measured; it is about whether the ceiling applies.
+   */
   autoHeight?: boolean | 'visible';
   state?: GridState;
   licence?: string;
   maximise?: boolean;
+  /** Extra functions a formula may call, on top of the built-in library. */
+  formulaFunctions?: Record<string, (args: unknown[]) => unknown>;
   allowUnsafeTemplates?: boolean;
+  /**
+   * Caps on the change log behind `grid.updates` and `grid.timeline`.
+   *
+   * Two caps, because an entry is not a fixed size: `logLimit` bounds how many
+   * changes are kept (default 2000) and `logRows` bounds the rows they account
+   * for between them (default 100,000). A feed delivering large batches reaches
+   * the second long before the first, and without it the log is unbounded in
+   * bytes while looking bounded in entries.
+   */
+  updates?: {
+    logLimit?: number;
+    logRows?: number;
+    /**
+     * When a queued batch applies. `frame` (default) lands on a paint
+     * boundary, which is what makes one repaint per batch reliable;
+     * `microtask` at the end of the current task; `interval` on the coalescing
+     * window; `manual` only when you call `grid.updates.flush()`.
+     */
+    flush?: 'frame' | 'microtask' | 'interval' | 'manual';
+    /** Queued rows that force an early flush regardless of strategy. */
+    maxQueued?: number;
+    /** Milliseconds one flush may spend before deferring the rest. */
+    budgetMs?: number;
+  };
+  /**
+   * Threaded comments on individual cells (§16). Requires a stable
+   * `rowKey`: comments outlive the values they annotate, and index
+   * identity would reattach every thread on the next sort.
+   */
+  comments?: CommentConfig;
+  /**
+   * Collaborative presence (§18). A display feature over a transport the
+   * grid does not own; without a provider it is inert.
+   */
+  presence?: PresenceConfig;
+  /**
+   * Host environment for a support bundle. Supplied by the DOM layer;
+   * core cannot read `navigator` or `window` itself (§3.1).
+   */
+  environment?: () => Record<string, unknown>;
+  /**
+   * Column header histograms and the filters clicking them creates (§9.6).
+   *
+   * Off by default: the band roughly doubles header height, which is a cost
+   * no grid should pay without asking. Per-column settings layer over these.
+   */
+  facets?: FacetConfig | boolean;
   hostFilter?: { active(): boolean; passes(row: Row): boolean };
   context?: unknown;
+  /** Row count above which a column distribution is computed in a Worker. */
   workerThreshold?: number;
+  /**
+   * Compute column distributions off the main thread. Sorting, filtering and
+   * grouping run on the main thread; see §5.13 for why.
+   */
   useWorker?: boolean;
   workerUrl?: string;
   sharedMemory?: boolean;
   groupFooter?: boolean;
   /**
-   * Where the grand total goes. `'bottom'` pins it below the rows; omitted
-   * leaves it inline with the data. Only the string is recognised — `true`
-   * does nothing.
+   * Where the grand total goes.
+   *
+   * `true` adds it as the last display row, counted by `rows.count()` like any
+   * other. `'bottom'` pins it beneath the viewport instead, so it stays in
+   * view while the rows scroll and is *not* part of `rows.count()`. Omitted or
+   * `false` means no grand total row.
    */
-  grandTotalRow?: 'bottom';
+  grandTotalRow?: boolean | 'bottom';
   totalFilteredOnly?: boolean;
   totalOnlyChangedColumns?: boolean;
   showTotalInHeader?: boolean;
@@ -681,7 +860,7 @@ export interface GridConfig {
    * suppresses it entirely, which is what a read-only grid wants — the default
    * menu offers Paste, Clear and Fill down.
    */
-  contextMenu?: boolean | ((p: CellParams) => MenuItem[]);
+  contextMenu?: boolean | ((p: CellMenuParams, defaults: MenuItem[]) => MenuItem[] | void);
   /** The header's 3-dot menu. `false` suppresses it. Default true. */
   columnMenu?: boolean;
   /**
@@ -695,13 +874,20 @@ export interface GridConfig {
     duration?: number;
     enabled?: boolean;
   };
+  /**
+   * Conditional formatting rules the grid holds as runtime state, keyed by
+   * column id or `'*'` for every column (spec 8.12). Seeds `grid.formatting`,
+   * which an end user can then change; the rules travel in saved views and
+   * undo like any other change. Config-time `cell.style` is unaffected.
+   */
+  formatting?: Record<string, FormattingRule[]>;
   /** A class, or classes, for every row. Re-evaluated on each repaint. */
   rowClass?: string | string[] | ((p: RowStyleParams) => string | string[]);
   /** Inline styles for every row. Camel-case or hyphenated property names. */
   rowStyle?: CellStyle | ((p: RowStyleParams) => CellStyle);
   toolPanel?: boolean | {
-    /** Built-in names: `columns`, `filters`, `views`, `quick`. */
-    panels?: string[];
+    /** Built-in names: `columns`, `filters`, `views`, `quick`, `formatting`. */
+    panels?: ToolPanelName[];
     openPanel?: string;
     /** Which edge to dock against. `left` is the icon rail; default `right`. */
     side?: 'left' | 'right';
@@ -711,7 +897,14 @@ export interface GridConfig {
      * Rail action buttons: `undo`, `redo`, `export`, `restore`. Defaults to all
      * four on the left rail and none on the right; `false` drops them.
      */
-    actions?: false | ('undo' | 'redo' | 'export' | 'restore')[];
+    /**
+     * Which action buttons the rail offers, in order. `false` drops them.
+     *
+     * The built-in names are `undo`, `redo`, `pause`, `restore`, `maximise`,
+     * `export`, `excel`, `clipboard` and `print`, plus `'-'` for a divider.
+     * A {@link RailAction} object places one of your own among them.
+     */
+    actions?: false | (RailActionName | '-' | RailAction)[];
     /** File name for the export action, without the extension. */
     exportName?: string;
   };
@@ -723,7 +916,27 @@ export interface GridConfig {
    */
   permissions?: PermissionPolicy;
   /** Prior state for diff and audit mode (§12). */
-  diff?: { snapshot?: unknown[] | Map<string, unknown>; strictNull?: boolean; addedColumns?: 'unchanged' | 'changed' };
+  diff?: {
+    snapshot?: unknown[] | Map<string, unknown>;
+    strictNull?: boolean;
+    addedColumns?: 'unchanged' | 'changed';
+    /**
+     * Whether a row present in the snapshot but gone from the data is shown,
+     * and whether it counts as data when it is.
+     *
+     * `false` — the default — leaves it out entirely. `'pinned'` shows it
+     * beneath the rows, struck through: visible history that is not part of the
+     * row set, so it is excluded from `rows.count()`, from exports and from
+     * selection. `'data'` appends it to the row set instead, so it *is*
+     * counted and exported.
+     *
+     * Neither is sorted or filtered among the live rows: a removed row's values
+     * are the snapshot's, and ordering yesterday's numbers among today's would
+     * present two data sets as one. Neither can be edited — there is nothing
+     * left to write to.
+     */
+    removedRows?: false | 'pinned' | 'data';
+  };
   /** Saved views (§15): a storage adapter and any pre-loaded views. */
   views?: { storage?: { read(): unknown[]; write(views: unknown[]): void }; saved?: unknown[] };
   /** The undo toolbar. `element` mounts it into the host's own chrome. */
@@ -733,13 +946,35 @@ export interface GridConfig {
    * host's, and owns the model, the key and the privacy decision.
    */
   ai?: {
-    ask(p: { prompt: string; schema: unknown; context?: unknown }): Promise<unknown>;
+    ask(p: {
+    /** The full text to send: the schema description and the question together. */
+    prompt: string;
+    /** The grid's schema as data — columns, types and operators. No row values. */
+    schema: unknown;
+    /** The same schema rendered as text, which is what `prompt` embeds. */
+    schemaText: string;
+    /** What the user typed. */
+    message: string;
+    context?: unknown;
+  }): Promise<unknown>;
     schemaOptions?: object;
     context?: unknown;
     element?: HTMLElement;
     placeholder?: string;
   };
-  pivot?: { enabled?: boolean; groupTotals?: 'before' | 'after' | false; maxColumns?: number; separator?: string };
+  pivot?: {
+    enabled?: boolean;
+    /**
+     * Add a column group totalling every value column across all pivot values —
+     * the grand total beside the pivoted ones. `'before'` places it at the near
+     * edge, `'after'` at the far edge. Omitted or `false` adds none.
+     */
+    groupTotals?: 'before' | 'after' | false;
+    /** Heading for that group. Defaults to `Total`. */
+    totalsLabel?: string;
+    maxColumns?: number;
+    separator?: string;
+  };
 }
 
 /**
@@ -795,6 +1030,7 @@ export interface GridState {
   sort?: SortEntry[];
   group?: string[];
   pivot?: { enabled: boolean; columns: string[] };
+  formatting?: Record<string, FormattingRule[]>;
   expanded?: string[];
   selection?: string[];
   scroll?: { top: number; left: number };
@@ -806,13 +1042,65 @@ export interface StateApplyReport {
   skipped: { key: string; reason: string }[];
 }
 
+// ---------------------------------------------------------------------------
+// Conditional formatting (spec 8.12)
+// ---------------------------------------------------------------------------
+
+export interface FormattingCondition {
+  op: Operator;
+  value?: unknown;
+  value2?: unknown;
+}
+
+export interface FormattingScale {
+  min: number;
+  max: number;
+  mid?: number;
+  colours?: string[];
+}
+
+/**
+ * One rule. Either a condition and the styling it produces, or a colour scale.
+ * A rule held as runtime state must be JSON, so `style` may not be a function
+ * there — config-time `cell.style` still accepts one.
+ */
+export interface FormattingRule {
+  id?: string;
+  when?: FormattingCondition;
+  style?: CellStyle | ((p: CellParams) => CellStyle | null);
+  scale?: FormattingScale;
+  stopIfTrue?: boolean;
+  enabled?: boolean;
+  icon?: string;
+  bar?: boolean;
+  label?: string;
+}
+
+/** A column id, or `'*'` for every column. */
+export type FormattingScope = string;
+
+export interface FormattingApi {
+  list(scope?: FormattingScope): FormattingRule[];
+  all(): Record<FormattingScope, FormattingRule[]>;
+  scopes(): FormattingScope[];
+  add(scope: FormattingScope, rule: FormattingRule, opts?: { at?: number }): FormattingRule | null;
+  remove(scope: FormattingScope, which: string | number): boolean;
+  update(scope: FormattingScope, which: string | number, patch: FormattingRule): FormattingRule | null;
+  move(scope: FormattingScope, which: string | number, to: number): boolean;
+  set(scope: FormattingScope, rules: FormattingRule[]): FormattingRule[];
+  replaceAll(rules: Record<FormattingScope, FormattingRule[]>): void;
+  clear(scope?: FormattingScope): void;
+  styleFor(colId: string, value: unknown): CellStyle | null;
+}
+
 // ---------------------------------------------------------------------------
 // Events (spec 18.4)
 // ---------------------------------------------------------------------------
 
 export type EventName =
   | 'ready' | 'destroy' | 'render:first' | 'model:changed' | 'rows:changed' | 'rows:queued'
-  | 'cell:changed' | 'cell:clicked' | 'cell:dblclicked' | 'cell:contextmenu'
+  | 'cell:changed' | 'cell:pending' | 'cell:confirmed' | 'cell:reverted'
+  | 'cell:clicked' | 'cell:dblclicked' | 'cell:contextmenu'
   | 'cell:edit:start' | 'cell:edit:end' | 'row:edit:start' | 'row:edit:end'
   | 'row:clicked' | 'row:dblclicked' | 'group:toggled'
   | 'sort:changed' | 'filter:changed'
@@ -911,6 +1199,8 @@ export interface RowsApi {
   count(): number;
   /** Rows in the source before filtering; under pagination, across every page. */
   totalCount(): number;
+  /** Data rows matching the filters, excluding group, footer and total rows. */
+  matchCount(): number;
   data(): unknown[];
   forEach(fn: (row: Row, index: number) => void): void;
   value(key: string, colId: string): unknown;
@@ -941,15 +1231,35 @@ export interface ColumnsApi {
   totals(ids: string | string[]): void;
 }
 
+export interface DetailApi {
+  enabled(): boolean;
+  isMaster(target: string | Row): boolean;
+  isOpen(key: string): boolean;
+  open(key: string): void;
+  close(key: string): void;
+  toggle(key: string): boolean;
+  closeAll(): void;
+  keys(): string[];
+  active(): string | null;
+  placement(): 'inline' | 'target' | null;
+  config(): DetailConfig | null;
+}
+
 export interface SelectionApi {
   rows(): Row[];
   keys(): string[];
   set(keys: string[]): void;
   all(): void;
   clear(): void;
+  headerState(): boolean | 'partial';
   cells(): { key: string; colId: string }[];
   ranges(): CellRange[];
   setRange(range: CellRange): void;
+  addRange(range: CellRange): void;
+  startRange(rowIndex: number, colId: string, opts?: { additive?: boolean }): void;
+  extendRange(rowIndex: number, colId: string): void;
+  corner(): { row: number; colId: string } | null;
+  inRange(rowIndex: number, colId: string): boolean;
 }
 
 export interface CellRange {
@@ -972,10 +1282,15 @@ export interface SortApi {
 }
 
 export interface EditApi {
-  start(key: string, colId: string): void;
+  start(key: string, colId: string): boolean;
   stop(cancel?: boolean): void;
   undo(): void;
   redo(): void;
+  setCells(writes: { key: string; colId: string; value: unknown }[], type?: 'cell' | 'fill' | 'paste'): number;
+  pasteInto(anchor: { key: string; colId: string }, text: string, extent?: { rows?: number; columns?: number }): number;
+  settle(id: string, ok: boolean, reason?: string): boolean;
+  pending(): OpenWrite[];
+  status(key: string, colId: string): 'pending' | null;
 }
 
 export interface ScrollApi {
@@ -1032,6 +1347,436 @@ export interface RowStyleParams {
   context: unknown;
 }
 
+/**
+ * Presentation mode renders the grid for a room: full-screen, application
+ * chrome hidden, and everything enlarged by a scale that multiplies the
+ * configured density rather than replacing it. The data stays live and
+ * interactive throughout.
+ */
+/**
+ * Rendering the grid to a still image. `scale` multiplies the pixel dimensions
+ * — 2 for a retina still, 3 or 4 for a slide. `background` fills behind the
+ * grid so a PNG dropped into a deck does not show it through.
+ */
+export interface CaptureOptions {
+  scale?: number;
+  background?: string;
+  download?: boolean;
+  fileName?: string;
+}
+
+/**
+ * The presenter's drawing layer. Pixels over the grid — it never reads or
+ * writes data, and it is inert until a tool is chosen, so scrolling and
+ * selection pass straight through. Marks are held in content coordinates, so
+ * they stay with the cells they annotate when the grid scrolls, and are
+ * cleared when a presentation ends.
+ */
+export interface AnnotationApi {
+  readonly tool: 'pen' | 'arrow' | 'rect' | 'highlight' | null;
+  readonly count: number;
+  use(tool: 'pen' | 'arrow' | 'rect' | 'highlight' | null, opts?: { colour?: string }): string | null;
+  undo(): number;
+  clear(): void;
+  redraw(): void;
+}
+
+/**
+ * Holding incoming updates, and the counters describing what they cost.
+ * Pausing is explicit — a button, not a guess at whether the user is busy.
+ */
+/** One thing the grid has flagged as probably a mistake. */
+export interface DiagnosticWarning {
+  /** Stable identifier, nameable in a support conversation. */
+  id: string;
+  message: string;
+  /** The specific values involved, so the warning is actionable. */
+  values: Record<string, unknown>;
+  count: number;
+  first: number;
+  last: number;
+  /** `'check'` raised by a diagnostic check, `'reported'` from `warnOnce`. */
+  source: 'check' | 'reported' | 'info';
+}
+
+export interface DiagnosticsApi {
+  snapshot(): Record<string, unknown>;
+  /** `dom.cellWrites` is the figure a DOM-write assertion reads. */
+  renders(): Record<string, unknown>;
+  store(): Record<string, unknown>;
+  operations(): Record<string, unknown>;
+  providers(): Record<string, unknown>;
+  events(): Record<string, number>;
+  config(): { effective: Record<string, unknown>; supplied: string[]; defaulted: string[] };
+  warnings(): DiagnosticWarning[];
+  dismiss(id: string): void;
+  /** Contains no row data, cell values or column values. */
+  bundle(): Record<string, unknown>;
+  checkOptions(options: unknown): boolean;
+  record(kind: string, detail: { rows?: number; ms?: number; worker?: boolean }): void;
+  render(cause: string, phases?: Record<string, number>): void;
+  /** Off by default; recording times every emit. */
+  recordEvents(on: boolean, limit?: number): void;
+  eventLog(): Array<{ type: string; origin: string; listeners: number;
+                      payload: Record<string, string>; at: number; ms: number }>;
+  clearEventLog(): void;
+  /** Keep current store statistics so growth can be measured against them. */
+  mark(): Record<string, unknown>;
+  since(): Record<string, unknown> | null;
+  reset(): void;
+}
+
+/** One peer, as the grid holds them. */
+export interface Peer {
+  id: string;
+  name: string;
+  /** Assigned deterministically from the id when the provider supplies none. */
+  colour: string;
+  avatarUrl?: string | null;
+  initials?: string | null;
+  /** Row key and column, never an index. */
+  cursor: { rowId: string; colId: string } | null;
+  ranges: Array<{ rowIds: string[]; columns: string[] }>;
+  editing: { rowId: string; colId: string } | null;
+  /** Local receipt time, not the sender's clock. */
+  at: number;
+  /** The sender's own timestamp, for inspection only. Nothing decides on it. */
+  sentAt?: number | null;
+  idle?: boolean;
+  silentMs?: number;
+  /** True when the peer's cursor is on a row this view is not showing. */
+  hidden?: boolean;
+}
+
+/**
+ * Transport for presence. The grid never opens a connection: it subscribes to
+ * what the provider delivers and hands it what changed locally.
+ */
+export interface PresenceProvider {
+  /** Returns an unsubscribe function, if it has one. */
+  subscribe(onMessage: (message: Peer | Peer[]) => void): (() => void) | void;
+  publish(state: Record<string, unknown>): void;
+}
+
+export interface PresenceConfig {
+  /** Without one the feature is inert and raises nothing. */
+  provider?: PresenceProvider;
+  /** The local identity, echoed in everything published. */
+  me?: { id: string; name?: string; colour?: string; avatarUrl?: string; initials?: string };
+  /** Milliseconds between published updates. Throttled, not debounced. */
+  throttleMs?: number;
+  /** Silence after which a peer is shown idle. */
+  idleMs?: number;
+  /** Silence after which a peer is dropped. */
+  removeMs?: number;
+  /** Silence after which a peer's edit claim is disregarded. */
+  lockMs?: number;
+  /**
+   * Refuse local editing of a cell a peer is editing. Advisory only: the
+   * authoritative resolution is the conditional write in `edit.commit`.
+   */
+  lock?: boolean;
+  /** Override the peer colour palette. */
+  palette?: string[];
+  /** Suppress the roster, or place it. */
+  roster?: boolean | { side?: 'start' | 'end' };
+  /** Suppress join and leave announcements to assistive technology. */
+  announce?: boolean;
+}
+
+export interface PresenceApi {
+  readonly enabled: boolean;
+  readonly me: Record<string, unknown> | null;
+  readonly publishing: boolean;
+  peers(): Peer[];
+  hiddenCount(): number;
+  editorOf(rowId: string, colId: string): Peer | null;
+  /** Advisory. Reduces collisions; does not eliminate them. */
+  lockedBy(rowId: string, colId: string): Peer | null;
+  jumpTo(peerId: string): boolean;
+  publish(): void;
+  setPublishing(on: boolean): void;
+  setPaused(paused: boolean): void;
+  connect(provider: PresenceProvider | null): void;
+  stats(): Record<string, number>;
+}
+
+/** One comment in a thread, as the provider returns it. */
+export interface Comment {
+  id: string;
+  body: string;
+  /** Rendered as supplied. The grid does not know who the user is. */
+  author?: { name?: string; avatarUrl?: string; initials?: string };
+  at?: number;
+  edited?: boolean;
+  resolved?: boolean;
+  parentId?: string | null;
+  /** The cell's value when this was written, so a later reader is told it moved. */
+  value?: unknown;
+  /**
+   * What the current user may do. Absent means the grid shows every affordance
+   * and relies on the provider to refuse. Hiding a button is a convenience,
+   * never a security control.
+   */
+  can?: { edit?: boolean; delete?: boolean; resolve?: boolean };
+}
+
+/** Counts for one cell. Never bodies — this is consulted on every repaint. */
+export interface CommentDescriptor {
+  count: number;
+  unresolved: number;
+  updated: number;
+}
+
+/** What `loadIndex` returns per commented cell. */
+export interface CommentIndexEntry extends CommentDescriptor {
+  cellKey?: string;
+  rowId?: string;
+  field?: string;
+}
+
+/**
+ * Storage for comments. Every method returns a promise; a rejection surfaces in
+ * the panel without disturbing grid state.
+ */
+export interface CommentProvider {
+  loadIndex(rowIds: string[], fields: string[]): Promise<CommentIndexEntry[]>;
+  loadThread(cellKey: string): Promise<Comment[]>;
+  addComment(cellKey: string, body: string, parentId: string | null,
+             context?: { value?: unknown }): Promise<Comment>;
+  editComment(commentId: string, body: string): Promise<Comment>;
+  deleteComment(commentId: string): Promise<void>;
+  resolveThread(cellKey: string): Promise<void>;
+  unresolveThread(cellKey: string): Promise<void>;
+}
+
+export interface CommentConfig {
+  /** Without one the feature is inert and no error is raised. */
+  provider?: CommentProvider;
+  /** Milliseconds a viewport change waits before the index is fetched. */
+  debounce?: number;
+  /** Cell descriptors held before the oldest are dropped. */
+  indexLimit?: number;
+  /** `'anchored'` floats beside the cell; `'docked'` uses a side panel. */
+  mode?: 'anchored' | 'docked';
+  /** Restricted markdown in bodies: emphasis, code and links only. */
+  markdown?: boolean;
+  /** Label for the row, so the panel says what is being commented on. */
+  rowLabel?: (row: Row) => string;
+}
+
+export interface CommentsApi {
+  readonly enabled: boolean;
+  readonly openKey: string | null;
+  readonly thread: Comment[] | null;
+  readonly loading: boolean;
+  readonly complete: boolean;
+  /** `'no-provider'`, `'no-row-identity'`, or null when available. */
+  unavailable(): string | null;
+  at(rowId: string, colId: string): CommentDescriptor | null;
+  request(rowIds: string[], fields?: string[]): void;
+  open(rowId: string, colId: string): Promise<Comment[] | null>;
+  close(opts?: { reason?: string }): void;
+  add(body: string, opts?: { parentId?: string; author?: object }): Promise<Comment | null>;
+  edit(commentId: string, body: string): Promise<Comment | null>;
+  remove(commentId: string): Promise<boolean>;
+  resolve(): Promise<boolean>;
+  unresolve(): Promise<boolean>;
+  refresh(): void;
+  loadAll(): Promise<boolean>;
+  hiddenUnresolved(): number;
+  filterToCommented(opts?: { unresolvedOnly?: boolean }): boolean;
+}
+
+/** One bucket of a column's distribution. */
+export interface FacetBucket {
+  /** Lower edge, for ordered columns. Half-open `[from, to)` except the last. */
+  from?: number;
+  /** Upper edge, for ordered columns. Inclusive on the last bucket only. */
+  to?: number;
+  /** The value, for categorical and boolean columns. */
+  value?: unknown;
+  /** True on the terminal bucket holding nulls, NaN and empty values. */
+  null?: boolean;
+  /** True on the aggregated tail bucket under `aboveLimit: 'topN'`. */
+  remainder?: boolean;
+  /** A ready-made label, where one is more useful than the raw value. */
+  label?: string;
+}
+
+/** Where a column's buckets are, and how they were chosen. */
+export interface FacetBounds {
+  kind: 'numeric' | 'date' | 'category' | 'boolean' | 'none';
+  buckets: FacetBucket[];
+  /** Set when no histogram was drawn, naming why. */
+  suppressed?: 'type' | 'cardinality' | 'rows' | 'streaming' | 'no-provider' | 'disabled';
+  /** Distinct values, on categorical columns. */
+  cardinality?: number;
+  /** The time unit chosen, on date columns. */
+  granularity?: 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+  /** The numeric strategy actually applied, which may differ from the request. */
+  strategy?: 'equal' | 'quantile' | 'log';
+  min?: number;
+  max?: number;
+}
+
+/** A column's computed distribution. */
+export interface FacetState {
+  bounds: FacetBounds | null;
+  /** Counts under every filter except this column's own. Aligned to `buckets`. */
+  counts: Uint32Array | null;
+  /** Counts with no filter applied, for the "40 of 200" reading. */
+  unfiltered: Uint32Array | null;
+  /** True while a recount is outstanding; draw the previous counts faded. */
+  stale: boolean;
+  suppressed: string | null;
+}
+
+/** Per-column histogram settings, layered over the grid's. */
+export interface ColumnFacetConfig {
+  enabled?: boolean;
+  buckets?: number;
+  strategy?: 'equal' | 'quantile' | 'log';
+  granularity?: 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+  order?: 'count' | 'alpha';
+  cardinalityLimit?: number;
+  aboveLimit?: 'suppress' | 'topN';
+  /** Replace the built-in bucketing entirely. */
+  bucketFn?: (handle: unknown, indices: Uint32Array | null, count: number) => FacetBounds;
+  /** Label a bucket for its tooltip and accessible name. */
+  format?: (bucket: FacetBucket, count: number, unfiltered: number) => string;
+}
+
+/** Grid-level histogram settings. */
+export interface FacetConfig extends ColumnFacetConfig {
+  /** Off unless asked for: header space is tight and this doubles its height. */
+  enabled?: boolean;
+  /** Start as a one-line density strip that opens on hover or click. */
+  collapsed?: boolean;
+  /** Band height in pixels. */
+  height?: number;
+  /** Rows above which histograms are suppressed. */
+  rowCeiling?: number;
+  /** Milliseconds a filter change waits before charts recount. */
+  debounce?: number;
+  /** Whether a paused stream re-enables histograms. Defaults to true. */
+  whilePaused?: boolean;
+  /** Bucket counts for a source the client cannot compute over. */
+  provider?: (request: {
+    colId: string;
+    column: unknown;
+    filters: unknown;
+    quick: string;
+    bounds: FacetBounds | null;
+    buckets: number;
+    strategy: string;
+    granularity?: string;
+  }) => Promise<{ bounds?: FacetBounds; buckets?: FacetBucket[]; counts: ArrayLike<number>;
+                  unfiltered?: ArrayLike<number>; kind?: string }>;
+}
+
+export interface FacetsApi {
+  get(colId: string): FacetState | null;
+  suppression(colId: string): string | null;
+  config(colId?: string): FacetConfig;
+  refresh(opts?: { immediate?: boolean }): void;
+  isExpanded(colId: string): boolean;
+  toggle(colId: string, open?: boolean): boolean;
+  select(colId: string, from: number, to?: number,
+         opts?: { additive?: boolean; gesture?: string }): boolean;
+  clear(colId: string): boolean;
+  selected(colId: string): number[];
+  expanded(): string[];
+}
+
+export interface UpdatesApi {
+  readonly paused: boolean;
+  pause(): boolean;
+  resume(): ChangeResult;
+  flush(): ChangeResult;
+  stats(): {
+    paused: boolean;
+    pending: number;
+    queued: number;
+    coalesced: number;
+    coalescedTotal: number;
+    rows: number;
+    dropped: number;
+    held: number;
+    heldLimit: number;
+    flushes: number;
+    strategy: string;
+    deferrals: number;
+    maxQueued: number;
+    budgetMs: number;
+    span: { from: number; to: number } | null;
+  };
+  log(opts?: { since?: number }): { at: number; change: RowChange; rows: number }[];
+}
+
+/**
+ * Moving the grid through recent data changes. Reads the change log rather
+ * than the undo history: history records what the *user* did, and the question
+ * on a live grid is what the *data* did. Nothing is scrubbable until
+ * `attach()` — what a value used to be is not recoverable after the fact.
+ */
+export interface TimelineApi {
+  readonly attached: boolean;
+  readonly live: boolean;
+  readonly position: number;
+  readonly depth: number;
+  attach(): void;
+  detach(): void;
+  seek(steps: number): number;
+  step(by: number): number;
+  toLive(): number;
+  at(): number | null;
+  span(): { from: number; to: number } | null;
+}
+
+export interface PresentationApi {
+  readonly active: boolean;
+  readonly scale: number;
+  readonly options: { scale?: number; chrome?: string[]; views?: string[]; from?: number; autoAdvance?: number };
+  readonly views: string[];
+  readonly index: number;
+  readonly viewId: string | null;
+  start(options?: {
+    scale?: number;
+    chrome?: string[];
+    /** Saved view ids to step through. Views are the slides. */
+    views?: string[];
+    /** Where in that sequence to begin. */
+    from?: number;
+    /** Milliseconds between automatic advances, for an unattended display. */
+    autoAdvance?: number;
+  }): boolean;
+  stop(): boolean;
+  setScale(value: number): number;
+  nudge(steps?: number): number;
+  step(by?: number): number;
+  goTo(index: number): number;
+  reset(): boolean;
+  readonly spotlight: { keys: string[]; colIds: string[] } | null;
+  setSpotlight(target?: { keys?: string[]; colIds?: string[] } | null): boolean;
+}
+
+/**
+ * Redaction obscures a column's values on screen. It is presentational: the
+ * values stay in the model, the DOM, the clipboard and every export. Use
+ * `permissions` with `writeOnly` for a value that must not be readable.
+ */
+export interface RedactionApi {
+  has(colId: string): boolean;
+  list(): string[];
+  toggle(colId: string): boolean;
+  add(colId: string): void;
+  remove(colId: string): void;
+  set(ids: string[]): void;
+  clear(): void;
+  readonly active: boolean;
+}
+
 export interface HighlightApi {
   /** Highlight a cell (`{key, colId}`), a row (`{key}`) or a column (`{colId}`). */
   (target: { key?: string; colId?: string } | string,
@@ -1059,8 +1804,20 @@ export interface OverlayApi {
 }
 
 export interface HistoryEntry {
+  /** Monotonic sequence number, in the order actions were recorded. */
+  seq: number;
+  /** What kind of action it was, e.g. `'sort'`, `'column:pin'`, `'edit'`. */
+  type: string;
+  /** Human text for a button, e.g. `'sort by Region'`. */
   label: string;
-  kind: string;
+  /** The column or row the action was aimed at, where there was one. */
+  target: string | null;
+  /** When it was recorded, on the high-resolution clock. */
+  at: number;
+  /** True when the edit model owns the undo rather than the history stack. */
+  delegated: boolean;
+  /** Set once the entry has been undone. */
+  undone?: boolean;
   [key: string]: unknown;
 }
 
@@ -1136,7 +1893,14 @@ export interface AiApi {
   schema(opts?: { maxColumns?: number; maxRows?: number }): Record<string, unknown>;
   /** The same schema as a tool definition. */
   tool(opts?: { maxColumns?: number; maxRows?: number }): Record<string, unknown>;
-  prompt(text: string, opts?: Record<string, unknown>): string;
+  /**
+   * The prompt describing this grid — its columns, types and operators — for
+   * sending to a model. It carries no row values.
+   *
+   * It does not take the user's question: compose that yourself alongside the
+   * text this returns, which is what `ask` receives as `schemaText`.
+   */
+  prompt(opts?: Record<string, unknown>): string;
   buildPrompt(text: string, opts?: Record<string, unknown>): string;
   /** Parse what the model returned into a plan. */
   plan(reply: string | Record<string, unknown>, opts?: Record<string, unknown>): Record<string, unknown>;
@@ -1164,6 +1928,48 @@ export interface PaginationApi {
  * created with `createGrid` unless `maximise: false`; never on a headless grid,
  * which has no window to fill.
  */
+/** What a cell-menu builder and a host item's `action` are handed. */
+export interface CellMenuParams {
+  key: string;
+  colId: string;
+  value: unknown;
+  /** The row wrapper. */
+  row: Row;
+  /** Your original row object. */
+  data: unknown;
+  column: ResolvedColumn;
+  index: number;
+  grid: Grid;
+}
+
+/** What a host rail action's `run` is handed. */
+/** The rail's built-in action names, plus `'-'` for a divider. */
+export type RailActionName =
+  | 'undo' | 'redo' | 'pause' | 'restore' | 'maximise'
+  | 'export' | 'excel' | 'clipboard' | 'print';
+
+export interface RailActionParams {
+  grid: Grid;
+  keys: string[];
+  cells: { key: string; colId: string }[];
+}
+
+export interface RailAction {
+  name: string;
+  title: string | (() => string);
+  icon?: string | (() => string);
+  run(params: RailActionParams): void;
+  enabled?(): boolean;
+}
+
+/** The result of evaluating a formula a user typed into a cell (spec 8.11). */
+export type FormulaResult =
+  | { ok: true; value: unknown; references: string[] }
+  | { ok: false; error: string; at?: number };
+
+export function evaluateFormula(text: string, params?: ParseParams): FormulaResult;
+export function looksLikeFormula(text: unknown): boolean;
+
 export interface MaximiseApi {
   enter(): boolean;
   exit(): boolean;
@@ -1190,7 +1996,27 @@ export interface Grid {
   readonly licence: LicenceApi;
   readonly pagination: PaginationApi;
   readonly highlight: HighlightApi;
+  readonly redaction: RedactionApi;
+  capture?(opts?: CaptureOptions): Promise<Blob>;
+  annotate?: AnnotationApi;
+  readonly presentation: PresentationApi;
+  readonly updates: UpdatesApi;
+  readonly timeline: TimelineApi;
+  readonly facets: FacetsApi;
+  readonly detail: DetailApi;
+  readonly comments: CommentsApi;
+  readonly presence: PresenceApi;
+  readonly diagnostics: DiagnosticsApi;
+  readonly formatting: FormattingApi;
   readonly maximise?: MaximiseApi;
+  /**
+   * The element you passed to `createGrid`, not the grid's own root.
+   *
+   * The grid builds its `.lattice` root *inside* that element, so
+   * `el.closest('.lattice')` never matches this, and a theme attribute set on
+   * it has no effect — the theme is read from the root within. Use
+   * `element.querySelector('.lattice')` for the grid's own root.
+   */
   readonly element: HTMLElement | null;
   readonly destroyed: boolean;
   /** False until the first render has been laid out. */