@ashley-shrok/viewmodel-shell 0.16.0 → 1.1.0

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,24 @@ export interface TableColumn {
 export interface TableRow {
     id?: string;
     cells: Record<string, string>;
+    /** Click-anywhere row dispatch primitive. When set, the renderer makes the
+     *  entire row clickable AND keyboard-activatable (Enter / Space — Space
+     *  preventDefaults page scroll) AND exposes accessibility (role="button",
+     *  tabindex=0, aria-label derived from cell text). Per-row identity is
+     *  encoded in the action name (e.g. `select-ticket-42`) — no context field,
+     *  consistent with the Phase 6 wire. Coexists with `actions[]`: clicking a
+     *  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
+     *  the button renderer blindly, silently dropping non-button entries. */
+    actions?: (ButtonNode | CheckboxNode)[];
     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 +263,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 +344,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 +393,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 +419,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