@toclocoinc/lattice-grid 1.46.1 → 1.48.0

package/docs/api-detail.html

@@ -437,7 +437,7 @@
 <div class="shell">
   <aside class="rail">
     <p class="rail__brand">Lattice Grid</p>
-    <p class="rail__sub">Developer guide · v1.46.1</p>
+    <p class="rail__sub">Developer guide · v1.48.0</p>
     <nav>
       <div class="rail__group">
         <span class="rail__label">Start here</span>
@@ -506,6 +506,7 @@
         <a href="#rules-guide">Conditional formatting</a>
         <a href="#formatting-guide">Formatting a user can change</a>
         <a href="#quickfilter-guide">Quick filter</a>
+        <a href="#find">Find</a>
         <a href="#charts-guide">In-cell charts</a>
       </div>
       <div class="rail__group">
@@ -2482,7 +2483,10 @@ grid.setPinnedRows([], { edge: 'top' });        <span class="cmt">// clear</span
     </p>
     <div class="why">
       <p><strong>The API.</strong> <code>groupColumns(ids, { title, groupId })</code> wraps columns
-      in a new band or adds them to an existing one; <code>ungroupColumn(id)</code> takes a column
+      in a new band or adds them to an existing one; pass <code>id</code> instead of
+      <code>groupId</code> to create a new band with a caller-chosen, stable id you can address
+      later (<code>groupColumns(ids, { title: 'Traffic', id: 'g-traffic' })</code>).
+      <code>ungroupColumn(id)</code> takes a column
       out (dissolving a band it empties); <code>renameGroup(id, title)</code>,
       <code>dissolveGroup(id)</code> and <code>moveGroup(id, to)</code> do the rest. Each emits
       <code>columngroup:changed</code>. A band's columns are always contiguous, and a nested band
