@toclocoinc/lattice-grid 1.48.0 → 1.50.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.48.0 · [latticegrid.dev](https://www.latticegrid.dev) · TOCLOCO Inc
+Version 1.50.0 · [latticegrid.dev](https://www.latticegrid.dev) · TOCLOCO Inc
 
 ---
 
@@ -349,6 +349,7 @@ the UMD build or `.cjs` for CommonJS.
 | 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`). |
+| tabs | `@toclocoinc/lattice-grid/modules/tabs` | `modules/tabs.min.js` | `LatticeGridTabs` | A tab strip where each tab is its own full grid, optionally derived from another (`createTabs`). |
 | 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`). |

package/docs/API.html

@@ -2129,7 +2129,7 @@ createGrid(el, {
           <tr><td class="sig">delta</td><td class="desc">Current value minus the baseline.</td></tr>
           <tr><td class="sig">deltaPercent</td><td class="desc">The same as a percentage. A change from nothing has no percentage and reads null rather than infinity.</td></tr>
           <tr><td class="sig">rate</td><td class="desc">Change per second, from the last two readings.</td></tr>
-          <tr><td class="sig">history</td><td class="desc">The recent readings, oldest first. <code>depth</code> sets how many; the default is 20.</td></tr>
+          <tr><td class="sig">history</td><td class="desc">The recent readings, oldest first. <code>depth</code> sets how many; the default is 20. Counts <em>changes</em> by default — see the time-windowed form below for a real time series.</td></tr>
           <tr><td class="sig">firstValue</td><td class="desc">The baseline itself.</td></tr>
           <tr><td class="sig">streak</td><td class="desc">Consecutive moves in one direction, signed. It resets on a turn, because "seven rises" means something and "seven changes" does not.</td></tr>
         </tbody>
@@ -2164,6 +2164,10 @@ createGrid(el, {
 ]</code></pre>
     <p>Computed in one pass over the display rows and cached against that ordering, so a hundred thousand rows are walked once per sort rather than once per cell. A running column is not sortable. Sorting on one asks the sort to depend on its own output (the value is defined by the display order) so the column does not offer a sort unless its definition asks for one, and the query layer refuses such a sort with a warning rather than computing it. Sort by the column it runs over instead. Group headings and totals rows are skipped, a running total that counted a subtotal would double everything below it, and a row with no value carries the figure forward unchanged rather than resetting it.</p>
 
+    <h4 id="history-window">History has two clocks: a count of changes, or a span of time (BACKLOG-0001043)</h4>
+    <p>Plain <code>history</code> (above) is an <em>event</em> series: it records a reading only when the value changes, so a row that sits still never advances it. Bound to a <code>cell.render</code> sparkline (<code>'line'</code>, <code>'area'</code>, <code>'column'</code>, <code>'winloss'</code>) that means a static row's sparkline freezes, then jumps when a change finally lands — while a title like "last 60s" keeps claiming a span the column never measured. Add a <em>time</em> <code>window</code> to make it a real time series instead:</p>
+    <pre><code>{ id: 'spark', title: 'Last 60s', shadow: { of: 'price', kind: 'history', window: { kind: 'time', span: 60_000 }, depth: 20 } }</code></pre>
+    <p>This is the same <code>window: { kind, span }</code> shape the rolling kinds below already accept — not a second spelling of it — and it changes what <code>history</code> means rather than adding a new kind: <code>depth</code> (20 here) is now how many buckets the <code>span</code> divides into, so this is sixty seconds as twenty three-second buckets. Each bucket is sampled once, at its close, as the row's <em>last known value</em> at that moment — carried forward from the previous bucket when nothing changed in between. A static row therefore draws a flat line that keeps advancing, one sample per bucket, and a change lands in the bucket it actually happened in rather than being appended at the end. The bucket clock runs on its own low-frequency timer (never a render loop), so the series keeps moving even while no data event ever reaches the column. <code>window: { kind: 'count' }</code> and <code>{ kind: 'session' }</code> are refused for <code>history</code> — a plain count is already what <code>depth</code> means without a window, and a session has no fixed span to divide into buckets — and a caller who never sets <code>window</code> gets the original count-based behaviour, unchanged.</p>
     <div class="note"><p>Positional kinds rank over every <em>tracked</em> row, not over the filtered set: a rank that changed as you filtered would make "the top ten movers" depend on what happened to be on screen, and the column would disagree with itself between two views of the same data. Pass <code>scope: 'filtered'</code> on the shadow spec to rank within what the filters left instead: both answers are legitimate, which is why it is a choice rather than a default.</p></div>
     <div class="note"><p>Shadow state is keyed by row key, never by index: after any sort an index-keyed history would report one row's past against another row's present, and the wrong number would be <em>sortable</em>. Memory is capped at 200,000 tracked rows per column; past that the oldest are dropped and <code>tracking().forgotten</code> says how many, rather than a smaller number being reported as though it were the truth.</p></div>
 
@@ -5044,6 +5048,7 @@ plan.applyEdit({ id: 'design', duration: 7 }); // recomputes; the critical path
           <tr><td class="sig">importMSPDI(xml, { hoursPerDay? })</td><td class="desc">Import a Microsoft Project (MSPDI) <code>.xml</code> document into a <code>{ tasks, dependencies, resources, projectStart, calendar }</code> model ready for <code>createGantt</code>: the task tree, typed dependencies with lag, constraints, baseline, %complete, resources with capacity and the resource assignments.</td></tr>
           <tr><td class="sig">exportMSPDI(model, { hoursPerDay?, projectName? })</td><td class="desc">Serialise a Gantt model (optionally a scheduled one) back to Microsoft Project (MSPDI) XML &mdash; the same fields, round-tripping with <code>importMSPDI</code>. The controller offers <code>gantt.toMSPDI()</code> as a shortcut over the current plan.</td></tr>
           <tr><td class="sig">computeEarnedValue(tasks, schedule, { statusDate?, costField?, actualCostField? })</td><td class="desc">Earned-value management (EVM) from the baseline and %complete at a status date: Planned Value (PV/BCWS), Earned Value (EV/BCWP), Actual Cost (AC/ACWP, from a per-task <code>actualCost</code>), plus Schedule Variance (EV&minus;PV), Cost Variance (EV&minus;AC), SPI (EV/PV) and CPI (EV/AC) &mdash; per task, rolled up to summaries and the project. Budget (BAC) is the task's <code>cost</code>, or its duration when no cost is given. The controller exposes <code>gantt.earnedValue({ statusDate })</code> as the shortcut; the split view surfaces the metrics through <code>kind: 'evm'</code> columns.</td></tr>
+          <tr><td class="sig">getState() / setState(snapshot)</td><td class="desc">Serialise and restore the Gantt's own VIEWER state (BACKLOG-0001042) &mdash; which view is mounted (<code>'plain'</code>/<code>'split'</code>/<code>null</code>), zoom, the arrow/progress/baseline toggles, calendar/non-working shading, the plain view's swimlane grouping, the split view's left-panel width and its collapsed summary rows. Not the task data (already covered by <code>setTasks</code>/<code>rows.apply</code>). Versioned, JSON-safe, and <code>setState</code> tolerates an unknown, wrong-typed or newer-version snapshot without throwing, applying only what it recognises.</td></tr>
         </tbody>
       </table>
     </div>
@@ -5526,6 +5531,67 @@ grid.destroy();
 <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="tabs">The tabbed grid</h2>
+    <p><code>modules/tabs</code> is an opt-in top-of-grid tab strip where <strong>each tab is its own full, independently-configured grid instance</strong> &mdash; "configure each tab as per a normal grid" rather than one grid whose state is swapped. That is a deliberate rejection of the cheaper alternative: <code>grid.state.get()</code>/<code>.apply()</code> only repositions, hides, resizes and sorts <strong>existing</strong> columns by id (no field, type, editor or row data), so a state-swap only works when every tab shares one column schema and one source &mdash; strictly less than the ask. A tab may instead declare <code>from: '&lt;tabId&gt;'</code> plus a narrowing (<code>where</code>, <code>group</code>, <code>join</code>, &hellip;), and the module wires a <code>source: { mode: 'derived', from: &lt;the parent tab's live grid&gt;, &hellip; }</code> for it &mdash; the shipped derived-source mechanism, not a new config-inheritance one. <code>createGrid</code> is <strong>injected</strong> (the same pattern the React/Vue/Svelte adapters use), so the module imports no engine code regardless of how it is loaded — its own minified ESM build (<code>tabs.esm.min.js</code>) is ~65KB gzipped, the same size class as the KPI and framework-adapter modules (~61&ndash;66KB), rather than the ~700KB a module that inlines the whole engine (the web component, htmx) ships.</p>
+    <pre><code>import { createGrid } from '@toclocoinc/lattice-grid';
+import { createTabs } from '@toclocoinc/lattice-grid/modules/tabs';
+
+const tabs = createTabs(document.querySelector('#tabs'), {
+  createGrid,                     <span class="cmt">// injected -- see below</span>
+  tabs: [
+    { id: 'all', label: 'All', config: { rowKey: 'id', rows, columns } },
+    { id: 'open', label: 'Open', from: 'all', where: (r) =&gt; r.stage === 'Open',
+      follow: 'filtered', refresh: 'live', config: { columns } },
+    { id: 'breached', label: 'Breached', from: 'open',       <span class="cmt">// derives from Open, not All -- a chain</span>
+      where: (r) =&gt; r.daysOverdue &gt; 0, config: { columns } },
+  ],
+  onBeforeTabChange: ({ id }) =&gt; !hasUnsavedEdit(),  <span class="cmt">// veto a switch</span>
+});</code></pre>
+    <p><strong>Lifecycle.</strong> A tab's grid mounts on <em>first activation</em>, not up front, and then stays alive &mdash; hidden, never destroyed &mdash; until the whole strip is. Per-tab scroll, selection, filters, sort, grouping, expansion — and an open cell/row editor — therefore survive a switch away and back natively, by simply not touching that grid instance, rather than through a lossy serialise/restore round-trip: leave a tab mid-edit, switch away, switch back, and the editor is exactly as it was left, uncommitted and undiscarded. Activating a derived tab materialises its whole ancestor chain first (mounted, hidden), and a cyclic <code>from</code> graph is refused &mdash; naming the exact cycle &mdash; when <code>createTabs</code> is called, not at first click.</p>
+    <p><strong>A hidden tab costs nothing this module can spend.</strong> An inactive panel carries the <code>hidden</code> attribute (<code>display:none</code>); the module runs no timer, observer or repaint of its own against it. Measured with a real browser (<code>bench/tabs-idle.mjs</code>): several mounted-but-hidden, untouched tabs cost the same idle CPU as none at all. The one honestly-reported exception is not this module's: a <em>derived</em> tab's row model still re-derives on every change to its (possibly hidden) parent &mdash; by design, so reactivating it is instant rather than a stale flash &mdash; and the engine's own repaint listener for a derived source's <code>rows:changed</code> calls the renderer directly, bypassing <code>grid.updates.pause()</code> (which only holds the streaming-ingestion path). A hidden derived tab therefore still runs a read/compute/write pass on every parent change, even though the write phase paints a zero-size viewport; the bench measures and reports the size of that gap rather than leaving it inferred.</p>
+    <p><strong>Accessibility.</strong> A real <code>role="tablist"</code>/<code>"tab"</code>/<code>"tabpanel"</code> with <code>aria-selected</code> and a roving <code>tabindex</code>, imitating the grid's own column-header keyboard model rather than the tool panel's tablist (which has the roles but no arrow-key handling). This is <strong>manual activation</strong>: <kbd>&larr;</kbd>/<kbd>&rarr;</kbd> and <kbd>Home</kbd>/<kbd>End</kbd> move the roving tab stop without switching the panel or mounting a grid; <kbd>Enter</kbd>/<kbd>Space</kbd>, or a click, activates. The newly active tab's label is announced through a polite live region.</p>
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Member</th><th>Description</th></tr></thead>
+        <tbody>
+          <tr><td class="sig">createTabs(el, config)</td><td class="desc">Create a tabbed grid. <code>config.createGrid</code> is required (injected, not imported); <code>config.tabs</code> is a non-empty array of tab descriptors, each an <code>id</code>, a <code>label</code>, a grid <code>config</code>, and optionally <code>from</code> plus the derivation narrowing (<code>where</code>, <code>group</code>, <code>groupBy</code>, <code>bucket</code>, <code>join</code>, <code>unnest</code>, <code>refresh</code>, <code>crossFilter</code>, <code>follow</code>, <code>limit</code>, <code>sort</code>, <code>profile</code>) forwarded onto the derived source built for it.</td></tr>
+          <tr><td class="sig">tabs() / tab(id) / isMounted(id)</td><td class="desc">The configured tab ids, in order; a tab's live grid instance (or <code>null</code> before its first activation); whether a tab has been materialised yet.</td></tr>
+          <tr><td class="sig">activate(id, opts)</td><td class="desc">Switch the active tab, gated by <code>beforeTabChange</code>. Returns <code>true</code>/<code>false</code> synchronously with no handler registered, or a <code>Promise&lt;boolean&gt;</code> when a handler deferred.</td></tr>
+          <tr><td class="sig">on(name, fn) / off(name, fn)</td><td class="desc">Events: <code>tab:changed</code>, the cancellable <code>beforeTabChange</code> (call <code>preventDefault(reason?)</code> or return <code>false</code> to veto), and its paired <code>tabChange:cancelled</code>. Config sugar: <code>onTabChange</code>, <code>onBeforeTabChange</code>, <code>onTabChangeCancelled</code>.</td></tr>
+          <tr><td class="sig">destroy()</td><td class="desc">Tear the whole strip down; destroys every mounted tab's grid (each isolated, so one throwing does not strand the rest).</td></tr>
+        </tbody>
+      </table>
+    </div>
+    <h3 id="tabs-live-example">All / Open / Breached, a two-deep derivation chain, executed</h3>
+    <p class="section-note"><code>createTabs</code> deliberately has no headless mode &mdash; it requires a real host element, the same way <code>createGrid</code> itself does &mdash; so this executed example reaches for the same in-tree DOM test double the suite itself runs the renderer against headlessly (<code>packages/dom/src/renderer/testdom.js</code>), rather than a real browser. <code>demo/tabs.html</code> is the browser version of the same chain, with buttons that edit All directly and let Open and Breached follow.</p>
+    <pre data-run="js" data-expect="4,3,2" data-covers="export:createTabs"><code><span class="kw">const</span> { createTestDom } = <span class="kw">await</span> import('../packages/dom/src/renderer/testdom.js');
+<span class="kw">const</span> { root } = createTestDom();
+<span class="kw">const</span> { createGrid } = <span class="kw">await</span> import('../packages/dom/src/index.js');
+<span class="kw">const</span> { createTabs } = <span class="kw">await</span> import('../packages/modules/tabs/index.js');
+
+<span class="kw">const</span> rows = [
+  { id: 1, stage: 'Open', daysOverdue: 0 },
+  { id: 2, stage: 'Open', daysOverdue: 5 },
+  { id: 3, stage: 'Won', daysOverdue: 0 },
+  { id: 4, stage: 'Open', daysOverdue: 2 },
+];
+<span class="kw">const</span> columns = [{ field: 'id' }, { field: 'stage' }, { field: 'daysOverdue' }];
+
+<span class="kw">const</span> tabs = createTabs(root, {
+  createGrid,
+  tabs: [
+    { id: 'all', label: 'All', config: { rowKey: 'id', rows, columns } },
+    { id: 'open', label: 'Open', from: 'all', where: (r) =&gt; r.stage === 'Open', config: { columns } },
+    <span class="cmt">// derives from Open, not All -- a two-deep chain</span>
+    { id: 'breached', label: 'Breached', from: 'open', where: (r) =&gt; r.daysOverdue &gt; 0, config: { columns } },
+  ],
+});
+
+tabs.activate('breached');                    <span class="cmt">// materialises 'open' too, automatically</span>
+<span class="kw">const</span> counts = ['all', 'open', 'breached'].map((id) =&gt; tabs.tab(id).rows.count());
+tabs.destroy();
+<span class="kw">return</span> counts.join(',');                       <span class="cmt">// 4,3,2</span></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';
@@ -6168,7 +6234,7 @@ spans.addSpan('R0', 'name', 3, 2); <span class="cmt">// rowspan 3, colspan 2</sp
     <h3 id="nested-config-example">Nested configuration, executed</h3>
     <p class="section-note">Thirteen option blocks, each key written where it belongs. Parsed and evaluated on
     every build, so a key that was renamed or moved shows up here.</p>
-    <pre data-run="js" data-expect="14" data-covers="config:aboveLimit config:adapter config:binary config:bucket config:bucketFn config:buckets config:cacheLimit config:cardinalityLimit config:checkbox config:coalesceMs config:commit config:confirm config:cumulative config:debounce config:decimals config:delimiter config:display config:download config:enabled config:enterMovesDown config:fetch config:fileName config:fill config:fillHandle config:follow config:format config:from config:granularity config:groupBy config:hasChildren config:headerCheckbox config:headers config:hint config:idleMs config:indexLimit config:isMaster config:join config:label config:limit config:limitPer config:lineEnding config:loadChildren config:lock config:lockMs config:markdown config:maxCachedPages config:maxDecimals config:maxRows config:me config:minDecimals config:mode config:onCreate config:open config:orient config:orphans config:pageSize config:palette config:parentKey config:path config:pendingTimeout config:placement config:processCell config:profile config:promoteToMemoryBelow config:provider config:quote config:ranges config:removeMs config:retainSource config:roster config:scale config:select config:space config:start config:strategy config:system config:target config:throttleMs config:undoDepth config:unit config:unnest config:where"><code><span class="cmt">// Placeholders for the things a real page supplies. The point of this block is</span>
+    <pre data-run="js" data-expect="14" data-covers="config:aboveLimit config:adapter config:ageBy config:binary config:bucket config:bucketFn config:buckets config:cacheLimit config:cardinalityLimit config:checkbox config:coalesceMs config:commit config:confirm config:cumulative config:debounce config:decimals config:delimiter config:display config:download config:enabled config:enterMovesDown config:fetch config:fileName config:fill config:fillHandle config:follow config:format config:from config:granularity config:groupBy config:hasChildren config:headerCheckbox config:headers config:hint config:idleMs config:indexLimit config:isMaster config:join config:label config:limit config:limitPer config:lineEnding config:loadChildren config:lock config:lockMs config:markdown config:maxCachedPages config:maxAge config:maxDecimals config:maxRows config:me config:minDecimals config:mode config:onCreate config:open config:orient config:orphans config:pageSize config:palette config:parentKey config:path config:pendingTimeout config:placement config:processCell config:profile config:promoteToMemoryBelow config:provider config:quote config:ranges config:removeMs config:retainSource config:roster config:scale config:select config:space config:start config:strategy config:system config:target config:throttleMs config:undoDepth config:unit config:unnest config:where"><code><span class="cmt">// Placeholders for the things a real page supplies. The point of this block is</span>
 <span class="cmt">// the option names: each one below is a documented key, written where it</span>
 <span class="cmt">// belongs, so a key that was renamed or moved stops matching its interface.</span>
 <span class="kw">const</span> source = {}, other = {}, provider = {}, compute = {}, adapter = {};
@@ -6209,7 +6275,10 @@ spans.addSpan('R0', 'name', 3, 2); <span class="cmt">// rowspan 3, colspan 2</sp
 <span class="kw">const</span> pagedSourceConfig = { mode: 'paged', pageSize: 100, maxCachedPages: 5, fetch };
 
 <span class="cmt">// A streaming source — StreamSourceConfig</span>
-<span class="kw">const</span> streamSourceConfig = { mode: 'stream', open, coalesceMs: 16, maxRows: 1e6, promoteToMemoryBelow: 5e5 };
+<span class="kw">const</span> streamSourceConfig = { mode: 'stream', open, coalesceMs: 16, maxRows: 1e6, promoteToMemoryBelow: 5e5,
+    <span class="cmt">// A rolling *time* window beside the count one: keep five minutes, aged by the</span>
+    <span class="cmt">// row's own clock. Omit ageBy and rows age from when they arrived instead.</span>
+    maxAge: 5 * 60 * 1000, ageBy: 'ts' };
 
 <span class="cmt">// A pushdown source — PushdownSourceConfig</span>
 <span class="kw">const</span> pushdownSourceConfig = { adapter, compute, pageSize: 200 };
@@ -6916,6 +6985,7 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
           <tr><td class="name">labels</td><td class="type">boolean</td><td class="desc">Draw the tick labels. <small>(optional)</small></td></tr>
           <tr><td class="name">every</td><td class="type">number</td><td class="desc">Show every nth category label, on a crowded category axis. <small>(optional)</small></td></tr>
           <tr><td class="name">rotate</td><td class="type">boolean | 'auto'</td><td class="desc">Force the category labels' rotation rather than deciding it. <small>(optional)</small></td></tr>
+          <tr><td class="name">window</td><td class="type">Pick&lt;WindowSpec, 'kind' | 'span'&gt;</td><td class="desc">A rolling window for the axis domain (BACKLOG-0001036), in the shipped `WindowSpec` vocabulary that rolling statistics already use. Only `{ kind: 'time', span }` applies to an axis: the domain becomes the last `span` milliseconds ending **now**, so the chart keeps scrolling left while the feed is silent — the thing a count window cannot do, because with no rows arriving nothing changes. Advanced on a low-frequency clock (a quarter of the window, between 50 ms and 1 s), never per frame, and stopped when the chart is destroyed or its document is hidden. Needs a continuous x axis carrying wall-clock times; `{ kind: 'count' }` is the source's `maxRows` and is refused here rather than given a second meaning. <small>(optional)</small></td></tr>
         </tbody>
       </table>
     </div>
@@ -9900,6 +9970,8 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
           <tr><td class="name">mode</td><td class="type">'stream'</td><td class="desc"></td></tr>
           <tr><td class="name">open</td><td class="type">(req: {</td><td class="desc"></td></tr>
           <tr><td class="name">maxRows</td><td class="type">number</td><td class="desc">The most rows to keep. A stream has no end, so an unbounded grid dies overnight; this makes it a sliding window and the oldest rows are dropped. Omit for no limit. Set on the source, not passed to `open`, it bounds what the grid retains rather than what the producer sends. <small>(optional)</small></td></tr>
+          <tr><td class="name">maxAge</td><td class="type">number</td><td class="desc">The longest a row is kept, in milliseconds — a rolling *time* window, sitting beside `maxRows` as a second, independent bound (BACKLOG-0001036). Rows older than the span are evicted through the same path, the same `evicted` counters and the same `stream:evicted` event as the count bound, so an existing readout keeps working. Set both and whichever bites first applies. Eviction continues on a low-frequency timer while the feed is idle, so "the last five minutes" keeps shrinking through a silent period rather than freezing — which is the thing `maxRows` cannot do. Retention is a *bound, not a guillotine*: rows live a little past the span before a block is dropped. Two things add to it. First the eviction slack, ten per cent of the span, exactly as `maxRows` overshoots its count, so the row permutation is rebuilt once per block rather than once per row. Second, when the feed is idle, up to one tick of the eviction timer, which runs at a quarter of the span clamped to between 50 ms and one second. So the real ceiling is roughly `span * 1.1 + tick`, and because the tick has a floor it is proportionally larger the shorter the window: negligible at a five-minute window (about 10%), around 1.25x at ten seconds, and as much as ~1.35x at three. That is the deliberate trade for an idle grid that costs no CPU. Omit for no age limit. <small>(optional)</small></td></tr>
+          <tr><td class="name">ageBy</td><td class="type">string | ((row: unknown) =&gt; unknown)</td><td class="desc">Which clock `maxAge` reads: a column id (or dotted path), or a function of the row returning a `Date`, epoch milliseconds, or an ISO string (BACKLOG-0001036). Given, the window follows the **data's own** clock, so it means what the producer means — and inherits the producer's clock skew. Omitted, `maxAge` falls back to **arrival time**: when the row reached this source. Arrival time needs no timestamp column and cannot be skewed, but it is not event time — a row delayed in transit counts as young. A row whose time value cannot be read is never aged out. <small>(optional)</small></td></tr>
           <tr><td class="name">promoteToMemoryBelow</td><td class="type">number</td><td class="desc"><small>(optional)</small></td></tr>
           <tr><td class="name">coalesceMs</td><td class="type">number</td><td class="desc"><small>(optional)</small></td></tr>
         </tbody>

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.48.0</p>
+    <p class="rail__sub">Developer guide · v1.50.0</p>
     <nav>
       <div class="rail__group">
         <span class="rail__label">Start here</span>
@@ -4470,6 +4470,96 @@ grid.updates.log({ since: Date.now() - 60000 });   <span class="cmt">// what arr
       left up overnight holds every row it was ever sent. Set <code>source.maxRows</code> and the
       stream becomes a sliding window, dropping the oldest as new ones arrive and reporting how
       many it let go through <code>evicted</code> on the progress report.</p>
+    </div>
+
+    <h3 id="time-window-guide">A time window, not just a row count</h3>
+    <p class="lead-in">
+      <code>maxRows</code> is a <em>count</em> window. <code>maxAge</code> is a <em>time</em>
+      window. They are different promises, and a live feed usually wants the second one.
+    </p>
+    <div class="example">
+      <p class="example__label">Keep the last five minutes, and show the last five minutes</p>
+      <pre><code>const grid = createGrid(el, {
+  columns,
+  source: {
+    mode: 'stream',
+    open,
+    maxAge: 5 * 60 * 1000,   <span class="cmt">// keep five minutes of rows</span>
+    ageBy: 'ts',             <span class="cmt">// ...aged by this column; omit for arrival time</span>
+    maxRows: 20000,          <span class="cmt">// ...and never more than this many, whichever bites first</span>
+  },
+});
+
+createChart({
+  grid, container, type: 'line', x: 'ts', y: { col: 'value', fn: 'avg' },
+  <span class="cmt">// The x domain is the last five minutes ending *now*, so the chart</span>
+  <span class="cmt">// keeps scrolling left even while the feed is silent.</span>
+  axis: { x: { window: { kind: 'time', span: 5 * 60 * 1000 } } },
+});</code></pre>
+    </div>
+    <div class="why">
+      <p><strong>A count window drifts, and it freezes.</strong> <code>maxRows</code> equals
+      &ldquo;the last five minutes&rdquo; only while the feed rate is steady: a burst silently
+      shrinks the window to two minutes, a quiet spell stretches it to twenty, and the x axis
+      changes span under the reader. Worse, when the feed goes quiet nothing is evicted and the
+      chart stops moving, even though time is still passing &mdash; and the silence is usually the
+      thing worth seeing. <code>maxAge</code> is a span of wall clock, so it means the same thing
+      whatever the feed is doing.</p>
+      <p><strong>Two bounds, one eviction path.</strong> <code>maxAge</code> and
+      <code>maxRows</code> are independent and compose: both are applied on the same pass and
+      whichever bites first is simply the one that drops rows. Neither is silently ignored.
+      Age eviction reuses the count bound&rsquo;s machinery outright, so <code>evicted</code> on
+      the progress report and the <code>stream:evicted</code> event carry age evictions exactly as
+      they always carried count evictions &mdash; an existing &ldquo;dropped off the back of the
+      window&rdquo; readout keeps working with nothing changed.</p>
+      <p><strong>The span is a bound, not a guillotine.</strong> A row lives a little past the span
+      before it goes, and two things add to that. First the eviction slack, ten per cent of the
+      span &mdash; exactly the overshoot <code>maxRows</code> already allows on its count &mdash; so
+      the row permutation is rebuilt once per block rather than once per arriving row. Second, when
+      the feed is idle, up to one tick of the eviction timer, which runs at a quarter of the span
+      clamped to between 50&nbsp;ms and one second. The real ceiling is therefore about
+      <code>span &times; 1.1 + tick</code>, and because the tick has a floor it is
+      <em>proportionally larger the shorter the window</em>: about 10% over at a five-minute
+      window, around 1.25&times; at ten seconds, and as much as ~1.35&times; at three. That is the
+      deliberate price of an idle grid that costs no CPU, and it is why the number to reach for is
+      the window you want the reader to see rather than a hard retention limit. The chart&rsquo;s
+      domain is exact either way &mdash; it ends at <em>now</em> &mdash; so the extra rows sit off
+      the left edge rather than being drawn.</p>
+      <p><strong>Which clock: <code>ageBy</code>, or arrival.</strong> Given
+      <code>ageBy</code> &mdash; a column id, a dotted path, or a function of the row returning a
+      <code>Date</code>, epoch milliseconds or an ISO string &mdash; the window follows the
+      <em>data&rsquo;s own</em> clock, so it means what the producer means. That also inherits the
+      producer&rsquo;s clock skew: if their clock runs five minutes fast, their rows live five
+      minutes longer than yours. Omit <code>ageBy</code> and rows age from <strong>arrival
+      time</strong>, when the row reached the source. Arrival time needs no timestamp column and
+      cannot be skewed, but it is not event time &mdash; a row delayed in transit is treated as
+      young. A synthetic or metric feed usually wants arrival; a log or event feed usually wants
+      <code>ageBy</code>. A row whose time value cannot be read is never aged out: dropping data
+      because a timestamp was malformed is the worse failure.</p>
+      <p><strong>Out of order is handled, not reordered.</strong> With <code>ageBy</code> the
+      row&rsquo;s clock need not be monotonic in arrival order, so eviction scans the window rather
+      than walking the head; a late row that is already older than the span is dropped on the same
+      pass it arrived on and counted as evicted, rather than being painted and then withdrawn a
+      moment later. Nothing is re-sorted: a row&rsquo;s <em>position</em> is still arrival order,
+      only its <em>retention</em> is decided by its time.</p>
+      <p><strong>The chart axis rolls independently.</strong> The axis takes the same
+      <code>WindowSpec</code> vocabulary rolling statistics use &mdash;
+      <code>window: { kind: 'time', span }</code> &mdash; and its domain ends at <em>now</em>
+      rather than at the newest point, which is what makes the chart keep scrolling with zero new
+      rows. It works with or without <code>maxAge</code> on the source; set both to the same span
+      and the retained data and the drawn domain agree. Only <code>kind: 'time'</code> applies to
+      an axis: a count window over a chart is the source&rsquo;s <code>maxRows</code>, and
+      <code>kind: 'count'</code> is refused with a warning rather than quietly given a second
+      meaning. The x column has to be continuous and carry wall-clock times &mdash; a banded or
+      categorical axis has no domain to roll.</p>
+      <p><strong>Idle costs nothing.</strong> Both halves advance on a plain interval &mdash; a
+      quarter of the window, clamped to between 50&nbsp;ms and one second &mdash; and never on an
+      animation frame. The source&rsquo;s wake returns after a single number comparison unless a
+      row is actually due, and the chart&rsquo;s wake does nothing at all when the document is
+      hidden or the chart is detached. Both timers are cleared on destroy. Measured over a
+      five-minute window holding 50,000 rows with no feed at all, the window&rsquo;s CPU cost is
+      inside the run-to-run noise of the same source with no bound set: under 0.04% of one core
+      (<code>bench/idle-window.mjs</code>).</p>
       <p><strong>The log keeps the raw sequence, not the merged one.</strong> Merging is right for
       applying a backlog quickly and wrong for looking at what happened, because the intermediate
       states are exactly what a time scrubber would move between. It survives the flush,
@@ -6553,7 +6643,8 @@ grid.import.apply(preview);</code></pre>
           <tr><td class="name">createKanban</td><td class="desc">A board (kanban) view of rows as cards, grouped into columns by a configurable property (a status, a stage, a state field), with per-column card count and an optional points sum, a WIP over-limit flag, configured columns shown even when empty, granular readonly (whole board / per column / per card), field-mapped card templates that reuse the grid’s own column formatters when a grid is bound, and the core pointer events (<code>card:click</code>, <code>card:dblclick</code>, <code>card:contextmenu</code>). It is a dataset viewer like any other: it consumes data through the same keyed-diff <code>rows.apply({ add, update, remove })</code> contract a grid exposes, so a Data Router can <code>attach(value, board)</code> and drive a kanban beside a grid and a chart off one feed. Accessibility is built in from the start — a labelled group of labelled column lists, cards in a roving-tabindex focus ring with arrow-key navigation, and a polite live region. Every structural property is named in config (<code>columnProperty</code>, <code>pointsProperty</code>, <code>orderProperty</code>, <code>swimlaneProperty</code>, <code>sprintProperty</code>, <code>epicProperty</code>) so it maps DemandFlow and any customer schema without code change. Pass <code>null</code> as the element for a headless board that computes the same model without a DOM. Cards drag between columns (writing the column property) and within a column into a position (writing the order property with fractional ranking), and the same move is keyboard-accessible — <kbd>Space</kbd> to grab, arrows to choose a target, <kbd>Space</kbd>/<kbd>Enter</kbd> to drop, <kbd>Escape</kbd> to cancel — announced on the live region; multi-select drags every selected card. A move calls <code>onBeforeMove(card, from, to, index)</code> first (return <code>false</code> to veto) and then persists through the grid’s shipped write-back path — grid-bound via <code>grid.edit.setCells</code> (the same public edit-commit path inline editing uses, so the grid’s pipeline owns optimistic apply / confirm / revert), standalone with a revert when <code>onCardMove</code> rejects — emitting <code>card:move</code>. A configurable per-card <code>contextMenu</code> replaces the <code>card:contextmenu</code> event when present. With <code>swimlanes: true</code> it renders a 2D lane&times;column grid grouped by <code>swimlaneProperty</code> (per-lane count/points, columns aligned across lanes, a cross-lane drag writing the swimlane property); columns and lanes collapse (state surviving a keyed-diff update), columns reorder by header drag, and <code>setQuickFilter</code>/<code>setFilter</code>/<code>facets</code> drive search and faceting. <code>setSprint</code>/<code>showBacklog</code>/<code>sprints</code> give a sprint view, switcher and backlog; <code>setEpic</code>/<code>epicRollup</code>/<code>rollup</code> give an epic view and rollups (count, points, progress toward the <code>done</code> columns). A card can pop out a nested grid of its children (an epic's stories, a story's tasks, recursively) via a <code>childrenProperty</code> and/or <code>loadChildren(card)</code>: the child is a full composed <code>createGrid</code> (or, with <code>asBoard</code>, a nested board) opened in a drawer/modal/inline container — reuse by composition, no grid-core coupling — emitting <code>card:expand</code>/<code>card:drill</code>. Live updates arrive through the same keyed-diff contract a grid uses, so a Data Router drives the board directly (<code>attach(board, predicate)</code>); a live <code>rows.apply</code> re-renders preserving scroll, focus, selection, collapse and any open pop-out. <code>virtualize</code> renders only a scroll window of a tall column; <code>getState</code>/<code>setState</code> (and <code>config.state</code>) save and restore collapse, order, filter and sprint/epic selection; <code>setLoading</code>/<code>setError</code> give loading and error states. The move is fully keyboard-driven — Space to grab, arrows for column/position, Alt+Up/Down across swimlanes, Space/Enter to drop, Escape to cancel — announced on a live region. A field opted in with <code>card: { title: { field, edit: true } }</code> edits inline (double-click or <code>editCard</code>): grid-bound through the grid's own field editor via its public edit path, standalone through a host editor factory or a default input with an <code>onCardEdit</code> revert; a per-column add-card (<code>config.addCard</code>/<code>onAddCard</code>, or <code>grid.edit.addRow</code>) creates a card and opens it in edit. The module imports nothing from the grid's DOM package.</td></tr>
           <tr><td class="name">createKPI</td><td class="desc">A KPI / stat-tile view (module <code>kpi</code>) of a dataset as a panel of aggregate tiles — each tile a <code>sum</code>, <code>avg</code>, <code>min</code>, <code>max</code>, <code>count</code>, <code>countDistinct</code> or a <code>custom</code> reducer over the routed rows, with an optional <code>filter</code> predicate, number <code>format</code> (<code>number</code>/<code>currency</code>/<code>percent</code>/<code>compact</code>), a <code>baseline</code> for a delta, semantic threshold bands (<code>thresholds</code> with two cut points and a direction, or an explicit <code>bands</code> list, giving a <code>good</code>/<code>warn</code>/<code>critical</code> status kept separate from any accent), and an optional <code>sparkline</code> series. It is a dataset viewer like any other: it consumes data through the same keyed-diff <code>rows.apply({ add, update, remove })</code> contract a grid exposes, so a Data Router can <code>attach(value, kpi)</code> and drive a KPI panel beside a grid, a kanban and a chart off one feed. Updates are incremental — a delta adjusts each tile's running accumulator by only the rows it carries (an add contributes, a remove reverses, an update reverses-then-contributes), the two bounded exceptions being a <code>min</code>/<code>max</code> whose current extreme is removed (a rescan of that tile's own value multiset) and a <code>custom</code> reducer (recomputed over the filtered store, an arbitrary function having no inverse). Each tile is a labelled <code>&lt;figure&gt;</code>, focusable and keyboard-activatable, its value announced, the sparkline respecting <code>prefers-reduced-motion</code>; a <code>tile:click</code> event (also from the keyboard) lets a host drill down or filter a routed grid. Pass <code>null</code> as the element for a headless panel that computes the same tile model without a DOM. Not a dashboard layout engine (that is the parked dashboard generator) and no charting beyond the minimal sparkline (that is the charts module).</td></tr>
           <tr><td class="name">createAI</td><td class="desc">Create an AI narrative / insights controller (module <code>ai</code>) over a live grid. It produces a short, plain-language narrative of the grid's <em>computed</em> figures — a per-KPI / per-chart / per-column <code>explain</code>, or an <code>insights</code> panel over the current filtered view. The grid makes no AI call of its own: <code>createAI</code> imports no provider SDK, holds no key, and makes no network request; it calls one host callback, <code>ask({ system, messages, prompt, tools?, schema?, signal })</code> — your model, your key, your privacy decision — the same philosophy as the data adapters. Two grounding paths feed one guard: where the provider offers tool-use the model is given a curated read-only tool set (<code>getSchema</code>, <code>getProfile</code>, <code>getStatistics</code>, <code>getForecast</code>, <code>runQuery</code>) and the grid's own engine computes what it asks for; otherwise the module builds a facts packet from <code>grid.statistics</code>/the profile/forecasts/view counts and passes it in the prompt. Every figure in the narrative is reconciled against the values the engine produced this render — an ungrounded number is stripped before display (the number-reconciliation guard), so a hallucinated figure never reaches the user. The prompt is constrained to narrate-only; the layer is read-only and never mutates data. <code>redact</code> (a column id, a list, or a predicate) and <code>maxRows</code> bound what the module hands <code>ask()</code>, and the module sends nothing itself; an <code>ask()</code> error surfaces a friendly message and the grid stays fully usable, AI being additive rather than load-bearing. Complementary to <code>grid.ai</code> (the intent/plan skill layer): pass no <code>ask</code> and it adopts the grid's configured <code>ai.ask</code>, running the facts-packet path over it. Pass a headless grid for a DOM-free narrative; <code>facts(target)</code> returns the exact grounded packet without calling <code>ask()</code>. UMD global <code>LatticeGridAI</code>.</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">createTabs</td><td class="desc">Create a tabbed grid (module <code>tabs</code>): a <code>role="tablist"</code> strip above a stack of <code>role="tabpanel"</code> regions, each hosting its own, independently-configured <code>createGrid</code> instance — "configure each tab as per a normal grid" rather than one grid whose state is swapped (<code>ColumnModel#applyState</code> only repositions/hides/resizes existing columns by id; it carries no field, type or row data, so a state-swap only works when every tab shares one schema). <code>createGrid</code> is injected (<code>createTabs(el, { createGrid, tabs })</code>), the same pattern the React/Vue/Svelte adapters use, so the module imports no engine code and adds nothing to a page that does not load it. A tab that names <code>from: '&lt;tabId&gt;'</code> gets a <code>source: { mode: 'derived', from: &lt;the parent tab’s live grid&gt;, where, group, join, … }</code> wired for it automatically — reusing the shipped derived-source mechanism rather than a new config-inheritance one — and activating a derived tab materialises its whole ancestor chain first; a cyclic <code>from</code> graph is refused (naming the exact cycle) when <code>createTabs</code> is called, not at first click. A tab’s grid mounts on first activation and then stays alive, hidden, so its scroll/selection/filters/sort/grouping/expansion — and an open cell/row editor, left exactly as it was, uncommitted and undiscarded — survive a switch natively; <code>destroy()</code> tears every mounted tab down. The strip is a real tablist with <code>aria-selected</code>, a roving <code>tabindex</code>, and manual-activation keyboard handling (arrows/Home/End move focus, Enter/Space or a click activates). Events: <code>tab:changed</code>, a cancellable <code>beforeTabChange</code> paired with <code>tabChange:cancelled</code>. UMD global <code>LatticeGridTabs</code>.</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">createGantt</td><td class="desc">Create a project-planning Gantt controller (module <code>gantt</code>) over a task list and a dependency list. A CPM engine (<code>computeSchedule</code>) computes each task's early/late start and finish, its slack and the zero-float critical path, honouring the four link types (<code>LINK_TYPES</code>: FS/SS/FF/SF) with lag, and recomputes on every edit — emitting <code>schedule</code> or, on a dependency cycle or bad input, <code>error</code> (a code from <code>SCHEDULE_ERROR</code>). Milestones are zero-duration points; summary (WBS) tasks are derived from their children (earliest start, latest finish, weighted progress) rather than scheduled; <code>findViolations</code> flags a task placed earlier than its predecessors allow, and <code>toISODate</code> maps an engine day-number back to a calendar date.</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>

package/lattice-grid.d.ts

@@ -1,5 +1,5 @@
 /*!
- * Lattice Grid 1.48.0, type declarations
+ * Lattice Grid 1.50.0, type declarations
  * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
  * https://latticegrid.dev
  */
@@ -729,6 +729,12 @@ export interface Column {
   shadow?: ShadowKind | {
     of?: string;
     kind: ShadowKind;
+    /**
+     * For `kind: 'history'`, how many past readings to keep (20 by default). With
+     * a time `window` (BACKLOG-0001043) this is instead how many buckets the span
+     * divides into — `window: {kind: 'time', span: 60_000}, depth: 20` is sixty
+     * one-second buckets. Ignored by every other kind.
+     */
     depth?: number;
     /**
      * For a positional kind, what to rank against. `'all'` (the default) uses
@@ -768,6 +774,16 @@ export interface Column {
      * (`time`), or everything so far (`session`). The first rows of a series
      * carry a partial window, stamped by a `windowCoverage` companion rather than
      * dressed as full.
+     *
+     * For `kind: 'history'` (BACKLOG-0001043), only `{kind: 'time', span}` (or
+     * `minutes`) applies, and it changes what `history` means rather than what it
+     * aggregates: the `depth` buckets that span divides into are read once each,
+     * carrying the row's last known value forward into any bucket in which it did
+     * not change, so a static row still draws a flat, advancing line instead of
+     * freezing — the plain count-based history (no `window`) is a count of
+     * *changes* and stays exactly as it was. `count` and `session` are refused
+     * here: a plain count is already what `depth` means, and a session has no
+     * fixed span to divide into buckets.
      */
     window?: {
       kind: 'count' | 'time' | 'session';
@@ -1145,6 +1161,41 @@ export interface StreamSourceConfig {
    * rather than what the producer sends.
    */
   maxRows?: number;
+  /**
+   * The longest a row is kept, in milliseconds — a rolling *time* window, sitting
+   * beside `maxRows` as a second, independent bound (BACKLOG-0001036). Rows older
+   * than the span are evicted through the same path, the same `evicted` counters
+   * and the same `stream:evicted` event as the count bound, so an existing
+   * readout keeps working. Set both and whichever bites first applies. Eviction
+   * continues on a low-frequency timer while the feed is idle, so "the last five
+   * minutes" keeps shrinking through a silent period rather than freezing —
+   * which is the thing `maxRows` cannot do.
+   *
+   * Retention is a *bound, not a guillotine*: rows live a little past the span
+   * before a block is dropped. Two things add to it. First the eviction slack,
+   * ten per cent of the span, exactly as `maxRows` overshoots its count, so the
+   * row permutation is rebuilt once per block rather than once per row. Second,
+   * when the feed is idle, up to one tick of the eviction timer, which runs at a
+   * quarter of the span clamped to between 50 ms and one second. So the real
+   * ceiling is roughly `span * 1.1 + tick`, and because the tick has a floor it
+   * is proportionally larger the shorter the window: negligible at a five-minute
+   * window (about 10%), around 1.25x at ten seconds, and as much as ~1.35x at
+   * three. That is the deliberate trade for an idle grid that costs no CPU.
+   *
+   * Omit for no age limit.
+   */
+  maxAge?: number;
+  /**
+   * Which clock `maxAge` reads: a column id (or dotted path), or a function of
+   * the row returning a `Date`, epoch milliseconds, or an ISO string
+   * (BACKLOG-0001036). Given, the window follows the **data's own** clock, so it
+   * means what the producer means — and inherits the producer's clock skew.
+   * Omitted, `maxAge` falls back to **arrival time**: when the row reached this
+   * source. Arrival time needs no timestamp column and cannot be skewed, but it
+   * is not event time — a row delayed in transit counts as young. A row whose
+   * time value cannot be read is never aged out.
+   */
+  ageBy?: string | ((row: unknown) => unknown);
   promoteToMemoryBelow?: number;
   coalesceMs?: number;
 }
@@ -6238,6 +6289,19 @@ export interface ChartAxis {
   every?: number;
   /** Force the category labels' rotation rather than deciding it. */
   rotate?: boolean | 'auto';
+  /**
+   * A rolling window for the axis domain (BACKLOG-0001036), in the shipped
+   * `WindowSpec` vocabulary that rolling statistics already use. Only
+   * `{ kind: 'time', span }` applies to an axis: the domain becomes the last
+   * `span` milliseconds ending **now**, so the chart keeps scrolling left while
+   * the feed is silent — the thing a count window cannot do, because with no
+   * rows arriving nothing changes. Advanced on a low-frequency clock (a quarter
+   * of the window, between 50 ms and 1 s), never per frame, and stopped when the
+   * chart is destroyed or its document is hidden. Needs a continuous x axis
+   * carrying wall-clock times; `{ kind: 'count' }` is the source's `maxRows` and
+   * is refused here rather than given a second meaning.
+   */
+  window?: Pick<WindowSpec, 'kind' | 'span'>;
 }
 
 /**
@@ -8760,3 +8824,108 @@ declare module 'lattice-grid/modules/ai' {
 
   export default createAI;
 }
+
+declare module 'lattice-grid/modules/tabs' {
+  /**
+   * One tab: an id, a display label, a grid config, and — for a derived tab —
+   * the parent tab id plus the narrowing forwarded onto the derived source
+   * built for it (`source: { mode: 'derived', from: <parent's grid>, ... }`).
+   * The derivation keys are the ones `packages/core/src/source/derive.js`
+   * already understands; this module invents none of its own.
+   */
+  interface TabDescriptor {
+    /** A stable, unique id. Required. */
+    id: string;
+    /** The tab button's text. Defaults to `id`. */
+    label?: string;
+    /** The grid config passed to `createGrid` for this tab (merged with the derived `source`, when `from` is set). */
+    config?: object;
+    /** The parent tab id to derive from. When set, `config.source` is built for you and any of your own is replaced (with a warning). */
+    from?: string;
+    /** Row predicate forwarded to the derived source. */
+    where?: (row: unknown) => boolean;
+    /** Group-by forwarded to the derived source. */
+    group?: unknown;
+    groupBy?: unknown;
+    /** Time-bucketing forwarded to the derived source. */
+    bucket?: unknown;
+    /** Join spec forwarded to the derived source. */
+    join?: unknown;
+    /** Array-field unnesting forwarded to the derived source. */
+    unnest?: unknown;
+    /** `'live' | 'idle' | 'manual' | number` forwarded to the derived source. */
+    refresh?: 'live' | 'idle' | 'manual' | number;
+    /** Cross-filter wiring forwarded to the derived source. */
+    crossFilter?: unknown;
+    /** Which slice of the parent's rows to derive from: `'filtered' | 'all' | 'selected' | 'grouped'`. */
+    follow?: 'filtered' | 'all' | 'selected' | 'grouped';
+    /** Row limit forwarded to the derived source. */
+    limit?: number;
+    /** Sort forwarded to the derived source. */
+    sort?: unknown;
+    /** Statistical-profile derivation, forwarded to the derived source. */
+    profile?: unknown;
+    /** This tab's panel's own `aria-label`, when the label alone is not enough context. */
+    ariaLabel?: string;
+  }
+
+  /** The payload every tab-change event carries. */
+  interface TabChangeEvent {
+    id: string;
+    previousId: string | null;
+    origin?: 'api' | 'user' | 'init';
+    reason?: string | null;
+    /** Cancel the switch (only meaningful on `beforeTabChange`). */
+    preventDefault?: (reason?: string) => void;
+    defaultPrevented?: boolean;
+  }
+
+  /** Tabbed-grid configuration. */
+  interface TabsConfig {
+    /** The grid factory to mount each tab with, e.g. `import { createGrid } from 'lattice-grid'`. Required. */
+    createGrid: (el: HTMLElement, config: object) => unknown;
+    /** The tabs, in display order. Required, at least one. */
+    tabs: TabDescriptor[];
+    /** The initially active tab id. Defaults to the first tab. */
+    active?: string;
+    /** The tablist landmark's accessible name. */
+    ariaLabel?: string;
+    /** An explicit message-catalogue override; otherwise a mounted tab's own `grid.messages` is used. */
+    messages?: { t(key: string, params?: Record<string, unknown>): string };
+    onTabChange?: (event: TabChangeEvent) => void;
+    onBeforeTabChange?: (event: TabChangeEvent) => boolean | void | Promise<boolean>;
+    onTabChangeCancelled?: (event: TabChangeEvent) => void;
+  }
+
+  /**
+   * A tabbed grid: a `role="tablist"` strip above a stack of `role="tabpanel"`
+   * regions, each hosting its own, independently-configured grid instance
+   * (BACKLOG-0001039). A tab's grid mounts on first activation and is kept
+   * alive, hidden, until `destroy()`.
+   */
+  interface Tabs {
+    readonly el: HTMLElement;
+    /** The currently active tab id. */
+    readonly activeId: string;
+    /** The configured tab ids, in order. */
+    tabs(): string[];
+    /** The live grid instance for a tab, or `null` before it has been materialised. */
+    tab(id: string): unknown | null;
+    /** Whether a tab's grid has been created yet. */
+    isMounted(id: string): boolean;
+    /** Switch the active tab, gated by `beforeTabChange`. */
+    activate(id: string, opts?: { origin?: 'api' | 'user' }): boolean | Promise<boolean>;
+    on(name: 'beforeTabChange' | 'tab:changed' | 'tabChange:cancelled' | string, fn: (event: TabChangeEvent) => void): () => void;
+    off(name: string, fn: (event: TabChangeEvent) => void): void;
+    /** Tear the whole strip down; destroys every mounted tab's grid. */
+    destroy(): void;
+  }
+
+  /**
+   * Create a tabbed grid over a host element. Each tab is a full,
+   * independently-configured grid instance; a tab may derive from another via
+   * `from`, reusing the shipped `source: { mode: 'derived' }` mechanism.
+   */
+  export function createTabs(el: HTMLElement, config: TabsConfig): Tabs;
+  export default createTabs;
+}