@toclocoinc/lattice-grid 1.39.0 → 1.42.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.39.0 · [latticegrid.dev](https://www.latticegrid.dev) · TOCLOCO Inc
+Version 1.42.0 · [latticegrid.dev](https://www.latticegrid.dev) · TOCLOCO Inc
 
 ---
 

package/docs/API.html

@@ -5268,6 +5268,66 @@ router.apply([{ op: 'delete', row: { id: 'd2' } }]);              <span class="c
 router.destroy();
 <span class="kw">return</span> [seeded, afterRemove, band].join(' | ');</code></pre>
 
+    <h2 id="ai">The AI narrative / insights layer</h2>
+    <p><code>modules/ai</code> is an opt-in layer that produces a short, plain-language <strong>narrative</strong> of the grid's <em>computed</em> figures &mdash; a per-KPI / per-chart / per-column &ldquo;Explain&rdquo;, or an insights panel over the current (filtered) view. It is a separate bundle that adds no weight to a page that does not load it, changes nothing in grid core, and pulls in no dependency. <strong>The grid makes no AI call of its own:</strong> <code>createAI</code> never imports a provider SDK, never reads a key, and never makes a network request. It calls one async callback you supply, <code>ask()</code> &mdash; your model, your key, your privacy decision &mdash; exactly the philosophy of the data adapters, where auth and transport are always the caller's.</p>
+    <pre><code>import { createAI } from '@toclocoinc/lattice-grid/modules/ai';
+
+const ai = createAI(grid, {
+  ask: async ({ system, messages, tools, schema, signal }) =&gt; {
+    const r = await myProvider.chat({ system, messages, tools, signal });
+    return { text: r.text, toolCalls: r.toolCalls };   <span class="cmt">// or a bare string</span>
+  },
+  maxRows: 50,                 <span class="cmt">// cap what any tool result carries to ask()</span>
+  redact: ['ssn', 'salary'],   <span class="cmt">// columns whose values never leave the browser</span>
+});
+
+ai.insights(document.querySelector('#insights'));                 <span class="cmt">// the panel</span>
+const { text, flagged } = await ai.explain({ kind: 'column', colId: 'amount' });</code></pre>
+    <p><strong>Grounded, and reconciled.</strong> Where your provider offers tool-use, the model is given a curated <strong>read-only</strong> tool set (<code>getSchema</code>, <code>getProfile</code>, <code>getStatistics</code>, <code>getForecast</code>, <code>runQuery</code>) and <em>our</em> engine computes what it asks for; where it does not, the module builds a <strong>facts packet</strong> from the grid's computed results (<code>grid.statistics</code>, the profile, forecasts, view counts) and passes it in the prompt. Either way, <strong>every figure in the narrative is reconciled against the values the engine produced this render</strong> &mdash; an ungrounded number is stripped before the user sees it. The prompt is constrained to narrate-only; the layer is read-only and never mutates data. <code>redact</code> 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 &mdash; AI is additive, never load-bearing.</p>
+    <p><code>createAI</code> is complementary to <code>grid.ai</code>: <code>grid.ai</code> is the intent/plan skill layer (a question becomes a validated filter/sort plan you preview and apply); <code>createAI</code> is the narrative/insights consumer that explains figures. They can share one host <code>ask()</code> &mdash; pass none to <code>createAI</code> and it adopts the grid's configured <code>ai.ask</code>, running the facts-packet path over it.</p>
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Member</th><th>Description</th></tr></thead>
+        <tbody>
+          <tr><td class="sig">createAI(grid, config)</td><td class="desc">Create an AI narrative / insights controller over a live grid (headless or rendered). Config: <code>ask</code> (the host callback; falls back to the grid's <code>ai.ask</code>), <code>enable</code>, <code>maxRows</code>, <code>redact</code>, <code>tools</code>, <code>locale</code>, <code>reconcile</code> (<code>'strip'</code>/<code>'flag'</code>), <code>element</code>, <code>onNarrative</code>, <code>onError</code>.</td></tr>
+          <tr><td class="sig">explain(target?, opts?) / narrate(...)</td><td class="desc">Produce a grounded, reconciled narrative. <code>target</code> is <code>{ kind: 'view' }</code>, <code>{ kind: 'column', colId }</code>, <code>{ kind: 'forecast', colId, options }</code>, or <code>{ kind: 'kpi'|'chart', facts }</code>. Resolves to <code>{ text, facts, grounded, flagged, rounds, mode }</code>.</td></tr>
+          <tr><td class="sig">insights(el?, opts?)</td><td class="desc">Mount (or re-target) the insights panel into an element, its generate control wired to a view narrative. Keeps the grid usable on an <code>ask()</code> error.</td></tr>
+          <tr><td class="sig">attachExplain(target, opts?)</td><td class="desc">Build an &ldquo;Explain&rdquo; button bound to a target (a KPI tile, a chart datum, a column). Clicking it narrates the target.</td></tr>
+          <tr><td class="sig">facts(target?, opts?)</td><td class="desc">Build the facts packet for a target <em>without</em> calling <code>ask()</code> &mdash; the exact grounded set a narrative would use, and what would leave the browser.</td></tr>
+          <tr><td class="sig">on(name, fn) / off(name, fn) / destroy()</td><td class="desc">Events: <code>narrative</code> and <code>error</code>. <code>destroy()</code> tears the controller down and leaves the grid untouched.</td></tr>
+        </tbody>
+      </table>
+    </div>
+    <h3 id="ai-reconcile-example">Grounded, with the reconciliation guard, executed</h3>
+    <p class="section-note">A mock <code>ask()</code> returns one grounded figure (the row count) and one invented one.
+    The number-reconciliation guard strips the ungrounded figure and keeps the grounded one. Run headless on every build.</p>
+    <pre data-run="js" data-expect="1 flagged | true kept | true stripped" data-covers="export:createAI"><code><span class="kw">const</span> { createHeadlessGrid } = <span class="kw">await</span> import('../packages/core/src/index.js');
+<span class="kw">const</span> { createAI } = <span class="kw">await</span> import('../packages/modules/ai/index.js');
+
+<span class="kw">const</span> grid = createHeadlessGrid({
+  rowKey: 'id',
+  columns: [{ field: 'id' }, { field: 'region' }, { field: 'amount', type: 'number' }],
+  rows: [
+    { id: 1, region: 'EMEA', amount: 100 },
+    { id: 2, region: 'AMER', amount: 300 },
+    { id: 3, region: 'APAC', amount: 200 },
+  ],
+});
+
+<span class="cmt">// Your model, your key. The grid makes no network call — it awaits this.</span>
+<span class="cmt">// This mock returns one grounded figure (3 rows) and one invented one (900%).</span>
+<span class="kw">const</span> ask = <span class="kw">async</span> () =&gt; ({ text: 'There are 3 rows in view. Confidence 900%.' });
+
+<span class="kw">const</span> ai = createAI(grid, { ask, tools: <span class="kw">false</span> });
+<span class="kw">const</span> result = <span class="kw">await</span> ai.explain({ kind: 'view' });
+
+<span class="kw">const</span> kept = result.text.includes('3 rows');      <span class="cmt">// grounded — survives</span>
+<span class="kw">const</span> stripped = !result.text.includes('900%');   <span class="cmt">// hallucinated — removed</span>
+
+ai.destroy();
+grid.destroy();
+<span class="kw">return</span> `${result.flagged.length} flagged | ${kept} kept | ${stripped} stripped`;</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';
@@ -6287,6 +6347,38 @@ const rows = stream.map((temp, t) =&gt; ({ t, temp }));
 const signal = condition(rows);
 return `methods ${ROLLING_ANOMALY_METHODS.length}; spike ${roll.flags[10]}; alert ${signal ? signal.flagged.length : 0}`;</code></pre>
 
+    <h3 id="forecasting">Forecasting</h3>
+    <p class="section-note">Project an ordered series forward, and carry a prediction band where a defensible closed form exists (BACKLOG-0000963). Five methods behind one entry point: <code>movingAverage</code> and <code>ses</code> are flat forecasts (the trailing-window mean, the final smoothed level); <code>holt</code> adds a projected trend, <code>holtWinters</code> a projected trend and an additive seasonal; <code>linear</code> extrapolates an ordinary least-squares fit of the time axis. The exponential-smoothing bands are the innovations state-space forecast variances (Hyndman &amp; Athanasopoulos) at the normal quantile; the linear and moving-average bands are the exact Student-t intervals, and <code>linear</code> also reports the narrower mean-response (confidence) band a trendline draws. These are the pure kernels the chart trendline overlay and the time-series grid forecast from; a host can forecast a plain array the same way.</p>
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Name</th><th>Signature</th><th>Description</th></tr></thead>
+        <tbody>
+          <tr><td class="name">FORECAST_METHODS</td><td class="type">readonly ('movingAverage' | 'ses' | 'holt' | 'holtWinters' | 'linear')[]</td><td class="desc">The five methods a caller may ask for, named so a result can say which produced it.</td></tr>
+          <tr><td class="name">forecast</td><td class="type">(seq, opts?) =&gt; ForecastResult | null</td><td class="desc">Forecast an ordered series <code>opts.horizon</code> steps ahead by <code>opts.method</code> (default <code>linear</code>), at <code>opts.confidence</code> (default 0.95). Accepts a plain array of numbers (index is the time axis) or <code>{at, value}</code> rows. A smoothing factor absent from <code>opts</code> (<code>alpha</code>/<code>beta</code>/<code>gamma</code>) is fit by minimising the in-sample one-step SSE; <code>holtWinters</code> needs <code>opts.period</code> (≥ 2) and two whole periods of data. Each point carries <code>mean</code> and, where a band applies, <code>lower</code>/<code>upper</code>; <code>linear</code> adds <code>lowerMean</code>/<code>upperMean</code>. Null when the series is too short for the method.</td></tr>
+        </tbody>
+      </table>
+    </div>
+    <pre data-run="js" data-expect="methods 5; next 5.8; r2 0.6; band 1.68..9.92; season 63.125" data-covers="export:FORECAST_METHODS export:forecast"><code>const { forecast, FORECAST_METHODS } = await import('../packages/core/src/index.js');
+// Linear: fit the time axis, project one step, and carry the prediction band.
+const lin = forecast([{ at: 1, value: 2 }, { at: 2, value: 4 }, { at: 3, value: 5 }, { at: 4, value: 4 }, { at: 5, value: 5 }], { method: 'linear', horizon: 1 });
+const p = lin.points[0];
+// Holt-Winters additive: a level, a trend and a two-step season, projected two
+// steps ahead — the seasonal swing is carried into the forecast, not smoothed away.
+const hw = forecast([10, 20, 30, 40], { method: 'holtWinters', period: 2, alpha: 0.5, beta: 0.5, gamma: 0.5, horizon: 2 });
+return `methods ${FORECAST_METHODS.length}; next ${p.mean.toFixed(1)}; r2 ${lin.r2.toFixed(1)}; band ${p.lower.toFixed(2)}..${p.upper.toFixed(2)}; season ${hw.points[1].mean}`;</code></pre>
+
+    <p class="section-note">The same forecast off the standard stats surface: <code>grid.statistics.forecast(colId, opts)</code> reads the column over the filtered rows — ordered by <code>opts.by</code> when the time axis matters, exactly as <code>grid.statistics.series(...)</code> orders — and returns the same <code>ForecastResult</code>, so a host reaches a forecast the way it reaches <code>grid.statistics.anomalies(...)</code> rather than assembling the series itself.</p>
+    <pre data-run="js" data-expect="next 5.8; r2 0.6; band true" data-covers="method:statistics"><code>const { createHeadlessGrid } = await import('../packages/core/src/index.js');
+const grid = createHeadlessGrid({
+  columns: [{ field: 't', type: 'number' }, { field: 'v', type: 'number' }],
+  rows: [[1, 2], [2, 4], [3, 5], [4, 4], [5, 5]].map(([t, v], i) =&gt; ({ id: String(i), t, v })),
+  rowKey: 'id',
+});
+// Forecast the 'v' column one step ahead, ordered by 't', with the prediction band.
+const f = grid.statistics.forecast('v', { by: 't', method: 'linear', horizon: 1 });
+const p = f.points[0];
+return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.lower &gt; 0}`;</code></pre>
+
 
 <!-- BEGIN GENERATED TYPE REFERENCE -->
     <h2 id="type-reference">Type reference</h2>
@@ -7828,6 +7920,40 @@ return `methods ${ROLLING_ANOMALY_METHODS.length}; spike ${roll.flags[10]}; aler
         </tbody>
       </table>
     </div>
+    <h3 id="type-ForecastPoint">ForecastPoint</h3>
+    <p class="section-note">One forecast step: the point estimate and, where a band applies, its interval.</p>
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Member</th><th>Type</th><th>Description</th></tr></thead>
+        <tbody>
+          <tr><td class="name">step</td><td class="type">number</td><td class="desc">The step ahead, `1 … horizon`.</td></tr>
+          <tr><td class="name">at</td><td class="type">number</td><td class="desc">The time-axis position the step is stamped at, extrapolated at the mean spacing.</td></tr>
+          <tr><td class="name">mean</td><td class="type">number</td><td class="desc">The point forecast.</td></tr>
+          <tr><td class="name">lower</td><td class="type">number | null</td><td class="desc">The prediction-interval lower bound (a future observation), or null when none applies.</td></tr>
+          <tr><td class="name">upper</td><td class="type">number | null</td><td class="desc">The prediction-interval upper bound, or null when none applies.</td></tr>
+          <tr><td class="name">lowerMean</td><td class="type">number | null</td><td class="desc">The mean-response (confidence) lower bound — `linear` only, the band a trendline draws. <small>(optional)</small></td></tr>
+          <tr><td class="name">upperMean</td><td class="type">number | null</td><td class="desc">The mean-response (confidence) upper bound — `linear` only. <small>(optional)</small></td></tr>
+          <tr><td class="name">se</td><td class="type">number | null</td><td class="desc">The prediction standard error the band was built from, or null when none applies.</td></tr>
+        </tbody>
+      </table>
+    </div>
+    <h3 id="type-ForecastResult">ForecastResult</h3>
+    <p class="section-note">A forecast: the chosen model, its parameters, and the projected points.</p>
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Member</th><th>Type</th><th>Description</th></tr></thead>
+        <tbody>
+          <tr><td class="name">method</td><td class="type">'movingAverage' | 'ses' | 'holt' | 'holtWinters' | 'linear'</td><td class="desc">Which method produced it.</td></tr>
+          <tr><td class="name">horizon</td><td class="type">number</td><td class="desc">How many steps ahead were projected.</td></tr>
+          <tr><td class="name">confidence</td><td class="type">number</td><td class="desc">The band level, e.g. 0.95.</td></tr>
+          <tr><td class="name">n</td><td class="type">number</td><td class="desc">How many finite readings the fit used.</td></tr>
+          <tr><td class="name">sigma</td><td class="type">number | null</td><td class="desc">The residual standard deviation the bands were built from, or null when there was none.</td></tr>
+          <tr><td class="name">r2</td><td class="type">number</td><td class="desc">The fit's coefficient of determination — `linear` only. <small>(optional)</small></td></tr>
+          <tr><td class="name">params</td><td class="type">{</td><td class="desc">The model parameters: `slope`/`intercept` (linear), `alpha`/`beta`/`gamma`/`period`, or `windowLen`.</td></tr>
+          <tr><td class="name">points</td><td class="type">ForecastPoint[]</td><td class="desc">The forecast, one entry per step.</td></tr>
+        </tbody>
+      </table>
+    </div>
     <h3 id="type-FormattingApi">FormattingApi</h3>
     <div class="table-wrap">
       <table>
@@ -8268,6 +8394,8 @@ return `methods ${ROLLING_ANOMALY_METHODS.length}; spike ${roll.flags[10]}; aler
         <tbody>
           <tr><td class="name">preview</td><td class="type">(text: string, opts?: object): ImportPreview</td><td class="desc">Parse delimited text into a preview, changing nothing.</td></tr>
           <tr><td class="name">csv</td><td class="type">(text: string, opts?: object): Record&lt;string, unknown&gt;[]</td><td class="desc">Parse delimited text into coerced records — the inverse of `export.csv`.</td></tr>
+          <tr><td class="name">previewXlsx</td><td class="type">(bytes: Uint8Array | ArrayBuffer, opts?: object): Promise&lt;ImportXlsxPreview&gt;</td><td class="desc">Parse an `.xlsx` file's bytes into a preview, changing nothing (§14, BACKLOG-0000970). Async: the archive is inflated with `DecompressionStream`.</td></tr>
+          <tr><td class="name">xlsx</td><td class="type">(bytes: Uint8Array | ArrayBuffer, opts?: object): Promise&lt;Record&lt;string, unknown&gt;[]&gt;</td><td class="desc">Parse an `.xlsx` file's bytes into coerced records — the inverse of `export.excel`.</td></tr>
           <tr><td class="name">apply</td><td class="type">(</td><td class="desc">Add or replace the grid's rows from text, a preview or records.</td></tr>
         </tbody>
       </table>
@@ -8316,6 +8444,22 @@ return `methods ${ROLLING_ANOMALY_METHODS.length}; spike ${roll.flags[10]}; aler
         </tbody>
       </table>
     </div>
+    <h3 id="type-ImportXlsxPreview">ImportXlsxPreview</h3>
+    <p class="section-note">What an `.xlsx` preview carries — an {@link ImportPreview} plus the sheet read (§14).</p>
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Member</th><th>Type</th><th>Description</th></tr></thead>
+        <tbody>
+          <tr><td class="name">sheet</td><td class="type">string | null</td><td class="desc">The archive path of the worksheet that was read, e.g. `xl/worksheets/sheet1.xml`.</td></tr>
+          <tr><td class="name">header</td><td class="type">string[]</td><td class="desc">The source column headings.</td></tr>
+          <tr><td class="name">columns</td><td class="type">ImportColumn[]</td><td class="desc">The per-column mapping and inference the user may edit before confirming.</td></tr>
+          <tr><td class="name">records</td><td class="type">Record&lt;string, unknown&gt;[]</td><td class="desc">Every mapped, coerced record the import would add.</td></tr>
+          <tr><td class="name">sample</td><td class="type">Record&lt;string, unknown&gt;[]</td><td class="desc">The leading records, for a preview table.</td></tr>
+          <tr><td class="name">rowCount</td><td class="type">number</td><td class="desc">How many data rows the sheet holds.</td></tr>
+          <tr><td class="name">warnings</td><td class="type">string[]</td><td class="desc">Anything worth flagging before confirming.</td></tr>
+        </tbody>
+      </table>
+    </div>
     <h3 id="type-IngestConfig">IngestConfig</h3>
     <p class="section-note">How rows are ingested into the column store.</p>
     <div class="table-wrap">
@@ -9431,6 +9575,7 @@ return `methods ${ROLLING_ANOMALY_METHODS.length}; spike ${roll.flags[10]}; aler
           <tr><td class="name">capability</td><td class="type">(colId: string, opts?: {</td><td class="desc">Process capability against the column's `spec`, with control limits and the Western Electric rule breaks. `baseline` fixes the limits over the first N readings, which is how a shift is found rather than hidden by the limits it widened.</td></tr>
           <tr><td class="name">interval</td><td class="type">(colId: string, opts?: {</td><td class="desc">A confidence interval for what a column measures, the range the estimate pins the figure down to, not a verdict about it. Reads the rows the filters left, so an interval narrows as the grid does: it describes the filtered population, not the whole table.</td></tr>
           <tr><td class="name">series</td><td class="type">(colId: string, opts: { by: string; periodsPerYear?: number }): SeriesStats | null</td><td class="desc">How a column varies along an ordering. `by` is required and never guessed: kernels see rows in the order they arrived, which is not the grid's sort.</td></tr>
+          <tr><td class="name">forecast</td><td class="type">(colId: string, opts?: {</td><td class="desc">Forecast one column forward (BACKLOG-0000963): the stats-surface face of the {@link forecast} kernel. The column is read over the filtered rows in arrival order, or ordered by `opts.by` (a date or numeric column, as {@link series} orders) when the time axis matters, then projected `opts.horizon` steps ahead by `opts.method` (default `linear`) with a prediction band where one applies. Every kernel option passes through; returns the same {@link ForecastResult}, or null when the column is unknown or too short.</td></tr>
           <tr><td class="name">weightedAverage</td><td class="type">(colId: string, weightId: string): number | null</td><td class="desc">A weighted average of one column by another.</td></tr>
           <tr><td class="name">keyOf</td><td class="type">(data: unknown): string | null</td><td class="desc">The key a row's data resolves to.</td></tr>
           <tr><td class="name">maintenance</td><td class="type">Readonly&lt;Record&lt;string, 'maintained' | 'rescan'&gt;&gt;</td><td class="desc">Which reductions can be maintained against a change, and which rescan. <small>(read-only)</small></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.39.0</p>
+    <p class="rail__sub">Developer guide · v1.42.0</p>
     <nav>
       <div class="rail__group">
         <span class="rail__label">Start here</span>
@@ -6343,6 +6343,7 @@ grid.import.apply(preview);</code></pre>
           <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. By default routing is first-match-wins (<code>overlap: false</code>); to fan one partition value to several viewers at once (a grid <em>and</em> a KPI panel <em>and</em> a chart off one feed) create the router with <code>overlap: true</code> — with the default, a second viewer on the same value receives nothing and the router emits a one-time dev warning naming the clash. 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. v5 adds wedge-conversion primitives: <code>subscribe(value, handler)</code> routes a slice to any non-grid view (KPI tile, detail pane, map, form) as the same keyed diff a grid gets; <code>alert(value, condition, handler)</code> evaluates a condition over a slice and emits (edge-triggered, debounced) rather than rendering; and <code>configure(spec)</code> (or <code>createDataRouter({ config })</code>) takes the whole routing graph as one declarative data spec that desugars to the imperative API and composes with it. v3 also adds per-route reshaping — <code>transform</code>/<code>filter</code>/<code>sort</code> and <code>rollup</code> ({ groupBy, aggregate }) summaries — a relationship graph (<code>relate(edges)</code>: multi-hop, several-into-one AND, and mutual edges) that scales v2's pairwise <code>link</code>, and stream hygiene: a <code>seq</code>/version orders and de-duplicates a feed (stale/duplicate deltas dropped, counted in <code>dropped</code>), <code>push</code> with a <code>batch</code>/<code>coalesce</code> buffers a high-frequency feed (<code>flushStream</code> for a deterministic point), and <code>lastSeq</code>/<code>checkpoint</code>/<code>seenThrough</code> resume precisely after a dropped socket. v4 adds time-travel: <code>buffer({ window, max })</code> records the ordered stream into a bounded ring over a moving base, so <code>scrubTo</code> reconstructs a past point, <code>replay</code> (with <code>pause</code>/<code>resume</code>) walks a range, and <code>live</code> returns to the head — every state pushed by the same keyed diff, <code>traveling</code>/<code>buffered</code> reporting the state. v6 adds cross-tab sync: <code>broadcast({ channel })</code> mirrors the ordered, de-duplicated deltas to other tabs/windows over a BroadcastChannel with no echo loop, a popped-out grid joining the same feed with no second socket and resyncing mid-stream via the reconnect path. v7 adds query-slice routing: <code>query(adapter, request)</code> sources the router from a DFQL/DuckDB (or any pushdown) adapter, partitioning one result across the routes; a route-level <code>where</code> is pushed down where the adapter's capabilities allow and the residual finished client-side, with <code>lastQueryPlan</code> reporting the split. v8 adds write-back: a <code>writable</code> route captures the grid's committed edits off its public edit surface and routes them to <code>onWrite(change, ctx)</code> (per-route or router-global), reverting on reject, re-entering an accepted write as a delta, and surfacing a last-write-wins <code>onConflict</code>; a derived route cannot be writable. v9 adds fan-in: <code>addSource(feed, { map, key })</code> returns a per-feed handle (<code>load</code>/<code>apply</code>/<code>push</code>/<code>remove</code>) whose rows are normalized and namespaced so many feeds merge into one keyed store without id collisions, <code>removeSource</code> dropping exactly a feed's rows and <code>sources</code> listing them. v10 adds observability: <code>metrics()</code> is a cheap snapshot of per-route/per-source counts and throughput plus the global unrouted/dropped/buffered/lag figures, <code>on('metrics')</code> drives a periodic emit (off unless a listener is registered), and <code>mountDevtools(el)</code> renders a live panel from the module's own DOM file. Detaches its grids on <code>destroy</code>; the host owns them.</td></tr>
           <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">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>

package/lattice-grid.d.ts

@@ -1,5 +1,5 @@
 /*!
- * Lattice Grid 1.39.0, type declarations
+ * Lattice Grid 1.42.0, type declarations
  * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
  * https://latticegrid.dev
  */
@@ -2774,6 +2774,22 @@ export interface StatisticsApi {
    * kernels see rows in the order they arrived, which is not the grid's sort.
    */
   series(colId: string, opts: { by: string; periodsPerYear?: number }): SeriesStats | null;
+  /**
+   * Forecast one column forward (BACKLOG-0000963): the stats-surface face of the
+   * {@link forecast} kernel. The column is read over the filtered rows in arrival
+   * order, or ordered by `opts.by` (a date or numeric column, as {@link series}
+   * orders) when the time axis matters, then projected `opts.horizon` steps ahead
+   * by `opts.method` (default `linear`) with a prediction band where one applies.
+   * Every kernel option passes through; returns the same {@link ForecastResult},
+   * or null when the column is unknown or too short.
+   */
+  forecast(colId: string, opts?: {
+    method?: 'movingAverage' | 'ses' | 'holt' | 'holtWinters' | 'linear';
+    horizon?: number; confidence?: number; windowLen?: number;
+    alpha?: number; beta?: number; gamma?: number; period?: number;
+    /** The column to order by before forecasting — a date or numeric axis. */
+    by?: string;
+  }): ForecastResult | null;
   /** A weighted average of one column by another. */
   weightedAverage(colId: string, weightId: string): number | null;
   /** The key a row's data resolves to. */
@@ -2989,6 +3005,80 @@ export function anomalyCondition(
 ): (rows: Iterable<Record<string, unknown>>) =>
   false | { method: string; field: string; flagged: { row: Record<string, unknown>; score: number | null }[] };
 
+/**
+ * The forecasting methods a caller may ask for (BACKLOG-0000963), named so a
+ * result says which produced it: a trailing moving average, single / double
+ * (Holt) / triple (Holt-Winters) exponential smoothing, and a linear least-squares
+ * fit of the time axis.
+ */
+export const FORECAST_METHODS: readonly ('movingAverage' | 'ses' | 'holt' | 'holtWinters' | 'linear')[];
+
+/** One forecast step: the point estimate and, where a band applies, its interval. */
+export interface ForecastPoint {
+  /** The step ahead, `1 … horizon`. */
+  step: number;
+  /** The time-axis position the step is stamped at, extrapolated at the mean spacing. */
+  at: number;
+  /** The point forecast. */
+  mean: number;
+  /** The prediction-interval lower bound (a future observation), or null when none applies. */
+  lower: number | null;
+  /** The prediction-interval upper bound, or null when none applies. */
+  upper: number | null;
+  /** The mean-response (confidence) lower bound — `linear` only, the band a trendline draws. */
+  lowerMean?: number | null;
+  /** The mean-response (confidence) upper bound — `linear` only. */
+  upperMean?: number | null;
+  /** The prediction standard error the band was built from, or null when none applies. */
+  se: number | null;
+}
+
+/** A forecast: the chosen model, its parameters, and the projected points. */
+export interface ForecastResult {
+  /** Which method produced it. */
+  method: 'movingAverage' | 'ses' | 'holt' | 'holtWinters' | 'linear';
+  /** How many steps ahead were projected. */
+  horizon: number;
+  /** The band level, e.g. 0.95. */
+  confidence: number;
+  /** How many finite readings the fit used. */
+  n: number;
+  /** The residual standard deviation the bands were built from, or null when there was none. */
+  sigma: number | null;
+  /** The fit's coefficient of determination — `linear` only. */
+  r2?: number;
+  /** The model parameters: `slope`/`intercept` (linear), `alpha`/`beta`/`gamma`/`period`, or `windowLen`. */
+  params: {
+    slope?: number; intercept?: number;
+    alpha?: number; beta?: number; gamma?: number; period?: number; windowLen?: number;
+  };
+  /** The forecast, one entry per step. */
+  points: ForecastPoint[];
+}
+
+/**
+ * Forecast an ordered series `horizon` steps into the future (BACKLOG-0000963).
+ *
+ * `movingAverage` and `ses` are flat forecasts (the trailing-window mean, the
+ * final smoothed level); `holt` adds a projected trend, `holtWinters` a projected
+ * trend and an additive seasonal of period `opts.period`; `linear` extrapolates
+ * an ordinary least-squares fit of the time axis. A prediction band is carried
+ * where a defensible closed form exists — the exponential-smoothing bands are the
+ * innovations state-space forecast variances at the normal quantile; the linear
+ * and moving-average bands are the exact Student-t intervals, and `linear` also
+ * reports the narrower mean-response (confidence) band. A smoothing factor absent
+ * from `opts` is fit by minimising the in-sample one-step SSE. Returns null when
+ * the series is too short for the chosen method.
+ */
+export function forecast(
+  seq: ArrayLike<number | null> | { at?: number; value: number | null }[],
+  opts?: {
+    method?: 'movingAverage' | 'ses' | 'holt' | 'holtWinters' | 'linear';
+    horizon?: number; confidence?: number; windowLen?: number;
+    alpha?: number; beta?: number; gamma?: number; period?: number;
+  },
+): ForecastResult | null;
+
 export type ShadowKind =
   | 'updates' | 'updatedAt' | 'sinceUpdate' | 'delta' | 'deltaPercent'
   | 'rate' | 'history' | 'firstValue' | 'streak'
@@ -4186,12 +4276,37 @@ export interface ImportPreview {
   warnings: string[];
 }
 
+/** What an `.xlsx` preview carries — an {@link ImportPreview} plus the sheet read (§14). */
+export interface ImportXlsxPreview {
+  /** The archive path of the worksheet that was read, e.g. `xl/worksheets/sheet1.xml`. */
+  sheet: string | null;
+  /** The source column headings. */
+  header: string[];
+  /** The per-column mapping and inference the user may edit before confirming. */
+  columns: ImportColumn[];
+  /** Every mapped, coerced record the import would add. */
+  records: Record<string, unknown>[];
+  /** The leading records, for a preview table. */
+  sample: Record<string, unknown>[];
+  /** How many data rows the sheet holds. */
+  rowCount: number;
+  /** Anything worth flagging before confirming. */
+  warnings: string[];
+}
+
 /** Bringing rows in — the mirror of {@link ExportApi} (§14, BACKLOG-0000949). */
 export interface ImportApi {
   /** Parse delimited text into a preview, changing nothing. */
   preview(text: string, opts?: object): ImportPreview;
   /** Parse delimited text into coerced records — the inverse of `export.csv`. */
   csv(text: string, opts?: object): Record<string, unknown>[];
+  /**
+   * Parse an `.xlsx` file's bytes into a preview, changing nothing (§14,
+   * BACKLOG-0000970). Async: the archive is inflated with `DecompressionStream`.
+   */
+  previewXlsx(bytes: Uint8Array | ArrayBuffer, opts?: object): Promise<ImportXlsxPreview>;
+  /** Parse an `.xlsx` file's bytes into coerced records — the inverse of `export.excel`. */
+  xlsx(bytes: Uint8Array | ArrayBuffer, opts?: object): Promise<Record<string, unknown>[]>;
   /** Add or replace the grid's rows from text, a preview or records. */
   apply(
     input: string | ImportPreview | Record<string, unknown>[],
@@ -7885,3 +8000,142 @@ declare module 'lattice-grid/modules/kpi' {
   export function createKPI(el: HTMLElement | null, config?: KPIConfig): KPI;
   export default createKPI;
 }
+
+declare module 'lattice-grid/modules/ai' {
+  /**
+   * The provider-agnostic model callback the host supplies (BACKLOG-0000965).
+   * The module never imports a provider SDK, reads a key, or makes a network
+   * call — it builds this payload and awaits the host's reply. A host may wrap a
+   * chat provider (`{ text }`), a completion (a bare string), a tool-calling turn
+   * (`{ toolCalls }`), or a structured provider (`{ structured }`).
+   */
+  type AIAsk = (payload: {
+    /** The narrate-only system instruction. */
+    system: string;
+    /** The single user message: the facts block and the ask. */
+    message: string;
+    /** System and message joined, for a completion-shaped provider. */
+    prompt: string;
+    /** The running chat, including any tool results, for a chat-shaped provider. */
+    messages: Array<{ role: string; content: string; [k: string]: unknown }>;
+    /** The read-only tool definitions, present only on the tool-use path. */
+    tools?: object[];
+    /** The grid's generated schema (no row values). */
+    schema?: unknown;
+    /** An abort signal the host should honour. */
+    signal?: AbortSignal;
+  }) => Promise<
+    | string
+    | { text?: string; content?: string; toolCalls?: object[]; structured?: unknown }
+  >;
+
+  /** A single computed figure a narrative is grounded on. */
+  interface AIFact {
+    id: string;
+    label: string;
+    /** The raw numeric value, or null for a context-only fact. */
+    value: number | null;
+    /** The pre-formatted display string the model is told to use verbatim. */
+    display: string;
+    kind: string;
+    colId?: string;
+  }
+
+  /**
+   * A narrative target. `view` narrates the current filtered view; `column`
+   * narrates one column's profile; `forecast` adds its projection; `kpi`/`chart`
+   * narrate figures the caller passes through in `facts`.
+   */
+  interface AITarget {
+    kind?: 'view' | 'column' | 'forecast' | 'kpi' | 'chart';
+    colId?: string;
+    /** Forecast options, for `kind: 'forecast'`. */
+    options?: object;
+    /** Caller-supplied figures for a KPI/chart Explain, grounded like the rest. */
+    facts?: Array<{ id?: string; label: string; value: unknown; display?: string; kind?: string; colId?: string }>;
+  }
+
+  /** The facts packet a narrative grounds on. */
+  interface AIFactsPacket {
+    target: AITarget;
+    facts: AIFact[];
+    /** The numeric values seeding the reconciliation registry. */
+    groundedValues: number[];
+    meta: { kind: string; filtered: boolean; factCount: number; redacted?: boolean; colId?: string };
+  }
+
+  /** The result of a narrative: reconciled prose plus what grounded and what did not. */
+  interface AINarrative {
+    /** The narrative, with every ungrounded figure stripped (or flagged). */
+    text: string;
+    facts: AIFact[];
+    /** The figures that reconciled against a computed value. */
+    grounded: string[];
+    /** The figures removed as ungrounded. */
+    flagged: string[];
+    packet: AIFactsPacket;
+    /** How many ask() rounds ran (>1 only on the tool-use path). */
+    rounds: number;
+    mode: 'tools' | 'packet';
+  }
+
+  /** AI module configuration. */
+  interface AIConfig {
+    /** The host's model callback. Falls back to the grid's `ai.ask` when omitted. */
+    ask?: AIAsk;
+    /** Opt into specific features: `'narrative'`, `'insights'`. All on when omitted. */
+    enable?: string[];
+    /** Cap on rows any tool result carries to `ask()`. */
+    maxRows?: number;
+    /** Columns whose values must never leave the browser. */
+    redact?: string | string[] | ((colId: string) => boolean);
+    /** Force tool-use on or off; auto-detected from how `ask` was supplied otherwise. */
+    tools?: boolean;
+    /** Locale for figure formatting. */
+    locale?: string;
+    /** Column cap for a view summary. */
+    maxColumns?: number;
+    /** What to do with an ungrounded figure: `'strip'` (default) or `'flag'`. */
+    reconcile?: 'strip' | 'flag';
+    /** An element to mount the insights panel into. */
+    element?: HTMLElement;
+    /** Called when a narrative is produced. */
+    onNarrative?: (result: AINarrative) => void;
+    /** Called when `ask()` errors; the grid stays usable. */
+    onError?: (error: { error: unknown; target: AITarget }) => void;
+  }
+
+  /**
+   * An AI narrative / insights controller over a live grid. Read-only: it
+   * explains the grid's computed figures and never mutates data. `grid.ai` (in
+   * core) is the complementary intent/plan skill layer; this is the
+   * narrative/insights consumer.
+   */
+  interface AI {
+    /** The mounted insights panel element, or null. */
+    readonly el: HTMLElement | null;
+    /** Whether a usable `ask()` is configured. */
+    readonly ready: boolean;
+    /** Produce a grounded, reconciled narrative for a target. */
+    explain(target?: AITarget, opts?: object): Promise<AINarrative>;
+    /** An alias for {@link AI.explain}. */
+    narrate(target?: AITarget, opts?: object): Promise<AINarrative>;
+    /** Mount (or re-target) the insights panel into an element. */
+    insights(el?: HTMLElement, opts?: object): AI;
+    /** Build an "Explain" button bound to a target. */
+    attachExplain(target: AITarget, opts?: object): HTMLElement | null;
+    /** Build the facts packet for a target without calling `ask()`. */
+    facts(target?: AITarget, opts?: object): AIFactsPacket;
+    on(name: 'narrative' | 'error' | string, fn: (payload: object) => void): () => void;
+    off(name: string, fn: (payload: object) => void): void;
+    destroy(): void;
+  }
+
+  /**
+   * Create an AI narrative / insights controller over a live grid. The grid may
+   * be headless or rendered; the module grounds every figure on the grid's
+   * engine and calls only the host's `ask()`.
+   */
+  export function createAI(grid: unknown, config?: AIConfig): AI;
+  export default createAI;
+}