@ashley-shrok/viewmodel-shell 3.9.0 → 4.0.0

package/agent-skill.md

@@ -139,6 +139,8 @@ If a response carries `nextPollIn: N`, schedule a POST `{ "name": "poll", "state
 
 File uploads use the multipart form above. One form entry per file input, keyed by the input's `name` attribute (from the corresponding node's `name` field in the tree). The file's binary content is the entry's value. JSON-body dispatch cannot carry files; use multipart.
 
+**A file rides only the action(s) its input declares.** Each file `FieldNode` carries an `uploadOn` array of action names. Send a file's binary entry **only** when the action you are dispatching (`_action.name`) is listed in that file input's `uploadOn`; if you dispatch any other action, do **not** include the file. A file input with no `uploadOn` (absent or empty) rides **nothing** — its binary is never sent. This mirrors the browser, where the same declaration decides which click sends the file: an agent should not attach a file to an action a human's click could not have sent it with. (There is no positional/implicit rule — the file's own `uploadOn` is the whole contract.)
+
 ## Versioning
 
 This manual applies to protocol token `viewmodel-shell/1.0` — the value of the `protocol` field on the discoverability meta tag. The protocol token tracks the wire shape, NOT the package version: a 1.5.x or 1.6.x package release may still carry protocol `viewmodel-shell/1.0` because the wire has not undergone a breaking change. A future major-version bump (`viewmodel-shell/2.0`) signals a breaking change and invalidates this manual; expect a new skill at the same `/.well-known/vms-skill.md` URL.

package/dist/browser.js

@@ -601,11 +601,26 @@ export class BrowserAdapter {
         const form = document.createElement("form");
         form.className = `vms-form${n.layout && n.layout !== "stack" ? ` vms-form--${n.layout}` : ""}`;
         form.noValidate = true;
-        this.kids(n.children, form, on);
+        // File collection is by DECLARED intent, not button position: a file input
+        // rides an action iff that action's name is listed in the input's `uploadOn`
+        // (carried here via the data-vms-upload-on attribute set in field()). EVERY
+        // trigger inside the form — submit, buttons[], a ButtonNode or
+        // FieldNode.action nested in children — routes through this one path, so
+        // where a trigger sits is irrelevant; the file's own uploadOn decides. An
+        // input with no uploadOn rides nothing (there is no positional fallback).
         const dispatchWithFiles = (action) => {
             const files = {};
             form.querySelectorAll("input[type=file]").forEach(inp => {
-                if (inp.name && inp.files?.[0])
+                if (!inp.name || !inp.files?.[0])
+                    return;
+                let uploadOn = [];
+                try {
+                    uploadOn = JSON.parse(inp.dataset.vmsUploadOn ?? "[]");
+                }
+                catch {
+                    uploadOn = [];
+                }
+                if (uploadOn.includes(action.name))
                     files[inp.name] = inp.files[0];
             });
             const ev = { name: action.name };
@@ -613,6 +628,10 @@ export class BrowserAdapter {
                 ev.files = files;
             on(ev);
         };
+        // Children dispatch through the file-aware path too — so a ButtonNode (or a
+        // FieldNode.action Enter) nested anywhere in the form carries files per the
+        // uploadOn contract, identical to a footer buttons[] trigger.
+        this.kids(n.children, form, dispatchWithFiles);
         // #22 — submitButton takes precedence: the form renders the consumer's own
         // button (its label + emphasis/tone/size/width) as the submit and fires its
         // action; submitLabel/submitAction for the implicit button are then ignored.
@@ -809,6 +828,10 @@ export class BrowserAdapter {
             inp.className = "vms-field__input";
             inp.id = `vms-${n.name}`;
             inp.name = n.name;
+            // Carry the declared upload routing to dispatch time — form()'s
+            // dispatchWithFiles reads this and attaches the file only to an action
+            // named here. Absent/empty => the file rides no action.
+            inp.dataset.vmsUploadOn = JSON.stringify(n.uploadOn ?? []);
             // File-input persistence: re-apply any registered file to the new node.
             const existingFile = this.fileRegistry.get(n.name);
             if (existingFile) {
@@ -823,6 +846,13 @@ export class BrowserAdapter {
                 const file = inp.files?.[0];
                 if (file) {
                     this.fileRegistry.set(n.name, file);
+                    // [vms:orphan-file] — a picked file that declares no uploadOn action
+                    // will never be sent (the binary rides an action, and this input
+                    // names none). Silent under-attach is the dangerous failure, so warn.
+                    if (!n.uploadOn || n.uploadOn.length === 0) {
+                        this.warnOnce("orphan-file:" + n.name, "[vms:orphan-file] file field '" + n.name + "' has a picked file but no uploadOn action — " +
+                            "its binary will not be sent; add uploadOn:[\"<action>\"] naming the action that should carry it.");
+                    }
                     // [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

package/dist/index.d.ts

@@ -255,7 +255,10 @@ export interface FormNode {
      *  `bind` path and travel with the dispatch's `_state` payload. Mirrors
      *  HTML's multiple submit buttons / `formaction` — different action per
      *  button, same underlying state. A plain ButtonNode placed in `children`
-     *  has identical dispatch semantics; the buttons[] slot is a layout hint. */
+     *  has identical dispatch semantics: both flow through the same file-aware
+     *  dispatch, so file collection is governed by each file input's `uploadOn`
+     *  (below), NOT by whether the trigger sits in `buttons[]` or `children`. The
+     *  buttons[] slot is purely a layout hint. */
     buttons?: ButtonNode[];
     /** Opt-in: bare Enter inside a descendant <textarea> dispatches submitAction
      *  (chat-composer "Enter sends, Shift/Ctrl/Meta/Alt+Enter = newline"). No-op
@@ -320,6 +323,15 @@ export interface FieldNode {
     /** Dispatched when Enter is pressed (text-like inputs only). Carries an
      *  action name only — the current value is already in state at the bind path. */
     action?: ActionEvent;
+    /** FILE INPUTS ONLY. The action name(s) whose dispatch carries this file's
+     *  binary over the multipart wire. A file rides an action iff that action's
+     *  name is listed here — declared on the *file*, so which trigger sends it no
+     *  longer depends on where a button sits (the trigger can live anywhere in the
+     *  form; footer `buttons[]`, `children`, submit, and Enter all honor this
+     *  equally). An absent or empty `uploadOn` means the file rides **nothing**
+     *  (there is no positional fallback); the browser warns `[vms:orphan-file]`
+     *  when a file is picked with no `uploadOn`. Ignored on non-file inputs. */
+    uploadOn?: string[];
 }
 export interface CheckboxNode {
     type: "checkbox";

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.9.0",
+  "version": "4.0.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",