@ashley-shrok/viewmodel-shell 6.4.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
@@ -3608,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;
@@ -1155,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.4.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

@@ -1783,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);
+}