@ashley-shrok/viewmodel-shell 1.5.0 → 1.7.0

package/agent-skill.md

@@ -0,0 +1,121 @@
+# ViewModel Shell — agent operating manual
+
+This is the protocol manual for an agent driving a ViewModel Shell (VMS) app over its JSON wire. It is operational, not historical. Follow each section as a rule.
+
+## What this is
+
+VMS is a server-driven UI framework. The server is a pure function `(state, action) → (newState, view)`. Every response carries the entire UI state as an opaque blob and a fresh `vm` view tree. You do not have to render the tree to drive the API — you can read its node types and dispatch actions directly.
+
+## Endpoints
+
+Read the page's `<meta name="viewmodel-shell">` tag for the endpoint pair:
+
+```json
+{ "protocol": "viewmodel-shell/1.0", "endpoint": "/api/x", "actionEndpoint": "/api/x/action", "skill": "/.well-known/vms-skill.md" }
+```
+
+- `GET <endpoint>` → returns the initial `{ "ok": true, "vm": <ViewNode tree>, "state": <opaque state blob> }`.
+- `POST <actionEndpoint>` → dispatches an action. See the next section for the body shape.
+
+The `skill` field is optional and points at this manual (or an app-specific preamble + this manual).
+
+## Action dispatch shape
+
+Two body forms are accepted. Use JSON when you can; multipart only when uploading files.
+
+**JSON (recommended for agents).** Set `Content-Type: application/json` and POST a flat envelope:
+
+```json
+{ "name": "save-ticket-42", "state": { "...": "round-tripped state blob from the last response" } }
+```
+
+There is no `context` field — per-row / per-tab identity is encoded in the action name itself (e.g. `delete-row-42`, `filter-active`). File uploads are NOT supported in this form.
+
+**Multipart (browser-style and file-bearing).** Set `Content-Type: multipart/form-data` and post three kinds of entries:
+
+| Field | Value |
+|---|---|
+| `_action` | JSON: `{"name": "<action-name>"}` |
+| `_state` | JSON: the current state blob |
+| any file-input `name` | the binary file content (one entry per file input) |
+
+## The round-trip rule
+
+The `state` blob from the last response goes back unchanged on the next dispatch, EXCEPT for the fields the user changed. Input nodes carry a `bind` property whose value is a dotted path inside `state` where the input's value lives (e.g. `"bind": "form.title"`). Before dispatching an action that depends on user input, write your value at the bound path inside the state blob; leave every other field as you received it. The server is authoritative for everything else and may rewrite any field in the response.
+
+## Response envelope
+
+Every response carries `ok: boolean`.
+
+**Success:**
+
+```json
+{ "ok": true, "vm": { /* ViewNode tree */ }, "state": { /* opaque blob */ } }
+```
+
+Optional success-path fields, which may appear alone or alongside `vm`/`state`:
+
+| Field | Meaning |
+|---|---|
+| `redirect` | A URL string. Navigate to it (or hand control off). When `redirect` is present, `vm` and `state` may be omitted. |
+| `sideEffects` | An array of side-effect verbs (see next section). Applied in order before any redirect or re-render. |
+| `nextPollIn` | Milliseconds. Schedule a `{"name": "poll"}` dispatch after this delay. |
+| `busy` | Boolean. While `true`, drop user-initiated dispatches. Polls bypass. The next response that omits or sets `false` clears the lock. |
+| `preventUnload` | Boolean. While `true`, treat the page as having unsaved work — warn before navigating away. |
+
+**Failure:**
+
+```json
+{ "ok": false, "errors": [ { "message": "...", "code": "parse_error", "path": "form.title" } ] }
+```
+
+`errors[].path` and `errors[].code` are optional. HTTP status is 4xx or 5xx on failure. Check `ok` once at the response edge; do not branch on HTTP status.
+
+## Side-effect verbs
+
+`sideEffects[]` entries each carry a `type` discriminator. Built-in verbs as of `viewmodel-shell/1.0`:
+
+```json
+{ "sideEffects": [
+  { "type": "set-local-storage", "key": "auth_jwt", "value": "eyJ..." },
+  { "type": "set-session-storage", "key": "draft_id", "value": "42" },
+  { "type": "download", "url": "/api/invoices/42/pdf", "filename": "invoice-42.pdf" }
+] }
+```
+
+| Verb | Effect |
+|---|---|
+| `set-local-storage` | Write `key`/`value` to platform localStorage (or your agent's equivalent persistent store). |
+| `set-session-storage` | Same as above for session-scoped storage. |
+| `download` | Fetch `url` (re-presenting your auth headers — see *Auth*) and save the bytes. Filename precedence: `Content-Disposition` > side-effect `filename` > URL basename > `"download"`. |
+
+**Forward-compat rule — silently ignore unknown verbs.** A future minor release may add new verbs. If you see a `type` you do not recognize, skip it; do not error. Honor or ignore per your policy.
+
+## Errors
+
+`ok: false` responses always carry `errors[]`. The framework uses a stable code vocabulary at the protocol edge:
+
+| Code | Meaning |
+|---|---|
+| `parse_error` | The request body could not be parsed (malformed JSON, missing required field). |
+| `unknown_action` | The `name` in your action envelope does not match any handler in the current tree. |
+| `invalid_tree` | The server built a tree that violates a wire invariant (this is a server bug, not yours). |
+| `uncaught_exception` | The action handler threw. Treat as a 500-class failure. |
+
+Stop on `ok: false`. Surface the message to the user. Do not retry blindly — most of these are deterministic.
+
+## Auth
+
+The wire does not mandate an auth shape. If the app needs credentials, the app preamble above (or its own README) names them. Common patterns: a `Bearer` token in `Authorization`, a CSRF/anti-forgery token in a custom header, a session cookie. Send the same headers on every request, including polls and downloads. The `download` side-effect re-presents your auth headers when the agent fetches the file.
+
+## Polling
+
+If a response carries `nextPollIn: N`, schedule a POST `{ "name": "poll", "state": <last state> }` against the same `actionEndpoint` after `N` milliseconds. The server may continue returning `nextPollIn` until the workflow reaches a terminal state, at which point the field will be absent. Polls run silently — they are not user-initiated.
+
+## Files
+
+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.
+
+## 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.d.ts

@@ -52,7 +52,10 @@ export declare class BrowserAdapter implements Adapter {
      *  every keystroke writes, Enter dispatches filterAction; pagination
      *  prev/next write the target page to paginationBind then dispatch
      *  prevAction/nextAction. Per-row controls (row.actions[]) are a mix of
-     *  ButtonNode and CheckboxNode dispatched by entry.type. When row.action
+     *  ButtonNode and CheckboxNode; the renderer partitions them by entry.type —
+     *  CheckboxNodes render in a dedicated LEADING column (left, the data-grid
+     *  selection convention), ButtonNodes in the TRAILING actions cell (right).
+     *  When row.action
      *  is set, the entire <tr> becomes clickable + keyboard-activatable
      *  (Enter / Space — Space preventDefaults page scroll) and exposes
      *  role="button", tabindex=0, and an aria-label derived from cell text;

package/dist/browser.js

@@ -781,7 +781,10 @@ export class BrowserAdapter {
      *  every keystroke writes, Enter dispatches filterAction; pagination
      *  prev/next write the target page to paginationBind then dispatch
      *  prevAction/nextAction. Per-row controls (row.actions[]) are a mix of
-     *  ButtonNode and CheckboxNode dispatched by entry.type. When row.action
+     *  ButtonNode and CheckboxNode; the renderer partitions them by entry.type —
+     *  CheckboxNodes render in a dedicated LEADING column (left, the data-grid
+     *  selection convention), ButtonNodes in the TRAILING actions cell (right).
+     *  When row.action
      *  is set, the entire <tr> becomes clickable + keyboard-activatable
      *  (Enter / Space — Space preventDefaults page scroll) and exposes
      *  role="button", tabindex=0, and an aria-label derived from cell text;
@@ -795,6 +798,17 @@ export class BrowserAdapter {
         table.className = "vms-table";
         const thead = document.createElement("thead");
         const headerRow = document.createElement("tr");
+        // Per-row checkboxes render in a dedicated LEADING column. If ANY row
+        // carries a checkbox, every row gets a leading select cell (empty when the
+        // row has none) and the header/filter rows get a matching leading <th>, so
+        // body cells stay column-aligned with their headers. (The trailing actions
+        // cell needs no header because it's the LAST column — a leading column does.)
+        const tableHasCheckboxes = n.rows.some(r => r.actions?.some(e => e.type === "checkbox") ?? false);
+        if (tableHasCheckboxes) {
+            const selTh = document.createElement("th");
+            selTh.className = "vms-table__th vms-table__th--select";
+            headerRow.appendChild(selTh);
+        }
         const sortIntent = (n.sortBind != null ? this.sa.read(n.sortBind) : null);
         const sortedCol = sortIntent?.column;
         const sortedDir = sortIntent?.direction;
@@ -832,6 +846,9 @@ export class BrowserAdapter {
             const filterAction = n.filterAction;
             const filterRow = document.createElement("tr");
             filterRow.className = "vms-table__filter-row";
+            if (tableHasCheckboxes) {
+                filterRow.appendChild(document.createElement("th"));
+            }
             n.columns.forEach(col => {
                 const th = document.createElement("th");
                 if (col.filterable) {
@@ -898,6 +915,22 @@ export class BrowserAdapter {
                     }
                 });
             }
+            // Leading select cell — holds this row's checkbox controls (empty when
+            // the row has none). Rendered for every row whenever the table has any
+            // checkboxes, so columns line up with the leading <th> added above. When
+            // row.action is set, swallow clicks so toggling doesn't fire the row action.
+            if (tableHasCheckboxes) {
+                const selTd = document.createElement("td");
+                selTd.className = "vms-table__td vms-table__td--select";
+                for (const entry of row.actions ?? []) {
+                    if (entry.type === "checkbox")
+                        this.checkbox(entry, selTd, on);
+                }
+                if (row.action) {
+                    selTd.addEventListener("click", (e) => { e.stopPropagation(); });
+                }
+                tr.appendChild(selTd);
+            }
             n.columns.forEach(col => {
                 const td = document.createElement("td");
                 td.className = "vms-table__td";
@@ -921,21 +954,15 @@ export class BrowserAdapter {
                 }
                 tr.appendChild(td);
             });
-            // Per-row interactive controls — dispatch by entry.type so a CheckboxNode
-            // renders as a real <input type="checkbox"> rather than silently as an
-            // empty button. When row.action is set, swallow clicks on the actions td
-            // so toggling a per-row control doesn't ALSO fire the row action.
-            if (row.actions && row.actions.length > 0) {
+            // Trailing actions cell — per-row ButtonNodes only (checkboxes render in
+            // the leading select cell above). When row.action is set, swallow clicks
+            // on the actions td so pressing a button doesn't ALSO fire the row action.
+            const buttonEntries = (row.actions ?? []).filter((e) => e.type === "button");
+            if (buttonEntries.length > 0) {
                 const td = document.createElement("td");
                 td.className = "vms-table__td vms-table__td--actions";
-                for (const entry of row.actions) {
-                    if (entry.type === "button")
-                        this.button(entry, td, on);
-                    else if (entry.type === "checkbox")
-                        this.checkbox(entry, td, on);
-                    // forward-compatible: unknown entry types no-op (the closed TS union
-                    // narrows; the runtime guard is for late-arriving wire shapes).
-                }
+                for (const entry of buttonEntries)
+                    this.button(entry, td, on);
                 if (row.action) {
                     td.addEventListener("click", (e) => { e.stopPropagation(); });
                 }

package/dist/index.d.ts

@@ -320,11 +320,12 @@ export interface TableRow {
      *  per-row button, checkbox, or cell linkLabel anchor does NOT also fire
      *  `row.action` (the renderer stops propagation on those targets). */
     action?: ActionEvent;
-    /** Per-row interactive controls rendered in a trailing actions cell. Each
-     *  entry is either a ButtonNode (its own unique action name encodes per-row
-     *  identity, e.g. `delete-row-42`) or a CheckboxNode (its own `bind` path
-     *  per row). The renderer dispatches by `entry.type` so both types render
-     *  correctly — a previous version typed this as `ButtonNode[]` and called
+    /** Per-row interactive controls. Each entry is either a ButtonNode (its own
+     *  unique action name encodes per-row identity, e.g. `delete-row-42`) or a
+     *  CheckboxNode (its own `bind` path per row). The renderer partitions by
+     *  `entry.type`: CheckboxNodes render in a dedicated LEADING column (left —
+     *  the data-grid selection convention), ButtonNodes in the TRAILING actions
+     *  cell (right). A previous version typed this as `ButtonNode[]` and called
      *  the button renderer blindly, silently dropping non-button entries. */
     actions?: (ButtonNode | CheckboxNode)[];
     variant?: string;

package/dist/server.d.ts

@@ -68,6 +68,63 @@ export declare const shellSideEffect: {
      *  JSON wire, matching the .NET WhenWritingNull null-omission contract. */
     download: (url: string, filename?: string) => ShellSideEffect;
 };
+/**
+ * Mount the canonical VMS agent skill markdown as an HTTP handler.
+ *
+ * The skill is a self-contained operating manual for the VMS wire protocol
+ * (action dispatch shape, state round-trip rules, response envelope vocabulary,
+ * side-effect verbs, polling, errors, file uploads). Advertise it to agents
+ * driving your app via the `skill` field on the
+ * `<meta name="viewmodel-shell">` discoverability tag, pointing at whatever URL
+ * you mount this handler at (recommended: `/.well-known/vms-skill.md`).
+ *
+ * **Canonical source:** `viewmodel-shell/agent-skill.md` (shipped in the npm
+ * package's `files` array; the .NET package embeds a byte-identical copy at
+ * `viewmodel-shell-dotnet/AgentSkill.md` — see `parity/check-skill.ts`).
+ *
+ * **Preamble shape.** When `appPreamble` is supplied (non-empty after trim),
+ * the served body is:
+ *
+ * ```
+ * ## App-specific notes
+ *
+ * <preamble verbatim>
+ *
+ * ---
+ *
+ * <canonical-skill-body verbatim>
+ * ```
+ *
+ * When omitted (or whitespace-only), the served body is the canonical skill
+ * verbatim. The body is computed ONCE at handler-creation time; per-request
+ * cost is a single `new Response(body)`. Multiple handlers with different
+ * preambles are cheap and fully independent.
+ *
+ * **Cross-runtime.** Pure Web Fetch API — works in Bun, Deno, Hono, Cloudflare
+ * Workers, and Node 18+. The application's router owns method/path routing;
+ * the handler accepts any request and unconditionally serves the markdown body
+ * with `Content-Type: text/markdown; charset=utf-8`.
+ *
+ * @example
+ * ```ts
+ * import { createAgentSkillHandler } from "@ashley-shrok/viewmodel-shell/server";
+ * const skillHandler = createAgentSkillHandler({
+ *   appPreamble: "This is the foo app. Auth: Bearer JWT in Authorization.",
+ * });
+ * Bun.serve({
+ *   async fetch(req) {
+ *     const url = new URL(req.url);
+ *     if (url.pathname === "/.well-known/vms-skill.md" && req.method === "GET") {
+ *       return skillHandler(req);
+ *     }
+ *     // ... your other routes
+ *   },
+ * });
+ * ```
+ */
+export declare function createAgentSkillHandler(opts?: {
+    appPreamble?: string;
+}): (req: Request) => Response;
 /**
  * Thrown by an action handler to signal a malformed/invalid request. The
  * createAction wrapper catches this and returns a 400 with the error

package/dist/server.js

@@ -8,6 +8,21 @@
 // Re-export the ViewNode hierarchy and wire types so a backend can import
 // everything it needs from one place.
 export * from "./index.js";
+// ─── Canonical agent skill load (1.6.0 / 1.5.0) ──────────────────────────────
+// Loaded once at module init so createAgentSkillHandler can bake the body at
+// handler-creation time (no per-request fs work). The path resolution works for
+// BOTH layouts:
+//   - Source/dev (vitest):    src/server.ts → ../agent-skill.md
+//   - Published tarball:      dist/server.js → ../agent-skill.md (file is in
+//                             package root, listed in package.json `files`)
+// If `agent-skill.md` is missing at module init the import throws — the
+// fail-loud rule (see AGENTS.md capability-seam doc) applies: a silent 404
+// from the skill endpoint would defeat the purpose.
+import { readFileSync as __vmsReadFileSync } from "node:fs";
+import { fileURLToPath as __vmsFileURLToPath } from "node:url";
+import { dirname as __vmsDirname, join as __vmsJoin } from "node:path";
+const __vmsAgentSkillDir = __vmsDirname(__vmsFileURLToPath(import.meta.url));
+const AGENT_SKILL_MARKDOWN = __vmsReadFileSync(__vmsJoin(__vmsAgentSkillDir, "..", "agent-skill.md"), "utf8");
 /**
  * Walk a ViewNode tree and assert that every dispatch-bearing action name names
  * exactly one operation. Two occurrences are considered "the same operation"
@@ -376,6 +391,71 @@ export const shellSideEffect = {
      *  JSON wire, matching the .NET WhenWritingNull null-omission contract. */
     download: (url, filename) => ({ type: "download", url, ...(filename != null ? { filename } : {}) }),
 };
+// ─── Canonical agent skill mount helper (1.6.0 / 1.5.0) ──────────────────────
+/**
+ * Mount the canonical VMS agent skill markdown as an HTTP handler.
+ *
+ * The skill is a self-contained operating manual for the VMS wire protocol
+ * (action dispatch shape, state round-trip rules, response envelope vocabulary,
+ * side-effect verbs, polling, errors, file uploads). Advertise it to agents
+ * driving your app via the `skill` field on the
+ * `<meta name="viewmodel-shell">` discoverability tag, pointing at whatever URL
+ * you mount this handler at (recommended: `/.well-known/vms-skill.md`).
+ *
+ * **Canonical source:** `viewmodel-shell/agent-skill.md` (shipped in the npm
+ * package's `files` array; the .NET package embeds a byte-identical copy at
+ * `viewmodel-shell-dotnet/AgentSkill.md` — see `parity/check-skill.ts`).
+ *
+ * **Preamble shape.** When `appPreamble` is supplied (non-empty after trim),
+ * the served body is:
+ *
+ * ```
+ * ## App-specific notes
+ *
+ * <preamble verbatim>
+ *
+ * ---
+ *
+ * <canonical-skill-body verbatim>
+ * ```
+ *
+ * When omitted (or whitespace-only), the served body is the canonical skill
+ * verbatim. The body is computed ONCE at handler-creation time; per-request
+ * cost is a single `new Response(body)`. Multiple handlers with different
+ * preambles are cheap and fully independent.
+ *
+ * **Cross-runtime.** Pure Web Fetch API — works in Bun, Deno, Hono, Cloudflare
+ * Workers, and Node 18+. The application's router owns method/path routing;
+ * the handler accepts any request and unconditionally serves the markdown body
+ * with `Content-Type: text/markdown; charset=utf-8`.
+ *
+ * @example
+ * ```ts
+ * import { createAgentSkillHandler } from "@ashley-shrok/viewmodel-shell/server";
+ * const skillHandler = createAgentSkillHandler({
+ *   appPreamble: "This is the foo app. Auth: Bearer JWT in Authorization.",
+ * });
+ * Bun.serve({
+ *   async fetch(req) {
+ *     const url = new URL(req.url);
+ *     if (url.pathname === "/.well-known/vms-skill.md" && req.method === "GET") {
+ *       return skillHandler(req);
+ *     }
+ *     // ... your other routes
+ *   },
+ * });
+ * ```
+ */
+export function createAgentSkillHandler(opts = {}) {
+    const preamble = opts.appPreamble?.trim() ?? "";
+    const body = preamble.length === 0
+        ? AGENT_SKILL_MARKDOWN
+        : `## App-specific notes\n\n${preamble}\n\n---\n\n${AGENT_SKILL_MARKDOWN}`;
+    return (_req) => new Response(body, {
+        status: 200,
+        headers: { "Content-Type": "text/markdown; charset=utf-8" },
+    });
+}
 // ─── Action handler factory ──────────────────────────────────────────────────
 /**
  * Thrown by an action handler to signal a malformed/invalid request. The

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ashley-shrok/viewmodel-shell",
-  "version": "1.5.0",
+  "version": "1.7.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",
@@ -21,6 +21,7 @@
   "files": [
     "dist",
     "styles",
+    "agent-skill.md",
     "README.md",
     "LICENSE"
   ],