@ashley-shrok/viewmodel-shell 3.11.0 → 4.1.0

package/agent-skill.md

@@ -135,10 +135,39 @@ The wire does not mandate an auth shape. If the app needs credentials, the app p
 
 If a response carries `nextPollIn: N`, schedule a POST `{ "name": "poll", "state": <last state> }` against the same `actionEndpoint` after `N` milliseconds. The server may continue returning `nextPollIn` until the workflow reaches a terminal state, at which point the field will be absent. Polls run silently — they are not user-initiated.
 
+## Non-blocking actions (`blocking:false`)
+
+Some node action descriptors in the `vm` tree (a `CheckboxNode.action`, `ButtonNode.action`, a `TableRow.action`, etc.) may carry `"blocking": false` alongside the action's `name`. This is a CLIENT-SIDE scheduling hint for the browser `ViewModelShell` instance: it selects a non-blocking dispatch lane that coexists with an in-flight blocking action instead of queuing behind it, and coalesces rapid repeated triggers of the same action to "latest wins."
+
+It never appears in the `_action` POST payload you send. The request body shape stays `{"name": "<action-name>"}` (JSON form) or `{"name":"<action-name>"}` (multipart `_action` field) regardless of whether the descriptor you read it from said `blocking:true` (the default, typically omitted) or `blocking:false`.
+
+**For you (a wire-driving agent with no client-side dispatch loop): `blocking` is INFORMATIONAL ONLY. Dispatch the action exactly the same way regardless of its value** — POST `_action`/`_state` (or the JSON form) as normal and read the response per the existing rules in this manual (`ok`, `rejected`, `errors[]`). You do not need to implement coalescing, an epoch, or any dispatch-lane concept to drive the wire correctly.
+
+This connects to the polling section above: the `{"name": "poll"}` dispatch this manual already documents is itself an instance of a non-blocking action — a poll always rides the non-blocking lane client-side — so nothing about how you send a poll dispatch changes either.
+
 ## Files
 
 File uploads use the multipart form above. One form entry per file input, keyed by the input's `name` attribute (from the corresponding node's `name` field in the tree). The file's binary content is the entry's value. JSON-body dispatch cannot carry files; use multipart.
 
