@ashley-shrok/viewmodel-shell 3.6.2 → 3.8.0

package/agent-skill.md

@@ -63,6 +63,7 @@ Optional success-path fields, which may appear alone or alongside `vm`/`state`:
 | `busy` | Boolean. While `true`, drop user-initiated dispatches. Polls bypass. The next response that omits or sets `false` clears the lock. |
 | `preventUnload` | Boolean. While `true`, treat the page as having unsaved work — warn before navigating away. |
 | `rejected` | A SOFT (domain/validation) rejection — see below. The action was refused, but `vm`/`state` are still returned. |
+| `serverBuild` | A string id of the client bundle the server currently deploys. Present only when the app enables versioning. If you advertise your own build via the `X-VMS-Client-Build` request header and it differs from `serverBuild`, you are running against a rolled-forward server — see *Client build / version skew*. |
 
 **Failure:**
 
@@ -115,9 +116,17 @@ Optional success-path fields, which may appear alone or alongside `vm`/`state`:
 | `unknown_action` | The `name` in your action envelope does not match any handler in the current tree. |
 | `invalid_tree` | The server built a tree that violates a wire invariant (this is a server bug, not yours). |
 | `uncaught_exception` | The action handler threw. Treat as a 500-class failure. |
+| `stale_client` | Your request advertised an `X-VMS-Client-Build` header that no longer matches the server's current deployed build. The mutation was rejected **before your `_state` was read — nothing was applied.** The fix is to reload to the current app (re-`GET` the endpoint for a fresh `vm`/`state`), not to retry the same request. See *Client build / version skew*. |
 
 Stop on `ok: false`. Surface the message to the user. Do not retry blindly — most of these are deterministic.
 
+## Client build / version skew
+
+Optional, opt-in. When the app enables versioning, every response carries a `serverBuild` string (the client bundle the server currently deploys), and you may advertise the build you are running by sending an `X-VMS-Client-Build: <your-build-id>` header on every action POST.
+
+- **Detection.** On any successful response, if you sent a build and `serverBuild` differs from it, the server has rolled forward while you kept running an old bundle. Reload to the current app (re-`GET` the endpoint) so you are driving the current tree.
+- **Fail-closed guard.** If you send a mismatching `X-VMS-Client-Build`, a *mutating* action is rejected with `ok: false`, HTTP 400, `code: "stale_client"` — **before** your `_state` is deserialized, so nothing is applied. Do not retry the same request against the same build; reload first. If you do NOT send the header, no request is ever rejected on this basis (the guard only fires for a client that advertised a stale build).
+
 ## Auth
 
 The wire does not mandate an auth shape. If the app needs credentials, the app preamble above (or its own README) names them. Common patterns: a `Bearer` token in `Authorization`, a CSRF/anti-forgery token in a custom header, a session cookie. Send the same headers on every request, including polls and downloads. The `download` side-effect re-presents your auth headers when the agent fetches the file.

package/dist/browser.d.ts

@@ -12,6 +12,13 @@ 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;
+    /** 3.8.0 — force a full page reload. The shell calls this as the fail-closed
+     *  recovery for a `stale_client` rejection (a mutation refused because this
+     *  tab is running an out-of-date bundle). `window.location.reload()` pulls the
+     *  fresh, cache-revalidated shell + bundle. Fail-quiet by absence in core (the
+     *  `stale_client` VmsActionError already surfaced via onError), so this is a
+     *  plain implementation, not a fail-loud capability. */
+    reload(): 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

package/dist/browser.js

@@ -36,6 +36,12 @@ const noopStateAccess = {
     read: () => undefined,
     write: () => { },
 };
