@ashley-shrok/viewmodel-shell 3.8.0 → 3.11.0

package/dist/browser.d.ts

@@ -3,6 +3,7 @@ export declare class BrowserAdapter implements Adapter {
     private container;
     private fileRegistry;
     private sa;
+    private diagWarned;
     private detailsOpenSnapshot;
     private sectionKeyCounter;
     private fitsObservers;
@@ -77,6 +78,15 @@ export declare class BrowserAdapter implements Adapter {
     /** FieldNode — reads value from `sa.read(bind)`; writes back on input/change.
      *  When `action` is set, it fires on Enter (text-like) or change (select) —
      *  the new value is already in state by that point. */
+    /** Warn to the dev console at most once per key (deduped over this adapter's
+     *  lifetime). Fires in dev AND prod — the client bundle can't tell them apart,
+     *  and prod telemetry that captures console.warn should see these too. */
+    private warnOnce;
+    /** Read a bind path, tolerating a bind-less field (file inputs) — null bind
+     *  reads nothing. */
+    private readBind;
+    /** Write to a bind path, no-op when the field has no bind (file inputs). */
+    private writeBind;
     private field;
     /** Forms-completeness (3.4.0) — apply disabled/readonly to the control and
      *  render help + error text below it, wiring aria-describedby / aria-invalid.

package/dist/browser.js

@@ -46,6 +46,11 @@ export class BrowserAdapter {
     container;
     fileRegistry = new Map();
     sa = noopStateAccess;
+    // Dev-console diagnostics dedup (3.9.0). Both [vms:no-bind] and
+    // [vms:type-mismatch] warn at most once per key over this adapter's lifetime.
+    // The client bundle can't distinguish dev/prod, so these fire in both — which
+    // is intentional: prod telemetry that captures console.warn sees them too.
+    diagWarned = new Set();
     // 1.2.0 — open-state snapshot for SectionNode.collapsible. Captured by
     // render() BEFORE this.container.innerHTML = "" by walking
     // [data-section-key] details elements; consumed by render() AFTER node()
@@ -675,8 +680,35 @@ export class BrowserAdapter {
     /** FieldNode — reads value from `sa.read(bind)`; writes back on input/change.
      *  When `action` is set, it fires on Enter (text-like) or change (select) —
      *  the new value is already in state by that point. */
+    /** Warn to the dev console at most once per key (deduped over this adapter's
+     *  lifetime). Fires in dev AND prod — the client bundle can't tell them apart,
+     *  and prod telemetry that captures console.warn should see these too. */
+    warnOnce(key, msg) {
+        if (!this.diagWarned.has(key)) {
+            this.diagWarned.add(key);
+            console.warn(msg);
+        }
+    }
+    /** Read a bind path, tolerating a bind-less field (file inputs) — null bind
+     *  reads nothing. */
+    readBind(bind) {
+        return bind == null ? undefined : this.sa.read(bind);
+    }
+    /** Write to a bind path, no-op when the field has no bind (file inputs). */
+    writeBind(bind, value) {
+        if (bind != null)
+            this.sa.write(bind, value);
+    }
     field(n, parent, on) {
-        const stateValue = this.sa.read(n.bind);
+        const stateValue = this.readBind(n.bind);
+        // [vms:no-bind] — a value-bearing input with no bind renders but silently
+        // drops user input (nothing to persist to). Exclude `file` (bind is
+        // legitimately optional — the binary rides multipart) and `hidden`
+        // (server-authoritative, no user input).
+        if (n.inputType !== "file" && n.inputType !== "hidden" && n.bind == null) {
+            this.warnOnce("no-bind:" + n.name, "[vms:no-bind] FieldNode '" + n.name + "' (inputType=" + n.inputType +
+                ") has no bind — value-bearing inputs need a bind path to persist; the field renders but user input is dropped.");
+        }
         if (n.inputType === "hidden") {
             // Hidden fields don't write back — server is authoritative for hidden.
             const inp = document.createElement("input");
@@ -699,7 +731,7 @@ export class BrowserAdapter {
             inp.name = n.name;
             inp.checked = Boolean(stateValue);
             inp.addEventListener("change", () => {
-                this.sa.write(n.bind, inp.checked);
+                this.writeBind(n.bind, inp.checked);
             });
             wrapper.appendChild(inp);
             if (n.label) {
@@ -752,19 +784,19 @@ export class BrowserAdapter {
             // explicit empty the server can reject, never a silently-missing key.
             if (isMulti) {
                 if (!Array.isArray(stateValue)) {
-                    this.sa.write(n.bind, Array.from(sel.selectedOptions, o => o.value));
+                    this.writeBind(n.bind, Array.from(sel.selectedOptions, o => o.value));
                 }
             }
             else if (stateValue === undefined || String(stateValue) !== sel.value) {
-                this.sa.write(n.bind, sel.value);
+                this.writeBind(n.bind, sel.value);
             }
             sel.addEventListener("change", () => {
                 if (isMulti) {
                     const arr = Array.from(sel.selectedOptions).map(o => o.value);
-                    this.sa.write(n.bind, arr);
+                    this.writeBind(n.bind, arr);
                 }
                 else {
-                    this.sa.write(n.bind, sel.value);
+                    this.writeBind(n.bind, sel.value);
                 }
                 if (n.action)
                     on({ name: n.action.name });
@@ -791,14 +823,31 @@ export class BrowserAdapter {
                 const file = inp.files?.[0];
                 if (file) {
                     this.fileRegistry.set(n.name, file);
+                    // [vms:type-mismatch] — OBSERVABLE-SUBSET diagnostic. The client is
+                    // untyped JS: it CANNOT know a state slot's *declared* server type, so
+                    // it only catches the observable case where a file object overwrites a
+                    // slot that already holds a scalar. It does NOT catch an empty/null slot
+                    // typed string-map server-side — certain detection of that is a
+                    // server-side `_state` deserialize diagnostic (a separate follow-up).
+                    if (n.bind != null) {
+                        const existing = this.readBind(n.bind);
+                        if (existing != null && typeof existing !== "object") {
+                            this.warnOnce("type-mismatch:" + n.name + ":" + n.bind, "[vms:type-mismatch] file FieldNode '" + n.name +
+                                "' writes a {filename,size} object into bind '" + n.bind +
+                                "', whose current state value is a " + (typeof existing) +
+                                " — if that slot is typed string/string-map the _state round-trip will FAIL (cannot convert object to String). Give the file field an object-typed slot, or omit bind (the file rides multipart regardless).");
+                        }
+                    }
                     // Per Phase-6 decision: the picked file is visible in state as a
                     // serialization-safe placeholder; the binary travels on the
-                    // multipart side channel.
-                    this.sa.write(n.bind, { filename: file.name, size: file.size });
+                    // multipart side channel. Backward-compat: apps binding a file field
+                    // to an object slot still get the placeholder. A bind-less file input
+                    // writes nothing (writeBind no-ops) — the binary rides multipart.
+                    this.writeBind(n.bind, { filename: file.name, size: file.size });
                 }
                 else {
                     this.fileRegistry.delete(n.name);
-                    this.sa.write(n.bind, null);
+                    this.writeBind(n.bind, null);
                 }
             });
             wrapper.appendChild(inp);
@@ -813,7 +862,7 @@ export class BrowserAdapter {
             ta.value = stateValue == null ? "" : String(stateValue);
             if (n.required)
                 ta.required = true;
-            ta.addEventListener("input", () => { this.sa.write(n.bind, ta.value); });
+            ta.addEventListener("input", () => { this.writeBind(n.bind, ta.value); });
             wrapper.appendChild(ta);
         }
         else if (n.inputType === "code") {
@@ -836,7 +885,7 @@ export class BrowserAdapter {
             ta.value = stateValue == null ? "" : String(stateValue);
             if (n.required)
                 ta.required = true;
-            ta.addEventListener("input", () => { this.sa.write(n.bind, ta.value); });
+            ta.addEventListener("input", () => { this.writeBind(n.bind, ta.value); });
             ta.addEventListener("keydown", (e) => {
                 if (e.key === "Tab") {
                     e.preventDefault();
@@ -844,7 +893,7 @@ export class BrowserAdapter {
                     const end = ta.selectionEnd ?? 0;
                     ta.value = ta.value.slice(0, start) + "\t" + ta.value.slice(end);
                     ta.selectionStart = ta.selectionEnd = start + 1;
-                    this.sa.write(n.bind, ta.value);
+                    this.writeBind(n.bind, ta.value);
                 }
             });
             wrapper.appendChild(ta);
@@ -860,7 +909,7 @@ export class BrowserAdapter {
             inp.value = stateValue == null ? "" : String(stateValue);
             if (n.required)
                 inp.required = true;
-            inp.addEventListener("input", () => { this.sa.write(n.bind, inp.value); });
+            inp.addEventListener("input", () => { this.writeBind(n.bind, inp.value); });
             if (n.action) {
                 const action = n.action;
                 inp.addEventListener("keydown", (e) => {
@@ -869,7 +918,7 @@ export class BrowserAdapter {
                         // Belt-and-suspenders: flush the latest value to state before
                         // dispatching, in case the browser hasn't fired `input` yet
                         // (e.g. an autofill that lands then submits).
-                        this.sa.write(n.bind, inp.value);
+                        this.writeBind(n.bind, inp.value);
                         on({ name: action.name });
                     }
                 });

package/dist/index.d.ts

@@ -267,8 +267,15 @@ export interface FieldNode {
     type: "field";
     name: string;
     inputType: "text" | "email" | "password" | "number" | "date" | "time" | "datetime-local" | "textarea" | "hidden" | "file" | "select" | "select-multiple" | "checkbox" | "code";
-    /** Path into state where this input reads its current value and writes user changes (e.g. `fields.title`). */
-    bind: string;
+    /** Path into state where this input reads its current value and writes user
+     *  changes (e.g. `fields.title`). REQUIRED for value-bearing inputs
+     *  (text/email/password/number/date/time/datetime-local/textarea/select/
+     *  select-multiple/checkbox/code) and OPTIONAL for `file` inputs — a file
+     *  input's binary rides the multipart side channel (fileRegistry keyed on
+     *  `name`), so omit `bind` on a file input to avoid writing a
+     *  `{filename,size}` placeholder object into state (which breaks a
+     *  string/string-map state slot on round-trip). */
+    bind?: string;
     label?: string;
     placeholder?: string;
     required?: boolean;

package/dist/vite.d.ts

@@ -0,0 +1,68 @@
+import type { Plugin } from "vite";
+/**
+ * Hash the raw bytes of a Vite `manifest.json` into a VMS client build-id.
+ *
+ * The LOCKED cross-backend contract: SHA-256 of the **raw file bytes on disk**
+ * → the **first `hashLength` hex chars, LOWERCASE**. No re-serialize, no JSON
+ * normalization, no BOM handling — both the npm plugin and the .NET
+ * `VmsManifestBuildId.Compute` hash the exact same bytes so a client's
+ * compiled-in id matches the server-computed id byte-for-byte across the fleet.
+ *
+ * Exported so the cross-backend hash-lock test can call it directly against the
+ * shared fixture bytes.
+ *
+ * @param bytes    Raw `manifest.json` file bytes.
+ * @param hashLength Number of leading hex chars to keep (default 12).
+ */
+export declare function vmsHashManifestBytes(bytes: Uint8Array, hashLength?: number): string;
+/**
+ * Options for {@link vmsBuildIdPlugin}.
+ */
+export interface VmsBuildIdPluginOptions {
+    /**
+     * File extensions of emitted chunks whose source should have the build-id
+     * placeholder substituted. Default `[".js"]` — the shell bundle is JS, so CSS
+     * and other assets are left untouched (and never carry the placeholder).
+     */
+    extensions?: string[];
+    /**
+     * Number of leading hex chars of the SHA-256 to use as the build id.
+     * Default 12 (the locked contract shared with the .NET side).
+     */
+    hashLength?: number;
+}
+/**
+ * Vite plugin that stamps a content-hash of the built `manifest.json` into the
+ * client bundle so `ShellOptions.clientBuildId` matches the server's
+ * `AddVmsShellVersioning()` hash for version-skew detection.
+ *
+ * ## How it works (the chicken-and-egg fix)
+ * Vite writes chunk content-hashes into `manifest.json` during the bundle, so
+ * the final manifest hash isn't known until after the bundle is written. The
+ * plugin:
+ *
+ * 1. `config` hook — injects `import.meta.env.VITE_VMS_BUILD` as a unique
+ *    internal placeholder token via `define`, and (if unset) turns on
+ *    `build.manifest = "manifest.json"` at the server-read path.
+ * 2. `writeBundle` hook — reads the emitted `manifest.json` raw bytes, computes
+ *    the build id via {@link vmsHashManifestBytes}, and string-replaces the
+ *    placeholder in every emitted chunk whose filename ends in one of
+ *    `extensions` **that actually contains the placeholder** (the skip-guard —
+ *    so non-shell chunks are never rewritten).
+ *
+ * ## The `build.manifest` gotcha it kills
+ * Vite 5+ defaults the manifest to `.vite/manifest.json`, but the .NET server
+ * reads `wwwroot/manifest.json`. If those diverge the two sides hash different
+ * inputs and skew detection silently breaks. This plugin sets
+ * `build.manifest = "manifest.json"` when unset. If the app has ALREADY set a
+ * DIFFERENT manifest path, the plugin does NOT override it — it emits a `[vms]`
+ * warning so the divergence is loud, not silent.
+ *
+ * ## Fleet constraint — no post-build modification of `manifest.json`
+ * The server hashes `manifest.json` at startup; the client compiled-in id is
+ * hashed at build time. A deploy-pipeline step that minifies / prettifies /
+ * re-formats `manifest.json` between Vite emit and .NET startup changes the raw
+ * bytes and diverges the two hashes. Ship the manifest byte-for-byte as Vite
+ * wrote it.
+ */
+export declare function vmsBuildIdPlugin(options?: VmsBuildIdPluginOptions): Plugin;

package/dist/vite.js

@@ -0,0 +1,116 @@
+// ─── ViewModel Shell — vite subpath (3.11.0) ─────────────────────────────────
+// A Vite plugin that packages the version-skew (3.8.0) client build-id contract
+// so adopters stop hand-rolling the ~40-line placeholder/writeBundle glue.
+//
+// Adoption drops to two lines:
+//   // vite.config.ts
+//   import { vmsBuildIdPlugin } from "@ashley-shrok/viewmodel-shell/vite";
+//   export default { plugins: [vmsBuildIdPlugin()] };
+//   // shell init
+//   new ViewModelShell({ …, clientBuildId: import.meta.env.VITE_VMS_BUILD });
+//
+// The `vite` import is TYPE-ONLY (`import type`), so the built `dist/vite.js`
+// carries NO runtime `require("vite")` — non-Vite consumers of the root package
+// never pull vite in. Node builtins (`fs`/`crypto`/`path`) are fine here: the
+// core-globals CI guard only scopes `src/index.ts`.
+import { createHash, randomBytes } from "node:crypto";
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Hash the raw bytes of a Vite `manifest.json` into a VMS client build-id.
+ *
+ * The LOCKED cross-backend contract: SHA-256 of the **raw file bytes on disk**
+ * → the **first `hashLength` hex chars, LOWERCASE**. No re-serialize, no JSON
+ * normalization, no BOM handling — both the npm plugin and the .NET
+ * `VmsManifestBuildId.Compute` hash the exact same bytes so a client's
+ * compiled-in id matches the server-computed id byte-for-byte across the fleet.
+ *
+ * Exported so the cross-backend hash-lock test can call it directly against the
+ * shared fixture bytes.
+ *
+ * @param bytes    Raw `manifest.json` file bytes.
+ * @param hashLength Number of leading hex chars to keep (default 12).
+ */
+export function vmsHashManifestBytes(bytes, hashLength = 12) {
+    return createHash("sha256").update(bytes).digest("hex").slice(0, hashLength);
+}
+/**
+ * Vite plugin that stamps a content-hash of the built `manifest.json` into the
+ * client bundle so `ShellOptions.clientBuildId` matches the server's
+ * `AddVmsShellVersioning()` hash for version-skew detection.
+ *
+ * ## How it works (the chicken-and-egg fix)
+ * Vite writes chunk content-hashes into `manifest.json` during the bundle, so
+ * the final manifest hash isn't known until after the bundle is written. The
+ * plugin:
+ *
+ * 1. `config` hook — injects `import.meta.env.VITE_VMS_BUILD` as a unique
+ *    internal placeholder token via `define`, and (if unset) turns on
+ *    `build.manifest = "manifest.json"` at the server-read path.
+ * 2. `writeBundle` hook — reads the emitted `manifest.json` raw bytes, computes
+ *    the build id via {@link vmsHashManifestBytes}, and string-replaces the
+ *    placeholder in every emitted chunk whose filename ends in one of
+ *    `extensions` **that actually contains the placeholder** (the skip-guard —
+ *    so non-shell chunks are never rewritten).
+ *
+ * ## The `build.manifest` gotcha it kills
+ * Vite 5+ defaults the manifest to `.vite/manifest.json`, but the .NET server
+ * reads `wwwroot/manifest.json`. If those diverge the two sides hash different
+ * inputs and skew detection silently breaks. This plugin sets
+ * `build.manifest = "manifest.json"` when unset. If the app has ALREADY set a
+ * DIFFERENT manifest path, the plugin does NOT override it — it emits a `[vms]`
+ * warning so the divergence is loud, not silent.
+ *
+ * ## Fleet constraint — no post-build modification of `manifest.json`
+ * The server hashes `manifest.json` at startup; the client compiled-in id is
+ * hashed at build time. A deploy-pipeline step that minifies / prettifies /
+ * re-formats `manifest.json` between Vite emit and .NET startup changes the raw
+ * bytes and diverges the two hashes. Ship the manifest byte-for-byte as Vite
+ * wrote it.
+ */
+export function vmsBuildIdPlugin(options = {}) {
+    const extensions = options.extensions ?? [".js"];
+    const hashLength = options.hashLength ?? 12;
+    // Unique per plugin instance — an internal implementation detail, NOT an
+    // option, so two co-configured tools can't collide on the token text.
+    const placeholder = "__VMS_BUILD_" + randomBytes(4).toString("hex") + "__";
+    return {
+        name: "vms-build-id",
+        apply: "build",
+        config(userConfig) {
+            const existing = userConfig.build?.manifest;
+            if (existing !== undefined && existing !== "manifest.json") {
+                // eslint-disable-next-line no-console
+                console.warn(`[vms] build.manifest is set to ${JSON.stringify(existing)}, but the .NET ` +
+                    `server reads "manifest.json" (wwwroot/manifest.json). The client and server ` +
+                    `will hash different files and version-skew detection will not work. ` +
+                    `Set build.manifest to "manifest.json" (or remove it and let vmsBuildIdPlugin set it).`);
+            }
+            // Return a partial (merge-friendly) config per Vite's `config` hook contract.
+            return {
+                define: {
+                    "import.meta.env.VITE_VMS_BUILD": JSON.stringify(placeholder),
+                },
+                ...(existing === undefined
+                    ? { build: { manifest: "manifest.json" } }
+                    : {}),
+            };
+        },
+        writeBundle(outputOptions, bundle) {
+            const dir = outputOptions.dir ?? "";
+            const manifestBytes = readFileSync(join(dir, "manifest.json"));
+            const buildId = vmsHashManifestBytes(manifestBytes, hashLength);
+            for (const fileName of Object.keys(bundle)) {
+                if (!extensions.some((ext) => fileName.endsWith(ext)))
+                    continue;
+                const p = join(dir, fileName);
+                const src = readFileSync(p, "utf-8");
+                // Skip-guard: only rewrite chunks that actually carry the placeholder,
+                // so non-shell chunks are never touched (no double-writes).
+                if (src.includes(placeholder)) {
+                    writeFileSync(p, src.replaceAll(placeholder, buildId));
+                }
+            }
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ashley-shrok/viewmodel-shell",
-  "version": "3.8.0",
+  "version": "3.11.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 \u2014 a .NET reference backend ships with the repo, but any language can produce the JSON contract.",
   "type": "module",
   "license": "MIT",
@@ -47,6 +47,7 @@
     "jsdom": "^25.0.1",
     "react": "^19.2.0",
     "typescript": "^5.4.0",
+    "vite": ">=5",
     "vitest": "^2.1.4"
   },
   "optionalDependencies": {
@@ -54,6 +55,14 @@
     "@opentui/react": "^0.2.14",
     "react": "^19.2.0"
   },
+  "peerDependencies": {
+    "vite": ">=5"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -71,6 +80,10 @@
       "types": "./dist/tui.d.ts",
       "default": "./dist/tui.js"
     },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "default": "./dist/vite.js"
+    },
     "./styles.css": "./styles/default.css",
     "./themes/dark-blue.css": "./styles/themes/dark-blue.css",
     "./themes/dark-green.css": "./styles/themes/dark-green.css",