@ashley-shrok/viewmodel-shell 3.11.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/package.json

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