+// SectionNode.followTail — a `[data-follow-tail]` element counts as "at the
+// bottom" (and should stay pinned to the newest content on re-render) when it
+// is within this many pixels of the bottom. A small tolerance so sub-pixel
+// rounding and being ~a line off the bottom still counts as "following"; scroll
+// up past it and the adapter respects the user reading history instead.
+const FOLLOW_TAIL_STICK_THRESHOLD_PX = 40;
 export class BrowserAdapter {
     container;
     fileRegistry = new Map();
@@ -74,9 +80,26 @@ export class BrowserAdapter {
         const winScrollY = window.scrollY;
         const scrollMap = new Map();
         this.container.querySelectorAll("[id]").forEach(el => {
+            // follow-tail elements own their own restore (see below) — the generic
+            // preserve-the-prior-scrollTop contract is exactly what they must NOT do.
+            if (el.hasAttribute("data-follow-tail"))
+                return;
             if (el.scrollTop !== 0 || el.scrollLeft !== 0)
                 scrollMap.set(el.id, { top: el.scrollTop, left: el.scrollLeft });
         });
+        // SectionNode.followTail — snapshot, in document order, whether each
+        // append-only feed was scrolled near its bottom (and its prior scrollTop
+        // for the scrolled-up case). Ordinal-matched to the post-render walk below,
+        // the same stable-order approach as the collapsible-section snapshot; a
+        // brand-new feed has no entry at its ordinal and is pinned to the bottom.
+        const followTail = [];
+        this.container.querySelectorAll("[data-follow-tail]").forEach(el => {
+            const distanceFromBottom = el.scrollHeight - el.scrollTop - el.clientHeight;
+            followTail.push({
+                nearBottom: distanceFromBottom <= FOLLOW_TAIL_STICK_THRESHOLD_PX,
+                top: el.scrollTop,
+            });
+        });
         // 1.2.0 — snapshot collapsible-section open state by stable key. Same
         // pattern as focusId/scrollMap above: capture before innerHTML wipe, walk
         // the rebuilt tree after node() returns, restore matching keys. Reset
@@ -116,6 +139,19 @@ export class BrowserAdapter {
                 el.scrollLeft = left;
             }
         });
+        // SectionNode.followTail restore — runs AFTER the generic scrollMap restore
+        // so it wins on any element carrying both an id and data-follow-tail. Walk
+        // the rebuilt feeds in document order and match them to the pre-render
+        // snapshot by ordinal: a feed that WAS near the bottom (or is brand new, no
+        // snapshot at its ordinal) is pinned to the NEW bottom so freshly appended
+        // content is visible; a feed the user had scrolled up in keeps its place.
+        this.container.querySelectorAll("[data-follow-tail]").forEach((el, i) => {
+            const snap = followTail[i];
+            if (!snap || snap.nearBottom)
+                el.scrollTop = el.scrollHeight;
+            else
+                el.scrollTop = snap.top;
+        });
         // Only restore window scroll when the page was actually scrolled — restoring
         // to (0,0) is a no-op, and skipping it avoids jsdom's noisy "Not implemented:
         // window.scrollTo" virtual-console log in unit tests (jsdom never scrolls, so
