@toclocoinc/lattice-grid 1.34.1 → 1.36.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.34.1</p>
+    <p class="rail__sub">Developer guide · v1.36.0</p>
     <nav>
       <div class="rail__group">
         <span class="rail__label">Start here</span>
@@ -1869,6 +1869,38 @@ grid.rows.load(data);
 grid.overlay.hide();</code></pre>
     </div>
 
+    <h3 id="url-source-guide">Straight from a URL, with <code>createUrlSource</code></h3>
+    <p class="lead-in">
+      When the data is a file at a URL you do not have to fetch it yourself.
+      <code>createUrlSource(url, opts)</code> loads a JSON file or streams an NDJSON/JSONL file directly,
+      and you pass it as the <code>source</code>. See the
+      <a href="API.html#url-source">Sources reference</a> for every option.
+    </p>
+    <div class="example">
+      <p class="example__label">A JSON file, and a streamed NDJSON file</p>
+      <pre><code><span class="cmt">// A JSON file: a top-level array, or nested via rowsPath / map.</span>
+createGrid(el, { columns, rowKey: 'id', source: createUrlSource('/data/circuits.json') });
+
+<span class="cmt">// An NDJSON file: rows stream in as they parse, first rows first.</span>
+createGrid(el, { columns, rowKey: 'id', source: createUrlSource('/data/events.ndjson', { batchSize: 500 }) });
+
+<span class="cmt">// Auth, a nested array, and a 30s refresh:</span>
+createGrid(el, {
+  columns, rowKey: 'id',
+  source: createUrlSource('/api/rows', {
+    headers: { Authorization: 'Bearer …' },
+    rowsPath: 'result.items',
+    poll: 30000,
+  }),
+});</code></pre>
+    </div>
+    <p>
+      The format is inferred from the extension, then the <code>Content-Type</code>, then a sniff &mdash;
+      override it with <code>format: 'json' | 'ndjson'</code>. A non-2xx response, a network error or a
+      malformed NDJSON line becomes a <code>source:error</code> event rather than an exception, and
+      <code>lenient: true</code> skips a bad NDJSON line instead of failing the whole stream.
+    </p>
+
     <h3>Incremental changes</h3>
     <p class="lead-in">
       <code>rows.load</code> replaces everything. When you have a delta, a websocket message, a
@@ -6238,8 +6270,9 @@ grid.state.apply(savedView.state);
           <tr><td class="name">canChartRange</td><td class="desc">Whether <code>chartRange</code> would draw something for the grid’s current selection — the question a menu asks before offering the item.</td></tr>
           <tr><td class="name">deriveRangeSpec</td><td class="desc">Decide what a chart of a range should be without drawing it: the type, the category column, the measures, and a spec ready for <code>createChart</code>.</td></tr>
           <tr><td class="name">regressionPlots</td><td class="desc">Turn a fitted regression model into diagnostic chart specs ready for <code>createChart</code>: the fit line with its confidence band, residuals-vs-fitted, a QQ plot of the residuals, and a multicollinearity correlogram with the model’s VIF. The plots that need a per-row or per-coefficient quantity the grid has no column for (scale-location, residuals-vs-leverage, the coefficient forest) are returned as a null spec carrying the reason rather than dropped.</td></tr>
-          <tr><td class="name">createDataRouter</td><td class="desc">Split one arriving stream or dataset across many grids by what each record is — a property or a predicate — driving each grid through the public keyed <code>rows.apply</code> path so a snapshot is a diff, a delta is applied in place, a moved partition moves the row rather than duplicating it, and an unmatched record is counted, sunk and never dropped. v2 adds cross-grid selection filtering: <code>link(source, target, relation)</code> makes a selection in one grid filter what another receives — by a key map or a predicate function, multi-select as an IN set, debounced — re-pushed through the same keyed-diff path so the target stays dumb. 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. Detaches its grids on <code>destroy</code>; the host owns them.</td></tr>
+          <tr><td class="name">createDataRouter</td><td class="desc">Split one arriving stream or dataset across many grids by what each record is — a property or a predicate — driving each grid through the public keyed <code>rows.apply</code> path so a snapshot is a diff, a delta is applied in place, a moved partition moves the row rather than duplicating it, and an unmatched record is counted, sunk and never dropped. 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">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>
@@ -6492,6 +6525,59 @@ el.grid.sort.set([{ col: 'charge', dir: 'desc' }]);</code></pre>
         </tbody>
       </table>
     </div>