+**A file rides only the action(s) its input declares.** Each file `FieldNode` carries an `uploadOn` array of action names. Send a file's binary entry **only** when the action you are dispatching (`_action.name`) is listed in that file input's `uploadOn`; if you dispatch any other action, do **not** include the file. A file input with no `uploadOn` (absent or empty) rides **nothing** — its binary is never sent. This mirrors the browser, where the same declaration decides which click sends the file: an agent should not attach a file to an action a human's click could not have sent it with. (There is no positional/implicit rule — the file's own `uploadOn` is the whole contract.)
+
+## Chart data (`type:"chart"`)
+
+A `ChartNode` in the `vm` tree carries bounded, agent-legible declared data — it is read-only structured data like any other node, with no dispatch-bearing fields of its own:
+
+```json
+{ "type": "chart", "kind": "bar", "title": "Weekly visits",
+  "points": [ { "label": "Mon", "value": 12 }, { "label": "Tue", "value": 19 } ],
+  "tone": "info" }
+```
+
+- `kind` — optional. Omitted means `"bar"`, the only value in `viewmodel-shell/1.0`.
+- `points` — an array of self-contained `{label, value}` pairs. No parallel-array index alignment is needed (unlike some other frameworks' chart data shapes) — read each point directly.
+- `title` — optional chart title.
+- `tone` — optional (`danger|warning|success|info`). This only affects rendered COLOR in a browser client. A wire-driving agent with no renderer can simply read `points`/`title` directly and ignore `tone`.
+
+There is nothing else to do to "drive" a chart over the wire.
+
 ## Versioning
 
 This manual applies to protocol token `viewmodel-shell/1.0` — the value of the `protocol` field on the discoverability meta tag. The protocol token tracks the wire shape, NOT the package version: a 1.5.x or 1.6.x package release may still carry protocol `viewmodel-shell/1.0` because the wire has not undergone a breaking change. A future major-version bump (`viewmodel-shell/2.0`) signals a breaking change and invalidates this manual; expect a new skill at the same `/.well-known/vms-skill.md` URL.

package/dist/browser.d.ts

@@ -7,6 +7,9 @@ export declare class BrowserAdapter implements Adapter {
     private detailsOpenSnapshot;
     private sectionKeyCounter;
     private fitsObservers;
+    private chartInstances;
+    private chartKeyCounter;
+    private chartKeysSeen;
     constructor(container: HTMLElement);
     render(vm: ViewNode, onAction: (action: ActionEvent) => void, stateAccess?: StateAccess): void;
     navigate(url: string): void;
@@ -68,6 +71,41 @@ export declare class BrowserAdapter implements Adapter {
      * preservation covers server-driven re-renders, not this resize-switch path.
      */
     private fits;
+    /**
+     * ChartNode (CHART-01/02/03/04) — a single-series BAR chart drawn by Chart.js,
+     * loaded as a PRIVATE, LAZY, OPTIONAL adapter dependency: the dynamic
+     * `import("chart.js")` in loadChart() is reached ONLY when a ChartNode renders,
+     * and it registers ONLY the bar pieces so the bundle tree-shakes (an app that
+     * renders no chart loads zero chart.js bytes; the core + .NET/bun backends gain
+     * no dependency). tone→theme-token color (CHART-02) is read via getComputedStyle
+     * — NO raw CSS crosses the wire.
+     *
+     * The canvas + Chart instance are keyed by a stable per-render ordinal and kept
+     * in `chartInstances` ACROSS renders, so a re-render with changed data reuses
+     * the SAME canvas (detached, not destroyed, by render()'s innerHTML wipe — its
+     * 2D context + bitmap survive) and redraws IN PLACE via `.update()` (CHART-03)
+     * rather than reconstructing. render() mark-sweeps + destroy()s any instance the
+     * new tree dropped (leak prevention). getComputedStyle / canvas / Chart.js live
+     * ONLY here in browser.ts — the core (index.ts) stays platform-agnostic.
+     */
+    private chart;
+    /**
+     * Lazily import chart.js and construct the Chart for `key`. The dynamic import
+     * is what keeps chart.js zero-bytes-when-absent; registering ONLY the bar
+     * controller/elements/scales/tooltip is what keeps CHART-04 small (tree-shaken).
+     * Fire-and-forget from chart() (`void this.loadChart(...)`), so a missing
+     * dependency is surfaced through the fail-loud seam (chartFailLoud), NEVER a
+     * floating unhandled rejection.
+     */
+    private loadChart;
+    /**
+     * Fail-loud for a missing chart.js — routed through the SAME sanctioned seam as
+     * the other no-safe-default capabilities (AGENTS.md fail-loud rule). The
+     * BrowserAdapter holds no ShellOptions.onError reference, so it uses the
+     * AGENTS.md-sanctioned fallback (console.error). NEVER a silent no-op, NEVER a
+     * floating unhandled rejection — deterministic + spy-able in tests.
+     */
+    private chartFailLoud;
     private section;
     private list;
     private listItem;

package/dist/browser.js

@@ -68,6 +68,24 @@ export class BrowserAdapter {
     // never leak when the tree is rebuilt — the same per-render reset idiom as
     // detailsOpenSnapshot / sectionKeyCounter above.
     fitsObservers = [];
+    // Phase 12 (CHART-01/03) — live Chart.js instances keyed by a stable per-render
+    // ordinal chart key. DELIBERATELY PERSISTENT across renders (NOT reset like the
+    // per-render fields below): the canvas + Chart instance must SURVIVE render()'s
+    // innerHTML wipe so a re-render with changed data redraws IN PLACE via
+    // .update() instead of re-constructing. `chart` is `any` (the module is
+    // dynamically imported, so there's no compile-time Chart type dependency);
+    // `latest` stashes the newest config while an async load is in flight so a fast
+    // second render still applies once the import resolves. Instances are
+    // mark-swept (destroy()'d + deleted) in render() when the new tree drops them.
+    chartInstances = new Map();
+    // Per-render disambiguator for chart keys (title-derived or anonymous). Reset
+    // at the TOP of every render() (like sectionKeyCounter) so snapshot keys and
+    // rebuild keys compute identically across a render pass.
+    chartKeyCounter = new Map();
+    // Per-render set of every chart key rendered this pass. Reset at the TOP of
+    // every render(); render() mark-sweeps any chartInstances key NOT in this set
+    // (a ChartNode removed from the new tree → its Chart instance is destroyed).
+    chartKeysSeen = new Set();
     constructor(container) {
         this.container = container;
     }
@@ -123,8 +141,25 @@ export class BrowserAdapter {
         // Same per-render reset model as the focus/scroll/details snapshots above.
         this.fitsObservers.forEach(o => o.disconnect());
         this.fitsObservers = [];
+        // Phase 12 (CHART-01/03) — reset the per-render chart bookkeeping (NOT
+        // chartInstances, which is deliberately persistent). Same per-render reset
+        // model as sectionKeyCounter: keys must compute identically across the
+        // rebuild + the post-rebuild mark-sweep below.
+        this.chartKeyCounter = new Map();
+        this.chartKeysSeen = new Set();
         this.container.innerHTML = "";
         this.node(vm, this.container, onAction);
+        // Phase 12 (CHART-03) — mark-sweep: destroy + drop any Chart instance whose
+        // key was NOT rendered this pass (a ChartNode removed from the new tree), so
+        // instances never leak across a long session. Swept POST-rebuild (unlike the
+        // fits pre-wipe disconnect) because a persisting chart's canvas must survive
+        // the innerHTML wipe to be reused for an in-place .update().
+        for (const [key, entry] of this.chartInstances) {
+            if (!this.chartKeysSeen.has(key)) {
+                entry.chart?.destroy();
+                this.chartInstances.delete(key);
+            }
+        }
         if (focusId) {
             const el = this.container.querySelector(`#${CSS.escape(focusId)}`);
             if (el) {
@@ -324,6 +359,7 @@ export class BrowserAdapter {
             case "fits": return this.fits(n, parent, on);
             case "empty-state": return this.emptyState(n, parent, on);
             case "badge": return this.badge(n, parent);
+            case "chart": return this.chart(n, parent);
             default: {
                 // Fail loud, not silent (AGENTS.md: "Nothing important fails quietly").
                 // Runtime trees are server-controlled JSON, so an unknown/forward-version
@@ -444,6 +480,140 @@ export class BrowserAdapter {
         ro.observe(container);
         this.fitsObservers.push(ro);
     }
+    /**
+     * ChartNode (CHART-01/02/03/04) — a single-series BAR chart drawn by Chart.js,
+     * loaded as a PRIVATE, LAZY, OPTIONAL adapter dependency: the dynamic
+     * `import("chart.js")` in loadChart() is reached ONLY when a ChartNode renders,
+     * and it registers ONLY the bar pieces so the bundle tree-shakes (an app that
+     * renders no chart loads zero chart.js bytes; the core + .NET/bun backends gain
+     * no dependency). tone→theme-token color (CHART-02) is read via getComputedStyle
+     * — NO raw CSS crosses the wire.
+     *
+     * The canvas + Chart instance are keyed by a stable per-render ordinal and kept
+     * in `chartInstances` ACROSS renders, so a re-render with changed data reuses
+     * the SAME canvas (detached, not destroyed, by render()'s innerHTML wipe — its
+     * 2D context + bitmap survive) and redraws IN PLACE via `.update()` (CHART-03)
+     * rather than reconstructing. render() mark-sweeps + destroy()s any instance the
+     * new tree dropped (leak prevention). getComputedStyle / canvas / Chart.js live
+     * ONLY here in browser.ts — the core (index.ts) stays platform-agnostic.
+     */
+    chart(n, parent) {
+        // Stable key: title-derived base disambiguated by a per-render ordinal so
+        // multiple/anonymous charts get distinct keys that compute identically across
+        // renders (mirrors the collapsible-section key disambiguation).
+        const baseKey = n.title ?? "vms-chart-anon";
+        const ordinal = this.chartKeyCounter.get(baseKey) ?? 0;
+        this.chartKeyCounter.set(baseKey, ordinal + 1);
+        const key = `${baseKey}#${ordinal}`;
+        this.chartKeysSeen.add(key);
+        const wrapper = document.createElement("div");
+        wrapper.className = "vms-chart";
+        parent.appendChild(wrapper);
+        // tone → theme token, NOT `--vms-${tone}`: `danger` maps to `--vms-error`
+        // (matching .vms-section--danger); omitted → the neutral `--vms-accent`.
+        const toneToken = {
+            danger: "--vms-error",
+            warning: "--vms-warning",
+            success: "--vms-success",
+            info: "--vms-info",
+        };
+        const cs = getComputedStyle(this.container);
+        const token = (n.tone && toneToken[n.tone]) || "--vms-accent";
+        const color = cs.getPropertyValue(token).trim();
+        // Grid/tick/axis colors track the theme so the chart reads consistently in
+        // light AND dark. Chart.js's default grid is a FIXED faint-black
+        // (rgba(0,0,0,0.1)) — visible on a light background but ~invisible on a dark
+        // one — so wire the grid + axis border to `--vms-border` (subtle in every
+        // theme) and the tick labels to `--vms-text-muted`.
+        const gridColor = cs.getPropertyValue("--vms-border").trim();
+        const tickColor = cs.getPropertyValue("--vms-text-muted").trim();
+        const scaleOpts = {
+            grid: { color: gridColor },
+            border: { color: gridColor },
+            ticks: { color: tickColor },
+        };
+        const config = {
+            type: "bar",
+            data: {
+                labels: n.points.map(p => p.label),
+                datasets: [{
+                        data: n.points.map(p => p.value),
+                        backgroundColor: color,
+                        borderColor: color,
+                    }],
+            },
+            options: {
+                responsive: true,
+                maintainAspectRatio: false,
+                scales: { x: scaleOpts, y: scaleOpts },
+                plugins: {
+                    title: n.title ? { display: true, text: n.title } : { display: false },
+                    legend: { display: false }, // single series — no legend
+                },
+            },
+        };
+        const existing = this.chartInstances.get(key);
+        if (existing) {
+            // Reuse the SAME canvas element (detached by the innerHTML wipe, not
+            // destroyed) — its 2D context + drawn bitmap survive.
+            wrapper.appendChild(existing.canvas);
+            if (existing.chart) {
+                // Redraw in place (CHART-03).
+                existing.chart.data = config.data;
+                existing.chart.options = config.options;
+                existing.chart.update();
+            }
+            else {
+                // Still loading — stash the newest config to apply when the import resolves.
+                existing.latest = config;
+            }
+            return;
+        }
+        // First render of this key: create a fresh canvas + kick the lazy loader
+        // (do NOT await inside the synchronous render()).
+        const canvas = document.createElement("canvas");
+        wrapper.appendChild(canvas);
+        this.chartInstances.set(key, { canvas, chart: null, latest: config });
+        void this.loadChart(key, config);
+    }
+    /**
+     * Lazily import chart.js and construct the Chart for `key`. The dynamic import
+     * is what keeps chart.js zero-bytes-when-absent; registering ONLY the bar
+     * controller/elements/scales/tooltip is what keeps CHART-04 small (tree-shaken).
+     * Fire-and-forget from chart() (`void this.loadChart(...)`), so a missing
+     * dependency is surfaced through the fail-loud seam (chartFailLoud), NEVER a
+     * floating unhandled rejection.
+     */
+    async loadChart(key, config) {
+        let mod;
+        try {
+            mod = await import("chart.js");
+        }
+        catch {
+            this.chartFailLoud("ChartNode present but the optional peer dependency 'chart.js' is not " +
+                "installed. Run: npm install chart.js");
+            return;
+        }
+        const { Chart, BarController, BarElement, CategoryScale, LinearScale, Tooltip } = mod;
+        // Tree-shaken registration — ONLY the bar pieces.
+        Chart.register(BarController, BarElement, CategoryScale, LinearScale, Tooltip);
+        const entry = this.chartInstances.get(key);
+        // A later render may have mark-swept this key before the import resolved.
+        if (!entry)
+            return;
+        entry.chart = new Chart(entry.canvas, entry.latest ?? config);
+        entry.latest = null;
+    }
+    /**
+     * Fail-loud for a missing chart.js — routed through the SAME sanctioned seam as
+     * the other no-safe-default capabilities (AGENTS.md fail-loud rule). The
+     * BrowserAdapter holds no ShellOptions.onError reference, so it uses the
+     * AGENTS.md-sanctioned fallback (console.error). NEVER a silent no-op, NEVER a
+     * floating unhandled rejection — deterministic + spy-able in tests.
+     */
+    chartFailLoud(msg) {
+        console.error("[ViewModelShell]", new Error(msg));
+    }
     section(n, parent, on) {
         // 1.2.0 — collapsible:true branch emits native <details>/<summary>; the
         // open/closed state is DOM-local and preserved across re-renders by the
@@ -541,7 +711,7 @@ export class BrowserAdapter {
         // TableRow.action (1.1.0). Containment via stopPropagation on nested
         // interactive controls AFTER kids() has rendered them.
         if (n.action) {
-            const actionName = n.action.name;
+            const action = n.action;
             el.tabIndex = 0;
             el.setAttribute("role", "button");
             // aria-label derivation: heading > flattened descendant text (capped) > "Card".
@@ -558,14 +728,14 @@ export class BrowserAdapter {
                 ariaLabel = text.length > 0 ? text.slice(0, 200) : "Card";
             }
             el.setAttribute("aria-label", ariaLabel);
-            el.addEventListener("click", () => { on({ name: actionName }); });
+            el.addEventListener("click", () => { on(action); });
             el.addEventListener("keydown", (e) => {
                 if (e.key === "Enter") {
-                    on({ name: actionName });
+                    on(action);
                 }
                 else if (e.key === " " || e.key === "Spacebar") {
                     e.preventDefault(); // suppress page scroll
-                    on({ name: actionName });
+                    on(action);
                 }
             });
             // Containment: clicks on nested interactive controls must NOT bubble to
@@ -601,11 +771,26 @@ export class BrowserAdapter {
         const form = document.createElement("form");
         form.className = `vms-form${n.layout && n.layout !== "stack" ? ` vms-form--${n.layout}` : ""}`;
         form.noValidate = true;
-        this.kids(n.children, form, on);
+        // File collection is by DECLARED intent, not button position: a file input
+        // rides an action iff that action's name is listed in the input's `uploadOn`
+        // (carried here via the data-vms-upload-on attribute set in field()). EVERY
+        // trigger inside the form — submit, buttons[], a ButtonNode or
+        // FieldNode.action nested in children — routes through this one path, so
+        // where a trigger sits is irrelevant; the file's own uploadOn decides. An
+        // input with no uploadOn rides nothing (there is no positional fallback).
         const dispatchWithFiles = (action) => {
             const files = {};
             form.querySelectorAll("input[type=file]").forEach(inp => {
-                if (inp.name && inp.files?.[0])
+                if (!inp.name || !inp.files?.[0])
+                    return;
+                let uploadOn = [];
+                try {
+                    uploadOn = JSON.parse(inp.dataset.vmsUploadOn ?? "[]");
+                }
+                catch {
+                    uploadOn = [];
+                }
+                if (uploadOn.includes(action.name))
                     files[inp.name] = inp.files[0];
             });
             const ev = { name: action.name };
@@ -613,6 +798,10 @@ export class BrowserAdapter {
                 ev.files = files;
             on(ev);
         };
+        // Children dispatch through the file-aware path too — so a ButtonNode (or a
+        // FieldNode.action Enter) nested anywhere in the form carries files per the
+        // uploadOn contract, identical to a footer buttons[] trigger.
+        this.kids(n.children, form, dispatchWithFiles);
         // #22 — submitButton takes precedence: the form renders the consumer's own
         // button (its label + emphasis/tone/size/width) as the submit and fires its
         // action; submitLabel/submitAction for the implicit button are then ignored.
@@ -799,7 +988,7 @@ export class BrowserAdapter {
                     this.writeBind(n.bind, sel.value);
                 }
                 if (n.action)
-                    on({ name: n.action.name });
+                    on(n.action);
             });
             wrapper.appendChild(sel);
         }
@@ -809,6 +998,10 @@ export class BrowserAdapter {
             inp.className = "vms-field__input";
             inp.id = `vms-${n.name}`;
             inp.name = n.name;
+            // Carry the declared upload routing to dispatch time — form()'s
+            // dispatchWithFiles reads this and attaches the file only to an action
+            // named here. Absent/empty => the file rides no action.
+            inp.dataset.vmsUploadOn = JSON.stringify(n.uploadOn ?? []);
             // File-input persistence: re-apply any registered file to the new node.
             const existingFile = this.fileRegistry.get(n.name);
             if (existingFile) {
@@ -823,6 +1016,13 @@ export class BrowserAdapter {
                 const file = inp.files?.[0];
                 if (file) {
                     this.fileRegistry.set(n.name, file);
+                    // [vms:orphan-file] — a picked file that declares no uploadOn action
+                    // will never be sent (the binary rides an action, and this input
+                    // names none). Silent under-attach is the dangerous failure, so warn.
+                    if (!n.uploadOn || n.uploadOn.length === 0) {
+                        this.warnOnce("orphan-file:" + n.name, "[vms:orphan-file] file field '" + n.name + "' has a picked file but no uploadOn action — " +
+                            "its binary will not be sent; add uploadOn:[\"<action>\"] naming the action that should carry it.");
+                    }
                     // [vms:type-mismatch] — OBSERVABLE-SUBSET diagnostic. The client is
                     // untyped JS: it CANNOT know a state slot's *declared* server type, so
                     // it only catches the observable case where a file object overwrites a
@@ -919,7 +1119,7 @@ export class BrowserAdapter {
                         // dispatching, in case the browser hasn't fired `input` yet
                         // (e.g. an autofill that lands then submits).
                         this.writeBind(n.bind, inp.value);
-                        on({ name: action.name });
+                        on(action);
                     }
                 });
             }
@@ -1008,7 +1208,7 @@ export class BrowserAdapter {
         inp.addEventListener("change", () => {
             this.sa.write(n.bind, inp.checked);
             if (n.action)
-                on({ name: n.action.name });
+                on(n.action);
         });
         parent.appendChild(lbl);
     }
@@ -1105,7 +1305,7 @@ export class BrowserAdapter {
             btn.setAttribute("aria-selected", String(tab.value === n.selected));
             btn.addEventListener("click", () => {
                 this.sa.write(n.bind, tab.value);
-                on({ name: tab.action.name });
+                on(tab.action);
             });
             nav.appendChild(btn);
         });
@@ -1239,7 +1439,7 @@ export class BrowserAdapter {
                     const cur = this.sa.read(sortBind);
                     const nextDir = cur?.column === col.key && cur?.direction === "asc" ? "desc" : "asc";
                     this.sa.write(sortBind, { column: col.key, direction: nextDir });
-                    on({ name: sortAction.name });
+                    on(sortAction);
                 });
             }
             headerRow.appendChild(th);
@@ -1279,7 +1479,7 @@ export class BrowserAdapter {
                         if (e.key === "Enter") {
                             if (bindPath != null)
                                 this.sa.write(bindPath, inp.value);
-                            on({ name: filterAction.name });
+                            on(filterAction);
                         }
                     });
                     th.appendChild(inp);
@@ -1305,7 +1505,7 @@ export class BrowserAdapter {
             // row.action — click-anywhere + keyboard + ARIA. Per-row controls and
             // cell linkLabel anchors stopPropagation below so they don't double-fire.
             if (row.action) {
-                const rowActionName = row.action.name;
+                const rowAction = row.action;
                 tr.tabIndex = 0;
                 tr.setAttribute("role", "button");
                 const labelParts = Object.values(row.cells)
@@ -1316,14 +1516,14 @@ export class BrowserAdapter {
                     : (row.id ? `Row ${row.id}` : "");
                 if (ariaLabel)
                     tr.setAttribute("aria-label", ariaLabel);
-                tr.addEventListener("click", () => { on({ name: rowActionName }); });
+                tr.addEventListener("click", () => { on(rowAction); });
                 tr.addEventListener("keydown", (e) => {
                     if (e.key === "Enter") {
-                        on({ name: rowActionName });
+                        on(rowAction);
                     }
                     else if (e.key === " " || e.key === "Spacebar") {
                         e.preventDefault(); // suppress page scroll
-                        on({ name: rowActionName });
+                        on(rowAction);
                     }
                 });
             }
@@ -1406,7 +1606,7 @@ export class BrowserAdapter {
                     b.addEventListener("click", () => {
                         if (paginationBind != null)
                             this.sa.write(paginationBind, targetPage);
-                        on({ name: action.name });
+                        on(action);
                     });
                 }
                 return b;

package/dist/index.d.ts

@@ -1,6 +1,21 @@
 export interface ActionEvent {
     name: string;
     files?: Record<string, File>;
+    /**
+     * Phase 14 (NBA-01..04) — optional dispatch-scheduling hint, read PURELY
+     * client-side to pick a dispatch lane. Omitted = `true`, the framework's
+     * pre-Phase-14 behavior: byte-identical for every existing app. `false` =
+     * a non-blocking round trip that coexists with a blocking dispatch instead
+     * of contending for the client's single dispatch mutex (see
+     * `.planning/design/non-blocking-actions.md`).
+     *
+     * This field never rides inside the `_action` POST payload — the wire shape
+     * stays `{name}` only (the Phase 6 shape). `blocking` travels on the SAME
+     * ActionEvent object already embedded on a triggering node's
+     * `action`/`dismissAction`/`sortActions[...]`/`filterAction`/`prevAction`/
+     * `nextAction`/tab `action` field; the server never needs to see it.
+     */
+    blocking?: boolean;
 }
 export interface StateAccess {
     read(path: string): unknown;
@@ -88,7 +103,7 @@ export interface Adapter {
      *  concept). */
     reload?(): void;
 }
-export type ViewNode = PageNode | SectionNode | ListNode | ListItemNode | FormNode | FieldNode | CheckboxNode | ButtonNode | TextNode | LinkNode | ImageNode | StatBarNode | TabsNode | ProgressNode | ModalNode | TableNode | CopyButtonNode | DividerNode | FitsNode | EmptyStateNode | BadgeNode;
+export type ViewNode = PageNode | SectionNode | ListNode | ListItemNode | FormNode | FieldNode | CheckboxNode | ButtonNode | TextNode | LinkNode | ImageNode | StatBarNode | TabsNode | ProgressNode | ModalNode | TableNode | CopyButtonNode | DividerNode | FitsNode | EmptyStateNode | BadgeNode | ChartNode;
 export interface PageNode {
     type: "page";
     title?: string;
@@ -255,7 +270,10 @@ export interface FormNode {
      *  `bind` path and travel with the dispatch's `_state` payload. Mirrors
      *  HTML's multiple submit buttons / `formaction` — different action per
      *  button, same underlying state. A plain ButtonNode placed in `children`
-     *  has identical dispatch semantics; the buttons[] slot is a layout hint. */
+     *  has identical dispatch semantics: both flow through the same file-aware
+     *  dispatch, so file collection is governed by each file input's `uploadOn`
+     *  (below), NOT by whether the trigger sits in `buttons[]` or `children`. The
+     *  buttons[] slot is purely a layout hint. */
     buttons?: ButtonNode[];
     /** Opt-in: bare Enter inside a descendant <textarea> dispatches submitAction
      *  (chat-composer "Enter sends, Shift/Ctrl/Meta/Alt+Enter = newline"). No-op
@@ -320,6 +338,15 @@ export interface FieldNode {
     /** Dispatched when Enter is pressed (text-like inputs only). Carries an
      *  action name only — the current value is already in state at the bind path. */
     action?: ActionEvent;
+    /** FILE INPUTS ONLY. The action name(s) whose dispatch carries this file's
+     *  binary over the multipart wire. A file rides an action iff that action's
+     *  name is listed here — declared on the *file*, so which trigger sends it no
+     *  longer depends on where a button sits (the trigger can live anywhere in the
+     *  form; footer `buttons[]`, `children`, submit, and Enter all honor this
+     *  equally). An absent or empty `uploadOn` means the file rides **nothing**
+     *  (there is no positional fallback); the browser warns `[vms:orphan-file]`
+     *  when a file is picked with no `uploadOn`. Ignored on non-file inputs. */
+    uploadOn?: string[];
 }
 export interface CheckboxNode {
     type: "checkbox";
@@ -622,6 +649,31 @@ export interface FitsNode {
      *  guaranteed-fits fallback rendered when none fit. */
     children: ViewNode[];
 }
+export interface ChartPoint {
+    /** Category label (x-axis tick). */
+    label: string;
+    /** Numeric magnitude (bar height). */
+    value: number;
+}
+export interface ChartNode {
+    type: "chart";
+    /** Chart type. CLOSED union; OMITTED = "bar". "bar" is the only value in v4.1;
+     *  `line` is an ADDITIVE future value (CHART-LINE), NOT a new node — so
+     *  consumers/agents key off `kind`, and a later milestone widens the union
+     *  without a wire break. The renderer treats an absent `kind` as "bar". */
+    kind?: "bar";
+    /** Ordered category→value data. Each point is a SELF-CONTAINED {label, value}
+     *  pair (mirroring StatItem) so an agent reads the series DIRECTLY with no
+     *  parallel-array index alignment. Bars render in array order. */
+    points: ChartPoint[];
+    /** Optional chart title rendered above the plot. */
+    title?: string;
+    /** Optional appearance tone from the existing tone axis, mapped to the theme's
+     *  --vms-* tone tokens (danger→--vms-error, warning→--vms-warning,
+     *  success→--vms-success, info→--vms-info; omitted → --vms-accent). NO raw
+     *  color/CSS crosses the wire (D3) — only the closed tone token. */
+    tone?: "danger" | "warning" | "success" | "info";
+}
 export interface ShellOptions {
     endpoint: string;
     actionEndpoint: string;
@@ -638,7 +690,10 @@ export interface ShellOptions {
     onUploadProgress?: (sent: number, total: number) => void;
     /** When set, the shell dispatches a "poll" action at this interval (ms) after every load/dispatch.
      *  The server can override the next interval via ShellResponse.nextPollIn, or stop polling by
-     *  omitting nextPollIn when no pollInterval is configured. */
+     *  omitting nextPollIn when no pollInterval is configured. NBA-05 (Phase 15): every poll dispatch
+     *  rides the non-blocking lane (see `schedulePoll`'s doc comment) — a blocking user action fired
+     *  while a poll round trip is in flight is never dropped or delayed by it. See
+     *  `.planning/design/non-blocking-actions.md`. */
     pollInterval?: number;
     /** 3.8.0 — the id of the client bundle this shell instance is running (the app
      *  injects it at build time, e.g. from a Vite `define`/env — VMS never derives
@@ -755,13 +810,78 @@ export declare class ViewModelShell {
     private options;
     private currentVm;
     private currentState;
-    private dispatching;
+    /** Guards ONLY the blocking lane — renamed 1:1 from `dispatching`. Today's
+     *  rapid-click-during-a-round-trip protection, byte-identical. */
+    private blockingInFlight;
+    /** Guards the non-blocking lane so at most one non-blocking round trip is
+     *  ever in flight at once. */
+    private nonBlockingInFlight;
+    /** NBA-02 coalescing slot. Holds the LATEST non-blocking dispatch requested
+     *  while one is already in flight; each subsequent trigger OVERWRITES it
+     *  (never appended/queued — "latest wins"), so at most one extra round
+     *  trip fires once the in-flight one resolves. Stores the pending trigger's
+     *  OWN `silent` classification alongside its action (CR-01 fix, Phase 14
+     *  gap closure) — the refire must replay with the classification the
+     *  coalesced trigger was ORIGINALLY dispatched with, never with whichever
+     *  invocation happens to resolve first and run the refire. Without this, a
+     *  bare `poll` action (silent=true, no `blocking` field of its own)
+     *  coalescing behind an in-flight `blocking:false` action would refire
+     *  through the resolving action's `silent=false`, misrouting the poll into
+     *  the blocking lane. See `.planning/design/non-blocking-actions.md`. */
+    private pendingNonBlockingRefire;
+    /** Monotonic counter incremented once per ACTUAL network dispatch attempt,
+     *  shared across both lanes, assigned at the moment the request is fired
+     *  (not at trigger/coalesce time) so it reflects real fire order. */
+    private dispatchSeq;
+    /** The highest dispatchSeq whose response has been applied (rendered) so
+     *  far. NBA-03: a NON-BLOCKING response is applied only when its seq >=
+     *  appliedSeq; a lower seq means a strictly newer dispatch already applied
+     *  and this response is stale — discard it rather than clobber the newer
+     *  render. A BLOCKING response is authoritative and always applies
+     *  unconditionally (CR-02 fix, Phase 14 gap closure): `blockingInFlight`
+     *  guarantees at most one blocking dispatch is ever in flight, so a
+     *  blocking response can never be superseded by another blocking one —
+     *  gating it against a faster-resolving, later-fired NON-blocking response
+     *  would silently discard the user's own action with no signal. Always
+     *  advanced via `Math.max` (never lowered) regardless of which lane
+     *  applied. See `.planning/design/non-blocking-actions.md` — "Epoch".
+     *
+     *  NBA-06 (Phase 15): the non-blocking apply gate ALSO discards a response
+     *  whenever `pendingNonBlockingRefire !== null` at apply time, even if its
+     *  own seq is not stale by the `seq >= appliedSeq` test above. This closes
+     *  the rapid-double-toggle gap: toggle A fires, toggle B (the user's very
+     *  next click on the same control) coalesces into `pendingNonBlockingRefire`
+     *  while A is still in flight; A's response is the ONLY one outstanding, so
+     *  it is never stale by seq alone — but it necessarily echoes state as of
+     *  A's own send time, predating B's local write. Applying it would revert
+     *  B's not-yet-sent value AND poison the refire (which reads `currentState`
+     *  fresh at its own fire time). Discarding A here is safe because the
+     *  queued refire (B) is guaranteed to fire immediately next, in the same
+     *  `finally` block, and will itself advance `appliedSeq` when it applies.
+     *  See `.planning/design/non-blocking-actions.md` — "Coalescing". */
+    private appliedSeq;
     private pollTimer;
     private serverBusy;
     private userDispatching;
     constructor(options: ShellOptions);
     private syncBusy;
     load(params?: Record<string, string>): Promise<void>;
+    /**
+     * The actual network round trip for a single dispatch: builds the
+     * multipart body, fires the request, parses/validates the response, and
+     * applies it per the lane-aware epoch rule (Phase 14 / NBA-03, refined by
+     * the CR-02 gap closure — see the `appliedSeq` field doc). Never throws to
+     * its caller — every error path is swallowed here exactly as it was in
+     * pre-Phase-14 `dispatch()`, so lane call sites need only a bare
+     * `try { await this.performRoundTrip(action, nonBlocking); } finally { ... }`
+     * with no `catch` of their own.
+     *
+     * @param nonBlocking whether THIS dispatch is on the non-blocking lane
+     *   (silent=true or action.blocking===false). Determines whether the
+     *   response is subject to the staleness-discard (non-blocking) or always
+     *   applies unconditionally (blocking — see the `appliedSeq` field doc).
+     */
+    private performRoundTrip;
     dispatch(action: ActionEvent, silent?: boolean): Promise<void>;
     /** Feed a pre-parsed ShellResponse into the shell — for SSE/WebSocket integrations. */
     push(response: ShellResponse): void;
@@ -809,6 +929,18 @@ export declare class ViewModelShell {
      * the two ids match.
      */
     private checkVersionSkew;
+    /**
+     * NBA-05 (Phase 15): the timer-driven poll dispatch below always calls
+     * `this.dispatch({ name: "poll" }, true)` — passing `silent = true` — so
+     * `nonBlocking = silent || action.blocking === false` in `dispatch()` is
+     * ALWAYS `true` for a poll, regardless of any `blocking` field on the
+     * action itself. This means poll ALWAYS rides the non-blocking lane and
+     * never contends with `blockingInFlight`: `ShellOptions.pollInterval` is
+     * sugar over the same non-blocking dispatch path a `blocking: false`
+     * action uses, not a separate mechanism. See
+     * `.planning/design/non-blocking-actions.md` — "Wire / API surface" (the
+     * "`pollInterval` becomes sugar over the same non-blocking path" line).
+     */
     private schedulePoll;
     /**
      * Authenticated download: fetch the URL with getRequestHeaders() merged

package/dist/index.js

@@ -63,7 +63,60 @@ export class ViewModelShell {
     options;
     currentVm = null;
     currentState = null;
-    dispatching = false;
+    // Phase 14 (NBA-01..03) — the single `dispatching` mutex is replaced by two
+    // independent in-flight lanes so a non-blocking (silent/blocking:false)
+    // round trip coexists with a blocking one instead of contending for one
+    // shared slot. See `.planning/design/non-blocking-actions.md`.
+    /** Guards ONLY the blocking lane — renamed 1:1 from `dispatching`. Today's
+     *  rapid-click-during-a-round-trip protection, byte-identical. */
+    blockingInFlight = false;
+    /** Guards the non-blocking lane so at most one non-blocking round trip is
+     *  ever in flight at once. */
+    nonBlockingInFlight = false;
+    /** NBA-02 coalescing slot. Holds the LATEST non-blocking dispatch requested
+     *  while one is already in flight; each subsequent trigger OVERWRITES it
+     *  (never appended/queued — "latest wins"), so at most one extra round
+     *  trip fires once the in-flight one resolves. Stores the pending trigger's
+     *  OWN `silent` classification alongside its action (CR-01 fix, Phase 14
+     *  gap closure) — the refire must replay with the classification the
+     *  coalesced trigger was ORIGINALLY dispatched with, never with whichever
+     *  invocation happens to resolve first and run the refire. Without this, a
+     *  bare `poll` action (silent=true, no `blocking` field of its own)
+     *  coalescing behind an in-flight `blocking:false` action would refire
+     *  through the resolving action's `silent=false`, misrouting the poll into
+     *  the blocking lane. See `.planning/design/non-blocking-actions.md`. */
+    pendingNonBlockingRefire = null;
+    /** Monotonic counter incremented once per ACTUAL network dispatch attempt,
+     *  shared across both lanes, assigned at the moment the request is fired
+     *  (not at trigger/coalesce time) so it reflects real fire order. */
+    dispatchSeq = 0;
+    /** The highest dispatchSeq whose response has been applied (rendered) so
+     *  far. NBA-03: a NON-BLOCKING response is applied only when its seq >=
+     *  appliedSeq; a lower seq means a strictly newer dispatch already applied
+     *  and this response is stale — discard it rather than clobber the newer
+     *  render. A BLOCKING response is authoritative and always applies
+     *  unconditionally (CR-02 fix, Phase 14 gap closure): `blockingInFlight`
+     *  guarantees at most one blocking dispatch is ever in flight, so a
+     *  blocking response can never be superseded by another blocking one —
+     *  gating it against a faster-resolving, later-fired NON-blocking response
+     *  would silently discard the user's own action with no signal. Always
+     *  advanced via `Math.max` (never lowered) regardless of which lane
+     *  applied. See `.planning/design/non-blocking-actions.md` — "Epoch".
+     *
+     *  NBA-06 (Phase 15): the non-blocking apply gate ALSO discards a response
+     *  whenever `pendingNonBlockingRefire !== null` at apply time, even if its
+     *  own seq is not stale by the `seq >= appliedSeq` test above. This closes
+     *  the rapid-double-toggle gap: toggle A fires, toggle B (the user's very
+     *  next click on the same control) coalesces into `pendingNonBlockingRefire`
+     *  while A is still in flight; A's response is the ONLY one outstanding, so
+     *  it is never stale by seq alone — but it necessarily echoes state as of
+     *  A's own send time, predating B's local write. Applying it would revert
+     *  B's not-yet-sent value AND poison the refire (which reads `currentState`
+     *  fresh at its own fire time). Discarding A here is safe because the
+     *  queued refire (B) is guaranteed to fire immediately next, in the same
+     *  `finally` block, and will itself advance `appliedSeq` when it applies.
+     *  See `.planning/design/non-blocking-actions.md` — "Coalescing". */
+    appliedSeq = 0;
     pollTimer = null;
     // 0.16.0 — busy = serverBusy OR a user-initiated dispatch is in flight.
     // Polls (silent=true dispatches) don't flip userDispatching so they never
@@ -128,32 +181,27 @@ export class ViewModelShell {
             onLoading?.(false);
         }
     }
-    async dispatch(action, silent = false) {
-        // 0.16.0 — drop user-initiated dispatches while server-busy. Polls (silent)
-        // bypass so the server can clear the busy state.
-        if (!silent && this.serverBusy)
-            return;
-        if (this.dispatching)
-            return;
-        const { actionEndpoint, onError, onLoading } = this.options;
-        if (this.currentState === null) {
-            const err = new Error(`Cannot dispatch '${action.name}' before initial load completes. ` +
-                `Call shell.load() and wait for it before allowing user interaction.`);
-            onError ? onError(err) : console.error("[ViewModelShell]", err);
-            return;
-        }
+    /**
+     * The actual network round trip for a single dispatch: builds the
+     * multipart body, fires the request, parses/validates the response, and
+     * applies it per the lane-aware epoch rule (Phase 14 / NBA-03, refined by
+     * the CR-02 gap closure — see the `appliedSeq` field doc). Never throws to
+     * its caller — every error path is swallowed here exactly as it was in
+     * pre-Phase-14 `dispatch()`, so lane call sites need only a bare
+     * `try { await this.performRoundTrip(action, nonBlocking); } finally { ... }`
+     * with no `catch` of their own.
+     *
+     * @param nonBlocking whether THIS dispatch is on the non-blocking lane
+     *   (silent=true or action.blocking===false). Determines whether the
+     *   response is subject to the staleness-discard (non-blocking) or always
+     *   applies unconditionally (blocking — see the `appliedSeq` field doc).
+     */
+    async performRoundTrip(action, nonBlocking) {
+        // Phase 14 (NBA-03) — assigned at the moment the request actually fires
+        // (not at trigger/coalesce time) so it reflects real fire order.
+        const seq = ++this.dispatchSeq;
+        const { actionEndpoint, onError } = this.options;
         try {
-            this.dispatching = true;
-            if (!silent) {
-                // 0.16.0 — flag a user dispatch as in-flight + apply .vms-busy. This
-                // is what kills the "rapid clicks during a round-trip silently flip the
-                // checkbox" UX bug: by the time the user's second click arrives, the
-                // container has pointer-events: none and the click never reaches the
-                // input.
-                this.userDispatching = true;
-                this.syncBusy();
-                onLoading?.(true);
-            }
             const form = new FormData();
             // Phase 6 — wire-shape break: `_action` carries the action name only.
             // The state at the input's bind path holds whatever value the previous
@@ -207,7 +255,37 @@ export class ViewModelShell {
                 // vm/state on an ok:false response. Type-erosion-safe.
                 throw new VmsActionError(body.errors ?? [{ message: `Action '${action.name}' failed: ${res.status}` }], res.status);
             }
-            this.processResponse(body);
+            // Phase 14 (NBA-03, refined by the CR-02 gap closure) — lane-aware
+            // epoch gate. Purely client-side; no wire field (see
+            // .planning/design/non-blocking-actions.md — "Epoch").
+            if (nonBlocking) {
+                // Non-blocking (background) response: apply only if no strictly-newer
+                // dispatch (of either lane) has already been applied — this is the
+                // staleness-discard NBA-03 exists for. Phase 15 (NBA-06) ALSO
+                // discards when a coalesced re-fire is already queued
+                // (`pendingNonBlockingRefire !== null`) at the moment this response
+                // is ready to apply: a strictly newer round trip — carrying the
+                // user's latest local writes — is guaranteed to fire immediately
+                // after (in this same dispatch's `finally` block) and supersede it,
+                // so applying THIS response first would only clobber those
+                // not-yet-sent writes with a stale echo. See the `pendingNonBlockingRefire`
+                // field doc and .planning/design/non-blocking-actions.md — "Coalescing".
+                if (seq >= this.appliedSeq && this.pendingNonBlockingRefire === null) {
+                    this.appliedSeq = Math.max(this.appliedSeq, seq);
+                    this.processResponse(body);
+                }
+            }
+            else {
+                // Blocking (user) response: authoritative — ALWAYS applies. At most
+                // one blocking dispatch is ever in flight (blockingInFlight guards
+                // it), so it can never be superseded by another blocking response;
+                // gating it against a faster non-blocking response would silently
+                // discard the user's own action. appliedSeq still advances (via max,
+                // never lowered) so a later-arriving stale non-blocking response is
+                // correctly discarded against this newer high-water mark.
+                this.appliedSeq = Math.max(this.appliedSeq, seq);
+                this.processResponse(body);
+            }
         }
         catch (err) {
             const error = err instanceof Error ? err : new Error(String(err));
@@ -233,18 +311,91 @@ export class ViewModelShell {
                 this.options.adapter.render(this.currentVm, (a) => this.dispatch(a), this.stateAccessForAdapter());
             }
         }
-        finally {
-            this.dispatching = false;
-            if (!silent) {
+    }
+    async dispatch(action, silent = false) {
+        // Phase 14 (NBA-01) — unifies the existing poll-only `silent` flag with
+        // the new `blocking:false` field under one "non-blocking lane" concept
+        // (design doc: "Poll = a non-blocking action on a timer").
+        const nonBlocking = silent || action.blocking === false;
+        if (!nonBlocking) {
+            // ─── Blocking lane — byte-identical guard order/behavior to the
+            // pre-Phase-14 single `dispatching` mutex, renamed to `blockingInFlight`. ───
+            // 0.16.0 — drop user-initiated dispatches while server-busy.
+            if (this.serverBusy)
+                return;
+            if (this.blockingInFlight)
+                return;
+            if (this.currentState === null) {
+                const err = new Error(`Cannot dispatch '${action.name}' before initial load completes. ` +
+                    `Call shell.load() and wait for it before allowing user interaction.`);
+                const { onError } = this.options;
+                onError ? onError(err) : console.error("[ViewModelShell]", err);
+                return;
+            }
+            // 0.16.0 — flag a user dispatch as in-flight + apply .vms-busy. This
+            // is what kills the "rapid clicks during a round-trip silently flip the
+            // checkbox" UX bug: by the time the user's second click arrives, the
+            // container has pointer-events: none and the click never reaches the
+            // input.
+            this.blockingInFlight = true;
+            this.userDispatching = true;
+            this.syncBusy();
+            this.options.onLoading?.(true);
+            try {
+                await this.performRoundTrip(action, false);
+            }
+            finally {
+                this.blockingInFlight = false;
                 this.userDispatching = false;
                 this.syncBusy();
-                onLoading?.(false);
+                this.options.onLoading?.(false);
             }
+            return;
+        }
+        // ─── Non-blocking lane — covers BOTH silent===true (poll) and
+        // action.blocking===false (NBA-01). Deliberately does NOT set
+        // userDispatching / call onLoading / toggle .vms-busy — that is what
+        // "does not trip the busy-lock" means; only the blocking lane does.
+        if (this.nonBlockingInFlight) {
+            // NBA-02 — coalesce; do NOT fire a second concurrent request. Overwrite
+            // (never append/queue) so at most one extra round trip fires once the
+            // in-flight one resolves, carrying the LATEST trigger. CR-01 fix: store
+            // this trigger's OWN `silent` alongside its action — see the field doc
+            // on `pendingNonBlockingRefire`.
+            this.pendingNonBlockingRefire = { action, silent };
+            return;
+        }
+        // Mirrors the blocking lane's pre-load guard, identical error message.
+        if (this.currentState === null) {
+            const err = new Error(`Cannot dispatch '${action.name}' before initial load completes. ` +
+                `Call shell.load() and wait for it before allowing user interaction.`);
+            const { onError } = this.options;
+            onError ? onError(err) : console.error("[ViewModelShell]", err);
+            return;
+        }
+        this.nonBlockingInFlight = true;
+        try {
+            await this.performRoundTrip(action, true);
+        }
+        finally {
+            this.nonBlockingInFlight = false;
+            const refire = this.pendingNonBlockingRefire;
+            this.pendingNonBlockingRefire = null;
+            // CR-01 fix — the coalesced re-fire recurses into dispatch() with the
+            // PENDING TRIGGER'S OWN `silent` classification (stored alongside its
+            // action in the slot), never with the value THIS (resolving)
+            // invocation happened to be entered with. A poll's coalesced refire
+            // always stays silent regardless of what resolved first; a
+            // blocking:false action's coalesced refire always re-enters the
+            // non-blocking branch via its own action.blocking===false. See the
+            // field doc on `pendingNonBlockingRefire`.
+            if (refire)
+                void this.dispatch(refire.action, refire.silent);
         }
     }
     /** Feed a pre-parsed ShellResponse into the shell — for SSE/WebSocket integrations. */
     push(response) {
-        if (this.dispatching)
+        if (this.blockingInFlight || this.nonBlockingInFlight)
             return;
         // 1.0.0 — parse-then-branch for push. External push consumers (SSE, WebSocket)
         // may feed ok:false responses (e.g. a server-pushed error notification). Route
@@ -403,6 +554,18 @@ export class ViewModelShell {
             this.options.onError ? this.options.onError(err) : console.error("[ViewModelShell]", err);
         }
     }
+    /**
+     * NBA-05 (Phase 15): the timer-driven poll dispatch below always calls
+     * `this.dispatch({ name: "poll" }, true)` — passing `silent = true` — so
+     * `nonBlocking = silent || action.blocking === false` in `dispatch()` is
+     * ALWAYS `true` for a poll, regardless of any `blocking` field on the
+     * action itself. This means poll ALWAYS rides the non-blocking lane and
+     * never contends with `blockingInFlight`: `ShellOptions.pollInterval` is
+     * sugar over the same non-blocking dispatch path a `blocking: false`
+     * action uses, not a separate mechanism. See
+     * `.planning/design/non-blocking-actions.md` — "Wire / API surface" (the
+     * "`pollInterval` becomes sugar over the same non-blocking path" line).
+     */
     schedulePoll(nextPollIn) {
         const delay = nextPollIn ?? this.options.pollInterval;
         if (delay == null)

package/dist/server.js

@@ -201,7 +201,10 @@ function collectActions(node, enclosingForm, out) {
             return;
         }
         // Nodes with no dispatch-bearing actions of their own:
-        //   text, link, image, stat-bar, progress, copy-button, badge
+        //   text, link, image, stat-bar, progress, copy-button, badge, chart
+        // ChartNode (CHART-05) is a DELIBERATE childless/action-free leaf — it
+        // carries only data points, so it falls through here with no recursion (no
+        // fits-style blind spot).
         default:
             return;
     }
@@ -366,8 +369,9 @@ function walkForSectionAction(node, outerInteractive) {
             return;
         }
         // Leaf-like nodes (field, checkbox, button, text, link, image, stat-bar,
-        // tabs, progress, table, copy-button, badge) carry no SectionNode
-        // descendants — TableNode rows hold strings + per-row controls, not sections.
+        // tabs, progress, table, copy-button, badge, chart) carry no SectionNode
+        // descendants — TableNode rows hold strings + per-row controls, not sections;
+        // ChartNode (CHART-05) is a childless/action-free data leaf.
         default:
             return;
     }

package/dist/tui.js

@@ -748,6 +748,7 @@ function renderNode(node, ctx, key) {
         case "tabs": return _jsx(TabsView, { node: node, ctx: ctx }, key);
         case "progress": return _jsx(ProgressView, { node: node }, key);
         case "stat-bar": return _jsx(StatBarView, { node: node }, key);
+        case "chart": return _jsx(ChartView, { node: node }, key);
         case "modal": return _jsx(ModalView, { node: node, ctx: ctx }, key);
         case "copy-button": return _jsx(CopyButtonView, { node: node, ctx: ctx }, key);
         case "divider": return _jsx("text", { fg: "#555555", children: node.orientation === "vertical" ? "│" : "─".repeat(40) }, key);
@@ -1100,6 +1101,26 @@ function ProgressView({ node }) {
 function StatBarView({ node }) {
     return (_jsx("box", { flexDirection: "row", gap: 1, children: node.stats.map((s, i) => (_jsxs("box", { flexDirection: "row", gap: 1, children: [i > 0 ? _jsx("text", { fg: "#555555", children: "\u2502" }) : null, _jsx("text", { fg: "#888888", children: s.label }), _jsx("text", { children: String(s.value) })] }, i))) }));
 }
+// ── chart ─────────────────────────────────────────────────────────────────
+// CHART-05 — DELIBERATE degradation. A terminal has no canvas, but a ChartNode
+// is STRUCTURED data, so it prints as a legible label/value/ASCII-bar series:
+// the title (if any) on its own line, then per point `<label padded>  <value>
+// <bar>` where <bar> is a run of "█" scaled to value/max × CHART_BAR_WIDTH.
+// Empty points render just the title (or nothing); an all-zero / non-positive
+// max renders labels+values with no bars (guarded, never throws / divides).
+// The TUI is @experimental; the requirement is only that ChartNode does not
+// break it and degrades legibly. ChartNode is a LEAF (no children) → no
+// container-walk arm is needed (mirrors StatBarView / ProgressView).
+const CHART_BAR_WIDTH = 20;
+function ChartView({ node }) {
+    const points = node.points ?? [];
+    const maxValue = points.length ? Math.max(0, ...points.map((p) => p.value)) : 0;
+    const labelWidth = points.reduce((w, p) => Math.max(w, p.label.length), 0);
+    return (_jsxs("box", { flexDirection: "column", children: [node.title ? _jsx("text", { attributes: 1 /* BOLD */, children: node.title }) : null, points.map((p, i) => {
+                const barLen = maxValue > 0 ? Math.round((p.value / maxValue) * CHART_BAR_WIDTH) : 0;
+                return (_jsxs("box", { flexDirection: "row", gap: 1, children: [_jsx("text", { fg: "#888888", children: p.label.padEnd(labelWidth) }), _jsx("text", { children: String(p.value).padStart(4) }), _jsx("text", { fg: "#4a9eff", children: "█".repeat(barLen) })] }, i));
+            })] }));
+}
 // ── modal ─────────────────────────────────────────────────────────────────
 // Modals are PORTALED to app-root by App (see findModal + ModalOverlay).
 // The inline ModalView (invoked when renderNode hits a "modal" in the tree)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ashley-shrok/viewmodel-shell",
-  "version": "3.11.0",
+  "version": "4.1.0",
   "description": "A server-driven UI framework where the wire format is structured enough that agents can build full-stack apps without ever opening a browser and all UI tests are pure unit tests with no browser runtime. Server returns a JSON tree of typed nodes; a thin TypeScript adapter renders it to DOM. Backend-agnostic \u2014 a .NET reference backend ships with the repo, but any language can produce the JSON contract.",
   "type": "module",
   "license": "MIT",
@@ -44,6 +44,7 @@
     "@types/bun": "^1.1.0",
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",
+    "chart.js": "^4",
     "jsdom": "^25.0.1",
     "react": "^19.2.0",
     "typescript": "^5.4.0",
@@ -56,9 +57,13 @@
     "react": "^19.2.0"
   },
   "peerDependencies": {
+    "chart.js": "^4",
     "vite": ">=5"
   },
   "peerDependenciesMeta": {
+    "chart.js": {
+      "optional": true
+    },
     "vite": {
       "optional": true
     }

package/styles/default.css

@@ -283,6 +283,12 @@ body:has(.vms-page--fill) { margin: 0; }
    the renderer (browser.ts), not in CSS. ── */
 .vms-fits { display: block; }
 
+/* ── Chart container (CHART-01 / Phase 12). Framework CSS (NOT app CSS): Chart.js
+   responsive sizing requires a BOUNDED, positioned container — the canvas fills
+   this wrapper. The zero-app-CSS policy is unaffected (this is shipped framework
+   CSS, and no raw style crosses the wire — tone maps to a --vms-* token). ── */
+.vms-chart { display: block; position: relative; width: 100%; height: 20rem; }
+
 /* ── Alignment: arrange (main axis → justify-content) / align (cross axis →
    align-items) (ALIGN-01/02/03 / 1.12.0). Intended for layout:"row" (the cluster
    primitive) but these are generic box-alignment, so they're harmless on any flex