@toclocoinc/lattice-grid 1.63.3 → 1.64.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.63.3</p>
+    <p class="rail__sub">Developer guide · v1.64.0</p>
     <nav>
       <div class="rail__group">
         <span class="rail__label">Start here</span>
@@ -554,7 +554,7 @@
         <a href="API.html">reference tables</a> are the shorter version for when you already know.
       </p>
       <p class="chips">
-        <span class="chip">Version 1.63.3</span>
+        <span class="chip">Version 1.64.0</span>
           <span class="chip">Zero dependencies</span>
         <span class="chip">No build step</span>
       </p>
@@ -1369,7 +1369,7 @@ off();                                       <span class="cmt">// every subscrip
     </p>
     <div class="example">
       <p class="example__label">Which version am I running?</p>
-      <pre><code>grid.getVersion();          <span class="cmt">// '1.63.3'</span>
+      <pre><code>grid.getVersion();          <span class="cmt">// '1.64.0'</span>
 LatticeGrid.getVersion();   <span class="cmt">// the same, when you have no grid to hand</span></code></pre>
     </div>
     <p class="lead-in">
@@ -7896,6 +7896,81 @@ grid.diff.before('CIR-100042', 'capacity');</code></pre>
       highlight cannot serve both.
     </p>
 
+    <h3 id="network-map-guide">A network map: icon nodes, links coloured by their value</h3>
+    <p class="lead-in">
+      A <code>network</code> chart draws the rows as a graph &mdash; two columns name the endpoints
+      and a third carries the value on the link. Until 1.64 every node was a plain circle, every
+      edge the same grey, and the layout went wherever the simulation put it, so the picture a
+      network team actually draws &mdash; core on top, regions below, an icon per device, a colour
+      per circuit &mdash; could not be expressed. Three options change that, and every one of them
+      carries a fact that only the host has.
+    </p>
+    <div class="example">
+      <p class="example__label">One <code>nodes</code> list, one rule set, one chart config</p>
+      <pre><code>createGrid(el, {
+  columns: [{ field: 'from' }, { field: 'to' }, { field: 'load', type: 'number' }],
+  rows,                                  <span class="cmt">// one row per circuit</span>
+  selection: 'multiple',
+  <span class="cmt">// The rules live on the column. The cells and the links read the same ones.</span>
+  formatting: {
+    load: [
+      { label: 'Healthy',   when: { op: 'lt',  value: 40 }, style: { background: '#107c41' } },
+      { label: 'Busy',      when: { op: 'lt',  value: 80 }, style: { background: '#f0b400' } },
+      { label: 'Saturated', when: { op: 'gte', value: 80 }, style: { background: '#a4262c' } },
+    ],
+  },
+});
+
+createChart({
+  grid, container: '#topology', type: 'network',
+  source: 'from', target: 'to', y: { col: 'load', fn: 'sum' },
+  selection: true,
+  nodes: [
+    <span class="cmt">// x/y are fractions of the plot: both given pins the node there.</span>
+    { id: 'core-1', label: 'Core', icon: 'router', x: 0.3, y: 0.15 },
+    { id: 'core-2', label: 'Core', icon: 'router', x: 0.7, y: 0.15 },
+    { id: 'emea',   label: 'EMEA', icon: 'hub',    x: 0.2, y: 0.8 },
+    { id: 'amer',   label: 'AMER', icon: 'hub',    x: 0.5, y: 0.8 },
+    { id: 'apac',   label: 'APAC', icon: 'hub',    x: 0.8, y: 0.8 },
+  ],
+});</code></pre>
+    </div>
+    <div class="why">
+      <p><strong>The icons come from the grid, not from the chart.</strong> <code>icon</code> is a
+      name in the grid&rsquo;s own sprite registry &mdash; a built-in, or one you registered &mdash;
+      and the chart reads it through <code>grid.icons</code>, the grid it is bound to. That is
+      deliberate and it is the only route that works: the charts module ships as its own bundle, so
+      an <code>import</code> of the registry there would hand the chart a <em>second</em>, empty
+      copy, and a glyph you registered would be invisible to it. One registry, reached through the
+      one object both sides already share. Unknown names warn once and draw a plain disc rather
+      than nothing.</p>
+      <p><strong>Pinning steers the layout without replacing it.</strong> A node with both
+      <code>x</code> and <code>y</code> is a fixed body: it still pushes its neighbours apart and
+      still pulls on its links, and the integration step skips it. Everything unpinned settles
+      around it by the same deterministic relaxation as before &mdash; and pinning one node does
+      not reshuffle the others, because the layout&rsquo;s seeding draws for every node whether it
+      is pinned or not, precisely so that it cannot. Half a position is not a position: a node with
+      only <code>x</code> is laid out.</p>
+      <p><strong>Parallel links are not summed.</strong> Three rows between the same pair are three
+      lines, offset 4&nbsp;px apart, symmetric about the pair&rsquo;s own line, in row order. One
+      line carrying their total would be a number nothing measured &mdash; three circuits at 40% do
+      not make one at 120% &mdash; and the pointer picks out the line you are over rather than the
+      pair, so each one&rsquo;s own value is readable. Links are undirected: no arrowheads, and
+      <code>A,B</code> is the same pair as <code>B,A</code>.</p>
+      <p><strong>There is no chart-level threshold option, on purpose.</strong> The colour comes
+      from <code>grid.formatting.styleFor(col, value)</code> &mdash; <code>background</code>, then
+      <code>backgroundColor</code>, then <code>color</code>; a gradient is not a colour and is not
+      read. 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 only the rules that fired, with their own labels and
+      swatches, and changing a rule recolours the links on the next frame without the layout
+      re-running, so nothing moves.</p>
+      <p><strong>Clicking acts on rows, because a link is a row.</strong> 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&rsquo;s selection then lights those marks and dims the
+      rest. The types whose marks are <em>aggregates</em> are deliberately untouched: selecting the
+      forty rows behind a bar is not what a click on a bar means.</p>
+    </div>
+
     <h3 id="removed-rows">Showing what was deleted</h3>
     <div class="example">
       <p class="example__label">A deletion is a change too</p>