+    <h4>Cancellable before-events (BACKLOG-0000943)</h4>
+    <p>Every user-initiated mutation has a paired cancellable <code>before</code> event. The handler
+    receives a <code>BeforeEvent</code> carrying the action context plus <code>preventDefault(reason?)</code>,
+    <code>defaultPrevented</code> and <code>reason</code>. Calling <code>preventDefault()</code> — or
+    returning <code>false</code>, the legacy kanban <code>onBeforeMove</code> idiom — cancels the action.
+    A handler may be <code>async</code>; the mutation is held until every registered before-handler
+    settles, so a confirm dialog or a server check genuinely gates the write. Any one handler
+    preventing cancels it (veto wins), and a handler that throws is treated as a cancel and surfaced.
+    On a veto the paired <code>&lt;action&gt;:cancelled</code> event fires carrying the reason.</p>
+    <p>These fire for <em>user</em> actions only. Host/API writes (for example
+    <code>grid.edit.setCells</code>) and remote/router-applied deltas (<code>rows.apply</code>,
+    origin&nbsp;!==&nbsp;<code>'user'</code>) do not fire them — remote truth is not a user gesture and
+    does not self-veto. The <code>origin</code> field carried on each before-event lets a host
+    deduplicate a module-initiated write (a kanban or Gantt move that re-enters core) from a genuine
+    user gesture. If a handler was <code>async</code> and the underlying state moved during the await
+    (a row removed, a value changed by a live delta), the gate re-validates and cancels with reason
+    <code>'stale'</code> rather than applying against state that has moved. With no before-handler
+    registered every mutation stays synchronous and behaves exactly as before.</p>
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Event</th><th>Fires when</th></tr></thead>
+        <tbody>
+          <tr><td class="name">beforeEdit</td><td class="desc">Before a validated cell/row commit applies. Carries row, key, mode, changes, origin. Validation (edit.validate) is separate and runs first. Paired with edit:cancelled.</td></tr>
+          <tr><td class="name">beforeSort</td><td class="desc">Before a sort is set. Paired with sort:cancelled.</td></tr>
+          <tr><td class="name">beforeFilter</td><td class="desc">Before a structured or quick filter is set (kind tells them apart). Paired with filter:cancelled.</td></tr>
+          <tr><td class="name">beforeColumnMove</td><td class="desc">Before a column reorder applies, earlier than the post-mutation column change. Paired with columnMove:cancelled.</td></tr>
+          <tr><td class="name">beforeColumnResize</td><td class="desc">Before a column width change applies. Paired with columnResize:cancelled.</td></tr>
+          <tr><td class="name">beforeColumnHide</td><td class="desc">Before one or more columns are hidden. Paired with columnHide:cancelled.</td></tr>
+          <tr><td class="name">beforeSelect</td><td class="desc">Before a user selection change applies; a veto snaps back to the last announced selection. Paired with selection:cancelled.</td></tr>
+          <tr><td class="name">beforeRowAdd</td><td class="desc">Before an optimistic row append applies. Paired with rowAdd:cancelled.</td></tr>
+          <tr><td class="name">beforeDelete</td><td class="desc">Before an optimistic row delete applies — the canonical confirm-before-delete hook. Paired with delete:cancelled.</td></tr>
+          <tr><td class="name">beforeRowMove</td><td class="desc">Before a row reorder applies. Paired with rowMove:cancelled.</td></tr>
+          <tr><td class="name">beforeGroup</td><td class="desc">Before a group/tree expand or collapse applies. Paired with group:cancelled.</td></tr>
+          <tr><td class="name">edit:cancelled</td><td class="desc">A beforeEdit was vetoed; reason is 'stale' when a live delta moved the cell during an async gate.</td></tr>
+          <tr><td class="name">sort:cancelled</td><td class="desc">A beforeSort was vetoed.</td></tr>
+          <tr><td class="name">filter:cancelled</td><td class="desc">A beforeFilter was vetoed.</td></tr>
+          <tr><td class="name">columnMove:cancelled</td><td class="desc">A beforeColumnMove was vetoed.</td></tr>
+          <tr><td class="name">columnResize:cancelled</td><td class="desc">A beforeColumnResize was vetoed.</td></tr>
+          <tr><td class="name">columnHide:cancelled</td><td class="desc">A beforeColumnHide was vetoed.</td></tr>
+          <tr><td class="name">selection:cancelled</td><td class="desc">A beforeSelect was vetoed; the selection snapped back.</td></tr>
+          <tr><td class="name">rowAdd:cancelled</td><td class="desc">A beforeRowAdd was vetoed.</td></tr>
+          <tr><td class="name">delete:cancelled</td><td class="desc">A beforeDelete was vetoed; reason is 'stale' when the row was already gone.</td></tr>
+          <tr><td class="name">rowMove:cancelled</td><td class="desc">A beforeRowMove was vetoed; reason is 'stale' when the row had moved.</td></tr>
+          <tr><td class="name">group:cancelled</td><td class="desc">A beforeGroup was vetoed.</td></tr>
+          <tr><td class="name">export:request</td><td class="desc">A remote export was requested. Past-tense notification.</td></tr>
+          <tr><td class="name">export:done</td><td class="desc">A remote export completed. Past-tense notification.</td></tr>
+          <tr><td class="name">shortcuts:opened</td><td class="desc">The keyboard-shortcuts help overlay opened. Past-tense notification.</td></tr>
+          <tr><td class="name">shortcuts:closed</td><td class="desc">The keyboard-shortcuts help overlay closed. Past-tense notification.</td></tr>
+          <tr><td class="name">print:before</td><td class="desc">Print mode is about to snapshot. Past-tense notification, not cancellable (BACKLOG-0000941).</td></tr>
+          <tr><td class="name">print:after</td><td class="desc">Print mode restored the grid, even if the browser cancelled the print (BACKLOG-0000941).</td></tr>
+        </tbody>
+      </table>
+    </div>
     <h4>Presentation and formatting</h4>
     <div class="table-wrap">
       <table>

