@toclocoinc/lattice-grid 1.63.3 → 1.65.0

package/docs/API.html

@@ -360,7 +360,7 @@
 <div class="shell">
   <aside class="rail">
     <p class="rail__brand">Lattice Grid</p>
-    <p class="rail__sub">API reference · v1.63.3</p>
+    <p class="rail__sub">API reference · v1.65.0</p>
     <nav>
       <div class="rail__group">
         <span class="rail__label">Start</span>
@@ -413,6 +413,12 @@
         <a href="#sources">Sources</a>
         <a href="#events">Event reference</a>
       </div>
+      <div class="rail__group">
+        <span class="rail__label">Frameworks</span>
+        <a href="#adapters">Framework adapters</a>
+        <a href="#react-v2">React</a>
+        <a href="#angular-v2">Angular</a>
+      </div>
       <div class="rail__group">
         <span class="rail__label">Registries</span>
         <a href="#names">Built-in names</a>
@@ -444,7 +450,7 @@
     </header>
 
     <p class="chips">
-      <span class="chip">Version 1.63.3</span>
+      <span class="chip">Version 1.65.0</span>
       <span class="chip">Zero dependencies</span>
       <span class="chip"><a href="api-detail.html">Developer guide &rarr;</a></span>
     </p>
@@ -520,6 +526,7 @@
         <thead><tr><th>Entry point</th><th>Factory</th><th>Needs</th></tr></thead>
         <tbody>
           <tr><td class="name">modules/react</td><td class="sig">createLatticeGrid({ React, createGrid })</td><td class="desc">Returns a component. Forwards a ref exposing <code>.grid</code>. Since 1.63 the same entry point also builds a component for <a href="#react-v2">every other viewer</a> and the data router.</td></tr>
+          <tr><td class="name">@toclocoinc/<wbr>lattice-grid-angular</td><td class="sig">&lt;lattice-grid [config]="…"&gt;</td><td class="desc">A package of its own, not a bundle: standalone components compiled ahead of time, one per viewer, plus the data router as a service. See <a href="#angular-v2">Angular</a>. <code>modules/angular</code>, which needs the JIT compiler, is deprecated.</td></tr>
           <tr><td class="name">modules/vue</td><td class="sig">createLatticeGrid({ vue, createGrid })</td><td class="desc">Returns a Vue 3 component definition.</td></tr>
           <tr><td class="name">modules/svelte</td><td class="sig">createLatticeAction({ createGrid })</td><td class="desc">Returns a <code>use:</code> action.</td></tr>
         </tbody>
@@ -706,6 +713,120 @@ controller.destroy();
       a line that could never run. The build now deletes that branch from every emitted artefact.
     </p>
 
+    <h3 id="angular-v2">Angular: a compiled package, <code>@toclocoinc/lattice-grid-angular</code></h3>
+    <p>
+      Angular's components are not objects a library can assemble at run time in a production
+      build. <code>modules/angular</code> did assemble them that way, which needs Angular's JIT
+      compiler in the page &mdash; present on a development server, absent from every AOT build.
+      So Angular gets a package of its own: TypeScript components compiled by
+      <code>@angular/compiler-cli</code> into a partial-Ivy library, which your build's Angular
+      Linker turns into definitions exactly as it does for any other Angular library you install.
+      <strong>No compiler in your bundle, and one standalone component per viewer.</strong>
+    </p>
+    <pre><code>npm install @toclocoinc/lattice-grid @toclocoinc/lattice-grid-angular</code></pre>
+    <pre><code><span class="kw">import</span> { bootstrapApplication } <span class="kw">from</span> '@angular/platform-browser';
+<span class="kw">import</span> { createGrid } <span class="kw">from</span> '@toclocoinc/lattice-grid';
+<span class="kw">import</span> { createKPI } <span class="kw">from</span> '@toclocoinc/lattice-grid/modules/kpi';
+<span class="kw">import</span> { createChart } <span class="kw">from</span> '@toclocoinc/lattice-grid/modules/charts';
+<span class="kw">import</span> {
+  LatticeGridComponent, LatticeKpiComponent, LatticeChartComponent, provideLattice,
+} <span class="kw">from</span> '@toclocoinc/lattice-grid-angular';
+
+@Component({
+  selector: 'app-dashboard',
+  imports: [LatticeGridComponent, LatticeKpiComponent, LatticeChartComponent],
+  template: `
+    &lt;lattice-grid #grid name="quakes" [config]="config" [quickFilter]="search()"
+                  (cell-changed)="save($event)" /&gt;
+    &lt;lattice-kpi  gridName="quakes" [config]="{ tiles }" /&gt;
+    &lt;lattice-chart gridName="quakes" [config]="{ type: 'bar', x: 'region', y: 'count' }" /&gt;
+  `,
+})
+<span class="kw">export class</span> Dashboard {
+  <span class="cmt">// The live grid, the same object createGrid returns.</span>
+  grid = viewChild&lt;LatticeGridComponent&gt;('grid');
+}
+
+<span class="cmt">// Each factory is injected, not imported by the library: an application that</span>
+<span class="cmt">// shows a grid downloads the grid, and never the board or the eighteen charts.</span>
+bootstrapApplication(Dashboard, {
+  providers: [provideLattice({ createGrid, createKPI, createChart })],
+});</code></pre>
+
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Export</th><th>Element</th><th>What it is</th></tr></thead>
+        <tbody>
+          <tr><td class="name">LatticeGridComponent</td><td class="sig">&lt;lattice-grid&gt;</td><td class="desc">The grid. <code>[config]</code> is every configuration key; <code>[sort]</code>, <code>[filters]</code>, <code>[quickFilter]</code> and <code>[selectedKeys]</code> are applied through the matching API; <code>[rowUpdates]</code> and <code>[predicates]</code> drive a live feed. Every grid event is an output under its kebab-case name, and <code>(grid-ready)</code> hands you the instance. Give the element a height.</td></tr>
+          <tr><td class="name">LatticeGridDirective</td><td class="sig">[latticeGrid]</td><td class="desc">The same component on an element your template already owns: <code>&lt;div [latticeGrid]="config" class="tall"&gt;&lt;/div&gt;</code>. Same inputs, outputs and <code>grid</code> reference.</td></tr>
+          <tr><td class="name">LatticeKpiComponent</td><td class="sig">&lt;lattice-kpi&gt;</td><td class="desc">The KPI panel. Grid-bound by default &mdash; <code>[gridName]</code> picks which published grid &mdash; or give it <code>[rows]</code> for a panel with no grid.</td></tr>
+          <tr><td class="name">LatticeChartComponent</td><td class="sig">&lt;lattice-chart&gt;</td><td class="desc">A chart. Requires a grid, so nothing is built until one exists; a changed spec key goes to <code>chart.update()</code> and the chart redraws rather than being rebuilt. <code>(click)</code>, <code>(hover)</code> and <code>(leave)</code> on this element are the chart's events, carrying the datum under the pointer.</td></tr>
+          <tr><td class="name">LatticeKanbanComponent</td><td class="sig">&lt;lattice-kanban&gt;</td><td class="desc">The board. <code>[rows]</code>, <code>[quickFilter]</code>, <code>[sprint]</code>, <code>[epic]</code>, <code>[loading]</code> and <code>[error]</code> are live inputs.</td></tr>
+          <tr><td class="name">LatticeGanttComponent</td><td class="sig">&lt;lattice-gantt&gt;</td><td class="desc">The plan. <code>[tasks]</code> and <code>[dependencies]</code> are live inputs. It takes an explicit <code>[grid]</code> but never adopts a published one.</td></tr>
+          <tr><td class="name">LatticeLayoutComponent</td><td class="sig">&lt;lattice-layout&gt;</td><td class="desc">The dashboard layout. Windows are driven through the instance; its events arrive as <code>(layout-changed)</code>, <code>(window-moved)</code> and the rest.</td></tr>
+          <tr><td class="name">LatticeTabsComponent<br>LatticeTabDirective</td><td class="sig">&lt;lattice-tabs&gt;<br>ng-template[latticeTab]</td><td class="desc">The tab strip, with <strong>Angular-rendered tab content</strong>: a tab's content is an <code>&lt;ng-template latticeTab="id"&gt;</code> in your own template, rendered into the strip's panel through this component's <code>ViewContainerRef</code> &mdash; so a tab's grid is a real <code>&lt;lattice-grid&gt;</code> with inputs, a reference and your injectors above it. A tab with no template is left to the module, so configuration-driven grid tabs still work and the two kinds mix on one strip.</td></tr>
+          <tr><td class="name">LatticeGridRegistry</td><td class="sig">inject(LatticeGridRegistry)</td><td class="desc">Where <code>&lt;lattice-grid name="…"&gt;</code> publishes itself and grid-bound viewers find it, as a signal per name &mdash; a panel declared before its grid exists mounts itself the moment the grid arrives. <code>providedIn: 'root'</code>; put it in a component's own <code>providers</code> to scope a registry to that subtree.</td></tr>
+          <tr><td class="name">provideLattice</td><td class="sig">provideLattice({ …factories })</td><td class="desc">The factories the components build through. Give it the ones your application uses; a component whose factory is missing names the import and the provider call that fixes it.</td></tr>
+          <tr><td class="name">provideLatticeRouter<br>LatticeRouter</td><td class="sig">providers: [provideLatticeRouter(cfg)]</td><td class="desc">The data router as a service. Put it in a component's <code>providers</code> and it is created when the first <code>&lt;lattice-grid route="…"&gt;</code> under it attaches, and destroyed with that component &mdash; its configuration read once, because rebuilding would drop every attached grid and every row it holds. Each grid detaches before it is destroyed, so the router never holds a dead grid.</td></tr>
+        </tbody>
+      </table>
+    </div>
+
+    <p class="section-note">
+      <strong>Change detection: zone or zoneless, unconfigured.</strong> The grid is created inside
+      <code>NgZone.runOutsideAngular</code>, because it installs its own scroll, wheel and pointer
+      listeners and running change detection on every scroll frame of a million-row grid is the
+      difference between smooth and unusable. An event that reaches an output you have
+      <em>bound</em> re-enters the zone, so <code>(cell-changed)="count = count + 1"</code> repaints
+      exactly as you expect; an output nobody bound costs nothing. Under zoneless change detection
+      that machinery is Angular's own no-op and a signal you set in a handler repaints the view.
+      The one thing to know when reading the grid's DOM from Angular: <strong>the grid paints on its
+      own schedule, not Angular's</strong>, so measure a cell in a grid event, not in
+      <code>ngAfterViewInit</code>.
+    </p>
+    <p class="section-note">
+      <strong><code>OnPush</code> is safe everywhere.</strong> None of these components asks its
+      parent to re-render: each owns one element, builds one instance in
+      <code>afterNextRender</code> and pushes changed inputs into it from <code>ngOnChanges</code>.
+      A host on <code>OnPush</code> that never re-renders still gets a fully live grid, because the
+      grid is not rendered by Angular.
+    </p>
+    <p class="section-note">
+      <strong>Inputs are diffed by identity, and never rebuild the instance.</strong> A changed
+      input reaches the viewer that is already on screen &mdash; scroll position, selection,
+      expansion and any open editor intact. Two things rebuild rather than update: the grid a
+      viewer is bound to, and an input it cannot exist without. An input a viewer has no live
+      setter for is named once in a warning rather than silently dropped. And because the
+      comparison is <code>Object.is</code>, an inline <code>[config]="{ rows: rows }"</code> is a
+      new object on every pass: hold it in a field or a signal.
+    </p>
+    <p class="section-note">
+      <strong>Cleanup is the component's.</strong> <code>ngOnDestroy</code> detaches from the
+      router, withdraws the grid from the registry and destroys the instance &mdash; in that order.
+      An <code>&#64;if</code> that closes and opens again leaves exactly one instance alive, and
+      destroying the application leaves no instance, interval or listener behind. That is asserted
+      with counters in a real browser, against the linked package, in
+      <code>test/angular-package-browser.test.js</code>.
+    </p>
+    <p class="section-note">
+      <strong>Angular 17 and up, browser only.</strong> The library is compiled partially, so your
+      own Angular version compiles it: its declarations need a linker no newer than 14, and its peer
+      range is <code>&gt;=17</code>. Nothing is created on the server &mdash;
+      <code>isPlatformBrowser</code> guards every build and <code>afterNextRender</code> does not
+      run there &mdash; so a server-rendered page emits the empty host element and the grid is built
+      on hydration. Angular Universal is not otherwise supported.
+    </p>
+    <p class="section-note">
+      <strong><code>modules/angular</code> is deprecated.</strong> The old bundle still works where
+      it always worked &mdash; a page with <code>@angular/compiler</code> loaded &mdash; and it now
+      says so once, and fails with a <code>[lattice]</code> message naming this package when it
+      finds a real Angular with no JIT compiler, instead of leaving you with Angular's own. In
+      1.65 it also gained the fix that <code>&lt;div [latticeGrid]="config"&gt;</code> binds the
+      configuration through the directive's selector, as its documentation always said it did. It
+      will be removed in a later release; move to <code>@toclocoinc/lattice-grid-angular</code>,
+      which covers every viewer rather than the grid alone.
+    </p>
+
     <div class="note">
       <p><strong>Published as <code>@toclocoinc/lattice-grid</code></strong>: <code>npm install
       @toclocoinc/lattice-grid</code>, then <code>import { createLatticeGrid } from
