@ashley-shrok/viewmodel-shell 0.15.0 → 0.16.0

package/dist/browser.d.ts

@@ -10,6 +10,11 @@ export declare class BrowserAdapter implements Adapter {
      *  contentType is informational — the Blob's own .type takes precedence in
      *  browsers. We accept the arg for adapter symmetry (other adapters use it). */
     saveFile(data: Blob, filename: string, _contentType: string): void;
+    /** 0.16.0 — toggle the `.vms-busy` class on the container. Default CSS makes
+     *  every interactive descendant non-clickable (cursor:wait + pointer-events:
+     *  none), so a rapid checkbox click during a round-trip never visually flips
+     *  the box. Idempotent (classList.toggle with a force value). */
+    setBusy(active: boolean): void;
     /** 0.14.0 — install / clear the browser's `beforeunload` guard. The shell
      *  calls this on every response with `response.preventUnload ?? false`, so
      *  the lock-and-clear cycle is just "server sets preventUnload:true while

package/dist/browser.js

@@ -105,6 +105,13 @@ export class BrowserAdapter {
             setTimeout(() => URL.revokeObjectURL(url), 0);
         }
     }
+    /** 0.16.0 — toggle the `.vms-busy` class on the container. Default CSS makes
+     *  every interactive descendant non-clickable (cursor:wait + pointer-events:
+     *  none), so a rapid checkbox click during a round-trip never visually flips
+     *  the box. Idempotent (classList.toggle with a force value). */
+    setBusy(active) {
+        this.container.classList.toggle("vms-busy", active);
+    }
     /** 0.14.0 — install / clear the browser's `beforeunload` guard. The shell
      *  calls this on every response with `response.preventUnload ?? false`, so
      *  the lock-and-clear cycle is just "server sets preventUnload:true while

package/dist/index.d.ts

@@ -42,6 +42,16 @@ export interface Adapter {
      *  targets (TUI) have no terminal equivalent. Modern browsers show a
      *  generic "Leave site?" dialog; the message is not customizable. */
     setPreventUnload?(active: boolean): void;
+    /** 0.16.0 — visually lock the UI during periods where user dispatches will
+     *  be dropped. Called by the shell on every transition with `active = true`
+     *  when EITHER a user-initiated dispatch is in flight OR the server returned
+     *  `ShellResponse.busy: true` on its most recent response. Polls (silent
+     *  dispatches) bypass — they're the only way out of a server-busy state.
+     *  `BrowserAdapter` toggles `.vms-busy` on its container; default CSS makes
+     *  every interactive descendant non-clickable (cursor: wait + pointer-events:
+     *  none), so a rapid checkbox click during an in-flight round-trip never
+     *  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 interface PageNode {
@@ -324,6 +334,10 @@ export interface ShellResponse {
      *  `preventUnload: true` from each response; clear it when the work
      *  completes (typically via polling). See `Adapter.setPreventUnload`. */
     preventUnload?: boolean;
+    /** 0.16.0 — when true, the shell locks the UI (drops user-initiated
+     *  dispatches; the adapter applies `.vms-busy` for the visual cue). Polls
+     *  bypass so the server can clear the state. See `Adapter.setBusy`. */
+    busy?: boolean;
 }
 export declare class ViewModelShell {
     private options;
@@ -331,7 +345,10 @@ export declare class ViewModelShell {
     private currentState;
     private dispatching;
     private pollTimer;
+    private serverBusy;
+    private userDispatching;
     constructor(options: ShellOptions);
+    private syncBusy;
     load(params?: Record<string, string>): Promise<void>;
     dispatch(action: ActionEvent, silent?: boolean): Promise<void>;
     /** Feed a pre-parsed ShellResponse into the shell — for SSE/WebSocket integrations. */

package/dist/index.js

@@ -5,9 +5,18 @@ export class ViewModelShell {
     currentState = null;
     dispatching = false;
     pollTimer = null;
+    // 0.16.0 — busy = serverBusy OR a user-initiated dispatch is in flight.
+    // Polls (silent=true dispatches) don't flip userDispatching so they never
+    // toggle the busy class — that's how a server-busy state stays continuously
+    // locked across many ticks without flicker.
+    serverBusy = false;
+    userDispatching = false;
     constructor(options) {
         this.options = options;
     }
+    syncBusy() {
+        this.options.adapter.setBusy?.(this.serverBusy || this.userDispatching);
+    }
     async load(params) {
         const { endpoint, adapter, onError, onLoading } = this.options;
         this.stopPolling();
@@ -25,6 +34,9 @@ export class ViewModelShell {
             // server may legitimately want it on at first paint (e.g. the page was
             // refreshed mid-work and the long action is still pending server-side).
             adapter.setPreventUnload?.(body.preventUnload ?? false);
+            // 0.16.0 — same for the busy lockout.
+            this.serverBusy = body.busy ?? false;
+            this.syncBusy();
             adapter.render(body.vm, (action) => this.dispatch(action));
             this.schedulePoll(body.nextPollIn);
         }
@@ -37,6 +49,10 @@ export class ViewModelShell {
         }
     }
     async dispatch(action, silent = false) {
+        // 0.16.0 — drop user-initiated dispatches while server-busy. Polls (silent)
+        // bypass so the server can clear the busy state.
+        if (!silent && this.serverBusy)
+            return;
         if (this.dispatching)
             return;
         const { actionEndpoint, onError, onLoading } = this.options;
@@ -48,8 +64,16 @@ export class ViewModelShell {
         }
         try {
             this.dispatching = true;
-            if (!silent)
+            if (!silent) {
+                // 0.16.0 — flag a user dispatch as in-flight + apply .vms-busy. This
+                // is what kills the "rapid clicks during a round-trip silently flip the
+                // checkbox" UX bug: by the time the user's second click arrives, the
+                // container has pointer-events: none and the click never reaches the
+                // input.
+                this.userDispatching = true;
+                this.syncBusy();
                 onLoading?.(true);
+            }
             const form = new FormData();
             form.append("_action", JSON.stringify({ name: action.name, context: action.context ?? {} }));
             form.append("_state", JSON.stringify(this.currentState));
@@ -93,8 +117,11 @@ export class ViewModelShell {
         }
         finally {
             this.dispatching = false;
-            if (!silent)
+            if (!silent) {
+                this.userDispatching = false;
+                this.syncBusy();
                 onLoading?.(false);
+            }
         }
     }
     /** Feed a pre-parsed ShellResponse into the shell — for SSE/WebSocket integrations. */
@@ -147,6 +174,9 @@ export class ViewModelShell {
         // wants a redirect to NOT be blocked by its own guard simply omits
         // preventUnload (or sets it false) on that response — standard pattern.
         adapter.setPreventUnload?.(body.preventUnload ?? false);
+        // 0.16.0 — likewise for the busy lockout.
+        this.serverBusy = body.busy ?? false;
+        this.syncBusy();
         if (body.redirect) {
             if (this.options.onRedirect) {
                 this.options.onRedirect(body.redirect);

package/dist/server.d.ts

@@ -22,6 +22,12 @@ export interface ShellResponseBody<TState> {
      *  (or set false) to clear; set true while a long-running server action is
      *  in flight so an accidental tab-close doesn't lose work. */
     preventUnload?: boolean;
+    /** 0.16.0 — lock the UI: the shell drops user-initiated dispatches client-
+     *  side and the BrowserAdapter applies `.vms-busy` (cursor:wait + pointer-
+     *  events:none on interactive descendants). Polls bypass so the server can
+     *  clear the state. Naturally paired with `preventUnload` for long-running
+     *  server actions. */
+    busy?: boolean;
 }
 /** Build a redirect response (Vm and State omitted; shell navigates the browser). */
 export declare function shellRedirect<TState = unknown>(url: string): ShellResponseBody<TState>;

package/package.json

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

@@ -649,6 +649,18 @@ select.vms-field__input  { cursor: pointer; padding-right: var(--vms-space-xl);
 .vms-table__pagination-btn { padding: var(--vms-space-xs) var(--vms-space-sm); font-size: var(--vms-text-sm); }
 .vms-table__pagination-btn:disabled { opacity: 0.45; cursor: default; }
 
+/* 0.16.0 — `.vms-busy` is applied by BrowserAdapter when the shell is in a
+   busy state (a user-initiated dispatch is in flight OR the server returned
+   ShellResponse.busy: true). cursor: wait communicates the state; pointer-
+   events: none on interactive descendants makes the lock honest — rapid
+   clicks during a round-trip never visually flip checkboxes / depress buttons
+   because the click never reaches them. Polls (silent dispatches) bypass the
+   class so a long-running action stays continuously locked across many ticks
+   without flickering. */
+.vms-busy { cursor: wait; }
+.vms-busy a, .vms-busy button, .vms-busy input, .vms-busy textarea,
+.vms-busy select, .vms-busy [role="button"], .vms-busy [data-id] { pointer-events: none; }
+
 /* ── Recommended error-banner pattern ──
    Apps typically render this from the `onError` callback. Not emitted by
    the framework; included here so apps can use the convention without