@ashley-shrok/viewmodel-shell 0.3.12 → 0.3.13

package/dist/browser.d.ts

@@ -4,6 +4,15 @@ export declare class BrowserAdapter implements Adapter {
     private fileRegistry;
     constructor(container: HTMLElement);
     render(vm: ViewNode, onAction: (action: ActionEvent) => void): void;
+    navigate(url: string): void;
+    storage(scope: "local" | "session", key: string, value: string): void;
+    transport(input: string, init: {
+        method?: string;
+        headers?: Record<string, string>;
+        body?: FormData | string;
+    }, hooks?: {
+        onUploadProgress?: (sent: number, total: number) => void;
+    }): Promise<Response>;
     private node;
     private kids;
     private page;

package/dist/browser.js

@@ -45,6 +45,86 @@ export class BrowserAdapter {
             }
         });
     }
+    navigate(url) {
+        window.location.href = url;
+    }
+    storage(scope, key, value) {
+        const store = scope === "session" ? sessionStorage : localStorage;
+        store.setItem(key, value);
+    }
+    async transport(input, init, hooks) {
+        const onUploadProgress = hooks?.onUploadProgress;
+        if (!onUploadProgress) {
+            // No progress requested → identical to the core fetch path (D-02 fallback parity).
+            return fetch(input, init);
+        }
+        return new Promise((resolve, reject) => {
+            const xhr = new XMLHttpRequest();
+            // IN-01: this seam only exists to carry a body+files action request, so
+            // a method-less init is non-sensical. dispatch() (the sole caller) always
+            // passes "POST"; default to "POST" (not "GET") so a future caller bug
+            // never silently produces a body-bearing GET.
+            xhr.open(init.method ?? "POST", input);
+            // WR-02: every header dispatch() builds in `init.headers` (Accept +
+            // getRequestHeaders()) is applied here, so the XHR path's request
+            // headers are byte-identical to the fetch path's. Scope note: this
+            // seam is same-origin only. The fetch fallback sends cookies on
+            // same-origin requests via its default `credentials: "same-origin"`;
+            // XHR sends same-origin cookies without `withCredentials`, so the
+            // common (same-origin `actionEndpoint`) case matches fetch exactly.
+            // Cross-origin action endpoints are out of scope for this transport.
+            for (const [k, v] of Object.entries(init.headers ?? {})) {
+                xhr.setRequestHeader(k, v);
+            }
+            let knownTotal = 0; // last computable total (0 = never computable)
+            let lastLoaded = 0; // last reported bytes sent
+            xhr.upload.onprogress = (e) => {
+                lastLoaded = e.loaded;
+                if (e.lengthComputable) {
+                    knownTotal = e.total;
+                    onUploadProgress(e.loaded, e.total); // D-05 in-flight, computable
+                }
+                else {
+                    onUploadProgress(e.loaded, 0); // D-05 indeterminate sentinel (0)
+                }
+            };
+            xhr.onload = () => {
+                // D-05 terminal emission: mirror whichever value was being reported.
+                // Known total → (total, total); indeterminate → (finalLoaded, finalLoaded).
+                // NEVER (0,0) once any progress event has fired; a body that produces
+                // no progress event (e.g. a zero-byte upload, or a transport that
+                // completes before the browser emits any upload progress) legitimately
+                // terminates at (0,0), which the documented `total > 0` consumer guard
+                // (MIGRATION.md 5b) handles.
+                if (knownTotal > 0)
+                    onUploadProgress(knownTotal, knownTotal);
+                else
+                    onUploadProgress(lastLoaded, lastLoaded);
+                // D-08: status 0 means a network-level failure (CORS rejection / blocked
+                // request) where onload fired but onerror did not. The Fetch Response
+                // constructor throws RangeError for status 0, and that throw would land
+                // OUTSIDE the Promise executor (never settling it → dispatch() hangs).
+                // Reject instead so dispatch()'s try/catch routes it to onError —
+                // byte-identical to fetch, which rejects on CORS/network failure.
+                if (xhr.status === 0) {
+                    reject(new Error(`Transport request to ${input} failed (status 0)`));
+                    return;
+                }
+                // D-08: resolve a real Response so dispatch()'s res.ok / await res.json()
+                // / processResponse() is byte-identical to the fetch path.
+                resolve(new Response(xhr.responseText, {
+                    status: xhr.status,
+                    statusText: xhr.statusText,
+                }));
+            };
+            // D-07: error / timeout / abort → reject so dispatch()'s existing
+            // try/catch routes it to onError exactly like a failed fetch.
+            xhr.onerror = () => reject(new Error(`Transport request to ${input} failed`));
+            xhr.ontimeout = () => reject(new Error(`Transport request to ${input} timed out`));
+            xhr.onabort = () => reject(new Error(`Transport request to ${input} aborted`));
+            xhr.send(init.body ?? null);
+        });
+    }
     node(n, parent, on) {
         switch (n.type) {
             case "page": return this.page(n, parent, on);

package/dist/index.d.ts

@@ -5,6 +5,24 @@ export interface ActionEvent {
 }
 export interface Adapter {
     render(vm: ViewNode, onAction: (action: ActionEvent) => void): void;
+    /** Hand the platform off to a URL (the browser adapter sets the page location).
+     *  No safe no-op exists — if a redirect arrives and neither ShellOptions.onRedirect
+     *  nor this method is available, the shell fails loudly. */
+    navigate?(url: string): void;
+    /** Write a client side-effect to platform storage. Write-only — the wire
+     *  contract has no storage read. scope is "local" | "session". */
+    storage?(scope: "local" | "session", key: string, value: string): void;
+    /** OPTIONAL transport override. Phase 1 leaves the core's `fetch` as the
+     *  universal default and does NOT route load()/dispatch() through this.
+     *  Defined now so Phase 2 (upload progress) can plug an XHR binding in via
+     *  the `hooks.onUploadProgress` callback with no further wire/API change. */
+    transport?(input: string, init: {
+        method?: string;
+        headers?: Record<string, string>;
+        body?: FormData | string;
+    }, hooks?: {
+        onUploadProgress?: (sent: number, total: number) => void;
+    }): Promise<Response>;
 }
 export type ViewNode = PageNode | SectionNode | ListNode | ListItemNode | FormNode | FieldNode | CheckboxNode | ButtonNode | TextNode | LinkNode | StatBarNode | TabsNode | ProgressNode | ModalNode | TableNode;
 export interface PageNode {
@@ -150,8 +168,12 @@ export interface ShellOptions {
     onLoading?: (loading: boolean) => void;
     /** Called before each dispatch — merge the returned headers into every POST request. */
     getRequestHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
-    /** Called when the server responds with a redirect URL. Defaults to window.location.href = url. */
+    /** Called when the server responds with a redirect URL. When unset, falls back to adapter.navigate(url); if the adapter has no navigate, the shell fails loudly. */
     onRedirect?: (url: string) => void;
+    /** Called during a files-bearing dispatch when the plugged-in adapter implements transport().
+     *  sent = bytes uploaded so far; total = total bytes, or 0 when the total is indeterminate
+     *  (guard total > 0 before computing sent / total). Never fires on the fetch fallback path. */
+    onUploadProgress?: (sent: number, total: number) => void;
     /** When set, the shell dispatches a "poll" action at this interval (ms) after every load/dispatch.
      *  The server can override the next interval via ShellResponse.nextPollIn, or stop polling by
      *  omitting nextPollIn when no pollInterval is configured. */
@@ -187,6 +209,7 @@ export declare class ViewModelShell {
     stopPolling(): void;
     getCurrentVm(): ViewNode | null;
     getCurrentState(): unknown;
+    private failCapability;
     private processResponse;
     private schedulePoll;
 }

package/dist/index.js

@@ -55,11 +55,21 @@ export class ViewModelShell {
                 }
             }
             const extraHeaders = this.options.getRequestHeaders ? await this.options.getRequestHeaders() : {};
-            const res = await fetch(actionEndpoint, {
+            const adapter = this.options.adapter;
+            const init = {
                 method: "POST",
                 headers: { Accept: "application/json", ...extraHeaders },
                 body: form,
-            });
+            };
+            let res;
+            if (action.files && this.options.onUploadProgress && adapter.transport) {
+                res = await adapter.transport(actionEndpoint, init, {
+                    onUploadProgress: this.options.onUploadProgress,
+                });
+            }
+            else {
+                res = await fetch(actionEndpoint, init);
+            }
             if (!res.ok)
                 throw new Error(`Action '${action.name}' failed: ${res.status}`);
             this.processResponse((await res.json()));
@@ -88,21 +98,39 @@ export class ViewModelShell {
     }
     getCurrentVm() { return this.currentVm; }
     getCurrentState() { return this.currentState; }
+    failCapability(capability, detail) {
+        const err = new Error(`[ViewModelShell] Adapter is missing the "${capability}" capability but the ` +
+            `server response requires it (${detail}). This is a hard failure, not a no-op: ` +
+            `a silently-dropped ${capability} (e.g. an auth token never persisted, or a ` +
+            `redirect that never happens) is a correctness/security bug. Implement ` +
+            `${capability}() on your Adapter, or (for redirect) pass ShellOptions.onRedirect.`);
+        this.options.onError ? this.options.onError(err) : console.error("[ViewModelShell]", err);
+    }
     processResponse(body) {
+        const adapter = this.options.adapter;
         for (const effect of body.sideEffects ?? []) {
             if (effect.type === "set-local-storage" && effect.key != null) {
-                localStorage.setItem(effect.key, effect.value ?? "");
+                if (adapter.storage)
+                    adapter.storage("local", effect.key, effect.value ?? "");
+                else
+                    this.failCapability("storage", `side-effect "${effect.type}" key="${effect.key}"`);
             }
             else if (effect.type === "set-session-storage" && effect.key != null) {
-                sessionStorage.setItem(effect.key, effect.value ?? "");
+                if (adapter.storage)
+                    adapter.storage("session", effect.key, effect.value ?? "");
+                else
+                    this.failCapability("storage", `side-effect "${effect.type}" key="${effect.key}"`);
             }
         }
         if (body.redirect) {
             if (this.options.onRedirect) {
                 this.options.onRedirect(body.redirect);
             }
+            else if (adapter.navigate) {
+                adapter.navigate(body.redirect);
+            }
             else {
-                window.location.href = body.redirect;
+                this.failCapability("navigate", `redirect to "${body.redirect}"`);
             }
             return;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ashley-shrok/viewmodel-shell",
-  "version": "0.3.12",
+  "version": "0.3.13",
   "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",
@@ -26,10 +26,14 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "check:core-globals": "node scripts/check-core-platform-globals.mjs",
+    "test": "vitest run",
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {
-    "typescript": "^5.4.0"
+    "typescript": "^5.4.0",
+    "jsdom": "^25.0.1",
+    "vitest": "^2.1.4"
   },
   "exports": {
     ".": {