@ashley-shrok/viewmodel-shell 0.13.0 → 0.14.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) {

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 {
@@ -320,6 +330,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/package.json

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