@ashley-shrok/viewmodel-shell 0.13.0 → 0.15.0

package/dist/browser.d.ts

@@ -10,6 +10,12 @@ 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.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
+     *  work is pending, omits it (or sets false) when done." Idempotent. */
+    private unloadHandler;
+    setPreventUnload(active: boolean): void;
     transport(input: string, init: {
         method?: string;
         headers?: Record<string, string>;

package/dist/browser.js

@@ -105,6 +105,28 @@ export class BrowserAdapter {
             setTimeout(() => URL.revokeObjectURL(url), 0);
         }
     }
+    /** 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
+     *  work is pending, omits it (or sets false) when done." Idempotent. */
+    unloadHandler = null;
+    setPreventUnload(active) {
+        if (active && this.unloadHandler == null) {
+            this.unloadHandler = (e) => {
+                // Two signals because browsers historically disagreed on which they
+                // honor; modern Chromium/Firefox honor preventDefault, older Safari
+                // and ancient browsers look at returnValue. The dialog text itself is
+                // browser-controlled ("Leave site?…") and cannot be customized.
+                e.preventDefault();
+                e.returnValue = "";
+            };
+            window.addEventListener("beforeunload", this.unloadHandler);
+        }
+        else if (!active && this.unloadHandler != null) {
+            window.removeEventListener("beforeunload", this.unloadHandler);
+            this.unloadHandler = null;
+        }
+    }
     async transport(input, init, hooks) {
         const onUploadProgress = hooks?.onUploadProgress;
         if (!onUploadProgress) {
@@ -652,24 +674,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);
@@ -761,23 +777,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

@@ -32,6 +32,16 @@ export interface Adapter {
      *  May return void or Promise<void>; the shell awaits the return value so
      *  async I/O errors surface via onError. */
     saveFile?(data: Blob, filename: string, contentType: string): void | Promise<void>;
+    /** 0.14.0 — install / clear a "warn before navigating away" guard, driven
+     *  by `ShellResponse.preventUnload` on every response (load, dispatch,
+     *  push). Idempotent: the shell calls with the boolean from each response,
+     *  the adapter installs when true / clears when false. Designed for
+     *  long-running server actions where an accidental tab close would lose
+     *  in-flight work. Fail-quiet by absence (unlike navigate/storage/saveFile)
+     *  — this is a UX safety net, not a security guarantee, and non-browser
+     *  targets (TUI) have no terminal equivalent. Modern browsers show a
+     *  generic "Leave site?" dialog; the message is not customizable. */
+    setPreventUnload?(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 {
@@ -203,31 +213,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 {
@@ -320,6 +318,12 @@ export interface ShellResponse {
     sideEffects?: ShellSideEffect[];
     /** When set, schedules the next poll at this delay (ms). Overrides pollInterval for one tick. */
     nextPollIn?: number;
+    /** 0.14.0 — when true, the shell asks the adapter to install a "warn before
+     *  unload" guard; when false / absent, the guard is cleared. Drives long-
+     *  running-work workflows: while server-side work is in flight, return
+     *  `preventUnload: true` from each response; clear it when the work
+     *  completes (typically via polling). See `Adapter.setPreventUnload`. */
+    preventUnload?: boolean;
 }
 export declare class ViewModelShell {
     private options;

package/dist/index.js

@@ -21,6 +21,10 @@ export class ViewModelShell {
             const body = (await res.json());
             this.currentVm = body.vm;
             this.currentState = body.state;
+            // 0.14.0 — apply the unload guard from the initial-load response too. The
+            // 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);
             adapter.render(body.vm, (action) => this.dispatch(action));
             this.schedulePoll(body.nextPollIn);
         }
@@ -138,6 +142,11 @@ export class ViewModelShell {
                 void this.download(effect.url, effect.filename);
             }
         }
+        // 0.14.0 — apply the unload guard before the redirect/render branch so it's
+        // in place (or cleared) consistently across both branches. A server that
+        // 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);
         if (body.redirect) {
             if (this.options.onRedirect) {
                 this.options.onRedirect(body.redirect);

package/dist/server.d.ts

@@ -18,6 +18,10 @@ export interface ShellResponseBody<TState> {
     redirect?: string;
     sideEffects?: ShellSideEffect[];
     nextPollIn?: number;
+    /** 0.14.0 — install / clear the browser's "warn before unload" guard. Omit
+     *  (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;
 }
 /** 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.13.0",
+  "version": "0.15.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",