@@ -162,6 +198,15 @@ export class BrowserAdapter {
     setBusy(active) {
         this.container.classList.toggle("vms-busy", active);
     }
+    /** 3.8.0 — force a full page reload. The shell calls this as the fail-closed
+     *  recovery for a `stale_client` rejection (a mutation refused because this
+     *  tab is running an out-of-date bundle). `window.location.reload()` pulls the
+     *  fresh, cache-revalidated shell + bundle. Fail-quiet by absence in core (the
+     *  `stale_client` VmsActionError already surfaced via onError), so this is a
+     *  plain implementation, not a fail-loud capability. */
+    reload() {
+        window.location.reload();
+    }
     /** 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
@@ -474,6 +519,12 @@ export class BrowserAdapter {
         }
         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.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" : ""}`;
+        // SectionNode.followTail — mark this as an append-only feed so render()'s
+        // snapshot/restore keeps its newest content in view (see render() + the
+        // FOLLOW_TAIL_STICK_THRESHOLD_PX constant). No CSS/class — the scroll comes
+        // from the element already being an overflow region (pair with fill).
+        if (n.followTail === true)
+            el.dataset.followTail = "";
         if (n.heading) {
             const h = document.createElement("h2");
             h.className = "vms-section__heading";

package/dist/index.d.ts

@@ -74,6 +74,19 @@ export interface Adapter {
         tone?: string;
         durationMs?: number;
     }): void;
+    /** 3.8.0 — force a full reload of the running client (the browser adapter
+     *  calls `window.location.reload()`). The shell invokes this ONLY as the
+     *  fail-closed recovery for a `stale_client` rejection: the server refused a
+     *  mutation because the tab is running an out-of-date bundle, nothing was
+     *  applied, and reloading to the fresh bundle is the only honest recovery.
+     *  FAIL-QUIET BY ABSENCE — modeled on setBusy/toast, NOT on
+     *  navigate/storage/saveFile: the `stale_client` failure ALSO surfaces via
+     *  `onError` (as a VmsActionError), so an adapter without this verb still
+     *  learns of the skew and can recover its own way. A missing `reload` is
+     *  therefore NOT a silent failure, so the core MUST NOT call failCapability
+     *  when it is absent (non-browser targets like the TUI have no reload
+     *  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;
 export interface PageNode {
@@ -110,6 +123,8 @@ export interface SectionNode {
     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;
+    /** When true, this section is a "follow the tail" scroll region — an append-only feed that keeps its NEWEST content in view across re-renders, unless the user has scrolled up to read history. The general primitive for a growing transcript: a chat log above a pinned composer, a live `tail -f` log view, an activity/audit stream, streamed job output. It exists because the default scroll-preservation contract (0.7.1/#7 — restore the prior `scrollTop`) is INVERTED for a growing feed: the old bottom becomes mid-scroll once taller content is appended, so the newest content silently ends up off-screen. Pure client-side render behavior (the server stays stateless — scroll position never rides the wire): the BrowserAdapter records, before each re-render, whether this element was within a small threshold of the bottom; after the re-render it pins a near-bottom element to the NEW bottom (`scrollTop = scrollHeight`) and leaves a scrolled-up element exactly where the user parked it. The decision is a pure function of the feed's scroll position at render time — `render()` doesn't know (or care) what triggered it, so a background poll, an SSE push, and the user's own form submit all follow the same rule; a genuinely scrolled-up feed is never hijacked. (When a chat visibly jumps to the bottom on the user's OWN send, that's the send interaction scrolling to the bottom before the re-render — the standard "your message pulls you down" UX — which the feed then correctly reads as at-bottom, not a special case here.) A brand-new follow-tail section starts pinned to the bottom (opens at the latest message). Emits `data-follow-tail` (no CSS — the scroll comes from the element already being an overflow region), so it's meant to pair with `fill` (which provides the internal `overflow-y:auto`) or any app that makes the section scroll; on a non-scrolling element it's an inert no-op. Orthogonal to `fill` and `layout`. The TUI ignores it (terminals follow naturally). Absent/false = byte-identical to today's preserve-my-place restore. */
+    followTail?: 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}. */
@@ -618,6 +633,16 @@ export interface ShellOptions {
      *  The server can override the next interval via ShellResponse.nextPollIn, or stop polling by
      *  omitting nextPollIn when no pollInterval is configured. */
     pollInterval?: number;
+    /** 3.8.0 — the id of the client bundle this shell instance is running (the app
+     *  injects it at build time, e.g. from a Vite `define`/env — VMS never derives
+     *  it, staying platform-agnostic). When set, the shell (1) attaches it as the
+     *  `X-VMS-Client-Build` header on every action POST so the server can
+     *  fail-closed on a stale mutation, and (2) compares it against a response's
+     *  `serverBuild` and fires a `VmsVersionSkewError` via `onError` when they
+     *  differ (AFTER rendering — detection never swallows the render). Absent =
+     *  the whole version-skew feature is off; behavior is byte-identical to a
+     *  build without it. */
+    clientBuildId?: string;
 }
 export interface ShellSideEffect {
     /** "set-local-storage" | "set-session-storage" | "download" | "toast" — unknown types are silently ignored. */
@@ -669,6 +694,23 @@ export declare class VmsActionError extends Error {
     /** Shortcut to `errors[0]?.code`. Undefined when the first entry has no code. */
     get code(): string | undefined;
 }
+/**
+ * 3.8.0 — surfaced via `onError` when a SUCCESS response's `serverBuild` differs
+ * from the configured `ShellOptions.clientBuildId` (client/server version skew:
+ * a long-lived tab is running an out-of-date bundle against a server that has
+ * rolled forward). This is fired AFTER the response renders normally — it never
+ * swallows the render — so it is a loud, catchable signal, not a failure. The
+ * app distinguishes it with `if (err instanceof VmsVersionSkewError)` (typically
+ * to prompt the user to reload). Distinct from `VmsActionError`: this rides on a
+ * fully-successful `ok:true` response.
+ */
+export declare class VmsVersionSkewError extends Error {
+    readonly serverBuild: string;
+    readonly clientBuild: string;
+    /** Stable discriminator for this failure class (parallels VmsActionError.code). */
+    readonly code = "version_skew";
+    constructor(serverBuild: string, clientBuild: string);
+}
 export interface ShellResponse {
     vm: ViewNode;
     state: unknown;
@@ -696,6 +738,11 @@ export interface ShellResponse {
     ok?: boolean;
     /** 1.0.0 — structured error entries. Present when `ok: false`. */
     errors?: ErrorEntry[];
+    /** 3.8.0 — the server's current-deployed client-build id, stamped on every
+     *  response when the app configures versioning. Compared against
+     *  `ShellOptions.clientBuildId` to detect a never-reloaded tab running against
+     *  a rolled-forward server. Absent = the feature is off. */
+    serverBuild?: string;
 }
 export declare class ViewModelShell {
     private options;
@@ -745,6 +792,16 @@ export declare class ViewModelShell {
     private stateAccessForAdapter;
     private failCapability;
     private processResponse;
+    /**
+     * 3.8.0 — Phase 1 detection. When the app configured `clientBuildId` and the
+     * response carries a differing `serverBuild`, fire a `VmsVersionSkewError`
+     * through the existing `onError` seam so the app can react (e.g. prompt a
+     * reload). Called from BOTH success paths (`load()` and `processResponse()`)
+     * AFTER the response has rendered — detection is additive and never affects
+     * the render. No-op when `clientBuildId` is unset, `serverBuild` is absent, or
+     * the two ids match.
+     */
+    private checkVersionSkew;
     private schedulePoll;
     /**
      * Authenticated download: fetch the URL with getRequestHeaders() merged

package/dist/index.js

@@ -36,6 +36,29 @@ export class VmsActionError extends Error {
         return this.errors[0]?.code;
     }
 }
+/**
+ * 3.8.0 — surfaced via `onError` when a SUCCESS response's `serverBuild` differs
+ * from the configured `ShellOptions.clientBuildId` (client/server version skew:
+ * a long-lived tab is running an out-of-date bundle against a server that has
+ * rolled forward). This is fired AFTER the response renders normally — it never
+ * swallows the render — so it is a loud, catchable signal, not a failure. The
+ * app distinguishes it with `if (err instanceof VmsVersionSkewError)` (typically
+ * to prompt the user to reload). Distinct from `VmsActionError`: this rides on a
+ * fully-successful `ok:true` response.
+ */
+export class VmsVersionSkewError extends Error {
+    serverBuild;
+    clientBuild;
+    /** Stable discriminator for this failure class (parallels VmsActionError.code). */
+    code = "version_skew";
+    constructor(serverBuild, clientBuild) {
+        super(`Client build "${clientBuild}" is out of date — the server is now serving ` +
+            `build "${serverBuild}". Reload to get the current app.`);
+        this.serverBuild = serverBuild;
+        this.clientBuild = clientBuild;
+        this.name = "VmsVersionSkewError";
+    }
+}
 export class ViewModelShell {
     options;
     currentVm = null;
@@ -92,6 +115,10 @@ export class ViewModelShell {
             this.syncBusy();
             adapter.render(body.vm, (action) => this.dispatch(action), this.stateAccessForAdapter());
             this.schedulePoll(body.nextPollIn);
+            // 3.8.0 — version-skew DETECTION (Phase 1). Render happened above FIRST;
+            // this only fires a loud, catchable signal and never affects the render.
+            // At initial load the ids normally match (fresh bundle) so it's a no-op.
+            this.checkVersionSkew(body);
         }
         catch (err) {
             const error = err instanceof Error ? err : new Error(String(err));
@@ -140,9 +167,15 @@ export class ViewModelShell {
             }
             const extraHeaders = this.options.getRequestHeaders ? await this.options.getRequestHeaders() : {};
             const adapter = this.options.adapter;
+            // 3.8.0 — Phase 2 fail-closed guard: advertise the running bundle id so the
+            // server can reject a mutation from a stale client BEFORE deserializing
+            // _state. Merged AFTER getRequestHeaders() so app headers can't clobber it.
+            const headers = { Accept: "application/json", ...extraHeaders };
+            if (this.options.clientBuildId)
+                headers["X-VMS-Client-Build"] = this.options.clientBuildId;
             const init = {
                 method: "POST",
-                headers: { Accept: "application/json", ...extraHeaders },
+                headers,
                 body: form,
             };
             let res;
@@ -179,6 +212,17 @@ export class ViewModelShell {
         catch (err) {
             const error = err instanceof Error ? err : new Error(String(err));
             onError ? onError(error) : console.error("[ViewModelShell]", error);
+            // 3.8.0 — Phase 2 fail-closed recovery. The server rejected this mutation
+            // because the tab is running a stale bundle (nothing was applied). Order
+            // per the locked design: surface via onError FIRST (done above), THEN
+            // force a reload to the fresh bundle — the only safe recovery. reload is
+            // fail-quiet by absence (the VmsActionError already surfaced), so this is
+            // a plain optional-chain call, and we return before the below re-render
+            // (the page is reloading; re-rendering the stale tree is pointless).
+            if (error instanceof VmsActionError && error.code === "stale_client") {
+                this.options.adapter.reload?.();
+                return;
+            }
             // 0.8.0 (#11) — re-render the current VM on dispatch error. Adapters
             // may have applied client-side ephemeral state in onAction handlers
             // (e.g., BrowserAdapter swaps button text for ButtonNode.pendingLabel).
@@ -337,6 +381,27 @@ export class ViewModelShell {
             this.currentState = body.state;
         }
         this.schedulePoll(body.nextPollIn);
+        // 3.8.0 — version-skew DETECTION (Phase 1) on the dispatch / poll / push
+        // success path. Fired AFTER the render above (never swallows it). A redirect
+        // response returned early above, so this is the non-redirect path only.
+        this.checkVersionSkew(body);
+    }
+    /**
+     * 3.8.0 — Phase 1 detection. When the app configured `clientBuildId` and the
+     * response carries a differing `serverBuild`, fire a `VmsVersionSkewError`
+     * through the existing `onError` seam so the app can react (e.g. prompt a
+     * reload). Called from BOTH success paths (`load()` and `processResponse()`)
+     * AFTER the response has rendered — detection is additive and never affects
+     * the render. No-op when `clientBuildId` is unset, `serverBuild` is absent, or
+     * the two ids match.
+     */
+    checkVersionSkew(body) {
+        const clientBuild = this.options.clientBuildId;
+        const serverBuild = body.serverBuild;
+        if (clientBuild && serverBuild && serverBuild !== clientBuild) {
+            const err = new VmsVersionSkewError(serverBuild, clientBuild);
+            this.options.onError ? this.options.onError(err) : console.error("[ViewModelShell]", err);
+        }
     }
     schedulePoll(nextPollIn) {
         const delay = nextPollIn ?? this.options.pollInterval;

package/dist/server.d.ts

@@ -62,6 +62,12 @@ export interface ShellResponseBody<TState> {
      *  ErrorEntry {path?, message, code?} shape; `path` is OPTIONAL — a violation
      *  with no path is a form/action-level rejection (vs field-bound when set). */
     rejected?: ShellRejection;
+    /** 3.8.0 — the server's current-deployed client-build id. Normally stamped
+     *  automatically by `createAction(handler, { currentBuild })`; also settable
+     *  by hand on a response built outside createAction (e.g. a GET handler or a
+     *  server-pushed SSE/WebSocket body) so those responses carry `serverBuild`
+     *  too. Absent = the versioning feature is off for this response. */
+    serverBuild?: string;
 }
 /** Wrapper for a soft-validation rejection on an ok:true response. */
 export interface ShellRejection {
@@ -207,6 +213,10 @@ export declare const ERR_CODES: {
     readonly INVALID_TREE: "invalid_tree";
     /** App handler threw an unrecognised exception. HTTP 500. */
     readonly UNCAUGHT: "uncaught_exception";
+    /** 3.8.0 — request's `X-VMS-Client-Build` header ≠ the server's current-deployed
+     *  build id (a stale, never-reloaded tab attempting a mutation). The request is
+     *  rejected BEFORE `_state` is deserialized. HTTP 400. */
+    readonly STALE_CLIENT: "stale_client";
 };
 /** Union type of the framework error codes from ERR_CODES. Useful for narrowing `errors[0].code`. */
 export type ErrCode = typeof ERR_CODES[keyof typeof ERR_CODES];
@@ -224,5 +234,19 @@ export type ErrCode = typeof ERR_CODES[keyof typeof ERR_CODES];
  *     const state = applyAction(payload);
  *     return { vm: buildVm(state), state };
  *   }));
+ *
+ * 3.8.0 — optional version-skew half. Pass `{ currentBuild }` (the id of the
+ * client bundle this server currently deploys) to opt in:
+ *   - GUARD (fail-closed): if the request carries an `X-VMS-Client-Build` header
+ *     whose value ≠ `currentBuild`, the mutation is rejected with a 400
+ *     `stale_client` envelope BEFORE the body/`_state` is deserialized (the
+ *     app's typed handler never runs on a stale client's payload).
+ *   - STAMP: every successful response includes `serverBuild: currentBuild` so
+ *     the client can detect a never-reloaded tab.
+ * Omit `currentBuild` (or pass nothing) and behavior is byte-identical to
+ * before — no guard, no stamp. The existing handler-only call signature is
+ * unchanged.
  */
-export declare function createAction<TState>(handler: (payload: ActionPayload<TState>) => Promise<ShellResponseBody<TState>> | ShellResponseBody<TState>): (request: Request) => Promise<Response>;
+export declare function createAction<TState>(handler: (payload: ActionPayload<TState>) => Promise<ShellResponseBody<TState>> | ShellResponseBody<TState>, options?: {
+    currentBuild?: string;
+}): (request: Request) => Promise<Response>;

package/dist/server.js

@@ -574,6 +574,10 @@ export const ERR_CODES = {
     INVALID_TREE: "invalid_tree",
     /** App handler threw an unrecognised exception. HTTP 500. */
     UNCAUGHT: "uncaught_exception",
+    /** 3.8.0 — request's `X-VMS-Client-Build` header ≠ the server's current-deployed
+     *  build id (a stale, never-reloaded tab attempting a mutation). The request is
+     *  rejected BEFORE `_state` is deserialized. HTTP 400. */
+    STALE_CLIENT: "stale_client",
 };
 /**
  * Build a JSON-stringified `{ok: false, errors: [...]}` envelope.
@@ -623,9 +627,35 @@ function jsonResponse(body, status) {
  *     const state = applyAction(payload);
  *     return { vm: buildVm(state), state };
  *   }));
+ *
+ * 3.8.0 — optional version-skew half. Pass `{ currentBuild }` (the id of the
+ * client bundle this server currently deploys) to opt in:
+ *   - GUARD (fail-closed): if the request carries an `X-VMS-Client-Build` header
+ *     whose value ≠ `currentBuild`, the mutation is rejected with a 400
+ *     `stale_client` envelope BEFORE the body/`_state` is deserialized (the
+ *     app's typed handler never runs on a stale client's payload).
+ *   - STAMP: every successful response includes `serverBuild: currentBuild` so
+ *     the client can detect a never-reloaded tab.
+ * Omit `currentBuild` (or pass nothing) and behavior is byte-identical to
+ * before — no guard, no stamp. The existing handler-only call signature is
+ * unchanged.
  */
-export function createAction(handler) {
+export function createAction(handler, options) {
+    const currentBuild = options?.currentBuild;
     return async (request) => {
+        // 3.8.0 — fail-closed stale-client guard. Runs FIRST, before any body parse,
+        // so a stale client's `_state` is never deserialized. Only when the app
+        // configured `currentBuild` AND the header is present AND it mismatches.
+        if (currentBuild) {
+            const clientBuild = request.headers.get("x-vms-client-build");
+            if (clientBuild !== null && clientBuild !== currentBuild) {
+                return jsonResponse(errorEnvelope([{
+                        message: `Stale client: request build "${clientBuild}" does not match the ` +
+                            `current deployed build "${currentBuild}". Reload to continue.`,
+                        code: ERR_CODES.STALE_CLIENT,
+                    }]), 400);
+            }
+        }
         const contentType = request.headers.get("content-type") ?? "";
         let payload;
         try {
@@ -676,6 +706,12 @@ export function createAction(handler) {
         }
         // Phase 07 / ERROR-01 — every successful response acquires ok:true at the
         // response edge. Controllers / app handlers do NOT set ok themselves.
-        return jsonResponse(JSON.stringify({ ok: true, ...result }), 200);
+        // 3.8.0 — stamp serverBuild when versioning is configured. Placed after the
+        // result spread so `currentBuild` wins over any hand-set result.serverBuild.
+        return jsonResponse(JSON.stringify({
+            ok: true,
+            ...result,
+            ...(currentBuild ? { serverBuild: currentBuild } : {}),
+        }), 200);
     };
 }

package/package.json

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