@ashley-shrok/viewmodel-shell 0.16.0 → 1.0.1

package/dist/index.d.ts

@@ -1,10 +1,20 @@
 export interface ActionEvent {
     name: string;
-    context?: Record<string, unknown>;
     files?: Record<string, File>;
 }
+export interface StateAccess {
+    read(path: string): unknown;
+    write(path: string, value: unknown): void;
+}
 export interface Adapter {
-    render(vm: ViewNode, onAction: (action: ActionEvent) => void): void;
+    /** Render the view tree. `stateAccess` is the shell-owned `{ read, write }`
+     *  seam over the live state object: the adapter reads input values via
+     *  `stateAccess.read(node.bind)` and writes user input back via
+     *  `stateAccess.write(node.bind, value)`. The third arg is OPTIONAL so
+     *  callers (tests, embedders) that have no live state can still mount
+     *  the adapter for class-emission / static-tree checks — adapters supply
+     *  a no-op fallback internally when omitted. */
+    render(vm: ViewNode, onAction: (action: ActionEvent) => void, stateAccess?: StateAccess): 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. */
@@ -98,12 +108,12 @@ export interface FormNode {
     /** Layout preset for the form's controls. Omitted or "stack" = fields stacked (current, no modifier class). "inline" = field row + submit on one line (add/search bar) — emits .vms-form--inline. Closed union (D-29). */
     layout?: "stack" | "inline";
     /** Multi-action submit buttons (#15). Each is a full ButtonNode (so
-     *  `variant` + `pendingLabel` apply) that, on activation, HARVESTS this
-     *  form's current field values into its `action.context` and dispatches —
-     *  the same harvest the default submit performs, but carrying a different
-     *  action. Mirrors HTML's multiple submit buttons / `formaction`. A plain
-     *  ButtonNode placed in `children` keeps its no-harvest behavior; only
-     *  buttons in THIS slot harvest. */
+     *  `variant` + `pendingLabel` apply) that, on activation, dispatches its
+     *  declared action by name. Field values live in state at each input's
+     *  `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. */
     buttons?: ButtonNode[];
     children: ViewNode[];
 }
@@ -111,9 +121,10 @@ 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;
     label?: string;
     placeholder?: string;
-    value?: string;
     required?: boolean;
     options?: Array<{
         value: string;
@@ -124,15 +135,18 @@ export interface FieldNode {
      *  library (CodeMirror, Monaco, etc.) — the framework only ships
      *  monospaced editable text, no coloring. */
     language?: string;
-    /** Dispatched when Enter is pressed (text-like inputs only). Adapter merges { [name]: value } into context. */
+    /** 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;
 }
 export interface CheckboxNode {
     type: "checkbox";
     name: string;
-    checked: boolean;
+    /** Path into state where this input reads its current value and writes user changes (e.g. `fields.title`). */
+    bind: string;
     label?: string;
-    /** Dispatched immediately on change. Adapter merges { checked: boolean } into context. */
+    /** Dispatched immediately on change. Carries an action name only — the new
+     *  checked value is already in state at the bind path. */
     action?: ActionEvent;
 }
 export interface ButtonNode {
@@ -182,11 +196,15 @@ export interface StatBarNode {
 export interface TabsNode {
     type: "tabs";
     selected: string;
-    /** Base action. Adapter merges { value: tab.value } into context on click. */
-    action: ActionEvent;
+    /** Path into state where this input reads its current value and writes user changes (e.g. `fields.title`). */
+    bind: string;
+    /** Each tab declares its own action — the framework requires a unique action
+     *  name per tab (e.g. `select-tab-pending`, `select-tab-active`). The renderer
+     *  writes `value` to the bound state path before dispatching the action. */
     tabs: Array<{
         value: string;
         label: string;
+        action: ActionEvent;
     }>;
 }
 export interface ProgressNode {
@@ -219,25 +237,12 @@ export interface TableColumn {
 export interface TableRow {
     id?: string;
     cells: Record<string, string>;
-    action?: ActionEvent;
+    /** Per-row action buttons. Each is a full ButtonNode with its own unique
+     *  action name (e.g. `delete-row-42`, `close-ticket-42`) — per-row identity
+     *  is encoded in the name, not as a separate context payload. */
+    actions?: ButtonNode[];
     variant?: string;
 }
-export interface TableSelection {
-    /** Row ids that should render PRE-SELECTED on initial render — the server's
-     *  initial pre-selection. Subsequent toggles are purely client-side DOM state;
-     *  the server doesn't see them until a `buttons[]` click harvests them. */
-    selectedIds: string[];
-    /** When present, the adapter renders these as a bulk-action toolbar ABOVE
-     *  the table. On click, each button harvests the currently-checked rows from
-     *  the DOM and dispatches its `action` with `{ selectedIds: [...] }` merged
-     *  into its `context`. This is the only way to act on the selection — there
-     *  is no per-toggle dispatch (0.15.0 removed the `action` mode that did,
-     *  because rapid clicks were dropped by the dispatch guard and the in-flight
-     *  response wiped the DOM). If a future release needs cross-page persistence
-     *  or live "N selected" indicators, the way back is a redesigned wire shape
-     *  (dispatch queueing + optimistic preservation), not the old `action` mode. */
-    buttons?: ButtonNode[];
-}
 export interface TablePagination {
     /** 1-based current page. */
     page: number;
@@ -246,30 +251,38 @@ export interface TablePagination {
     /** Total rows across all pages — server-truth. The adapter renders the range
      *  label and enables/disables prev/next from this; it does NOT slice. */
     totalRows: number;
-    /** Dispatched on a page-control click. The adapter merges `{ page }` — the
-     *  target 1-based page. */
-    action: ActionEvent;
+    /** Dispatched on the prev page-control click. Carries an action name only —
+     *  the renderer writes the target page to TableNode.paginationBind before dispatch. */
+    prevAction?: ActionEvent;
+    /** Dispatched on the next page-control click. Carries an action name only —
+     *  the renderer writes the target page to TableNode.paginationBind before dispatch. */
+    nextAction?: ActionEvent;
 }
 export interface TableNode {
     type: "table";
     columns: TableColumn[];
     rows: TableRow[];
-    sortColumn?: string;
-    sortDirection?: "asc" | "desc";
-    /** Base action. Adapter merges { column, direction } into context on header click. */
-    sortAction?: ActionEvent;
-    /** Base action. Adapter merges { column, value, filters } into context on Enter. */
+    /** Path into state where the current sort intent (`{column, direction}`) is read/written. */
+    sortBind?: string;
+    /** Per-column filter input bind paths. The renderer reads/writes filter
+     *  values at these paths; the values then travel with the next dispatch. */
+    filterBinds?: Record<string, string>;
+    /** Path into state where the renderer writes the target page number before
+     *  firing `pagination.prevAction` / `pagination.nextAction`. */
+    paginationBind?: string;
+    /** Per-column sort header click actions, keyed by column key. Each carries a
+     *  unique action name — the renderer writes the new sort intent to `sortBind`
+     *  before dispatching. */
+    sortActions?: Record<string, ActionEvent>;
+    /** One filter-dispatch action per table. The renderer fires this when the
+     *  user submits the filter form; per-column filter values are already in
+     *  state at the `filterBinds` paths. */
     filterAction?: ActionEvent;
-    /** Per-row multi-select. When set, the adapter renders a leading checkbox
-     *  column + a header select-all checkbox and tints selected rows. `TableRow.id`
-     *  is REQUIRED on every row when selection is set — it's the address the
-     *  toggle action reports back. */
-    selection?: TableSelection;
     /** Server-driven pagination. When set, the adapter renders an "X–Y of N"
      *  range + prev/next controls below the table. **The server slices `rows` to
      *  the current page** — the adapter never paginates client-side (that would
      *  break for DB-backed tables, which are most of them). By convention
-     *  `sortAction` / `filterAction` reset `page` to 1 on the server side, since
+     *  filter dispatches reset `page` to 1 on the server side, since
      *  the row window changes underneath them. */
     pagination?: TablePagination;
 }
@@ -319,6 +332,36 @@ export interface ShellSideEffect {
      *  when present; this is the fallback before the URL basename. */
     filename?: string;
 }
+/** One entry in the structured error payload returned on `ok: false`. */
+export interface ErrorEntry {
+    /** Absent when not tied to a specific input slot (parse errors, uncaught
+     *  exceptions, etc.). Present when bound to a specific bind-path on an input. */
+    path?: string;
+    /** Human-readable description of the error. Always present. */
+    message: string;
+    /** Framework-set discriminator for the failure class. Initial vocabulary:
+     *  "parse_error" | "unknown_action" | "invalid_tree" | "uncaught_exception".
+     *  Absent when not applicable (e.g. BadRequest / D-08 path). */
+    code?: string;
+}
+/**
+ * Structured error surfaced via `onError` when the server returns `ok: false`.
+ * Extends `Error` so existing `onError` consumers that don't know about the
+ * envelope continue receiving a normal Error with a useful `.message`.
+ *
+ * Consumers that want the structured payload: `if (err instanceof VmsActionError) { ... err.errors ... }`.
+ *
+ * `status` is the HTTP status code (0 for push-originated errors with no
+ * HTTP transaction). `code` is a shortcut to `errors[0].code` for ergonomic
+ * branching on single-error responses.
+ */
+export declare class VmsActionError extends Error {
+    readonly errors: ErrorEntry[];
+    readonly status: number;
+    constructor(errors: ErrorEntry[], status: number);
+    /** Shortcut to `errors[0]?.code`. Undefined when the first entry has no code. */
+    get code(): string | undefined;
+}
 export interface ShellResponse {
     vm: ViewNode;
     state: unknown;
@@ -338,6 +381,14 @@ export interface ShellResponse {
      *  dispatches; the adapter applies `.vms-busy` for the visual cue). Polls
      *  bypass so the server can clear the state. See `Adapter.setBusy`. */
     busy?: boolean;
+    /** 1.0.0 — framework-set envelope flag. Present on every framework-rendered
+     *  response; absent on hand-constructed legacy push bodies (treated as ok:true
+     *  for backwards compatibility). On ok:false responses, only `errors[]` is
+     *  consumed — any vm/state present in the body is IGNORED at runtime (D-15
+     *  hardening: the shell throws before the currentVm/currentState writes run). */
+    ok?: boolean;
+    /** 1.0.0 — structured error entries. Present when `ok: false`. */
+    errors?: ErrorEntry[];
 }
 export declare class ViewModelShell {
     private options;
@@ -356,6 +407,35 @@ export declare class ViewModelShell {
     stopPolling(): void;
     getCurrentVm(): ViewNode | null;
     getCurrentState(): unknown;
+    /**
+     * Read the bound state value at a dotted path (e.g. "fields.title",
+     * "rows.42.selected"). Used by adapters (BrowserAdapter, TuiAdapter, …) to
+     * render an input's current value. Returns `undefined` when any segment
+     * along the path is missing — adapters treat that as "no value set" and
+     * render the appropriate empty form (empty string, unchecked, etc.).
+     *
+     * This is half of the bind-path seam introduced in Phase 6: the shell holds
+     * state mutably so that input events can update it (via `stateWrite`)
+     * without round-tripping to the server until a real dispatch fires.
+     */
+    stateRead(path: string): unknown;
+    /**
+     * Write a value into state at a dotted path. The shell mutates the held
+     * state object in place at the bind path; the next dispatch sends the
+     * updated state to the server. Intermediate objects/arrays are created on
+     * demand (numeric next segment → array, else object).
+     *
+     * This is the other half of the bind-path seam — the BrowserAdapter (or any
+     * adapter that supports user input) calls this on every keystroke / change
+     * event so drafts ARE state.
+     */
+    stateWrite(path: string, value: unknown): void;
+    /**
+     * Build the read/write seam the Adapter receives as its third render arg.
+     * Backed by `stateRead` / `stateWrite` so the adapter never needs a direct
+     * reference to the shell.
+     */
+    private stateAccessForAdapter;
     private failCapability;
     private processResponse;
     private schedulePoll;

package/dist/index.js

@@ -1,4 +1,41 @@
 // ─── Action ──────────────────────────────────────────────────────────────────
+/**
+ * Private helper: compose a human-readable `.message` from an errors array.
+ * Single entry → the entry's message verbatim.
+ * Multiple entries → "<first> (and N more)" so console.error is still useful.
+ */
+function summarizeErrors(errors) {
+    if (errors.length === 0)
+        return "Server returned ok:false with no error details";
+    if (errors.length === 1)
+        return errors[0].message;
+    return `${errors[0].message} (and ${errors.length - 1} more)`;
+}
+/**
+ * Structured error surfaced via `onError` when the server returns `ok: false`.
+ * Extends `Error` so existing `onError` consumers that don't know about the
+ * envelope continue receiving a normal Error with a useful `.message`.
+ *
+ * Consumers that want the structured payload: `if (err instanceof VmsActionError) { ... err.errors ... }`.
+ *
+ * `status` is the HTTP status code (0 for push-originated errors with no
+ * HTTP transaction). `code` is a shortcut to `errors[0].code` for ergonomic
+ * branching on single-error responses.
+ */
+export class VmsActionError extends Error {
+    errors;
+    status;
+    constructor(errors, status) {
+        super(summarizeErrors(errors));
+        this.errors = errors;
+        this.status = status;
+        this.name = "VmsActionError";
+    }
+    /** Shortcut to `errors[0]?.code`. Undefined when the first entry has no code. */
+    get code() {
+        return this.errors[0]?.code;
+    }
+}
 export class ViewModelShell {
     options;
     currentVm = null;
@@ -25,9 +62,25 @@ export class ViewModelShell {
             const url = params ? `${endpoint}?${new URLSearchParams(params)}` : endpoint;
             const extraHeaders = this.options.getRequestHeaders ? await this.options.getRequestHeaders() : {};
             const res = await fetch(url, { headers: { Accept: "application/json", ...extraHeaders } });
-            if (!res.ok)
+            // 1.0.0 — parse-then-branch: always parse the body even on 4xx/5xx so the
+            // structured envelope is available. The ok:false check throws BEFORE the
+            // currentVm/currentState writes below — D-15 runtime hardening (throw-before-
+            // write ordering means the shell never mutates state from a failure body).
+            let body;
+            try {
+                body = (await res.json());
+            }
+            catch (_parseErr) {
+                // Non-JSON body on a 4xx/5xx (proxy error page, 502, etc.).
+                // Fall back to a plain Error — the body was never a VMS envelope.
                 throw new Error(`${res.status} ${res.statusText}`);
-            const body = (await res.json());
+            }
+            if (body.ok === false) {
+                // D-15 runtime hardening: throw BEFORE currentVm/currentState are written.
+                // Even if the server (incorrectly) sent vm/state on an ok:false response,
+                // neither field is consumed — type-erosion-safe.
+                throw new VmsActionError(body.errors ?? [{ message: `${res.status} ${res.statusText}` }], res.status);
+            }
             this.currentVm = body.vm;
             this.currentState = body.state;
             // 0.14.0 — apply the unload guard from the initial-load response too. The
@@ -37,7 +90,7 @@ export class ViewModelShell {
             // 0.16.0 — same for the busy lockout.
             this.serverBusy = body.busy ?? false;
             this.syncBusy();
-            adapter.render(body.vm, (action) => this.dispatch(action));
+            adapter.render(body.vm, (action) => this.dispatch(action), this.stateAccessForAdapter());
             this.schedulePoll(body.nextPollIn);
         }
         catch (err) {
@@ -75,7 +128,10 @@ export class ViewModelShell {
                 onLoading?.(true);
             }
             const form = new FormData();
-            form.append("_action", JSON.stringify({ name: action.name, context: action.context ?? {} }));
+            // Phase 6 — wire-shape break: `_action` carries the action name only.
+            // The state at the input's bind path holds whatever value the previous
+            // `context` payload used to carry; the server reads it from there.
+            form.append("_action", JSON.stringify({ name: action.name }));
             form.append("_state", JSON.stringify(this.currentState));
             if (action.files) {
                 for (const [name, file] of Object.entries(action.files)) {
@@ -98,9 +154,27 @@ export class ViewModelShell {
             else {
                 res = await fetch(actionEndpoint, init);
             }
-            if (!res.ok)
-                throw new Error(`Action '${action.name}' failed: ${res.status}`);
-            this.processResponse((await res.json()));
+            // 1.0.0 — parse-then-branch: always parse the body even on 4xx/5xx so the
+            // structured envelope is available to construct VmsActionError. The existing
+            // catch arm below re-renders currentVm on error (D-15 behavior) — VmsActionError
+            // flows through that same path since it IS an Error instance.
+            let body;
+            try {
+                body = (await res.json());
+            }
+            catch (_parseErr) {
+                // Non-JSON body on a 4xx/5xx (proxy error page, 502, etc.).
+                // Fall back to a plain Error — the body was never a VMS envelope.
+                throw new Error(`Action '${action.name}' failed: ${res.status} ${res.statusText}`);
+            }
+            if (body.ok === false) {
+                // D-15 runtime hardening: throw BEFORE this.processResponse(body) runs.
+                // The throw skips processResponse entirely, so currentVm/currentState are
+                // NOT updated from the failure body — even if the server (incorrectly) sent
+                // vm/state on an ok:false response. Type-erosion-safe.
+                throw new VmsActionError(body.errors ?? [{ message: `Action '${action.name}' failed: ${res.status}` }], res.status);
+            }
+            this.processResponse(body);
         }
         catch (err) {
             const error = err instanceof Error ? err : new Error(String(err));
@@ -112,7 +186,7 @@ export class ViewModelShell {
             // Skipped when no VM has loaded yet (pre-initial-load dispatch is
             // already an error case handled above; currentVm stays null there).
             if (this.currentVm !== null) {
-                this.options.adapter.render(this.currentVm, (a) => this.dispatch(a));
+                this.options.adapter.render(this.currentVm, (a) => this.dispatch(a), this.stateAccessForAdapter());
             }
         }
         finally {
@@ -128,6 +202,16 @@ export class ViewModelShell {
     push(response) {
         if (this.dispatching)
             return;
+        // 1.0.0 — parse-then-branch for push. External push consumers (SSE, WebSocket)
+        // may feed ok:false responses (e.g. a server-pushed error notification). Route
+        // them to onError WITHOUT calling processResponse — currentVm/currentState
+        // are NOT updated (D-15 runtime hardening for the push path).
+        // status: 0 because there was no HTTP transaction in an external push.
+        if (response.ok === false) {
+            const err = new VmsActionError(response.errors ?? [{ message: "Server pushed ok:false envelope" }], 0);
+            this.options.onError ? this.options.onError(err) : console.error("[ViewModelShell]", err);
+            return;
+        }
         this.processResponse(response);
     }
     stopPolling() {
@@ -138,6 +222,44 @@ export class ViewModelShell {
     }
     getCurrentVm() { return this.currentVm; }
     getCurrentState() { return this.currentState; }
+    /**
+     * Read the bound state value at a dotted path (e.g. "fields.title",
+     * "rows.42.selected"). Used by adapters (BrowserAdapter, TuiAdapter, …) to
+     * render an input's current value. Returns `undefined` when any segment
+     * along the path is missing — adapters treat that as "no value set" and
+     * render the appropriate empty form (empty string, unchecked, etc.).
+     *
+     * This is half of the bind-path seam introduced in Phase 6: the shell holds
+     * state mutably so that input events can update it (via `stateWrite`)
+     * without round-tripping to the server until a real dispatch fires.
+     */
+    stateRead(path) {
+        return readPath(this.currentState, path);
+    }
+    /**
+     * Write a value into state at a dotted path. The shell mutates the held
+     * state object in place at the bind path; the next dispatch sends the
+     * updated state to the server. Intermediate objects/arrays are created on
+     * demand (numeric next segment → array, else object).
+     *
+     * This is the other half of the bind-path seam — the BrowserAdapter (or any
+     * adapter that supports user input) calls this on every keystroke / change
+     * event so drafts ARE state.
+     */
+    stateWrite(path, value) {
+        this.currentState = writePath(this.currentState, path, value);
+    }
+    /**
+     * Build the read/write seam the Adapter receives as its third render arg.
+     * Backed by `stateRead` / `stateWrite` so the adapter never needs a direct
+     * reference to the shell.
+     */
+    stateAccessForAdapter() {
+        return {
+            read: (path) => this.stateRead(path),
+            write: (path, value) => this.stateWrite(path, value),
+        };
+    }
     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: ` +
@@ -191,7 +313,7 @@ export class ViewModelShell {
         }
         this.currentVm = body.vm;
         this.currentState = body.state;
-        this.options.adapter.render(body.vm, (a) => this.dispatch(a));
+        this.options.adapter.render(body.vm, (a) => this.dispatch(a), this.stateAccessForAdapter());
         this.schedulePoll(body.nextPollIn);
     }
     schedulePoll(nextPollIn) {
@@ -246,6 +368,105 @@ export class ViewModelShell {
         }
     }
 }
