@toclocoinc/lattice-grid 1.22.0 → 1.24.0

package/docs/api-detail.html

@@ -437,7 +437,7 @@
 <div class="shell">
   <aside class="rail">
     <p class="rail__brand">Lattice Grid</p>
-    <p class="rail__sub">Developer guide · v1.22.0</p>
+    <p class="rail__sub">Developer guide · v1.24.0</p>
     <nav>
       <div class="rail__group">
         <span class="rail__label">Start here</span>
@@ -1305,6 +1305,7 @@ LatticeGrid.getVersion();   <span class="cmt">// the same, when you have no grid
           <tr><td class="name">Units: engineering</td><td class="desc"><code>speed</code>, <code>kph</code>, <code>mph</code>, <code>knots</code>, <code>acceleration</code>, <code>area</code>, <code>hectares</code>, <code>volume</code>, <code>cubicMetres</code>, <code>energy</code>, <code>kilowattHours</code>, <code>power</code>, <code>kilowatts</code>, <code>force</code>, <code>pressure</code>, <code>bar</code>, <code>psi</code>, <code>torque</code>, <code>density</code>, <code>flow</code>, <code>litresPerMinute</code>, <code>radians</code>, <code>degrees</code></td></tr>
           <tr><td class="name">Units: electrical and scientific</td><td class="desc"><code>voltage</code>, <code>current</code>, <code>resistance</code>, <code>capacitance</code>, <code>inductance</code>, <code>charge</code>, <code>conductance</code>, <code>fluxDensity</code>, <code>luminousFlux</code>, <code>illuminance</code>, <code>substance</code>, <code>absorbedDose</code>, <code>equivalentDose</code>, <code>radioactivity</code>, <code>luminousIntensity</code>, <code>doseRate</code>, <code>rpm</code>, <code>angularVelocity</code>, <code>ppm</code>, <code>ppb</code>, <code>basisPoints</code>, <code>molarity</code>, <code>massFlow</code>, <code>tonnesPerHour</code>, <code>viscosity</code>, <code>kinematicViscosity</code>, <code>thermalConductivity</code>, <code>specificHeat</code>, <code>frequency</code></td></tr>
           <tr><td class="name">Temperature</td><td class="desc"><code>celsius</code>, <code>fahrenheit</code>, <code>kelvin</code></td></tr>
+          <tr><td class="name">Currency</td><td class="desc"><code>currency</code>, <code>usd</code>, <code>eur</code>, <code>gbp</code>, <code>jpy</code></td></tr>
           <tr><td class="name">Structured</td><td class="desc"><code>json</code>, <code>colour</code>, <code>rating</code>, <code>percent</code></td></tr>
         </tbody>
       </table>