package/lattice-grid.d.ts

@@ -1,5 +1,5 @@
 /*!
- * Lattice Grid 1.34.1, type declarations
+ * Lattice Grid 1.36.0, type declarations
  * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
  * https://latticegrid.dev
  */
@@ -3442,7 +3442,21 @@ export type EventName =
   /* Annotations */
   | 'annotation:changed'
   /* Export */
-  | 'export:progress'
+  | 'export:progress' | 'export:request' | 'export:done'
+  /* Keyboard help overlay (past-tense notifications) */
+  | 'shortcuts:opened' | 'shortcuts:closed'
+  /* Print (past-tense notifications, BACKLOG-0000941) */
+  | 'print:before' | 'print:after'
+  /* Cancellable before-events (BACKLOG-0000943). Delivered through the async
+   * before-dispatch path with a {@link BeforeEvent} carrying preventDefault. */
+  | 'beforeEdit' | 'beforeSort' | 'beforeFilter'
+  | 'beforeColumnMove' | 'beforeColumnResize' | 'beforeColumnHide'
+  | 'beforeSelect' | 'beforeRowAdd' | 'beforeDelete' | 'beforeRowMove' | 'beforeGroup'
+  /* Their cancellation notifications (past-tense, non-cancellable). */
+  | 'edit:cancelled' | 'sort:cancelled' | 'filter:cancelled'
+  | 'columnMove:cancelled' | 'columnResize:cancelled' | 'columnHide:cancelled'
+  | 'selection:cancelled' | 'rowAdd:cancelled' | 'delete:cancelled'
+  | 'rowMove:cancelled' | 'group:cancelled'
   /* Every event at once, for logging and debugging. */
   | '*';
 
@@ -3453,6 +3467,31 @@ export interface GridEvent {
   [key: string]: unknown;
 }
 
