npm - @ashley-shrok/viewmodel-shell - Versions diffs - 3.4.0 → 3.6.0 - Mend

@ashley-shrok/viewmodel-shell 3.4.0 → 3.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/agent-skill.md CHANGED Viewed

@@ -91,7 +91,8 @@ Optional success-path fields, which may appear alone or alongside `vm`/`state`:
 { "sideEffects": [
   { "type": "set-local-storage", "key": "auth_jwt", "value": "eyJ..." },
   { "type": "set-session-storage", "key": "draft_id", "value": "42" },
-  { "type": "download", "url": "/api/invoices/42/pdf", "filename": "invoice-42.pdf" }
+  { "type": "download", "url": "/api/invoices/42/pdf", "filename": "invoice-42.pdf" },
+  { "type": "toast", "message": "Ticket #4012 closed.", "tone": "success" }
 ] }
 ```
@@ -100,6 +101,7 @@ Optional success-path fields, which may appear alone or alongside `vm`/`state`:
 | `set-local-storage` | Write `key`/`value` to platform localStorage (or your agent's equivalent persistent store). |
 | `set-session-storage` | Same as above for session-scoped storage. |
 | `download` | Fetch `url` (re-presenting your auth headers — see *Auth*) and save the bytes. Filename precedence: `Content-Disposition` > side-effect `filename` > URL basename > `"download"`. |
+| `toast` | Show a transient confirmation: `message` (required) + optional `tone` (`danger`\|`warning`\|`success`\|`info`) + `durationMs`. A UX nicety — **fail-quiet**: an agent/adapter with no toast surface simply ignores it (nothing to persist or act on), so it carries no state and needs no acknowledgement. |
 **Forward-compat rule — silently ignore unknown verbs.** A future minor release may add new verbs. If you see a `type` you do not recognize, skip it; do not error. Honor or ignore per your policy.

package/dist/browser.d.ts CHANGED Viewed

@@ -12,6 +12,17 @@ export declare class BrowserAdapter implements Adapter {
     storage(scope: "local" | "session", key: string, value: string): void;
     saveFile(data: Blob, filename: string, _contentType: string): void;
     setBusy(active: boolean): void;
+    /** Transient confirmation toast. Lazily creates/reuses a single fixed-corner
+     *  host region (.vms-toast-region) appended to <body> so toasts stack and
+     *  survive the container's innerHTML wipe on each render(); appends a
+     *  .vms-toast element (+ tone modifier) and auto-removes it after
+     *  durationMs (default 4000), with a brief fade-out. This is the ONLY place
+     *  toast DOM lives — core stays platform-agnostic (it just calls this verb).
+     *  Fail-quiet by absence is the core's concern (it optional-chains the call). */
+    toast(message: string, opts?: {
+        tone?: string;
+        durationMs?: number;
+    }): void;
     private unloadHandler;
     setPreventUnload(active: boolean): void;
     transport(input: string, init: {
@@ -96,4 +107,11 @@ export declare class BrowserAdapter implements Adapter {
      *  concept. */
     private table;
     private copyButton;
+    /** EmptyStateNode — a centered "nothing here" block: a heading, an optional
+     *  message, then the optional CTA ButtonNode (rendered via the shared button
+     *  renderer so it dispatches like any other button). */
+    private emptyState;
+    /** BadgeNode — a compact inline status pill / count. Leaf node: label text +
+     *  tone/emphasis modifier classes. */
+    private badge;
 }

package/dist/browser.js CHANGED Viewed

@@ -162,6 +162,38 @@ export class BrowserAdapter {
     setBusy(active) {
         this.container.classList.toggle("vms-busy", active);
     }
+    /** Transient confirmation toast. Lazily creates/reuses a single fixed-corner
+     *  host region (.vms-toast-region) appended to <body> so toasts stack and
+     *  survive the container's innerHTML wipe on each render(); appends a
+     *  .vms-toast element (+ tone modifier) and auto-removes it after
+     *  durationMs (default 4000), with a brief fade-out. This is the ONLY place
+     *  toast DOM lives — core stays platform-agnostic (it just calls this verb).
+     *  Fail-quiet by absence is the core's concern (it optional-chains the call). */
+    toast(message, opts) {
+        let region = document.querySelector(".vms-toast-region");
+        if (!region) {
+            region = document.createElement("div");
+            region.className = "vms-toast-region";
+            document.body.appendChild(region);
+        }
+        const el = document.createElement("div");
+        el.className = `vms-toast${opts?.tone ? ` vms-toast--${opts.tone}` : ""}`;
+        el.setAttribute("role", "status");
+        el.setAttribute("aria-live", "polite");
+        el.textContent = message;
+        region.appendChild(el);
+        const duration = opts?.durationMs ?? 4000;
+        setTimeout(() => {
+            el.classList.add("vms-toast--leaving");
+            // Remove after the fade-out transition; a short fixed delay keeps it
+            // simple (no transitionend bookkeeping). Clean up the region if it empties.
+            setTimeout(() => {
+                el.remove();
+                if (region && region.childElementCount === 0)
+                    region.remove();
+            }, 200);
+        }, duration);
+    }
     unloadHandler = null;
     setPreventUnload(active) {
         if (active && this.unloadHandler == null) {
@@ -240,6 +272,8 @@ export class BrowserAdapter {
             case "copy-button": return this.copyButton(n, parent);
             case "divider": return this.divider(n, parent);
             case "fits": return this.fits(n, parent, on);
+            case "empty-state": return this.emptyState(n, parent, on);
+            case "badge": return this.badge(n, parent);
             default: {
                 // Fail loud, not silent (AGENTS.md: "Nothing important fails quietly").
                 // Runtime trees are server-controlled JSON, so an unknown/forward-version
@@ -259,7 +293,7 @@ export class BrowserAdapter {
     }
     page(n, parent, on) {
         const el = document.createElement("div");
-        el.className = `vms-page${n.density === "compact" ? " vms-page--compact" : ""}${n.layout && n.layout !== "stack" ? ` vms-page--${n.layout}` : ""}${n.width ? ` vms-page--${n.width}` : ""}${n.arrange ? ` vms-arrange--${n.arrange}` : ""}${n.align ? ` vms-align--${n.align}` : ""}${n.threshold ? ` vms-switch--${n.threshold}` : ""}${n.limit ? ` vms-switch-limit--${n.limit}` : ""}${n.minItem ? ` vms-cards-min--${n.minItem}` : ""}`;
+        el.className = `vms-page${n.density === "compact" ? " vms-page--compact" : ""}${n.layout && n.layout !== "stack" ? ` vms-page--${n.layout}` : ""}${n.fill === true ? " vms-page--fill" : ""}${n.width ? ` vms-page--${n.width}` : ""}${n.arrange ? ` vms-arrange--${n.arrange}` : ""}${n.align ? ` vms-align--${n.align}` : ""}${n.threshold ? ` vms-switch--${n.threshold}` : ""}${n.limit ? ` vms-switch-limit--${n.limit}` : ""}${n.minItem ? ` vms-cards-min--${n.minItem}` : ""}`;
         if (n.title) {
             const h = document.createElement("h1");
             h.className = "vms-page__title";
@@ -371,7 +405,7 @@ export class BrowserAdapter {
             this.sectionKeyCounter.set(baseKey, ordinal + 1);
             const finalKey = `${baseKey}:${ordinal}`;
             const el = document.createElement("details");
-            el.className = `vms-section vms-section--collapsible${n.variant === "card" ? " vms-section--card" : ""}${n.tone ? ` vms-section--${n.tone}` : ""}${n.layout && n.layout !== "stack" ? ` vms-section--${n.layout}` : ""}${n.arrange ? ` vms-arrange--${n.arrange}` : ""}${n.align ? ` vms-align--${n.align}` : ""}${n.threshold ? ` vms-switch--${n.threshold}` : ""}${n.limit ? ` vms-switch-limit--${n.limit}` : ""}${n.minItem ? ` vms-cards-min--${n.minItem}` : ""}${n.alignSelf ? ` vms-self--${n.alignSelf}` : ""}${n.maxWidth ? ` vms-maxw--${n.maxWidth}` : ""}`;
+            el.className = `vms-section vms-section--collapsible${n.variant === "card" ? " vms-section--card" : ""}${n.tone ? ` vms-section--${n.tone}` : ""}${n.layout && n.layout !== "stack" ? ` vms-section--${n.layout}` : ""}${n.fill === true ? " vms-section--fill" : ""}${n.arrange ? ` vms-arrange--${n.arrange}` : ""}${n.align ? ` vms-align--${n.align}` : ""}${n.threshold ? ` vms-switch--${n.threshold}` : ""}${n.limit ? ` vms-switch-limit--${n.limit}` : ""}${n.minItem ? ` vms-cards-min--${n.minItem}` : ""}${n.alignSelf ? ` vms-self--${n.alignSelf}` : ""}${n.maxWidth ? ` vms-maxw--${n.maxWidth}` : ""}`;
             el.dataset.sectionKey = finalKey;
             // Initial render is always closed — the post-render restore loop in
             // render() re-applies `open=true` for keys the user had open before.
@@ -395,7 +429,7 @@ export class BrowserAdapter {
         // action — see validateSectionAction in server.ts.
         if (n.link) {
             const a = document.createElement("a");
-            a.className = `vms-section vms-section--linked${n.variant === "card" ? " vms-section--card" : ""}${n.tone ? ` vms-section--${n.tone}` : ""}${n.layout && n.layout !== "stack" ? ` vms-section--${n.layout}` : ""}${n.arrange ? ` vms-arrange--${n.arrange}` : ""}${n.align ? ` vms-align--${n.align}` : ""}${n.threshold ? ` vms-switch--${n.threshold}` : ""}${n.limit ? ` vms-switch-limit--${n.limit}` : ""}${n.minItem ? ` vms-cards-min--${n.minItem}` : ""}${n.alignSelf ? ` vms-self--${n.alignSelf}` : ""}${n.maxWidth ? ` vms-maxw--${n.maxWidth}` : ""}`;
+            a.className = `vms-section vms-section--linked${n.variant === "card" ? " vms-section--card" : ""}${n.tone ? ` vms-section--${n.tone}` : ""}${n.layout && n.layout !== "stack" ? ` vms-section--${n.layout}` : ""}${n.fill === true ? " vms-section--fill" : ""}${n.arrange ? ` vms-arrange--${n.arrange}` : ""}${n.align ? ` vms-align--${n.align}` : ""}${n.threshold ? ` vms-switch--${n.threshold}` : ""}${n.limit ? ` vms-switch-limit--${n.limit}` : ""}${n.minItem ? ` vms-cards-min--${n.minItem}` : ""}${n.alignSelf ? ` vms-self--${n.alignSelf}` : ""}${n.maxWidth ? ` vms-maxw--${n.maxWidth}` : ""}`;
             a.href = n.link.url;
             // Mirror LinkNode's external-attribute pattern (browser.ts ~line 666)
             // byte-for-byte: target=_blank + rel=noopener noreferrer when external.
@@ -439,7 +473,7 @@ export class BrowserAdapter {
             return;
         }
         const el = document.createElement("section");
-        el.className = `vms-section${n.variant === "card" ? " vms-section--card" : ""}${n.tone ? ` vms-section--${n.tone}` : ""}${n.layout && n.layout !== "stack" ? ` vms-section--${n.layout}` : ""}${n.arrange ? ` vms-arrange--${n.arrange}` : ""}${n.align ? ` vms-align--${n.align}` : ""}${n.threshold ? ` vms-switch--${n.threshold}` : ""}${n.limit ? ` vms-switch-limit--${n.limit}` : ""}${n.minItem ? ` vms-cards-min--${n.minItem}` : ""}${n.alignSelf ? ` vms-self--${n.alignSelf}` : ""}${n.maxWidth ? ` vms-maxw--${n.maxWidth}` : ""}${n.action ? " vms-section--clickable" : ""}`;
+        el.className = `vms-section${n.variant === "card" ? " vms-section--card" : ""}${n.tone ? ` vms-section--${n.tone}` : ""}${n.layout && n.layout !== "stack" ? ` vms-section--${n.layout}` : ""}${n.fill === true ? " vms-section--fill" : ""}${n.arrange ? ` vms-arrange--${n.arrange}` : ""}${n.align ? ` vms-align--${n.align}` : ""}${n.threshold ? ` vms-switch--${n.threshold}` : ""}${n.limit ? ` vms-switch-limit--${n.limit}` : ""}${n.minItem ? ` vms-cards-min--${n.minItem}` : ""}${n.alignSelf ? ` vms-self--${n.alignSelf}` : ""}${n.maxWidth ? ` vms-maxw--${n.maxWidth}` : ""}${n.action ? " vms-section--clickable" : ""}`;
         if (n.heading) {
             const h = document.createElement("h2");
             h.className = "vms-section__heading";
@@ -1293,4 +1327,32 @@ export class BrowserAdapter {
         });
         parent.appendChild(btn);
     }
+    /** EmptyStateNode — a centered "nothing here" block: a heading, an optional
+     *  message, then the optional CTA ButtonNode (rendered via the shared button
+     *  renderer so it dispatches like any other button). */
+    emptyState(n, parent, on) {
+        const el = document.createElement("div");
+        el.className = "vms-empty-state";
+        const heading = document.createElement("div");
+        heading.className = "vms-empty-state__heading";
+        heading.textContent = n.heading;
+        el.appendChild(heading);
+        if (n.message != null && n.message !== "") {
+            const msg = document.createElement("div");
+            msg.className = "vms-empty-state__message";
+            msg.textContent = n.message;
+            el.appendChild(msg);
+        }
+        if (n.action)
+            this.button(n.action, el, on);
+        parent.appendChild(el);
+    }
+    /** BadgeNode — a compact inline status pill / count. Leaf node: label text +
+     *  tone/emphasis modifier classes. */
+    badge(n, parent) {
+        const span = document.createElement("span");
+        span.className = `vms-badge${n.tone ? ` vms-badge--${n.tone}` : ""}${n.emphasis ? ` vms-badge--${n.emphasis}` : ""}`;
+        span.textContent = n.label;
+        parent.appendChild(span);
+    }
 }

package/dist/index.d.ts CHANGED Viewed

@@ -62,8 +62,20 @@ export interface Adapter {
      *  none), so a rapid checkbox click during an in-flight round-trip never
      *  visually flips the box. Fail-quiet by absence (TUI has no equivalent). */
     setBusy?(active: boolean): void;
+    /** Show a transient confirmation toast, driven by a `{ type: "toast" }`
+     *  ShellSideEffect. `BrowserAdapter` stacks toasts in a single fixed-corner
+     *  host region and auto-dismisses each after `opts.durationMs` (default
+     *  ~4000ms). FAIL-QUIET BY ABSENCE — modeled on setPreventUnload/setBusy,
+     *  NOT on navigate/storage/saveFile: a dropped toast is a missed UX nicety,
+     *  never a correctness/security bug, so the core MUST NOT call failCapability
+     *  when this verb is absent (non-browser targets like the TUI simply have no
+     *  toast surface and the effect is a no-op). */
+    toast?(message: string, opts?: {
+        tone?: string;
+        durationMs?: number;
+    }): void;
 }
-export type ViewNode = PageNode | SectionNode | ListNode | ListItemNode | FormNode | FieldNode | CheckboxNode | ButtonNode | TextNode | LinkNode | ImageNode | StatBarNode | TabsNode | ProgressNode | ModalNode | TableNode | CopyButtonNode | DividerNode | FitsNode;
+export type ViewNode = PageNode | SectionNode | ListNode | ListItemNode | FormNode | FieldNode | CheckboxNode | ButtonNode | TextNode | LinkNode | ImageNode | StatBarNode | TabsNode | ProgressNode | ModalNode | TableNode | CopyButtonNode | DividerNode | FitsNode | EmptyStateNode | BadgeNode;
 export interface PageNode {
     type: "page";
     title?: string;
@@ -71,6 +83,8 @@ export interface PageNode {
     density?: "comfortable" | "compact";
     /** Layout preset arranging direct children. Omitted or "stack" = current vertical flow (no modifier class). "split" (equal 2-up), "cards" (uniform grid), "sidebar" (thin + wide app shell), "row" (left-aligned wrapping horizontal row; items hug content), "switcher" (N equal items flipping all-row ↔ all-stack atomically at a content-width `threshold` — the negative-flex-basis primitive a grid cannot express; distinct from `cards` auto-fit which passes through intermediate column counts) emit .vms-page--{value}. Closed union (D-01/D-02; sidebar D-28; row D-30; switcher SWITCH-01). */
     layout?: "stack" | "split" | "cards" | "sidebar" | "row" | "switcher";
+    /** When true the page fills the viewport height (`height:100dvh`) so a `fill` section inside it can take the leftover space and scroll internally — the full-height app-shell axis (a pinned footer/header with an internally-scrolling body, the Flutter Column+Expanded mechanism). Meant to pair with a `SectionNode.fill` child, which becomes the `flex:1 1 auto; min-height:0; overflow-y:auto` region. Absent/false = normal document flow (byte-identical to today). Orthogonal to `layout`. */
+    fill?: boolean;
     /** Page-shell max-width override. Omitted = framework default cap (`--vms-page-max`, 1080px). "wide" = `--vms-page-max-wide` (1440px default), for data-heavy pages with wide tables. "full" = uncapped (max-width: none), for full-bleed dashboards. TUI ignores this (terminals fill naturally). Closed union (D-13 / issue #13). */
     width?: "wide" | "full";
     /** Main-axis arrangement for `layout:"row"` (the cluster primitive) — maps to `justify-content`. Omitted = no class → the row default (`flex-start`, left-pack) holds = byte-identical to today. Closed union copied verbatim from Jetpack Compose `Arrangement` ∩ Flutter `MainAxisAlignment` (ALIGN-01). Emits .vms-arrange--{value}. */
@@ -94,6 +108,8 @@ export interface SectionNode {
     tone?: "danger" | "warning" | "success" | "info";
     /** Layout preset arranging direct children. Omitted or "stack" = current vertical flow (no modifier class). "split" (equal 2-up), "cards" (uniform grid), "sidebar" (thin + wide app shell), "row" (left-aligned wrapping horizontal row; items hug content), "switcher" (N equal items flipping all-row ↔ all-stack atomically at a content-width `threshold` — the negative-flex-basis primitive a grid cannot express; distinct from `cards` auto-fit which passes through intermediate column counts) emit .vms-section--{value}. Closed union (D-01/D-02; sidebar D-28; row D-30; switcher SWITCH-01). */
     layout?: "stack" | "split" | "cards" | "sidebar" | "row" | "switcher";
+    /** When true (and inside a `fill` page) this section takes the remaining column height and scrolls internally (`flex:1 1 auto; min-height:0; overflow-y:auto`) — the body region of a full-height app shell (e.g. a chat transcript above a pinned composer). Orthogonal to `layout` — a fill section still arranges its own children via `layout`. Outside a `fill` page it's a harmless no-op (the modifier class is inert without a `100dvh` parent). Absent/false = byte-identical to today. */
+    fill?: boolean;
     /** Main-axis arrangement for `layout:"row"` (the cluster primitive) — maps to `justify-content`. Omitted = no class → the row default (`flex-start`, left-pack) holds = byte-identical to today. Closed union copied verbatim from Jetpack Compose `Arrangement` ∩ Flutter `MainAxisAlignment` (ALIGN-01). Emits .vms-arrange--{value}. */
     arrange?: "start" | "center" | "end" | "space-between" | "space-around" | "space-evenly";
     /** Cross-axis alignment for `layout:"row"` (the cluster primitive) — maps to `align-items`. Omitted = no class → the row default (`center`) holds = byte-identical to today. Closed union copied verbatim from Flutter `CrossAxisAlignment` (ALIGN-02). Emits .vms-align--{value}. */
@@ -488,6 +504,47 @@ export interface CopyButtonNode {
      *  = content-width (the default hug). Orthogonal to emphasis/tone/size. */
     width?: "auto" | "full";
 }
+/**
+ * A first-class "nothing here" presentation — the empty-state primitive
+ * (MUI/Ant `<Empty>`, the standard zero-data placeholder). A centered block
+ * with a required heading, an optional supporting message, and an optional
+ * call-to-action ButtonNode (e.g. "Create your first ticket"). No icon field —
+ * the framework ships no icon set.
+ *
+ * The `action` ButtonNode carries a real action name and is a dispatch-bearing
+ * descendant, so EVERY tree-walk (action-name uniqueness collector, section
+ * shape validator) descends into it — exactly like `modal.footer` / `fits`
+ * candidates / `section.action`. A missed walk would silently exempt the CTA
+ * from the one-name-one-operation rule.
+ */
+export interface EmptyStateNode {
+    type: "empty-state";
+    /** The primary line — what's missing / what to do. Required. */
+    heading: string;
+    /** Optional supporting line below the heading. */
+    message?: string;
+    /** Optional call-to-action button (e.g. "Add the first item"). */
+    action?: ButtonNode;
+}
+/**
+ * A compact status pill / count — the badge primitive (MUI/Ant `<Badge>`,
+ * `<Tag>`). A leaf inline node (no children, no action) for a short label or
+ * count that appears inside text/section/list/table contexts. Appearance is
+ * the universal `tone` (semantic color) + `emphasis` (filled vs outline) axes,
+ * matching the rest of the framework's appearance vocabulary.
+ */
+export interface BadgeNode {
+    type: "badge";
+    /** The pill text — a short label or count (e.g. "New", "3", "Beta"). */
+    label: string;
+    /** Semantic intent/severity — the universal status tone axis. Emits
+     *  .vms-badge--{tone}. Omitted = neutral. Closed union. */
+    tone?: "danger" | "warning" | "success" | "info";
+    /** Visual weight — `primary` = filled solid tone, `secondary` = outline.
+     *  Mirrors ButtonNode's emphasis semantics. Emits .vms-badge--{emphasis}.
+     *  Omitted = the default filled tint. Closed union. */
+    emphasis?: "primary" | "secondary";
+}
 /**
  * The SwiftUI `ViewThatFits` port. The renderer picks the FIRST child whose
  * intrinsic size FITS the available container (no axis overflow), else the next,
@@ -563,7 +620,7 @@ export interface ShellOptions {
     pollInterval?: number;
 }
 export interface ShellSideEffect {
-    /** "set-local-storage" | "set-session-storage" | "download" — unknown types are silently ignored. */
+    /** "set-local-storage" | "set-session-storage" | "download" | "toast" — unknown types are silently ignored. */
     type: string;
     /** For "set-local-storage" / "set-session-storage": the storage key. */
     key?: string;
@@ -574,6 +631,13 @@ export interface ShellSideEffect {
     /** For "download": optional filename hint. Response Content-Disposition wins
      *  when present; this is the fallback before the URL basename. */
     filename?: string;
+    /** For "toast": the text shown in the transient confirmation. Required for a
+     *  toast effect (the shell guards `message != null` before routing). */
+    message?: string;
+    /** For "toast": optional semantic tone — "danger" | "warning" | "success" | "info". */
+    tone?: string;
+    /** For "toast": optional auto-dismiss delay in ms (adapter default ~4000). */
+    durationMs?: number;
 }
 /** One entry in the structured error payload returned on `ok: false`. */
 export interface ErrorEntry {

package/dist/index.js CHANGED Viewed

@@ -290,6 +290,16 @@ export class ViewModelShell {
                 // storage, and a slow download MUST NOT delay the user-visible update.
                 void this.download(effect.url, effect.filename);
             }
+            else if (effect.type === "toast" && effect.message != null) {
+                // FAIL-QUIET (cf. setPreventUnload/setBusy): a toast is a UX nicety,
+                // not a correctness/security guarantee, so an adapter without the
+                // capability simply drops it — NO failCapability, no onError. The
+                // optional-chaining call is the entire contract.
+                adapter.toast?.(effect.message, {
+                    tone: effect.tone,
+                    durationMs: effect.durationMs,
+                });
+            }
         }
         // 0.14.0 — apply the unload guard before the redirect/render branch so it's
         // in place (or cleared) consistently across both branches. A server that

package/dist/server.d.ts CHANGED Viewed

@@ -87,6 +87,14 @@ export declare const shellSideEffect: {
      *  The conditional spread keeps `filename` ABSENT (not undefined) on the
      *  JSON wire, matching the .NET WhenWritingNull null-omission contract. */
     download: (url: string, filename?: string) => ShellSideEffect;
+    /** Transient confirmation toast (a UX nicety, fail-quiet by absence — see
+     *  Adapter.toast). `message` is required; `tone`/`durationMs` are optional and
+     *  kept ABSENT (not undefined) from the JSON wire via conditional spread,
+     *  matching the .NET WhenWritingNull null-omission contract. */
+    toast: (message: string, opts?: {
+        tone?: string;
+        durationMs?: number;
+    }) => ShellSideEffect;
 };
 /**
  * Mount the canonical VMS agent skill markdown as an HTTP handler.

package/dist/server.js CHANGED Viewed

@@ -190,8 +190,18 @@ function collectActions(node, enclosingForm, out) {
                 collectActions(child, enclosingForm, out);
             return;
         }
+        case "empty-state": {
+            // EmptyStateNode.action is an optional ButtonNode carrying a real action
+            // name. It is a dispatch-bearing descendant, so the uniqueness collector
+            // MUST descend into it — otherwise the CTA is silently exempt from the
+            // one-name-one-operation rule (the 3.3.0 missed-walk failure class).
+            const es = node;
+            if (es.action)
+                collectActions(es.action, enclosingForm, out);
+            return;
+        }
         // Nodes with no dispatch-bearing actions of their own:
-        //   text, link, image, stat-bar, progress, copy-button
+        //   text, link, image, stat-bar, progress, copy-button, badge
         default:
             return;
     }
@@ -346,9 +356,18 @@ function walkForSectionAction(node, outerInteractive) {
                 walkForSectionAction(child, outerInteractive);
             return;
         }
+        case "empty-state": {
+            // EmptyStateNode.action is a ButtonNode (no SectionNode descendants), but
+            // descend for consistency with every other walk so a future shape can't
+            // slip an interactive section past this validator.
+            const es = node;
+            if (es.action)
+                walkForSectionAction(es.action, outerInteractive);
+            return;
+        }
         // Leaf-like nodes (field, checkbox, button, text, link, image, stat-bar,
-        // tabs, progress, table, copy-button) carry no SectionNode descendants —
-        // TableNode rows hold strings + per-row controls, not sections.
+        // tabs, progress, table, copy-button, badge) carry no SectionNode
+        // descendants — TableNode rows hold strings + per-row controls, not sections.
         default:
             return;
     }
@@ -427,6 +446,16 @@ export const shellSideEffect = {
      *  The conditional spread keeps `filename` ABSENT (not undefined) on the
      *  JSON wire, matching the .NET WhenWritingNull null-omission contract. */
     download: (url, filename) => ({ type: "download", url, ...(filename != null ? { filename } : {}) }),
+    /** Transient confirmation toast (a UX nicety, fail-quiet by absence — see
+     *  Adapter.toast). `message` is required; `tone`/`durationMs` are optional and
+     *  kept ABSENT (not undefined) from the JSON wire via conditional spread,
+     *  matching the .NET WhenWritingNull null-omission contract. */
+    toast: (message, opts) => ({
+        type: "toast",
+        message,
+        ...(opts?.tone != null ? { tone: opts.tone } : {}),
+        ...(opts?.durationMs != null ? { durationMs: opts.durationMs } : {}),
+    }),
 };
 // ─── Canonical agent skill mount helper (1.6.0 / 1.5.0) ──────────────────────
 /**

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@ashley-shrok/viewmodel-shell",
-  "version": "3.4.0",
+  "version": "3.6.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",
@@ -26,7 +26,7 @@
     "LICENSE"
   ],
   "bin": {
-    "vms-tui": "./dist/tui-cli.js"
+    "vms-tui": "dist/tui-cli.js"
   },
   "scripts": {
     "build": "tsc -b tsconfig.tui.json",

package/styles/default.css CHANGED Viewed

@@ -144,6 +144,17 @@ body {
 .vms-page--wide { max-width: var(--vms-page-max-wide); }
 .vms-page--full { max-width: none; }
+/* ── Fill / full-height app-shell axis ──
+   `.vms-page--fill` makes the page fill the viewport height so a `.vms-section--fill`
+   child can claim the leftover column height and scroll internally (the
+   pinned-footer/header + internally-scrolling body shell — Flutter Column+Expanded).
+   `.vms-section--fill` is the Expanded region: flex:1 → take remaining height,
+   min-height:0 → allow the flex child to shrink below content so overflow scrolls
+   instead of pushing siblings off-screen, overflow-y:auto → scroll internally.
+   Orthogonal to layout; outside a fill page the section rule is an inert no-op. */
+.vms-page--fill { height: 100dvh; }
+.vms-section--fill { flex: 1 1 auto; min-height: 0; overflow-y: auto; }
 /* ── Section ── */
 .vms-section { display: flex; flex-direction: column; gap: var(--vms-space-sm); }
 .vms-section__heading {
@@ -977,3 +988,117 @@ select.vms-field__input  { cursor: pointer; padding-right: var(--vms-space-xl);
   cursor: pointer;
   font-size: var(--vms-text-lg);
 }
+/* ── Toast (side-effect-driven transient confirmation) ──
+   The BrowserAdapter lazily creates ONE .vms-toast-region pinned to the
+   bottom-right corner and stacks .vms-toast elements into it; each auto-removes
+   after its durationMs with a brief fade. The region is click-through
+   (pointer-events:none) so it never blocks the UI under it; individual toasts
+   re-enable pointer events for their own content. Framework-owned styling —
+   this is the framework owning its presentation, not app CSS. */
+.vms-toast-region {
+  position: fixed;
+  bottom: var(--vms-space-md);
+  right: var(--vms-space-md);
+  z-index: 1100; /* above .vms-modal-backdrop (1000) */
+  display: flex;
+  flex-direction: column;
+  gap: var(--vms-space-xs);
+  align-items: flex-end;
+  pointer-events: none;
+  max-width: min(24rem, calc(100vw - 2 * var(--vms-space-md)));
+}
+.vms-toast {
+  pointer-events: auto;
+  /* Neutral toast = high-contrast inverted chip (the snackbar pattern): the
+     theme's text color as the surface, the theme's surface as the text. This
+     stands clear of the page background it sits on in EITHER theme — a
+     surface-colored toast was nearly invisible against the page surface. */
+  background: var(--vms-text);
+  color: var(--vms-surface);
+  border: 1px solid transparent;
+  border-radius: var(--vms-radius);
+  font-size: var(--vms-text-base);
+  font-weight: 500;
+  padding: var(--vms-space-sm) var(--vms-space-md);
+  box-shadow: 0 6px 22px rgba(0, 0, 0, 0.30);
+  opacity: 1;
+  transition: opacity var(--vms-t), transform var(--vms-t);
+}
+/* tone — a FULLY filled chip in the status color (not a thin accent rail), so
+   an important toast (especially danger) is impossible to miss. error/warning
+   are dark enough for white body text to clear WCAG-AA on their pure tokens;
+   success/info are deepened (color-mix w/ black) so white at 14px also clears
+   4.5:1 (their pure tokens sit at 3.2 / 4.4:1). */
+.vms-toast--danger  { background: var(--vms-error);   color: #fff; }
+.vms-toast--warning { background: var(--vms-warning); color: #fff; }
+.vms-toast--success { background: color-mix(in srgb, var(--vms-success) 80%, #000); color: #fff; }
+.vms-toast--info    { background: color-mix(in srgb, var(--vms-info) 88%, #000);    color: #fff; }
+/* fade-out applied just before removal. */
+.vms-toast--leaving { opacity: 0; transform: translateY(0.25rem); }
+/* ── Empty state (first-class "nothing here" presentation) ──
+   A centered block: heading, optional message, optional CTA button. */
+.vms-empty-state {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: var(--vms-space-sm);
+  text-align: center;
+  padding: var(--vms-space-xl) var(--vms-space-md);
+  color: var(--vms-text-muted);
+}
+.vms-empty-state__heading {
+  font-size: var(--vms-text-lg);
+  font-weight: 600;
+  color: var(--vms-text);
+}
+.vms-empty-state__message {
+  font-size: var(--vms-text-base);
+  color: var(--vms-text-muted);
+  max-width: min(40ch, 100%);
+}
+/* The CTA button inside an empty state centers (override the button's default
+   align-self:flex-start) so it sits under the centered heading/message. */
+.vms-empty-state .vms-button { align-self: center; }
+/* ── Badge (compact inline status pill / count) ──
+   Leaf inline element. Default = neutral filled tint; tone recolors it; emphasis
+   switches between a solid fill (primary) and an outline (secondary). */
+.vms-badge {
+  --_badge-tone: var(--vms-text-muted);
+  display: inline-flex;
+  align-items: center;
+  /* Center the pill on the surrounding text instead of baselining it (an
+     inline-flex pill otherwise hangs below the baseline of adjacent text). */
+  vertical-align: middle;
+  gap: var(--vms-space-2xs);
+  font-size: var(--vms-text-xs);
+  font-weight: 600;
+  line-height: 1;
+  padding: 0.2em 0.6em;
+  border-radius: 999px;
+  white-space: nowrap;
+  /* default (no tone, no emphasis): subtle neutral tint pill. */
+  background: color-mix(in srgb, var(--_badge-tone) 16%, var(--vms-surface));
+  color: var(--_badge-tone);
+  border: 1px solid transparent;
+}
+/* tone — the universal status color, sets the pill's working color. */
+.vms-badge--danger  { --_badge-tone: var(--vms-error); }
+.vms-badge--warning { --_badge-tone: var(--vms-warning); }
+.vms-badge--success { --_badge-tone: var(--vms-success); }
+.vms-badge--info    { --_badge-tone: var(--vms-info); }
+/* emphasis — primary = solid filled tone (white text); secondary = outline.
+   Declared after tone so the chosen --_badge-tone drives both. */
+.vms-badge--primary {
+  background: var(--_badge-tone);
+  border-color: var(--_badge-tone);
+  color: #fff;
+}
+.vms-badge--secondary {
+  background: transparent;
+  border-color: var(--_badge-tone);
+  color: var(--_badge-tone);
+}