@ashley-shrok/viewmodel-shell 0.14.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
@@ -674,24 +681,18 @@ export class BrowserAdapter {
             box.checked = allOnPage;
             box.indeterminate = someOnPage && !allOnPage;
             box.addEventListener("change", () => {
-                const selAction = sel.action;
-                if (selAction) {
-                    // Server-truth mode: dispatch; server re-renders with new selectedIds.
-                    on({ name: selAction.name, context: { ...(selAction.context ?? {}), all: true, checked: box.checked } });
-                }
-                else {
-                    // Local mode (0.13.0): toggle every row checkbox + class in this table
-                    // to match the header. No dispatch — the dispatch guard can't drop anything.
-                    const want = box.checked;
-                    table.querySelectorAll("tbody input.vms-table__select").forEach(rowBox => {
-                        if (rowBox.disabled)
-                            return;
-                        rowBox.checked = want;
-                        const tr = rowBox.closest(".vms-table__row");
-                        if (tr)
-                            tr.classList.toggle("vms-table__row--selected", want);
-                    });
-                }
+                // Toggle every row checkbox + class in this table to match the header.
+                // No dispatch — selection is purely DOM-local; bulk actions harvest the
+                // checked rows when a `selection.buttons[]` entry is clicked.
+                const want = box.checked;
+                table.querySelectorAll("tbody input.vms-table__select").forEach(rowBox => {
+                    if (rowBox.disabled)
+                        return;
+                    rowBox.checked = want;
+                    const tr = rowBox.closest(".vms-table__row");
+                    if (tr)
+                        tr.classList.toggle("vms-table__row--selected", want);
+                });
             });
             th.appendChild(box);
             headerRow.appendChild(th);
@@ -783,23 +784,18 @@ export class BrowserAdapter {
                     // data-id is what selection.buttons[] harvest reads on click.
                     box.dataset.id = rowId;
                     box.addEventListener("change", () => {
-                        const selAction = sel.action;
-                        if (selAction) {
-                            on({ name: selAction.name, context: { ...(selAction.context ?? {}), id: rowId, checked: box.checked } });
-                        }
-                        else {
-                            // Local mode (0.13.0): flip the row class to mirror the box, then
-                            // reconcile the header select-all (could now be all / some / none).
-                            tr.classList.toggle("vms-table__row--selected", box.checked);
-                            const headerBox = table.querySelector("thead input.vms-table__select--all");
-                            if (headerBox) {
-                                const all = table.querySelectorAll("tbody input.vms-table__select:not(:disabled)");
-                                let checked = 0;
-                                all.forEach(b => { if (b.checked)
-                                    checked++; });
-                                headerBox.checked = all.length > 0 && checked === all.length;
-                                headerBox.indeterminate = checked > 0 && checked < all.length;
-                            }
+                        // Flip the row class to mirror the box, then reconcile the header
+                        // select-all (could now be all / some / none). No dispatch — bulk
+                        // actions read the DOM via the selection.buttons[] harvest.
+                        tr.classList.toggle("vms-table__row--selected", box.checked);
+                        const headerBox = table.querySelector("thead input.vms-table__select--all");
+                        if (headerBox) {
+                            const all = table.querySelectorAll("tbody input.vms-table__select:not(:disabled)");
+                            let checked = 0;
+                            all.forEach(b => { if (b.checked)
+                                checked++; });
+                            headerBox.checked = all.length > 0 && checked === all.length;
+                            headerBox.indeterminate = checked > 0 && checked < all.length;
                         }
                     });
                 }

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 {
@@ -213,31 +223,19 @@ export interface TableRow {
     variant?: string;
 }
 export interface TableSelection {
-    /** Row ids that should render PRE-SELECTED on this render. In server-truth
-     *  mode (`action` set) this is the live selection, round-tripped in state and
-     *  authoritative every render. In local mode (`action` omitted) this is the
-     *  server's initial pre-selection only — subsequent toggles are purely
-     *  client-side DOM state and the server doesn't see them until a `buttons[]`
-     *  click harvests them. */
+    /** Row ids that should render PRE-SELECTED on initial render — the server's
+     *  initial pre-selection. Subsequent toggles are purely client-side DOM state;
+     *  the server doesn't see them until a `buttons[]` click harvests them. */
     selectedIds: string[];
-    /** OPTIONAL (0.13.0). When present: server-truth mode — every checkbox toggle
-     *  dispatches this action with merged `{ id, checked }` per row or
-     *  `{ all: true, checked }` for the header select-all (where "all" = the
-     *  rendered page). Selection survives sort/filter/pagination via the state
-     *  round-trip. When OMITTED: local mode — the adapter toggles the DOM
-     *  checkbox + `.vms-table__row--selected` class purely client-side with no
-     *  dispatch. Local mode is the recommended pattern for rapid-selection
-     *  workflows (no dropped clicks under the dispatch guard); see `buttons` for
-     *  how bulk actions read the resulting selection. */
-    action?: ActionEvent;
-    /** OPTIONAL (0.13.0). When present, the adapter renders these as a bulk-action
-     *  toolbar ABOVE the table. On click, each button harvests the currently
-     *  checked rows from the DOM and dispatches its `action` with
-     *  `{ selectedIds: [...] }` merged into its `context`. Designed primarily to
-     *  pair with local mode (`action` absent) — it's how the server learns the
-     *  selection without a per-toggle round-trip — but works in server-truth mode
-     *  too (the harvest matches `selectedIds` since the DOM reflects server-truth
-     *  after each render). */
+    /** When present, the adapter renders these as a bulk-action toolbar ABOVE
+     *  the table. On click, each button harvests the currently-checked rows from
+     *  the DOM and dispatches its `action` with `{ selectedIds: [...] }` merged
+     *  into its `context`. This is the only way to act on the selection — there
+     *  is no per-toggle dispatch (0.15.0 removed the `action` mode that did,
+     *  because rapid clicks were dropped by the dispatch guard and the in-flight
+     *  response wiped the DOM). If a future release needs cross-page persistence
+     *  or live "N selected" indicators, the way back is a redesigned wire shape
+     *  (dispatch queueing + optimistic preservation), not the old `action` mode. */
     buttons?: ButtonNode[];
 }
 export interface TablePagination {
@@ -336,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;
@@ -343,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/dist/tui.js

@@ -914,30 +914,15 @@ function TableView({ node, ctx }) {
             context: { ...(node.sortAction.context ?? {}), column: columnKey, direction },
         });
     };
-    // Selection — leading [x]/[ ] column. Dispatch payloads match BrowserAdapter:
-    // { id, checked } per row, { all: true, checked } for select-all (server-truth
-    // mode). 0.13.0: if `action` is omitted, this is LOCAL mode. The TUI renders
-    // checkboxes from `selectedIds` (the server's pre-selection); clicks are
-    // inert because the TUI doesn't track DOM-equivalent state across the
-    // hook-less conformance walker. The browser carries the real local-mode
-    // workflow; TUI is experimental — use the browser for interactive bulk
-    // selection. The selection.buttons[] toolbar still renders below.
+    // Selection — leading [x]/[ ] column. TUI is render-only: checkboxes display
+    // selectedIds; clicks are inert (the TUI doesn't track DOM-equivalent state
+    // across the hook-less conformance walker). Bulk actions live in
+    // selection.buttons[]; the harvest reads sel.selectedIds (server's
+    // pre-selection). The browser carries the interactive surface.
     const sel = node.selection;
     const effectiveSet = sel ? new Set(sel.selectedIds) : null;
     const allOnPage = sel != null && node.rows.length > 0 &&
         node.rows.every((r) => r.id != null && effectiveSet.has(r.id));
-    const onToggleAll = sel?.action
-        ? () => ctx.onAction({
-            name: sel.action.name,
-            context: { ...(sel.action.context ?? {}), all: true, checked: !allOnPage },
-        })
-        : undefined;
-    const onToggleRow = sel?.action
-        ? (rowId, checked) => ctx.onAction({
-            name: sel.action.name,
-            context: { ...(sel.action.context ?? {}), id: rowId, checked },
-        })
-        : undefined;
     return (_jsx("scrollbox", { focused: focused, focusable: isPaneFocusable, borderColor: focused ? "#88aaff" : "#555555", focusedBorderColor: "#88aaff", flexGrow: 1, flexShrink: 1, children: _jsxs("box", { flexDirection: "column", children: [sel?.buttons && sel.buttons.length > 0 ? (_jsx("box", { flexDirection: "row", gap: 1, children: sel.buttons.map((btn, i) => {
                         const harvestCtx = {
                             ...ctx,
@@ -950,7 +935,7 @@ function TableView({ node, ctx }) {
                             },
                         };
                         return _jsx(ButtonView, { node: btn, ctx: harvestCtx }, i);
-                    }) })) : null, _jsxs("box", { flexDirection: "row", gap: 2, children: [sel ? (_jsx("text", { attributes: 1 /* BOLD */, ...(onToggleAll ? { onMouseDown: onToggleAll } : {}), children: allOnPage ? "[x]" : "[ ]" })) : null, node.columns.map((c) => {
+                    }) })) : null, _jsxs("box", { flexDirection: "row", gap: 2, children: [sel ? (_jsx("text", { attributes: 1 /* BOLD */, children: allOnPage ? "[x]" : "[ ]" })) : null, node.columns.map((c) => {
                             const isSorted = node.sortColumn === c.key;
                             const caret = isSorted ? (node.sortDirection === "desc" ? " ↓" : " ↑") : "";
                             // B5 — only sortable headers respond to clicks (matches BrowserAdapter).
@@ -964,11 +949,7 @@ function TableView({ node, ctx }) {
                         : undefined;
                     return (_jsxs("box", { flexDirection: "row", gap: 2, ...(onRowClick ? { onMouseDown: onRowClick } : {}), children: [sel ? (() => {
                                 const isSel = row.id != null && effectiveSet.has(row.id);
-                                const rowId = row.id;
-                                const onBox = rowId != null && onToggleRow
-                                    ? () => onToggleRow(rowId, !isSel)
-                                    : undefined;
-                                return (_jsx("text", { fg: isSel ? "#88ff88" : "#888888", ...(onBox ? { onMouseDown: onBox } : {}), children: isSel ? "[x]" : "[ ]" }));
+                                return (_jsx("text", { fg: isSel ? "#88ff88" : "#888888", children: isSel ? "[x]" : "[ ]" }));
                             })() : null, node.columns.map((c) => {
                                 const cell = row.cells[c.key] ?? "";
                                 if (c.linkLabel != null && cell.length > 0) {

package/package.json

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