@@ -3146,8 +3150,17 @@ createGrid(el, {
       <p>Column and table names are checked against an identifier pattern rather than escaped, and
       a name that fails is refused. Integers past the safe range are kept as strings instead of
       being rounded into a plausible lie.</p>
+      <p>A timestamp or date filter is bound through a typed placeholder — <code>"ts" &gt;=
+      CAST(? AS TIMESTAMP)</code> — because a prepared statement binds an ISO string as
+      <code>VARCHAR</code> and DuckDB will not compare that with a <code>TIMESTAMP</code>,
+      <code>TIMESTAMP WITH TIME ZONE</code> or <code>DATE</code> column. The adapter reads the
+      column types once from the engine (<code>DESCRIBE</code>) and falls back to the grid column's
+      declared type, so both a typed and an untyped grid column over a timestamp filter correctly,
+      including a time window. Send instants ending in <code>Z</code>, as the grid's date filter
+      does: the cast is the engine's, and its zone rules apply (see the reference for the
+      <code>TIMESTAMPTZ</code> and naive-string cases).</p>
       <p><code>demo/duckdb.html</code> runs this against a Parquet file of several million readings
-      with no server involved.</p>
+      with no server involved, including a time-window filter on its <code>TIMESTAMP</code> column.</p>
     </div>
 
     <h3 id="fulldataset">Whole-dataset statistics over a remote source</h3>
@@ -5081,6 +5094,7 @@ grid.annotate.use(null);                     <span class="cmt">// hand the grid
           <tr><td class="name"><kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>H</kbd></td><td class="desc">Move focus to the column header</td></tr>
           <tr><td class="name"><kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>P</kbd></td><td class="desc">Move focus to the tool panel</td></tr>
           <tr><td class="name"><kbd>Shift</kbd>+<kbd>F10</kbd> <span class="sep">or</span> <kbd>ContextMenu</kbd></td><td class="desc">Open the context menu for the focused cell</td></tr>
+          <tr><td class="name"><kbd>Ctrl</kbd>+<kbd>F</kbd></td><td class="desc">Find in the grid</td></tr>
           <tr><td class="name"><kbd>Alt</kbd>+<kbd>Shift</kbd>+<kbd>ArrowUp</kbd> <span class="sep">or</span> <kbd>Alt</kbd>+<kbd>Shift</kbd>+<kbd>ArrowDown</kbd></td><td class="desc">Move the focused row, when row reorder is enabled</td></tr>
           <tr><th colspan="2">On a column heading</th></tr>
           <tr><td class="name"><kbd>ArrowLeft</kbd> <span class="sep">or</span> <kbd>ArrowRight</kbd></td><td class="desc">Move between headings</td></tr>
@@ -5412,6 +5426,7 @@ grid.edit.pasteInto(text);                        <span class="cmt">// Excel's t
           <tr><td class="sig">Enter</td><td class="desc">Start editing; commit and step down.</td></tr>
           <tr><td class="sig">Tab</td><td class="desc">Commit and step across.</td></tr>
           <tr><td class="sig">Escape</td><td class="desc">Cancel the edit; restore a maximised grid once nothing else wants it.</td></tr>
+          <tr><td class="sig">Ctrl/Cmd + F</td><td class="desc">Open the <a href="#find">find bar</a>; in it, Enter / Shift+Enter step through the matches and Escape closes.</td></tr>
           <tr><td class="sig">Space</td><td class="desc">Toggle the row's selection.</td></tr>
           <tr><td class="sig">Home / End, Page Up / Down</td><td class="desc">Jump; with Ctrl, to the ends of the grid.</td></tr>
         </tbody>
@@ -6062,6 +6077,86 @@ grid.highlight.clear();</code></pre>
       it. A highlight belongs to the row rather than the element, so it survives scrolling, sorting
       and paging.
     </p>
+
+    <h2 id="find">Find</h2>
+    <p class="lead-in">
+      The quick filter answers "show me only the rows that contain X". Find answers a different
+      question — "where is X?" — and leaves every other row exactly where it was, so you keep your
+      place and the neighbours that give a value its meaning. Press <kbd>Ctrl</kbd>+<kbd>F</kbd>
+      (<kbd>Cmd</kbd>+<kbd>F</kbd> on a Mac) with focus in the grid: a bar opens above the header
+      with focus in its input, every cell whose <em>displayed</em> text matches lights up in place,
+      the bar reads "N of M", <kbd>Enter</kbd> and <kbd>Shift</kbd>+<kbd>Enter</kbd> step through
+      the matches with wrap, and <kbd>Escape</kbd> closes it and clears the marks.
+    </p>
+    <div class="example">
+      <p class="example__label">The same thing from code</p>
+      <pre data-run="js" data-expect="2 matches, 3 rows shown, current a, events true" data-covers="method:find config:find config:shortcut config:debounce event:find:changed"><code>const { createHeadlessGrid } = await import('../packages/core/src/index.js');
+const grid = createHeadlessGrid({
+  rowKey: 'id',
+  find: { shortcut: true, debounce: 0 },   // the bar's settings; `find: false` removes the bar
+  columns: [
+    { field: 'name' },
+    { field: 'price', format: (p) =&gt; `$${p.value.toFixed(2)}` },
+  ],
+  rows: [
+    { id: 'a', name: 'Acme', price: 3.5 },
+    { id: 'b', name: 'Beta', price: 13.25 },
+    { id: 'c', name: 'Acme Two', price: 3.75 },
+  ],
+});
+let events = 0;
+grid.on('find:changed', () =&gt; { events += 1; });
+
+const count = grid.find('$3.');            // the formatted text: two prices begin "$3."
+const first = grid.find.current();          // { key: 'a', colId: 'price', index: 0, pinned: null }
+grid.find.next();                           // row c; next() again wraps back to a
+const rowsStillShown = grid.rows.count();   // 3 — find never removes a row
+
+grid.destroy();
+return `${count.total} matches, ${rowsStillShown} rows shown, current ${first.key}, events ${events &gt; 0}`;</code></pre>
+    </div>
+    <p class="lead-in">
+      <code>grid.find(text, opts)</code> searches now and returns a <code>FindCount</code>; it is
+      callable like <code>grid.highlight</code>. The options are a <code>FindQuery</code>:
+      <code>caseSensitive</code>, <code>wholeCell</code>, <code>columns</code> (an id or a list of
+      ids; omitted searches every visible column) and <code>from</code> (the display index the
+      first current match is chosen at or after). Then <code>find.next()</code>,
+      <code>find.prev()</code> and <code>find.goTo(i)</code> move the current match and scroll it
+      into view; <code>find.matches()</code>, <code>find.count()</code>,
+      <code>find.current()</code> and <code>find.state()</code> read the result;
+      <code>find.open(text?)</code>, <code>find.close()</code> and <code>find.clear()</code> drive
+      the bar; <code>find.stateFor(key, colId)</code> is what the painter asks. Every change fires
+      <code>find:changed</code> with the query, the open flag and the count.
+    </p>
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Rule</th><th>What it means</th></tr></thead>
+        <tbody>
+          <tr><td class="sig">Display text</td><td class="desc">Find matches what the cell <em>shows</em> — a column <code>format</code>, a unit type, a lookup label — never the raw value. Searching <code>$3.</code> finds prices formatted that way. There is no regular-expression mode; the quick filter has one.</td></tr>
+          <tr><td class="sig">An overlay, not a filter</td><td class="desc">No row is reordered, removed or edited. Matches are painted as <code>.lat-cell--find</code>, the current one also as <code>.lat-cell--find-current</code>, coloured by <code>--lattice-find-match</code> and <code>--lattice-find-current</code>. Find and the quick filter coexist: both may be active, and find re-runs over whatever the filter leaves.</td></tr>
+          <tr><td class="sig">Pinned rows and columns</td><td class="desc">Rows pinned to either edge (and a bottom grand total) are searched and painted like any other; a pinned match has <code>index: -1</code> and <code>pinned: 'top' | 'bottom'</code>. Pinned columns are cells like any other.</td></tr>
+          <tr><td class="sig">Virtualised rows</td><td class="desc">Matches are computed from the row model, not the DOM, so a match five thousand rows down is counted without rendering it; stepping to it scrolls it into view, and the paint follows the render.</td></tr>
+          <tr><td class="sig">The active cell</td><td class="desc">Stepping to a match makes it the active cell, so <kbd>Enter</kbd> in the grid edits it — except while an edit is already open, when the match is scrolled and painted and the editor is left alone.</td></tr>
+          <tr><td class="sig">Windowed sources</td><td class="desc">A paged pushdown source (OData, DuckDB, REST) holds only its loaded rows client-side, so only those are searched. The count says so — "N of M <em>in loaded rows</em>", and <code>FindCount.windowed</code> is true with <code>loaded</code> and <code>rows</code> beside it — rather than presenting a page-one count as the whole. Pushing find to the adapter is a follow-up, not a v1 promise.</td></tr>
+          <tr><td class="sig">Large grids</td><td class="desc">Typing is scanned in per-frame slices from the row at the top of the viewport, so the matches on screen appear after the first slice and the grid stays interactive; the count reads "N of M so far" and <code>count.complete</code> is false until the scan finishes. <code>grid.find(text)</code> scans to completion before returning, so its answer is final.</td></tr>
+          <tr><td class="sig">The browser's find</td><td class="desc"><kbd>Ctrl</kbd>+<kbd>F</kbd> is claimed only while focus is inside the grid and not in a text field, so the page's own find works everywhere else and an open cell editor keeps it. <code>find: { shortcut: false }</code> leaves the binding to the page and keeps the bar reachable through <code>find.open()</code>; <code>find: false</code> removes the bar altogether.</td></tr>
+          <tr><td class="sig">Accessibility</td><td class="desc">The bar is a <code>role="search"</code> landmark; every control is a native input, button or select with a catalogue name, so nothing needs a mouse. The count is announced through a polite <code>role="status"</code> line once per completed search ("3 of 12 matches", "No matches in loaded rows"); the current match becomes the focused cell when no edit is open, so a screen reader reads it. The strings are in every bundled locale.</td></tr>
+          <tr><td class="sig">Keys in the bar</td><td class="desc">Only <kbd>Escape</kbd> and <kbd>Enter</kbd> in the input are consumed by the bar. Everything else — <kbd>Tab</kbd> between its controls, <kbd>Enter</kbd> and <kbd>Space</kbd> on its buttons, a page's own <kbd>Ctrl</kbd>+<kbd>S</kbd> — propagates as it would from any form control, so a host's document-level shortcuts still see it; the grid's own keyboard and range layers stand aside for a key aimed at the bar, which is what keeps Tab from being read as "next cell" and Enter from opening an editor.</td></tr>
+          <tr><td class="sig">Pinned strips</td><td class="desc">Stepping to a match scrolls it fully into the part of the body the pinned strips do not cover — below pinned-top rows and sticky group headings, above pinned-bottom rows and a bottom grand total. That is <code>grid.scroll.toRow</code>'s behaviour for every caller, not only find.</td></tr>
+        </tbody>
+      </table>
+    </div>
+    <div class="example">
+      <p class="example__label">Configuration</p>
+      <pre><code>find: false                              <span class="cmt">// no bar, no Ctrl+F; grid.find(text) still works</span>
+find: { shortcut: false }                <span class="cmt">// bar via grid.find.open() only</span>
+find: { debounce: 250 }                  <span class="cmt">// a slower typist, or a slower grid</span>
+
+grid.find('acme', { caseSensitive: true, wholeCell: false, columns: ['customer'] });
+grid.find.count();     <span class="cmt">// { current, total, complete, windowed, loaded, rows }</span>
+grid.on('find:changed', (e) =&gt; status.textContent = `${e.count.current} of ${e.count.total}`);</code></pre>
+    </div>
+
     <h2 id="views-guide">Saved views</h2>
     <p class="lead-in">
       A view is a named grid state: sort, filters, grouping, column order, widths, visibility.
@@ -6434,6 +6529,7 @@ grid.import.apply(preview);</code></pre>
           <tr><td class="name">processCell</td><td class="desc">(optional)</td></tr>
           <tr><td class="name">promoteToMemoryBelow</td><td class="desc">(optional)</td></tr>
           <tr><td class="name">quickFilterText</td><td class="desc">Initial quick-filter term. Equivalent to grid.filters.quick(text).</td></tr>
+          <tr><td class="name">find</td><td class="desc">The in-grid find bar (Ctrl+F): false removes it, { shortcut, debounce } tunes it. See <a href="#find">Find</a>.</td></tr>
           <tr><td class="name">quote</td><td class="desc">(optional)</td></tr>
           <tr><td class="name">removeMs</td><td class="desc">Silence after which a peer is dropped. (optional)</td></tr>
           <tr><td class="name">showHeader</td><td class="desc">Draw the column headings at all. false removes the row, and removes it from the accessibility tree rather than only from view. Distinct from showColumnFunctions, which keeps the headings and drops only their sort, filter and menu controls.</td></tr>
@@ -6770,6 +6866,7 @@ el.grid.sort.set([{ col: 'charge', dir: 'desc' }]);</code></pre>
         <tbody>
           <tr><td class="name">formatting:changed</td><td class="desc">A conditional formatting rule was added, edited, reordered or restated.</td></tr>
           <tr><td class="name">highlight:changed</td><td class="desc">A highlight was added or cleared.</td></tr>
+          <tr><td class="name">find:changed</td><td class="desc">The find query, its matches, the current match or the bar's open state changed; carries the FindCount, partial while the sliced scan runs.</td></tr>
           <tr><td class="name">permissions:changed</td><td class="desc">The context moved and every column re-resolved.</td></tr>
           <tr><td class="name">presentation:captured</td><td class="desc">A PNG was taken.</td></tr>
           <tr><td class="name">presentation:changed</td><td class="desc">The options of a running presentation changed.</td></tr>

package/lattice-grid.d.ts

@@ -1,5 +1,5 @@
 /*!
- * Lattice Grid 1.46.1, type declarations
+ * Lattice Grid 1.48.0, type declarations
  * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
  * https://latticegrid.dev
  */
@@ -2072,6 +2072,15 @@ export interface GridConfig {
    */
   shortcuts?: boolean;
 
+  /**
+   * The in-grid find bar (BACKLOG-0001018): Ctrl+F / Cmd+F with focus in the
+   * grid opens it; typing highlights every matching cell in place without
+   * filtering a row away; Enter and Shift+Enter step through the matches.
+   * `false` removes the bar and its shortcut; the `grid.find` API still works.
+   * Default true.
+   */
+  find?: boolean | FindConfig;
+
   /**
    * Let a user reorder rows by dragging a handle, or with
    * Alt+Shift+Up/Down.
@@ -3815,7 +3824,7 @@ export type EventName =
   /* Selection and view */
   | 'selection:changed' | 'range:changed' | 'clipboard:copy'
   | 'page:changed' | 'scroll' | 'scroll:end' | 'size:changed'
-  | 'detail:toggled' | 'toolpanel:focus' | 'highlight:changed'
+  | 'detail:toggled' | 'toolpanel:focus' | 'highlight:changed' | 'find:changed'
   /* Tree data */
   | 'tree:loading' | 'tree:loaded' | 'tree:loadFailed' | 'tree:loadAborted'
   /* State, history and views */
@@ -4096,9 +4105,12 @@ export interface ColumnsApi {
    * (BACKLOG-0000739). Header banding, not row grouping (see {@link group}); the
    * band is a {@link ColumnGroup} node so a drag-, keyboard- or config-built band
    * is the same tree, and it round-trips through a saved view. Emits
-   * `columngroup:changed`.
+   * `columngroup:changed`. Pass `groupId` to add to the band already carrying
+   * that id, or `id` (BACKLOG-0000985) to create a new band with a caller-chosen
+   * stable id you can reference later; `groupId` wins if both are given and an
+   * `id` already in use warns and no-ops.
    */
-  groupColumns(ids: string | string[], opts?: { title?: string; at?: number; groupId?: string }): string | null;
+  groupColumns(ids: string | string[], opts?: { title?: string; at?: number; groupId?: string; id?: string }): string | null;
   /** Take a leaf out of its band; a band emptied by the move is dissolved. */
   ungroupColumn(id: string): void;
   /** Rename a banded header. */
@@ -4319,7 +4331,10 @@ export interface ScrollApi {
   /**
    * A row key, or a display index. A key survives a sort and is usually what a
    * caller holds; resolving one scans the display order, so prefer an index
-   * when scrolling a very large grid repeatedly.
+   * when scrolling a very large grid repeatedly. The row lands fully visible in
+   * the part of the body the pinned strips (pinned rows, sticky group
+   * headings, a bottom grand total) do not cover: `end` puts it just above the
+   * bottom strip, `start` just below the top one.
    */
   toRow(row: string | number, align?: 'start' | 'center' | 'end' | 'auto'): void;
   toColumn(id: string): void;
@@ -4957,6 +4972,106 @@ export interface HighlightApi {
   colourFor(key: string, colId: string): string | null;
 }
 
+/**
+ * The in-grid find bar's settings (BACKLOG-0001018). `find: true` or an
+ * omitted key mounts the bar with these defaults; `find: false` removes the
+ * bar and its shortcut while `grid.find` keeps working programmatically.
+ */
+export interface FindConfig {
+  /**
+   * Bind Ctrl+F (Cmd+F on a Mac) while focus is in the grid. The browser's
+   * own find is untouched while focus is anywhere else on the page. Default
+   * true.
+   */
+  shortcut?: boolean;
+  /** Milliseconds of typing quiet before the bar searches. Default 120. */
+  debounce?: number;
+}
+
+/**
+ * How `grid.find(text, opts)` matches. Defaults: case-insensitive, substring,
+ * every visible column, starting from the first row. Find matches the
+ * **formatted display text** — what the cell shows, a column `format`
+ * included — never a raw value; there is no regular-expression mode.
+ */
+export interface FindQuery {
+  /** Match letter case exactly. Default false. */
+  caseSensitive?: boolean;
+  /** The whole cell text must equal the search text rather than contain it. Default false. */
+  wholeCell?: boolean;
+  /** Search only these column ids. Omitted searches every visible column. */
+  columns?: string[] | string | null;
+  /** The display index to start from: the first match at or after it becomes current. Default 0. */
+  from?: number;
+}
+
+/** One matching cell. */
+export interface FindMatch {
+  key: string;
+  colId: string;
+  /** The display index, or -1 for a row pinned to an edge. */
+  index: number;
+  /** Which sticky strip a pinned row is in; null for a body row. */
+  pinned: 'top' | 'bottom' | null;
+}
+
+/**
+ * How many matches there are and which is current. `windowed` is the honest
+ * scope flag: over a paged pushdown source only the loaded rows are searched,
+ * so `total` counts matches in `loaded` rows out of the `rows` the source
+ * reports for the whole matching set.
+ */
+export interface FindCount {
+  /** 1-based position of the current match; 0 when there is none. */
+  current: number;
+  total: number;
+  /** False while the bar's sliced scan is still running, so a partial count is never read as final. */
+  complete: boolean;
+  windowed: boolean;
+  /** Rows the search actually read; a windowed source's not-yet-fetched placeholders are not counted. */
+  loaded: number;
+  /** The rows the source reports for the whole matching set, when it can say. */
+  rows: number;
+}
+
+/** The current query and whether the bar is showing. */
+export interface FindState {
+  text: string;
+  caseSensitive: boolean;
+  wholeCell: boolean;
+  columns: string[] | null;
+  open: boolean;
+}
+
+/**
+ * In-grid find (BACKLOG-0001018): locate text and step through where it
+ * occurs without filtering anything away. Matches are a visual overlay — no
+ * row is reordered, removed or edited — and coexist with the quick filter.
+ */
+export interface FindApi {
+  /** Search now, scanning every loaded row before returning; an empty text clears. */
+  (text: string, opts?: FindQuery): FindCount;
+  /** Show the bar with focus in its input, optionally seeding the text. */
+  open(text?: string): void;
+  /** Hide the bar and clear every match. */
+  close(): void;
+  /** Clear the query and the highlights, leaving the bar as it is. */
+  clear(): void;
+  /** The next match, wrapping from the last to the first, scrolled into view and made the active cell unless an edit is open. */
+  next(): FindMatch | null;
+  /** The previous match, wrapping from the first to the last. */
+  prev(): FindMatch | null;
+  /** Make the match at a position in `matches()` current. */
+  goTo(index: number): FindMatch | null;
+  /** Every match, in display order: pinned-top rows, then the body, then pinned-bottom rows. */
+  matches(): FindMatch[];
+  count(): FindCount;
+  current(): FindMatch | null;
+  state(): FindState;
+  /** How a cell is painted: the current match, another match, or nothing. */
+  stateFor(key: string, colId: string): 'current' | 'match' | null;
+}
+
 export interface StateApi {
   get(): GridState;
   apply(state: GridState, opts?: { skip?: (keyof GridState)[] }): StateApplyReport;
@@ -5242,6 +5357,8 @@ export interface Grid {
   readonly pagination: PaginationApi;
   /** Transient emphasis on a row, column or cell. */
   readonly highlight: HighlightApi;
+  /** In-grid find: locate text without filtering, and step through the matches. */
+  readonly find: FindApi;
   /** Values hidden from view and from export. */
   readonly redaction: RedactionApi;
   /** An image of the grid as drawn, where the module is installed. */
@@ -6163,6 +6280,16 @@ export interface ChartTrend {
   alpha?: number;
   /** For Holt's exponential smoothing, the trend factor in `[0, 1]`; omit to fit it. */
   beta?: number;
+  /**
+   * The uncertainty band shaded around a linear `forecast` (BACKLOG-0000975).
+   * The Student-t `prediction` band (a future observation) by default;
+   * `confidence` shades the narrower mean-response band; `false` opts out and
+   * leaves the bare dashed line. Ignored where there is no linear forecast to
+   * put a band on.
+   */
+  band?: boolean | 'prediction' | 'confidence';
+  /** The forecast band's confidence level in `(0, 1)`; 0.95 by default. */
+  confidence?: number;
   /** `false` suppresses the R² label on a linear trend. */
   label?: boolean;
 }
@@ -7687,6 +7814,16 @@ declare module 'lattice-grid/modules/kanban' {
     color?: string;
     wipLimit?: number;
     collapsed?: boolean;
+    /**
+     * A per-column SLA override (BACKLOG-0000960): a lone threshold read as the
+     * breach level, or a `{ warn, breach }` pair. Overrides the global `sla`
+     * thresholds for cards in this column (precedence: lane → column → global).
+     */
+    sla?: KanbanSlaThreshold | { warn?: KanbanSlaThreshold; breach?: KanbanSlaThreshold };
+    /** A per-column warn threshold — the shorthand for `sla: { warn }`. */
+    slaWarn?: KanbanSlaThreshold;
+    /** A per-column breach threshold — the shorthand for `sla: { breach }`. */
+    slaBreach?: KanbanSlaThreshold;
   };
 
   /** A card field editor handle returned by a host editor factory. */
@@ -7732,6 +7869,112 @@ declare module 'lattice-grid/modules/kanban' {
     originalEvent?: unknown;
   }
 
+  /**
+   * A card-aging / SLA threshold (BACKLOG-0000960): a raw millisecond count, or
+   * a `{ weeks, days, hours, minutes, seconds, ms }` spec whose fields are summed
+   * (`{ days: 3, hours: 12 }` → 3.5 days). A negative or non-finite value means
+   * "no threshold at this level".
+   */
+  type KanbanSlaThreshold = number | {
+    weeks?: number; week?: number; w?: number;
+    days?: number; day?: number; d?: number;
+    hours?: number; hour?: number; h?: number;
+    minutes?: number; minute?: number; m?: number; min?: number;
+    seconds?: number; second?: number; s?: number; sec?: number;
+    ms?: number; milliseconds?: number;
+  };
+
+  /**
+   * Card-aging / SLA configuration (BACKLOG-0000960). A card is measured against a
+   * `warn` and a `breach` threshold; the view puts an age chip on aged cards and a
+   * highlight on breached ones, and a rising crossing fires the `card:sla` event
+   * and the matching `onWarn`/`onBreach` callback (signature `(level, rows)`, the
+   * Data Router alert handler's). Thresholds resolve most-specific-first:
+   * lane → column → global. Reached at runtime as {@link Kanban#sla}.
+   */
+  interface KanbanSlaConfig {
+    /** The global warn threshold. */
+    warn?: KanbanSlaThreshold;
+    /** The global breach threshold. */
+    breach?: KanbanSlaThreshold;
+    /** Per-column overrides by column id (each a threshold or a `{ warn, breach }` pair). */
+    columns?: Record<string, KanbanSlaThreshold | { warn?: KanbanSlaThreshold; breach?: KanbanSlaThreshold }>;
+    /** Per-swimlane overrides by lane id (each a threshold or a `{ warn, breach }` pair). */
+    lanes?: Record<string, KanbanSlaThreshold | { warn?: KanbanSlaThreshold; breach?: KanbanSlaThreshold }>;
+    /**
+     * Where the ageing clock starts: `'column'` (default) measures time in the
+     * card's current column; `'board'` measures age since the card arrived/was
+     * created.
+     */
+    basis?: 'column' | 'board';
+    /** A row property holding the wall-clock time the card entered its column. */
+    enteredProperty?: string;
+    /** A row property holding the wall-clock time the card was created. */
+    createdProperty?: string;
+    /** Whether cards in a done column are exempt from ageing (default true). */
+    ignoreDone?: boolean;
+    /** Whether the flow transition log drives the ageing basis when present (default true). */
+    useTransitionLog?: boolean;
+    /** Show the age chip on every aged card (`'always'`), or only on warn/breach (`'threshold'`, default). */
+    showAge?: 'always' | 'threshold';
+    /** A wall-clock epoch clock, injectable for deterministic tests (default `Date.now`). */
+    now?: () => number;
+    /** A re-check interval in ms so a card breaching by sitting still still lights up (0 = off). */
+    tick?: number;
+    /** Called on a rising crossing to warn level, `(level, rows)` — the router alert handler's shape. */
+    onWarn?: (level: 'warn' | 'breach', rows: KanbanRow[]) => void;
+    /** Called on a rising crossing to breach level, `(level, rows)` — the router alert handler's shape. */
+    onBreach?: (level: 'warn' | 'breach', rows: KanbanRow[]) => void;
+  }
+
+  /** The computed SLA state of one card (BACKLOG-0000960). */
+  interface KanbanSlaState {
+    key: unknown;
+    columnId: string | null;
+    lane?: unknown;
+    /** The ageing-clock start epoch (ms), or null when no time source could be resolved. */
+    start: number | null;
+    /** The card's age in ms, or null when unknown. */
+    ageMs: number | null;
+    /** A short human age label (`2d`, `5h`, …), '' when unknown. */
+    ageText: string;
+    /** The resolved warn threshold in ms, or null. */
+    warnMs: number | null;
+    /** The resolved breach threshold in ms, or null. */
+    breachMs: number | null;
+    /** The classified level, or null when the card cannot be aged. */
+    level: 'ok' | 'warn' | 'breach' | null;
+    /** True when `level` is `'breach'`. */
+    breached: boolean;
+  }
+
+  /**
+   * The card-aging / SLA monitor (BACKLOG-0000960), reached as {@link Kanban#sla}
+   * when a `sla` config is supplied. Pure and DOM-free: it computes each card's
+   * ageing state from the board's card model and the flow transition log, and the
+   * view paints it.
+   */
+  interface KanbanSla {
+    /** The normalised SLA config (read-only). */
+    readonly config: object;
+    /** Recompute every card's SLA state without emitting anything. */
+    sync(): KanbanSla;
+    /** Recompute and fire `card:sla`/`onWarn`/`onBreach` on each rising crossing. */
+    evaluate(opts?: { emit?: boolean }): KanbanSlaState[];
+    /** Establish the baseline, notify on the current state, and start the optional tick. */
+    start(): KanbanSla;
+    /** The SLA state of one card (by card model or key), or null when unknown. */
+    stateFor(cardOrKey: KanbanCard | unknown): KanbanSlaState | null;
+    /** Every card's current SLA state. */
+    states(): KanbanSlaState[];
+    /** The cards currently at breach level. */
+    breaches(): KanbanSlaState[];
+    /** The cards currently at warn level (not yet breached). */
+    warnings(): KanbanSlaState[];
+    /** Stop the tick and drop the board subscriptions. */
+    destroy(): void;
+  }
+
   /**
    * Kanban configuration. Every structural property is named here so the same
    * board maps DemandFlow (a status field, `points`, `sprint`, `epic`, a
@@ -7772,6 +8015,13 @@ declare module 'lattice-grid/modules/kanban' {
     children?: KanbanChildren;
     /** Card virtualization for tall columns: true, or `{ rowHeight, overscan, threshold, viewport }`. */
     virtualize?: boolean | { rowHeight?: number; overscan?: number; threshold?: number; viewport?: number };
+    /**
+     * Card aging / SLA highlighting (BACKLOG-0000960): warn/breach thresholds
+     * (globally, per column and/or per lane) that age each card and fire
+     * `card:sla` on a rising crossing. Opt-in; reached at runtime as
+     * {@link Kanban#sla}. See {@link KanbanSlaConfig}.
+     */
+    sla?: KanbanSlaConfig;
     /** A saved board state (from `getState`) to restore on construction. */
     state?: object;
     /** Show a per-column add-card affordance. */
@@ -7872,6 +8122,8 @@ declare module 'lattice-grid/modules/kanban' {
     readonly el: unknown | null;
     readonly rowKey: string | ((row: KanbanRow) => unknown);
     rows: KanbanRows;
+    /** The card-aging / SLA monitor, present only when a `sla` config was supplied (BACKLOG-0000960). */
+    sla?: KanbanSla;
     columns(): KanbanColumn[];
     column(id: string): KanbanColumn | undefined;
     count(id: string): number;
@@ -8153,15 +8405,52 @@ declare module 'lattice-grid/modules/ai' {
   /**
    * 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`.
+   * narrate figures the caller passes through in `facts`; `risk` assembles a
+   * project RISK SUMMARY from the separate Gantt / Kanban modules' public outputs
+   * (BACKLOG-0000979).
    */
   interface AITarget {
-    kind?: 'view' | 'column' | 'forecast' | 'kpi' | 'chart';
+    kind?: 'view' | 'column' | 'forecast' | 'kpi' | 'chart' | 'risk';
     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 }>;
+    /**
+     * For `kind: 'risk'`: a Gantt instance (from `createGantt`). Read duck-typed
+     * for `earnedValue()` (SPI/CPI/variances) and `schedule` (critical path,
+     * float). The AI bundle never imports the Gantt module.
+     */
+    gantt?: unknown;
+    /**
+     * For `kind: 'risk'`: a Kanban board (from `createKanban`). Read for its
+     * `board.sla` monitor (breach / warning counts). The AI bundle never imports
+     * the Kanban module.
+     */
+    board?: unknown;
+    /** For `kind: 'risk'`: an SLA monitor, if not reached through `board`. */
+    sla?: unknown;
+    /** For `kind: 'risk'`: a precomputed `gantt.earnedValue()` result. */
+    earnedValue?: object;
+    /** For `kind: 'risk'`: a precomputed `gantt.schedule` result. */
+    schedule?: object;
+    /** For `kind: 'risk'`: precomputed SLA breach states. */
+    breaches?: object[];
+    /** For `kind: 'risk'`: precomputed SLA warning states. */
+    warnings?: object[];
+    /** For `kind: 'risk'`: options passed to `gantt.earnedValue()`. */
+    evmOptions?: object;
+    /**
+     * For `kind: 'risk'`: expose the at-risk task NAMES (off by default — a risk
+     * summary carries aggregates only unless the host opts in).
+     */
+    includeTaskNames?: boolean;
+    /**
+     * For `kind: 'risk'`: expose the money figures BAC/PV/EV/AC (off by default).
+     */
+    includeCost?: boolean;
+    /** For `kind: 'risk'`: cap on named at-risk tasks (default 10). */
+    maxTasks?: number;
   }
 
   /** The facts packet a narrative grounds on. */
@@ -8170,7 +8459,27 @@ declare module 'lattice-grid/modules/ai' {
     facts: AIFact[];
     /** The numeric values seeding the reconciliation registry. */
     groundedValues: number[];
-    meta: { kind: string; filtered: boolean; factCount: number; redacted?: boolean; colId?: string };
+    meta: {
+      kind: string; filtered: boolean; factCount: number; redacted?: boolean; colId?: string;
+      /** For `kind: 'risk'`: which module sources resolved. */
+      sources?: { schedule: boolean; earnedValue: boolean; sla: boolean };
+      /** For `kind: 'risk'`: which opt-in exposures were honoured. */
+      exposed?: { taskNames: boolean; cost: boolean };
+    };
+  }
+
+  /**
+   * The risk facts a board / Gantt risk summary grounds on (BACKLOG-0000979),
+   * from {@link buildRiskFacts}: the facts plus which module sources resolved and
+   * which opt-in exposures (task names, cost) were honoured.
+   */
+  interface AIRiskFacts {
+    facts: AIFact[];
+    meta: {
+      kind: 'risk';
+      sources: { schedule: boolean; earnedValue: boolean; sla: boolean };
+      exposed: { taskNames: boolean; cost: boolean };
+    };
   }
 
   /** The result of a narrative: reconciled prose plus what grounded and what did not. */
@@ -8366,6 +8675,19 @@ declare module 'lattice-grid/modules/ai' {
     explain(target?: AITarget, opts?: object): Promise<AINarrative>;
     /** An alias for {@link AI.explain}. */
     narrate(target?: AITarget, opts?: object): Promise<AINarrative>;
+    /**
+     * Produce a grounded, reconciled board / Gantt RISK SUMMARY
+     * (BACKLOG-0000979): a plain-language reading like "3 tasks at risk on the
+     * critical path, SPI 0.67, 2 SLA breaches". A convenience over
+     * `explain({ kind: 'risk', ... })`; the module sources go in `sources`
+     * (`gantt`, `board`/`sla`, or precomputed outputs). Every figure runs through
+     * the same reconciliation guard as {@link AI.explain}.
+     */
+    riskSummary(sources?: {
+      gantt?: unknown; board?: unknown; sla?: unknown;
+      earnedValue?: object; schedule?: object; breaches?: object[]; warnings?: object[];
+      includeTaskNames?: boolean; includeCost?: boolean; maxTasks?: number; evmOptions?: object;
+    }, 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. */
@@ -8422,5 +8744,19 @@ declare module 'lattice-grid/modules/ai' {
    * engine and calls only the host's `ask()`.
    */
   export function createAI(grid: unknown, config?: AIConfig): AI;
+
+  /**
+   * Build the RISK-SUMMARY facts packet (BACKLOG-0000979) from the separate
+   * Gantt / Kanban modules' public outputs — SPI/CPI and variances from
+   * `gantt.earnedValue()`, tasks at risk / on the critical path from
+   * `gantt.schedule`, and SLA breaches from `board.sla`. Reads the module
+   * instances (or their precomputed outputs) duck-typed off `target`; the AI
+   * bundle imports neither module. This is the exact grounded set
+   * `explain({ kind: 'risk' })` would use, exposed for preview and testing.
+   */
+  export function buildRiskFacts(target: AITarget, opts?: {
+    locale?: string; fmt?: (value: number) => string;
+  }): AIRiskFacts;
+
   export default createAI;
 }