@ashley-shrok/viewmodel-shell 3.7.0 → 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

@@ -198,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

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 {
@@ -620,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. */
@@ -671,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;
@@ -698,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;
@@ -747,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.7.0",
+  "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",