+/**
+ * A cancellable *before*-event (BACKLOG-0000943), delivered to `on('beforeX')`
+ * handlers before a user-initiated mutation is applied.
+ *
+ * A handler cancels the pending action by calling `preventDefault(reason?)`; the
+ * mutation is then abandoned and a past-tense `<action>:cancelled` event carries
+ * the reason. A handler may be `async` (or return a Promise): the grid awaits
+ * every before-handler before deciding, so a confirm dialog or a server check
+ * can gate the write. Any one handler preventing cancels the action.
+ *
+ * The action-specific fields (the edited cells, the target index, the affected
+ * rows) are spread alongside these, so a handler decides without reaching into
+ * grid internals. `origin` distinguishes a genuine user gesture from a
+ * host/module-driven or remote write, which is how a module whose move re-enters
+ * core is deduplicated by the host.
+ */
+export interface BeforeEvent extends GridEvent {
+  /** Cancel the pending action; the optional reason is surfaced on the cancellation event. */
+  preventDefault(reason?: string): void;
+  /** True once any handler has called `preventDefault` or returned false. */
+  defaultPrevented: boolean;
+  /** The reason given to `preventDefault`, or null; `'stale'` when re-validation failed. */
+  reason: string | null;
+}
+
 export type EventHandler = (e: GridEvent) => void;
 export type Unsubscribe = () => void;
 
@@ -4997,6 +5036,53 @@ export function createPushdownSource(
   }>;
 };
 
+/**
+ * Load a JSON or NDJSON file from a URL (BACKLOG-0000944).
+ *
+ * Returns a `StreamSourceConfig` for `createGrid(el, { source: createUrlSource(url, opts) })`.
+ * A JSON file (a top-level array, or a nested array selected by `rowsPath`/`map`)
+ * is read whole and handed over as rows; an NDJSON/JSONL file (one JSON value per
+ * line) is streamed in incrementally in batches. Format is resolved from an
+ * explicit `format`, else the URL extension, else the `Content-Type`, else a
+ * sniff of the first bytes or a clear error. Errors — a non-2xx status, a network
+ * failure, a bad body, a malformed line — surface as `source:error`, never as an
+ * uncaught throw. Zero new dependencies: `fetch`, `response.body.getReader()` and
+ * `TextDecoder`.
+ *
+ * @param url the file URL
+ * @param opts loading options
+ * @returns a stream source config
+ */
+export function createUrlSource(
+  url: string,
+  opts?: {
+    /** Explicit format; wins over inference. */
+    format?: 'json' | 'ndjson';
+    /** Dot path to the array inside a wrapped JSON body (JSON only). */
+    rowsPath?: string;
+    /** Extract the array from the parsed JSON (JSON only); runs after `rowsPath`. */
+    map?: (parsed: unknown) => unknown[];
+    /** Transport override for auth, headers or a proxy; default `globalThis.fetch`. */
+    fetch?: typeof fetch;
+    /** Headers merged into the request. */
+    headers?: Record<string, string>;
+    /** Re-fetch on this interval in milliseconds; each pass replaces the rows. */
+    poll?: number;
+    /** NDJSON rows per emitted chunk, to avoid render thrash; default 500. */
+    batchSize?: number;
+    /** NDJSON: skip a malformed line with a warning rather than failing the stream. */
+    lenient?: boolean;
+    /** Start fetching on construction; default true. */
+    autoStart?: boolean;
+    /** Sliding-window bound passed through to the stream. */
+    maxRows?: number;
+    /** Render-coalescing window in ms, passed through to the stream. */
+    coalesceMs?: number;
+    /** Promote to a memory source below this row count, passed through to the stream. */
+    promoteToMemoryBelow?: number;
+  },
+): StreamSourceConfig;
+
 /**
  * The pushdown map (BACKLOG-0000730 Part B): one published record per statistic
  * giving whether the engine can express it, the DuckDB aggregate SQL it emits,
@@ -6276,21 +6362,43 @@ declare module 'lattice-grid/modules/gantt' {
   /** One of the four dependency link types (finish-to-start, start-to-start, finish-to-finish, start-to-finish). */
   export type GanttLinkType = 'FS' | 'SS' | 'FF' | 'SF';
 