+// ─── Bind-path walkers (file-private; no platform globals) ───────────────────
+//
+// Tiny JSON walk + write helpers consumed by stateRead/stateWrite. Numeric
+// segments index into arrays when the current value is an array; otherwise
+// they're object keys. writePath creates intermediate objects/arrays on
+// demand when the next segment shape implies one. Bind paths arrive trimmed
+// of leading/trailing dots; an empty path writes to the root.
+// Reject segments that would mutate Object.prototype on write or expose it on
+// read. The bind string is server-controlled today, but stateWrite() is a
+// public method and demos build bind paths dynamically; the guard is defense
+// in depth so consumer code can never turn a path string into prototype pollution.
+function isUnsafeSegment(seg) {
+    return seg === "__proto__" || seg === "constructor" || seg === "prototype";
+}
+function readPath(obj, path) {
+    // Defense: a bind-less input that somehow reached the renderer would call
+    // here with path=undefined. The wire contract guarantees `bind` on every
+    // input, but the runtime should not crash if a malformed tree leaks
+    // through — return undefined and let the field render as empty.
+    if (path == null || path === "")
+        return path == null ? undefined : obj;
+    const segs = path.split(".");
+    let cur = obj;
+    for (const seg of segs) {
+        if (isUnsafeSegment(seg))
+            return undefined;
+        if (cur == null)
+            return undefined;
+        if (Array.isArray(cur)) {
+            const idx = Number(seg);
+            if (!Number.isInteger(idx) || idx < 0)
+                return undefined;
+            cur = cur[idx];
+        }
+        else if (typeof cur === "object") {
+            cur = cur[seg];
+        }
+        else {
+            return undefined;
+        }
+    }
+    return cur;
+}
+function writePath(obj, path, value) {
+    // Defense: drop writes from bind-less inputs (see readPath).
+    if (path == null)
+        return obj;
+    if (path === "")
+        return value;
+    const segs = path.split(".");
+    for (const seg of segs) {
+        if (isUnsafeSegment(seg))
+            return obj;
+    }
+    // Bootstrap a root if the current state is null/undefined; choose the shape
+    // implied by the first segment (numeric ⇒ array, else object).
+    let root = obj;
+    if (root == null || typeof root !== "object") {
+        root = isArrayIndexSegment(segs[0]) ? [] : {};
+    }
+    let cur = root;
+    for (let i = 0; i < segs.length - 1; i++) {
+        const seg = segs[i];
+        if (Array.isArray(cur)) {
+            const idx = Number(seg);
+            let nxt = cur[idx];
+            if (nxt == null || typeof nxt !== "object") {
+                // Intermediate slot creation: default to object. The next segment's
+                // shape can't be inferred safely (numeric keys appear in both arrays
+                // and maps keyed by id), so the round-trip-safe default is {}. The
+                // root bootstrap above remains the only place the array heuristic
+                // fires — there we genuinely have no parent shape to honor.
+                nxt = {};
+                cur[idx] = nxt;
+            }
+            cur = nxt;
+        }
+        else {
+            const o = cur;
+            let nxt = o[seg];
+            if (nxt == null || typeof nxt !== "object") {
+                nxt = {};
+                o[seg] = nxt;
+            }
+            cur = nxt;
+        }
+    }
+    const last = segs[segs.length - 1];
+    if (Array.isArray(cur)) {
+        cur[Number(last)] = value;
+    }
+    else {
+        cur[last] = value;
+    }
+    return root;
+}
+function isArrayIndexSegment(seg) {
+    return /^[0-9]+$/.test(seg);
+}
 // ─── Download helpers (file-private; no platform globals) ────────────────────
 // `Blob` and `URL` are universals (browser, Node 18+, Deno, Bun) — confirmed
 // off the check:core-globals denylist. `URL.createObjectURL` is browser-only

