@ashley-shrok/viewmodel-shell 0.10.0 → 0.12.0

package/README.md

@@ -51,6 +51,8 @@ The download endpoint stays auth-gated and the server authorizes in the action h
 
 ## Terminal (TUI)
 
+> ⚠️ **Experimental.** The terminal adapter (`@ashley-shrok/viewmodel-shell/tui` + `vms-tui`) is incomplete and under active design — scrolling, keyboard/focus ergonomics, and layout coverage all need more work. Its API and behavior may change or be removed **without a major-version bump**; don't build production workflows on it yet. The browser/server/core packages are stable and unaffected. Constructing a `TuiAdapter` prints a one-time notice — silence it with `VMS_TUI_SILENCE_EXPERIMENTAL=1`.
+
 The same backend renders in a terminal — same wire, no backend change, with a real lazygit-style UX: mouse clicks, wheel scroll, per-pane focus cycle, and a context-aware status bar. Point the CLI at any ViewModel Shell endpoint:
 
 ```bash

package/dist/browser.d.ts

@@ -31,6 +31,7 @@ export declare class BrowserAdapter implements Adapter {
     private link;
     private statBar;
     private tabs;
+    private image;
     private progress;
     private modal;
     private table;

package/dist/browser.js

@@ -190,6 +190,7 @@ export class BrowserAdapter {
             case "button": return this.button(n, parent, on);
             case "text": return this.text(n, parent);
             case "link": return this.link(n, parent);
+            case "image": return this.image(n, parent);
             case "stat-bar": return this.statBar(n, parent);
             case "tabs": return this.tabs(n, parent, on);
             case "progress": return this.progress(n, parent);
@@ -569,6 +570,19 @@ export class BrowserAdapter {
         });
         parent.appendChild(nav);
     }
+    image(n, parent) {
+        const img = document.createElement("img");
+        let cls = "vms-image";
+        if (n.size)
+            cls += ` vms-image--${n.size}`;
+        if (n.shape)
+            cls += ` vms-image--${n.shape}`;
+        img.className = cls;
+        img.src = n.src;
+        if (n.alt != null)
+            img.alt = n.alt;
+        parent.appendChild(img);
+    }
     progress(n, parent) {
         const track = document.createElement("div");
         track.className = "vms-progress";
@@ -623,6 +637,25 @@ export class BrowserAdapter {
         table.className = "vms-table";
         const thead = document.createElement("thead");
         const headerRow = document.createElement("tr");
+        // Selection: a leading checkbox column. The header box is a select-all over
+        // the rows CURRENTLY rendered (the current page) — never unloaded rows.
+        const sel = n.selection;
+        const selectedSet = sel ? new Set(sel.selectedIds) : null;
+        if (sel) {
+            const th = document.createElement("th");
+            th.className = "vms-table__th vms-table__th--select";
+            const allOnPage = n.rows.length > 0 && n.rows.every(r => r.id != null && selectedSet.has(r.id));
+            const someOnPage = n.rows.some(r => r.id != null && selectedSet.has(r.id));
+            const box = document.createElement("input");
+            box.type = "checkbox";
+            box.className = "vms-table__select vms-table__select--all";
+            box.checked = allOnPage;
+            box.indeterminate = someOnPage && !allOnPage;
+            const selAction = sel.action;
+            box.addEventListener("change", () => on({ name: selAction.name, context: { ...(selAction.context ?? {}), all: true, checked: box.checked } }));
+            th.appendChild(box);
+            headerRow.appendChild(th);
+        }
         n.columns.forEach(col => {
             const th = document.createElement("th");
             const isSorted = col.key === n.sortColumn;
@@ -651,6 +684,8 @@ export class BrowserAdapter {
             const filterAction = n.filterAction;
             const filterRow = document.createElement("tr");
             filterRow.className = "vms-table__filter-row";
+            if (sel)
+                filterRow.appendChild(document.createElement("th")); // align under the select column
             n.columns.forEach(col => {
                 const th = document.createElement("th");
                 if (col.filterable) {
@@ -684,6 +719,9 @@ export class BrowserAdapter {
                 rowClass += ` vms-table__row--${row.variant}`;
             if (row.action)
                 rowClass += " vms-table__row--clickable";
+            const isSelected = sel != null && row.id != null && selectedSet.has(row.id);
+            if (isSelected)
+                rowClass += " vms-table__row--selected";
             tr.className = rowClass;
             if (row.id)
                 tr.dataset.id = row.id;
@@ -691,6 +729,26 @@ export class BrowserAdapter {
                 const rowAction = row.action;
                 tr.addEventListener("click", () => on(rowAction));
             }
+            if (sel) {
+                const td = document.createElement("td");
+                td.className = "vms-table__td vms-table__td--select";
+                // A click in the checkbox cell must not also fire the row's click action.
+                td.addEventListener("click", (e) => e.stopPropagation());
+                const box = document.createElement("input");
+                box.type = "checkbox";
+                box.className = "vms-table__select";
+                box.checked = isSelected;
+                if (row.id != null) {
+                    const rowId = row.id;
+                    const selAction = sel.action;
+                    box.addEventListener("change", () => on({ name: selAction.name, context: { ...(selAction.context ?? {}), id: rowId, checked: box.checked } }));
+                }
+                else {
+                    box.disabled = true; // selection addresses rows by id; a row without one can't be selected
+                }
+                td.appendChild(box);
+                tr.appendChild(td);
+            }
             n.columns.forEach(col => {
                 const td = document.createElement("td");
                 td.className = "vms-table__td";
@@ -715,6 +773,32 @@ export class BrowserAdapter {
         });
         table.appendChild(tbody);
         wrapper.appendChild(table);
+        if (n.pagination) {
+            const pg = n.pagination;
+            const footer = document.createElement("div");
+            footer.className = "vms-table__pagination";
+            const totalPages = Math.max(1, Math.ceil(pg.totalRows / pg.pageSize));
+            const from = pg.totalRows === 0 ? 0 : (pg.page - 1) * pg.pageSize + 1;
+            const to = Math.min(pg.page * pg.pageSize, pg.totalRows);
+            const range = document.createElement("span");
+            range.className = "vms-table__pagination-range";
+            range.textContent = `${from}–${to} of ${pg.totalRows}`;
+            footer.appendChild(range);
+            const pgAction = pg.action;
+            const mkBtn = (label, targetPage, disabled) => {
+                const b = document.createElement("button");
+                b.type = "button";
+                b.className = "vms-button vms-button--secondary vms-table__pagination-btn";
+                b.textContent = label;
+                b.disabled = disabled;
+                if (!disabled)
+                    b.addEventListener("click", () => on({ name: pgAction.name, context: { ...(pgAction.context ?? {}), page: targetPage } }));
+                return b;
+            };
+            footer.appendChild(mkBtn("‹ Prev", pg.page - 1, pg.page <= 1));
+            footer.appendChild(mkBtn("Next ›", pg.page + 1, pg.page >= totalPages));
+            wrapper.appendChild(footer);
+        }
         parent.appendChild(wrapper);
     }
     copyButton(n, parent) {

package/dist/index.d.ts

@@ -33,7 +33,7 @@ export interface Adapter {
      *  async I/O errors surface via onError. */
     saveFile?(data: Blob, filename: string, contentType: string): void | Promise<void>;
 }
-export type ViewNode = PageNode | SectionNode | ListNode | ListItemNode | FormNode | FieldNode | CheckboxNode | ButtonNode | TextNode | LinkNode | StatBarNode | TabsNode | ProgressNode | ModalNode | TableNode | CopyButtonNode;
+export type ViewNode = PageNode | SectionNode | ListNode | ListItemNode | FormNode | FieldNode | CheckboxNode | ButtonNode | TextNode | LinkNode | ImageNode | StatBarNode | TabsNode | ProgressNode | ModalNode | TableNode | CopyButtonNode;
 export interface PageNode {
     type: "page";
     title?: string;
@@ -131,7 +131,7 @@ export interface ButtonNode {
 export interface TextNode {
     type: "text";
     value: string;
-    style?: "heading" | "subheading" | "body" | "muted" | "strikethrough" | "error" | "pre";
+    style?: "heading" | "subheading" | "body" | "muted" | "strikethrough" | "error" | "warning" | "pre";
 }
 export interface LinkNode {
     type: "link";
@@ -140,6 +140,18 @@ export interface LinkNode {
     /** true = open outside current app context (browser: new tab + noopener) */
     external?: boolean;
 }
+export interface ImageNode {
+    type: "image";
+    /** Image source URL (required). */
+    src: string;
+    /** Accessibility text. Non-browser adapters (TUI) degrade to this. */
+    alt?: string;
+    /** Design-system sizing hint → `.vms-image--{size}`. Omit for intrinsic size
+     *  (capped at 100% of the container). NOT free-form CSS. */
+    size?: "small" | "medium" | "large" | "full";
+    /** `"circle"` → square-cropped circular image (avatars). */
+    shape?: "circle";
+}
 export interface StatBarNode {
     type: "stat-bar";
     stats: Array<{
@@ -190,6 +202,32 @@ export interface TableRow {
     action?: ActionEvent;
     variant?: string;
 }
+export interface TableSelection {
+    /** Row ids currently selected — server-truth. The adapter checks each row
+     *  whose `id` is in this list and emits `.vms-table__row--selected` on it.
+     *  Selection survives sort/filter/pagination because it round-trips in state,
+     *  independent of which rows are currently in `rows`. */
+    selectedIds: string[];
+    /** Dispatched on a selection toggle. The adapter merges `{ id, checked }` for
+     *  a per-row checkbox, or `{ all: true, checked }` for the header select-all
+     *  checkbox (where "all" means the rows currently rendered — i.e. the current
+     *  page, never unloaded rows). The "select all N matching" affordance, when an
+     *  app wants it, is the app's own node composed above the table — the
+     *  framework gives the primitive, not the policy. */
+    action: ActionEvent;
+}
+export interface TablePagination {
+    /** 1-based current page. */
+    page: number;
+    /** Rows per page. Drives the "X–Y of N" range label and the last-page calc. */
+    pageSize: number;
+    /** Total rows across all pages — server-truth. The adapter renders the range
+     *  label and enables/disables prev/next from this; it does NOT slice. */
+    totalRows: number;
+    /** Dispatched on a page-control click. The adapter merges `{ page }` — the
+     *  target 1-based page. */
+    action: ActionEvent;
+}
 export interface TableNode {
     type: "table";
     columns: TableColumn[];
@@ -200,6 +238,18 @@ export interface TableNode {
     sortAction?: ActionEvent;
     /** Base action. Adapter merges { column, value, filters } into context on Enter. */
     filterAction?: ActionEvent;
+    /** Per-row multi-select. When set, the adapter renders a leading checkbox
+     *  column + a header select-all checkbox and tints selected rows. `TableRow.id`
+     *  is REQUIRED on every row when selection is set — it's the address the
+     *  toggle action reports back. */
+    selection?: TableSelection;
+    /** Server-driven pagination. When set, the adapter renders an "X–Y of N"
+     *  range + prev/next controls below the table. **The server slices `rows` to
+     *  the current page** — the adapter never paginates client-side (that would
+     *  break for DB-backed tables, which are most of them). By convention
+     *  `sortAction` / `filterAction` reset `page` to 1 on the server side, since
+     *  the row window changes underneath them. */
+    pagination?: TablePagination;
 }
 export interface CopyButtonNode {
     type: "copy-button";

package/dist/tui.d.ts

@@ -8,6 +8,16 @@ interface TuiOpts {
      *  of the available width; the remainder fills with the rest of the children. */
     sidebarFraction?: number;
 }
+/**
+ * Renders a ViewModel Shell view tree to a terminal via OpenTUI (Bun runtime).
+ *
+ * @experimental The terminal adapter is incomplete and under active design —
+ * scrolling, keyboard/focus ergonomics, and layout coverage all need more
+ * work. Its API and behavior may change or be removed without a major-version
+ * bump. Constructing one prints a one-time stderr notice (silence with
+ * `VMS_TUI_SILENCE_EXPERIMENTAL=1`). The browser/server/core packages are
+ * stable; only `@ashley-shrok/viewmodel-shell/tui` + `vms-tui` are experimental.
+ */
 export declare class TuiAdapter implements Adapter {
     private renderer;
     private root;
@@ -74,5 +84,9 @@ export declare class TuiAdapter implements Adapter {
      *  landed (parity with the Ink adapter's _peekSession). */
     _peekSession(key: string): string | undefined;
 }
+/**
+ * @experimental Part of the experimental terminal target (see {@link TuiAdapter}).
+ * A static, non-mounting render path used by the cross-adapter conformance suite.
+ */
 export declare function renderTree(vm: ViewNode): React.ReactNode;
 export {};

package/dist/tui.js

@@ -3,6 +3,34 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { spawn } from "node:child_process";
+// ─── Experimental notice ───────────────────────────────────────────────────
+// The terminal adapter is EXPERIMENTAL (see the @experimental tag on
+// TuiAdapter). We emit a one-time stderr heads-up the first time a TuiAdapter
+// is constructed in a process — covering both `vms-tui` (which constructs one)
+// and programmatic consumers. Fires once per process; silence with
+// VMS_TUI_SILENCE_EXPERIMENTAL=1 for deliberate users who don't want the nag.
+let experimentalNoticeShown = false;
+function warnExperimental() {
+    if (experimentalNoticeShown)
+        return;
+    experimentalNoticeShown = true;
+    if (process.env.VMS_TUI_SILENCE_EXPERIMENTAL)
+        return;
+    process.stderr.write("[vms-tui] ⚠ The terminal adapter (TuiAdapter) is EXPERIMENTAL: incomplete, " +
+        "under-tested, and subject to breaking change or removal without a major-version " +
+        "bump. Not recommended for production. The browser/server/core packages are " +
+        "stable and unaffected. Silence this notice with VMS_TUI_SILENCE_EXPERIMENTAL=1.\n");
+}
+/**
+ * Renders a ViewModel Shell view tree to a terminal via OpenTUI (Bun runtime).
+ *
+ * @experimental The terminal adapter is incomplete and under active design —
+ * scrolling, keyboard/focus ergonomics, and layout coverage all need more
+ * work. Its API and behavior may change or be removed without a major-version
+ * bump. Constructing one prints a one-time stderr notice (silence with
+ * `VMS_TUI_SILENCE_EXPERIMENTAL=1`). The browser/server/core packages are
+ * stable; only `@ashley-shrok/viewmodel-shell/tui` + `vms-tui` are experimental.
+ */
 export class TuiAdapter {
     renderer = null;
     root = null;
@@ -38,6 +66,7 @@ export class TuiAdapter {
     // pending state, no per-button cleanup wiring needed).
     pendingButtonKey = null;
     constructor(opts) {
+        warnExperimental();
         this.viewport = opts?.viewport ?? "fill";
         const f = opts?.sidebarFraction ?? 1 / 3;
         this.sidebarFraction = Math.min(0.6, Math.max(0.15, f));
@@ -672,6 +701,7 @@ function renderNode(node, ctx, key) {
         case "section": return _jsx(SectionView, { node: node, ctx: ctx }, key);
         case "text": return _jsx(TextView, { node: node }, key);
         case "link": return _jsx(LinkView, { node: node, ctx: ctx }, key);
+        case "image": return _jsx(ImageView, { node: node }, key);
         case "list": return _jsx(ListView, { node: node, ctx: ctx }, key);
         case "list-item": return _jsx(ListItemView, { node: node, ctx: ctx }, key);
         case "table": return _jsx(TableView, { node: node, ctx: ctx }, key);
@@ -775,6 +805,7 @@ const STYLE_ATTRS = {
     muted: { fg: "#888888" },
     strikethrough: { attributes: 16 /* STRIKETHROUGH */, fg: "#888888" },
     error: { fg: "#ff5555" },
+    warning: { fg: "#e0a823" },
     pre: { fg: "#cccccc" },
 };
 function TextView({ node }) {
@@ -804,6 +835,14 @@ function LinkView({ node, ctx }) {
         : undefined;
     return (_jsx("text", { attributes: 4 /* UNDERLINE */, fg: "#6688cc", ...(onMouseDown ? { onMouseDown } : {}), children: inner }));
 }
+// ── image ─────────────────────────────────────────────────────────────────
+// Terminals can't render raster images, so the TUI degrades to the alt text
+// (the wire's accessibility intent) — the multi-target-safe contract from the
+// ImageNode design. size/shape are browser-only layout hints and are ignored.
+function ImageView({ node }) {
+    const alt = node.alt && node.alt.trim().length > 0 ? node.alt : "image";
+    return _jsxs("text", { fg: "#888888", children: ["[image: ", alt, "]"] });
+}
 // ── list / list-item ──────────────────────────────────────────────────────
 // A top-level `list` (direct child of page) is a pane on its own; nested
 // lists scroll as part of their containing section. list-item variants
@@ -875,38 +914,75 @@ function TableView({ node, ctx }) {
             context: { ...(node.sortAction.context ?? {}), column: columnKey, direction },
         });
     };
-    return (_jsx("scrollbox", { focused: focused, focusable: isPaneFocusable, borderColor: focused ? "#88aaff" : "#555555", focusedBorderColor: "#88aaff", flexGrow: 1, flexShrink: 1, children: _jsxs("box", { flexDirection: "column", children: [_jsx("box", { flexDirection: "row", gap: 2, children: node.columns.map((c) => {
-                        const isSorted = node.sortColumn === c.key;
-                        const caret = isSorted ? (node.sortDirection === "desc" ? " ↓" : " ↑") : "";
-                        // B5 — only sortable headers respond to clicks (matches BrowserAdapter).
-                        const clickable = c.sortable && node.sortAction != null;
-                        const onMouseDown = clickable ? () => onHeaderClick(c.key) : undefined;
-                        return (_jsxs("text", { attributes: 1 /* BOLD */, ...(onMouseDown ? { onMouseDown } : {}), children: [c.label, caret] }, c.key));
-                    }) }), node.columns.some((c) => c.filterable) ? (_jsx("box", { flexDirection: "row", gap: 2, children: node.columns.map((c) => (_jsx("text", { fg: "#888888", children: c.filterable ? (c.filterValue ? `[${c.filterValue}]` : "[filter]") : "" }, c.key))) })) : null, node.rows.map((row, ri) => {
+    // Selection — leading [x]/[ ] column. Dispatch payloads match BrowserAdapter:
+    // { id, checked } per row, { all: true, checked } for select-all.
+    const sel = node.selection;
+    const selectedSet = sel ? new Set(sel.selectedIds) : null;
+    const allOnPage = sel != null && node.rows.length > 0 &&
+        node.rows.every((r) => r.id != null && selectedSet.has(r.id));
+    const onToggleAll = sel
+        ? () => ctx.onAction({
+            name: sel.action.name,
+            context: { ...(sel.action.context ?? {}), all: true, checked: !allOnPage },
+        })
+        : undefined;
+    const onToggleRow = sel
+        ? (rowId, checked) => ctx.onAction({
+            name: sel.action.name,
+            context: { ...(sel.action.context ?? {}), id: rowId, checked },
+        })
+        : undefined;
+    return (_jsx("scrollbox", { focused: focused, focusable: isPaneFocusable, borderColor: focused ? "#88aaff" : "#555555", focusedBorderColor: "#88aaff", flexGrow: 1, flexShrink: 1, children: _jsxs("box", { flexDirection: "column", children: [_jsxs("box", { flexDirection: "row", gap: 2, children: [sel ? (_jsx("text", { attributes: 1 /* BOLD */, ...(onToggleAll ? { onMouseDown: onToggleAll } : {}), children: allOnPage ? "[x]" : "[ ]" })) : null, node.columns.map((c) => {
+                            const isSorted = node.sortColumn === c.key;
+                            const caret = isSorted ? (node.sortDirection === "desc" ? " ↓" : " ↑") : "";
+                            // B5 — only sortable headers respond to clicks (matches BrowserAdapter).
+                            const clickable = c.sortable && node.sortAction != null;
+                            const onMouseDown = clickable ? () => onHeaderClick(c.key) : undefined;
+                            return (_jsxs("text", { attributes: 1 /* BOLD */, ...(onMouseDown ? { onMouseDown } : {}), children: [c.label, caret] }, c.key));
+                        })] }), node.columns.some((c) => c.filterable) ? (_jsxs("box", { flexDirection: "row", gap: 2, children: [sel ? _jsx("text", { fg: "#888888", children: "   " }) : null, node.columns.map((c) => (_jsx("text", { fg: "#888888", children: c.filterable ? (c.filterValue ? `[${c.filterValue}]` : "[filter]") : "" }, c.key)))] })) : null, node.rows.map((row, ri) => {
                     // B5 — row click dispatches row.action when present.
                     const onRowClick = row.action
                         ? () => ctx.onAction(row.action)
                         : undefined;
-                    return (_jsx("box", { flexDirection: "row", gap: 2, ...(onRowClick ? { onMouseDown: onRowClick } : {}), children: node.columns.map((c) => {
-                            const cell = row.cells[c.key] ?? "";
-                            if (c.linkLabel != null && cell.length > 0) {
-                                // Cell is a link — emit OSC-8 for external links, plain
-                                // underlined text otherwise. External links are clickable
-                                // natively via the terminal's OSC-8 support; internal cell
-                                // links route through navigate (B5).
-                                const ESC = String.fromCharCode(27);
-                                const BEL = String.fromCharCode(7);
-                                const inner = c.linkExternal
-                                    ? `${ESC}]8;;${cell}${BEL}${c.linkLabel}${ESC}]8;;${BEL}`
-                                    : c.linkLabel;
-                                const cellClick = !c.linkExternal && cell.length > 0
-                                    ? () => ctx.navigate(cell)
+                    return (_jsxs("box", { flexDirection: "row", gap: 2, ...(onRowClick ? { onMouseDown: onRowClick } : {}), children: [sel ? (() => {
+                                const isSel = row.id != null && selectedSet.has(row.id);
+                                const rowId = row.id;
+                                const onBox = rowId != null && onToggleRow
+                                    ? () => onToggleRow(rowId, !isSel)
                                     : undefined;
-                                return (_jsx("text", { attributes: 4 /* UNDERLINE */, fg: "#6688cc", ...(cellClick ? { onMouseDown: cellClick } : {}), children: inner }, c.key));
-                            }
-                            return _jsx("text", { children: cell }, c.key);
-                        }) }, row.id ?? ri));
-                })] }) }));
+                                return (_jsx("text", { fg: isSel ? "#88ff88" : "#888888", ...(onBox ? { onMouseDown: onBox } : {}), children: isSel ? "[x]" : "[ ]" }));
+                            })() : null, node.columns.map((c) => {
+                                const cell = row.cells[c.key] ?? "";
+                                if (c.linkLabel != null && cell.length > 0) {
+                                    // Cell is a link — emit OSC-8 for external links, plain
+                                    // underlined text otherwise. External links are clickable
+                                    // natively via the terminal's OSC-8 support; internal cell
+                                    // links route through navigate (B5).
+                                    const ESC = String.fromCharCode(27);
+                                    const BEL = String.fromCharCode(7);
+                                    const inner = c.linkExternal
+                                        ? `${ESC}]8;;${cell}${BEL}${c.linkLabel}${ESC}]8;;${BEL}`
+                                        : c.linkLabel;
+                                    const cellClick = !c.linkExternal && cell.length > 0
+                                        ? () => ctx.navigate(cell)
+                                        : undefined;
+                                    return (_jsx("text", { attributes: 4 /* UNDERLINE */, fg: "#6688cc", ...(cellClick ? { onMouseDown: cellClick } : {}), children: inner }, c.key));
+                                }
+                                return _jsx("text", { children: cell }, c.key);
+                            })] }, row.id ?? ri));
+                }), node.pagination ? (() => {
+                    const pg = node.pagination;
+                    const totalPages = Math.max(1, Math.ceil(pg.totalRows / pg.pageSize));
+                    const from = pg.totalRows === 0 ? 0 : (pg.page - 1) * pg.pageSize + 1;
+                    const to = Math.min(pg.page * pg.pageSize, pg.totalRows);
+                    const go = (p) => ctx.onAction({
+                        name: pg.action.name,
+                        context: { ...(pg.action.context ?? {}), page: p },
+                    });
+                    const canPrev = pg.page > 1;
+                    const canNext = pg.page < totalPages;
+                    return (_jsxs("box", { flexDirection: "row", gap: 2, children: [_jsx("text", { fg: "#888888", children: `${from}–${to} of ${pg.totalRows}` }), _jsx("text", { fg: canPrev ? "#88aaff" : "#555555", ...(canPrev ? { onMouseDown: () => go(pg.page - 1) } : {}), children: "‹ Prev" }), _jsx("text", { fg: canNext ? "#88aaff" : "#555555", ...(canNext ? { onMouseDown: () => go(pg.page + 1) } : {}), children: "Next ›" })] }));
+                })() : null] }) }));
 }
 // ── minimum-viable text surface for the rest of the node set ───────────────
 // Same as B1 — text only, no interactivity. Full widgets land in B3/B4.
@@ -1202,6 +1278,10 @@ function UnsupportedView({ type }) {
 // test/conformance.tui.test.ts) invokes the components directly. Note that
 // the App component is hooks-free — focus state is passed via props with a
 // safe default — so the walker works without a React reconciler.
+/**
+ * @experimental Part of the experimental terminal target (see {@link TuiAdapter}).
+ * A static, non-mounting render path used by the cross-adapter conformance suite.
+ */
 export function renderTree(vm) {
     return _jsx(App, { vm: vm, onAction: () => { } });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ashley-shrok/viewmodel-shell",
-  "version": "0.10.0",
+  "version": "0.12.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.",
   "type": "module",
   "license": "MIT",

package/styles/default.css

@@ -28,12 +28,15 @@
   --vms-done-text:   #9090a0;
   --vms-error:       #c2453d;
   --vms-error-glow:  rgba(194, 69, 61, 0.10);
-  --vms-warning:       #a37510;
+  --vms-warning:       #8a630d;
   --vms-priority-high: #d76410;
   --vms-success:       #2da359;
   --vms-info:          #2277dd;
   --vms-radius:      10px;
   --vms-radius-sm:   6px;
+  --vms-image-small:   4rem;
+  --vms-image-medium:  8rem;
+  --vms-image-large:   16rem;
   --vms-font-body:   system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
   --vms-font-head:   system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
   --vms-font-mono:   ui-monospace, 'Cascadia Code', 'Fira Code', Menlo, Consolas, 'Liberation Mono', monospace;
@@ -458,6 +461,7 @@ select.vms-field__input  { cursor: pointer; padding-right: var(--vms-space-xl);
 .vms-text--muted         { color: var(--vms-text-muted); font-size: var(--vms-text-sm); }
 .vms-text--strikethrough { color: var(--vms-done-text); text-decoration: line-through; }
 .vms-text--error         { color: var(--vms-error); font-size: var(--vms-text-base); }
+.vms-text--warning       { color: var(--vms-warning); font-size: var(--vms-text-base); }
 .vms-text--pre           { font-family: var(--vms-font-mono); white-space: pre; }
 
 /* ── Link ── */
@@ -473,6 +477,15 @@ select.vms-field__input  { cursor: pointer; padding-right: var(--vms-space-xl);
 }
 .vms-link:hover { border-bottom-color: var(--vms-accent); }
 
+/* ── Image ── */
+.vms-image { max-width: 100%; height: auto; display: block; }
+.vms-image--small  { width: var(--vms-image-small); }
+.vms-image--medium { width: var(--vms-image-medium); }
+.vms-image--large  { width: var(--vms-image-large); }
+.vms-image--full   { width: 100%; }
+/* Avatars: square-crop to a circle (object-fit avoids distortion on non-square sources). */
+.vms-image--circle { border-radius: 50%; aspect-ratio: 1; object-fit: cover; }
+
 /* ── Progress ── */
 .vms-progress { height: 3px; background: var(--vms-surface-2); border-radius: 99px; overflow: hidden; }
 .vms-progress__bar { height: 100%; background: var(--vms-accent); border-radius: 99px; transition: width 0.3s ease; }
@@ -601,6 +614,30 @@ select.vms-field__input  { cursor: pointer; padding-right: var(--vms-space-xl);
 .vms-table__link { color: var(--vms-accent); text-decoration: none; }
 .vms-table__link:hover { text-decoration: underline; }
 
+/* Selection — leading checkbox column + selected-row tint. The tint derives
+   from --vms-accent via color-mix, so a custom :root theme recolors it
+   automatically (same pattern as the status variants above). Selected wins
+   over the clickable-hover background so a selected row stays legible. */
+.vms-table__th--select,
+.vms-table__td--select { width: 1%; white-space: nowrap; text-align: center; padding-right: 0; }
+.vms-table__select { accent-color: var(--vms-accent); cursor: pointer; }
+.vms-table__row--selected { background: color-mix(in srgb, var(--vms-accent) 12%, transparent); }
+.vms-table__row--selected.vms-table__row--clickable:hover { background: color-mix(in srgb, var(--vms-accent) 18%, transparent); }
+
+/* Pagination footer — range label + prev/next, separated from the table by a
+   hairline. Buttons reuse .vms-button styling; only sizing/disabled is added. */
+.vms-table__pagination {
+  display: flex;
+  align-items: center;
+  gap: var(--vms-space-sm);
+  padding-top: var(--vms-space-sm);
+  margin-top: var(--vms-space-xs);
+  border-top: 1px solid var(--vms-border);
+}
+.vms-table__pagination-range { color: var(--vms-text-muted); font-size: var(--vms-text-sm); margin-right: auto; }
+.vms-table__pagination-btn { padding: var(--vms-space-xs) var(--vms-space-sm); font-size: var(--vms-text-sm); }
+.vms-table__pagination-btn:disabled { opacity: 0.45; cursor: default; }
+
 /* ── Recommended error-banner pattern ──
    Apps typically render this from the `onError` callback. Not emitted by
    the framework; included here so apps can use the convention without

package/styles/themes/light-amber.css

@@ -13,7 +13,7 @@
   --vms-done-text:    #9090a0;
   --vms-error:        #c2453d;
   --vms-error-glow:   rgba(194, 69, 61, 0.10);
-  --vms-warning:      #c89610;
+  --vms-warning:      #8a630d;
   --vms-priority-high:#d76410;
   --vms-success:      #2da359;
   --vms-info:         #2277dd;

package/styles/themes/light-blue.css

@@ -13,7 +13,7 @@
   --vms-done-text:    #9090a0;
   --vms-error:        #c2453d;
   --vms-error-glow:   rgba(194, 69, 61, 0.10);
-  --vms-warning:      #c89610;
+  --vms-warning:      #8a630d;
   --vms-priority-high:#d76410;
   --vms-success:      #2da359;
   --vms-info:         #2277dd;

package/styles/themes/light-green.css

@@ -13,7 +13,7 @@
   --vms-done-text:    #9090a0;
   --vms-error:        #c2453d;
   --vms-error-glow:   rgba(194, 69, 61, 0.10);
-  --vms-warning:      #c89610;
+  --vms-warning:      #8a630d;
   --vms-priority-high:#d76410;
   --vms-success:      #2da359;
   --vms-info:         #2277dd;

package/styles/themes/light-purple.css

@@ -16,7 +16,7 @@
   --vms-done-text:    #9090a0;
   --vms-error:        #c2453d;
   --vms-error-glow:   rgba(194, 69, 61, 0.10);
-  --vms-warning:      #c89610;
+  --vms-warning:      #8a630d;
   --vms-priority-high:#d76410;
   --vms-success:      #2da359;
   --vms-info:         #2277dd;

package/styles/themes/light-rose.css

@@ -13,7 +13,7 @@
   --vms-done-text:    #9090a0;
   --vms-error:        #c2453d;
   --vms-error-glow:   rgba(194, 69, 61, 0.10);
-  --vms-warning:      #c89610;
+  --vms-warning:      #8a630d;
   --vms-priority-high:#d76410;
   --vms-success:      #2da359;
   --vms-info:         #2277dd;

package/styles/themes/light-teal.css

@@ -13,7 +13,7 @@
   --vms-done-text:    #9090a0;
   --vms-error:        #c2453d;
   --vms-error-glow:   rgba(194, 69, 61, 0.10);
-  --vms-warning:      #c89610;
+  --vms-warning:      #8a630d;
   --vms-priority-high:#d76410;
   --vms-success:      #2da359;
   --vms-info:         #2277dd;