+  /** A scheduling constraint: pin the start, pin the finish, or schedule as late as possible. */
+  export type GanttConstraintType =
+    | 'must-start-on' | 'must-finish-on' | 'as-late-as-possible' | 'MSO' | 'MFO' | 'ALAP';
+
+  /** A working-time calendar: a Monday–Friday preset, or explicit working weekdays and holidays. */
+  export type GanttCalendar =
+    | 'weekends'
+    | { workdays?: number[]; holidays?: Array<string | number | Date> };
+
   /**
-   * A task in a Gantt plan. Give a `duration` or a numeric `start`+`end` (one is
-   * derived from the other). `milestone: true` (or `duration: 0`) is a
-   * zero-duration point. `parent` nests a task under a summary task, whose window
-   * and progress are DERIVED from its children rather than scheduled.
+   * A task in a Gantt plan. Give a `duration` or a `start`+`end` (a day-number,
+   * ISO date string or `Date`; one is derived from the other). `milestone: true`
+   * (or `duration: 0`) is a zero-duration point. `parent` nests a task under a
+   * summary, whose window and progress are DERIVED from its children.
+   * `baselineStart`/`baselineEnd` (host-stored) drive planned-vs-actual variance;
+   * `constraint` pins or pulls the task; `assignee` and `height` feed the split
+   * view's grid panel.
    */
   export interface GanttTask {
     id: string | number;
     name?: string;
-    start?: number;
-    end?: number;
+    start?: number | string | Date;
+    end?: number | string | Date;
     duration?: number;
     percentComplete?: number;
     milestone?: boolean;
     parent?: string | number;
+    baselineStart?: number | string | Date;
+    baselineEnd?: number | string | Date;
+    baseline?: { start?: number | string | Date; end?: number | string | Date };
+    constraint?: GanttConstraintType;
+    constraintDate?: number | string | Date;
+    assignee?: string | string[];
+    assignees?: string[];
+    owner?: string;
+    /** An explicit row height (px) for the split view; applied to both panels. */
+    height?: number;
   }
 
   /**
@@ -6320,6 +6428,21 @@ declare module 'lattice-grid/modules/gantt' {
     isSummary: boolean;
     isMilestone: boolean;
     children: string[];
+    /** The planned (baseline) window, present only when the task carries a baseline. */
+    baselineStart?: number | null;
+    baselineEnd?: number | null;
+    /** Variance vs the baseline (actual − planned, day-numbers); a positive value is a slip. */
+    startVariance?: number | null;
+    finishVariance?: number | null;
+    durationVariance?: number | null;
+  }
+
+  /** An unhonourable scheduling constraint, reported rather than obeyed. */
+  interface GanttConflict {
+    id: string;
+    type: string;
+    at: number | null;
+    earliestFeasible: number;
   }
 
   /** A CPM schedule result: per-task dates/float and the critical path, or an error. */
@@ -6333,6 +6456,10 @@ declare module 'lattice-grid/modules/gantt' {
     projectStart?: number;
     projectFinish?: number;
     projectDuration?: number;
+    /** Constraints a predecessor made infeasible (empty when all are satisfied). */
+    conflicts?: GanttConflict[];
+    /** Whether a working-time calendar was applied. */
+    calendar?: boolean;
   }
 
   /** A placement violation flagged by `findViolations`. */