package/dist/server.d.ts

@@ -1,15 +1,29 @@
 import type { ViewNode, ShellSideEffect } from "./index.js";
 export * from "./index.js";
+/**
+ * Walk a ViewNode tree and assert that every dispatch-bearing action name names
+ * exactly one operation. Two occurrences are considered "the same operation"
+ * iff they share the same enclosing FormNode reference; otherwise a duplicate
+ * action name is a violation.
+ *
+ * Call this from your GET handler before returning the initial response if you
+ * want the same protection at initial-load time — the action-handler wrapper
+ * (`createAction`) calls it automatically on every response that carries `vm`.
+ *
+ * @throws Error when a violation is found. The message names the colliding
+ *   action and suggests the two fixes (rename one node, or move both into the
+ *   same enclosing form).
+ */
+export declare function validateActionNames(vm: ViewNode): void;
 export interface ActionPayload<TState> {
     name: string;
-    context: Record<string, unknown> | null;
     state: TState;
     /** Populated only on multipart submissions (FormData). Empty for JSON bodies. */
     files: Record<string, File>;
 }
 /** Parse a multipart/form-data action body — the wire format the TypeScript shell uses. */
 export declare function parseFormDataAction<TState>(formData: FormData): ActionPayload<TState>;
-/** Parse a flat JSON action body — { name, context, state }. For curl/agent callers. */
+/** Parse a flat JSON action body — `{name, state}`. For curl/agent callers. */
 export declare function parseJsonAction<TState>(body: string | object): ActionPayload<TState>;
 /** What an action handler returns. All fields are optional — see ShellResponse reference in AGENTS.md. */
 export interface ShellResponseBody<TState> {
@@ -43,6 +57,63 @@ export declare const shellSideEffect: {
      *  JSON wire, matching the .NET WhenWritingNull null-omission contract. */
     download: (url: string, filename?: string) => ShellSideEffect;
 };
+/**
+ * Thrown by an action handler to signal a malformed/invalid request. The
+ * createAction wrapper catches this and returns a 400 with the error
+ * message in the body, matching the .NET twin's BadRequest("...") path.
+ * Reserved for "structurally invalid request the user can't see" (missing
+ * required action field, etc.) — NOT for routine app validation (that stays
+ * state-based per gotcha #4). No `code` is set on the wire entry (D-08).
+ */
+export declare class BadRequestError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown by an action handler to signal that the dispatched action name is
+ * not recognised. The createAction wrapper catches this and returns a 400
+ * with `code: "unknown_action"` in the envelope, allowing agents to distinguish
+ * "I sent a name your tree doesn't expose" from "your handler crashed."
+ *
+ * Usage — add a default arm to your dispatch switch:
+ *   default: throw new UnknownActionError(payload.name);
+ *
+ * Mirrors .NET `UnknownActionException` — both backends use the same wire code.
+ */
+export declare class UnknownActionError extends Error {
+    /** The offending action name sent by the client. */
+    readonly actionName: string;
+    constructor(actionName: string);
+}
+/**
+ * The entry shape inside the `errors[]` array of an `ok: false` envelope.
+ * `path` and `code` are optional — absent (not null) when not applicable,
+ * per the WhenWritingNull / conditional-spread null-omission contract.
+ */
+export interface ErrorEntry {
+    path?: string;
+    message: string;
+    code?: string;
+}
+/**
+ * Stable, framework-only error code vocabulary. Apps MUST NOT set these —
+ * the framework sets `code` on framework-detected failures only. Agents
+ * that want generic handling check `ok`; agents that want to branch by
+ * failure class check `code` against these constants.
+ *
+ * D-03 lock: "small, stable, framework-only set."
+ */
+export declare const ERR_CODES: {
+    /** Malformed / unparseable request body. HTTP 400. */
+    readonly PARSE: "parse_error";
+    /** App threw `UnknownActionError` (action name not recognised). HTTP 400. */
+    readonly UNKNOWN_ACTION: "unknown_action";
+    /** Built view tree violates the action-name uniqueness rule. HTTP 500. */
+    readonly INVALID_TREE: "invalid_tree";
+    /** App handler threw an unrecognised exception. HTTP 500. */
+    readonly UNCAUGHT: "uncaught_exception";
+};
+/** Union type of the framework error codes from ERR_CODES. Useful for narrowing `errors[0].code`. */
+export type ErrCode = typeof ERR_CODES[keyof typeof ERR_CODES];
 /**
  * Web Fetch API–native request handler factory. Auto-detects content-type
  * (application/json vs multipart/form-data), parses the body, calls your