@ashley-shrok/viewmodel-shell 3.5.0 → 3.6.1

package/dist/browser.js

@@ -293,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";
@@ -405,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.
@@ -429,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.
@@ -473,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";

package/dist/index.d.ts

@@ -83,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}. */
@@ -106,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}. */

package/package.json

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

package/styles/default.css

@@ -144,6 +144,31 @@ 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; }
+/* Fill makes the host's <body> margin load-bearing: the base `body` rule above
+   deliberately leaves margin to the host (one-line `body{margin:0}` convention),
+   but a 100dvh page plus the UA's default 8px body margin overflows the viewport
+   (100dvh + 16px → ~16px of scroll, a clipped pinned footer). So when — and ONLY
+   when — a fill page is present, the framework owns the body reset itself. Scoped
+   via :has() so non-fill pages keep the existing host-owns-margin convention. */
+body:has(.vms-page--fill) { margin: 0; }
+/* Fill + sidebar composition: `.vms-page--sidebar` is `flex-wrap: wrap` (for the
+   breakpoint-free stacked collapse), so the flex LINE's cross-size is the children's
+   natural max, not the container's 100dvh. With `align: stretch` the children then
+   stretch to that natural max and burst the fill height (e.g. a long sidebar list
+   pushes the page past the viewport). Cap each child at the page height and let it
+   scroll internally instead. Scoped to fill+sidebar so no other layout is touched. */
+.vms-page--fill.vms-page--sidebar > * { max-height: 100%; overflow-y: auto; }
+
 /* ── Section ── */
 .vms-section { display: flex; flex-direction: column; gap: var(--vms-space-sm); }
 .vms-section__heading {