@ashley-shrok/viewmodel-shell 1.10.0 → 1.12.0

package/dist/browser.d.ts

@@ -5,6 +5,7 @@ export declare class BrowserAdapter implements Adapter {
     private sa;
     private detailsOpenSnapshot;
     private sectionKeyCounter;
+    private fitsObservers;
     constructor(container: HTMLElement);
     render(vm: ViewNode, onAction: (action: ActionEvent) => void, stateAccess?: StateAccess): void;
     navigate(url: string): void;
@@ -23,6 +24,31 @@ export declare class BrowserAdapter implements Adapter {
     private node;
     private kids;
     private page;
+    /**
+     * Phase 10 (FITS-01) — the SwiftUI `ViewThatFits` measure-and-pick renderer.
+     * Renders each candidate in order and keeps the FIRST that does not overflow
+     * the container on `axis` (1px tolerance to avoid sub-pixel false positives),
+     * leaving the LAST candidate rendered as the guaranteed-fits fallback if none
+     * fit. `pick()` runs SYNCHRONOUSLY inside one frame, so the browser paints
+     * only the final choice — no flash of intermediate candidates.
+     *
+     * No-layout fallback: when `container.clientWidth === 0` (jsdom / SSR /
+     * detached / display:none) measurement is unavailable, so it renders ONLY the
+     * LAST (safe-fallback) child.
+     *
+     * The `.vms-fits` container is a full-width block (CSS), so its observed width
+     * is PARENT-driven — it reflects the available space, not the chosen child.
+     * That keeps measurement correct AND prevents a measure→resize feedback loop,
+     * making observing the container stable. A `ResizeObserver` re-runs `pick()`
+     * on a window/parent resize and is tracked in `fitsObservers` for the next
+     * render's disconnect-and-clear.
+     *
+     * Known v1 limitation (document, don't solve): a resize-triggered candidate
+     * switch rebuilds the fits subtree, so focus/caret/draft state INSIDE a fits
+     * child may reset on a resize-switch. The framework's normal focus/scroll
+     * preservation covers server-driven re-renders, not this resize-switch path.
+     */
+    private fits;
     private section;
     private list;
     private listItem;

package/dist/browser.js

@@ -51,6 +51,12 @@ export class BrowserAdapter {
     // collapsible:true so that multiple sections sharing the same base key
     // (anonymous, or duplicate heading) get distinct final keys.
     sectionKeyCounter = new Map();
+    // Phase 10 (FITS-01) — per-render registry of the ResizeObservers created by
+    // fits() containers. ALL are disconnected and the array cleared at the TOP of
+    // every render() (before the innerHTML wipe) so observers from a prior tree
+    // never leak when the tree is rebuilt — the same per-render reset idiom as
+    // detailsOpenSnapshot / sectionKeyCounter above.
+    fitsObservers = [];
     constructor(container) {
         this.container = container;
     }
@@ -84,6 +90,11 @@ export class BrowserAdapter {
         });
         this.detailsOpenSnapshot = openMap;
         this.sectionKeyCounter = new Map();
+        // Phase 10 (FITS-01) — disconnect every ResizeObserver registered by the
+        // prior render's fits() calls before the tree is rebuilt (leak prevention).
+        // Same per-render reset model as the focus/scroll/details snapshots above.
+        this.fitsObservers.forEach(o => o.disconnect());
+        this.fitsObservers = [];
         this.container.innerHTML = "";
         this.node(vm, this.container, onAction);
         if (focusId) {
@@ -222,6 +233,7 @@ export class BrowserAdapter {
             case "modal": return this.modal(n, parent, on);
             case "table": return this.table(n, parent, on);
             case "copy-button": return this.copyButton(n, parent);
+            case "fits": return this.fits(n, parent, on);
         }
     }
     kids(nodes, parent, on) {
@@ -229,7 +241,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}` : ""}`;
+        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}` : ""}`;
         if (n.title) {
             const h = document.createElement("h1");
             h.className = "vms-page__title";
@@ -239,6 +251,97 @@ export class BrowserAdapter {
         this.kids(n.children, el, on);
         parent.appendChild(el);
     }
+    /**
+     * Phase 10 (FITS-01) — the SwiftUI `ViewThatFits` measure-and-pick renderer.
+     * Renders each candidate in order and keeps the FIRST that does not overflow
+     * the container on `axis` (1px tolerance to avoid sub-pixel false positives),
+     * leaving the LAST candidate rendered as the guaranteed-fits fallback if none
+     * fit. `pick()` runs SYNCHRONOUSLY inside one frame, so the browser paints
+     * only the final choice — no flash of intermediate candidates.
+     *
+     * No-layout fallback: when `container.clientWidth === 0` (jsdom / SSR /
+     * detached / display:none) measurement is unavailable, so it renders ONLY the
+     * LAST (safe-fallback) child.
+     *
+     * The `.vms-fits` container is a full-width block (CSS), so its observed width
+     * is PARENT-driven — it reflects the available space, not the chosen child.
+     * That keeps measurement correct AND prevents a measure→resize feedback loop,
+     * making observing the container stable. A `ResizeObserver` re-runs `pick()`
+     * on a window/parent resize and is tracked in `fitsObservers` for the next
+     * render's disconnect-and-clear.
+     *
+     * Known v1 limitation (document, don't solve): a resize-triggered candidate
+     * switch rebuilds the fits subtree, so focus/caret/draft state INSIDE a fits
+     * child may reset on a resize-switch. The framework's normal focus/scroll
+     * preservation covers server-driven re-renders, not this resize-switch path.
+     */
+    fits(n, parent, on) {
+        const container = document.createElement("div");
+        container.className = "vms-fits";
+        parent.appendChild(container);
+        const axis = n.axis ?? "horizontal";
+        const candidates = n.children;
+        const pick = () => {
+            // Defensive: a fits with no children is a degenerate tree.
+            if (candidates.length === 0)
+                return;
+            const vertical = axis === "vertical";
+            // The available space is the container's REAL (constrained) box. The
+            // container is block / full-width so this is the slot the parent gave it,
+            // not the chosen child's size.
+            const available = vertical ? container.clientHeight : container.clientWidth;
+            // No-layout guard: measurement unavailable (jsdom / SSR / display:none /
+            // detached) → render the safe LAST child (guaranteed-fits fallback).
+            if (available === 0) {
+                container.innerHTML = "";
+                this.node(candidates[candidates.length - 1], container, on);
+                return;
+            }
+            // Measure each candidate's INTRINSIC size in an off-screen probe, NOT its
+            // constrained rendered size. This is the crux of a correct ViewThatFits:
+            // a candidate like a flex-wrap `row` SHRINKS / WRAPS to fit any width, so
+            // its in-container scrollWidth never exceeds clientWidth — measuring that
+            // would make every candidate "fit" and the selection would never change
+            // (the bug this replaces). Measuring the probe at `width: max-content`
+            // lets the candidate lay out at its IDEAL width (one line, no wrap), which
+            // is what ViewThatFits compares against the proposed size. The probe is
+            // appended to `container` for correct style/font inheritance but kept
+            // off-screen + hidden, and it does NOT change the container's observed
+            // border-box, so the ResizeObserver below cannot feed back into itself.
+            const probe = document.createElement("div");
+            probe.setAttribute("aria-hidden", "true");
+            probe.style.cssText =
+                "position:absolute;left:-99999px;top:0;visibility:hidden;pointer-events:none;";
+            if (vertical) {
+                // Vertical fit: constrain width to the real available width and measure
+                // the resulting intrinsic height against the available height.
+                probe.style.width = `${available}px`;
+            }
+            else {
+                probe.style.width = "max-content"; // intrinsic (ideal, unwrapped) width
+            }
+            container.appendChild(probe);
+            let chosen = candidates.length - 1; // fallback = last
+            for (let i = 0; i < candidates.length; i++) {
+                probe.innerHTML = "";
+                this.node(candidates[i], probe, on);
+                void probe.offsetWidth; // force a synchronous reflow before reading
+                const intrinsic = vertical ? probe.scrollHeight : probe.scrollWidth;
+                // First candidate whose intrinsic size fits the available space wins.
+                if (intrinsic <= available + 1) {
+                    chosen = i;
+                    break;
+                }
+            }
+            probe.remove();
+            container.innerHTML = "";
+            this.node(candidates[chosen], container, on);
+        };
+        pick();
+        const ro = new ResizeObserver(() => pick());
+        ro.observe(container);
+        this.fitsObservers.push(ro);
+    }
     section(n, parent, on) {
         // 1.2.0 — collapsible:true branch emits native <details>/<summary>; the
         // open/closed state is DOM-local and preserved across re-renders by the
@@ -250,7 +353,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.layout && n.layout !== "stack" ? ` vms-section--${n.layout}` : ""}`;
+            el.className = `vms-section vms-section--collapsible${n.variant === "card" ? " vms-section--card" : ""}${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}` : ""}`;
             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.
@@ -265,6 +368,29 @@ export class BrowserAdapter {
             parent.appendChild(el);
             return;
         }
+        // 1.11.0 — flyout:true overlay disclosure. The hover/focus sibling of
+        // collapsible's inline <details>: heading => focusable <button> trigger,
+        // children => an absolutely-positioned panel revealed on :hover /
+        // :focus-within (pure CSS — see default.css; no JS, no listeners, no
+        // round-tripped open state). Precedence: collapsible (checked above) wins,
+        // so reaching here means collapsible is not set; flyout in turn wins over
+        // link/action below. Omitted/false renders byte-identical to <section>.
+        if (n.flyout === true) {
+            const el = document.createElement("div");
+            el.className = `vms-section vms-section--flyout${n.variant === "card" ? " vms-section--card" : ""}${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}` : ""}`;
+            const trigger = document.createElement("button");
+            trigger.type = "button";
+            trigger.className = "vms-section__trigger";
+            // Headingless fallback label — mirrors collapsible's "Show details".
+            trigger.textContent = n.heading ?? "Menu";
+            el.appendChild(trigger);
+            const panel = document.createElement("div");
+            panel.className = "vms-section__panel";
+            this.kids(n.children, panel, on);
+            el.appendChild(panel);
+            parent.appendChild(el);
+            return;
+        }
         // 1.5.0 — SectionNode.link URL-wrapper variant (issue #21). When set,
         // emit a wrapping <a href> element instead of <section> so every native
         // browser link affordance works for free (middle-click / Ctrl/Cmd-click
@@ -274,7 +400,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.layout && n.layout !== "stack" ? ` vms-section--${n.layout}` : ""}`;
+            a.className = `vms-section vms-section--linked${n.variant === "card" ? " vms-section--card" : ""}${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}` : ""}`;
             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.
@@ -318,7 +444,7 @@ export class BrowserAdapter {
             return;
         }
         const el = document.createElement("section");
-        el.className = `vms-section${n.variant === "card" ? " vms-section--card" : ""}${n.layout && n.layout !== "stack" ? ` vms-section--${n.layout}` : ""}${n.action ? " vms-section--clickable" : ""}`;
+        el.className = `vms-section${n.variant === "card" ? " vms-section--card" : ""}${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.action ? " vms-section--clickable" : ""}`;
         if (n.heading) {
             const h = document.createElement("h2");
             h.className = "vms-section__heading";

package/dist/index.d.ts

@@ -63,16 +63,26 @@ export interface Adapter {
      *  visually flips the box. Fail-quiet by absence (TUI has no equivalent). */
     setBusy?(active: boolean): void;
 }
-export type ViewNode = PageNode | SectionNode | ListNode | ListItemNode | FormNode | FieldNode | CheckboxNode | ButtonNode | TextNode | LinkNode | ImageNode | 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 | FitsNode;
 export interface PageNode {
     type: "page";
     title?: string;
     /** Density of global spacing. Omitted or "comfortable" = current behavior (no modifier class). "compact" emits .vms-page--compact. Closed union (D-03). */
     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) emit .vms-page--{value}. Closed union (D-01/D-02; sidebar D-28). */
-    layout?: "stack" | "split" | "cards" | "sidebar";
+    /** 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";
     /** 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}. */
+    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}. */
+    align?: "start" | "center" | "end" | "stretch" | "baseline";
+    /** For `layout:"switcher"`: the content-width FLIP point — a CLOSED size scale (NOT raw CSS, per P2) mapping sm→20rem, md→30rem, lg→40rem, xl→48rem. Emits .vms-switch--{token} which sets `--vms-switch-threshold`. Omitted = no class → the `var(--vms-switch-threshold, 30rem)` CSS default (30rem) holds = well-defined, byte-identical to today. (SWITCH-02) */
+    threshold?: "sm" | "md" | "lg" | "xl";
+    /** For `layout:"switcher"`: the OPTIONAL max-items-per-row count cap — once the child count exceeds `limit`, every child goes full-width regardless of container width. A bounded numeric union (2..8) per P2 (bounded scalar, not raw CSS). Emits .vms-switch-limit--{n}. Omitted = no class → no count cap, byte-identical to today. (SWITCH-02) */
+    limit?: 2 | 3 | 4 | 5 | 6 | 7 | 8;
+    /** For `layout:"cards"`: overrides the auto-fit minimum track width (today's fixed `--vms-card-min: 16rem`) — a CLOSED size scale (NOT raw CSS, per P2) mapping xs→10rem, sm→13rem, md→16rem (= today's default), lg→20rem, xl→24rem. Emits .vms-cards-min--{token} which sets `--vms-card-min` on that element (the existing `repeat(auto-fit, minmax(min(var(--vms-card-min),100%),1fr))` cards rule reads it). Omitted = no class → the inherited 16rem default holds = byte-identical to today. Intended for `cards`; harmless elsewhere (it only sets a variable the cards rule reads). (GRID-01) */
+    minItem?: "xs" | "sm" | "md" | "lg" | "xl";
     children: ViewNode[];
 }
 export interface SectionNode {
@@ -80,12 +90,44 @@ export interface SectionNode {
     heading?: string;
     /** Section surface variant. Omitted = current behavior (no modifier class). "card" emits .vms-section--card. Closed union (D-03). */
     variant?: "card";
-    /** 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) emit .vms-section--{value}. Closed union (D-01/D-02; sidebar D-28). */
-    layout?: "stack" | "split" | "cards" | "sidebar";
+    /** 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";
+    /** 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}. */
+    align?: "start" | "center" | "end" | "stretch" | "baseline";
+    /** For `layout:"switcher"`: the content-width FLIP point — a CLOSED size scale (NOT raw CSS, per P2) mapping sm→20rem, md→30rem, lg→40rem, xl→48rem. Emits .vms-switch--{token} which sets `--vms-switch-threshold`. Omitted = no class → the `var(--vms-switch-threshold, 30rem)` CSS default (30rem) holds = well-defined, byte-identical to today. (SWITCH-02) */
+    threshold?: "sm" | "md" | "lg" | "xl";
+    /** For `layout:"switcher"`: the OPTIONAL max-items-per-row count cap — once the child count exceeds `limit`, every child goes full-width regardless of container width. A bounded numeric union (2..8) per P2 (bounded scalar, not raw CSS). Emits .vms-switch-limit--{n}. Omitted = no class → no count cap, byte-identical to today. (SWITCH-02) */
+    limit?: 2 | 3 | 4 | 5 | 6 | 7 | 8;
+    /** For `layout:"cards"`: overrides the auto-fit minimum track width (today's fixed `--vms-card-min: 16rem`) — a CLOSED size scale (NOT raw CSS, per P2) mapping xs→10rem, sm→13rem, md→16rem (= today's default), lg→20rem, xl→24rem. Emits .vms-cards-min--{token} which sets `--vms-card-min` on that element (the existing `repeat(auto-fit, minmax(min(var(--vms-card-min),100%),1fr))` cards rule reads it). Omitted = no class → the inherited 16rem default holds = byte-identical to today. Intended for `cards`; harmless elsewhere (it only sets a variable the cards rule reads). (GRID-01) */
+    minItem?: "xs" | "sm" | "md" | "lg" | "xl";
     /** Optional stable preservation key for the renderer's collapsible-section open-state snapshot. Used only when `collapsible: true`. Provide when `heading` isn't unique within a page or is absent — otherwise the renderer falls back to `heading ?? "vms-section-anon"`, disambiguated by per-render ordinal. Omitted = use the heading fallback. */
     id?: string;
     /** When true, the section renders as a native `<details>`/`<summary>` disclosure widget (closed by default). Aesthetic, client-side primitive — the open/closed state is DOM-local and the server does NOT round-trip it (same conceptual model as draft text values in unsubmitted form inputs). The browser adapter snapshots `<details>.open` before each re-render and restores it after, keyed by `id ?? heading ?? "vms-section-anon"` (disambiguated by per-render ordinal); a re-key drops the preserved state (the documented escape hatch for rare server-driven expansion). The summary label is the section's `heading`; a headingless collapsible section uses the fallback string `"Show details"`. If a section needs to start open, do not mark it collapsible. Omitted/false = today's `<section>` rendering, byte-identical. */
     collapsible?: boolean;
+    /** When true, the section renders as an OVERLAY disclosure ("flyout") — the
+     *  hover/focus sibling of `collapsible`'s inline `<details>` reveal. The
+     *  `heading` becomes a focusable `<button class="vms-section__trigger">`
+     *  trigger; the `children` are wrapped in a `<div class="vms-section__panel">`
+     *  that is absolutely positioned and revealed on `:hover` / `:focus-within`
+     *  (pure CSS — no JavaScript, no state machine). Hover (desktop), tap-to-focus
+     *  (touch), and keyboard Tab-to-trigger (a11y) all reveal it for free; it hides
+     *  on blur / pointer-leave. Unlike `collapsible`, the open state is EPHEMERAL
+     *  (driven by `:hover`/`:focus-within`), so it is NOT round-tripped and NOT
+     *  snapshotted across re-renders — there is nothing to preserve.
+     *
+     *  Use a flyout (overlay) rather than `collapsible` (inline) when the revealed
+     *  content should float over siblings instead of pushing them — e.g. a menu
+     *  inside a `layout:"row"` bar, where an inline disclosure would shove the bar
+     *  open. A headingless flyout uses the fallback trigger label `"Menu"`.
+     *
+     *  Mutually exclusive with the other section modes; the renderer resolves a
+     *  fixed precedence and never combines them: `collapsible` > `flyout` > `link`
+     *  > `action`. So `collapsible: true` wins if both are set, and a flyout
+     *  section ignores `link`/`action`. Omitted/false = today's `<section>`
+     *  rendering, byte-identical (no class drift, no extra elements). */
+    flyout?: boolean;
     /** Click-anywhere section dispatch primitive — mirrors `TableRow.action` (1.1.0)
      *  at the section level. When set, the renderer makes the entire section
      *  clickable AND keyboard-activatable (Enter / Space — Space preventDefaults
@@ -391,6 +433,53 @@ export interface CopyButtonNode {
      *  buttons. Closed union; omitted = current behavior (no modifier). */
     variant?: "primary" | "secondary" | "danger";
 }
+/**
+ * The SwiftUI `ViewThatFits` port. The renderer picks the FIRST child whose
+ * intrinsic size FITS the available container (no axis overflow), else the next,
+ * else the LAST child as the guaranteed-fits fallback — container-relative
+ * responsive SELECTION decided CLIENT-SIDE at layout time via real measurement,
+ * with zero viewport breakpoints. Generalizes the `split`→`stack` collapse to
+ * arbitrary alternatives (e.g. a wide toolbar `row` first, a compact stacked
+ * `switcher` last).
+ *
+ * Children ordering convention (load-bearing): candidates are ordered
+ * preferred/widest FIRST → safe-fallback/narrowest LAST. Same direction as
+ * SwiftUI `ViewThatFits`.
+ *
+ * This is the ONE primitive that is NOT pure CSS — the selection requires real
+ * layout measurement and therefore lives ENTIRELY in `BrowserAdapter`
+ * (`browser.ts`), never in platform-agnostic core. The renderer measures each
+ * candidate's INTRINSIC (max-content / ideal, unwrapped) size in an off-screen
+ * probe and picks the first whose intrinsic size fits the container's available
+ * box — NOT its constrained rendered size, because a flex-wrap candidate shrinks
+ * to fit any width and would always appear to "fit". A `ResizeObserver` re-runs
+ * the selection on resize. In any no-layout context (TUI, SSR, jsdom,
+ * `clientWidth === 0`) it degrades to rendering the LAST (safe-fallback) child.
+ *
+ * ⚠️ SCOPE: `fits` is for selecting between layouts whose intrinsic width is
+ * BOUNDED and meaningful — a toolbar row vs. a stacked menu, icon-only vs.
+ * icon+label controls, a compact vs. full control cluster. It is NOT the tool
+ * for text-heavy multi-column page layouts: a paragraph's max-content width is
+ * "all text on one line" (effectively unbounded), so measuring it is not
+ * meaningful. For list/detail and similar text panes use `split` / `sidebar`,
+ * which collapse to a single column intrinsically on their own (zero @media).
+ */
+export interface FitsNode {
+    type: "fits";
+    /** Axis on which the container's fit is tested. CLOSED union; OMITTED =
+     *  `"horizontal"` (the dominant case: pick the widest layout that fits the
+     *  available WIDTH). `"horizontal"` tests width overflow, `"vertical"` tests
+     *  height overflow, `"both"` tests EITHER axis. The renderer treats an absent
+     *  `axis` as `"horizontal"`. */
+    axis?: "horizontal" | "vertical" | "both";
+    /** Ordered candidate list. ORDERING CONVENTION (load-bearing — document
+     *  prominently): candidates are ordered **preferred/widest FIRST →
+     *  safe-fallback/narrowest LAST**, the same direction as SwiftUI
+     *  `ViewThatFits`. The renderer picks the FIRST candidate whose intrinsic
+     *  size fits the container on `axis` (no overflow); the LAST candidate is the
+     *  guaranteed-fits fallback rendered when none fit. */
+    children: ViewNode[];
+}
 export interface ShellOptions {
     endpoint: string;
     actionEndpoint: string;

package/dist/tui.js

@@ -501,6 +501,14 @@ function countPanes(vm) {
             for (const c of node.children)
                 visit(c, false);
         }
+        else if (node.type === "fits") {
+            // FITS-02 — the TUI renders only a fits node's LAST child, so treat it
+            // as a transparent wrapper around that child for pane counting (recurse
+            // into the last child only, isTopLevel=false like section).
+            const last = node.children[node.children.length - 1];
+            if (last)
+                visit(last, false);
+        }
     };
     // B4 focus trap: when a modal is in the tree, only count panes within the
     // modal's subtree. Outer panes still RENDER, but they're not part of the
@@ -565,6 +573,13 @@ function focusedPaneSummary(vm, index) {
                 if (visit(c, false))
                     return true;
         }
+        else if (node.type === "fits") {
+            // FITS-02 — only the LAST child renders in the TUI; mirror that here so
+            // focus targeting matches the rendered tree (recurse into last child only).
+            const last = node.children[node.children.length - 1];
+            if (last && visit(last, false))
+                return true;
+        }
         return false;
     };
     const modal = findModal(vm);
@@ -737,6 +752,16 @@ function renderNode(node, ctx, key) {
         case "copy-button": return _jsx(CopyButtonView, { node: node, ctx: ctx }, key);
         case "form": return _jsx(FormView, { node: node, ctx: ctx }, key);
         case "field": return _jsx(FieldView, { node: node, ctx: ctx }, key);
+        case "fits": {
+            // FITS-02 — deliberate TUI degradation. A terminal has no pixel layout
+            // engine, so the `fits` node's measure-and-pick selection is meaningless
+            // here; we render its guaranteed-fits LAST candidate (the documented
+            // fallback — children are ordered preferred/widest FIRST → safe/narrowest
+            // LAST). The TUI is @experimental; the requirement is only that `fits`
+            // doesn't break it and degrades sensibly. Empty children → render nothing.
+            const last = node.children[node.children.length - 1];
+            return last ? renderNode(last, ctx, key) : null;
+        }
         default:
             return _jsx(UnsupportedView, { type: node.type }, key);
     }
@@ -781,6 +806,11 @@ function layoutProps(layout, _sidebarFraction) {
             return { flexDirection: "row", gap: 1, flexGrow: 1, flexShrink: 1 };
         case "cards":
             return { flexDirection: "row", flexWrap: "wrap", gap: 1 };
+        case "row":
+            // 1.11.0 — left-aligned wrapping horizontal row; items hug content.
+            // (Section flyout has no TUI overlay; it degrades to a plain labeled
+            // section — SectionView ignores the flag and renders children inline.)
+            return { flexDirection: "row", flexWrap: "wrap", gap: 1 };
         case "sidebar":
             return { flexDirection: "row", gap: 1, flexGrow: 1, flexShrink: 1 };
         case "stack":

package/package.json

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

@@ -159,6 +159,17 @@ body {
 .vms-section--cards > .vms-section__heading {
   grid-column: 1 / -1;
 }
+/* minItem tokens (GRID-01) — promote the CSS-only `--vms-card-min` (the D-05
+   seam) to declared server intent. Each sets the custom property the auto-fit
+   cards rule above reads unchanged (xs→10rem, sm→13rem, md→16rem [= the default],
+   lg→20rem, xl→24rem), so a smaller token yields more, narrower columns and a
+   larger token fewer, wider ones. An OMITTED minItem emits no class, so the
+   inherited 16rem default holds = byte-identical to today. */
+.vms-cards-min--xs { --vms-card-min: 10rem; }
+.vms-cards-min--sm { --vms-card-min: 13rem; }
+.vms-cards-min--md { --vms-card-min: 16rem; }
+.vms-cards-min--lg { --vms-card-min: 20rem; }
+.vms-cards-min--xl { --vms-card-min: 24rem; }
 
 /* ── Layout preset: split (LAYOUT-02, D-06/D-07) ──
    Capped exactly-2-then-1, equal-width (shared 1fr max), zero media queries.
@@ -213,6 +224,97 @@ body {
 .vms-page--sidebar > .vms-page__title,
 .vms-section--sidebar > .vms-section__heading { flex: 0 0 100%; }
 
+/* ── Layout preset: row (D-30 / 1.11.0) — left-aligned wrapping horizontal row;
+   children hug their content (no forced grow), wrap to the next line on overflow.
+   The general horizontal-row primitive — a navbar composes from this + flyout.
+   Title/heading takes its own full-width row, like the other presets. gap
+   inherited from .vms-page/.vms-section — NOT redeclared. ── */
+.vms-page--row,
+.vms-section--row {
+  display: flex;
+  flex-direction: row;
+  flex-wrap: wrap;
+  align-items: center;
+}
+.vms-page--row > .vms-page__title,
+.vms-section--row > .vms-section__heading { flex: 0 0 100%; }
+
+/* ── Fits container (FITS-01 / Phase 10). STRUCTURAL selector (not visual
+   layout): a full-width block so its observed width reflects the available
+   space (parent-driven), which both (a) makes measurement correct and (b)
+   prevents a measure→resize feedback loop. The candidate SELECTION is done in
+   the renderer (browser.ts), not in CSS. ── */
+.vms-fits { display: block; }
+
+/* ── Alignment: arrange (main axis → justify-content) / align (cross axis →
+   align-items) (ALIGN-01/02/03 / 1.12.0). Intended for layout:"row" (the cluster
+   primitive) but these are generic box-alignment, so they're harmless on any flex
+   container. Closed enum sets copied from Jetpack Compose Arrangement ∩ Flutter
+   MainAxisAlignment (arrange) and Flutter CrossAxisAlignment (align). An OMITTED
+   field emits no class, so the row defaults (justify-content:flex-start /
+   align-items:center, both inherited from the .vms-*--row block above) hold =
+   byte-identical to today. ── */
+.vms-arrange--start         { justify-content: flex-start; }
+.vms-arrange--center        { justify-content: center; }
+.vms-arrange--end           { justify-content: flex-end; }
+.vms-arrange--space-between  { justify-content: space-between; }
+.vms-arrange--space-around   { justify-content: space-around; }
+.vms-arrange--space-evenly   { justify-content: space-evenly; }
+.vms-align--start    { align-items: flex-start; }
+.vms-align--center   { align-items: center; }
+.vms-align--end      { align-items: flex-end; }
+.vms-align--stretch  { align-items: stretch; }
+.vms-align--baseline { align-items: baseline; }
+
+/* ── Layout preset: switcher (SWITCH-01/02 / 1.13.0) — the Every-Layout Switcher,
+   zero @media. N equal items flip all-row ↔ all-stack ATOMICALLY via a negative
+   `flex-basis`: above the threshold the basis `(threshold - 100%) * 999` goes
+   hugely negative → clamped to 0 → all children share one row; below it the
+   basis goes hugely positive → each child claims a full line → all stack. No
+   intermediate partial-wrap state — that's the distinction from `cards`
+   auto-fit (which passes through intermediate column counts). Title/heading
+   keeps its own full-width row like the other presets. gap inherited from
+   .vms-page/.vms-section — NOT redeclared. An OMITTED threshold/limit emits no
+   class, so the `var(--vms-switch-threshold, 30rem)` default (30rem) + no count
+   cap hold = byte-identical to having no token. ── */
+.vms-page--switcher,
+.vms-section--switcher {
+  display: flex;
+  flex-direction: row;   /* override .vms-page/.vms-section base column — the
+                            negative-flex-basis flip operates on the MAIN axis,
+                            which MUST be horizontal or the children stack
+                            vertically forever (the trick never fires). */
+  flex-wrap: wrap;
+}
+.vms-page--switcher > *,
+.vms-section--switcher > * {
+  flex-grow: 1;
+  flex-basis: calc((var(--vms-switch-threshold, 30rem) - 100%) * 999);
+}
+.vms-page--switcher > .vms-page__title,
+.vms-section--switcher > .vms-section__heading { flex: 0 0 100%; }
+
+/* threshold tokens — each sets the custom property the basis calc reads
+   (sm→20rem, md→30rem, lg→40rem, xl→48rem; md == the 30rem default). */
+.vms-switch--sm { --vms-switch-threshold: 20rem; }
+.vms-switch--md { --vms-switch-threshold: 30rem; }
+.vms-switch--lg { --vms-switch-threshold: 40rem; }
+.vms-switch--xl { --vms-switch-threshold: 48rem; }
+
+/* limit (max-per-row count cap) — a quantity query per allowed n (2..8). The
+   `:nth-last-child(n+{n+1})` selector matches every child ONLY when there are
+   MORE than n of them (a switcher with exactly `limit` children stays on one
+   row; the cap engages on overflow). The matched children get
+   `flex-basis:100%`, overriding the negative-basis calc above to force each
+   onto its own full-width line regardless of container width. */
+.vms-switch-limit--2 > :nth-last-child(n+3),  .vms-switch-limit--2 > :nth-last-child(n+3) ~ * { flex-basis: 100%; }
+.vms-switch-limit--3 > :nth-last-child(n+4),  .vms-switch-limit--3 > :nth-last-child(n+4) ~ * { flex-basis: 100%; }
+.vms-switch-limit--4 > :nth-last-child(n+5),  .vms-switch-limit--4 > :nth-last-child(n+5) ~ * { flex-basis: 100%; }
+.vms-switch-limit--5 > :nth-last-child(n+6),  .vms-switch-limit--5 > :nth-last-child(n+6) ~ * { flex-basis: 100%; }
+.vms-switch-limit--6 > :nth-last-child(n+7),  .vms-switch-limit--6 > :nth-last-child(n+7) ~ * { flex-basis: 100%; }
+.vms-switch-limit--7 > :nth-last-child(n+8),  .vms-switch-limit--7 > :nth-last-child(n+8) ~ * { flex-basis: 100%; }
+.vms-switch-limit--8 > :nth-last-child(n+9),  .vms-switch-limit--8 > :nth-last-child(n+9) ~ * { flex-basis: 100%; }
+
 /* ── Section variant: card (THEME-04) — grouped surface, existing seam vars ── */
 .vms-section--card {
   background: var(--vms-surface);
@@ -271,6 +373,57 @@ body {
   outline-offset: 2px;
 }
 
+/* ── Section: flyout (1.11.0 — overlay disclosure, the hover/focus sibling of
+   collapsible) ── The heading renders as a focusable .vms-section__trigger button;
+   the children are wrapped in an absolutely-positioned .vms-section__panel revealed
+   on :hover / :focus-within. Pure CSS — hover (desktop), tap-to-focus (touch), and
+   Tab-to-trigger (keyboard a11y) all reveal it; it hides on blur / pointer-leave.
+   No JS, no round-tripped open state. The panel overlays (out of flow) so a flyout
+   inside a .vms-section--row bar does not reflow its siblings. */
+.vms-section--flyout {
+  position: relative;
+  flex-direction: column;   /* trigger stacks above the (absolute) panel; wrapper hugs the trigger */
+  align-items: flex-start;
+}
+.vms-section__trigger {
+  font-size: var(--vms-text-xs);
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--vms-text-muted);
+  cursor: pointer;
+  background: none;
+  border: none;
+  padding: 0;
+  font-family: inherit;
+}
+.vms-section__trigger:focus-visible {
+  outline: 2px solid var(--vms-accent);
+  outline-offset: 2px;
+}
+.vms-section__panel {
+  position: absolute;
+  top: 100%;
+  left: 0;
+  z-index: 50;
+  min-width: max-content;
+  display: flex;
+  flex-direction: column;
+  gap: var(--vms-space-sm);
+  margin-top: var(--vms-space-xs);
+  padding: var(--vms-space-sm);
+  background: var(--vms-surface);
+  border: 1px solid var(--vms-border);
+  border-radius: var(--vms-radius);
+  visibility: hidden;
+  opacity: 0;
+  transition: opacity var(--vms-t);
+}
+.vms-section--flyout:hover > .vms-section__panel,
+.vms-section--flyout:focus-within > .vms-section__panel {
+  visibility: visible;
+  opacity: 1;
+}
+
 /* ── Stat bar ── */
 .vms-stat-bar { display: flex; gap: var(--vms-space-lg); flex-wrap: wrap; }
 .vms-stat-bar__item { display: flex; align-items: baseline; gap: var(--vms-space-xs); }