@@ -1393,7 +1514,7 @@ grid.destroy();
       <table>
         <thead><tr><th>Member</th><th>Returns</th><th>Description</th></tr></thead>
         <tbody>
-          <tr><td class="sig">getVersion()</td><td class="type">string</td><td class="desc">The version this grid came from, e.g. <code>'1.63.3'</code>. Also on the module as <code>getVersion()</code>, for when you have no grid to hand.</td></tr>
+          <tr><td class="sig">getVersion()</td><td class="type">string</td><td class="desc">The version this grid came from, e.g. <code>'1.65.0'</code>. Also on the module as <code>getVersion()</code>, for when you have no grid to hand.</td></tr>
           <tr><td class="sig">get(key)</td><td class="type">unknown</td><td class="desc">Read any configuration key.</td></tr>
           <tr><td class="sig">set(key, value)</td><td class="type">void</td><td class="desc">Write one key. Every key is live; nothing needs a rebuild.</td></tr>
           <tr><td class="sig">setAll(values)</td><td class="type">void</td><td class="desc">Write several in one pass. Emits one <code>config:changed</code> for the batch, not one per key.</td></tr>
@@ -5164,7 +5285,7 @@ const chart = createChart({
           <tr><td class="sig">Part to whole</td><td><code>pie</code>, <code>donut</code>, <code>sunburst</code>, <code>treemap</code></td><td><code>x</code>, <code>y</code>; or the grid's grouping, see below</td></tr>
           <tr><td class="sig">Specialist</td><td><code>radar</code>, <code>gauge</code>, <code>funnel</code>, <code>candlestick</code></td><td>varies; candlestick takes four <code>measures</code> in open, high, low, close order</td></tr>
           <tr><td class="sig">Geographic</td><td><code>geomap</code></td><td><code>x</code> as an ISO code, <code>y</code> as the value</td></tr>
-          <tr><td class="sig">Flow</td><td><code>sankey</code>, <code>chord</code>, <code>network</code></td><td><code>source</code>, <code>target</code>, <code>y</code></td></tr>
+          <tr><td class="sig">Flow</td><td><code>sankey</code>, <code>chord</code>, <code>network</code></td><td><code>source</code>, <code>target</code>, <code>y</code>; a <code>network</code> also takes <code>nodes</code> &mdash; see <a href="#network-map">Network diagrams</a></td></tr>
           <tr><td class="sig">Over time</td><td><code>stream</code>, <code>marimekko</code>, <code>violin</code>, <code>gantt</code></td><td>varies; gantt takes <code>label</code>, <code>start</code>, <code>end</code></td></tr>
         </tbody>
       </table>
@@ -5211,6 +5332,9 @@ const chart = createChart({
           <tr><td class="name">code / codeProperty</td><td class="type">string</td><td class="desc">A geomap's ISO code column, and the property carrying the code in your <code>shapes</code>.</td></tr>
           <tr><td class="name">columns / method / values</td><td class="type">string[] / string / boolean</td><td class="desc">Correlogram: which columns to correlate, by <code>pearson</code>, <code>spearman</code> or <code>kendall</code>, and whether to print the coefficients in the cells.</td></tr>
           <tr><td class="name">iterations</td><td class="type">number</td><td class="desc">Network layouts: how many relaxation passes to run.</td></tr>
+          <tr><td class="name">nodes</td><td class="type">ChartNode[]</td><td class="desc">A <code>network</code>'s nodes, named by you rather than inferred from the rows: <code>{ id, label, icon, x, y }</code>. <code>id</code> matches a value in the <code>source</code> or <code>target</code> column; <code>icon</code> is any name in the grid's icon registry; <code>x</code>/<code>y</code> are fractions of the plot (0&nbsp;to&nbsp;1) and <strong>pin</strong> the node there, out of the force simulation. A node listed here that appears in no row is still drawn. See <a href="#network-map">Network diagrams</a>.</td></tr>
+          <tr><td class="name">icon</td><td class="type">string</td><td class="desc">The default glyph for a <code>network</code> node that names none of its own. Unset, an undeclared node is a plain disc.</td></tr>
+          <tr><td class="name">linkWidth</td><td class="type">number</td><td class="desc">Fix a <code>network</code> link's stroke width in pixels. Unset, width follows the link's value as a share of the heaviest link.</td></tr>
           <tr><td class="name">spec / baseline / rules / confidence</td><td class="type">object / number / string / number</td><td class="desc">Control and capability charts: a tolerance overriding the column's own <code>spec</code>, how many leading readings fix the control limits, which rule set judges the violations (<code>westernElectric</code> or <code>nelson</code>), and the level for the capability interval.</td></tr>
         </tbody>
       </table>
@@ -5486,6 +5610,97 @@ createChart({ grid, container: '#us', type: 'geomap', code: 'state', y: 'sales',
 
     <div class="note"><p>The module imports nothing from the grid: <code>createChart</code> is handed a grid rather than importing one. That is what keeps the charts bundle to the drawing, and it is why the grid must be created first, and why a chart cannot outlive it.</p></div>
 
+    <h3 id="network-map">Network diagrams &mdash; icon nodes, links coloured by their value</h3>
+    <p>A <code>network</code> draws the grid's rows as a graph: <code>source</code> and <code>target</code> name the two endpoint columns and <code>y</code> carries the value on the link between them. Three things make it a picture of <em>your</em> network rather than a generic hairball, and each is a fact only you have.</p>
+    <p><strong>Nodes you name.</strong> <code>nodes: [{ id, label, icon, x, y }]</code> gives a node a glyph from the grid's own icon registry &mdash; a built-in name, or one you registered &mdash; and a label drawn beneath it. A node that appears in the rows but not in <code>nodes</code> takes the chart's <code>icon</code> default (a plain disc when there is none) and its own id as its label. A node listed in <code>nodes</code> that appears in <em>no</em> row is still drawn: a device with no links is a fact worth seeing. The glyphs are SVG paths from the same registry the cells paint from, so they are sharp at any chart size and take the chart's theme colours.</p>
+    <p><strong>Positions you choose.</strong> <code>x</code> and <code>y</code> are fractions of the plot, measured from its top-left. A node giving <em>both</em> is <strong>pinned</strong> there and takes no part in the force simulation; everything else is laid out around it by the same deterministic relaxation as before, so &ldquo;core on top, regions below&rdquo; needs no hand-placed SVG. Half a position is not a position: a node with only <code>x</code> is laid out. A fraction outside 0&nbsp;to&nbsp;1 clamps to the edge of the plot rather than drawing where nobody can see it. Pinning one node never reshuffles the others &mdash; the layout's seeding draws for every node, pinned or not, precisely so that it cannot.</p>
+    <p><strong>Colours from the rules you already wrote.</strong> Each link's stroke comes from the value column's own conditional-formatting rules, through <code>grid.formatting.styleFor(col, value)</code> &mdash; the colour order is <code>background</code>, then <code>backgroundColor</code>, then <code>color</code>; a gradient (a data bar, an icon set) is not a colour and is not read. A link no rule matches keeps the chart's default link colour. <strong>There is no chart-level threshold option, deliberately</strong>: a second place to say &ldquo;red above 80&rdquo; is a second place for the chart and the cell to disagree. The legend lists the rules that actually fired, with their own labels and their own swatches; a rule that matched nothing is not advertised. Change a rule and the links recolour on the next frame without the layout re-running, so nothing moves.</p>
+    <p><strong>Links are undirected, and parallel links stay parallel.</strong> There are no arrowheads, and <code>A,B</code> is the same pair as <code>B,A</code> &mdash; a cable has two ends and no direction. <strong>Several rows between the same pair are drawn as several lines</strong>, side by side, offset perpendicular to the pair by 4&nbsp;px and symmetric about it, in row order, each with its own value and its own colour. They are <em>not</em> summed: three circuits between two sites are three readings, and one line carrying 120% would be a number nothing measured. The tooltip on any one line names both endpoints and that line's own value, and the pointer picks out the line you are actually over rather than the pair. Width follows the value unless <code>linkWidth</code> fixes it.</p>
+    <p><strong>Linked like every other chart.</strong> The graph is drawn from the grid's filtered rows and follows filter and sort. With <code>selection: true</code>, clicking a link selects its row and clicking a node selects every row it is an end of; the grid's selection then lights those links and nodes and dims the rest. A <code>click</code> handler still fires first and can <code>preventDefault()</code>.</p>
+
+    <h4 id="network-map-example">The picture, executed</h4>
+    <p class="section-note">Two core routers pinned across the top, three regional routers pinned below, two circuits between every pair, and one rule set on the <code>load</code> column doing all the colouring. Thirteen rows, thirteen lines, three colours, five glyphs, and a legend that names the three rules.</p>
+    <pre data-run="js" data-expect="13 links, #107c41/#a4262c/#f0b400 | pinned true | gap 4 | 5 icons | Healthy,Busy,Saturated" data-covers="export:createChart export:createGrid config:formatting config:selection"><code>const { createTestDom } = await import('../packages/dom/src/renderer/testdom.js');
+const { createGrid } = await import('../packages/dom/src/index.js');
+const { createChart } = await import('../packages/modules/charts/index.js');
+
+const { document, root } = createTestDom({ width: 640, height: 420 });
+
+// Two circuits between every core and every region: six pairs, twelve rows.
+const rows = [];
+for (const core of ['core-1', 'core-2']) {
+  for (const site of ['emea', 'amer', 'apac']) {
+    for (const [n, load] of [['a', 18], ['b', 92]]) {
+      rows.push({ id: `${core}/${site}/${n}`, from: core, to: site, load });
+    }
+  }
+}
+rows.push({ id: 'core-1/core-2/x', from: 'core-1', to: 'core-2', load: 61 });
+
+const grid = createGrid(root, {
+  rowKey: 'id',
+  selection: 'multiple',
+  columns: [{ field: 'from' }, { field: 'to' }, { field: 'load', type: 'number' }],
+  rows,
+  // One rule set on the column. The cells and the links read it together.
+  formatting: {
+    load: [
+      { id: 'ok', label: 'Healthy', when: { op: 'lt', value: 40 }, style: { background: '#107c41' } },
+      { id: 'busy', label: 'Busy', when: { op: 'lt', value: 80 }, style: { background: '#f0b400' } },
+      { id: 'hot', label: 'Saturated', when: { op: 'gte', value: 80 }, style: { background: '#a4262c' } },
+    ],
+  },
+});
+
+const container = document.createElement('div');
+container.rect = { width: 600, height: 400, top: 0, left: 0 };
+root.appendChild(container);
+
+const chart = createChart({
+  grid, container, type: 'network', source: 'from', target: 'to',
+  y: { col: 'load', fn: 'sum' }, selection: true,
+  nodes: [
+    { id: 'core-1', label: 'Core', icon: 'square', x: 0.3, y: 0.15 },
+    { id: 'core-2', label: 'Core', icon: 'square', x: 0.7, y: 0.15 },
+    { id: 'emea', label: 'EMEA', icon: 'circleFilled', x: 0.2, y: 0.8 },
+    { id: 'amer', label: 'AMER', icon: 'circleFilled', x: 0.5, y: 0.8 },
+    { id: 'apac', label: 'APAC', icon: 'circleFilled', x: 0.8, y: 0.8 },
+  ],
+});
+
+const find = (tag, cls) =&gt; [...container.querySelectorAll(tag)]
+  .filter((n) =&gt; (n.getAttribute('class') || '').includes(cls));
+const at = (key) =&gt; find('circle', '__node').find((c) =&gt; c.getAttribute('data-node') === key);
+const num = (el, name) =&gt; Number(el.getAttribute(name));
+
+// The picture: two cores on one row, three regions on another below them.
+const top = [at('core-1'), at('core-2')].map((c) =&gt; num(c, 'cy'));
+const bottom = ['emea', 'amer', 'apac'].map((k) =&gt; num(at(k), 'cy'));
+const rowsPinned = top[0] === top[1] &amp;&amp; bottom.every((y) =&gt; y === bottom[0]) &amp;&amp; bottom[0] &gt; top[0]
+  &amp;&amp; num(at('core-1'), 'cx') &lt; num(at('core-2'), 'cx');
+
+// Every link its own line, coloured by the rule its value matched.
+const edges = find('path', '__edge');
+const stroke = (e) =&gt; ((e.getAttribute('style') || '').match(/stroke:\s*([^;]+)/) || [])[1];
+const colours = [...new Set(edges.map(stroke))].sort();
+
+// Two circuits between core-1 and emea, drawn side by side 4px apart.
+const ends = (d) =&gt; d.match(/-?\d+(?:\.\d+)?/g).map(Number);
+const pair = edges.slice(0, 2).map((e) =&gt; ends(e.getAttribute('d')));
+const gap = Math.round(Math.hypot(pair[0][0] - pair[1][0], pair[0][1] - pair[1][1]));
+
+// Five glyphs, drawn from the registry the host extended.
+const glyphs = find('path', '__node-icon').length;
+
+// The legend names the rules that fired, not a palette.
+const legend = [...container.querySelectorAll('button')]
+  .filter((b) =&gt; (b.getAttribute('class') || '').includes('__legend-item'))
+  .map((b) =&gt; b.textContent).join(',');
+
+chart.destroy();
+grid.destroy();
+return `${edges.length} links, ${colours.join('/')} | pinned ${rowsPinned} | gap ${gap} | ${glyphs} icons | ${legend}`;</code></pre>
+
     <h3 id="chart-extension-types">Extension chart types — pay only for what you draw</h3>
     <p>The base charts bundle draws the built-in <code>TYPES</code> and nothing else. A new chart type is a <strong>separate, opt-in module</strong> a caller imports only if they use it (BACKLOG-0000886, on the slim-core seam BACKLOG-0000884). Importing it self-registers the type with the base module through <code>registerChartType</code>; the base <code>Chart</code> consults that registry for any type it does not draw natively. Because the base never imports the extension, the base bundle <strong>does not grow</strong> for a type a caller never uses.</p>
     <pre><code><span class="kw">import</span> '@toclocoinc/lattice-grid/modules/charts';           <span class="cmt">// the base</span>
@@ -5601,6 +5816,62 @@ grid.destroy();
   typeof hexmap.drawHexMap, typeof hexmap.bindHexMap,
 ].join(' | ');</code></pre>
 
+    <h3 id="chart-markermap">Map markers &mdash; a figure per location, coloured by its own rule</h3>
+    <p><code>modules/chart-markermap</code> registers <code>markermap</code>: one marker per row, placed by <code>lon</code>/<code>lat</code> over a geometry pack's outlines, showing the row's <code>label</code> and its <code>value</code> beside the dot. Two things come from the grid rather than from the chart, and that is the whole point of the type. The <strong>number</strong> is the value column's own formatted cell text, so a percentage, a currency or a unit reads on the map exactly as it reads in the table. The <strong>colour</strong> is whatever <code>grid.formatting.styleFor(valueColumn, value)</code> returns for that row &mdash; the rule's <code>background</code>, or its <code>color</code> where it sets no background &mdash; so a red / amber / green availability wall is one rule set on one column plus one chart configuration. There is deliberately no chart-level thresholds option and no colour column: the rules are the one source, and a legend lists the rules that actually fired, with each rule's own swatch.</p>
+    <p>With <code>shapes</code> it draws the pack's regions underneath, through the pack's own <code>projection</code>, and pans and zooms exactly as a <a href="#geometry-packs">geomap</a> of that pack does; without <code>shapes</code> the markers fall back to the projection alone. A row whose coordinates are absent, non-numeric or outside &plusmn;180 / &plusmn;90 draws no marker and is counted in <code>chart.data().unplaced</code>, which the map also writes under itself. Labels are deconflicted by trying four positions in a fixed order &mdash; right of the dot, then left, then above, then below &mdash; and a label with nowhere to go is dropped rather than overprinted; <code>labels: false</code> turns them all off on a dense map and leaves the tooltip, which carries the name, the value, the coordinates and the status. With <code>selection: true</code> a click on a marker selects that row in the grid, and the grid's selection emphasises the marker.</p>
+    <pre data-run="js" data-expect="#1b7f3b #1b7f3b #c8a415 #c0392b | London 99.95% / Sydney 99.91% / Frankfurt 99.62% / New York 98.05% | unplaced 0" data-covers="export:drawMarkerMap export:bindMarkerMap"><code><span class="kw">const</span> { createTestDom } = <span class="kw">await</span> import('../packages/dom/src/renderer/testdom.js');
+<span class="kw">const</span> { document, root } = createTestDom({ width: 700, height: 460 });
+<span class="kw">const</span> panel = document.createElement('div');
+panel.rect = { width: 700, height: 460, top: 0, left: 0 };
+root.appendChild(panel);
+
+<span class="kw">const</span> { createHeadlessGrid } = <span class="kw">await</span> import('../packages/core/src/index.js');
+<span class="kw">const</span> { createChart } = <span class="kw">await</span> import('../packages/modules/charts/index.js');
+<span class="cmt">// Importing the module registers `markermap`; its drawer is drawMarkerMap.</span>
+<span class="kw">const</span> markermap = <span class="kw">await</span> import('../packages/modules/chart-markermap/index.js');
+<span class="kw">const</span> { pack } = <span class="kw">await</span> import('../packages/modules/geo-world-110m/index.js');
+
+<span class="kw">const</span> grid = createHeadlessGrid({
+  rowKey: 'id',
+  columns: [
+    { field: 'site', type: 'text' }, { field: 'lng', type: 'number' },
+    { field: 'lat', type: 'number' }, { field: 'avail', type: 'number', format: '0.00%' },
+  ],
+  rows: [
+    { id: 'ldn', site: 'London', lng: -0.13, lat: 51.5, avail: 0.9995 },
+    { id: 'syd', site: 'Sydney', lng: 151.2, lat: -33.87, avail: 0.9991 },
+    { id: 'fra', site: 'Frankfurt', lng: 8.68, lat: 50.11, avail: 0.9962 },
+    { id: 'nyc', site: 'New York', lng: -74.0, lat: 40.71, avail: 0.9805 },
+  ],
+});
+<span class="cmt">// Three rules on the column. Nothing below repeats a threshold or a colour.</span>
+grid.formatting.add('avail', { when: { op: 'gte', value: 0.999 }, style: { background: '#1b7f3b' }, label: 'Healthy' });
+grid.formatting.add('avail', { when: { op: 'gte', value: 0.99 }, style: { background: '#c8a415' }, label: 'Watch' });
+grid.formatting.add('avail', { when: { op: 'lt', value: 0.99 }, style: { background: '#c0392b' }, label: 'Breached' });
+
+<span class="kw">const</span> chart = createChart({
+  grid, container: panel, type: 'markermap',
+  lon: 'lng', lat: 'lat', label: 'site', value: 'avail', shapes: pack,
+});
+
+<span class="cmt">// What was painted: a fill per marker, and the text beside each dot.</span>
+<span class="kw">const</span> fills = [];
+<span class="kw">const</span> labels = [];
+<span class="kw">const</span> walk = (node) =&gt; {
+  <span class="kw">for</span> (<span class="kw">const</span> child <span class="kw">of</span> node.children || []) {
+    <span class="kw">const</span> cls = String(child.getAttribute('class') || '');
+    <span class="kw">if</span> (cls.includes('markermap-dot')) fills.push(child.getAttribute('fill'));
+    <span class="kw">if</span> (cls.includes('data-label')) labels.push(child.textContent);
+    walk(child);
+  }
+};
+walk(chart.element);
+
+<span class="cmt">// The binder is public too, for a host that wants the placed rows itself.</span>
+<span class="kw">const</span> bound = markermap.bindMarkerMap(grid, { lon: 'lng', lat: 'lat', label: 'site', value: 'avail' });
+chart.destroy();
+<span class="kw">return</span> `${fills.join(' ')} | ${labels.join(' / ')} | unplaced ${bound.unplaced}`;</code></pre>
+
     <h2 id="datarouter">The data router</h2>
     <p><code>modules/data-router</code> is a host-layer demultiplexer: it takes <strong>one</strong> arriving stream or dataset, splits it by what each record <em>is</em>, and routes each partition to its own grid &mdash; or to a headless grid driving a chart. One round-trip, or one live feed, hydrates a whole screen of grids that each see only their slice. It is optional, imports nothing from the grid, and adds no core hook: every grid is driven through the <strong>public</strong> incremental path, <code>grid.rows.apply({ add, update, remove })</code>. <strong>The router never opens a connection itself &mdash; the host owns the connection (a <code>WebSocket</code>, SSE, CDC, a message bus, a plain fetch), and the router owns everything once a message has arrived</strong>; see <a href="#datarouter-websocket-example">a live WebSocket feed</a> for the worked, runnable integration.</p>
     <pre><code>import { createDataRouter } from '@toclocoinc/lattice-grid/modules/data-router';
@@ -5869,7 +6140,7 @@ socketA.close();
 <span class="kw">const</span> droppedBefore = router.dropped;
 <span class="kw">const</span> socketB = <span class="kw">new</span> MockWebSocket({ feed: feedB(), rate: 5, jitter: 0, snapshotDelay: 5 });
 wireRouter(router, socketB);
-<span class="kw">await</span> wait(30);
+<span class="kw">await</span> wait(80);
 <span class="kw">const</span> afterReconnect = g.rows.value('a', 'label');        <span class="cmt">// A@4 — only the new delta advanced it</span>
 <span class="kw">const</span> replaysDropped = router.dropped - droppedBefore;    <span class="cmt">// 2 — both replays dropped</span>
 socketB.close();
@@ -6681,6 +6952,52 @@ const kpi = createKPI(document.querySelector('#kpis'), {
       </table>
     </div>
     <p><strong>Interaction is light and host-driven.</strong> A tile emits <code>tile:click</code> (also from the keyboard) carrying the tile model, so a host can drill down or, in a demo, filter a routed grid &mdash; the wiring lives in the host, not the module. This is deliberately not a dashboard layout engine (that is the parked dashboard generator) and charting beyond a minimal sparkline belongs to the charts module.</p>
+    <h3 id="kpi-clock">The clock tile: the device clock, not an aggregate</h3>
+    <p><code>{ kind: 'clock', label, timeZone?, locale?, seconds?, date? }</code> in <code>tiles</code> renders a tile that shows the current date and time instead of a figure &mdash; the date on one line, the time on the next, e.g. <code>Mon, 21 Apr 2025</code> over <code>14:32:18</code> &mdash; styled like any other tile, so a panel of zone clocks beside a panel of figures reads as one visual system with no host CSS.</p>
+    <pre><code>const kpi = createKPI(document.querySelector('#kpis'), {
+  tiles: [
+    { kind: 'clock', label: 'London',   timeZone: 'Europe/London' },
+    { kind: 'clock', label: 'New York', timeZone: 'America/New_York', locale: 'en-US' },
+    { id: 'open', label: 'Open deals', aggregation: 'count', filter: (r) =&gt; r.stage !== 'won' },
+  ],
+});</code></pre>
+    <p><strong>Where the time comes from.</strong> The device clock, read every second in exact alignment with the second boundary &mdash; not a fixed <code>setInterval(1000)</code>, which drifts &mdash; so every clock tile on a panel ticks in the same repaint. One timer serves the <em>whole panel</em>, not one per tile: a panel of three zone clocks runs one shared interval, not three. The timer stops when the panel is <code>destroy()</code>ed or the document goes into the background (<code>document.hidden</code>) and resumes correctly &mdash; catching up immediately, then re-aligning &mdash; when the tab returns. A panel with no clock tile starts no timer at all.</p>
+    <p><strong>Zone and format.</strong> <code>timeZone</code> is any IANA zone name; omitted, the tile shows the viewer's local time. A name <code>Intl.DateTimeFormat</code> does not recognise is reported through the usual <code>[lattice]</code> diagnostics warning, by name, and the tile falls back to local time rather than rendering nothing. The date and time are formatted for <code>locale</code> &mdash; the tile's own, else the panel's <code>locale</code>, else the browser's default &mdash; entirely through <code>Intl.DateTimeFormat</code>: a 24-hour clock where the locale uses one, 12-hour with an AM/PM marker where it does not, because that is the locale's own convention rather than a second option to set. <code>seconds: false</code> drops the seconds from the time line; <code>date: false</code> drops the date line entirely. Every formatter is built once, at tile resolution, and reused on every tick.</p>
+    <p><strong>Inert everywhere a stat tile measures.</strong> A clock tile takes none of a stat tile's measurement options &mdash; <code>aggregation</code>, <code>field</code>, <code>format</code>, <code>thresholds</code>, <code>bands</code>, <code>target</code>, <code>baseline</code>, <code>sparkline</code> &mdash; because a tile that measures nothing has nothing for them to apply to. Supplying any of them is reported as a configuration warning by name and ignored: the tile still renders the clock, nothing else. It contributes nothing to the panel's totals, to a parent's rolled-up status in a <a href="#kpi-tree">tree</a> (its own <code>status</code> is always <code>null</code>, never <code>unknown</code> &mdash; a clock tile is never &ldquo;not measured&rdquo;, it always has a reading) and nothing to what a host reads out of <code>onChange</code> beyond its own text. It otherwise behaves exactly like any other tile: it sits in <code>tiles()</code>/<code>tile(id)</code> and a <a href="#kpi-tree">tree</a> alongside stat tiles, responds to <code>columns</code>, fires <code>tile:click</code>/<code>tile:dblclick</code>/<code>tile:contextmenu</code>, and its accessible name (<code>aria-label</code>) carries the same date and time text the two visible lines show.</p>
+    <h3 id="kpi-clock-example">A clock tile, two zones, executed</h3>
+    <p class="section-note">Structural assertions only &mdash; the clock reads the real device clock, so a doc example run on every build cannot pin a literal
+    time without freezing it. The <a href="#kpi-clock">formatting itself</a> is pinned for two locales and two zones with a fixed clock
+    in the test suite. Run headless on every build.</p>
+    <pre data-run="js" data-expect="clock clock null null null | true true | clock" data-covers="export:createKPI"><code><span class="kw">const</span> { createKPI } = <span class="kw">await</span> import('../packages/modules/kpi/index.js');
+
+<span class="kw">const</span> kpi = createKPI(null, {
+  tiles: [
+    { kind: 'clock', id: 'london', label: 'London', timeZone: 'Europe/London', locale: 'en-GB' },
+    <span class="cmt">// aggregation/thresholds are measurement options a clock tile refuses (warned, ignored):</span>
+    { kind: 'clock', id: 'ny', label: 'New York', timeZone: 'America/New_York', locale: 'en-US',
+      aggregation: 'sum', thresholds: { warn: 1, critical: 2 } },
+  ],
+});
+
+<span class="kw">const</span> london = kpi.tile('london');
+<span class="kw">const</span> ny = kpi.tile('ny');
+
+<span class="cmt">// kind, status and bar are the same three neutral values on every clock tile,</span>
+<span class="cmt">// whatever was supplied for the ignored options above (String(), because</span>
+<span class="cmt">// Array#join renders null as '' rather than 'null'):</span>
+<span class="kw">const</span> shapes = [london.kind, ny.kind, String(london.status), String(ny.status), String(ny.bar)].join(' '); <span class="cmt">// clock clock null null null</span>
+
+<span class="cmt">// The date and time lines hold the shape the formatting spec promises:</span>
+<span class="kw">const</span> shaped = [
+  /^[A-Za-z]{3}, \d{2} [A-Za-z]{3,4} \d{4}$/.test(london.clock.date),
+  /^\d{2}:\d{2}:\d{2}(\s?[AP]M)?$/.test(ny.clock.time),
+].join(' '); <span class="cmt">// true true</span>
+
+<span class="cmt">// The ignored `aggregation: 'sum'` never took effect:</span>
+<span class="kw">const</span> ignoredAgg = ny.aggregation; <span class="cmt">// clock</span>
+
+kpi.destroy();
+<span class="kw">return</span> [shapes, shaped, ignoredAgg].join(' | ');</code></pre>
     <h3 id="kpi-tree">The KPI tree: top-level items that expand to the indicators beneath them</h3>
     <p>Set <code>tree</code> and the panel becomes a <strong>rail</strong> instead of a grid of tiles: a small number of top-level items, each expanding to the indicators underneath it, with the parent telling you at a glance whether anything below needs attention. <code>Compute</code> expands to <code>psi</code> and <code>cpu</code>; collapsed, it still shows you that one of them is in breach.</p>
     <pre><code>const kpi = createKPI(document.querySelector('#rail'), {
@@ -6877,7 +7194,7 @@ grid.destroy();
 <span class="kw">return</span> `${by['risk.atRisk'].display} at risk | SPI ${by['risk.spi'].display} | ${by['risk.sla.breaches'].display} breaches`;</code></pre>
 
     <h2 id="tabs">The tabbed grid</h2>
-    <p><code>modules/tabs</code> is an opt-in top-of-grid tab strip where <strong>each tab is its own full, independently-configured grid instance</strong> &mdash; "configure each tab as per a normal grid" rather than one grid whose state is swapped. That is a deliberate rejection of the cheaper alternative: <code>grid.state.get()</code>/<code>.apply()</code> only repositions, hides, resizes and sorts <strong>existing</strong> columns by id (no field, type, editor or row data), so a state-swap only works when every tab shares one column schema and one source &mdash; strictly less than the ask. A tab may instead declare <code>from: '&lt;tabId&gt;'</code> plus a narrowing (<code>where</code>, <code>group</code>, <code>join</code>, &hellip;), and the module wires a <code>source: { mode: 'derived', from: &lt;the parent tab's live grid&gt;, &hellip; }</code> for it &mdash; the shipped derived-source mechanism, not a new config-inheritance one. <code>createGrid</code> is <strong>injected</strong> (the same pattern the React/Vue/Svelte adapters use), so the module imports no engine code regardless of how it is loaded — its own minified ESM build (<code>tabs.esm.min.js</code>) is ~65KB gzipped, the same size class as the KPI and framework-adapter modules (~61&ndash;66KB), rather than the ~700KB a module that inlines the whole engine (the web component, htmx) ships.</p>
+    <p><code>modules/tabs</code> is an opt-in top-of-grid tab strip where <strong>each tab is its own full, independently-configured grid instance</strong> &mdash; "configure each tab as per a normal grid" rather than one grid whose state is swapped. That is a deliberate rejection of the cheaper alternative: <code>grid.state.get()</code>/<code>.apply()</code> only repositions, hides, resizes and sorts <strong>existing</strong> columns by id (no field, type, editor or row data), so a state-swap only works when every tab shares one column schema and one source &mdash; strictly less than the ask. A tab may instead declare <code>from: '&lt;tabId&gt;'</code> plus a narrowing (<code>where</code>, <code>group</code>, <code>join</code>, &hellip;), and the module wires a <code>source: { mode: 'derived', from: &lt;the parent tab's live grid&gt;, &hellip; }</code> for it &mdash; the shipped derived-source mechanism, not a new config-inheritance one. <code>createGrid</code> is <strong>injected</strong> (the same pattern the React/Vue/Svelte adapters use), so the module imports no engine code regardless of how it is loaded — its own minified ESM build (<code>tabs.esm.min.js</code>) is about 12KB gzipped &mdash; the module and nothing else. A module bundle carries its own code plus a small shared runtime, not the engine: the framework adapters are 3&ndash;11KB, the KPI module about 50KB, while a module that inlines the whole engine (the web component, htmx) ships at roughly 760KB.</p>
     <pre><code>import { createGrid } from '@toclocoinc/lattice-grid';
 import { createTabs } from '@toclocoinc/lattice-grid/modules/tabs';
 
@@ -7019,7 +7336,7 @@ tabs.destroy();
 
     <h2 id="layout">The dashboard layout</h2>
     <p><code>modules/layout</code> is an opt-in <strong>reconfigurable dashboard surface</strong>: a cell grid inside an element, and a set of windows placed on it that a user can move, resize and close &mdash; by drag <em>or</em> by keyboard. It is the thing a customer would otherwise reach for GridStack or react-grid-layout to get, which means a second dependency, a second sizing model, and a seam where the viewers in it do not resize properly.</p>
-    <p><strong>It is payload-agnostic, and that is the whole design.</strong> A window body is a <code>div</code> with an <code>id</code>. The module creates it, sizes it, and never reads or writes its contents &mdash; it does not import <code>createGrid</code>, does not know what a payload is, and never calls into one. What it does instead is emit <code>window:resized</code> with the measured content box, which is the contract. That rule is what keeps its own code to <strong>12,890 bytes gzipped</strong> (measured: a 77,190-byte bundle over a 62,206-byte fixed floor, of which 2,094 bytes are the two shared module helpers) and what makes it usable for a payload we have not written yet.</p>
+    <p><strong>It is payload-agnostic, and that is the whole design.</strong> A window body is a <code>div</code> with an <code>id</code>. The module creates it, sizes it, and never reads or writes its contents &mdash; it does not import <code>createGrid</code>, does not know what a payload is, and never calls into one. What it does instead is emit <code>window:resized</code> with the measured content box, which is the contract. That rule is what keeps the whole module to <strong>about 17,500 bytes gzipped</strong> (measured on the built bundle: its own code over a shared module runtime of roughly 2KB) and what makes it usable for a payload we have not written yet.</p>
     <pre><code>import { createLayout } from '@toclocoinc/lattice-grid/modules/layout';
 
 const layout = createLayout(document.querySelector('#dash'), {
@@ -8685,6 +9002,7 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
           <tr><td class="name">text</td><td class="type">string</td><td class="desc">The label of a `text` mark. Required for `text`, ignored for other types. <small>(optional)</small></td></tr>
           <tr><td class="name">fontSize</td><td class="type">number</td><td class="desc">A `text` mark's font size in content pixels (before presentation scale). Defaults to 14. <small>(optional)</small></td></tr>
           <tr><td class="name">background</td><td class="type">string</td><td class="desc">An optional backing colour drawn behind a `text` mark's label. <small>(optional)</small></td></tr>
+          <tr><td class="name">region</td><td class="type">'start' | 'centre' | 'end'</td><td class="desc">Which columns the mark belongs to: a pinned region holds still while the grid scrolls sideways, the centre moves with it. Set from where a stroke began; omitted (the centre) for every mark that is not over a pinned column, so a mark saved before this existed reads unchanged. <small>(optional)</small></td></tr>
         </tbody>
       </table>
     </div>
@@ -8959,6 +9277,20 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
         </tbody>
       </table>
     </div>
+    <h3 id="type-ChartNode">ChartNode</h3>
+    <p class="section-note">One node of a `network` chart, as the host declares it. `x` and `y` are fractions of the plot, 0 to 1, measured from its top-left. A node giving both is **pinned** there and takes no part in the force simulation; the rest are laid out around it, deterministically. Giving only one of the two is not a position and the node is laid out.</p>
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Member</th><th>Type</th><th>Description</th></tr></thead>
+        <tbody>
+          <tr><td class="name">id</td><td class="type">string</td><td class="desc">Matches a value in the `source` or `target` column.</td></tr>
+          <tr><td class="name">label</td><td class="type">string</td><td class="desc">Drawn beneath the node. The id is used when this is absent. <small>(optional)</small></td></tr>
+          <tr><td class="name">icon</td><td class="type">string</td><td class="desc">A name in the grid's icon registry, drawn inside the node's disc. <small>(optional)</small></td></tr>
+          <tr><td class="name">x</td><td class="type">number</td><td class="desc">Where to pin it, as a fraction of the plot's width. <small>(optional)</small></td></tr>
+          <tr><td class="name">y</td><td class="type">number</td><td class="desc">Where to pin it, as a fraction of the plot's height. <small>(optional)</small></td></tr>
+        </tbody>
+      </table>
+    </div>
     <h3 id="type-ChartSpec">ChartSpec</h3>
     <p class="section-note">What a chart draws and how. `grid` and `container` are required; everything else describes the chart. A chart reads the grid's *filtered* rows, so it follows the grid without being told to.</p>
     <div class="table-wrap">
@@ -8997,6 +9329,9 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
           <tr><td class="name">diverging</td><td class="type">boolean</td><td class="desc">A diverging colour ramp, for heatmap and geomap. <small>(optional)</small></td></tr>
           <tr><td class="name">shapes</td><td class="type">unknown</td><td class="desc">Country outlines, for a geomap drawing countries rather than continents. Either GeoJSON, an object of code to SVG path data, or a geometry {@link GeoPack} imported from an optional `modules/geo-*` package (BACKLOG-0001321) — as the pack itself, or as `{ pack: id }` once its module has been imported and registered. <small>(optional)</small></td></tr>
           <tr><td class="name">codeProperty</td><td class="type">string</td><td class="desc"><small>(optional)</small></td></tr>
+          <tr><td class="name">lon</td><td class="type">string</td><td class="desc">The longitude column, for the types that place a row by where it is rather than by a code: `markermap`, `bubblemap` and `hexmap`. Degrees east, -180 to 180; a row outside that, or with no reading, is left off the map and counted. <small>(optional)</small></td></tr>
+          <tr><td class="name">lat</td><td class="type">string</td><td class="desc">The latitude column, beside {@link ChartSpec.lon}. Degrees north, -90 to 90, on the same terms. <small>(optional)</small></td></tr>
+          <tr><td class="name">value</td><td class="type">string</td><td class="desc">The measure a `markermap` writes beside each dot and colours it by. Its text is the column's own formatted cell text and its colour is whatever the column's conditional-formatting rules give that value, so a map and the table beside it say the same thing about the same number. <small>(optional)</small></td></tr>
           <tr><td class="name">layer</td><td class="type">string</td><td class="desc">Which layer of a multi-layer geometry pack to draw — the UK pack, for instance, ships `regions`, `local-authorities` and `constituencies` together (BACKLOG-0001321). Ignored for a single-layer pack. <small>(optional)</small></td></tr>
           <tr><td class="name">projection</td><td class="type">'equalEarth' | 'robinson' | 'mercator' | 'equirectangular' | 'albers'</td><td class="desc">The map projection a geomap draws through (BACKLOG-0001321): `'equalEarth'` (the default for a world), `'robinson'`, `'mercator'`, `'equirectangular'`, `'albers'`, `'transverseMercator'`, or a projection function of the caller's own `(lon: number, lat: number) =&gt; [number, number]`. Left unset, a geometry pack draws through the projection it declares. <small>(optional)</small></td></tr>
           <tr><td class="name">projectionOptions</td><td class="type">{ parallels?: [number, number]; centre?: [number, number] }</td><td class="desc">Parameters for the projections that take them: `parallels` and `centre` for `albers`, `centre` for `transverseMercator` (BACKLOG-0001321). <small>(optional)</small></td></tr>
@@ -9023,6 +9358,9 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
           <tr><td class="name">method</td><td class="type">'pearson' | 'spearman' | 'kendall'</td><td class="desc"><small>(optional)</small></td></tr>
           <tr><td class="name">values</td><td class="type">boolean</td><td class="desc"><small>(optional)</small></td></tr>
           <tr><td class="name">iterations</td><td class="type">number</td><td class="desc">Network layouts: how many relaxation passes to run. <small>(optional)</small></td></tr>
+          <tr><td class="name">nodes</td><td class="type">ChartNode[]</td><td class="desc">The nodes of a `network`, named by the host rather than inferred from the rows: an icon per device, a label, and a position the layout must honour. A node listed here that appears in no row is still drawn. A node in the rows that is not listed here takes the chart's `icon` default and its own id as its label. <small>(optional)</small></td></tr>
+          <tr><td class="name">icon</td><td class="type">string</td><td class="desc">The default glyph for a `network` node that names none of its own: any name in the grid's icon registry (see {@link Grid.icons}). Unset, a node with no icon is a plain disc. <small>(optional)</small></td></tr>
+          <tr><td class="name">linkWidth</td><td class="type">number</td><td class="desc">A `network` link's stroke width in pixels, fixed. Unset, width follows the link's value as a share of the heaviest link, as it always has. <small>(optional)</small></td></tr>
           <tr><td class="name">spec</td><td class="type">{ lower?: number; upper?: number; target?: number }</td><td class="desc">Control and capability charts: a tolerance overriding the column's own `spec`, how many leading readings fix the control limits, which rule set the violations are judged against, and the level for the capability interval. <small>(optional)</small></td></tr>
           <tr><td class="name">baseline</td><td class="type">number</td><td class="desc"><small>(optional)</small></td></tr>
           <tr><td class="name">rules</td><td class="type">'westernElectric' | 'nelson'</td><td class="desc"><small>(optional)</small></td></tr>
@@ -10840,6 +11178,7 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
           <tr><td class="name">setPinnedRows</td><td class="type">(rows: unknown[], opts?: { edge?: 'top' | 'bottom' }): void</td><td class="desc">Pin rows above or below the scrolling body. The rows render through the ordinary column pipeline but are not part of the data: not counted, sorted, filtered, grouped, selectable or exported. Pass a new array rather than mutating the one you passed before: array identity is how the grid knows the pinned rows have changed.</td></tr>
           <tr><td class="name">getPinnedRows</td><td class="type">(opts?: { edge?: 'top' | 'bottom' }): unknown[]</td><td class="desc">The objects currently pinned at one edge, as a copy.</td></tr>
           <tr><td class="name">form</td><td class="type">RowFormApi</td><td class="desc">The row form. Declines when `rowForm` is not configured. <small>(read-only)</small></td></tr>
+          <tr><td class="name">icons</td><td class="type">IconRegistryApi</td><td class="desc">The grid's icon registry, read-only. The same sprite set `registerIcon` writes to and every cell paints from, reachable from the grid instance so that code outside the grid bundle — an optional module drawing its own glyph, a network chart putting a `router` on a node — draws from the one registry rather than a second, empty copy of it. Register with `registerIcon` or `config.icons`, as before. <small>(read-only)</small></td></tr>
           <tr><td class="name">getVersion</td><td class="type">(): string</td><td class="desc">The library version.</td></tr>
           <tr><td class="name">destroy</td><td class="type">(): void</td><td class="desc">Release everything: listeners, timers, workers and the DOM the grid made.</td></tr>
         </tbody>
@@ -10865,6 +11204,7 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
           <tr><td class="name">pipes</td><td class="type">Record&lt;string, (value: unknown, ...args: string[]) =&gt; string&gt;</td><td class="desc">Named text transforms usable from a format mask or a template. <small>(optional)</small></td></tr>
           <tr><td class="name">totalFns</td><td class="type">Record&lt;string, TotalFn&gt;</td><td class="desc">Your own reductions, alongside the built-in ones. <small>(optional)</small></td></tr>
           <tr><td class="name">variants</td><td class="type">Record&lt;string, VariantDefinition&gt;</td><td class="desc">Named appearance variants a row or cell can be switched into by a rule. <small>(optional)</small></td></tr>
+          <tr><td class="name">icons</td><td class="type">Record&lt;string, IconDefinition&gt;</td><td class="desc">Your own SVG glyphs, registered by name before the first paint. The same registry `registerIcon` writes to and every cell, header control, rail button and chart glyph is painted from, so a name given here is usable anywhere a glyph name is: a column's `icon` decoration, a rail action's `icon`, a network node's `icon`. Registering a built-in name overrides it. Read the result back through {@link Grid.icons}. <small>(optional)</small></td></tr>
           <tr><td class="name">tree</td><td class="type">TreeConfig</td><td class="desc">Hierarchical rows: where the parent link or the path lives. <small>(optional)</small></td></tr>
           <tr><td class="name">detail</td><td class="type">DetailConfig</td><td class="desc">The expandable panel beneath a row. <small>(optional)</small></td></tr>
           <tr><td class="name">selection</td><td class="type">SelectionConfig | 'single' | 'multiple' | 'none'</td><td class="desc">What the user may select, and how selection behaves across groups. The `'none'` shorthand is `{ mode: 'none' }` and behaves identically: no row selection, and no cell ranges or fill handle either. <small>(optional)</small></td></tr>
@@ -10944,7 +11284,7 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
           <tr><td class="name">rowClass</td><td class="type">string | string[] | ((p: RowStyleParams) =&gt; string | string[])</td><td class="desc">A class, or classes, for every row. Re-evaluated on each repaint. <small>(optional)</small></td></tr>
           <tr><td class="name">rowStyle</td><td class="type">CellStyle | ((p: RowStyleParams) =&gt; CellStyle)</td><td class="desc">Inline styles for every row. Camel-case or hyphenated property names. <small>(optional)</small></td></tr>
           <tr><td class="name">toolPanel</td><td class="type">boolean | {</td><td class="desc"><small>(optional)</small></td></tr>
-          <tr><td class="name">groupPanel</td><td class="type">boolean | {</td><td class="desc">A drag-and-drop group-by strip above the column header — the pattern AG Grid calls the row-group panel. Drag a column heading into it to group by that column; the active groups show as removable, reorderable chips, and reordering the chips changes the nesting order. It is keyboard-operable (arrows navigate, Shift+arrow reorders, Delete ungroups, and an add control groups any column), and every change is announced through the live region, which is why it also addresses the drag-only complaint of BACKLOG-0000429. Off by default and non-breaking, matching `toolPanel`. It drives the same grouping model as `grid.columns.group()`; it reimplements nothing. <small>(optional)</small></td></tr>
+          <tr><td class="name">groupPanel</td><td class="type">boolean | {</td><td class="desc">A drag-and-drop group-by strip above the column header — the pattern AG Grid calls the row-group panel. Drag a column heading into it to group by that column; the active groups show as removable, reorderable chips, and reordering the chips changes the nesting order. It is keyboard-operable (arrows navigate, Shift+arrow reorders, Delete ungroups, and an add control groups any column), and every change is announced through the live region, which is why it also addresses the drag-only complaint (BACKLOG-0000429). Off by default and non-breaking, matching `toolPanel`. It drives the same grouping model as `grid.columns.group()`; it reimplements nothing. <small>(optional)</small></td></tr>
           <tr><td class="name">kpis</td><td class="type">Array&lt;Omit&lt;StatConfig, 'grid' | 'container'&gt;&gt;</td><td class="desc">A built-in KPI/stat strip: a labelled band of {@link createStat} tiles the grid places for you, above the column header. Each entry is a stat spec — the same fields {@link StatConfig} takes, minus `grid` and `container`, which the grid supplies — so a strip tile and a hand-placed one are the same object. The tiles follow the grid's filters, recomputing on every change exactly as a stand-alone stat does. Off by default and non-breaking, matching `groupPanel`: no `kpis` means no band and no cost. It reuses `createStat` and reimplements no compute. <small>(optional)</small></td></tr>
           <tr><td class="name">quickFilterText</td><td class="type">string</td><td class="desc">The quick filter's initial text. <small>(optional)</small></td></tr>
           <tr><td class="name">permissions</td><td class="type">PermissionPolicy</td><td class="desc">Per-column read/write/hidden policy. A usability control, not a security boundary: hidden data is still resident in the store. Enforce the same policy server-side with `permittedColumns` / `permittedExport`. <small>(optional)</small></td></tr>
@@ -11167,6 +11507,29 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
         </tbody>
       </table>
     </div>
+    <h3 id="type-IconGlyph">IconGlyph</h3>
+    <p class="section-note">One sprite: its view box, its path data, and how it is painted.</p>
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Member</th><th>Type</th><th>Description</th></tr></thead>
+        <tbody>
+          <tr><td class="name">viewBox</td><td class="type">string</td><td class="desc"></td></tr>
+          <tr><td class="name">paths</td><td class="type">string[]</td><td class="desc"></td></tr>
+          <tr><td class="name">paint</td><td class="type">'stroke' | 'fill'</td><td class="desc"></td></tr>
+        </tbody>
+      </table>
+    </div>
+    <h3 id="type-IconRegistryApi">IconRegistryApi</h3>
+    <p class="section-note">Read access to the grid's icon sprite set (see {@link Grid.icons}).</p>
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Member</th><th>Type</th><th>Description</th></tr></thead>
+        <tbody>
+          <tr><td class="name">get</td><td class="type">(name: string): IconGlyph | null</td><td class="desc">One glyph, as a copy, or null when the name is not registered.</td></tr>
+          <tr><td class="name">names</td><td class="type">(): string[]</td><td class="desc">Every registered name, in registration order.</td></tr>
+        </tbody>
+      </table>
+    </div>
     <h3 id="type-IconSetSpec">IconSetSpec</h3>
     <p class="section-note">An icon set (BACKLOG-0000955): a glyph placed beside the value by the band it falls in. Drawn as a `background-image` with padding, so it too needs no extra element and stays a plain style value. `set` names a built-in — `'arrows'`, `'trafficLights'` or `'ratings'` (see {@link ICON_SETS}) — or supply your own ordered `icons` (SVG documents, data URIs or `url(...)` values). Bands are split at `thresholds` (ascending, one fewer than the icons); without them the column's distribution is cut into equal-count bands. `reverse` flips the order so a high value can read as red.</p>
     <div class="table-wrap">
@@ -11633,6 +11996,22 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
         </tbody>
       </table>
     </div>
+    <h3 id="type-KPIClockTile">KPIClockTile</h3>
+    <p class="section-note">A clock tile: the device clock, not an aggregate (BACKLOG-0001640) — the date on one line and the time on the next, ticking once a second from one shared panel timer. It takes none of a stat tile's measurement options (`aggregation`, `field`, `format`, `thresholds`, `bands`, `target`, `baseline`, `sparkline`): supplying any of them is reported as a configuration warning by name and ignored, because a tile that measures nothing has nothing for them to apply to.</p>
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Member</th><th>Type</th><th>Description</th></tr></thead>
+        <tbody>
+          <tr><td class="name">kind</td><td class="type">'clock'</td><td class="desc">Discriminates a clock tile from an aggregate stat tile.</td></tr>
+          <tr><td class="name">id</td><td class="type">string</td><td class="desc">A stable identity for the tile (defaults to the label, then the index). <small>(optional)</small></td></tr>
+          <tr><td class="name">label</td><td class="type">string</td><td class="desc">The tile's accessible label (e.g. the city or zone it names). <small>(optional)</small></td></tr>
+          <tr><td class="name">timeZone</td><td class="type">string</td><td class="desc">Any IANA zone name (`'Europe/London'`). Omitted, the tile shows the viewer's local time. A name `Intl.DateTimeFormat` does not recognise is reported through the usual diagnostics warning and the tile falls back to local time rather than rendering nothing. <small>(optional)</small></td></tr>
+          <tr><td class="name">locale</td><td class="type">string</td><td class="desc">The locale the date and time are formatted in — the tile's own, else the panel's `KPIConfig.locale`, else the browser's default. A 24-hour clock or a 12-hour one with an AM/PM marker follows from the locale itself (`Intl.DateTimeFormat`'s own convention), never a separate option. <small>(optional)</small></td></tr>
+          <tr><td class="name">seconds</td><td class="type">boolean</td><td class="desc">Show the seconds on the time line. Default `true`. <small>(optional)</small></td></tr>
+          <tr><td class="name">date</td><td class="type">boolean</td><td class="desc">Show the date line at all. Default `true`. <small>(optional)</small></td></tr>
+        </tbody>
+      </table>
+    </div>
     <h3 id="type-KPIConfig">KPIConfig</h3>
     <p class="section-note">KPI panel configuration.</p>
     <div class="table-wrap">
@@ -11647,6 +12026,7 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
           <tr><td class="name">columns</td><td class="type">number</td><td class="desc"><small>(optional)</small></td></tr>
           <tr><td class="name">ariaLabel</td><td class="type">string</td><td class="desc"><small>(optional)</small></td></tr>
           <tr><td class="name">nullText</td><td class="type">string</td><td class="desc"><small>(optional)</small></td></tr>
+          <tr><td class="name">locale</td><td class="type">string</td><td class="desc">The default locale a clock tile formats in when the tile itself declares none (BACKLOG-0001640); falls back to the browser's default. No effect on a stat tile, which takes its own `format.locale`. <small>(optional)</small></td></tr>
           <tr><td class="name">tree</td><td class="type">KPITreeConfig | false</td><td class="desc">Arrange the tiles as a hierarchy; `false` keeps the panel flat. <small>(optional)</small></td></tr>
           <tr><td class="name">messages</td><td class="type">{ t(key: string, params?: Record&lt;string, unknown&gt;): string }</td><td class="desc">The catalogue the panel's own text is read from. A panel routinely has no grid to borrow one off — two of its three input modes have none — so this is the first-class way to translate it. A grid's own `messages` satisfies the shape; a key it does not carry falls back to English. <small>(optional)</small></td></tr>
           <tr><td class="name">onTileClick</td><td class="type">(event: KPIEvent) =&gt; void</td><td class="desc"><small>(optional)</small></td></tr>
@@ -11717,24 +12097,13 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
         </tbody>
       </table>
     </div>
-    <h3 id="type-KPIThresholds">KPIThresholds</h3>
-    <p class="section-note">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.</p>
-    <div class="table-wrap">
-      <table>
-        <thead><tr><th>Member</th><th>Type</th><th>Description</th></tr></thead>
-        <tbody>
-          <tr><td class="name">warn</td><td class="type">number</td><td class="desc"></td></tr>
-          <tr><td class="name">critical</td><td class="type">number</td><td class="desc"></td></tr>
-          <tr><td class="name">direction</td><td class="type">'higherIsBetter' | 'lowerIsBetter'</td><td class="desc"><small>(optional)</small></td></tr>
-        </tbody>
-      </table>
-    </div>
-    <h3 id="type-KPITile">KPITile</h3>
-    <p class="section-note">One tile: an aggregate over the routed rows, with optional filter, format, threshold and trend.</p>
+    <h3 id="type-KPIStatTile">KPIStatTile</h3>
+    <p class="section-note">An aggregate stat tile: the routed rows reduced to one number, with optional filter, format, threshold and trend.</p>
     <div class="table-wrap">
       <table>
         <thead><tr><th>Member</th><th>Type</th><th>Description</th></tr></thead>
         <tbody>
+          <tr><td class="name">kind</td><td class="type">'stat'</td><td class="desc">Absent, or `'stat'`: the default tile kind. <small>(optional)</small></td></tr>
           <tr><td class="name">id</td><td class="type">string</td><td class="desc">A stable identity for the tile (defaults to the label, then the index). <small>(optional)</small></td></tr>
           <tr><td class="name">label</td><td class="type">string</td><td class="desc">The tile's accessible label. <small>(optional)</small></td></tr>
           <tr><td class="name">aggregation</td><td class="type">KPIAggregation | ((rows: KPIRow[], tile: object) =&gt; unknown)</td><td class="desc">The aggregation kind, or a reducer `(rows, tile) =&gt; value` for a custom tile. <small>(optional)</small></td></tr>
@@ -11750,6 +12119,18 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
         </tbody>
       </table>
     </div>
+    <h3 id="type-KPIThresholds">KPIThresholds</h3>
+    <p class="section-note">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.</p>
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Member</th><th>Type</th><th>Description</th></tr></thead>
+        <tbody>
+          <tr><td class="name">warn</td><td class="type">number</td><td class="desc"></td></tr>
+          <tr><td class="name">critical</td><td class="type">number</td><td class="desc"></td></tr>
+          <tr><td class="name">direction</td><td class="type">'higherIsBetter' | 'lowerIsBetter'</td><td class="desc"><small>(optional)</small></td></tr>
+        </tbody>
+      </table>
+    </div>
     <h3 id="type-KPITileModel">KPITileModel</h3>
     <p class="section-note">A computed tile, as it appears in the model.</p>
     <div class="table-wrap">
@@ -11758,10 +12139,12 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
         <tbody>
           <tr><td class="name">id</td><td class="type">string</td><td class="desc"></td></tr>
           <tr><td class="name">label</td><td class="type">string</td><td class="desc"></td></tr>
+          <tr><td class="name">kind</td><td class="type">'stat' | 'clock'</td><td class="desc">`'stat'` for an aggregate tile, `'clock'` for a clock tile (BACKLOG-0001640).</td></tr>
           <tr><td class="name">aggregation</td><td class="type">string</td><td class="desc"></td></tr>
           <tr><td class="name">field</td><td class="type">string</td><td class="desc"><small>(optional)</small></td></tr>
-          <tr><td class="name">value</td><td class="type">unknown</td><td class="desc"></td></tr>
-          <tr><td class="name">formatted</td><td class="type">string</td><td class="desc"></td></tr>
+          <tr><td class="name">value</td><td class="type">unknown</td><td class="desc">For a clock tile, the read instant as epoch milliseconds.</td></tr>
+          <tr><td class="name">formatted</td><td class="type">string</td><td class="desc">For a clock tile, the date and time text joined by a space (the same text `clock.date` and `clock.time` carry separately).</td></tr>
+          <tr><td class="name">clock</td><td class="type">{ date: string | null; time: string }</td><td class="desc">Present only on a clock tile: the date and time lines rendered separately. `date` is `null` when the tile was given `date: false`. <small>(optional)</small></td></tr>
           <tr><td class="name">status</td><td class="type">'good' | 'warn' | 'critical' | 'unknown' | null</td><td class="desc">The tile's semantic band, or `unknown` when the tile measured nothing. `unknown` is decided from data presence before any threshold is consulted: an aggregation over nothing returns the identity of its operation (`sum` and `count` return 0), and 0 is a number a threshold grades, so without it an empty panel would report as a healthy one. Two things make a tile `unknown`: the panel holds no rows at all, or the tile's `field` names no column on the bound grid, so it never read a cell to reduce over. A tile whose `filter` matches none of the rows the panel *does* hold is neither — it has measured a real zero and is banded normally. `null` means the tile has no thresholds or bands configured.</td></tr>
           <tr><td class="name">target</td><td class="type">number</td><td class="desc"><small>(optional)</small></td></tr>
           <tr><td class="name">baseline</td><td class="type">number</td><td class="desc"><small>(optional)</small></td></tr>
@@ -13804,7 +14187,7 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
 <!-- END GENERATED TYPE REFERENCE -->
 
     <footer>
-      Lattice Grid 1.63.3 · Copyright © 2026 TOCLOCO Inc. All rights reserved.
+      Lattice Grid 1.65.0 · Copyright © 2026 TOCLOCO Inc. All rights reserved.
       This document describes the behaviour of the shipped library. Where this guide and the code
       disagree, the code wins: please <a href="https://www.latticegrid.dev">tell us</a>.
     </footer>