@@ -8078,7 +8153,7 @@ grid.import.apply(preview);</code></pre>
           <tr><td class="name">createKPI</td><td class="desc">A KPI / stat-tile view (module <code>kpi</code>) of a dataset as a panel of aggregate tiles — each tile a <code>sum</code>, <code>avg</code>, <code>min</code>, <code>max</code>, <code>count</code>, <code>countDistinct</code> or a <code>custom</code> reducer over the routed rows, with an optional <code>filter</code> predicate, number <code>format</code> (<code>number</code>/<code>currency</code>/<code>percent</code>/<code>compact</code>), a <code>baseline</code> for a delta, semantic threshold bands (<code>thresholds</code> with two cut points and a direction, or an explicit <code>bands</code> list, giving a <code>good</code>/<code>warn</code>/<code>critical</code> status kept separate from any accent), and an optional <code>sparkline</code> series. It is a dataset viewer like any other: it consumes data through the same keyed-diff <code>rows.apply({ add, update, remove })</code> contract a grid exposes, so a Data Router can <code>attach(value, kpi)</code> and drive a KPI panel beside a grid, a kanban and a chart off one feed. Updates are incremental — a delta adjusts each tile's running accumulator by only the rows it carries (an add contributes, a remove reverses, an update reverses-then-contributes), the two bounded exceptions being a <code>min</code>/<code>max</code> whose current extreme is removed (a rescan of that tile's own value multiset) and a <code>custom</code> reducer (recomputed over the filtered store, an arbitrary function having no inverse). Each tile is a labelled <code>&lt;figure&gt;</code>, focusable and keyboard-activatable, its value announced, the sparkline respecting <code>prefers-reduced-motion</code>; a <code>tile:click</code> event (also from the keyboard) lets a host drill down or filter a routed grid. Pass <code>null</code> as the element for a headless panel that computes the same tile model without a DOM. Not a dashboard layout engine (that is the parked dashboard generator) and no charting beyond the minimal sparkline (that is the charts module).</td></tr>
           <tr><td class="name">createAI</td><td class="desc">Create an AI narrative / insights controller (module <code>ai</code>) over a live grid. It produces a short, plain-language narrative of the grid's <em>computed</em> figures — a per-KPI / per-chart / per-column <code>explain</code>, or an <code>insights</code> panel over the current filtered view. The grid makes no AI call of its own: <code>createAI</code> imports no provider SDK, holds no key, and makes no network request; it calls one host callback, <code>ask({ system, messages, prompt, tools?, schema?, signal })</code> — your model, your key, your privacy decision — the same philosophy as the data adapters. Two grounding paths feed one guard: where the provider offers tool-use the model is given a curated read-only tool set (<code>getSchema</code>, <code>getProfile</code>, <code>getStatistics</code>, <code>getForecast</code>, <code>runQuery</code>) and the grid's own engine computes what it asks for; otherwise the module builds a facts packet from <code>grid.statistics</code>/the profile/forecasts/view counts and passes it in the prompt. Every figure in the narrative is reconciled against the values the engine produced this render — an ungrounded number is stripped before display (the number-reconciliation guard), so a hallucinated figure never reaches the user. The prompt is constrained to narrate-only; the layer is read-only and never mutates data. <code>redact</code> (a column id, a list, or a predicate) and <code>maxRows</code> bound what the module hands <code>ask()</code>, and the module sends nothing itself; an <code>ask()</code> error surfaces a friendly message and the grid stays fully usable, AI being additive rather than load-bearing. Complementary to <code>grid.ai</code> (the intent/plan skill layer): pass no <code>ask</code> and it adopts the grid's configured <code>ai.ask</code>, running the facts-packet path over it. Pass a headless grid for a DOM-free narrative; <code>facts(target)</code> returns the exact grounded packet without calling <code>ask()</code>. UMD global <code>LatticeGridAI</code>.</td></tr>
                     <tr><td class="name">createTabs</td><td class="desc">Create a tabbed grid (module <code>tabs</code>): a <code>role="tablist"</code> strip above a stack of <code>role="tabpanel"</code> regions, each hosting its own, independently-configured <code>createGrid</code> instance — "configure each tab as per a normal grid" rather than one grid whose state is swapped (<code>ColumnModel#applyState</code> only repositions/hides/resizes existing columns by id; it carries no field, type or row data, so a state-swap only works when every tab shares one schema). <code>createGrid</code> is injected (<code>createTabs(el, { createGrid, tabs })</code>), the same pattern the React/Vue/Svelte adapters use, so the module imports no engine code and adds nothing to a page that does not load it. A tab that names <code>from: '&lt;tabId&gt;'</code> gets a <code>source: { mode: 'derived', from: &lt;the parent tab’s live grid&gt;, where, group, join, … }</code> wired for it automatically — reusing the shipped derived-source mechanism rather than a new config-inheritance one — and activating a derived tab materialises its whole ancestor chain first; a cyclic <code>from</code> graph is refused (naming the exact cycle) when <code>createTabs</code> is called, not at first click. A tab’s grid mounts on first activation and then stays alive, hidden, so its scroll/selection/filters/sort/grouping/expansion — and an open cell/row editor, left exactly as it was, uncommitted and undiscarded — survive a switch natively; <code>destroy()</code> tears every mounted tab down. The strip is a real tablist with <code>aria-selected</code>, a roving <code>tabindex</code>, and manual-activation keyboard handling (arrows/Home/End move focus, Enter/Space or a click activates). Events: <code>tab:changed</code>, a cancellable <code>beforeTabChange</code> paired with <code>tabChange:cancelled</code>. UMD global <code>LatticeGridTabs</code>.</td></tr>
-          <tr><td class="name">createLayout</td><td class="desc">Create a reconfigurable dashboard layout (module <code>layout</code>): a cell grid inside an element, and a set of windows on it that a user can move, resize and close by drag <em>or</em> by keyboard &mdash; the surface a customer would otherwise reach for GridStack to get. It is <strong>payload-agnostic</strong>: a window body is a <code>div</code> with an <code>id</code> that the module creates, sizes and never reads, so it imports no engine code at all (not even <code>createGrid</code>) and its own code is 12,890 bytes gzipped, measured against a 62,206-byte fixed bundle floor. <code>columns</code>/<code>rows</code> divide the element; <code>overflowX</code> and <code>overflowY</code> are <em>independent</em> axes, each <code>'static'</code> (tracks divide the container with <code>minmax(0, 1fr)</code>) or <code>'scroll'</code> (tracks take a fixed <code>columnWidth</code>/<code>rowHeight</code> and the canvas extends past the viewport, so a column keeps the size it asked for &mdash; measured: shrinking a 600px host to 300px leaves a 200px column at 200px). Spacing takes a real CSS length: a number of pixels, or <code>'200px'</code>, <code>'25%'</code>, <code>'1fr'</code>, <code>'2rem'</code>; anything else is refused by name and replaced by the default, because the value reaches an inline style. Windows are placed by 1-based <code>xPos</code>/<code>yPos</code>/<code>xSize</code>/<code>ySize</code>, or auto-placed in the first free cell; <code>chrome</code> defaults on, and <code>closable</code>/<code>movable</code>/<code>resizable</code> all default <em>off</em>, so a fixed dashboard is fixed without opting out. <code>compact: 'vertical'</code> pushes displaced windows down then pulls them up (<code>window:moved</code> carries both <code>to</code> and <code>landed</code>); <code>'none'</code> keeps every window where it is put. <code>closable</code>/<code>movable</code>/<code>resizable</code> each also take a <em>layout-level</em> default of the same name, which a window's own boolean overrides, and <code>setInteractive(true|false|{movable, resizable, closable})</code> changes that default at runtime &mdash; the &ldquo;Edit layout&rdquo; button &mdash; without destroying the layout or any payload in it, with <code>getInteractive()</code> reading it back. Locking always wins and unlocking never overrides an opt-out: <code>setInteractive(false)</code> pins a window that declared <code>movable: true</code>, while <code>setInteractive(true)</code> leaves a window that declared <code>movable: false</code> pinned. The config key and the method are deliberately different: <code>movable: false</code> in the config states the <em>default</em> for windows that declare nothing and takes nothing away from one that opted in, whereas <code>setInteractive(false)</code> is an <em>active lock</em>. <code>getInteractive()</code> is three-valued &mdash; <code>undefined</code> for unset, <code>true</code>, or <code>false</code> for a lock &mdash; and a key carrying <code>undefined</code> is treated as absent, so <code>setInteractive(getInteractive())</code> is a no-op in every state. It moves both halves of the enforcement, the rendered handles <em>and</em> the pointer and keyboard gesture checks, and fires no event because a mode is not an arrangement &mdash; <code>getLayout()</code> neither carries it nor restores it. A locked layout is not a read-only dashboard: what is inside a window is configured with that payload's own settings. <code>maximise(id)</code>, <code>minimise(id)</code> and <code>restore(id)</code> are the display modes, with <code>maximised()</code> and <code>minimised()</code> reading them back: maximise fills the <em>layout host</em> rather than the browser window (no <code>position: fixed</code>, whose containing block is the nearest ancestor with a <code>transform</code> or a <code>contain</code>; no reparenting; nothing that can disturb the page around the dashboard), hides the other windows, runs <strong>no compaction at all</strong> and keeps the payload container as the very same DOM node &mdash; and <kbd>Escape</kbd> restores it from anywhere inside the layout. <code>minimise</code> draws a window as a single row and hides its payload while its chrome stays to carry the way back, so the windows below pull up on screen; in the arrangement nothing moves at all, because the collapse is a projection of the dashboard rather than a change to it, so restoring gives back exactly the arrangement that was there in <em>any</em> order and with any number of other windows still collapsed. A <code>chrome: false</code> window is refused by name. Both controls are opt-in per window (<code>maximisable</code>, <code>minimisable</code>) with a layout-level default of the same name, and <code>setInteractive()</code> deliberately does not touch either: a mode is not an arrangement, so neither appears in <code>getLayout()</code>, which reports the underlying placement in both states. Keyboard parity with the drag: a focusable handle per window running the kanban board's grab/move/drop/cancel model, with a polite live region announcing grabbed, every tentative position, dropped, cancelled and reverted. It owns exactly <strong>one</strong> <code>ResizeObserver</code> for the whole layout, over two targets, and tells payloads their new content box through <code>window:resized</code> &mdash; it never calls into a payload, because it cannot know what one is. Events: <code>window:moved</code>, <code>window:resized</code>, <code>window:closed</code>, <code>layout:changed</code>, the cancellable <code>beforeWindowMove</code>/<code>beforeWindowResize</code>/<code>beforeWindowClose</code> and their <code>*:cancelled</code> pairs; drag progress is not emitted per frame. <code>getLayout()</code>/<code>setLayout()</code> round-trip the arrangement as plain JSON, and <code>getState()</code>/<code>setState()</code> are the versioned pair. Closing a window does <strong>not</strong> destroy its payload &mdash; the container is handed back on <code>window:closed</code> and the host owns that lifecycle. UMD global <code>LatticeGridLayout</code>.</td></tr>
+          <tr><td class="name">createLayout</td><td class="desc">Create a reconfigurable dashboard layout (module <code>layout</code>): a cell grid inside an element, and a set of windows on it that a user can move, resize and close by drag <em>or</em> by keyboard &mdash; the surface a customer would otherwise reach for GridStack to get. It is <strong>payload-agnostic</strong>: a window body is a <code>div</code> with an <code>id</code> that the module creates, sizes and never reads, so it imports no engine code at all (not even <code>createGrid</code>) and the whole module is about 17,500 bytes gzipped on the built bundle, of which roughly 2KB is the shared module runtime. <code>columns</code>/<code>rows</code> divide the element; <code>overflowX</code> and <code>overflowY</code> are <em>independent</em> axes, each <code>'static'</code> (tracks divide the container with <code>minmax(0, 1fr)</code>) or <code>'scroll'</code> (tracks take a fixed <code>columnWidth</code>/<code>rowHeight</code> and the canvas extends past the viewport, so a column keeps the size it asked for &mdash; measured: shrinking a 600px host to 300px leaves a 200px column at 200px). Spacing takes a real CSS length: a number of pixels, or <code>'200px'</code>, <code>'25%'</code>, <code>'1fr'</code>, <code>'2rem'</code>; anything else is refused by name and replaced by the default, because the value reaches an inline style. Windows are placed by 1-based <code>xPos</code>/<code>yPos</code>/<code>xSize</code>/<code>ySize</code>, or auto-placed in the first free cell; <code>chrome</code> defaults on, and <code>closable</code>/<code>movable</code>/<code>resizable</code> all default <em>off</em>, so a fixed dashboard is fixed without opting out. <code>compact: 'vertical'</code> pushes displaced windows down then pulls them up (<code>window:moved</code> carries both <code>to</code> and <code>landed</code>); <code>'none'</code> keeps every window where it is put. <code>closable</code>/<code>movable</code>/<code>resizable</code> each also take a <em>layout-level</em> default of the same name, which a window's own boolean overrides, and <code>setInteractive(true|false|{movable, resizable, closable})</code> changes that default at runtime &mdash; the &ldquo;Edit layout&rdquo; button &mdash; without destroying the layout or any payload in it, with <code>getInteractive()</code> reading it back. Locking always wins and unlocking never overrides an opt-out: <code>setInteractive(false)</code> pins a window that declared <code>movable: true</code>, while <code>setInteractive(true)</code> leaves a window that declared <code>movable: false</code> pinned. The config key and the method are deliberately different: <code>movable: false</code> in the config states the <em>default</em> for windows that declare nothing and takes nothing away from one that opted in, whereas <code>setInteractive(false)</code> is an <em>active lock</em>. <code>getInteractive()</code> is three-valued &mdash; <code>undefined</code> for unset, <code>true</code>, or <code>false</code> for a lock &mdash; and a key carrying <code>undefined</code> is treated as absent, so <code>setInteractive(getInteractive())</code> is a no-op in every state. It moves both halves of the enforcement, the rendered handles <em>and</em> the pointer and keyboard gesture checks, and fires no event because a mode is not an arrangement &mdash; <code>getLayout()</code> neither carries it nor restores it. A locked layout is not a read-only dashboard: what is inside a window is configured with that payload's own settings. <code>maximise(id)</code>, <code>minimise(id)</code> and <code>restore(id)</code> are the display modes, with <code>maximised()</code> and <code>minimised()</code> reading them back: maximise fills the <em>layout host</em> rather than the browser window (no <code>position: fixed</code>, whose containing block is the nearest ancestor with a <code>transform</code> or a <code>contain</code>; no reparenting; nothing that can disturb the page around the dashboard), hides the other windows, runs <strong>no compaction at all</strong> and keeps the payload container as the very same DOM node &mdash; and <kbd>Escape</kbd> restores it from anywhere inside the layout. <code>minimise</code> draws a window as a single row and hides its payload while its chrome stays to carry the way back, so the windows below pull up on screen; in the arrangement nothing moves at all, because the collapse is a projection of the dashboard rather than a change to it, so restoring gives back exactly the arrangement that was there in <em>any</em> order and with any number of other windows still collapsed. A <code>chrome: false</code> window is refused by name. Both controls are opt-in per window (<code>maximisable</code>, <code>minimisable</code>) with a layout-level default of the same name, and <code>setInteractive()</code> deliberately does not touch either: a mode is not an arrangement, so neither appears in <code>getLayout()</code>, which reports the underlying placement in both states. Keyboard parity with the drag: a focusable handle per window running the kanban board's grab/move/drop/cancel model, with a polite live region announcing grabbed, every tentative position, dropped, cancelled and reverted. It owns exactly <strong>one</strong> <code>ResizeObserver</code> for the whole layout, over two targets, and tells payloads their new content box through <code>window:resized</code> &mdash; it never calls into a payload, because it cannot know what one is. Events: <code>window:moved</code>, <code>window:resized</code>, <code>window:closed</code>, <code>layout:changed</code>, the cancellable <code>beforeWindowMove</code>/<code>beforeWindowResize</code>/<code>beforeWindowClose</code> and their <code>*:cancelled</code> pairs; drag progress is not emitted per frame. <code>getLayout()</code>/<code>setLayout()</code> round-trip the arrangement as plain JSON, and <code>getState()</code>/<code>setState()</code> are the versioned pair. Closing a window does <strong>not</strong> destroy its payload &mdash; the container is handed back on <code>window:closed</code> and the host owns that lifecycle. UMD global <code>LatticeGridLayout</code>.</td></tr>
           <tr><td class="name">createDevtools</td><td class="desc">Mount the devtools panel against a grid, including its accessibility checks.</td></tr>
           <tr><td class="name">createGantt</td><td class="desc">Create a project-planning Gantt controller (module <code>gantt</code>) over a task list and a dependency list. A CPM engine (<code>computeSchedule</code>) computes each task's early/late start and finish, its slack and the zero-float critical path, honouring the four link types (<code>LINK_TYPES</code>: FS/SS/FF/SF) with lag, and recomputes on every edit — emitting <code>schedule</code> or, on a dependency cycle or bad input, <code>error</code> (a code from <code>SCHEDULE_ERROR</code>). Milestones are zero-duration points; summary (WBS) tasks are derived from their children (earliest start, latest finish, weighted progress) rather than scheduled; <code>findViolations</code> flags a task placed earlier than its predecessors allow, and <code>toISODate</code> maps an engine day-number back to a calendar date.</td></tr>
           <tr><td class="name">createLatticeGridElement</td><td class="desc">Build the element class without registering it, for a custom registry.</td></tr>
@@ -9408,7 +9483,7 @@ grid.licence.state();   <span class="cmt">// 'licensed' | 'localhost' | 'trial'<
 
     <footer>
       <p>
-        Lattice Grid 1.63.3 · Copyright © 2026 TOCLOCO Inc. All rights reserved.
+        Lattice Grid 1.64.0 · Copyright © 2026 TOCLOCO Inc. All rights reserved.
         Written against the shipped source. Where this guide and the code disagree, the code wins,
         please <a href="https://www.latticegrid.dev">tell us</a>.
       </p>

package/lattice-grid.d.ts

@@ -1,5 +1,5 @@
 /*!
- * Lattice Grid 1.63.3, type declarations
+ * Lattice Grid 1.64.0, type declarations
  * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
  * https://latticegrid.dev
  */
@@ -5167,6 +5167,21 @@ export interface ColumnsApi {
   totals(ids: string | string[]): void;
 }
 
+/** One sprite: its view box, its path data, and how it is painted. */
+export interface IconGlyph {
+  viewBox: string;
+  paths: string[];
+  paint: 'stroke' | 'fill';
+}
+
+/** Read access to the grid's icon sprite set (see {@link Grid.icons}). */
+export interface IconRegistryApi {
+  /** One glyph, as a copy, or null when the name is not registered. */
+  get(name: string): IconGlyph | null;
+  /** Every registered name, in registration order. */
+  names(): string[];
+}
+
 export interface RowFormApi {
   /** Open the form for a row. False when the form is not configured. */
   open(key: string): boolean;
@@ -5642,6 +5657,13 @@ export interface AnnotationMark {
   fontSize?: number;
   /** An optional backing colour drawn behind a `text` mark's label. */
   background?: string;
+  /**
+   * 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.
+   */
+  region?: 'start' | 'centre' | 'end';
 }
 
 export interface AnnotationApi {
@@ -6619,6 +6641,17 @@ export interface Grid {
   /** The row form. Declines when `rowForm` is not configured. */
   readonly form: RowFormApi;
 
+  /**
+   * 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.
+   */
+  readonly icons: IconRegistryApi;
+
   /** The library version. */
   getVersion(): string;
   /** Release everything: listeners, timers, workers and the DOM the grid made. */
@@ -7815,6 +7848,25 @@ export interface ChartSpec {
    */
   shapes?: unknown;
   codeProperty?: string;
+  /**
+   * 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.
+   */
+  lon?: string;
+  /**
+   * The latitude column, beside {@link ChartSpec.lon}. Degrees north, -90 to
+   * 90, on the same terms.
+   */
+  lat?: string;
+  /**
+   * 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.
+   */
+  value?: string;
   /**
    * Which layer of a multi-layer geometry pack to draw — the UK pack, for
    * instance, ships `regions`, `local-authorities` and `constituencies`
@@ -7882,6 +7934,25 @@ export interface ChartSpec {
   values?: boolean;
   /** Network layouts: how many relaxation passes to run. */
   iterations?: number;
+  /**
+   * 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.
+   */
+  nodes?: ChartNode[];
+  /**
+   * 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.
+   */
+  icon?: string;
+  /**
+   * 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.
+   */
+  linkWidth?: number;
 
   /**
    * Control and capability charts: a tolerance overriding the column's own
@@ -7895,6 +7966,27 @@ export interface ChartSpec {
   confidence?: number;
 }
 
+/**
+ * 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.
+ */
+export interface ChartNode {
+  /** Matches a value in the `source` or `target` column. */
+  id: string;
+  /** Drawn beneath the node. The id is used when this is absent. */
+  label?: string;
+  /** A name in the grid's icon registry, drawn inside the node's disc. */
+  icon?: string;
+  /** Where to pin it, as a fraction of the plot's width. */
+  x?: number;
+  /** Where to pin it, as a fraction of the plot's height. */
+  y?: number;
+}
+
 /**
  * The events a chart raises.
  *