@toclocoinc/lattice-grid 1.46.1 → 1.47.0

package/README.md

@@ -4,7 +4,7 @@
 dependencies, no build step required. Optional adapters for React, Vue, Svelte
 and Web Components ship alongside it.
 
-Version 1.46.1 · [latticegrid.dev](https://www.latticegrid.dev) · TOCLOCO Inc
+Version 1.47.0 · [latticegrid.dev](https://www.latticegrid.dev) · TOCLOCO Inc
 
 ---
 
@@ -36,6 +36,10 @@ Every module is optional and none of them is loaded unless you import it.
 | `modules/dhtmlx-compat.esm.min.js` | A compatibility wrapper for dhtmlx Grid, for moving an existing integration across without rewriting it. |
 | `modules/devtools.esm.min.js` | The devtools panel, including the accessibility checks. |
 
+This is the short list. [Modules & entry points](#modules--entry-points) is the
+complete map — every framework adapter, feature module and chart-type extension,
+with its npm import, CDN path and browser global.
+
 ---
 
 ## What it does
@@ -270,6 +274,132 @@ your editor tells you and what the grid does cannot drift apart.
 
 ---
 
+## Modules & entry points
+
+The package ships the core plus a set of optional modules, each as its own file.
+Nothing is loaded unless you import it, and a page that imports none of the
+modules pays for none of them. This section is the complete map: every public
+entry point, how to import it from npm, how to reach it on a CDN, and — for the
+`<script>`-tag builds — the browser global it leaves behind.
+
+**Three variants ship for most entry points.** Pick the one your page loads by:
+
+- **ESM** — `*.esm.min.js`. The default for a bundler or a native `<script
+  type="module">`. This is what the bare `@toclocoinc/lattice-grid` and
+  `@toclocoinc/lattice-grid/modules/<name>` specifiers resolve to.
+- **UMD** — `*.min.js`. For a plain `<script src>` load; it defines a browser
+  global (below). Reach it from npm with the explicit `.js` specifier
+  (`@toclocoinc/lattice-grid/modules/<name>.js`).
+- **CJS** — `*.min.cjs`. For `require()`. Reach it with the explicit `.cjs`
+  specifier, or let `require('@toclocoinc/lattice-grid')` resolve it.
+
+Alongside those: the stylesheet `lattice-grid.min.css` (required, imported as
+`@toclocoinc/lattice-grid/css`) and the TypeScript declarations
+`lattice-grid.d.ts` (wired through `package.json`, so no configuration).
+
+**On a CDN**, every file below sits under the same base — jsDelivr serves the
+published package directly:
+
+```
+https://cdn.jsdelivr.net/npm/@toclocoinc/lattice-grid@<version>/<file>
+```
+
+Pin an exact `<version>` in production. The `<file>` column in each table below
+is exactly what you append.
+
+### Core
+
+| npm import | CDN `<file>` | Browser global |
+|---|---|---|
+| `@toclocoinc/lattice-grid` (ESM) | `lattice-grid.esm.min.js` | — |
+| `@toclocoinc/lattice-grid` (CJS `require`) | `lattice-grid.min.cjs` | — |
+| `@toclocoinc/lattice-grid/lattice-grid.min.js` (UMD) | `lattice-grid.min.js` | `LatticeGrid` |
+| `@toclocoinc/lattice-grid/css` | `lattice-grid.min.css` | — (stylesheet) |
+| types | `lattice-grid.d.ts` | — (declarations) |
+
+### Framework adapters
+
+Each adapter ships all three variants (`modules/<name>.esm.min.js`,
+`modules/<name>.min.js`, `modules/<name>.min.cjs`). The npm ESM specifier is
+shown; append `.js` for the UMD build or `.cjs` for CommonJS.
+
+| Module | npm import (ESM) | CDN `<file>` (UMD) | Browser global | What it is |
+|---|---|---|---|---|
+| react | `@toclocoinc/lattice-grid/modules/react` | `modules/react.min.js` | `LatticeGridReact` | React adapter. |
+| vue | `@toclocoinc/lattice-grid/modules/vue` | `modules/vue.min.js` | `LatticeGridVue` | Vue adapter. |
+| svelte | `@toclocoinc/lattice-grid/modules/svelte` | `modules/svelte.min.js` | `LatticeGridSvelte` | Svelte adapter. |
+| angular | `@toclocoinc/lattice-grid/modules/angular` | `modules/angular.min.js` | `LatticeGridAngular` | Angular adapter. |
+| webcomponent | `@toclocoinc/lattice-grid/modules/webcomponent` | `modules/webcomponent.min.js` | `LatticeGrid` (extends it) | `<lattice-grid>` as a self-contained custom element. |
+| htmx | `@toclocoinc/lattice-grid/modules/htmx` | `modules/htmx.min.js` | `LatticeGridHtmx` | htmx integration that survives DOM swaps and hydrates from a server-rendered `<table>`. |
+
+The framework adapters take the framework and `createGrid` handed in rather than
+importing either (see [Quick start](#react-vue-svelte-and-web-components)). The
+web component and htmx are self-contained: they carry the grid, so load them on
+their own, not beside the base package.
+
+### Feature modules
+
+Each ships all three variants. The npm ESM specifier is shown; append `.js` for
+the UMD build or `.cjs` for CommonJS.
+
+| Module | npm import (ESM) | CDN `<file>` (UMD) | Browser global | What it is |
+|---|---|---|---|---|
+| charts | `@toclocoinc/lattice-grid/modules/charts` | `modules/charts.min.js` | `LatticeGrid` (extends it) | Charts bound to the grid's own result (`createChart`). |
+| data-router | `@toclocoinc/lattice-grid/modules/data-router` | `modules/data-router.min.js` | `LatticeGridDataRouter` | One stream split by property and routed to many grids or charts. |
+| kanban | `@toclocoinc/lattice-grid/modules/kanban` | `modules/kanban.min.js` | `LatticeGridKanban` | Board view: grid rows as cards grouped into columns (`createKanban`). |
+| gantt | `@toclocoinc/lattice-grid/modules/gantt` | `modules/gantt.min.js` | `LatticeGridGantt` | Editable, dependency-aware project plan with a computed critical path (`createGantt`). |
+| kpi | `@toclocoinc/lattice-grid/modules/kpi` | `modules/kpi.min.js` | `LatticeGridKPI` | A grid of stat tiles, each an aggregate over a dataset (`createKPI`). |
+| ai | `@toclocoinc/lattice-grid/modules/ai` | `modules/ai.min.js` | `LatticeGridAI` | Bring-your-own-model narrative and insights grounded on computed figures (`createAI`). |
+| mock-socket | `@toclocoinc/lattice-grid/modules/mock-socket` | `modules/mock-socket.min.js` | `LatticeGridMockSocket` | A serverless stand-in for a live WebSocket feed (`MockWebSocket`, `opsFeed`). |
+| devtools | `@toclocoinc/lattice-grid/modules/devtools` | `modules/devtools.min.js` | `LatticeGrid` (extends it) | The in-page diagnostic panel, including the accessibility checks (`createDevtools`). |
+| dhtmlx-compat | `@toclocoinc/lattice-grid/modules/dhtmlx-compat` | `modules/dhtmlx-compat.min.js` | `LatticeGrid` (extends it) | A dhtmlx `Grid`-shaped API for moving an existing integration across. |
+
+The four modules that extend `LatticeGrid` (charts, devtools, dhtmlx-compat,
+webcomponent) fold their exports into the core global, so load the core
+`<script>` first and then the module — for example `LatticeGrid.createChart(...)`
+becomes available once both are loaded. With a bundler they share the one core
+the page already imported rather than carrying a second copy.
+
+### Chart-type extensions
+
+Eighteen additional chart types ship as separate, tree-shakeable ESM modules.
+Each one **self-registers** its type onto the charts module's shared registry the
+moment it is imported — so load the base charts module first, import the
+extension for its side effect, then name the type in `createChart`. They ship as
+ESM only (import for side effect; there is no global to reach).
+
+```js
+import '@toclocoinc/lattice-grid/modules/charts';       // the base registry
+import '@toclocoinc/lattice-grid/modules/chart-alluvial'; // registers 'alluvial'
+createChart({ grid, container, type: 'alluvial', source: 'from', target: 'to', value: 'count' });
+```
+
+Each is imported from `@toclocoinc/lattice-grid/modules/chart-<type>` (CDN
+`<file>`: `modules/chart-<type>.esm.min.js`), and registers the `type` shown.
+
+| Import / `type` | What it draws |
+|---|---|
+| `chart-alluvial` → `alluvial` | Alluvial diagram: categorical flow from one dimension to another. |
+| `chart-arc` → `arc` | Arc diagram: nodes on a line, links as arcs. |
+| `chart-bubblemap` → `bubblemap` | Symbol / bubble map. |
+| `chart-bump` → `bump` | Bump chart: rank over time. |
+| `chart-calendar` → `calendar` | Calendar heatmap. |
+| `chart-decomposition` → `decomposition` | Seasonal decomposition panel. |
+| `chart-diverging` → `diverging` | Diverging bar chart. |
+| `chart-dumbbell` → `dumbbell` | Dumbbell / connected-dot plot. |
+| `chart-fan` → `fan` | Fan / forecast chart. |
+| `chart-hexbin` → `hexbin` | Hexbin / 2D-density plot. |
+| `chart-hexmap` → `hexmap` | Hexbin map. |
+| `chart-icicle` → `icicle` | Icicle chart. |
+| `chart-parallel` → `parallel` | Parallel coordinates. |
+| `chart-ridgeline` → `ridgeline` | Ridgeline (joy) plot. |
+| `chart-roc` → `roc` | ROC / PR / calibration curves. |
+| `chart-slope` → `slope` | Slope chart. |
+| `chart-splom` → `splom` | Scatter-plot matrix. |
+| `chart-waffle` → `waffle` | Waffle / dot-matrix chart. |
+
+---
+
 ## Full-screen mode
 
 A grid usually lives in whatever box the page layout gave it, and that box is

package/docs/API.html

@@ -4538,6 +4538,34 @@ charts.registerChartType('ridgeline', { draw: ridge.drawRidgeline });
   typeof parallel.drawParallel, typeof parallel.bindParallel,
 ].join(' | ');</code></pre>
 
+    <p>When parallel coordinates is given a <code>colourBy</code> column it colours each line by its category — but a colour with no key is a code, so the chart now emits a <strong>legend</strong> of those categories (BACKLOG-0000999), one entry per category in the order the colours were assigned, exactly the shape every other coloured type returns. The base draws it and wires the click, so a click on a category toggles it off through the same hide-a-series gesture the rest of the module has, and the drawer skips a hidden category's lines. With no <code>colourBy</code> there is nothing to key and no legend is drawn. The categories the key is built from are the ones <code>bindParallel</code> returns as <code>groups</code>:</p>
+    <pre data-run="js" data-expect="key red,green,blue" data-covers="export:bindParallel"><code><span class="kw">const</span> { createHeadlessGrid } = <span class="kw">await</span> import('../packages/core/src/index.js');
+<span class="kw">const</span> { bindParallel } = <span class="kw">await</span> import('../packages/modules/chart-parallel/index.js');
+<span class="kw">const</span> cats = ['red', 'green', 'blue'];
+<span class="kw">const</span> rows = Array.from({ length: 9 }, (unused, i) =&gt; ({ id: `R${i}`, a: i, b: i % 4, grp: cats[i % 3] }));
+<span class="kw">const</span> grid = createHeadlessGrid({
+  columns: [{ field: 'a', type: 'number' }, { field: 'b', type: 'number' }, { field: 'grp', type: 'text' }],
+  rows, rowKey: 'id',
+});
+<span class="cmt">// The colourBy categories, in colour order — each becomes a legend entry whose</span>
+<span class="cmt">// index picks the same colour its lines use.</span>
+<span class="kw">const</span> bound = bindParallel(grid, { columns: ['a', 'b'], colourBy: 'grp' });
+grid.destroy();
+<span class="kw">return</span> `key ${bound.groups.join(',')}`;</code></pre>
+
+    <p>A least-squares forecast on the trend overlay (<code>trend: { method: 'linear', forecast: n }</code>) no longer draws a bare dashed line: it shades the <strong>uncertainty band</strong> around the projection (BACKLOG-0000975). By default that is the Student-t <em>prediction</em> band (a future observation); <code>band: 'confidence'</code> shades the narrower mean-response band the fitted line's own doubt describes, and <code>band: false</code> leaves the bare line. The band widens as the line runs further past the data — the honest shape, since a projection is least certain where it reaches furthest — and <code>confidence</code> (default 0.95) sets its level. It is the exact interval the core <code>forecast</code> kernel reports for the linear method, computed locally in the charts bundle (never imported, for the bundle reason the trend maths already is) and asserted equal to the engine's to the last digit:</p>
+    <pre data-run="js" data-expect="match true; conf 0.95" data-covers="export:forecast"><code><span class="kw">const</span> { forecast } = <span class="kw">await</span> import('../packages/core/src/index.js');
+<span class="kw">const</span> { linearTrend } = <span class="kw">await</span> import('../packages/modules/charts/trendline.js');
+<span class="kw">const</span> ys = [2, 5, 6, 9, 11, 12];
+<span class="kw">const</span> pairs = ys.map((y, i) =&gt; ({ x: i, y }));
+<span class="cmt">// The trend overlay's forecast band, three steps ahead at 95%…</span>
+<span class="kw">const</span> overlay = linearTrend(pairs, 3, { confidence: 0.95 });
+<span class="cmt">// …is the core forecast kernel's linear prediction band, to the last digit.</span>
+<span class="kw">const</span> engine = forecast(ys, { method: 'linear', horizon: 3, confidence: 0.95 });
+<span class="kw">const</span> b = overlay.band.points[3];
+<span class="kw">const</span> e = engine.points[2];
+<span class="kw">return</span> `match ${b.lower === e.lower &amp;&amp; b.upper === e.upper}; conf ${overlay.band.confidence}`;</code></pre>
+
     <p>The hierarchy, flow and geographic remainder ships the same way — treemap, sunburst, funnel, radar, sankey, chord and network are already built in, so the new opt-in modules are: <strong>icicle</strong> (<code>drawIcicle</code>, <code>type: 'icicle'</code>, drawn from the grid's group tree), <strong>waffle</strong> (<code>drawWaffle</code>, <code>type: 'waffle'</code>), <strong>alluvial</strong> (<code>drawAlluvial</code>/<code>bindAlluvial</code>, <code>type: 'alluvial'</code>), <strong>arc diagram</strong> (<code>drawArc</code>/<code>bindArc</code>, <code>type: 'arc'</code>), <strong>bubble map</strong> (<code>drawBubbleMap</code>/<code>bindBubbleMap</code>, <code>type: 'bubblemap'</code>) and <strong>hexbin map</strong> (<code>drawHexMap</code>/<code>bindHexMap</code>, <code>type: 'hexmap'</code>). The two maps place <code>lon</code>/<code>lat</code> directly, so they need no outline data and fetch nothing.</p>
     <pre data-run="js" data-expect="true | function | function | function | function | function | function | function | function | function | function" data-covers="export:drawIcicle export:drawWaffle export:drawAlluvial export:bindAlluvial export:drawArc export:bindArc export:drawBubbleMap export:bindBubbleMap export:drawHexMap export:bindHexMap"><code><span class="kw">const</span> charts = <span class="kw">await</span> import('../packages/modules/charts/index.js');
 <span class="kw">const</span> icicle = <span class="kw">await</span> import('../packages/modules/chart-icicle/index.js');
@@ -4606,6 +4634,7 @@ router.load(snapshot);                        <span class="cmt">// every viewer
           <tr><td class="sig">configure(spec)</td><td class="desc"><strong>v5:</strong> the whole routing graph as one data spec &mdash; <code>routes</code> (grid/<code>default</code>/<code>subscribe</code>/<code>alert</code> entries), <code>links</code>, <code>relate</code>, <code>buffer</code> &mdash; desugared to the imperative API. Composes with imperative calls and round-trips to identical behaviour. Also accepted as <code>createDataRouter({ config })</code>.</td></tr>
           <tr><td class="sig">attach(grid, predicate, { writable, onWrite?, onConflict? })</td><td class="desc"><strong>v8 (BACKLOG-0000912):</strong> make a route <strong>writable</strong> &mdash; the router captures the grid's committed edits off its public edit surface (<code>grid.on('cell:changed')</code> &rarr; <code>grid.edit.setCells</code>) and routes them to <code>onWrite(change, { route, source })</code> (per-route here, or the router-global <code>onWrite</code>), reverting the cell on reject and re-entering an accepted write as a normal delta. <code>onConflict(change, { serverRow })</code> surfaces a last-write-wins conflict. A derived (<code>rollup</code>/<code>transform</code>) route cannot be writable &mdash; its edits are reverted and warned.</td></tr>
           <tr><td class="sig">attach(grid, predicate, { where })</td><td class="desc"><strong>v7 (BACKLOG-0000914):</strong> a route-level <code>where</code> &mdash; a filter-wire condition <code>{ col, op, value }</code> or an <code>and</code>/<code>or</code>/<code>not</code> group &mdash; used only by query-slice routing (<code>query()</code>): the router pushes it <em>down</em> to the engine where the adapter allows and finishes the residual client-side. Distinct from <code>filter</code> (a <code>fn(row)</code> that only ever runs in the browser).</td></tr>
+          <tr><td class="sig">attach(grid, predicate, { label, backpressure })</td><td class="desc"><strong>v10/v13:</strong> a human <code>label</code> for the route (shown in <code>metrics()</code> and the devtools panel), and a per-route <strong>backpressure</strong> policy that throttles / coalesces / samples how that route's viewer is refreshed under load &mdash; <em>without</em> touching the keyed store or any other route. <code>backpressure: { maxHz, minInterval?, sample?, maxLag? }</code>: <code>maxLag</code> (a backlog depth) sets when it engages (below it, changes pass straight through); <code>maxHz</code>/<code>minInterval</code> cap the refresh rate; <code>sample</code> (an integer &gt; 1) thins intermediate refreshes. A trailing flush always lands the latest state (deletes included), so the viewer converges and is never left stale.</td></tr>
           <tr><td class="sig">query(adapter, request?)</td><td class="desc"><strong>v7 (BACKLOG-0000914):</strong> source the router from a DFQL/DuckDB (or any pushdown) adapter. Runs <code>adapter.execute</code>, partitions the result across the routes and drives the grids by the same keyed diff <code>load()</code> uses; a route's <code>where</code> is planned against the adapter's capabilities (pushed down where allowed, residual finished client-side). Composes with per-route <code>transform</code>/<code>filter</code>/<code>sort</code>/<code>rollup</code> and links/graph. Async &mdash; resolves once every slice is fetched and applied.</td></tr>
           <tr><td class="sig">lastQueryPlan()</td><td class="desc"><strong>v7:</strong> the pushed/residual split of the last <code>query()</code>, per fetch &mdash; whether a filter reached the engine and what work was left client-side. <code>null</code> before any query. Provenance, so a slow slice is diagnosed rather than guessed.</td></tr>
           <tr><td class="sig">buffer({ window?, max? })</td><td class="desc"><strong>v4 (BACKLOG-0000911):</strong> turn on time-travel buffering &mdash; record the ordered, de-duplicated stream into a <strong>bounded</strong> ring (a time <code>window</code> in ms and/or a <code>max</code> delta count; eviction folds the oldest into a moving base, so memory never grows unbounded; a default cap applies if you name neither). Seeded from the current world, so it can be turned on at any time. Opt-in and off by default.</td></tr>
@@ -4618,9 +4647,12 @@ router.load(snapshot);                        <span class="cmt">// every viewer
           <tr><td class="sig">broadcasting</td><td class="desc"><strong>v6:</strong> whether the router is currently mirroring to a BroadcastChannel.</td></tr>
           <tr><td class="sig">addSource(feed, { map?, key? })</td><td class="desc"><strong>v9 (BACKLOG-0000931):</strong> register a source feed &mdash; fan-in. Returns a handle (<code>load</code>/<code>apply</code>/<code>push</code>/<code>remove</code>, plus <code>id</code>/<code>size</code>) whose rows are normalized by <code>map</code> and namespaced by <code>key</code> (a prefix string, <code>true</code> to prefix with the source id, or a <code>keyFn(row)</code>) so ids from different feeds cannot collide, then merged through the router's ordinary path &mdash; partitioned, routed, linked, deduped, buffered and written back exactly as the single-source path. <code>feed</code> is an optional source id or an options object. A source may also carry a <code>join</code> spec (v11) to <strong>enrich</strong> its rows with fields looked up from another source.</td></tr>
           <tr><td class="sig">removeSource(ref) / sources()</td><td class="desc"><strong>v9:</strong> drop exactly the rows a feed contributed (by source id or handle) from every route and unregister it; and list the registered source ids.</td></tr>
-          <tr><td class="sig">metrics()</td><td class="desc"><strong>v10 (BACKLOG-0000932):</strong> a cheap point-in-time observability snapshot &mdash; per-route row counts and throughput (rows/sec since the previous read), per-source rates and totals (fan-in), and the global <code>unrouted</code> / <code>dropped</code> / <code>buffered</code> / <code>lag</code> figures. Throughput is sampled over the interval since the last <code>metrics()</code> call or emit.</td></tr>
+          <tr><td class="sig">metrics()</td><td class="desc"><strong>v10 (BACKLOG-0000932):</strong> a cheap point-in-time observability snapshot &mdash; per-route row counts and throughput (rows/sec since the previous read), per-source rates and totals (fan-in), and the global <code>unrouted</code> / <code>dropped</code> / <code>buffered</code> / <code>lag</code> figures. Throughput is sampled over the interval since the last <code>metrics()</code> call or emit. Each entry in <code>routes[]</code> also carries its <code>label</code> and, when the route declares a backpressure policy, a <code>backpressure: { pending, coalesced }</code> object &mdash; <code>pending</code> is the held backlog since the last flush (the route's lag) and <code>coalesced</code> the cumulative change-events it has absorbed into deferred refreshes (<code>null</code> when the route has no policy).</td></tr>
           <tr><td class="sig">on('metrics', handler)</td><td class="desc"><strong>v10:</strong> subscribe to the periodic <code>metrics</code> emit (the <code>metricsInterval</code> ms, default 1000; <code>0</code> disables it). The timer runs only while at least one listener is registered and stops when the last is removed. Returns an unsubscribe function.</td></tr>
           <tr><td class="sig">mountDevtools(el, { interval? })</td><td class="desc"><strong>v10:</strong> mount an opt-in, DOM-touching live panel (in the module's own <code>devtools.js</code>, so the core stays DOM-free) that renders <code>metrics()</code> into <code>el</code> and refreshes on each emit. Returns a controller with <code>destroy()</code>. Off unless called.</td></tr>
+          <tr><td class="sig">persist({ key?, debounce?, storage?, indexedDB?, dbName?, storeName? })</td><td class="desc"><strong>v12 (BACKLOG-0000961):</strong> turn on durable persistence &mdash; snapshot the keyed store and the time-travel ring to a durable async key/value store so an offline reload or a browser refresh resumes exactly where it left off. The default backend is <strong>IndexedDB</strong> (native, no dependency), opened lazily and guarded so private-mode or blocked storage degrades to in-memory with a one-time warning rather than throwing. Writes a coalesced snapshot after each <code>load</code>/<code>apply</code> (debounced by <code>debounce</code> ms, default 250; <code>0</code> is eager). Pass <code>storage</code> &mdash; any object with async <code>get(key)</code>/<code>set(key, value)</code> &mdash; to use another backend (a server, a test double). Opt-in and off by default.</td></tr>
+          <tr><td class="sig">restore()</td><td class="desc"><strong>v12:</strong> resume from the durable snapshot. Read the last persisted state and apply it &mdash; <code>load</code> the live head through the ordinary keyed diff (so grids attached before this call repaint only what differs), restore the resume checkpoint and, when the snapshot carried a time-travel ring, restore buffering and the ring so <code>scrubTo</code>/<code>replay</code>/<code>live</code> work straight after a reload. Call it once, after attaching the grids. <code>async</code>; resolves <code>true</code> when a snapshot was found and applied, <code>false</code> when persistence is off/degraded or nothing was stored.</td></tr>
+          <tr><td class="sig">flushPersist() / persisting</td><td class="desc"><strong>v12:</strong> flush any pending durable write now (<code>async</code>; cancels the debounce and resolves once the write settles &mdash; for a <code>beforeunload</code> handler, a deterministic checkpoint, or a test), and whether durable persistence is on and not degraded to in-memory.</td></tr>
           <tr><td class="sig">detach(grid)</td><td class="desc">Stop routing to a grid and forget its slice; drop any link/edge it is part of (restoring a filtered sibling). The host still owns and destroys the grid.</td></tr>
           <tr><td class="sig">destroy()</td><td class="desc">Detach every grid, drop every link, edge and subscription. <strong>Detaches only</strong> &mdash; the host owns and destroys its grids.</td></tr>
         </tbody>
@@ -4891,6 +4923,7 @@ g.destroy(); router.destroy();
 <span class="kw">return</span> [merged, ids, afterRemove].join(' | ');</code></pre>
 
     <p><strong>Fan-in JOIN / enrichment (v11, BACKLOG-0000957).</strong> Fan-in above <em>merges</em> feeds side by side; a <code>join</code> spec goes further and <em>enriches</em> one feed's rows with fields looked up from <em>another</em> registered source &mdash; e.g. an <code>orders</code> feed enriched with <code>name</code>/<code>tier</code> from a <code>customers</code> source keyed by <code>customerId</code>. Declared per source: <code>addSource('orders', { join: { from: 'customers', localKey: 'customerId', fields: ['name', 'tier'], missing: 'hold' } })</code>. <code>localKey</code> is the field on the enriched (left) row holding the foreign key (a field name or <code>fn(row)</code>); <code>foreignKey</code> is the field matched on the lookup row (defaults to <code>localKey</code>'s name); <code>fields</code> is what to pull &mdash; an array, a <code>{ src: dest }</code> rename map, or <code>select(lookupRow, leftRow) =&gt; object</code>. No second store is built: the lookup source <em>is</em> an ordinary fan-in source, and the join probes its existing keyed store by an index of join-key&nbsp;&rarr;&nbsp;store-id. <code>missing</code> chooses what happens when the lookup is absent or late: <code>hold</code> withholds the row from viewers until its lookup arrives, <code>passthrough</code> (the default) lets it flow unenriched, and <code>null</code> flows it with the pulled fields set to <code>null</code>. Enriched rows reach viewers through the ordinary keyed-diff path. <strong>Late lookups re-enrich:</strong> when a lookup row arrives, changes, or is deleted, every already-seated left row that references it is re-enriched and re-emitted &mdash; a held row is released, a <code>null</code>/<code>passthrough</code> row gains its fields, and a row whose lookup vanished is nulled/stripped (or, under <code>hold</code>, withheld again). Enrichment always recomputes from the untouched base row, so it is idempotent.</p>
+    <p><strong>Durable resume and backpressure (v12/v13, BACKLOG-0000961 / BACKLOG-0000962).</strong> <code>persist({ key })</code> turns on durability: the router snapshots its keyed store and time-travel ring to a durable async store (IndexedDB by default, or any <code>{ get, set }</code> you pass as <code>storage</code>) after each <code>load</code>/<code>apply</code>, and <code>await router.restore()</code> &mdash; called once after the grids are attached &mdash; rehydrates them through the ordinary keyed diff, so an offline reload or a browser refresh resumes exactly where it left off (blocked/private storage degrades to in-memory with a one-time warning, never a throw). Independently, a route can declare <strong>backpressure</strong> &mdash; <code>attach(grid, type, { label, backpressure: { maxHz } })</code> &mdash; to cap how often its viewer repaints under load without slowing the store or any sibling route: <code>maxHz</code>/<code>minInterval</code> rate-limit the refresh, <code>sample</code> thins intermediate ones, and <code>maxLag</code> sets the backlog depth at which throttling engages; a trailing flush always lands the latest state so the viewer converges. What it cost is observable: <code>router.metrics().routes[].backpressure</code> is <code>{ pending, coalesced }</code> &mdash; the held backlog and the cumulative change-events folded into deferred refreshes (<code>null</code> for a route with no policy).</p>
     <h3 id="datarouter-v11-example">A JOIN with a late lookup, executed</h3>
     <p class="section-note">An order arrives before its customer, so under <code>hold</code> it is withheld; when the customer
     feed loads, the order is released and enriched with the looked-up name. Run headless on every build.</p>
@@ -5130,9 +5163,10 @@ const board = createKanban(document.querySelector('#board'), {
           <tr><td class="sig">editCard(key, field) / applyEdit(key, field, value)</td><td class="desc">Inline-edit a card field opted in with <code>card: { title: { field, edit: true } }</code>: grid-bound it commits through the grid's own field editor path (<code>grid.edit.setCells</code>); standalone it uses a host editor factory or a default input, reverting when <code>onCardEdit</code> rejects. Double-click a card to edit; emits <code>card:edit</code>.</td></tr>
           <tr><td class="sig">addCard(columnId, seed?)</td><td class="desc">Add a card to a column (with <code>config.addCard</code>'s per-column affordance) and open it in inline edit; a host <code>onAddCard(columnId)</code> supplies the row, or one is generated (grid-bound via <code>grid.edit.addRow</code>). Emits <code>card:add</code>.</td></tr>
           <tr><td class="sig">getState() / setState(snapshot)</td><td class="desc">Serialise and restore the board state — collapsed columns/lanes, column order, quick filter, sprint/epic selection and selection. Also accepted as <code>config.state</code> at construction.</td></tr>
+          <tr><td class="sig">sla</td><td class="desc">The card-aging / SLA monitor, present only when a <code>sla</code> config is supplied. Read <code>sla.states()</code>, <code>sla.breaches()</code>/<code>sla.warnings()</code> and <code>sla.stateFor(cardOrKey)</code> for each card's age and level; <code>sla.evaluate()</code> re-checks and fires crossings. See the card-aging note below.</td></tr>
           <tr><td class="sig">setLoading(bool) / setError(message)</td><td class="desc">A loading state and a host-supplied error banner; empty columns already render their placeholder.</td></tr>
           <tr><td class="sig">setRows(rows) / refresh()</td><td class="desc">Replace the source rows, or recompute and re-render.</td></tr>
-          <tr><td class="sig">on(name, fn) / off(name, fn)</td><td class="desc">Events: <code>card:click</code>, <code>card:dblclick</code>, <code>card:contextmenu</code>, <code>card:move</code>, <code>card:reverted</code>, <code>selection:changed</code>, <code>drag:start</code>, <code>drag:end</code> (plus the vocabulary the later cycles emit).</td></tr>
+          <tr><td class="sig">on(name, fn) / off(name, fn)</td><td class="desc">Events: <code>card:click</code>, <code>card:dblclick</code>, <code>card:contextmenu</code>, <code>card:move</code>, <code>card:reverted</code>, <code>card:confirmed</code>, <code>card:sla</code>, <code>selection:changed</code>, <code>drag:start</code>, <code>drag:end</code> (plus the vocabulary the later cycles emit). On a grid-bound board a move fires <code>card:move</code> optimistically; the grid's write-back then settles it with <code>card:confirmed</code> or, if the server rejects, <code>card:reverted</code> (the card re-reads and the flow transition log rolls the optimistic move back).</td></tr>
           <tr><td class="sig">readonly(scope)</td><td class="desc">Whether a scope is readonly &mdash; the whole board, a <code>{ column }</code> or a <code>{ card }</code>. A readonly card is not draggable; a move into a readonly column is refused.</td></tr>
           <tr><td class="sig">destroy()</td><td class="desc">Empty the element and drop the model. The host still owns any bound grid.</td></tr>
         </tbody>
@@ -5143,6 +5177,7 @@ const board = createKanban(document.querySelector('#board'), {
     <p><strong>Sprint, epic and card pop-out.</strong> <code>setSprint(id)</code> shows one sprint, <code>showBacklog()</code> the cards with no sprint, and <code>sprints()</code> feeds a switcher; <code>setEpic(id)</code> narrows to an epic and <code>epicRollup()</code> (or <code>rollup(property)</code>) returns per-epic count, points and progress toward the <code>done</code> columns. A card can <strong>pop out a nested grid of its children</strong> — an epic's stories, a story's tasks, recursively. The child relationship is a <code>childrenProperty</code> (parent-id within the dataset) and/or a <code>loadChildren(card)</code> (per-card dataset or async fetch), and the child is a full composed <code>createGrid</code> (sort/filter/edit/write-back) — supplied as <code>children.factory</code> — opened in a <code>drawer</code> (default), <code>modal</code> or <code>inline</code>. With <code>children.asBoard</code> the child is itself a board, so it can pop its own children. This reuses the grid by composition and adds no grid-core coupling. <code>expand(key)</code> and the per-card drill affordance emit <code>card:expand</code>; a deeper open emits <code>card:drill</code>.</p>
     <p><strong>Live updates.</strong> Because the board consumes data through the same keyed-diff contract a grid does, a <a href="#datarouter">Data Router</a> drives it directly — <code>router.attach(board, predicate)</code> — and one feed fans out to a grid, a kanban, a chart and a KPI tile at once. A live <code>rows.apply({ add, update, remove })</code> is applied as a keyed diff (an unchanged card keeps its model) and re-rendered <strong>preserving</strong> scroll, focus, selection, collapsed columns/lanes and any open pop-out, so a card can appear, move or update under the user without losing their place.</p>
     <p><strong>Scale, state and accessibility.</strong> <code>virtualize</code> renders only a scroll window of a tall column (with true-height spacers so the scrollbar stays honest), for boards of thousands of cards. <code>getState()</code>/<code>setState()</code> (and <code>config.state</code>) save and restore the collapsed columns and lanes, the column order, the quick filter and the sprint/epic selection, so a reopened board comes back as it was; <code>setLoading</code>/<code>setError</code> add loading and error states. Accessibility runs throughout: the board is a labelled group of labelled column lists, cards are a roving-tabindex focus ring (arrows to move focus, Enter to activate), the move is fully keyboard-driven (<kbd>Space</kbd> grab, arrows for column/position, <kbd>Alt</kbd>+<kbd>↑/↓</kbd> across swimlanes, <kbd>Space</kbd>/<kbd>Enter</kbd> drop, <kbd>Escape</kbd> cancel) with live-region announcements, and every affordance carries a name.</p>
+    <p><strong>Card aging / SLA.</strong> A <code>sla</code> config ages each card and highlights the ones sitting too long. Thresholds are a raw millisecond count or a <code>{ days, hours, … }</code> spec, set globally as <code>{ warn, breach }</code>, per column (either <code>sla.columns[id]</code>, or a column def's own <code>sla</code>/<code>slaWarn</code>/<code>slaBreach</code>) and per swimlane (<code>sla.lanes[id]</code>); the most specific wins, lane&nbsp;&rarr;&nbsp;column&nbsp;&rarr;&nbsp;global. <code>basis</code> chooses whether the clock is time-in-current-column (default) or age-on-the-board, resolved from the flow transition log, an <code>enteredProperty</code>/<code>createdProperty</code> timestamp, or arrival. The view puts an age chip on aged cards (<code>showAge: 'always'</code> shows it on every card) and a highlight on breached ones. A rising crossing (ok&rarr;warn, warn&rarr;breach) fires the <code>card:sla</code> event <em>and</em> the <code>onWarn</code>/<code>onBreach(level, rows)</code> callbacks — the same <code>(signal, rows)</code> shape a <a href="#datarouter">Data Router</a> <code>alert</code> route uses, so one handler serves both. It is reached at runtime as <code>board.sla</code>; done-column cards are exempt by default (<code>ignoreDone: false</code> opts them in), and an optional <code>tick</code> re-checks so a card that breaches by simply sitting still still lights up. Example: <code>createKanban(el, { …, sla: { warn: { days: 2 }, breach: { days: 4 }, onBreach: notify } })</code>.</p>
     <p><strong>Inline edit and add-card.</strong> A field is opted into inline edit with the object mapping form — <code>card: { title: { field: 'title', edit: true } }</code>. Double-clicking a card (or <code>editCard(key, field)</code>) edits it in place: <strong>grid-bound</strong>, through the grid's own field editor for that column via its public edit path, so the column's parse, validate and optimistic/confirm/revert all run; <strong>standalone</strong>, through a host <code>editor</code> factory (or a default input), reverting when <code>onCardEdit</code> rejects. A per-column add-card affordance (<code>config.addCard</code>) creates a card carrying the column's group value — from a host <code>onAddCard(columnId)</code>, or generated, or appended through <code>grid.edit.addRow</code> when bound — and opens it straight in inline edit on its title, so the user just types. The module imports nothing from the grid's DOM package: grid-bound edits ride the grid's public edit API, standalone edits use the host's editor, so a board-only page never pulls the grid in.</p>
     <h3 id="kanban-example">A board, grouped and aggregated, executed</h3>
     <p class="section-note">A DemandFlow-shaped set &mdash; statuses as columns, points, an empty configured column,
@@ -5388,7 +5423,8 @@ const { text, flagged } = await ai.explain({ kind: 'column', colId: 'amount' });
         <thead><tr><th>Member</th><th>Description</th></tr></thead>
         <tbody>
           <tr><td class="sig">createAI(grid, config)</td><td class="desc">Create an AI narrative / insights controller over a live grid (headless or rendered). Config: <code>ask</code> (the host callback; falls back to the grid's <code>ai.ask</code>), <code>enable</code>, <code>maxRows</code>, <code>redact</code>, <code>tools</code>, <code>locale</code>, <code>reconcile</code> (<code>'strip'</code>/<code>'flag'</code>), <code>element</code>, <code>onNarrative</code>, <code>onError</code>.</td></tr>
-          <tr><td class="sig">explain(target?, opts?) / narrate(...)</td><td class="desc">Produce a grounded, reconciled narrative. <code>target</code> is <code>{ kind: 'view' }</code>, <code>{ kind: 'column', colId }</code>, <code>{ kind: 'forecast', colId, options }</code>, or <code>{ kind: 'kpi'|'chart', facts }</code>. Resolves to <code>{ text, facts, grounded, flagged, rounds, mode }</code>.</td></tr>
+          <tr><td class="sig">explain(target?, opts?) / narrate(...)</td><td class="desc">Produce a grounded, reconciled narrative. <code>target</code> is <code>{ kind: 'view' }</code>, <code>{ kind: 'column', colId }</code>, <code>{ kind: 'forecast', colId, options }</code>, <code>{ kind: 'kpi'|'chart', facts }</code>, or <code>{ kind: 'risk', gantt, board }</code> for a board / Gantt risk summary. Resolves to <code>{ text, facts, grounded, flagged, rounds, mode }</code>.</td></tr>
+          <tr><td class="sig">riskSummary(sources?, opts?)</td><td class="desc">A board / Gantt <strong>RISK SUMMARY</strong> &mdash; &ldquo;3 tasks at risk on the critical path, SPI 0.67, 2 SLA breaches&rdquo; &mdash; grounded on the separate Gantt / Kanban modules' outputs (<code>gantt</code>, <code>board</code>/<code>sla</code>, or their precomputed <code>earnedValue</code>/<code>schedule</code>/<code>breaches</code>). A convenience over <code>explain({ kind: 'risk' })</code>, through the same reconciliation guard.</td></tr>
           <tr><td class="sig">insights(el?, opts?)</td><td class="desc">Mount (or re-target) the insights panel into an element, its generate control wired to a view narrative. Keeps the grid usable on an <code>ask()</code> error.</td></tr>
           <tr><td class="sig">attachExplain(target, opts?)</td><td class="desc">Build an &ldquo;Explain&rdquo; button bound to a target (a KPI tile, a chart datum, a column). Clicking it narrates the target.</td></tr>
           <tr><td class="sig">facts(target?, opts?)</td><td class="desc">Build the facts packet for a target <em>without</em> calling <code>ask()</code> &mdash; the exact grounded set a narrative would use, and what would leave the browser.</td></tr>
@@ -5426,6 +5462,32 @@ ai.destroy();
 grid.destroy();
 <span class="kw">return</span> `${result.flagged.length} flagged | ${kept} kept | ${stripped} stripped`;</code></pre>
 
+    <h3 id="ai-risk">Board / Gantt risk summary (<code>modules/ai</code>)</h3>
+    <p>A project manager wants one line: <em>&ldquo;3 tasks at risk on the critical path, SPI 0.67, 2 SLA breaches.&rdquo;</em> <code>ai.riskSummary(&hellip;)</code> (and the <code>{ kind: 'risk' }</code> target of <code>explain</code>) produces exactly that, grounded on figures the <strong>separate</strong> optional modules have already computed: <code>gantt.earnedValue()</code> for SPI/CPI and the schedule/cost variances, <code>gantt.schedule</code> for the critical path and the tasks at risk on it, and <code>board.sla</code> for the SLA breach and warning counts. Every figure runs through the <strong>same number-reconciliation guard</strong> as the rest of the narrative &mdash; an ungrounded figure is stripped before the user sees it.</p>
+    <p><strong>The AI bundle imports neither the Gantt nor the Kanban module.</strong> You pass the module instances (or their already-computed outputs) on the target, and the layer reads them duck-typed &mdash; so a page that loads the AI module without those bundles carries none of their weight. <code>buildRiskFacts(target, opts)</code> is exported to build (and preview) the exact grounded facts a risk summary would use, without calling <code>ask()</code>. <strong>Redaction:</strong> a risk summary carries aggregates only by default &mdash; counts and the EVM indices/variances; it withholds task names and card contents. <code>includeTaskNames</code> adds the at-risk task names (bounded by <code>maxTasks</code>) and <code>includeCost</code> adds the money figures (BAC/PV/EV/AC), each the host's explicit opt-in, reported back in <code>meta.exposed</code>.</p>
+    <pre data-run="js" data-expect="2 at risk | SPI 0.8 | 2 breaches" data-covers="export:buildRiskFacts"><code><span class="kw">const</span> { buildRiskFacts } = <span class="kw">await</span> import('../packages/modules/ai/index.js');
+
+<span class="cmt">// The public outputs a host already holds from the SEPARATE gantt / kanban</span>
+<span class="cmt">// modules. The AI bundle imports neither — it reads these duck-typed.</span>
+<span class="kw">const</span> earnedValue = { ok: <span class="kw">true</span>, project: { spi: 0.8, cpi: 0.9, sv: -1000, cv: -500 } };
+<span class="kw">const</span> schedule = {
+  ok: <span class="kw">true</span>,
+  order: ['a', 'b', 'c'],
+  critical: ['a', 'b', 'c'],                    <span class="cmt">// all three on the critical path</span>
+  tasks: <span class="kw">new</span> Map([
+    ['a', { id: 'a', name: 'Design', percentComplete: 100, totalFloat: 0 }],
+    ['b', { id: 'b', name: 'Build', percentComplete: 40, totalFloat: 0 }],
+    ['c', { id: 'c', name: 'Ship', percentComplete: 0, totalFloat: -2 }],
+  ]),
+};
+<span class="kw">const</span> breaches = [{ key: 'CARD-1' }, { key: 'CARD-2' }];   <span class="cmt">// from board.sla.breaches()</span>
+
+<span class="kw">const</span> { facts } = buildRiskFacts({ kind: 'risk', earnedValue, schedule, breaches });
+<span class="kw">const</span> by = Object.fromEntries(facts.map((f) =&gt; [f.id, f]));
+
+<span class="cmt">// Two incomplete tasks (Build, Ship) are on the critical path — at risk.</span>
+<span class="kw">return</span> `${by['risk.atRisk'].display} at risk | SPI ${by['risk.spi'].display} | ${by['risk.sla.breaches'].display} breaches`;</code></pre>
+
     <h2 id="mocksocket">The mock socket</h2>
     <p><code>modules/mock-socket</code> is a serverless stand-in for a live <code>WebSocket</code> feed, for building and demonstrating a real-time UI with <strong>no backend</strong>. <code>MockWebSocket</code> presents the same surface as the browser's <code>WebSocket</code> &mdash; the same <code>readyState</code> and state constants, the same <code>onopen</code>, <code>onmessage</code>, <code>onclose</code> and <code>onerror</code>, <code>addEventListener</code>, <code>send</code> and <code>close</code> &mdash; so the code that reads it does not change when it is swapped for a real one. It fires an initial snapshot the moment it opens, then a stream of deltas on a timer, all from a generator you hand it. It is a dev and test utility: optional, imports nothing from the grid, and is never pulled into the core bundle. It pairs naturally with the data router (one mock stream, partitioned to many grids), but depends on it no more than a real socket does.</p>
     <pre><code>import { MockWebSocket, opsFeed } from '@toclocoinc/lattice-grid/modules/mock-socket';
@@ -6925,6 +6987,8 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
           <tr><td class="name">kind</td><td class="type">'ses' | 'holt'</td><td class="desc">For the exponential method, single smoothing (`ses`) or Holt's level+trend (`holt`). <small>(optional)</small></td></tr>
           <tr><td class="name">alpha</td><td class="type">number</td><td class="desc">For the exponential method, the level factor in `[0, 1]`; omit to fit it. <small>(optional)</small></td></tr>
           <tr><td class="name">beta</td><td class="type">number</td><td class="desc">For Holt's exponential smoothing, the trend factor in `[0, 1]`; omit to fit it. <small>(optional)</small></td></tr>
+          <tr><td class="name">band</td><td class="type">boolean | 'prediction' | 'confidence'</td><td class="desc">The uncertainty band shaded around a linear `forecast` (BACKLOG-0000975). The Student-t `prediction` band (a future observation) by default; `confidence` shades the narrower mean-response band; `false` opts out and leaves the bare dashed line. Ignored where there is no linear forecast to put a band on. <small>(optional)</small></td></tr>
+          <tr><td class="name">confidence</td><td class="type">number</td><td class="desc">The forecast band's confidence level in `(0, 1)`; 0.95 by default. <small>(optional)</small></td></tr>
           <tr><td class="name">label</td><td class="type">boolean</td><td class="desc">`false` suppresses the R² label on a linear trend. <small>(optional)</small></td></tr>
         </tbody>
       </table>
@@ -7222,7 +7286,7 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
           <tr><td class="name">show</td><td class="type">(ids: string | string[]): void</td><td class="desc"></td></tr>
           <tr><td class="name">hide</td><td class="type">(ids: string | string[]): void</td><td class="desc"></td></tr>
           <tr><td class="name">move</td><td class="type">(id: string, to: number): void</td><td class="desc"></td></tr>
-          <tr><td class="name">groupColumns</td><td class="type">(ids: string | string[], opts?: { title?: string; at?: number; groupId?: string }): string | null</td><td class="desc">Wrap leaf columns in a banded header, or add them to an existing band (BACKLOG-0000739). Header banding, not row grouping (see {@link group}); the band is a {@link ColumnGroup} node so a drag-, keyboard- or config-built band is the same tree, and it round-trips through a saved view. Emits `columngroup:changed`.</td></tr>
+          <tr><td class="name">groupColumns</td><td class="type">(ids: string | string[], opts?: { title?: string; at?: number; groupId?: string; id?: string }): string | null</td><td class="desc">Wrap leaf columns in a banded header, or add them to an existing band (BACKLOG-0000739). Header banding, not row grouping (see {@link group}); the band is a {@link ColumnGroup} node so a drag-, keyboard- or config-built band is the same tree, and it round-trips through a saved view. Emits `columngroup:changed`. Pass `groupId` to add to the band already carrying that id, or `id` (BACKLOG-0000985) to create a new band with a caller-chosen stable id you can reference later; `groupId` wins if both are given and an `id` already in use warns and no-ops.</td></tr>
           <tr><td class="name">ungroupColumn</td><td class="type">(id: string): void</td><td class="desc">Take a leaf out of its band; a band emptied by the move is dissolved.</td></tr>
           <tr><td class="name">renameGroup</td><td class="type">(groupId: string, title: string): void</td><td class="desc">Rename a banded header.</td></tr>
           <tr><td class="name">dissolveGroup</td><td class="type">(groupId: string): void</td><td class="desc">Dissolve a band, returning its columns to the enclosing level in place.</td></tr>

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.46.1</p>
+    <p class="rail__sub">Developer guide · v1.47.0</p>
     <nav>
       <div class="rail__group">
         <span class="rail__label">Start here</span>
@@ -2482,7 +2482,10 @@ grid.setPinnedRows([], { edge: 'top' });        <span class="cmt">// clear</span
     </p>
     <div class="why">
       <p><strong>The API.</strong> <code>groupColumns(ids, { title, groupId })</code> wraps columns
-      in a new band or adds them to an existing one; <code>ungroupColumn(id)</code> takes a column
+      in a new band or adds them to an existing one; pass <code>id</code> instead of
+      <code>groupId</code> to create a new band with a caller-chosen, stable id you can address
+      later (<code>groupColumns(ids, { title: 'Traffic', id: 'g-traffic' })</code>).
+      <code>ungroupColumn(id)</code> takes a column
       out (dissolving a band it empties); <code>renameGroup(id, title)</code>,
       <code>dissolveGroup(id)</code> and <code>moveGroup(id, to)</code> do the rest. Each emits
       <code>columngroup:changed</code>. A band's columns are always contiguous, and a nested band