@ashley-shrok/viewmodel-shell 0.9.0 → 0.11.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);
@@ -249,14 +250,12 @@ export class BrowserAdapter {
         form.className = `vms-form${n.layout && n.layout !== "stack" ? ` vms-form--${n.layout}` : ""}`;
         form.noValidate = true;
         this.kids(n.children, form, on);
-        const submit = document.createElement("button");
-        submit.type = "submit";
-        submit.className = "vms-button vms-button--primary";
-        submit.textContent = n.submitLabel ?? "Submit";
-        form.appendChild(submit);
-        form.addEventListener("submit", (e) => {
-            e.preventDefault();
-            const ctx = { ...(n.submitAction.context ?? {}) };
+        // 0.10.0 (#15) — harvest this form's current field values, merge into the
+        // given action's context, and dispatch. Factored out of the submit
+        // handler so both the default submit AND each buttons[] entry can call it
+        // with a DIFFERENT action carrying the SAME live field values.
+        const harvest = (base) => {
+            const ctx = { ...(base.context ?? {}) };
             const files = {};
             form.querySelectorAll("input:not([type=checkbox]):not([type=file]), textarea").forEach(el => { if (el.name)
                 ctx[el.name] = el.value; });
@@ -277,11 +276,43 @@ export class BrowserAdapter {
                 if (inp.name && inp.files?.[0])
                     files[inp.name] = inp.files[0];
             });
-            const action = { name: n.submitAction.name, context: ctx };
+            const action = { name: base.name, context: ctx };
             if (Object.keys(files).length > 0)
                 action.files = files;
             on(action);
-        });
+        };
+        // Default submit button + Enter-to-submit, only when submitAction is set.
+        // (0.10.0: submitAction is now optional — a buttons[]-only form renders
+        // no default button, and Enter does not submit at the form level.)
+        if (n.submitAction) {
+            const submitAction = n.submitAction;
+            const submit = document.createElement("button");
+            submit.type = "submit";
+            submit.className = "vms-button vms-button--primary";
+            submit.textContent = n.submitLabel ?? "Submit";
+            form.appendChild(submit);
+            form.addEventListener("submit", (e) => {
+                e.preventDefault();
+                harvest(submitAction);
+            });
+        }
+        else {
+            // No default submit — still neutralize implicit Enter submission so a
+            // single-field buttons[]-only form doesn't reload via native submit.
+            form.addEventListener("submit", (e) => e.preventDefault());
+        }
+        // 0.10.0 (#15) — multi-action buttons. Each renders through the normal
+        // button() path (so variant + pendingLabel work) but its onAction is
+        // wrapped to harvest the form first. We render them in a footer row so
+        // they group like the default submit.
+        if (n.buttons && n.buttons.length > 0) {
+            const row = document.createElement("div");
+            row.className = "vms-form__buttons";
+            const harvestOn = (action) => harvest(action);
+            for (const btn of n.buttons)
+                this.button(btn, row, harvestOn);
+            form.appendChild(row);
+        }
         parent.appendChild(form);
     }
     field(n, parent, on) {
@@ -539,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";

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;
@@ -68,10 +68,23 @@ export interface ListItemNode {
 }
 export interface FormNode {
     type: "form";
-    submitAction: ActionEvent;
+    /** The default submit action — renders an auto submit button + fires on
+     *  Enter in a text field. OPTIONAL since 0.10.0 (#15): omit it for a form
+     *  whose only triggers are `buttons[]`. When omitted, no default submit
+     *  button renders and Enter does not submit at the form level (a
+     *  FieldNode.action still fires per-field). */
+    submitAction?: ActionEvent;
     submitLabel?: string;
     /** Layout preset for the form's controls. Omitted or "stack" = fields stacked (current, no modifier class). "inline" = field row + submit on one line (add/search bar) — emits .vms-form--inline. Closed union (D-29). */
     layout?: "stack" | "inline";
+    /** Multi-action submit buttons (#15). Each is a full ButtonNode (so
+     *  `variant` + `pendingLabel` apply) that, on activation, HARVESTS this
+     *  form's current field values into its `action.context` and dispatches —
+     *  the same harvest the default submit performs, but carrying a different
+     *  action. Mirrors HTML's multiple submit buttons / `formaction`. A plain
+     *  ButtonNode placed in `children` keeps its no-harvest behavior; only
+     *  buttons in THIS slot harvest. */
+    buttons?: ButtonNode[];
     children: ViewNode[];
 }
 export interface FieldNode {
@@ -118,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";
@@ -127,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<{

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
@@ -1034,12 +1073,12 @@ function CopyButtonView({ node, ctx }) {
 // reads each from the adapter's fieldValues map (falling back to wire), and
 // dispatches submitAction with `{ [name]: value, ... }` merged into context.
 function FormView({ node, ctx }) {
-    // Snapshot the form for the closure — same-instance fine since the closure
-    // is recreated on every render (which is every server response).
-    const submitThisForm = () => {
-        const merged = {
-            ...(node.submitAction.context ?? {}),
-        };
+    // 0.10.0 (#15) — harvest this form's current field values, merge into the
+    // given action's context, and dispatch. Generalized from the single-submit
+    // closure so the default submit AND each buttons[] entry can call it with
+    // a DIFFERENT action carrying the SAME live field values.
+    const submitFormWith = (base) => {
+        const merged = { ...(base.context ?? {}) };
         const collect = (n) => {
             if (n.type === "field") {
                 const wireValue = n.value ?? "";
@@ -1058,17 +1097,23 @@ function FormView({ node, ctx }) {
         };
         for (const child of node.children)
             collect(child);
-        ctx.onAction({ name: node.submitAction.name, context: merged });
+        ctx.onAction({ name: base.name, context: merged });
     };
+    // Enter-in-a-field submits the default action — only wired when present.
+    const submitAction = node.submitAction;
     const childCtx = {
         ...ctx,
         isTopLevel: false,
-        submitForm: submitThisForm,
+        submitForm: submitAction ? () => submitFormWith(submitAction) : null,
     };
+    // buttons[] (#15) render through ButtonView so variant + pendingLabel work;
+    // their onAction is wrapped to harvest the form first. pendingButtonKey
+    // plumbing (0.8.0) flows through ctx unchanged.
+    const buttonCtx = { ...childCtx, onAction: submitFormWith };
     // Layout preset on form: "stack" (default — fields stacked) or "inline"
     // (field row + submit on one line, the add-bar/search-bar pattern).
     const isInline = node.layout === "inline";
-    return (_jsxs("box", { flexDirection: isInline ? "row" : "column", gap: 1, children: [node.children.map((child, i) => renderNode(child, childCtx, i)), _jsxs("text", { attributes: 1 /* BOLD */, children: ["[ ", node.submitLabel ?? "Submit", " ]"] })] }));
+    return (_jsxs("box", { flexDirection: isInline ? "row" : "column", gap: 1, children: [node.children.map((child, i) => renderNode(child, childCtx, i)), submitAction != null ? (_jsxs("text", { attributes: 1 /* BOLD */, children: ["[ ", node.submitLabel ?? "Submit", " ]"] })) : null, node.buttons && node.buttons.length > 0 ? (_jsx("box", { flexDirection: "row", gap: 2, children: node.buttons.map((btn, i) => (_jsx(ButtonView, { node: btn, ctx: buttonCtx }, `b${i}`))) })) : null] }));
 }
 // ── field ─────────────────────────────────────────────────────────────────
 // Real OpenTUI input/textarea/select wired to the adapter's field state.
@@ -1196,6 +1241,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.9.0",
+  "version": "0.11.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;
@@ -231,6 +234,16 @@ body {
   flex-wrap: wrap;
 }
 .vms-form--inline > .vms-field { flex: 1 1 12rem; }
+/* Multi-action submit buttons row (0.10.0 / #15) — groups the form's
+   buttons[] entries on one line, like a dialog action bar. align-self
+   flex-start keeps the row from stretching full-width in the stacked form. */
+.vms-form__buttons {
+  display: flex;
+  flex-direction: row;
+  gap: var(--vms-space-sm);
+  align-self: flex-start;
+  flex-wrap: wrap;
+}
 .vms-field { display: flex; flex-direction: column; gap: var(--vms-space-2xs); }
 .vms-field__label { font-size: var(--vms-text-sm); color: var(--vms-text-muted); }
 .vms-field__input {
@@ -448,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 ── */
@@ -463,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; }

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;