@@ -6355,7 +6482,7 @@ declare module 'lattice-grid/modules/gantt' {
    * and the zero-float critical path, with summaries derived from their children,
    * milestones scheduled as points, and dependency cycles refused (never looped).
    */
-  export function computeSchedule(tasks: GanttTask[], deps?: GanttDependency[], options?: { projectStart?: number; deadline?: number }): GanttSchedule;
+  export function computeSchedule(tasks: GanttTask[], deps?: GanttDependency[], options?: { projectStart?: number | string | Date; deadline?: number | string | Date; calendar?: GanttCalendar | null }): GanttSchedule;
 
   /** The tasks placed earlier than their earliest feasible start (manual validation). */
   export function findViolations(tasks: GanttTask[], schedule: GanttSchedule): GanttViolation[];
@@ -6369,6 +6496,8 @@ declare module 'lattice-grid/modules/gantt' {
     readonly dependencies: GanttDependency[];
     readonly schedule: GanttSchedule | null;
     readonly critical: string[];
+    /** Constraints the latest schedule could not honour (empty when all are satisfied). */
+    readonly conflicts: GanttConflict[];
     readonly autoSchedule: boolean;
     readonly grid: unknown;
     setTasks(tasks: GanttTask[]): GanttSchedule;
@@ -6423,6 +6552,36 @@ declare module 'lattice-grid/modules/gantt' {
       /** Days a keyboard arrow moves/resizes a task (default 1). */
       moveStep?: number;
     }): unknown;
+    /**
+     * Mount the JOINED split view (BACKLOG-0000938): one continuous, row-aligned
+     * surface with a left task-grid panel (Task Name tree with expand/collapse,
+     * assignee avatars, a circular % ring, plus any host columns) and the right
+     * timeline, sharing a single vertical scroll so every grid row lines up
+     * exactly with its bar row. The timeline scrolls horizontally on its own.
+     * Composes the controller's schedule; makes no change to grid core.
+     */
+    mountSplit(container: unknown, options?: {
+      height?: number;
+      rowHeight?: number;
+      headerHeight?: number;
+      gridWidth?: number;
+      indent?: number;
+      zoom?: 'day' | 'week' | 'month' | 'quarter' | number;
+      today?: number;
+      nonWorking?: 'weekends' | ((day: number) => boolean);
+      calendar?: GanttCalendar | null;
+      showArrows?: boolean;
+      showProgress?: boolean;
+      showBaseline?: boolean;
+      barLabel?: 'name' | 'percent' | 'dates' | 'none' | ((task: GanttScheduledTask) => string);
+      columns?: Array<{ key: string; title?: string; width?: number; kind?: 'name' | 'assignee' | 'progress'; render?: (task: GanttScheduledTask, ctx: { rawTask: GanttTask; depth: number }) => unknown }>;
+    }): unknown;
+    /**
+     * Capture a baseline (planned) snapshot of the current schedule as HOST data
+     * (this does not mutate the tasks). Store it and feed it back as
+     * `baselineStart`/`baselineEnd` task fields to get variance and ghost bars.
+     */
+    captureBaseline(): Array<{ id: string; baselineStart: number; baselineEnd: number; baselineDuration: number }>;
     /** Detach the mounted view, if any. The host still owns the container. */
     unmount(): void;
     /** The mounted view, or null. */
@@ -6440,9 +6599,12 @@ declare module 'lattice-grid/modules/gantt' {
   export function createGantt(opts?: {
     tasks?: GanttTask[];
     dependencies?: GanttDependency[];
-    projectStart?: number;
-    /** A project deadline (day-number); tasks that cannot meet it get negative float. */
-    deadline?: number;
+    /** The schedule anchor: a day-number, ISO date string or Date. It only sets the floor a task with no predecessor starts on; it does not change how the schedule is computed. */
+    projectStart?: number | string | Date;
+    /** A project deadline (a day-number, ISO string or Date); tasks that cannot meet it get negative float. */
+    deadline?: number | string | Date;
+    /** A working-time calendar: skip weekends/holidays, durations in working days. */
+    calendar?: GanttCalendar | null;
     autoSchedule?: boolean;
     grid?: unknown;
     /** Map task fields to grid column ids to enable drag write-back. */
@@ -6789,8 +6951,16 @@ declare module 'lattice-grid/modules/kanban' {
     swimlanes?: boolean;
     /** Explicit lane definitions; otherwise lanes come from the distinct swimlane values. */
     lanes?: (string | { id: string; title?: string })[];
+    /** An explicit lane order by id (also set by a lane-header-drag reorder). */
+    laneOrder?: string[];
+    /** Enforce `wipLimit` as a hard gate: a move that would exceed it is refused (default false). */
+    enforceWip?: boolean;
+    /** A custom card template: return an HTML string or a DOM node to own the whole card body. */
+    cardRenderer?: (card: KanbanCard, ctx: { column: KanbanColumn; readonly: boolean; el: HTMLElement; doc: Document }) => string | Node | void;
     sprintProperty?: string;
     epicProperty?: string;
+    /** A configurable sprint dataset: the canonical sprint list (order + titles), shown even when empty. */
+    sprints?: (string | { id: unknown; title?: string })[];
     /** The initially selected sprint id, `Kanban.BACKLOG`, or undefined for all. */
     sprint?: unknown;
     /** The initially selected epic id, or undefined for all. */
@@ -6933,6 +7103,10 @@ declare module 'lattice-grid/modules/kanban' {
     reorderColumns(order: string[]): Kanban;
     /** Move one column before another (or to the end); emits `column:reorder`. */
     moveColumn(id: string, beforeId: string | null): Kanban;
+    /** Reorder the swimlanes to the given id order (emits `swimlane:reorder`). */
+    reorderLanes(order: string[]): Kanban;
+    /** Move one swimlane before another (or to the end); emits `swimlane:reorder`. */
+    moveLane(id: string, beforeId: string | null): Kanban;
     /** Set a predicate filter over cards, or clear it with null. */
     setFilter(fn: ((row: KanbanRow, card: KanbanCard) => boolean) | null): Kanban;
     /** Set the quick-filter text matched across card fields. */
@@ -6947,8 +7121,10 @@ declare module 'lattice-grid/modules/kanban' {
     showBacklog(): Kanban;
     /** Select the shown epic (undefined for all); emits `epic:changed`. */
     setEpic(epic: unknown): Kanban;
-    /** The distinct sprint values (the switcher's options). */
+    /** The distinct sprint values (the switcher's options); a configured `sprints` dataset pins the order. */
     sprints(): unknown[];
+    /** The sprint dataset as `{ id, title }` descriptors — the configured list plus any data-only sprint. */
+    sprintDefs(): { id: unknown; title: string }[];
     /** The distinct epic values. */
     epics(): unknown[];
     /** Roll rows up by a property: per-bucket count, points, done and progress. */
@@ -6990,3 +7166,145 @@ declare module 'lattice-grid/modules/kanban' {
   export function createKanban(el: HTMLElement | null, config?: KanbanConfig): Kanban;
   export default createKanban;
 }
+
+declare module 'lattice-grid/modules/kpi' {
+  /** A row backing a KPI aggregate: any object. Its identity comes from `rowKey`. */
+  type KPIRow = Record<string, unknown>;
+
+  /** The aggregation kinds a tile can compute. `custom` is a host reducer over the rows. */
+  type KPIAggregation = 'sum' | 'avg' | 'min' | 'max' | 'count' | 'countDistinct' | 'custom';
+
+  /** Number formatting for a tile value. `percent` treats the value as a ratio (0.42 → 42%). */
+  type KPIFormat =
+    | 'number' | 'currency' | 'percent' | 'compact'
+    | { type?: 'number' | 'currency' | 'percent' | 'compact'; decimals?: number; currency?: string; locale?: string };
+
+  /**
+   * A semantic threshold: two cut points and a direction. `higherIsBetter` (the
+   * default) makes a value at/above `warn` good, at/above `critical` a warning,
+   * below it critical; `lowerIsBetter` mirrors it. Colour is a host concern.
+   */
+  interface KPIThresholds {
+    warn: number;
+    critical: number;
+    direction?: 'higherIsBetter' | 'lowerIsBetter';
+  }
+
+  /** An explicit band: the `status` of the first band whose half-open `[min, max)` contains the value. */
+  interface KPIBand {
+    min?: number;
+    max?: number;
+    status: 'good' | 'warn' | 'critical';
+  }
+
+  /** An optional sparkline series: the `y` field plotted in order of the `x` field (or insertion). */
+  interface KPISparkline {
+    x?: string;
+    y: string | ((row: KPIRow) => unknown);
+  }
+
+  /** One tile: an aggregate over the routed rows, with optional filter, format, threshold and trend. */
+  interface KPITile {
+    /** A stable identity for the tile (defaults to the label, then the index). */
+    id?: string;
+    /** The tile's accessible label. */
+    label?: string;
+    /** The aggregation kind, or a reducer `(rows, tile) => value` for a custom tile. */
+    aggregation?: KPIAggregation | ((rows: KPIRow[], tile: object) => unknown);
+    /** The reducer for a `custom` aggregation, when `aggregation` is the string `'custom'`. */
+    compute?: (rows: KPIRow[], tile: object) => unknown;
+    /** The field the aggregation reads (a path or accessor). Ignored by `count`. */
+    field?: string | ((row: KPIRow) => unknown);
+    /** A predicate limiting the rows this tile aggregates. */
+    filter?: (row: KPIRow) => boolean;
+    /** Value formatting. */
+    format?: KPIFormat;
+    /** A comparison target rendered alongside the value. */
+    target?: number;
+    /** A baseline the tile's delta is measured against. */
+    baseline?: number;
+    /** Threshold bands, either two cut points or an explicit band list. */
+    thresholds?: KPIThresholds;
+    /** Explicit status bands (an alternative to `thresholds`). */
+    bands?: KPIBand[];
+    /** A trend sparkline series. */
+    sparkline?: KPISparkline | string;
+  }
+
+  /** A computed tile, as it appears in the model. */
+  interface KPITileModel {
+    id: string;
+    label: string;
+    aggregation: string;
+    field?: string;
+    value: unknown;
+    formatted: string;
+    status: 'good' | 'warn' | 'critical' | null;
+    target?: number;
+    baseline?: number;
+    delta: number | null;
+    deltaPercent: number | null;
+    deltaFormatted?: string;
+    count: number;
+    sparkline: number[] | null;
+  }
+
+  /** The payload every tile event carries. */
+  interface KPIEvent {
+    tile: KPITileModel;
+    id: string;
+    originalEvent?: unknown;
+  }
+
+  /** KPI panel configuration. */
+  interface KPIConfig {
+    rows?: KPIRow[];
+    grid?: unknown;
+    rowKey?: string | ((row: KPIRow) => unknown);
+    tiles?: KPITile[];
+    columns?: number;
+    ariaLabel?: string;
+    nullText?: string;
+    onTileClick?: (event: KPIEvent) => void;
+    onTileDblClick?: (event: KPIEvent) => void;
+    onTileContextMenu?: (event: KPIEvent) => void;
+    onChange?: (event: { model: { tiles: KPITileModel[] } }) => void;
+  }
+
+  /** The keyed-diff consumer surface a KPI panel shares with a grid, so a Data Router routes to it directly. */
+  interface KPIRows {
+    apply(change: { add?: KPIRow[]; update?: KPIRow[]; remove?: unknown[] }): void;
+    forEach(fn: (row: KPIRow, key: unknown) => void): void;
+    readonly count: number;
+  }
+
+  /**
+   * A KPI / stat-tile panel: a grid of aggregate tiles over a dataset. It
+   * consumes data through the same keyed-diff `rows.apply` contract a grid
+   * exposes, so `dataRouter.attach(value, kpi)` drives it like any other viewer,
+   * updating each tile incrementally from the routed delta.
+   */
+  interface KPI {
+    readonly el: unknown | null;
+    readonly rowKey: string | ((row: KPIRow) => unknown);
+    rows: KPIRows;
+    tiles(): KPITileModel[];
+    tile(id: string): KPITileModel | undefined;
+    value(id: string): unknown;
+    setRows(rows: KPIRow[]): KPI;
+    refresh(): KPI;
+    getState(): object;
+    setState(snapshot: object): KPI;
+    on(name: string, fn: (event: KPIEvent) => void): () => void;
+    off(name: string, fn: (event: KPIEvent) => void): void;
+    destroy(): void;
+  }
+
+  /**
+   * Create a KPI / stat-tile panel over rows or a bound grid. Pass a DOM element
+   * to render into, or `null` for a headless panel that computes the same tile
+   * model without a DOM.
+   */
+  export function createKPI(el: HTMLElement | null, config?: KPIConfig): KPI;
+  export default createKPI;
+}