@toclocoinc/lattice-grid 1.29.0 → 1.31.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.29.0 · [latticegrid.dev](https://www.latticegrid.dev) · TOCLOCO Inc
+Version 1.31.0 · [latticegrid.dev](https://www.latticegrid.dev) · TOCLOCO Inc
 
 ---
 

package/docs/API.html

@@ -1673,6 +1673,29 @@ grid.presentation.stop();                        <span class="cmt">// or Esc</sp
     </div>
     <p>Enlargement is a CSS scale factor multiplied into the same tokens <a href="#config">density</a> uses, so text, rows, padding and controls grow together rather than the grid being zoomed as an image. Font size is damped against it: type that scaled linearly with a 2× row height reads as shouting.</p>
 
+    <h2 id="annotate">grid.annotate</h2>
+    <p>The drawing layer over the grid: pixels on a transparent canvas, never data. A presenter picks a tool (<code>pen</code>, <code>arrow</code>, <code>rect</code>, <code>highlight</code>) and draws; the layer is inert until one is chosen, so scrolling and selection pass straight through otherwise. Marks are stored in <strong>content coordinates</strong>, so a circle drawn round a cell stays on that cell as the grid scrolls and resizes rather than hanging over the viewport.</p>
+    <p>Marks can also be <strong>seeded and added without drawing</strong> (BACKLOG-0000813), which is what lets a host ship a pre-drawn callout or restore one from storage. A mark descriptor is <code>{ type, points, colour? }</code> — <code>type</code> is <code>freehand</code>, <code>arrow</code>, <code>rect</code>, <code>highlight</code> or <code>text</code> (<code>pen</code> is accepted as an alias for <code>freehand</code>); <code>points</code> are <code>{x, y}</code> in content coordinates (a trail for freehand, the two endpoints for an arrow or rectangle, a single anchor for text). Seeded and added marks are <em>durable</em>: they survive a presentation ending, unlike a live-drawn mark, and they round-trip through <code>getState</code> and a saved view.</p>
+    <p>A <code>text</code> mark (BACKLOG-0000875) is a label anchored at one content point, carrying its <code>text</code> string and a basic style: <code>colour</code>, an optional <code>fontSize</code> in content pixels (default 14, scaled with a presentation), and an optional <code>background</code> colour drawn behind it. Like every mark it is held in content coordinates, so the label tracks the cell it annotates through scroll and resize.</p>
+    <pre><code><span class="cmt">// Seed a mark at construction — rendered on first paint, the way redaction seeds.</span>
+createGrid(el, {
+  columns, rows,
+  annotate: true,
+  state: { annotations: [
+    { type: 'arrow', points: [{ x: 40, y: 120 }, { x: 220, y: 80 }], colour: '#e0245e' },
+    { type: 'text', text: 'Q3 spike', points: [{ x: 232, y: 72 }], colour: '#1a6bc7', background: '#fffbe6' },
+  ] },
+});
+
+<span class="cmt">// Or add one durably at runtime — no synthesised pointer input.</span>
+grid.annotate.add({ type: 'rect', points: [{ x: 40, y: 100 }, { x: 260, y: 160 }] });
+grid.annotate.add({ type: 'text', text: 'review', points: [{ x: 48, y: 108 }], fontSize: 16 });
+
+<span class="cmt">// Persist and restore: seeded and added marks come back out of the state.</span>
+const marks = grid.getState().annotations;   <span class="cmt">// [{ type, points, colour }, …]</span>
+grid.state.apply({ annotations: marks });     <span class="cmt">// re-seed a fresh grid</span></code></pre>
+    <div class="note"><p><code>annotate.add</code> adds to the model and paints — it never synthesises pointer events, so a mark is exactly what the descriptor says. <code>undo()</code> removes the most recent mark and <code>clear()</code> removes them all, as before; <code>annotation:changed</code> still fires on every change. A presentation ending clears the presenter's live-drawn marks but keeps the durable ones, which are view state a host means to persist.</p></div>
+
     <h2 id="redaction">grid.redaction</h2>
     <p>Obscures a column's values on screen while leaving the shape of the data (row count, sort, filters, layout) perfectly readable. Built for presenting and screen sharing. Right-click a column heading for <strong>Redact column</strong>.</p>
     <p><strong>This is not a security control.</strong> The values stay in the model, the DOM, the clipboard and every export; anyone with the page can read them from devtools or by turning off one CSS rule. It defeats a camera, which is the whole claim. For a value that must not reach the browser at all, use <a href="#permissions">permissions</a> with <code>writeOnly</code>.</p>
@@ -2043,6 +2066,115 @@ createGrid(el, {
   grid.rows.value('r3', 'med'),          <span class="cmt">// median of 2,4,5 = 4</span>
 ].join('|');</code></pre>
 
+    <h3 id="seasonal-decomposition">Seasonal decomposition</h3>
+    <p>Splitting a series into <strong>trend + seasonal + residual</strong> (BACKLOG-0000873) answers "what's the underlying trend with the weekly pattern removed?". It is classical decomposition — the same algorithm <code>statsmodels.seasonal_decompose</code> uses, verified against it in the reference suite — delivered as four shadow columns over the same ordered pass: <code>tsTrend</code> (a centred moving average), <code>tsSeasonal</code> (the repeating index), <code>tsResidual</code> (what the two leave behind), and <code>tsCoverage</code>.</p>
+    <p>The <code>period</code> is <strong>caller-declared and required</strong> — 7 for a weekly cycle in daily data, 12 for a monthly cycle in monthly data; there is no auto-detection in v1. The model is <code>additive</code> by default; <code>decomposition: 'multiplicative'</code> is a declared option that is undefined on a non-positive series (those rows report null, with a warning). The centred window runs off the ends, so the leading and trailing rows have no trend — they are <em>partial edges</em>, reported as null and stamped <code>tsCoverage: 0</code> rather than emitted as if full.</p>
+    <pre><code>columns: [
+  { field: 'day',  type: 'date' },
+  { field: 'sales', type: 'number' },
+  { id: 'trend',  title: 'Trend',    shadow: { kind: 'tsTrend',    of: 'sales', orderBy: 'day', period: 7 } },
+  { id: 'season', title: 'Weekly',   shadow: { kind: 'tsSeasonal', of: 'sales', orderBy: 'day', period: 7 } },
+  { id: 'resid',  title: 'Residual', shadow: { kind: 'tsResidual', of: 'sales', orderBy: 'day', period: 7 } },
+  { id: 'cover',  title: 'Coverage', shadow: { kind: 'tsCoverage', of: 'sales', orderBy: 'day', period: 7 } },
+]</code></pre>
+    <pre data-run="js" data-expect="14|2|0|1|null|0" data-covers="export:createHeadlessGrid"><code><span class="kw">const</span> { createHeadlessGrid } = <span class="kw">await</span> import('../packages/core/src/index.js');
+<span class="cmt">// A period-4 series: trend 10+i plus a season [2,-1,0,-1], so value = trend + season.</span>
+<span class="kw">const</span> season = [2, -1, 0, -1];
+<span class="kw">const</span> base = { of: 'v', orderBy: 't', within: 'all', period: 4 };
+<span class="kw">const</span> grid = createHeadlessGrid({
+  columns: [
+    { field: 't', type: 'number' },
+    { field: 'v', type: 'number' },
+    { id: 'trend',  shadow: { kind: 'tsTrend', ...base } },
+    { id: 'season', shadow: { kind: 'tsSeasonal', ...base } },
+    { id: 'resid',  shadow: { kind: 'tsResidual', ...base } },
+    { id: 'cover',  shadow: { kind: 'tsCoverage', ...base } },
+  ],
+  rows: Array.from({ length: 8 }, (unused, i) => ({ id: String(i), t: i, v: (10 + i) + season[i % 4] })),
+  rowKey: 'id',
+});
+<span class="kw">return</span> [
+  grid.rows.value('4', 'trend'),   <span class="cmt">// centred MA recovers the trend: 14</span>
+  grid.rows.value('4', 'season'),  <span class="cmt">// the phase-0 seasonal index: 2</span>
+  grid.rows.value('4', 'resid'),   <span class="cmt">// nothing left over: 0</span>
+  grid.rows.value('4', 'cover'),   <span class="cmt">// interior row: full, 1</span>
+  grid.rows.value('0', 'trend') === null ? 'null' : 'x',  <span class="cmt">// partial edge: null, not invented</span>
+  grid.rows.value('0', 'cover'),   <span class="cmt">// edge stamped partial: 0</span>
+].join('|');</code></pre>
+
+    <h3 id="exponential-smoothing">Exponential smoothing</h3>
+    <p>Smoothing pulls the signal out of a noisy series (BACKLOG-0000873). <code>tsSmoothed</code> is the fitted <strong>level</strong> — not a forecast of the future — from single exponential smoothing (<code>smoothing: 'ses'</code>, the default) or Holt's level+trend (<code>smoothing: 'holt'</code>). The recursion matches statsmodels and is verified against it in the reference suite. Holt-Winters (seasonal) smoothing is deferred; seasonality is covered by decomposition above.</p>
+    <p>The smoothing factor is either <strong>caller-set</strong> (<code>alpha</code>, and <code>beta</code> for Holt) or <strong>fit by minimising the in-sample SSE</strong> when omitted — and the chosen value is reported, not hidden, by the <code>tsSmoothingAlpha</code> / <code>tsSmoothingBeta</code> companion columns.</p>
+    <pre><code>columns: [
+  { field: 'day',   type: 'date' },
+  { field: 'sales', type: 'number' },
+  { id: 'level', title: 'Smoothed', shadow: { kind: 'tsSmoothed',       of: 'sales', orderBy: 'day', smoothing: 'holt' } },
+  { id: 'a',     title: 'α',        shadow: { kind: 'tsSmoothingAlpha', of: 'sales', orderBy: 'day', smoothing: 'holt' } },
+  { id: 'b',     title: 'β',        shadow: { kind: 'tsSmoothingBeta',  of: 'sales', orderBy: 'day', smoothing: 'holt' } },
+]</code></pre>
+    <pre data-run="js" data-expect="6|8|0.5" data-covers="export:createHeadlessGrid"><code><span class="kw">const</span> { createHeadlessGrid } = <span class="kw">await</span> import('../packages/core/src/index.js');
+<span class="cmt">// SES at alpha 0.5 over 4,8,6,10: level runs 4, 6, 6, 8.</span>
+<span class="kw">const</span> base = { of: 'v', orderBy: 't', within: 'all', smoothing: 'ses', alpha: 0.5 };
+<span class="kw">const</span> grid = createHeadlessGrid({
+  columns: [
+    { field: 't', type: 'number' },
+    { field: 'v', type: 'number' },
+    { id: 'sm', shadow: { kind: 'tsSmoothed', ...base } },
+    { id: 'a',  shadow: { kind: 'tsSmoothingAlpha', ...base } },
+  ],
+  rows: [4, 8, 6, 10].map((v, i) => ({ id: String(i), t: i, v })),
+  rowKey: 'id',
+});
+<span class="kw">return</span> [
+  grid.rows.value('1', 'sm'),   <span class="cmt">// 0.5*8 + 0.5*4 = 6</span>
+  grid.rows.value('3', 'sm'),   <span class="cmt">// 0.5*10 + 0.5*6 = 8</span>
+  grid.rows.value('0', 'a'),    <span class="cmt">// the factor used, reported: 0.5</span>
+].join('|');</code></pre>
+
+    <h3 id="stationarity">Stationarity (ADF)</h3>
+    <p>Before you compare two series or detrend one, it helps to know whether it is <strong>stationary</strong> — reverting to a level or trend — or wandering with a unit root. <code>grid.statistics.adf</code> runs the Augmented Dickey-Fuller test (BACKLOG-0000873) and returns a scalar readout, not a per-row column: the statistic, the augmenting lag chosen by AIC, MacKinnon's critical values, an interpolated p-value (stamped approximate), and a plain-language verdict at the 5% level. The constant+trend regression and the AIC lag choice match statsmodels' <code>adfuller</code>, against which the statistic and lag are verified.</p>
+    <pre data-run="js" data-expect="non-stationary|0" data-covers="method:statistics"><code><span class="kw">const</span> { createHeadlessGrid } = <span class="kw">await</span> import('../packages/core/src/index.js');
+<span class="cmt">// A random walk (a unit root): it wanders rather than reverting.</span>
+<span class="kw">const</span> walk = [0.138, -0.725, -1.26, -0.536, -0.267, 0.167, -0.765, -0.146, -0.311, -0.586,
+  0.376, -0.41, 0.282, 0.865, -0.024, 0.149, -0.2, -0.654, -1.338, -1.917, -1.832, -1.333,
+  -0.492, -1.259, -1.89, -2.145, -2.146, -1.297, -1.26, -0.716, -0.846, -1.206, -2.126,
+  -1.724, -0.945, -1.599, -1.316, -0.413, 0.304, 0.732, -0.257, 0.086, -0.572, -0.501,
+  -1.153, -1.186, -1.455, -1.607];
+<span class="kw">const</span> grid = createHeadlessGrid({
+  columns: [{ field: 't', type: 'number' }, { field: 'v', type: 'number' }],
+  rows: walk.map((v, i) => ({ id: String(i), t: i, v })),
+  rowKey: 'id',
+});
+<span class="kw">const</span> adf = grid.statistics.adf({ of: 'v', orderBy: 't' });
+<span class="kw">return</span> [adf.verdict, adf.usedLag].join('|');   <span class="cmt">// non-stationary, 0 lags</span></code></pre>
+
+    <h3 id="autocorrelation">Autocorrelation (ACF / PACF)</h3>
+    <p><code>grid.statistics.acf</code> shows how far back a series depends on itself (BACKLOG-0000873): the autocorrelation (ACF) and partial autocorrelation (PACF) arrays out to a maximum lag, each with the approximate <code>±1.96/√n</code> white-noise band (stamped approximate) — a lag whose bar clears the band is evidence of real dependence. The estimators are the biased ACF and the Yule-Walker (Levinson-Durbin) PACF, matching statsmodels, verified in the reference suite. <strong>Lag 1 is the single source of truth</strong>: <code>acf[1]</code> is the same number <code>statistics.series(...).autocorrelation</code> reports, and <code>pacf[1] === acf[1]</code>.</p>
+    <p>The correlogram is the arrays fed to a bar chart over <a href="#seasonal-decomposition">explicit points</a>, with the band as reference lines — reusing the existing chart primitives:</p>
+    <pre><code>const { acf, bounds } = grid.statistics.acf({ of: 'sales', orderBy: 'day', maxlag: 20 });
+createChart({
+  grid, container: '#acf', type: 'bar',
+  points: acf.map((v, lag) =&gt; ({ x: lag, y: v })),
+  reference: [{ value: bounds.upper }, { value: bounds.lower }, { value: 0 }],
+});</code></pre>
+    <pre data-run="js" data-expect="1|true|true" data-covers="method:statistics"><code><span class="kw">const</span> { createHeadlessGrid } = <span class="kw">await</span> import('../packages/core/src/index.js');
+<span class="cmt">// A deterministic AR(1): each reading leans 0.6 on the one before.</span>
+<span class="kw">let</span> s = 5; <span class="kw">const</span> rand = () =&gt; { s = (Math.imul(s, 1664525) + 1013904223) &gt;&gt;&gt; 0; return s / 4294967296 - 0.5; };
+<span class="kw">const</span> y = []; <span class="kw">let</span> prev = 0;
+<span class="kw">for</span> (<span class="kw">let</span> i = 0; i &lt; 200; i++) { const v = 0.6 * prev + rand(); y.push(v); prev = v; }
+<span class="kw">const</span> grid = createHeadlessGrid({
+  columns: [{ field: 't', type: 'number' }, { field: 'v', type: 'number' }],
+  rows: y.map((v, i) =&gt; ({ id: String(i), t: i, v })),
+  rowKey: 'id',
+});
+<span class="kw">const</span> res = grid.statistics.acf({ of: 'v', orderBy: 't', maxlag: 6 });
+<span class="kw">const</span> series = grid.statistics.series('v', { by: 't' });
+<span class="kw">return</span> [
+  res.acf[0],                                    <span class="cmt">// lag 0 is always 1</span>
+  res.pacf[1] === res.acf[1],                    <span class="cmt">// the first partial equals the first acf</span>
+  Math.abs(res.acf[1] - series.autocorrelation) &lt; 1e-9,  <span class="cmt">// lag 1 is the single source of truth</span>
+].join('|');</code></pre>
+
     <h2 id="highlight">grid.highlight</h2>
     <p>One mechanism for two jobs: the flash a changed cell makes, and a marker you paint deliberately. A target is a cell (<code>{key, colId}</code>), a row (<code>{key}</code>, or a bare row key) or a column (<code>{colId}</code>). Cell beats row beats column, so a specific highlight is never hidden by a broad one laid over it.</p>
     <pre><code>createGrid(el, {
@@ -3483,6 +3615,7 @@ off();                                       <span class="cmt">// on() returns i
           <tr><td class="name">timeline:detached</td><td class="desc">The brush was removed.</td></tr>
           <tr><td class="name">timeline:seek</td><td class="desc">The brush settled on a range.</td></tr>
           <tr><td class="name">timeline:seeking</td><td class="desc">The brush is being dragged. Throttled.</td></tr>
+          <tr><td class="name">annotation:changed</td><td class="type">{ tool, count }</td><td class="desc">A drawing annotation was added, edited or cleared. Carries the active <code>tool</code> and the <code>count</code> of marks. A first-class event, so <code>grid.on('annotation:changed', ...)</code> and the framework adapters' <code>onAnnotationChanged</code> reach it directly rather than through the <code>'*'</code> wildcard.</td></tr>
           <tr><td class="name">presentation:started</td><td class="desc">Presentation mode began. Carries the scale, options, views and starting index. <code>presentation:changed</code> covers a later change to the same options, so a listener can tell entry from adjustment.</td></tr>
           <tr><td class="name">presentation:changed</td><td class="desc">The options of a running presentation changed.</td></tr>
           <tr><td class="name">presentation:ended</td><td class="desc">Presentation mode ended. Annotations are cleared here.</td></tr>
@@ -3511,6 +3644,33 @@ off();                                       <span class="cmt">// on() returns i
 
     <div class="note"><p>This list is complete, and stays complete: <code>tools/check.js</code> compares every <code>emit()</code> in the grid against the declared event names and fails the build on a mismatch. A chart raises its own events, which belong to the charts module rather than to this bus.</p></div>
 
+    <h3 id="event-known-example">A declared event is reachable directly, executed</h3>
+    <p class="section-note">Every name in the table above is a first-class event: <code>grid.on(name, ...)</code>
+    binds it without the unknown-name warning, and each maps to a framework handler prop. Shown for
+    <code>annotation:changed</code>, which BACKLOG-876 promoted from a wildcard-only emission to a
+    declared event. Run headless on every build.</p>
+    <pre data-run="js" data-expect="true | 0 | onAnnotationChanged" data-covers="event:annotation:changed"><code><span class="kw">const</span> { createHeadlessGrid } = <span class="kw">await</span> import('../packages/core/src/index.js');
+<span class="kw">const</span> { isKnownEvent } = <span class="kw">await</span> import('../packages/core/src/events/index.js');
+<span class="kw">const</span> { handlerName } = <span class="kw">await</span> import('../packages/modules/shared/adapter.js');
+
+<span class="kw">const</span> grid = createHeadlessGrid({ columns: [{ field: 'a' }], rows: [] });
+
+<span class="cmt">// Binding a declared event does not trip the unknown-name warning that an</span>
+<span class="cmt">// undeclared one would — that warning is exactly what BACKLOG-876 removed.</span>
+<span class="kw">const</span> warnings = [];
+<span class="kw">const</span> original = console.warn;
+console.warn = (...a) =&gt; warnings.push(a.join(' '));
+<span class="kw">const</span> off = grid.on('annotation:changed', () =&gt; {});
+console.warn = original;
+off();
+grid.destroy();
+
+<span class="kw">return</span> [
+  isKnownEvent('annotation:changed'),   <span class="cmt">// declared at on() time</span>
+  warnings.length,                      <span class="cmt">// 0: no unknown-event warning</span>
+  handlerName('annotation:changed'),    <span class="cmt">// the adapter prop the frameworks expose</span>
+].join(' | ');</code></pre>
+
     <h2 id="rules">Conditional formatting</h2>
     <p>Rules compile into the function <code>cell.style</code> already takes, so a compiled rule set
     installs exactly like a hand-written style function.</p>
@@ -3752,7 +3912,7 @@ const chart = createChart({
           <tr><td class="name">type</td><td class="type">string</td><td class="desc">One of the thirty above.</td></tr>
           <tr><td class="name">x / y</td><td class="type">string</td><td class="desc">Category and measure columns.</td></tr>
           <tr><td class="name">series</td><td class="type">string</td><td class="desc">Splits the measure into one series per distinct value.</td></tr>
-          <tr><td class="name">measures</td><td class="type">object[]</td><td class="desc"><code>{col, fn, type, axis}</code>: several measures at once, each reduced by any totals kernel.</td></tr>
+          <tr><td class="name">measures</td><td class="type">object[]</td><td class="desc"><code>{col, fn, type, axis}</code>: several measures at once, each reduced by an aggregation. <code>fn</code> is one of <code>sum</code>, <code>avg</code> (alias <code>mean</code>), <code>min</code>, <code>max</code>, <code>count</code>, <code>countValues</code>, <code>first</code>, <code>last</code>; it defaults to <code>sum</code>. An <code>fn</code> that is none of these is a mistake, not a silent <code>sum</code>: it warns once, naming the value and the supported set, and falls back to <code>sum</code> so the chart still draws.</td></tr>
           <tr><td class="name">title</td><td class="type">string</td><td class="desc">Drawn above the plot.</td></tr>
           <tr><td class="name">scheme</td><td class="type">string | string[]</td><td class="desc">A named scheme or your own colours. <code>schemeNames()</code> lists the built-in ones, including a colour-blind-safe palette.</td></tr>
           <tr><td class="name">legend</td><td class="type">boolean | object</td><td class="desc"><code>position</code>, and <code>isolate</code> so a click shows only that series, which is what a reader with eight series wants, and what plain toggling makes them do in seven clicks.</td></tr>
@@ -3933,6 +4093,114 @@ createGrid(el, {
 
     <div class="note"><p>The module imports nothing from the grid: <code>createChart</code> is handed a grid rather than importing one. That is what keeps the charts bundle to the drawing, and it is why the grid must be created first, and why a chart cannot outlive it.</p></div>
 
+    <h2 id="datarouter">The data router</h2>
+    <p><code>modules/data-router</code> is a host-layer demultiplexer: it takes <strong>one</strong> arriving stream or dataset, splits it by what each record <em>is</em>, and routes each partition to its own grid &mdash; or to a headless grid driving a chart. One round-trip, or one live feed, hydrates a whole screen of grids that each see only their slice. It is optional, imports nothing from the grid, and adds no core hook: every grid is driven through the <strong>public</strong> incremental path, <code>grid.rows.apply({ add, update, remove })</code>.</p>
+    <pre><code>import { createDataRouter } from '@toclocoinc/lattice-grid/modules/data-router';
+
+const router = createDataRouter({
+  key: 'entityType',          <span class="cmt">// partition: a property, or fn(row) =&gt; value</span>
+  rowKey: 'id',               <span class="cmt">// identity within a grid: a property, or fn(row)</span>
+  overlap: false,             <span class="cmt">// default: first matching route wins</span>
+  onUnrouted: (item) =&gt; {},   <span class="cmt">// optional sink for records that match no route</span>
+});
+
+router.attach(ordersGrid, 'order');            <span class="cmt">// a property value...</span>
+router.attach(bigGrid, (row) =&gt; row.amt &gt; 1e6); <span class="cmt">// ...or a composite predicate</span>
+router.attach(headlessGrid, 'metric', { rowKey: 'ts' }); <span class="cmt">// per-attach rowKey override; feeds a chart</span>
+router.attachDefault(restGrid);                <span class="cmt">// the "rest" sink: nothing is dropped</span>
+
+const counts = router.load(snapshot);          <span class="cmt">// keyed diff per grid: [{added,updated,removed}, ...]</span>
+router.apply([{ op: 'upsert', row }, { op: 'delete', row }]); <span class="cmt">// in-place deltas by rowKey</span></code></pre>
+    <p><strong>A snapshot is a keyed diff, not a replace.</strong> <code>load</code> re-partitions the whole dataset and, per grid, adds the new rows, updates only the changed ones and removes the gone ones &mdash; so an unchanged row never repaints and selection, scroll and edit state survive. <strong>Deltas are applied in place</strong> by <code>rowKey</code>, last-writer-wins within a batch; an <code>upsert</code> whose partition property has changed <em>moves</em> the row (it leaves the route it no longer matches and joins the one it now does, never duplicated). A record matching no route is counted in <code>router.unrouted</code>, handed to <code>onUnrouted</code>, and &mdash; if an <code>attachDefault</code> grid exists &mdash; routed there, so nothing is ever silently lost. By default a record goes to the first route it matches; <code>overlap: true</code> fans it to every matching route.</p>
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Member</th><th>Description</th></tr></thead>
+        <tbody>
+          <tr><td class="sig">createDataRouter({ key, rowKey?, overlap?, onUnrouted? })</td><td class="desc">Create a router. <code>key</code> is the partition (property or <code>fn(row)</code>); <code>rowKey</code> the default identity within a grid; <code>overlap</code> fans a record to all matching routes; <code>onUnrouted</code> is a sink for unmatched records.</td></tr>
+          <tr><td class="sig">attach(grid, predicate, { rowKey? })</td><td class="desc">Route to <code>grid</code> when <code>predicate</code> matches: a value compared to <code>key</code>, or a <code>fn(row) =&gt; boolean</code>. <code>rowKey</code> overrides the router default for this grid.</td></tr>
+          <tr><td class="sig">attachDefault(grid, { rowKey? })</td><td class="desc">The "rest" sink: the grid that receives every record no explicit route matched.</td></tr>
+          <tr><td class="sig">load(snapshot)</td><td class="desc">Apply a full snapshot as a keyed diff per grid. Returns per-route <code>{ added, updated, removed }</code> counts in attach order.</td></tr>
+          <tr><td class="sig">apply(deltas)</td><td class="desc">Apply <code>{ op: 'upsert' | 'delete', row }</code> deltas in place by <code>rowKey</code>.</td></tr>
+          <tr><td class="sig">unrouted</td><td class="desc">How many records matched no route (reset by <code>load</code>, running for deltas).</td></tr>
+          <tr><td class="sig">link(source, target, relation)</td><td class="desc"><strong>v2:</strong> make a selection in <code>source</code> filter what <code>target</code> receives. <code>relation</code> is a key map <code>{ from, to }</code> (target rows whose <code>to</code> value is among the selected source rows' <code>from</code> values &mdash; multi-select is an IN set, ANY match) or a function <code>fn(selectedSourceRows) =&gt; (row) =&gt; boolean</code>. No selection shows the full partition; changes are debounced.</td></tr>
+          <tr><td class="sig">flush()</td><td class="desc"><strong>v2:</strong> apply any debounced selection refilter now, for a deterministic point (and for tests).</td></tr>
+          <tr><td class="sig">detach(grid)</td><td class="desc">Stop routing to a grid and forget its slice; drop any link 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 and subscription. <strong>Detaches only</strong> &mdash; the host owns and destroys its grids.</td></tr>
+        </tbody>
+      </table>
+    </div>
+    <p>The router keeps a small <code>Map&lt;rowKey, row&gt;</code> per route to compute the snapshot diff. That is deliberate for v1; a future optimisation could diff against the grid's own key index rather than a shadow copy. Ordering and dedupe across a live feed are the host's to guarantee &mdash; a caller that must drop stale out-of-order deltas can carry its own version or sequence field and filter before <code>apply</code>; v1 imposes no version scheme.</p>
+    <p><strong>Cross-grid selection filtering (v2, BACKLOG-0000880).</strong> <code>link</code> keeps each target's <em>full partition</em> separate from what it currently shows: when the source's selection changes, the router recomputes the shown subset from the relation and re-pushes it through the same keyed-diff path, so the target grid stays dumb &mdash; it only ever receives rows, never a query or a reference to the source. Selection <em>in</em> the target survives an unrelated refilter, because the keyed path preserves it. No selection (or one the router cannot resolve to routed rows) shows the full partition, and deselecting restores it. The source grid must have selection enabled; still no grid-core change. Debounce is controlled by <code>selectionDebounce</code> (default 16&nbsp;ms; <code>0</code> is synchronous), and <code>flush()</code> forces it.</p>
+    <h3 id="datarouter-v2-example">Cross-grid selection filtering, executed</h3>
+    <p class="section-note">A customers grid and an orders grid off one feed; selecting customers filters the orders
+    grid to their regions through the keyed-diff path, and deselecting restores the full set. Run headless
+    on every build.</p>
+    <pre data-run="js" data-expect="3 | 2 | 3 | 3" data-covers="export:createDataRouter"><code><span class="kw">const</span> { createHeadlessGrid } = <span class="kw">await</span> import('../packages/core/src/index.js');
+<span class="kw">const</span> { createDataRouter } = <span class="kw">await</span> import('../packages/modules/data-router/index.js');
+
+<span class="kw">const</span> cols = [{ id: 'id', field: 'id' }, { id: 'type', field: 'type' }, { id: 'region', field: 'region', type: 'text' }];
+<span class="kw">const</span> customers = createHeadlessGrid({ rowKey: 'id', columns: cols, selection: 'multiple' });
+<span class="kw">const</span> orders = createHeadlessGrid({ rowKey: 'id', columns: cols });
+
+<span class="cmt">// debounce 0 so a selection refilters synchronously in this example.</span>
+<span class="kw">const</span> router = createDataRouter({ key: 'type', rowKey: 'id', selectionDebounce: 0 });
+router.attach(customers, 'customer');
+router.attach(orders, 'order');
+router.load([
+  { id: 'c1', type: 'customer', region: 'emea' },
+  { id: 'c2', type: 'customer', region: 'amer' },
+  { id: 'o1', type: 'order', region: 'emea' },
+  { id: 'o2', type: 'order', region: 'amer' },
+  { id: 'o3', type: 'order', region: 'emea' },
+]);
+<span class="cmt">// A selection in customers filters the orders grid by region.</span>
+router.link(customers, orders, { from: 'region', to: 'region' });
+
+<span class="kw">const</span> full = orders.rows.count();          <span class="cmt">// 3: no selection, full partition</span>
+customers.selection.set(['c1']);            <span class="cmt">// emea</span>
+<span class="kw">const</span> oneRegion = orders.rows.count();     <span class="cmt">// 2: o1, o3</span>
+customers.selection.set(['c1', 'c2']);      <span class="cmt">// emea + amer (IN set)</span>
+<span class="kw">const</span> both = orders.rows.count();          <span class="cmt">// 3</span>
+customers.selection.set([]);                <span class="cmt">// deselect restores</span>
+<span class="kw">const</span> restored = orders.rows.count();      <span class="cmt">// 3</span>
+
+customers.destroy(); orders.destroy(); router.destroy();
+<span class="kw">return</span> [full, oneRegion, both, restored].join(' | ');</code></pre>
+    <h3 id="datarouter-example">One feed, three grids, executed</h3>
+    <p class="section-note">A single snapshot fanned to an orders grid, an invoices grid and a "rest" sink, then a
+    delta that changes a row's partition &mdash; proving the fan-out, the sink, and that a moved row
+    leaves its old grid and joins the new one rather than being duplicated. Run headless on every build.</p>
+    <pre data-run="js" data-expect="2,1,1 | 1/2 | 0" data-covers="export:createDataRouter"><code><span class="kw">const</span> { createHeadlessGrid } = <span class="kw">await</span> import('../packages/core/src/index.js');
+<span class="kw">const</span> { createDataRouter } = <span class="kw">await</span> import('../packages/modules/data-router/index.js');
+
+<span class="kw">const</span> cols = [{ id: 'id', field: 'id' }, { id: 'type', field: 'type' }, { id: 'amt', field: 'amt', type: 'number' }];
+<span class="kw">const</span> orders = createHeadlessGrid({ rowKey: 'id', columns: cols });
+<span class="kw">const</span> invoices = createHeadlessGrid({ rowKey: 'id', columns: cols });
+<span class="kw">const</span> rest = createHeadlessGrid({ rowKey: 'id', columns: cols });
+
+<span class="cmt">// One router keyed on `type`; each grid sees only its slice, the "rest" sink</span>
+<span class="cmt">// catches anything that matches no explicit route.</span>
+<span class="kw">const</span> router = createDataRouter({ key: 'type', rowKey: 'id' });
+router.attach(orders, 'order');
+router.attach(invoices, 'invoice');
+router.attachDefault(rest);
+
+<span class="cmt">// One snapshot hydrates all three grids at once.</span>
+router.load([
+  { id: 'o1', type: 'order', amt: 10 },
+  { id: 'o2', type: 'order', amt: 20 },
+  { id: 'i1', type: 'invoice', amt: 99 },
+  { id: 'x1', type: 'ticket', amt: 1 },   <span class="cmt">// matches no route -&gt; the sink, not dropped</span>
+]);
+<span class="kw">const</span> fanned = [orders.rows.count(), invoices.rows.count(), rest.rows.count()].join(',');
+
+<span class="cmt">// o2's partition changes: it MOVES from orders to invoices, not duplicated.</span>
+router.apply([{ op: 'upsert', row: { id: 'o2', type: 'invoice', amt: 25 } }]);
+<span class="kw">const</span> moved = orders.rows.count() + '/' + invoices.rows.count();
+
+orders.destroy(); invoices.destroy(); rest.destroy(); router.destroy();
+<span class="kw">return</span> [fanned, moved, router.unrouted].join(' | ');</code></pre>
+
     <h2 id="charts">In-cell charts</h2>
     <p>Seven chart renderers for a cell. Each is a single SVG whose path data is the only thing a
     repaint writes, so they cost the same as any other cell as rows recycle.</p>
@@ -4482,7 +4750,7 @@ spans.addSpan('R0', 'name', 3, 2); <span class="cmt">// rowspan 3, colspan 2</sp
 
     <h3 id="module-exports-example">Every module export, executed</h3>
     <p class="section-note">Nine shipped modules, each export resolved against its own barrel on every build.</p>
-    <pre data-run="js" data-expect="61" data-covers="export:ContextMenu export:Messages export:Registry export:autoInit export:createGrid export:createLocalViewStorage export:createMessages export:createStat export:deltaOf export:gridElementsWithin export:hydrateTable export:mountPanel export:readTable export:toneOf export:Chart export:PALETTE export:SCHEMES export:TYPES export:createChart export:chartRange export:canChartRange export:deriveRangeSpec export:regressionPlots export:registerScheme export:resolveScheme export:schemeNames export:setDefaultScheme export:HTML_ROW_WARNING_THRESHOLD export:QUERY_CHANGED_EVENT export:SCROLL_NEAR_END_EVENT export:attach export:destroyWithin export:driveInfiniteScroll export:driveOobUpdates export:driveServerMode export:ingestResponse export:initWithin export:queryParams export:restoreStateWithin export:rowsFromFragment export:rowsFromJson export:saveStateWithin export:ATTRIBUTE_CONFIG export:EVENT_PREFIX export:GridElementController export:LatticeGrid export:TAG_NAME export:createLatticeGridElement export:defineLatticeGrid export:domEventName export:observedAttributeNames export:CONSOLE_ACTIVATION export:createDevtools export:expose export:EVENT_NAMES export:handlerName export:createLatticeGrid export:dashedName export:createLatticeAction export:Grid export:warnIfLargeHtmlPayload"><code><span class="cmt">// Every declared export of every shipped module, resolved against its own</span>
+    <pre data-run="js" data-expect="62" data-covers="export:ContextMenu export:Messages export:Registry export:autoInit export:createGrid export:createLocalViewStorage export:createMessages export:createStat export:deltaOf export:gridElementsWithin export:hydrateTable export:mountPanel export:readTable export:toneOf export:Chart export:PALETTE export:SCHEMES export:TYPES export:createChart export:chartRange export:canChartRange export:deriveRangeSpec export:regressionPlots export:registerScheme export:resolveScheme export:schemeNames export:setDefaultScheme export:HTML_ROW_WARNING_THRESHOLD export:QUERY_CHANGED_EVENT export:SCROLL_NEAR_END_EVENT export:attach export:destroyWithin export:driveInfiniteScroll export:driveOobUpdates export:driveServerMode export:ingestResponse export:initWithin export:queryParams export:restoreStateWithin export:rowsFromFragment export:rowsFromJson export:saveStateWithin export:ATTRIBUTE_CONFIG export:EVENT_PREFIX export:GridElementController export:LatticeGrid export:TAG_NAME export:createLatticeGridElement export:defineLatticeGrid export:domEventName export:observedAttributeNames export:CONSOLE_ACTIVATION export:createDevtools export:expose export:EVENT_NAMES export:handlerName export:createLatticeGrid export:dashedName export:createLatticeAction export:Grid export:warnIfLargeHtmlPayload export:createDataRouter"><code><span class="cmt">// Every declared export of every shipped module, resolved against its own</span>
 <span class="cmt">// barrel. A module that stopped exporting something fails here.</span>
 <span class="kw">const</span> modules = [
   [<span class="kw">await</span> import('../packages/dom/src/index.js'), [
@@ -4523,6 +4791,9 @@ spans.addSpan('R0', 'name', 3, 2); <span class="cmt">// rowspan 3, colspan 2</sp
   [<span class="kw">await</span> import('../packages/modules/dhtmlx-compat/index.js'), [
     'Grid',
   ]],
+  [<span class="kw">await</span> import('../packages/modules/data-router/index.js'), [
+    'createDataRouter',
+  ]],
 ];
 
 <span class="kw">let</span> present = 0;
@@ -4897,6 +5168,39 @@ return `methods ${ANOMALY_METHODS.length}; flagged ${z.flagged}; upper ${fence.u
 <!-- BEGIN GENERATED TYPE REFERENCE -->
     <h2 id="type-reference">Type reference</h2>
     <p class="section-note">Every interface the library declares, with the type of each member. The sections above describe how the grid is used; this one is the complete surface, generated from the type declarations so that it always matches the release.</p>
+    <h3 id="type-AcfResult">AcfResult</h3>
+    <p class="section-note">Autocorrelation (ACF) and partial autocorrelation (PACF) arrays (BACKLOG-0000873).</p>
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Member</th><th>Type</th><th>Description</th></tr></thead>
+        <tbody>
+          <tr><td class="name">acf</td><td class="type">number[]</td><td class="desc">The autocorrelation at each lag; index 0 is lag 0 and is always 1.</td></tr>
+          <tr><td class="name">pacf</td><td class="type">number[]</td><td class="desc">The partial autocorrelation at each lag; index 0 is 1, and `pacf[1] === acf[1]`.</td></tr>
+          <tr><td class="name">bounds</td><td class="type">{ upper: number; lower: number }</td><td class="desc">The approximate ±1.96/√n white-noise confidence band.</td></tr>
+          <tr><td class="name">n</td><td class="type">number</td><td class="desc">The series length the ACF/PACF were computed over.</td></tr>
+          <tr><td class="name">nlags</td><td class="type">number</td><td class="desc">The maximum lag.</td></tr>
+          <tr><td class="name">approximate</td><td class="type">boolean</td><td class="desc">Always true: the ±1.96/√n band is an approximation.</td></tr>
+        </tbody>
+      </table>
+    </div>
+    <h3 id="type-AdfResult">AdfResult</h3>
+    <p class="section-note">The Augmented Dickey-Fuller stationarity test result (BACKLOG-0000873).</p>
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Member</th><th>Type</th><th>Description</th></tr></thead>
+        <tbody>
+          <tr><td class="name">statistic</td><td class="type">number</td><td class="desc">The ADF t-statistic on the lagged level.</td></tr>
+          <tr><td class="name">usedLag</td><td class="type">number</td><td class="desc">The number of augmenting lags chosen by AIC.</td></tr>
+          <tr><td class="name">nobs</td><td class="type">number</td><td class="desc">The observations the final regression used.</td></tr>
+          <tr><td class="name">criticalValues</td><td class="type">{ '1%': number; '5%': number; '10%': number }</td><td class="desc">MacKinnon's constant+trend critical values at the 1%, 5% and 10% levels.</td></tr>
+          <tr><td class="name">pValue</td><td class="type">number</td><td class="desc">An approximate p-value, interpolated across the critical-value ladder.</td></tr>
+          <tr><td class="name">pApproximate</td><td class="type">boolean</td><td class="desc">Always true: the p-value is an interpolation, not the MacKinnon surface.</td></tr>
+          <tr><td class="name">stationary</td><td class="type">boolean</td><td class="desc">Whether the series is stationary at the 5% level.</td></tr>
+          <tr><td class="name">verdict</td><td class="type">string</td><td class="desc">The plain-language verdict: `'stationary'` or `'non-stationary'`.</td></tr>
+          <tr><td class="name">regression</td><td class="type">'ct'</td><td class="desc">The regression form used — always `'ct'` (constant + trend) in v1.</td></tr>
+        </tbody>
+      </table>
+    </div>
     <h3 id="type-AggregateProvenance">AggregateProvenance</h3>
     <p class="section-note">How one aggregate was routed, for `lastPlan()` provenance.</p>
     <div class="table-wrap">
@@ -4942,7 +5246,6 @@ return `methods ${ANOMALY_METHODS.length}; flagged ${z.flagged}; upper ${fence.u
       </table>
     </div>
     <h3 id="type-AnnotationApi">AnnotationApi</h3>
-    <p class="section-note">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.</p>
     <div class="table-wrap">
       <table>
         <thead><tr><th>Member</th><th>Type</th><th>Description</th></tr></thead>
@@ -4950,12 +5253,29 @@ return `methods ${ANOMALY_METHODS.length}; flagged ${z.flagged}; upper ${fence.u
           <tr><td class="name">tool</td><td class="type">'pen' | 'arrow' | 'rect' | 'highlight' | null</td><td class="desc"><small>(read-only)</small></td></tr>
           <tr><td class="name">count</td><td class="type">number</td><td class="desc"><small>(read-only)</small></td></tr>
           <tr><td class="name">use</td><td class="type">(tool: 'pen' | 'arrow' | 'rect' | 'highlight' | null, opts?: { colour?: string }): string | null</td><td class="desc"></td></tr>
+          <tr><td class="name">add</td><td class="type">(mark: AnnotationMark): number</td><td class="desc">Add a durable mark from a descriptor, without synthesising pointer input (BACKLOG-0000813). The mark is painted, survives a presentation ending, and round-trips through `getState`. Returns the mark count.</td></tr>
+          <tr><td class="name">list</td><td class="type">(): AnnotationMark[]</td><td class="desc">Every mark on the layer, as descriptors — the shape `getState` persists.</td></tr>
           <tr><td class="name">undo</td><td class="type">(): number</td><td class="desc"></td></tr>
           <tr><td class="name">clear</td><td class="type">(): void</td><td class="desc"></td></tr>
           <tr><td class="name">redraw</td><td class="type">(): void</td><td class="desc"></td></tr>
         </tbody>
       </table>
     </div>
+    <h3 id="type-AnnotationMark">AnnotationMark</h3>
+    <p class="section-note">A durable annotation mark descriptor (BACKLOG-0000813) — the shape a host seeds through `state.annotations`, adds through {@link AnnotationApi.add}, and reads back through {@link AnnotationApi.list} and `getState`. `points` are in **content coordinates** (the same space user-drawn marks are stored in), so a mark tracks scroll and resize rather than hanging over the viewport. A `freehand` mark is a trail of points; `arrow` and `rect` are their two endpoints. A `text` mark is a label anchored at a single content point, carrying its `text` string and an optional basic style (BACKLOG-0000875). `pen` is accepted as an alias for `freehand` on input; `list()` reports `freehand`.</p>
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Member</th><th>Type</th><th>Description</th></tr></thead>
+        <tbody>
+          <tr><td class="name">type</td><td class="type">'freehand' | 'arrow' | 'rect' | 'highlight' | 'text'</td><td class="desc"></td></tr>
+          <tr><td class="name">points</td><td class="type">{ x: number; y: number }[]</td><td class="desc">Content coordinates. A `text` mark carries a single anchor point; `arrow` and `rect` carry their two corners, and `freehand` a trail.</td></tr>
+          <tr><td class="name">colour</td><td class="type">string</td><td class="desc"><small>(optional)</small></td></tr>
+          <tr><td class="name">text</td><td class="type">string</td><td class="desc">The label of a `text` mark. Required for `text`, ignored for other types. <small>(optional)</small></td></tr>
+          <tr><td class="name">fontSize</td><td class="type">number</td><td class="desc">A `text` mark's font size in content pixels (before presentation scale). Defaults to 14. <small>(optional)</small></td></tr>
+          <tr><td class="name">background</td><td class="type">string</td><td class="desc">An optional backing colour drawn behind a `text` mark's label. <small>(optional)</small></td></tr>
+        </tbody>
+      </table>
+    </div>
     <h3 id="type-AnomalyReason">AnomalyReason</h3>
     <div class="table-wrap">
       <table>
@@ -6588,6 +6908,7 @@ return `methods ${ANOMALY_METHODS.length}; flagged ${z.flagged}; upper ${fence.u
           <tr><td class="name">pivot</td><td class="type">{ enabled: boolean; columns: string[] }</td><td class="desc"><small>(optional)</small></td></tr>
           <tr><td class="name">pivotView</td><td class="type">{ rowsCollapsed: string[]; columnsCollapsed: string[] }</td><td class="desc">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. <small>(optional)</small></td></tr>
           <tr><td class="name">formatting</td><td class="type">Record&lt;string, FormattingRule[]&gt;</td><td class="desc"><small>(optional)</small></td></tr>
+          <tr><td class="name">annotations</td><td class="type">AnnotationMark[]</td><td class="desc">Durable annotation marks (BACKLOG-0000813): seeded from here on first paint, and written back by `getState` so a host can persist and restore them. In content coordinates, so they track scroll and resize. <small>(optional)</small></td></tr>
           <tr><td class="name">expanded</td><td class="type">string[]</td><td class="desc"><small>(optional)</small></td></tr>
           <tr><td class="name">selection</td><td class="type">string[]</td><td class="desc"><small>(optional)</small></td></tr>
           <tr><td class="name">scroll</td><td class="type">{ top: number; left: number }</td><td class="desc"><small>(optional)</small></td></tr>
@@ -7830,6 +8151,8 @@ return `methods ${ANOMALY_METHODS.length}; flagged ${z.flagged}; upper ${fence.u
           <tr><td class="name">covariance</td><td class="type">(a: string, b: string, opts?: { population?: boolean }): number | null</td><td class="desc">Covariance, a correlation before the scales are divided out.</td></tr>
           <tr><td class="name">regression</td><td class="type">(a: string, b: string): RegressionFit | null</td><td class="desc">Least-squares fit of `b` on `a`: in finance, beta and alpha.</td></tr>
           <tr><td class="name">regressionModel</td><td class="type">(spec: RegressionSpec): RegressionModel | null</td><td class="desc">Fit a multi-predictor linear model over the filtered rows and return the full diagnostic set — coefficients with standard errors, t and p; R² and adjusted R²; per-row fitted values, residuals, leverage and Cook's D; VIF per predictor; a Breusch–Pagan heteroscedasticity flag; and, for a single predictor, a pointwise confidence band. `method` is `ols`, `wls` (needs a `weights` column) or `robust`; `quantile` is reserved and the regularised families refuse. Null on degenerate input (BACKLOG-0000792).</td></tr>
+          <tr><td class="name">adf</td><td class="type">(spec: { of: string; orderBy: string; maxlag?: number }): AdfResult | null</td><td class="desc">The Augmented Dickey-Fuller stationarity test over the `of` series in `orderBy` order (BACKLOG-0000873), constant+trend form with the lag order chosen by AIC up to an optional cap. Returns the statistic, the lag used, MacKinnon's critical values, an approximate (interpolated) p-value and a plain-language verdict at the 5% level — a scalar readout, not a column.</td></tr>
+          <tr><td class="name">acf</td><td class="type">(spec: { of: string; orderBy: string; maxlag?: number }): AcfResult | null</td><td class="desc">The autocorrelation (ACF) and partial autocorrelation (PACF) of the `of` series in `orderBy` order out to `maxlag` (BACKLOG-0000873), with the approximate ±1.96/√n band. A short-series readout; feed the arrays to a bar chart over explicit points with the band as reference lines. The lag-1 autocorrelation matches `series(...).autocorrelation`.</td></tr>
           <tr><td class="name">spearman</td><td class="type">(a: string, b: string): number | null</td><td class="desc">Spearman's rank correlation, which one outlier cannot drag.</td></tr>
           <tr><td class="name">kendall</td><td class="type">(a: string, b: string): number | null</td><td class="desc">Kendall's tau-b. Null past 5,000 rows: it is quadratic.</td></tr>
           <tr><td class="name">weightedQuantile</td><td class="type">(colId: string, weightId: string, p?: number): number | null</td><td class="desc">A quantile of one column weighted by another; the median by default.</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.29.0</p>
+    <p class="rail__sub">Developer guide · v1.31.0</p>
     <nav>
       <div class="rail__group">
         <span class="rail__label">Start here</span>
@@ -4835,6 +4835,8 @@ grid.on('presentation:captured', (e) =&gt; {
       <p class="example__label">Drawing over the grid</p>
       <pre><code>grid.annotate.use('pen');                    <span class="cmt">// pen · arrow · rect · highlight</span>
 grid.annotate.use('arrow', { colour: '#e0245e' });
+<span class="cmt">// A durable text label anchored to a cell, seeded or added (BACKLOG-875).</span>
+grid.annotate.add({ type: 'text', text: 'Q3 spike', points: [{ x: 232, y: 72 }], background: '#fffbe6' });
 grid.annotate.undo();
 grid.annotate.clear();
 grid.annotate.use(null);                     <span class="cmt">// hand the grid back</span></code></pre>
@@ -6236,6 +6238,7 @@ grid.state.apply(savedView.state);
           <tr><td class="name">canChartRange</td><td class="desc">Whether <code>chartRange</code> would draw something for the grid’s current selection — the question a menu asks before offering the item.</td></tr>
           <tr><td class="name">deriveRangeSpec</td><td class="desc">Decide what a chart of a range should be without drawing it: the type, the category column, the measures, and a spec ready for <code>createChart</code>.</td></tr>
           <tr><td class="name">regressionPlots</td><td class="desc">Turn a fitted regression model into diagnostic chart specs ready for <code>createChart</code>: the fit line with its confidence band, residuals-vs-fitted, a QQ plot of the residuals, and a multicollinearity correlogram with the model’s VIF. The plots that need a per-row or per-coefficient quantity the grid has no column for (scale-location, residuals-vs-leverage, the coefficient forest) are returned as a null spec carrying the reason rather than dropped.</td></tr>
+          <tr><td class="name">createDataRouter</td><td class="desc">Split one arriving stream or dataset across many grids by what each record is — a property or a predicate — driving each grid through the public keyed <code>rows.apply</code> path so a snapshot is a diff, a delta is applied in place, a moved partition moves the row rather than duplicating it, and an unmatched record is counted, sunk and never dropped. v2 adds cross-grid selection filtering: <code>link(source, target, relation)</code> makes a selection in one grid filter what another receives — by a key map or a predicate function, multi-select as an IN set, debounced — re-pushed through the same keyed-diff path so the target stays dumb. Detaches its grids on <code>destroy</code>; the host owns them.</td></tr>
           <tr><td class="name">createDevtools</td><td class="desc">Mount the devtools panel against a grid, including its accessibility checks.</td></tr>
           <tr><td class="name">createLatticeGridElement</td><td class="desc">Build the element class without registering it, for a custom registry.</td></tr>
           <tr><td class="name">createMessages</td><td class="desc">Build a message catalogue. A partial set lays over the built-in British English one.</td></tr>
@@ -6460,6 +6463,7 @@ el.grid.sort.set([{ col: 'charge', dir: 'desc' }]);</code></pre>
           <tr><td class="name">timeline:detached</td><td class="desc">The brush was removed.</td></tr>
           <tr><td class="name">timeline:seek</td><td class="desc">The brush settled on a range.</td></tr>
           <tr><td class="name">timeline:seeking</td><td class="desc">The brush is being dragged. Throttled.</td></tr>
+          <tr><td class="name">annotation:changed</td><td class="desc">A drawing annotation was added, edited or cleared. Carries the active tool and the mark count. Declared (BACKLOG-876) so grid.on('annotation:changed', ...) and the adapters' onAnnotationChanged reach it directly instead of via the '*' wildcard.</td></tr>
           <tr><td class="name">view:applied</td><td class="desc">Emits no storage write: applying a view changes nothing to persist.</td></tr>
           <tr><td class="name">view:default</td><td class="desc">view is null when the default was cleared.</td></tr>
           <tr><td class="name">view:removed</td><td class="desc">A saved view was deleted.</td></tr>