@@ -1392,6 +1393,15 @@ dataTypes: {
       <code>kelvin</code> convert on input: type <code>72 F</code> into a Celsius column and it
       stores 22.2, and <strong>refuse to be summed</strong>: twenty degrees plus twenty degrees is
       not forty degrees, and a footer saying so would be believed.</p>
+      <p><strong>Currency is its own type, not a unit either.</strong> A currency's
+      &ldquo;factor&rdquo; is an exchange rate that moves, so a value carries an amount
+      <em>and</em> a code and never a fixed factor. The grid ships and fetches no rates: pass a
+      rate source through <code>createCurrencyType({ display, rates })</code>, and a rate that is
+      needed but absent renders as a loud marker (<code>missingRate</code>), never as zero. A
+      column totalling in a display currency refuses to add unlike currencies until every value
+      can reach that currency. The shipped <code>currency</code>, <code>usd</code>,
+      <code>eur</code>, <code>gbp</code> and <code>jpy</code> types cover the single-currency case;
+      a rate table is denominated in a base you can state with <code>rateBase</code>.</p>
     </div>
 
     <h3>Types read from the data</h3>
@@ -3191,6 +3201,22 @@ columns: [
       protected columns exactly as every other card does. Like the others it is presentation only.
     </p>
 
+    <p class="lead-in">
+      <code>pivotView</code> is the fourth shape: the grid drawn as a pivot &mdash; a cross-tab
+      matrix. The grid's <code>group</code> dimensions run down the left gutter, its <code>pivot</code>
+      dimensions run across the top, and each totalled column fills a cell with its reduction, with a
+      subtotal down every row, across every column, and the grand total in the corner. Those numbers are
+      the grid's own: every cell is the same aggregate kernel the totals row uses, run over the rows that
+      feed the cell, so a pivot subtotal equals the grid's group total for that set by construction rather
+      than being re-derived &mdash; an average subtotal is the average of the rows, never an average of
+      cell averages. Both axes expand and collapse and both are virtualised through the shared row-template
+      layer, so a wide, deep matrix draws only the cells on screen. Clicking a body cell emits
+      <code>pivot:drill</code> with the keys of the contributing rows, the pivot's answer to &ldquo;what is
+      behind this number&rdquo;. The collapse state rides in a saved view, and because a matrix cannot be
+      read on a phone, at or below <code>maxWidth</code> the pivot degrades to a card list, exactly as the
+      table does under <code>responsive</code>. Like the others it is presentation only.
+    </p>
+
     <div class="example">
       <p class="example__label">The shorthands, and the config a grid reports back</p>
       <pre data-run="js" data-expect="recordCard true, gallery 240px, board 300px" data-covers="config:recordCard config:gallery config:board"><code><span class="kw">const</span> { createHeadlessGrid } = <span class="kw">await</span> import('../packages/core/src/index.js');
@@ -3214,6 +3240,33 @@ columns: [
 <span class="kw">return</span> `recordCard ${c.recordCard === <span class="kw">true</span>}, gallery ${c.gallery.tileWidth}px, board ${c.board.laneWidth}px`;</code></pre>
     </div>
 
+    <div class="example">
+      <p class="example__label">A pivot: group down, pivot across, and the drill event a cell click fires</p>
+      <pre data-run="js" data-expect="pivotView true, collapsed 0, drills 0" data-covers="config:pivotView method:pivotView event:pivot:drill"><code><span class="kw">const</span> { createHeadlessGrid } = <span class="kw">await</span> import('../packages/core/src/index.js');
+
+<span class="kw">const</span> grid = createHeadlessGrid({
+  columns: [{ field: 'region' }, { field: 'product' }, { field: 'amount', type: 'number', total: 'sum' }],
+  rows: [
+    { id: '1', region: 'EMEA', product: 'Widget', amount: 10 },
+    { id: '2', region: 'APAC', product: 'Gadget', amount: 5 },
+  ],
+  rowKey: 'id',
+  <span class="cmt">// Draw the grid as a pivot: the group down, the pivot across, a measure per cell.</span>
+  pivotView: <span class="kw">true</span>,
+});
+grid.columns.group(['region']);
+grid.columns.pivot(['product']);
+
+<span class="cmt">// A body-cell click drills to its rows through this event.</span>
+<span class="kw">let</span> drills = 0;
+grid.on('pivot:drill', () => { drills += 1; });
+
+<span class="cmt">// The collapse state a saved view carries.</span>
+<span class="kw">const</span> state = grid.pivotView.state();
+
+<span class="kw">return</span> `pivotView ${grid.config().pivotView === <span class="kw">true</span>}, collapsed ${state.rowsCollapsed.length}, drills ${drills}`;</code></pre>
+    </div>
+
     <div class="example">
       <p class="example__label">A card list</p>
       <pre><code>createGrid(element, {
@@ -3601,6 +3654,7 @@ socket.onmessage = (m) =&gt; {
           <tr><td class="sig">pending</td><td class="desc">Applied and painted, not yet acknowledged.</td><td class="desc"><code>cell:pending</code></td></tr>
           <tr><td class="sig">confirmed</td><td class="desc">The server accepted it. Nothing is written back.</td><td class="desc"><code>cell:confirmed</code></td></tr>
           <tr><td class="sig">reverted</td><td class="desc">The server refused it; the cell is rolled back.</td><td class="desc"><code>cell:reverted</code></td></tr>
+          <tr><td class="sig">conflict</td><td class="desc">The write was accepted but the server row had moved underneath it. Last-write-wins: your value stands and the server's truth is surfaced so you can reconcile it.</td><td class="desc"><code>cell:conflict</code></td></tr>
           <tr><td class="sig">superseded</td><td class="desc">A newer edit replaced it while it was in flight.</td><td class="desc">either, with <code>superseded: true</code></td></tr>
         </tbody>
       </table>
@@ -6137,6 +6191,7 @@ el.grid.sort.set([{ col: 'charge', dir: 'desc' }]);</code></pre>
           <tr><td class="name">cell:changed</td><td class="desc">A committed edit reached the data. undo distinguishes a rollback.</td></tr>
           <tr><td class="name">cell:clicked</td><td class="desc">A cell was clicked. Announcement only: nothing is consumed, so editing and selection behave unchanged.</td></tr>
           <tr><td class="name">cell:confirmed</td><td class="desc">The write reached the server.</td></tr>
+          <tr><td class="name">cell:conflict</td><td class="desc">The write was accepted but the server row had moved underneath it. Last-write-wins with the divergence surfaced: your value stands and serverRow carries the server's truth.</td></tr>
           <tr><td class="name">cell:contextmenu</td><td class="desc">Right-click on a cell.</td></tr>
           <tr><td class="name">cell:dblclicked</td><td class="desc">A cell was double-clicked. Carries the row, column, value and text.</td></tr>
           <tr><td class="name">cell:edit:end</td><td class="desc">It closed: committed or cancelled.</td></tr>

package/lattice-grid.d.ts

@@ -1,5 +1,5 @@
 /*!
- * Lattice Grid 1.22.0, type declarations
+ * Lattice Grid 1.24.0, type declarations
  * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
  * https://latticegrid.dev
  */
@@ -48,6 +48,9 @@ export type TypeName =
   | 'viscosity' | 'kinematicViscosity' | 'thermalConductivity' | 'specificHeat'
   // Temperature, which is affine rather than multiplicative
   | 'celsius' | 'fahrenheit' | 'kelvin'
+  // Currency, whose "factor" is a moving exchange rate, so it carries an amount
+  // and a code rather than joining the fixed-factor unit factory.
+  | 'currency' | 'usd' | 'eur' | 'gbp' | 'jpy'
   | (string & {});
 
 /**
@@ -430,10 +433,10 @@ export type RendererName =
   | 'winloss' | (string & {});
 
 export type EditorName =
-  | 'checkbox' | 'code' | 'colour' | 'date' | 'datetime' | 'duration' | 'iconPicker'
-  | 'ipaddress' | 'multiSelect' | 'number' | 'objectPicker' | 'password' | 'radix'
-  | 'rating' | 'segmented' | 'select' | 'slider' | 'temperature' | 'text' | 'textarea'
-  | 'time' | 'treeSelect' | 'unit' | (string & {});
+  | 'checkbox' | 'code' | 'colour' | 'currency' | 'date' | 'datetime' | 'duration'
+  | 'iconPicker' | 'ipaddress' | 'multiSelect' | 'number' | 'objectPicker' | 'password'
+  | 'radix' | 'rating' | 'segmented' | 'select' | 'slider' | 'temperature' | 'text'
+  | 'textarea' | 'time' | 'treeSelect' | 'unit' | (string & {});
 
 export interface EditorParams extends CellParams {
   stop(cancel?: boolean): void;
@@ -1141,6 +1144,68 @@ export interface OpenWrite {
   age: number;
 }
 
+/**
+ * What an adapter can persist back to its source — the write-back capability
+ * (§4.1), declared on `AdapterCapabilities.mutate`. `false` (the default) is
+ * read-only by declaration; a resolved block turns every kind off unless the
+ * adapter opts in.
+ */
+export interface MutateCapability {
+  /** The adapter can insert new rows. Wave 1: declared, not yet bridged. */
+  append?: boolean;
+  /** The adapter can patch existing rows. Wave 1: the wired kind (§4.3 Option A). */
+  update?: boolean;
+  /** The adapter can remove rows. Wave 1: declared, not yet bridged. */
+  delete?: boolean;
+  /**
+   * The reconcile contract — what the server hands back after a successful
+   * mutation (§5.1). `'row'`: the authoritative row (id, computed columns,
+   * timestamps), reconciled before confirm. `'key'`: only the assigned key.
+   * `'none'` (the default): nothing — the optimistic value stands
+   * (last-write-wins).
+   */
+  returning?: 'row' | 'key' | 'none';
+}
+
+/**
+ * One mutation handed to `adapter.mutate(op, request)` (§4.2). Cell-scoped
+ * `update` is the only kind wave 1 synthesises; `append`/`delete` are part of
+ * the shape so it survives into a later structural build (card 770).
+ */
+export interface MutationOp {
+  kind: 'append' | 'update' | 'delete';
+  /** append: the new rows (may lack a server-assigned key). */
+  rows?: unknown[];
+  /** update: the row key. */
+  key?: string;
+  /** update: the changed columns only, matching `PendingWrite` semantics. */
+  patch?: Record<string, unknown>;
+  /** delete: the row key(s). */
+  keys?: string[];
+  /** Provenance, carried through for auth / audit. */
+  origin?: string;
+  /** Stable id for idempotent retry / dedupe. Reserved; retry is a non-goal in wave 1. */
+  requestId?: string;
+}
+
+/**
+ * The result of a mutation (§4.2) — the reconcile payload. A cell-update commit
+ * flows this back through `PendingWrites`: `ok: false` reverts and surfaces
+ * `reason`; `rows` (`returning: 'row'`) reconciles server truth before confirm;
+ * `conflict` surfaces a last-write-wins divergence via `cell:conflict`.
+ */
+export interface MutationResult {
+  ok: boolean;
+  /** `returning: 'row'` — the authoritative row(s) to reconcile to. */
+  rows?: unknown[];
+  /** `returning: 'key'` — server-assigned key(s) for appended rows, in order. */
+  keys?: string[];
+  /** On rejection — surfaced on `cell:reverted`, never swallowed. */
+  reason?: string;
+  /** The server's current value, for a surfaced last-write-wins conflict. */
+  conflict?: { key: string; serverRow?: unknown };
+}
+
 export interface PaginationConfig {
   enabled?: boolean;
   pageSize?: number;
@@ -1400,6 +1465,46 @@ export interface GridConfig {
     itemRole?: string;
   };
 
+  /**
+   * Present the grid as a pivot — a cross-tab drawn as a matrix (§10,
+   * BACKLOG-0000738).
+   *
+   * The row dimensions (the grid's `group`) go down the left gutter, the column
+   * dimensions (the grid's `pivot`) go across the top, and each totalled column
+   * fills a cell with its reduction. `true` draws the matrix with the default
+   * geometry; an object sizes the cells and gutter or names the breakpoint below
+   * which it degrades to cards.
+   *
+   * **The numbers are the grid's own.** Every cell — body, subtotal, grand total
+   * — is the same aggregate kernel the totals row uses, run over the rows that
+   * feed the cell, so a pivot subtotal equals the grid's group total for that
+   * set by construction rather than being re-derived. Both axes expand and
+   * collapse, both are virtualised, and a cell click emits `pivot:drill` with the
+   * keys of the contributing rows.
+   *
+   * **Narrow-screen fallback.** A matrix cannot be read on a phone, so at or
+   * below `maxWidth` (the container width, not the viewport) the pivot degrades
+   * to a card list — the record card by default — exactly as the table does under
+   * `responsive`. Presentation only: sort, filter, group, pivot and the data
+   * pipeline are unchanged.
+   */
+  pivotView?: boolean | {
+    /** How wide one value column is, in pixels. 120 by default. */
+    cellWidth?: number;
+    /** How tall one body row is, in pixels. 32 by default. */
+    cellHeight?: number;
+    /** How wide the row-label gutter is, in pixels. 200 by default. */
+    headerWidth?: number;
+    /** Degrade to cards at or below this container width. 640 by default. */
+    maxWidth?: number;
+    /** The card layout the narrow fallback uses. The record card when omitted. */
+    fallbackTemplate?: string | object;
+    /** A class of your own on the pivot root, alongside the grid's. */
+    className?: string;
+    /** The pivot's role. `grid` by default — a pivot is a grid of cells. */
+    role?: string;
+  };
+
   /**
    * Present rows as cards when the grid's container is too narrow to be a
    * table honestly, a phone, or a narrow panel on a wide screen.
@@ -1956,6 +2061,12 @@ export interface GridState {
   sort?: SortEntry[];
   group?: string[];
   pivot?: { enabled: boolean; columns: string[] };
+  /**
+   * The pivot presentation's collapse state (§10, BACKLOG-0000738): which
+   * row-axis and column-axis nodes are collapsed. Absent when the matrix is
+   * fully expanded, and tolerated as "expand all" when applied.
+   */
+  pivotView?: { rowsCollapsed: string[]; columnsCollapsed: string[] };
   formatting?: Record<string, FormattingRule[]>;
   expanded?: string[];
   selection?: string[];
@@ -2067,6 +2178,12 @@ export interface PushdownCapabilities {
   total?: boolean;
   /** Whether it can group and aggregate. */
   group?: boolean;
+  /**
+   * What the adapter can persist back — the write-back contract (§4.1). `false`
+   * (the default) is read-only by declaration. A declared block opts kinds in;
+   * `capabilitiesOf` resolves it to a full `MutateCapability` (or `false`).
+   */
+  mutate?: false | MutateCapability;
 }
 
 /** An engine the grid can query, and what it is able to answer. */
@@ -2077,6 +2194,13 @@ export interface PushdownAdapter {
   /** Run the part of the query the adapter declared it could handle. */
   execute(query: RemoteRequest, request?: RemoteRequest):
     Promise<{ rows: unknown[]; total?: number }>;
+  /**
+   * Persist one mutation (§4.2). Present only when `capabilities.mutate` opts
+   * in. `createPushdownSource` synthesises an `edit.commit` that calls this for
+   * cell updates (§4.3 Option A); `request` threads the abort signal through the
+   * way `execute` receives it, and auth already lives on the adapter.
+   */
+  mutate?(op: MutationOp, request?: RemoteRequest): Promise<MutationResult>;
 }
 
 /** How one request was divided between the engine and the grid. */
@@ -2317,6 +2441,38 @@ export interface StatisticsApi {
    * its exact tier and, when one exists, the approximate alternative and bound.
    */
   maintenanceTier(fn: string): MaintenanceTier;
+  /**
+   * A windowed aggregate — "the average lately" (BACKLOG-0000654) — over one
+   * column, stamped with the window it covers (`over`), so a windowed figure is
+   * never read without its window. Exact over the values inside the window.
+   *
+   * `kind: 'count'` takes the last `span` values in arrival order. `kind:
+   * 'time'` takes the values within the last `span` ms (or `minutes`) and `kind:
+   * 'session'` takes every value; both need a timestamp column, so `by` is
+   * required for them and never guessed. Returns null when the column, or the
+   * `by` column, is unknown.
+   */
+  windowed(colId: string, fn: WindowedFn, opts: {
+    kind: 'count' | 'time' | 'session';
+    /** N ticks for a count window, or N ms for a time window. */
+    span?: number;
+    /** N minutes for a time window, converted to ms. */
+    minutes?: number;
+    /** A timestamp column; required for a time or session window. */
+    by?: string;
+  }): WindowedResult | null;
+}
+
+/** A named aggregate a windowed reduction can return. */
+export type WindowedFn =
+  | 'sum' | 'avg' | 'mean' | 'min' | 'max' | 'count' | 'variance' | 'stddev';
+
+/** One windowed figure and the window it covers. */
+export interface WindowedResult {
+  /** The reduction, or null when the window held no usable values. */
+  value: number | null;
+  /** The window the figure was computed over — always stated. */
+  over: WindowSpec;
 }
 
 /** How an approximate reduction's error bound holds, and what it measures. */
@@ -2359,6 +2515,40 @@ export interface WindowSpec {
   size: number;
 }
 
+/** The three window kinds a caller may ask for. */
+export const WINDOW_KINDS: readonly ('count' | 'time' | 'session')[];
+
+/**
+ * A sliding window over a stream of timestamped values (BACKLOG-0000654). Holds
+ * the values currently in the window and re-reduces them on demand; the reduction
+ * is exact over the values in the window. `grid.statistics.windowed(...)` drives
+ * one of these over a column; a host can also drive one live, tick by tick.
+ */
+export class Window {
+  constructor(kind: 'count' | 'time' | 'session', span?: number, now?: () => number);
+  /** How many values are in the window right now. */
+  readonly size: number;
+  /** Add one value at an explicit or current timestamp. */
+  push(v: number, t?: number): void;
+  /** The window descriptor as it stands now. */
+  spec(): WindowSpec;
+  /** The values currently in the window, oldest first. */
+  values(): number[];
+  /** Every windowed aggregate at once, each stamped with the window. */
+  aggregate(): {
+    over: WindowSpec; count: number; sum: number | null; mean: number | null;
+    min: number | null; max: number | null; variance: number | null; stddev: number | null;
+  };
+  /** One named aggregate over the window, stamped with the window it covers. */
+  reduce(fn: WindowedFn): WindowedResult;
+}
+
+/** Build a window from a caller's spec: last N ticks, last N minutes/ms, or the session. */
+export function openWindow(
+  opts: { kind: 'count' | 'time' | 'session'; span?: number; minutes?: number },
+  now?: () => number,
+): Window;
+
 export type ShadowKind =
   | 'updates' | 'updatedAt' | 'sinceUpdate' | 'delta' | 'deltaPercent'
   | 'rate' | 'history' | 'firstValue' | 'streak'
@@ -2615,7 +2805,7 @@ export type EventName =
   | 'rows:paused' | 'rows:resumed' | 'row:received' | 'row:sent' | 'row:copied'
   | 'row:moved' | 'source:error' | 'stream:chunk' | 'stream:end' | 'stream:evicted'
   /* Cells and editing */
-  | 'cell:changed' | 'cell:pending' | 'cell:confirmed' | 'cell:reverted'
+  | 'cell:changed' | 'cell:pending' | 'cell:confirmed' | 'cell:reverted' | 'cell:conflict'
   | 'cell:clicked' | 'cell:dblclicked' | 'cell:contextmenu'
   | 'cell:edit:start' | 'cell:edit:end' | 'row:edit:start' | 'row:edit:end'
   | 'row:clicked' | 'row:dblclicked'
@@ -2626,6 +2816,7 @@ export type EventName =
   /* Columns */
   | 'column:moved' | 'column:resized' | 'column:visible' | 'column:pinned'
   | 'column:grouped' | 'column:pivoted' | 'column:filter:open' | 'column:menu:open'
+  | 'pivot:drill'
   | 'columns:changed' | 'columns:tagged' | 'header:contextmenu'
   /* Selection and view */
   | 'selection:changed' | 'range:changed' | 'clipboard:copy'
@@ -2960,7 +3151,20 @@ export interface EditApi {
     changes: { key: string; colId: string; oldValue: unknown; newValue: unknown; changed: boolean }[];
     rejected: { key: string; colId: string; value: unknown; reason: 'permission' | 'readOnly' | 'validation' | 'locked' | 'missing' }[];
   };
-  settle(id: string, ok: boolean, reason?: string): boolean;
+  /**
+   * Report the outcome of an in-flight write (§18.3; §5.1-5.2 reconcile).
+   *
+   * `reconcile` carries server truth on a successful settle: `value` is a
+   * server-authoritative value written back before `cell:confirmed`
+   * (`returning: 'row'`); `conflict.serverRow` surfaces a last-write-wins
+   * conflict via `cell:conflict`. Omit both to keep the optimistic value.
+   */
+  settle(
+    id: string,
+    ok: boolean,
+    reason?: string,
+    reconcile?: { value?: unknown; conflict?: { serverRow?: unknown } },
+  ): boolean;
   pending(): OpenWrite[];
   status(key: string, colId: string): 'pending' | null;
 }
@@ -3444,6 +3648,22 @@ export interface PresentationApi {
   setSpotlight(target?: { keys?: string[]; colIds?: string[] } | null): boolean;
 }
 
+/**
+ * Controls for the pivot presentation (§10, BACKLOG-0000738): expand or collapse
+ * an axis node, and read the collapse state a saved view carries. Every method
+ * is a no-op on a headless grid, which has no matrix to collapse.
+ */
+export interface PivotViewApi {
+  /** Expand a collapsed node on the row or column axis. */
+  expand(axis: 'row' | 'column', path: string): void;
+  /** Collapse a node on the row or column axis, hiding its descendants. */
+  collapse(axis: 'row' | 'column', path: string): void;
+  /** Toggle a node's collapse on the row or column axis. */
+  toggle(axis: 'row' | 'column', path: string): void;
+  /** The collapsed row-axis and column-axis paths, as a saved view carries them. */
+  state(): { rowsCollapsed: string[]; columnsCollapsed: string[] };
+}
+
 /**
  * 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
@@ -3750,6 +3970,8 @@ export interface Grid {
   annotate?: AnnotationApi;
   /** Full screen, scaling and chrome suppression. */
   readonly presentation: PresentationApi;
+  /** Expand and collapse the pivot presentation's axes; the state a view carries. */
+  readonly pivotView: PivotViewApi;
   /** The live feed: pausing it, flushing it, and what it has done. */
   readonly updates: UpdatesApi;
   /** Replaying the changes the grid has seen. */
@@ -3872,6 +4094,66 @@ export function parseUnit(text: string | number, opts?: UnitConfig): number | nu
 export function formatUnit(value: number | null | undefined, opts?: UnitConfig): string;
 export const UNIT_SYSTEMS: Record<string, readonly UnitDescriptor[]>;
 
+/**
+ * A stored currency value: an amount in a named currency. `{amount:10,code:'USD'}`
+ * is a different value from `{amount:10,code:'EUR'}` — currency is a real type,
+ * not a display format, so the code rides on every cell.
+ */
+export interface Money {
+  amount: number;
+  code: string;
+}
+
+/**
+ * A caller-supplied exchange-rate source. The grid ships and fetches no rates.
+ * Either a function `(from, to) => rate|null`, or a table of rates per unit of a
+ * common base (the base being whichever code maps to 1, or `rateBase`). A source
+ * that cannot answer returns `null`, which is surfaced loudly, never as zero.
+ */
+export type RateSource =
+  | ((from: string, to: string) => number | null)
+  | Record<string, number>;
+
+export interface CurrencyConfig {
+  /** The default currency code for bare numeric input, e.g. `'USD'`. */
+  code?: string;
+  /** The currency to render and aggregate in. Omit to keep each cell's own. */
+  display?: string;
+  /** The caller's rate source: a `(from,to)=>rate|null` fn or a rate table. */
+  rates?: RateSource;
+  /** The code a rate *table* is denominated in, when not the one mapping to 1. */
+  rateBase?: string;
+  /** Fixed fraction digits; omit for the code's own convention. */
+  decimals?: number;
+  /** The locale for number formatting. */
+  locale?: string;
+  /** Text for a null cell. */
+  nullDisplay?: string;
+  /** The loud marker rendered when a needed rate is missing. */
+  missingRate?: string;
+  /** An Excel number-format override. */
+  excel?: string;
+  /** The code list a currency editor's picker offers. */
+  codes?: string[];
+}
+
+/** Build a currency `DataType` (amount + code), aggregate-safe across currencies. */
+export function createCurrencyType(config?: CurrencyConfig): DataType;
+/** Parse edited/pasted text into a `Money`, taking the config's `code` for bare numbers. */
+export function parseMoney(text: string | number, cfg?: CurrencyConfig): Money | null;
+/** Render a `Money`, in the display currency when set; loud marker when a rate is missing. */
+export function formatMoney(value: unknown, cfg?: CurrencyConfig): string;
+/** Convert a `Money` into a target code via the resolved rate fn; `null` when no rate. */
+export function convertMoney(
+  money: Money,
+  to: string,
+  rate: (from: string, to: string) => number | null,
+): number | null;
+/** Resolve a caller's rate source into a `(from,to)=>rate|null` function. */
+export function rateFunction(rates?: RateSource, base?: string): (from: string, to: string) => number | null;
+/** The loud marker text a missing rate renders as. */
+export const MISSING_RATE: string;
+
 /** How a statistic block finds the number it reports. */
 export interface StatValueSpec {
   /** The column to reduce, as a field name or a dotted path. Omit for `count`. */
@@ -4024,10 +4306,18 @@ export const NO_CAPABILITIES: Readonly<Required<PushdownCapabilities>>;
  * per condition per query, and membership on an array is a scan. The declared
  * form and the resolved form differ, which is why this is its own type.
  */
-export type ResolvedCapabilities = Omit<Required<PushdownCapabilities>, 'operators'> & {
+export type ResolvedCapabilities = Omit<Required<PushdownCapabilities>, 'operators' | 'mutate'> & {
   operators: ReadonlySet<string>;
+  /** Resolved by `resolveMutate`: `false`, or every kind and `returning` present. */
+  mutate: false | Required<MutateCapability>;
 };
 
+/**
+ * Resolve an adapter's declared `mutate` block against the defaults (§4.1).
+ * `false` (or anything falsy) stays `false` — read-only by declaration.
+ */
+export function resolveMutate(declared?: boolean | MutateCapability): false | Required<MutateCapability>;
+
 export function capabilitiesOf(declared?: PushdownCapabilities): ResolvedCapabilities;
 
 /**
@@ -4235,6 +4525,12 @@ export const LatticeGrid: {
   parseUnit: typeof parseUnit;
   formatUnit: typeof formatUnit;
   UNIT_SYSTEMS: typeof UNIT_SYSTEMS;
+  createCurrencyType: typeof createCurrencyType;
+  parseMoney: typeof parseMoney;
+  formatMoney: typeof formatMoney;
+  convertMoney: typeof convertMoney;
+  rateFunction: typeof rateFunction;
+  MISSING_RATE: typeof MISSING_RATE;
 };
 
 export default LatticeGrid;
@@ -4337,6 +4633,65 @@ export interface ChartMeasure {
   title?: string;
 }
 
+/** One axis's configuration. A bare string is the title. */
+export interface ChartAxis {
+  title?: string;
+  /** Fix the axis rather than taking its extent from the data. */
+  min?: number;
+  max?: number;
+  /** A tick count, or the exact values to tick. */
+  ticks?: number | unknown[];
+  /** A format mask, or a function of the value. */
+  format?: string | ((value: unknown) => string);
+  /** Draw the gridlines this axis owns. Default true for the measure axis. */
+  grid?: boolean;
+  /** Draw the tick labels. */
+  labels?: boolean;
+  /** Show every nth category label, on a crowded category axis. */
+  every?: number;
+  /** Force the category labels' rotation rather than deciding it. */
+  rotate?: boolean | 'auto';
+}
+
+/**
+ * One declarative annotation (BACKLOG-0000744).
+ *
+ * A reference or target line, a shaded band, or a callout. Its value is a
+ * constant `value` (or `from`/`to` for a band), or a `compute` reduction of the
+ * data it annotates — `mean`, `median`, `min`, `max`, or `p95` for a
+ * percentile — so it follows the data as the grid is filtered. Every annotation
+ * names the axis it reads, which on a dual-axis chart is what stops it being
+ * placed against the wrong scale, and is written into the accessible table as a
+ * sentence.
+ */
+export interface ChartAnnotation {
+  /** The default is a reference line. */
+  kind?: 'line' | 'target' | 'band' | 'callout';
+  /** A constant value, for a line, target or callout's measure position. */
+  value?: number;
+  /** A reduction of the annotated data instead of a constant. */
+  compute?: 'mean' | 'avg' | 'median' | 'min' | 'max' | string;
+  /** A band's two edges, each a constant or (with `fromCompute`/`toCompute`) computed. */
+  from?: number;
+  to?: number;
+  fromCompute?: string;
+  toCompute?: string;
+  /** A vertical line's or callout's x position: a category or a number. */
+  x?: unknown;
+  at?: unknown;
+  /** Force a line vertical rather than horizontal. */
+  orient?: 'horizontal' | 'vertical';
+  /** Which measure axis the annotation reads. */
+  axis?: 'left' | 'right' | 'y2';
+  /** Restrict a `compute` to one series, by its key. */
+  series?: string;
+  label?: string;
+  colour?: string;
+  /** A band's fill opacity; the default is 0.12. */
+  opacity?: number;
+  className?: string;
+}
+
 /** Data labels beside each mark. */
 export interface ChartLabels {
   position?: 'outside' | 'inside' | 'auto';
@@ -4383,7 +4738,28 @@ export interface ChartSpec {
   scheme?: string | string[];
   legend?: boolean | { position?: 'top' | 'bottom' | 'left' | 'right'; isolate?: boolean };
   labels?: boolean | ChartLabels;
-  axis?: object;
+  /**
+   * Per-axis configuration. Each side is a title string or an object of
+   * `{ title, min, max, ticks, format, grid, labels }`. `y2` (or `right`)
+   * configures the second measure axis of a dual-axis or combo chart
+   * (BACKLOG-0000743); a dual-axis chart labels both axes by default so it
+   * cannot silently mislead.
+   */
+  axis?: {
+    x?: string | ChartAxis;
+    y?: string | ChartAxis;
+    y2?: string | ChartAxis;
+    right?: string | ChartAxis;
+  };
+  /**
+   * Dragging across the plot. `true` or `'filter'` writes a range condition into
+   * the grid; `'zoom'` changes only this chart's own domain; `'select'` selects
+   * the rows under the drag. The object form names which axis the drag acts on —
+   * `axis: 'y'` or `'y2'` brushes a value axis, which on a dual-axis chart must
+   * say which one it means (BACKLOG-0000743).
+   */
+  brush?: boolean | 'filter' | 'zoom' | 'select'
+    | { mode: 'filter' | 'zoom' | 'select'; axis?: 'x' | 'y' | 'y2' };
   font?: object;
   margin?: number | { top?: number; right?: number; bottom?: number; left?: number };
   /** Horizontal reference lines. */
@@ -4402,7 +4778,20 @@ export interface ChartSpec {
    * from another column instead.
    */
   error?: boolean | { of?: string; confidence?: number };
-  reference?: { value: number; label?: string }[];
+  /**
+   * Horizontal reference lines. On a dual-axis bar or line chart (see
+   * {@link ChartMeasure.axis}) a line naming `axis: 'right'` is placed on the
+   * right-hand scale, so it means what the right axis says rather than landing
+   * at the same number on the scale it does not belong to.
+   */
+  reference?: { value: number; label?: string; axis?: 'left' | 'right' }[];
+  /**
+   * The declarative annotation layer: reference and target lines, shaded bands
+   * and callouts, each naming the axis it reads and each described into the
+   * accessible table as a sentence. A value may be a constant or `compute`d from
+   * the data it annotates, so it follows the chart as the grid is filtered.
+   */
+  annotations?: ChartAnnotation[];
   /** Bins for a histogram; the default is twelve. */
   buckets?: number;
   /** A diverging colour ramp, for heatmap and geomap. */