@ashley-shrok/viewmodel-shell 6.3.0 → 6.5.0

package/dist/browser.d.ts

@@ -250,4 +250,17 @@ export declare class BrowserAdapter implements Adapter {
      *  with an `action` becomes a role="button" tabstop with Enter/Space activation
      *  (Space suppresses page scroll), mirroring TableRow.action / SectionNode.action. */
     private tracker;
+    /** DiffNode — aligned before/after primitive. Row-kind (add/remove/context)
+     *  is derived client-side from the shape of DiffRow: old-only = remove,
+     *  new-only = add, matching text = context, differing text = modified pair
+     *  (side-by-side shows both cells; unified splits into remove-then-add).
+     *  Line-number cells carry the same kind class as their content cell so the
+     *  whole row-side reads as one connected colored band. Left-stripe lives only
+     *  on the leftmost cell of each colored row-side (linenum cell). In unified
+     *  mode the two linenum columns visually collapse into a single left margin
+     *  for context rows; for add/remove rows the second linenum keeps its tint so
+     *  the color band runs continuously, minus the stripe. Design of record:
+     *  `.planning/design/diff-node.md`. Spike-validated 2026-07-19. */
+    private diff;
+    private _diffCell;
 }

package/dist/browser.js

@@ -509,6 +509,7 @@ export class BrowserAdapter {
             case "breadcrumb": return this.breadcrumb(n, parent, on);
             case "steps": return this.steps(n, parent);
             case "tracker": return this.tracker(n, parent, on);
+            case "diff": return this.diff(n, parent);
             default: {
                 // Fail loud, not silent (AGENTS.md: "Nothing important fails quietly").
                 // Runtime trees are server-controlled JSON, so an unknown/forward-version
@@ -3025,6 +3026,45 @@ export class BrowserAdapter {
         if (tableHasCheckboxes) {
             const selTh = document.createElement("th");
             selTh.className = "vms-table__th vms-table__th--select";
+            // Header "select all rendered rows" affordance. A pure client-side toggle
+            // over the leading-column checkboxes: it writes the SAME per-row binds the
+            // row checkboxes use, so the server learns the selection through the exact
+            // path it already knows — no new wire field, and agents (which set binds
+            // directly) never need it. Scope is deliberately "all RENDERED rows": under
+            // filter-narrow that equals all matches; under pagination it is the current
+            // page (selection accumulates via the round-tripped binds); over-cap /
+            // zero-match render no rows, so the control below simply is not drawn and
+            // can never claim to select rows that are not on screen. This re-adds ONLY
+            // the DOM toggle, never the per-toggle dispatch that got the old
+            // TableNode.selection seam removed in 0.15.0.
+            const rowCheckboxes = n.rows.flatMap(r => (r.actions ?? []).filter((e) => e.type === "checkbox"));
+            if (rowCheckboxes.length > 0) {
+                const lbl = document.createElement("label");
+                lbl.className = "vms-checkbox vms-table__select-all";
+                const inp = document.createElement("input");
+                inp.type = "checkbox";
+                inp.className = "vms-checkbox__input";
+                inp.setAttribute("aria-label", "Select all rows");
+                const states = rowCheckboxes.map(cb => Boolean(this.sa.read(cb.bind)));
+                const allChecked = states.every(Boolean);
+                inp.checked = allChecked;
+                inp.indeterminate = !allChecked && states.some(Boolean);
+                const mark = document.createElement("span");
+                mark.className = "vms-checkbox__mark";
+                inp.addEventListener("change", () => {
+                    const target = inp.checked;
+                    for (const cb of rowCheckboxes) {
+                        this.sa.write(cb.bind, target);
+                        const rowInp = document.getElementById(`vms-checkbox-${cb.name}`);
+                        if (rowInp)
+                            rowInp.checked = target;
+                    }
+                    inp.indeterminate = false;
+                });
+                lbl.appendChild(inp);
+                lbl.appendChild(mark);
+                selTh.appendChild(lbl);
+            }
             headerRow.appendChild(selTh);
         }
         const sortIntent = (n.sortBind != null ? this.sa.read(n.sortBind) : null);
@@ -3198,6 +3238,34 @@ export class BrowserAdapter {
         });
         table.appendChild(tbody);
         wrapper.appendChild(table);
+        // Visible-scoped bulk-action toolbar (n.selection). Rendered ABOVE the table.
+        // Each button, on click, harvests the currently-CHECKED, currently-RENDERED
+        // rows (by walking tbody for a checked leading-column checkbox and reading the
+        // row's data-id) and writes that id array to n.selection.harvestBind —
+        // OVERWRITING — before dispatching. So the server only ever sees rows the user
+        // can currently see; a row selected then filtered/paginated out of view is not
+        // harvested. This revives the old selection.buttons[] harvest (removed with the
+        // `context` wire in Phase 6), adapted to write a BIND instead of context. It
+        // adds NONE of the per-toggle dispatch that got the 0.15.0 selection.action
+        // seam removed — selection stays a pure client concern until a bulk click.
+        if (n.selection && n.selection.buttons.length > 0) {
+            const sel = n.selection;
+            const toolbar = document.createElement("div");
+            toolbar.className = "vms-table__bulk-actions";
+            const harvest = (action) => {
+                const ids = [];
+                tbody.querySelectorAll("tr").forEach(tr => {
+                    const box = tr.querySelector(".vms-table__td--select input.vms-checkbox__input");
+                    if (box?.checked && tr.dataset.id)
+                        ids.push(tr.dataset.id);
+                });
+                this.sa.write(sel.harvestBind, ids);
+                on({ name: action.name });
+            };
+            for (const btn of sel.buttons)
+                this.button(btn, toolbar, harvest);
+            wrapper.insertBefore(toolbar, table);
+        }
         if (n.pagination) {
             const pg = n.pagination;
             const footer = document.createElement("div");
@@ -3541,4 +3609,96 @@ export class BrowserAdapter {
         }
         parent.appendChild(strip);
     }
+    /** DiffNode — aligned before/after primitive. Row-kind (add/remove/context)
+     *  is derived client-side from the shape of DiffRow: old-only = remove,
+     *  new-only = add, matching text = context, differing text = modified pair
+     *  (side-by-side shows both cells; unified splits into remove-then-add).
+     *  Line-number cells carry the same kind class as their content cell so the
+     *  whole row-side reads as one connected colored band. Left-stripe lives only
+     *  on the leftmost cell of each colored row-side (linenum cell). In unified
+     *  mode the two linenum columns visually collapse into a single left margin
+     *  for context rows; for add/remove rows the second linenum keeps its tint so
+     *  the color band runs continuously, minus the stripe. Design of record:
+     *  `.planning/design/diff-node.md`. Spike-validated 2026-07-19. */
+    diff(n, parent) {
+        const mode = n.mode ?? "side-by-side";
+        const root = document.createElement("div");
+        root.className = `vms-diff vms-diff--${mode}`;
+        if (n.id != null)
+            root.id = n.id;
+        root.setAttribute("role", "group");
+        root.setAttribute("aria-label", "Diff");
+        // Optional header row(s) — file paths for old / new.
+        if (n.header) {
+            if (mode === "side-by-side") {
+                const hOld = document.createElement("div");
+                hOld.className = "vms-diff__header vms-diff__header--old";
+                hOld.textContent = n.header.old;
+                root.appendChild(hOld);
+                const hNew = document.createElement("div");
+                hNew.className = "vms-diff__header vms-diff__header--new";
+                hNew.textContent = n.header.new;
+                root.appendChild(hNew);
+            }
+            else {
+                const h = document.createElement("div");
+                h.className = "vms-diff__header";
+                h.textContent = `${n.header.old}  →  ${n.header.new}`;
+                root.appendChild(h);
+            }
+        }
+        for (const row of n.rows) {
+            const oldCell = row.old ?? null;
+            const newCell = row.new ?? null;
+            const kindOld = oldCell == null ? "empty"
+                : newCell == null ? "remove"
+                    : oldCell.text === newCell.text ? "context"
+                        : "remove";
+            const kindNew = newCell == null ? "empty"
+                : oldCell == null ? "add"
+                    : newCell.text === oldCell.text ? "context"
+                        : "add";
+            if (mode === "side-by-side") {
+                this._diffCell(root, oldCell?.lineNumber, kindOld, true, "old");
+                this._diffCell(root, oldCell?.text, kindOld, false, "old");
+                this._diffCell(root, newCell?.lineNumber, kindNew, true, "new");
+                this._diffCell(root, newCell?.text, kindNew, false, "new");
+            }
+            else {
+                // Unified: context = one visual row; change = a remove row then an add row.
+                if (kindOld === "context") {
+                    this._diffCell(root, oldCell?.lineNumber, "context", true, "old");
+                    this._diffCell(root, newCell?.lineNumber, "context", true, "new");
+                    this._diffCell(root, oldCell?.text, "context", false, "old");
+                }
+                else {
+                    if (oldCell !== null) {
+                        this._diffCell(root, oldCell?.lineNumber, "remove", true, "old");
+                        this._diffCell(root, "", "remove", true, "new");
+                        this._diffCell(root, oldCell?.text, "remove", false, "old");
+                    }
+                    if (newCell !== null) {
+                        this._diffCell(root, "", "add", true, "old");
+                        this._diffCell(root, newCell?.lineNumber, "add", true, "new");
+                        this._diffCell(root, newCell?.text, "add", false, "new");
+                    }
+                }
+            }
+        }
+        parent.appendChild(root);
+    }
+    _diffCell(parent, content, kind, isLinenum, side) {
+        const el = document.createElement("div");
+        const parts = ["vms-diff__cell", `vms-diff__cell--${kind}`];
+        if (isLinenum) {
+            parts.push("vms-diff__cell--linenum");
+            parts.push(side === "old" ? "vms-diff__cell--old-linenum" : "vms-diff__cell--new-linenum");
+            // Line numbers are visual gutter — hide from SR (the actual content
+            // announces on the content cell). Also mark unselectable via CSS.
+            el.setAttribute("aria-hidden", "true");
+        }
+        el.className = parts.join(" ");
+        el.textContent = content == null ? "" : String(content);
+        parent.appendChild(el);
+    }
 }

package/dist/index.d.ts

@@ -103,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 | ChartNode | BreadcrumbNode | StepsNode | TrackerNode;
+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 | BreadcrumbNode | StepsNode | TrackerNode | DiffNode;
 export interface PageNode {
     type: "page";
     title?: string;
@@ -868,6 +868,31 @@ export interface TableNode {
      *  filter dispatches reset `page` to 1 on the server side, since
      *  the row window changes underneath them. */
     pagination?: TablePagination;
+    /** Visible-scoped bulk-action toolbar (opt-in). When set, the adapter renders
+     *  `selection.buttons[]` ABOVE the table; each button, on click, harvests the
+     *  currently-CHECKED, currently-RENDERED row ids (from the leading-column
+     *  per-row checkboxes) and writes them — a `string[]` of `TableRow.id` — to
+     *  `selection.harvestBind`, OVERWRITING, before dispatching its own action.
+     *  The server reads that path to act, so a bulk action can only ever affect
+     *  rows the user can currently see: a row selected under one filter and then
+     *  filtered/paginated out of view is NOT harvested. This is the safe default
+     *  for the common case; an app that genuinely wants cross-page/persistent
+     *  selection simply ignores this block and reads its own bound `selectedIds`
+     *  map instead (the framework never introspects app state, so that escape
+     *  hatch is always open). Selectable rows must carry `TableRow.id`. */
+    selection?: TableSelection;
+}
+/** Visible-scoped bulk-action toolbar for a `TableNode` — see `TableNode.selection`. */
+export interface TableSelection {
+    /** Bulk-action buttons rendered above the table. On click, each harvests the
+     *  visible-checked row ids into `harvestBind` (overwriting) and dispatches its
+     *  own `action` — name-only, per the Phase-6 wire. Full ButtonNodes, so they
+     *  carry their own emphasis/tone/confirm/disabled. */
+    buttons: ButtonNode[];
+    /** State path the harvest writes the visible-checked row-id array (`string[]`)
+     *  to right before dispatch. The server reads THIS to act — not a per-row
+     *  `selectedIds` map — which is what makes the action visible-scoped. */
+    harvestBind: string;
 }
 export interface CopyButtonNode {
     type: "copy-button";
@@ -1130,6 +1155,76 @@ export interface TrackerNode {
     /** Ordered buckets, oldest → newest (rendered left → right). */
     cells: TrackerCell[];
 }
+/** One cell of a diff row (either the "old" side or the "new" side). Carries the
+ *  cell's text plus an optional line number for the gutter. `text` may be an
+ *  empty string. The wire distinction "cell present but empty" vs "cell absent"
+ *  (the `null` case on the parent DiffRow) carries meaning — see DiffRow. */
+export interface DiffCell {
+    text: string;
+    lineNumber?: number;
+}
+/** One row of a DiffNode. Row-KIND (add / remove / context) is derived
+ *  client-side from the shape of the row itself — no separate `kind` wire field:
+ *
+ *    old != null && new == null  →  REMOVE  (left-side content, right side empty)
+ *    old == null && new != null  →  ADD     (right-side content, left side empty)
+ *    old.text === new.text       →  CONTEXT (unchanged; both sides identical)
+ *    old.text !== new.text       →  a modified pair — both cells shown side-by-side
+ *                                    and tinted in side-by-side mode; splits into
+ *                                    a REMOVE then ADD row-pair in unified mode
+ *
+ *  This "shape carries the meaning" pattern makes it impossible for a `kind`
+ *  label to disagree with the content, and keeps the wire compact. Line numbers
+ *  are optional so diff sources that don't track them (e.g. two prose versions)
+ *  degrade to a content-only column. */
+export interface DiffRow {
+    /** Old (pre-change) cell. OMIT to signal a pure addition (no left-side content).
+     *  Wire contract (gotcha #8): omit the key rather than emit `"old": null` — an
+     *  unset optional is ABSENT, never `"field": null`. The renderer treats a
+     *  missing key as "no old side" (pure add). */
+    old?: DiffCell;
+    /** New (post-change) cell. OMIT to signal a pure removal (no right-side content).
+     *  Same wire contract as `old` — omit the key rather than emit `null`. */
+    new?: DiffCell;
+}
+/** DiffNode — aligned before/after primitive for review, audit, and
+ *  change-comparison apps. Consumers compute the diff server-side (LibGit2Sharp
+ *  on .NET, `diff` lib on TS, `git diff --json`, whatever they have) and hand
+ *  VMS the structured rows — same server-computes / framework-renders doctrine
+ *  as the markdown → tree pattern. The framework owns ALL appearance and a11y:
+ *  the CSS-Grid alignment (4 tracks in side-by-side, 3 in unified), the tint +
+ *  left-stripe row coloring, the long-line horizontal-scroll-per-cell that
+ *  preserves row alignment, the empty-cell styling, the tinted line numbers,
+ *  and the unified-mode collapse of the two linenum columns into a single left
+ *  margin. This is the CHARTS/TRACKER precedent applied to before/after
+ *  content — aligned side-by-side is a genuinely uncomposable capability that
+ *  no combination of existing nodes produces (two `pre` blocks in `layout:"split"`
+ *  give you two independent walls of text with no row alignment). Explicitly
+ *  out of scope for v1: syntax highlighting on cells (a separate CodeBlockNode
+ *  question), word-level intra-line diff highlighting (would need inline rich
+ *  text, an open architectural question), in-line review comments, and
+ *  collapse/expand of hunks (consumers who want that compute a smaller `rows`
+ *  array server-side). Design of record: [design/diff-node.md](../../.planning/design/diff-node.md). */
+export interface DiffNode {
+    type: "diff";
+    id?: string;
+    /** Ordered rows, top → bottom (rendered in order). */
+    rows: DiffRow[];
+    /** Layout mode. Omitted = "side-by-side" (the default — the whole reason this
+     *  primitive exists over composition of two `pre` blocks). "unified" = a
+     *  single-column form with dual line-number columns, useful when horizontal
+     *  space is constrained or the app prefers the git-log-style presentation.
+     *  Closed union (DIFF-01). */
+    mode?: "unified" | "side-by-side";
+    /** Optional header row showing file paths (or any labels) for old/new. In
+     *  side-by-side mode: spans the two column-groups (2 tracks each). In unified
+     *  mode: spans all 3 tracks and joins the two labels with " → ". Omitted =
+     *  no header. */
+    header?: {
+        old: string;
+        new: string;
+    };
+}
 export interface ShellOptions {
     endpoint: string;
     actionEndpoint: string;

package/dist/server.js

@@ -239,11 +239,11 @@ function collectActions(node, enclosingForm, out) {
             return;
         }
         // Nodes with no dispatch-bearing actions of their own:
-        //   text, link, image, stat-bar, progress, copy-button, badge, chart, steps
+        //   text, link, image, stat-bar, progress, copy-button, badge, chart, steps, diff
         //   (breadcrumb crumb actions ARE recorded above via the "breadcrumb" arm)
-        // ChartNode (CHART-05) and StepsNode (NAV-02) are DELIBERATE
-        // childless/action-free leaves — they carry only data, so they fall through
-        // here with no recursion (no fits-style blind spot).
+        // ChartNode (CHART-05), StepsNode (NAV-02), and DiffNode (DIFF-01) are
+        // DELIBERATE childless/action-free leaves — they carry only data, so they
+        // fall through here with no recursion (no fits-style blind spot).
         default:
             return;
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ashley-shrok/viewmodel-shell",
-  "version": "6.3.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 — a .NET reference backend ships with the repo, but any language can produce the JSON contract.",
+  "version": "6.5.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",
   "author": "ashley-shrok",

package/styles/default.css

@@ -884,6 +884,14 @@ select.vms-field__input  { cursor: pointer; padding-right: var(--vms-space-xl);
   border-left: none;
   transform: rotate(40deg);
 }
+.vms-checkbox__input:indeterminate + .vms-checkbox__mark { background: var(--vms-accent); border-color: var(--vms-accent); }
+.vms-checkbox__input:indeterminate + .vms-checkbox__mark::after {
+  content: '';
+  position: absolute;
+  left: 3px; top: 7px;
+  width: 10px; height: 0;
+  border-top: 2px solid #fff;
+}
 .vms-checkbox__label { margin-left: var(--vms-space-xs); font-size: var(--vms-text-base); }
 
 /* ── Buttons — three orthogonal axes: emphasis (fill) × tone (color) × size
@@ -1775,3 +1783,109 @@ button.vms-breadcrumb__link {
   position: relative; /* lift the ring above neighbors */
   z-index: 1;
 }
+
+/* ── DiffNode ────────────────────────────────────────────────────────────────
+   Aligned before/after primitive. CSS Grid handles vertical alignment across
+   two columns naturally (each row's cells share a grid row). Long lines
+   overflow HORIZONTALLY within their cell (per-cell overflow-x: auto) — never
+   wrap, because wrapping would break the row-alignment guarantee. Row-kind
+   coloring is DUAL SIGNAL: background tint (22% alpha) + a 3px inset left
+   stripe on the leftmost cell of each colored row-side. Spike-validated
+   2026-07-19; design of record: .planning/design/diff-node.md. */
+.vms-diff {
+  display: grid;
+  font-family: var(--vms-font-mono, ui-monospace, SFMono-Regular, monospace);
+  font-size: var(--vms-text-sm);
+  line-height: 1.5;
+  border: 1px solid var(--vms-border);
+  border-radius: var(--vms-radius-md, 6px);
+  overflow: hidden;
+  background: var(--vms-surface);
+  color: var(--vms-text);
+}
+/* Side-by-side: 4 tracks (old-line#, old-content, new-line#, new-content). */
+.vms-diff--side-by-side {
+  grid-template-columns:
+    [old-line] max-content
+    [old-content] minmax(0, 1fr)
+    [new-line] max-content
+    [new-content] minmax(0, 1fr);
+}
+/* Unified: 3 tracks (dual line#s + one content column). */
+.vms-diff--unified {
+  grid-template-columns:
+    [line-old] max-content
+    [line-new] max-content
+    [content] minmax(0, 1fr);
+}
+.vms-diff__cell {
+  padding: 0.15em 0.6em;
+  white-space: pre;
+  overflow-x: auto;
+  min-width: 0; /* required inside minmax(0,1fr) so overflow doesn't blow the track */
+}
+/* Line-number cells (base — neutral tint; add/remove/empty override below). */
+.vms-diff__cell--linenum {
+  color: var(--vms-text-muted);
+  text-align: right;
+  user-select: none;
+  padding: 0.15em 0.5em;
+  border-right: 1px solid var(--vms-border);
+  background: color-mix(in srgb, var(--vms-text-muted) 4%, transparent);
+}
+/* Row-kind coloring — applied to BOTH linenum and content cells so each row-side
+   reads as one connected colored band. Stripe on the leftmost cell only. */
+.vms-diff__cell--add {
+  background: color-mix(in srgb, var(--vms-success) 22%, transparent);
+}
+.vms-diff__cell--remove {
+  background: color-mix(in srgb, var(--vms-error) 22%, transparent);
+}
+.vms-diff__cell--linenum.vms-diff__cell--add {
+  box-shadow: inset 3px 0 0 0 var(--vms-success);
+  color: var(--vms-success);
+}
+.vms-diff__cell--linenum.vms-diff__cell--remove {
+  box-shadow: inset 3px 0 0 0 var(--vms-error);
+  color: var(--vms-error);
+}
+.vms-diff__cell--context {
+  /* neutral — no fill */
+}
+.vms-diff__cell--empty {
+  background: color-mix(in srgb, var(--vms-text-muted) 6%, transparent);
+}
+/* Unified mode — collapse the two linenum columns visually into one left margin.
+   Context rows: only leftmost linenum keeps muted base + border-right (one clean
+   line-# margin). Add/remove rows: the second linenum keeps its row-tint so the
+   color band runs continuously across [line#][line#][content], but drops the
+   stripe (which belongs only on the leftmost cell of the row). */
+.vms-diff--unified .vms-diff__cell--new-linenum {
+  background: transparent;
+  border-right: none;
+}
+.vms-diff--unified .vms-diff__cell--new-linenum.vms-diff__cell--add {
+  background: color-mix(in srgb, var(--vms-success) 22%, transparent);
+  box-shadow: none;
+}
+.vms-diff--unified .vms-diff__cell--new-linenum.vms-diff__cell--remove {
+  background: color-mix(in srgb, var(--vms-error) 22%, transparent);
+  box-shadow: none;
+}
+/* Header (optional file-path row). */
+.vms-diff__header {
+  padding: 0.4em 0.8em;
+  font-weight: 600;
+  background: color-mix(in srgb, var(--vms-text-muted) 8%, transparent);
+  border-bottom: 1px solid var(--vms-border);
+}
+.vms-diff--side-by-side .vms-diff__header--old { grid-column: old-line / span 2; }
+.vms-diff--side-by-side .vms-diff__header--new {
+  grid-column: new-line / span 2;
+  border-left: 1px solid var(--vms-border);
+}
+.vms-diff--unified .vms-diff__header { grid-column: 1 / -1; }
+/* Vertical divider between old and new in side-by-side mode. */
+.vms-diff--side-by-side .vms-diff__cell--new-linenum {
+  border-left: 1px solid var(--vms-border);
+}