@ashley-shrok/viewmodel-shell 5.0.0 → 5.1.0

package/dist/browser.d.ts

@@ -136,6 +136,15 @@ export declare class BrowserAdapter implements Adapter {
     /** CheckboxNode (standalone, immediate-dispatch) — bound boolean; on toggle,
      *  write to state then dispatch the action name (if any). */
     private checkbox;
+    /** Shared button appearance + activation behavior, applied to a <button> element
+     *  (a standalone ButtonNode's button, OR a form's submitButton). Sets the full
+     *  className (emphasis/tone/size/width/disabled), label, and the `disabled` attr,
+     *  and returns a guarded `activate()` that runs disabled -> confirm -> pendingLabel
+     *  swap -> dispatch. Both the standalone button() renderer and the FormNode
+     *  submitButton branch use this so the two can NEVER diverge — the divergence WAS
+     *  the bug (a form-level submit button silently dropped pendingLabel/disabled/
+     *  confirm because it re-implemented rendering without the click behavior). */
+    private applyButtonBehavior;
     private button;
     private text;
     private link;
@@ -171,4 +180,22 @@ export declare class BrowserAdapter implements Adapter {
     /** BadgeNode — a compact inline status pill / count. Leaf node: label text +
      *  tone/emphasis modifier classes. */
     private badge;
+    /** BreadcrumbNode — a `<nav aria-label="breadcrumb">` landmark wrapping an
+     *  `<ol>`. Every crumb but the last navigates (href → `<a>`, action →
+     *  dispatching `<button>`); the LAST crumb is the current page, rendered as
+     *  plain text with `aria-current="page"` on its `<li>` (position is the
+     *  signal — no per-item flag). A framework-drawn, `aria-hidden` separator
+     *  sits between items (its glyph is CSS-owned — see default.css). All text is
+     *  set via textContent (never innerHTML). */
+    private breadcrumb;
+    /** StepsNode — a discrete stepper. Per-step status DERIVES from `current`
+     *  (index < current = done, === current = current, > current = upcoming);
+     *  there is NO per-step status field. The framework draws numbered markers
+     *  (a check glyph for done), the connector lines, and the intrinsic
+     *  horizontal→vertical collapse (CSS). a11y: the group carries an accessible
+     *  name; the current step's `<li>` gets `aria-current="step"`; each marker's
+     *  state (complete/current/upcoming) rides an `aria-label` so it's never
+     *  conveyed by color alone. The stepper is NOT focusable and is NOT
+     *  `role="progressbar"` (that's a continuous %). All text via textContent. */
+    private steps;
 }

package/dist/browser.js

@@ -360,6 +360,8 @@ export class BrowserAdapter {
             case "empty-state": return this.emptyState(n, parent, on);
             case "badge": return this.badge(n, parent);
             case "chart": return this.chart(n, parent);
+            case "breadcrumb": return this.breadcrumb(n, parent, on);
+            case "steps": return this.steps(n, parent);
             default: {
                 // Fail loud, not silent (AGENTS.md: "Nothing important fails quietly").
                 // Runtime trees are server-controlled JSON, so an unknown/forward-version
@@ -865,15 +867,17 @@ export class BrowserAdapter {
         const sb = n.submitButton;
         const effectiveSubmit = sb ? sb.action : n.submitAction;
         if (sb) {
-            const submitAction = sb.action;
             const submit = document.createElement("button");
             submit.type = "submit";
-            submit.className = `vms-button${sb.emphasis ? ` vms-button--${sb.emphasis}` : ""}${sb.tone ? ` vms-button--${sb.tone}` : ""}${sb.size ? ` vms-button--${sb.size}` : ""}${sb.width === "full" ? " vms-button--full" : ""}`;
-            submit.textContent = sb.label;
+            // Same appearance + activation as a standalone button — disabled/confirm/
+            // pendingLabel included. The form's submit event is the single dispatch
+            // point (keeps native Enter-to-submit for text fields working); activate()
+            // carries the disabled guard, confirm guard, and pendingLabel swap.
+            const activate = this.applyButtonBehavior(submit, sb, dispatchWithFiles);
             form.appendChild(submit);
             form.addEventListener("submit", (e) => {
                 e.preventDefault();
-                dispatchWithFiles(submitAction);
+                activate();
             });
         }
         else if (n.submitAction) {
@@ -1269,24 +1273,30 @@ export class BrowserAdapter {
         });
         parent.appendChild(lbl);
     }
-    button(n, parent, on) {
-        const btn = document.createElement("button");
-        btn.type = "button";
+    /** Shared button appearance + activation behavior, applied to a <button> element
+     *  (a standalone ButtonNode's button, OR a form's submitButton). Sets the full
+     *  className (emphasis/tone/size/width/disabled), label, and the `disabled` attr,
+     *  and returns a guarded `activate()` that runs disabled -> confirm -> pendingLabel
+     *  swap -> dispatch. Both the standalone button() renderer and the FormNode
+     *  submitButton branch use this so the two can NEVER diverge — the divergence WAS
+     *  the bug (a form-level submit button silently dropped pendingLabel/disabled/
+     *  confirm because it re-implemented rendering without the click behavior). */
+    applyButtonBehavior(btn, n, dispatch) {
         btn.className = `vms-button${n.emphasis ? ` vms-button--${n.emphasis}` : ""}${n.tone ? ` vms-button--${n.tone}` : ""}${n.size ? ` vms-button--${n.size}` : ""}${n.width === "full" ? " vms-button--full" : ""}${n.disabled ? " vms-button--disabled" : ""}`;
         btn.textContent = n.label;
         if (n.disabled)
             btn.disabled = true;
-        btn.addEventListener("click", () => {
+        return () => {
             // Forms-completeness (3.4.0): a disabled button never dispatches. (Native
-            // `disabled` already suppresses the click, but guard anyway in case the
-            // attribute was cleared out-of-band.)
+            // `disabled` already suppresses a click, but guard anyway — a form submit
+            // isn't a native button click, and the attribute could be cleared out-of-band.)
             if (n.disabled)
                 return;
             // confirm: a destructive-action guard. Show the NATIVE browser confirm
             // BEFORE any pendingLabel swap or dispatch; Cancel suppresses everything
             // (no dispatch, no visual change). Native by design — zero app/framework
             // state, and it's a client-only human affordance (an agent never reaches
-            // this click handler; it dispatches the action directly over the wire).
+            // this handler; it dispatches the action directly over the wire).
             if (n.confirm && !window.confirm(n.confirm))
                 return;
             // pendingLabel: instant client-side feedback. Swap text + add
@@ -1297,8 +1307,14 @@ export class BrowserAdapter {
                 btn.textContent = n.pendingLabel;
                 btn.classList.add("vms-button--pending");
             }
-            on(n.action);
-        });
+            dispatch(n.action);
+        };
+    }
+    button(n, parent, on) {
+        const btn = document.createElement("button");
+        btn.type = "button";
+        const activate = this.applyButtonBehavior(btn, n, on);
+        btn.addEventListener("click", activate);
         parent.appendChild(btn);
     }
     text(n, parent) {
@@ -1781,4 +1797,121 @@ export class BrowserAdapter {
         span.textContent = n.label;
         parent.appendChild(span);
     }
+    /** BreadcrumbNode — a `<nav aria-label="breadcrumb">` landmark wrapping an
+     *  `<ol>`. Every crumb but the last navigates (href → `<a>`, action →
+     *  dispatching `<button>`); the LAST crumb is the current page, rendered as
+     *  plain text with `aria-current="page"` on its `<li>` (position is the
+     *  signal — no per-item flag). A framework-drawn, `aria-hidden` separator
+     *  sits between items (its glyph is CSS-owned — see default.css). All text is
+     *  set via textContent (never innerHTML). */
+    breadcrumb(n, parent, on) {
+        const nav = document.createElement("nav");
+        nav.setAttribute("aria-label", "breadcrumb");
+        const ol = document.createElement("ol");
+        ol.className = "vms-breadcrumb";
+        n.items.forEach((item, i) => {
+            const isLast = i === n.items.length - 1;
+            const li = document.createElement("li");
+            li.className = "vms-breadcrumb__item";
+            if (isLast) {
+                // Current page: plain, non-clickable, aria-current on the <li>.
+                li.setAttribute("aria-current", "page");
+                const span = document.createElement("span");
+                span.className = "vms-breadcrumb__current";
+                span.textContent = item.label;
+                li.appendChild(span);
+            }
+            else if (item.href != null) {
+                // URL navigation — reuse LinkNode's external target/rel handling.
+                const a = document.createElement("a");
+                a.className = "vms-breadcrumb__link";
+                a.href = item.href;
+                a.textContent = item.label;
+                if (item.external) {
+                    a.target = "_blank";
+                    a.rel = "noopener noreferrer";
+                }
+                li.appendChild(a);
+            }
+            else if (item.action) {
+                // Server dispatch — a button that fires the action name only.
+                const action = item.action;
+                const btn = document.createElement("button");
+                btn.type = "button";
+                btn.className = "vms-breadcrumb__link vms-breadcrumb__link--action";
+                btn.textContent = item.label;
+                btn.addEventListener("click", () => { on({ name: action.name }); });
+                li.appendChild(btn);
+            }
+            else {
+                // Non-last crumb with neither href nor action — inert label.
+                const span = document.createElement("span");
+                span.className = "vms-breadcrumb__link";
+                span.textContent = item.label;
+                li.appendChild(span);
+            }
+            // Framework-drawn separator after every non-last crumb (glyph via CSS).
+            if (!isLast) {
+                const sep = document.createElement("span");
+                sep.className = "vms-breadcrumb__separator";
+                sep.setAttribute("aria-hidden", "true");
+                li.appendChild(sep);
+            }
+            ol.appendChild(li);
+        });
+        nav.appendChild(ol);
+        parent.appendChild(nav);
+    }
+    /** StepsNode — a discrete stepper. Per-step status DERIVES from `current`
+     *  (index < current = done, === current = current, > current = upcoming);
+     *  there is NO per-step status field. The framework draws numbered markers
+     *  (a check glyph for done), the connector lines, and the intrinsic
+     *  horizontal→vertical collapse (CSS). a11y: the group carries an accessible
+     *  name; the current step's `<li>` gets `aria-current="step"`; each marker's
+     *  state (complete/current/upcoming) rides an `aria-label` so it's never
+     *  conveyed by color alone. The stepper is NOT focusable and is NOT
+     *  `role="progressbar"` (that's a continuous %). All text via textContent. */
+    steps(n, parent) {
+        const ol = document.createElement("ol");
+        ol.className = n.orientation === "vertical"
+            ? "vms-steps vms-steps--vertical"
+            : "vms-steps";
+        ol.setAttribute("aria-label", "progress");
+        n.steps.forEach((step, i) => {
+            const state = i < n.current ? "done" : i === n.current ? "current" : "upcoming";
+            const li = document.createElement("li");
+            li.className = `vms-steps__step vms-steps__step--${state}`;
+            if (state === "current")
+                li.setAttribute("aria-current", "step");
+            // Connector — CSS-drawn line marker-center to marker-center, behind the
+            // opaque marker (hidden on the first step via CSS).
+            const connector = document.createElement("span");
+            connector.className = "vms-steps__connector";
+            connector.setAttribute("aria-hidden", "true");
+            li.appendChild(connector);
+            // Marker — number, or a check glyph for done. State rides aria-label so
+            // it's not color-only (the aria-label overrides the visual glyph name).
+            const marker = document.createElement("span");
+            marker.className = "vms-steps__marker";
+            marker.setAttribute("aria-label", state === "done" ? "complete" : state === "current" ? "current" : "upcoming");
+            marker.textContent = state === "done" ? "✓" : String(i + 1);
+            li.appendChild(marker);
+            // Body — label + optional one-line description.
+            const body = document.createElement("span");
+            body.className = "vms-steps__body";
+            const label = document.createElement("span");
+            label.className = "vms-steps__label";
+            label.textContent = step.label;
+            body.appendChild(label);
+            if (step.description != null && step.description !== "") {
+                const desc = document.createElement("span");
+                desc.className = "vms-steps__description";
+                desc.textContent = step.description;
+                body.appendChild(desc);
+            }
+            li.appendChild(body);
+            ol.appendChild(li);
+        });
+        parent.appendChild(ol);
+    }
 }

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;
+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;
 export interface PageNode {
     type: "page";
     title?: string;
@@ -417,6 +417,39 @@ export interface LinkNode {
      *  like every other view decision — there is no client-side route matching. */
     active?: boolean;
 }
+/** One crumb in a BreadcrumbNode trail. Mirrors LinkNode's nav model:
+ *  `href` = browser navigation (`external` ⇒ new tab + noopener, exactly like
+ *  LinkNode); `action` = a server dispatch instead of a URL (the VMS-native
+ *  navigate-by-state path). There is NO per-item "current" flag — position is
+ *  the signal: the LAST item in `items` is auto-rendered as the current page
+ *  (non-clickable, `aria-current="page"`), so it needs neither `href` nor
+ *  `action`. A crumb that carries `action` is a dispatch-bearing descendant, so
+ *  the action-name uniqueness walk descends into it (see collectActions). */
+export interface BreadcrumbItem {
+    /** Visible crumb text (required). */
+    label: string;
+    /** Browser navigation target. Omit on the last (current) crumb. */
+    href?: string;
+    /** true = open outside the current app context (browser: new tab + noopener),
+     *  exactly like LinkNode.external. Only meaningful alongside `href`. */
+    external?: boolean;
+    /** Server dispatch instead of a URL — the VMS navigate-by-state alternative to
+     *  `href`. Its name is uniqueness-checked by the tree validator. */
+    action?: ActionEvent;
+}
+/** A breadcrumb trail — an ordered list of labelled positions from the site/app
+ *  root to the current page. The framework owns ALL appearance and a11y (never
+ *  on the wire): it draws the `<nav aria-label="breadcrumb">` landmark, the
+ *  `<ol>`, `aria-current="page"` on the last item, and a FIXED separator between
+ *  items (the one appearance knob other frameworks expose stays framework-drawn
+ *  here — cf. DividerNode's framework-drawn separator). The wire carries only the
+ *  ordered labels + their nav targets. */
+export interface BreadcrumbNode {
+    type: "breadcrumb";
+    /** Ordered root→current list. The LAST entry is the current page (auto
+     *  non-clickable); earlier entries navigate via `href` or `action`. */
+    items: BreadcrumbItem[];
+}
 export interface ImageNode {
     type: "image";
     /** Image source URL (required). */
@@ -695,6 +728,39 @@ export interface ChartNode {
     /** Optional chart title rendered above the plot. */
     title?: string;
 }
+/** One stage in a StepsNode progression. Carries only display data — status
+ *  (done/current/upcoming) is NEVER on the item; it DERIVES from the node's
+ *  `current` index. */
+export interface StepItem {
+    /** Stage name (required). */
+    label: string;
+    /** Optional one-line supporting text shown beside/under the label. */
+    description?: string;
+}
+/** A discrete step / stepper / wizard progress indicator — an ordered list of
+ *  stages with a single 0-based `current` index. Per-step status DERIVES from
+ *  `current` (index < current = done, index === current = current, index >
+ *  current = upcoming); there is NO per-step status field. The framework owns
+ *  ALL appearance and a11y (never on the wire): numbered markers (check glyph
+ *  for done), connector lines drawn marker-center to marker-center, the
+ *  intrinsic horizontal→vertical reflow, and the discrete `aria-current="step"`
+ *  a11y pattern (it is NOT `role="progressbar"`). The wire carries only the
+ *  ordered labels + which one is current. */
+export interface StepsNode {
+    type: "steps";
+    /** Ordered stages. */
+    steps: StepItem[];
+    /** 0-based index of the active step. Required — `0` is a meaningful value
+     *  (the first step is current), so it always crosses the wire. */
+    current: number;
+    /** Layout INTENT (a closed enum, not a raw directive — the framework owns the
+     *  actual layout + reflow). OMITTED = `"horizontal"`: the renderer treats an
+     *  absent `orientation` as horizontal — a responsive strip that auto-stacks to
+     *  vertical INTRINSICALLY when the container is narrow (zero viewport
+     *  breakpoints). `"vertical"` = a deliberate vertical wizard (markers down the
+     *  left, connector running down, descriptions beside each step). */
+    orientation?: "horizontal" | "vertical";
+}
 export interface ShellOptions {
     endpoint: string;
     actionEndpoint: string;

package/dist/server.js

@@ -203,11 +203,27 @@ function collectActions(node, enclosingForm, out) {
                 collectActions(es.action, enclosingForm, out);
             return;
         }
+        case "breadcrumb": {
+            // A breadcrumb crumb can navigate by DISPATCHING AN ACTION instead of an
+            // href (the VMS navigate-by-state model). Each such action is a
+            // dispatch-bearing descendant, so the uniqueness collector MUST descend
+            // into it — modeled on the `tabs` arm, with the optional guard the
+            // empty-state arm uses (not every crumb carries an action; the last/current
+            // crumb and href-only crumbs carry none). Skipping this would silently
+            // exempt crumb actions from the one-name-one-operation rule.
+            const bc = node;
+            for (const item of bc.items) {
+                if (item.action)
+                    recordAction(item.action, enclosingForm, out);
+            }
+            return;
+        }
         // Nodes with no dispatch-bearing actions of their own:
-        //   text, link, image, stat-bar, progress, copy-button, badge, chart
-        // ChartNode (CHART-05) is a DELIBERATE childless/action-free leaf — it
-        // carries only data points, so it falls through here with no recursion (no
-        // fits-style blind spot).
+        //   text, link, image, stat-bar, progress, copy-button, badge, chart, steps
+        //   (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).
         default:
             return;
     }
@@ -372,9 +388,12 @@ function walkForSectionAction(node, outerInteractive) {
             return;
         }
         // Leaf-like nodes (field, checkbox, button, text, link, image, stat-bar,
-        // tabs, progress, table, copy-button, badge, chart) carry no SectionNode
-        // descendants — TableNode rows hold strings + per-row controls, not sections;
-        // ChartNode (CHART-05) is a childless/action-free data leaf.
+        // tabs, progress, table, copy-button, badge, chart, breadcrumb, steps) carry
+        // no SectionNode descendants — TableNode rows hold strings + per-row controls,
+        // not sections; ChartNode (CHART-05) is a childless/action-free data leaf;
+        // BreadcrumbNode/StepsNode (NAV-01..03) hold plain { label, ... } records,
+        // not ViewNode children, so no recursion is needed here (deliberate, not a
+        // missed walk).
         default:
             return;
     }

package/dist/tui.js

@@ -752,6 +752,26 @@ function renderNode(node, ctx, key) {
         case "modal": return _jsx(ModalView, { node: node, ctx: ctx }, key);
         case "copy-button": return _jsx(CopyButtonView, { node: node, ctx: ctx }, key);
         case "divider": return _jsx("text", { fg: "#555555", children: node.orientation === "vertical" ? "│" : "─".repeat(40) }, key);
+        case "breadcrumb":
+            // NAV-03 — @experimental TUI degrade. A terminal has no breadcrumb chrome,
+            // so we render the trail inline as labels joined by a separator glyph (the
+            // LAST item is the current page — rendered plainly, no interactivity). The
+            // framework-owned separator becomes a text " › ". Bar is "doesn't break +
+            // degrades sensibly" (see the `fits` case). No DOM.
+            return _jsx("text", { fg: "#888888", children: node.items.map((i) => i.label).join(" › ") }, key);
+        case "steps": {
+            // NAV-03 — @experimental TUI degrade. No stepper chrome in a terminal, so
+            // each step renders on its own line with a state marker DERIVED from
+            // `current` (index < current = done ✓, === current = ▸, > current = ·),
+            // mirroring the browser renderer's derive-from-current rule. `description`
+            // is appended when present. No DOM.
+            return (_jsx("box", { flexDirection: "column", children: node.steps.map((step, i) => {
+                    const marker = i < node.current ? "✓" : i === node.current ? "▸" : "·";
+                    const fg = i === node.current ? "#88aaff" : i < node.current ? "#aaaaaa" : "#666666";
+                    const line = step.description ? `${marker} ${step.label} — ${step.description}` : `${marker} ${step.label}`;
+                    return _jsx("text", { fg: fg, children: line }, i);
+                }) }, key));
+        }
         case "form": return _jsx(FormView, { node: node, ctx: ctx }, key);
         case "field": return _jsx(FieldView, { node: node, ctx: ctx }, key);
         case "fits": {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ashley-shrok/viewmodel-shell",
-  "version": "5.0.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.",
+  "version": "5.1.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",
   "author": "ashley-shrok",

package/styles/default.css

@@ -1162,3 +1162,187 @@ select.vms-field__input  { cursor: pointer; padding-right: var(--vms-space-xl);
   border-color: var(--_badge-tone);
   color: var(--_badge-tone);
 }
+
+/* ── Breadcrumb ──
+   <nav aria-label="breadcrumb"> > <ol.vms-breadcrumb> trail. Earlier crumbs are
+   accent links (or dispatching buttons reset to read as links); the current
+   (last) crumb is bold --vms-text; a fixed, muted, framework-drawn separator
+   (glyph via ::before — off the wire) sits after each non-last crumb. All
+   spacing/colour is token-driven. */
+.vms-breadcrumb {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--vms-space-xs);
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  font-size: var(--vms-text-sm);
+}
+.vms-breadcrumb__item {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--vms-space-xs);
+}
+.vms-breadcrumb__link {
+  color: var(--vms-accent);
+  text-decoration: none;
+  border-bottom: 1px solid transparent;
+  transition: border-color var(--vms-t);
+}
+.vms-breadcrumb__link:hover { border-bottom-color: var(--vms-accent); }
+/* Action crumbs render as <button> — strip native chrome so they read as links. */
+button.vms-breadcrumb__link {
+  background: none;
+  padding: 0;
+  border-top: none;
+  border-right: none;
+  border-left: none;
+  font: inherit;
+  line-height: inherit;
+  cursor: pointer;
+}
+.vms-breadcrumb__current {
+  color: var(--vms-text);
+  font-weight: 600;
+}
+/* One fixed framework-drawn separator (the glyph is CSS-owned, never on the wire). */
+.vms-breadcrumb__separator {
+  color: var(--vms-text-muted);
+  user-select: none;
+}
+.vms-breadcrumb__separator::before { content: "/"; }
+
+/* ── Steps ──
+   A discrete stepper. Numbered markers (a check glyph for done) joined by
+   connector lines the framework draws marker-CENTER to marker-CENTER behind the
+   opaque markers (so the line reads bubble-edge to bubble-edge). Per-step state
+   (done/current/upcoming) derives from the node's `current` index; done/current
+   markers fill --vms-accent, current gets an --vms-accent-glow ring, upcoming is
+   an outlined --vms-text-muted marker. Horizontal by default; it auto-collapses
+   to the stacked/vertical form INTRINSICALLY via a container query (ZERO
+   viewport breakpoints — P1); the deliberate .vms-steps--vertical wizard always
+   uses that stacked form. Marker/line widths use small px like .vms-link /
+   .vms-badge (no width token exists); every colour + gap is a --vms-* token. */
+.vms-steps {
+  --_step-marker: var(--vms-space-xl);   /* marker diameter (2.25rem) */
+  container-type: inline-size;
+  display: flex;
+  flex-wrap: wrap;
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  font-size: var(--vms-text-sm);
+}
+/* Horizontal (default): equal columns, centered marker over centered label. */
+.vms-steps__step {
+  flex: 1 1 0;
+  min-width: 0;
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  text-align: center;
+  gap: var(--vms-space-xs);
+}
+.vms-steps__marker {
+  position: relative;
+  z-index: 1;                            /* opaque marker sits ON the connector */
+  flex-shrink: 0;
+  box-sizing: border-box;
+  width: var(--_step-marker);
+  height: var(--_step-marker);
+  border-radius: 50%;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  font-size: var(--vms-text-xs);
+  font-weight: 600;
+  line-height: 1;
+  /* upcoming (default): outlined muted marker on the surface. */
+  background: var(--vms-surface);
+  border: 2px solid var(--vms-text-muted);
+  color: var(--vms-text-muted);
+}
+/* done + current: filled accent marker. The glyph uses --vms-surface so it
+   auto-adapts polarity (light theme → light glyph, dark → dark) and clears the
+   WCAG-AA graphical-object bar (>=3:1) on every shipped theme — the marker is a
+   graphical state indicator, its semantic state also rides an aria-label. */
+.vms-steps__step--done .vms-steps__marker,
+.vms-steps__step--current .vms-steps__marker {
+  background: var(--vms-accent);
+  border-color: var(--vms-accent);
+  color: var(--vms-surface);
+}
+.vms-steps__step--current .vms-steps__marker {
+  box-shadow: 0 0 0 4px var(--vms-accent-glow);
+}
+.vms-steps__body {
+  display: flex;
+  flex-direction: column;
+  gap: var(--vms-space-2xs);
+}
+.vms-steps__label { color: var(--vms-text); font-weight: 600; }
+.vms-steps__description { color: var(--vms-text-muted); font-size: var(--vms-text-xs); }
+
+/* Connector — the OUTGOING segment from this marker toward the next (hidden on
+   the last step). Colored by the step's own state: accent once the step is done,
+   muted otherwise. z-index 0 so the opaque markers cover it edge-to-edge. */
+.vms-steps__connector {
+  position: absolute;
+  z-index: 0;
+  top: calc(var(--_step-marker) / 2);
+  left: 50%;
+  width: 100%;
+  height: 2px;
+  transform: translateY(-1px);
+}
+.vms-steps__step:last-child .vms-steps__connector { display: none; }
+.vms-steps__step--done .vms-steps__connector { background: var(--vms-accent); }
+.vms-steps__step--current .vms-steps__connector,
+.vms-steps__step--upcoming .vms-steps__connector { background: var(--vms-text-muted); }
+
+/* ── Stacked form — shared by the deliberate vertical wizard AND the intrinsic
+   narrow-container collapse: marker on the left, label + description beside it,
+   the connector becomes a vertical line down the marker's center. ── */
+.vms-steps--vertical .vms-steps__step {
+  flex: 1 1 100%;
+  flex-direction: row;
+  align-items: flex-start;
+  text-align: left;
+  gap: var(--vms-space-sm);
+  padding-bottom: var(--vms-space-md);
+}
+.vms-steps--vertical .vms-steps__body {
+  padding-top: calc((var(--_step-marker) - var(--vms-text-sm)) / 2);
+}
+.vms-steps--vertical .vms-steps__connector {
+  top: calc(var(--_step-marker) / 2);
+  left: calc(var(--_step-marker) / 2);
+  bottom: 0;
+  width: 2px;
+  height: auto;
+  transform: translateX(-1px);
+}
+
+@container (max-width: 30rem) {
+  .vms-steps:not(.vms-steps--vertical) .vms-steps__step {
+    flex: 1 1 100%;
+    flex-direction: row;
+    align-items: flex-start;
+    text-align: left;
+    gap: var(--vms-space-sm);
+    padding-bottom: var(--vms-space-md);
+  }
+  .vms-steps:not(.vms-steps--vertical) .vms-steps__body {
+    padding-top: calc((var(--_step-marker) - var(--vms-text-sm)) / 2);
+  }
+  .vms-steps:not(.vms-steps--vertical) .vms-steps__connector {
+    top: calc(var(--_step-marker) / 2);
+    left: calc(var(--_step-marker) / 2);
+    bottom: 0;
+    width: 2px;
+    height: auto;
+    transform: translateX(-1px);
+  }
+}