@nanobpm/urban 0.61.0 → 0.63.0

package/dist/runtime/index.d.ts

@@ -14,6 +14,7 @@ export type { AppApi, Mounted, RuntimeContext } from "./core/context.ts";
 export { createLogger } from "./core/logger.ts";
 export type { Logger, LogLevel, LogFields, LogSink } from "./core/logger.ts";
 export { BpmnError, isBpmnError } from "./core/host.ts";
+export { ENGINE_CLIENT_METHODS } from "./core/host.ts";
 export { adaptConnectorHandler, mountConnectors, resolveInstalledConnectors, } from "./core/modules/connectors.ts";
 export type { ConnectorsHandle } from "./core/modules/connectors.ts";
 export { DataLayer, TypeRepo } from "./core/modules/datasource.ts";

package/dist/runtime/index.js

@@ -18,6 +18,10 @@ export { createLogger } from "./core/logger.js";
 // BPMN error contract: a handler throws `BpmnError(code)` to raise a modelled
 // error routed to an error boundary (ADR 0050), instead of a retryable failure.
 export { BpmnError, isBpmnError } from "./core/host.js";
+// The runtime source of truth for the `EngineClient` method surface (issue #341): a test
+// double / adapter iterates it to prove at runtime that it implements the full interface,
+// catching the "fake lags the SDK" seam-lag class categorically.
+export { ENGINE_CLIENT_METHODS } from "./core/host.js";
 // Connector packs (ADR 0050, in-process port)
 export { adaptConnectorHandler, mountConnectors, resolveInstalledConnectors, } from "./core/modules/connectors.js";
 // Data layer

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.61.0",
+	"version": "0.63.0",
 	"description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
 	"license": "Apache-2.0",
 	"type": "module",

package/src/runtime/browser/runtime.browser.js

@@ -1514,6 +1514,80 @@ function renderProse(node) {
   return card;
 }
 
+// Build a detail/escalation answer form for a single grid row. This is the ONE
+// implementation of the `detail.form` contract — shared verbatim by the
+// top-level grid's detail panel AND a dataGrid child-grid row (#333) so the two
+// can never drift. The form has a single free-text field (f.inputKey), an
+// optional prompt echoed from the row (f.promptField), and a route-driven submit
+// (f.action) whose path/body interpolate {{form.*}} / {{row.*}} tokens. It
+// renders only when the row's f.showWhenField is truthy (an answerable
+// escalation), returning null otherwise. On a successful submit it invokes
+// onSuccess — the top-level grid re-polls the whole page (pc:refresh) so the
+// answered row drops out on the next tick; a child grid re-fetches just its own
+// rows, matching the Tasks page where the row disappears once its user-task
+// completes.
+// A disclosure chevron for expanding an inline detail row. This is the ONE place
+// a "▸/▾" toggle button is built, so the glyph and its `aria-expanded` state can
+// never drift apart (they used to be set independently, leaving assistive tech
+// unaware a row had opened). Every chevron gets an explicit type="button" (so it
+// never submits an enclosing form) and an accessible name.
+/** @param {string} [label] @returns {HTMLElement} */
+function chevronToggle(label) {
+  return el("button", {
+    class: "pc-btn pc-btn-sm pc-chevron",
+    type: "button",
+    "aria-label": label || "Toggle details",
+    "aria-expanded": "false",
+  }, "▸");
+}
+// Set a chevron's open/closed state, keeping the glyph and aria-expanded in lock-step.
+/** @param {HTMLElement} btn @param {boolean} open */
+function setChevronOpen(btn, open) {
+  btn.textContent = open ? "▾" : "▸";
+  btn.setAttribute("aria-expanded", String(open));
+}
+
+/** @param {any} f
+ *  @param {Record<string, any>} row
+ *  @param {() => void | Promise<void>} onSuccess
+ *  @returns {HTMLElement|null}
+ */
+function buildDetailForm(f, row, onSuccess) {
+  if (!f || !row[f.showWhenField]) return null;
+  const box = el("div", { class: "pc-subform" });
+  if (f.title) box.append(el("div", { class: "pc-subform-title" }, f.title));
+  if (f.promptField && row[f.promptField] != null) {
+    box.append(el("div", { class: "pc-prompt" }, String(row[f.promptField])));
+  }
+  const input = el("textarea", { class: "pc-textarea", placeholder: f.inputLabel || f.inputKey, "aria-label": f.inputLabel || f.inputKey });
+  // role=status + aria-live so the "Sending…"/success/error transitions are
+  // announced to screen readers instead of silently changing text.
+  const msg = el("p", { class: "pc-msg", role: "status", "aria-live": "polite" });
+  const btn = el("button", { class: "pc-btn pc-btn-sm", type: "button" }, f.submitLabel || "Submit");
+  btn.addEventListener("click", async () => {
+    btn.disabled = true; msg.className = "pc-msg"; msg.textContent = "Sending…";
+    try {
+      // The textarea value is the form's single field (f.inputKey); route + body
+      // template come from f.action, e.g. { path: "/app/actions/message",
+      // body: { name, correlationKey: "{{row.pr_key}}", variables: "{{form}}" } }.
+      // Null-proto so an f.inputKey of "__proto__"/"constructor" can't mutate a prototype.
+      const form = Object.create(null); form[f.inputKey] = input.value;
+      await runRoute(f.action, { form, row });
+      msg.className = "pc-msg ok"; msg.textContent = (f.action && f.action.successLabel) || "Sent";
+      // Await onSuccess so a refresh that rejects (e.g. a child grid's re-fetch
+      // failing) is surfaced here and re-enables the button below, instead of the
+      // operator being stuck on a permanently-disabled button with a silent
+      // failure. On success the refresh detaches/rebuilds this form, so leaving
+      // the button disabled is moot; we only re-enable on the error path.
+      await onSuccess();
+    } catch (e) {
+      btn.disabled = false; msg.className = "pc-msg err"; msg.textContent = String(e.message || e);
+    }
+  });
+  box.append(el("div", { class: "pc-field" }, input), btn, msg);
+  return box;
+}
+
 /** @param {any} node */
 function renderDataGrid(node) {
   const p = node.props;
@@ -1630,42 +1704,6 @@ function renderDataGrid(node) {
     return b;
   }
 
-  /** @param {Record<string, any>} row
-   * @param {any} formCfg the panel's own form config (top-level or child grid); a
-   *   missing/undefined form means this panel has no form — it must NOT fall back to
-   *   the top-level grid's form, or a child panel would render the parent's form.
-   * @returns {HTMLElement|null}
-   */
-  function detailForm(row, formCfg) {
-    const f = formCfg;
-    if (!f || !row[f.showWhenField]) return null;
-    const box = el("div", { class: "pc-subform" });
-    if (f.title) box.append(el("div", { class: "pc-subform-title" }, f.title));
-    if (f.promptField && row[f.promptField] != null) {
-      box.append(el("div", { class: "pc-prompt" }, String(row[f.promptField])));
-    }
-    const input = el("textarea", { class: "pc-textarea", placeholder: f.inputLabel || f.inputKey });
-    const msg = el("p", { class: "pc-msg" });
-    const btn = el("button", { class: "pc-btn pc-btn-sm" }, f.submitLabel || "Submit");
-    btn.addEventListener("click", async () => {
-      btn.disabled = true; msg.className = "pc-msg"; msg.textContent = "Sending…";
-      try {
-        // The textarea value is the form's single field (f.inputKey); route + body
-        // template come from f.action, e.g. { path: "/app/actions/message",
-        // body: { name, correlationKey: "{{row.pr_key}}", variables: "{{form}}" } }.
-        // Null-proto so an f.inputKey of "__proto__"/"constructor" can't mutate a prototype.
-        const form = Object.create(null); form[f.inputKey] = input.value;
-        await runRoute(f.action, { form, row });
-        msg.className = "pc-msg ok"; msg.textContent = (f.action && f.action.successLabel) || "Sent";
-        document.dispatchEvent(new CustomEvent("pc:refresh"));
-      } catch (e) {
-        btn.disabled = false; msg.className = "pc-msg err"; msg.textContent = String(e.message || e);
-      }
-    });
-    box.append(el("div", { class: "pc-field" }, input), btn, msg);
-    return box;
-  }
-
   /** @param {any} cg
    * @param {Record<string, any>} row
    */
@@ -1685,7 +1723,11 @@ function renderDataGrid(node) {
     // parent rowKey + child rowKey, so it survives the top-level grid's refresh
     // poll (which rebuilds this whole subtree) and a full reload, mirroring how
     // groupBy group-collapse is persisted. Absent a `detail` block the child grid
-    // is byte-for-byte unchanged (backward compatible).
+    // is byte-for-byte unchanged (backward compatible). A `detail.form` (#333) is
+    // rendered inside that panel by the shared detailPanel/buildDetailForm, and its
+    // submit re-fetches only this child grid (see load() below) rather than the
+    // whole page — so answering a nested escalation drops the answered row without
+    // disturbing the parent grid.
     const cdetail = cg.detail || cg.expandable || null;
     const chasExpand = cdetail != null;
     const cextra = (cg.lazyField ? 1 : 0) + (chasExpand ? 1 : 0);
@@ -1727,12 +1769,20 @@ function renderDataGrid(node) {
     // the catch's error row have a valid, table-spanning colspan — if getJSON()
     // throws, a lazily-assigned cspan would still be undefined here.
     const cspan = String((ccols.length || 1) + cextra);
-    try {
+    // Re-fetch and repaint just this child grid's rows. Wired to the child detail
+    // panel's form onSuccess so answering a nested escalation drops the row once
+    // its user-task completes — the child-scoped mirror of the top-level grid's
+    // pc:refresh re-poll, without disturbing the parent grid or its other detail
+    // rows (which a global pc:refresh would leave untouched anyway, since open
+    // detail rows are reused across the poll).
+    async function load() {
       /** @type {{ rows: Array<Record<string, any>> }} */
       const { rows } = await getJSON(dataUrl(cg.source || "app", cg.table,
         [{ field: cg.childField, eq: row[cg.parentField] }], cg.orderBy));
+      cbody.replaceChildren();
       if (!rows.length) {
         cbody.append(el("tr", {}, el("td", { colspan: cspan }, "None")));
+        return;
       }
       for (const cr of rows) {
         const cells = ccols.map((c, i) => gridCell(c, cr, croles[i]));
@@ -1755,26 +1805,33 @@ function renderDataGrid(node) {
         // Per-row expander cell (trailing, after any lazyField cell): a chevron
         // that reveals this row's detailPanel in a following full-width row. The
         // panel is built lazily on first open (and eagerly when the row starts
-        // expanded), matching the top-level grid.
+        // expanded), matching the top-level grid. The panel's escalation form (if
+        // any) is wired to load() so answering it re-fetches only this child grid.
+        // The chevron uses the shared chevronToggle()/setChevronOpen() so its glyph
+        // and aria-expanded stay in lock-step for assistive tech.
         /** @type {any} */
         let cdtr = null;
         if (chasExpand) {
           const crk = crowKeyOf(cr);
           const cskey = ckeyBase && crk != null ? ckeyBase + crk : null;
           const collapsed = cskey ? readCollapsed(cskey, cdefaultCollapsed) : cdefaultCollapsed;
-          const ctoggle = el("button", { class: "pc-btn pc-btn-sm pc-chevron" }, collapsed ? "▸" : "▾");
+          const ctoggle = chevronToggle("Toggle row details");
+          setChevronOpen(ctoggle, !collapsed);
           cells.push(el("td", { class: "pc-row-actions" }, ctoggle));
           cdtr = el("tr", { hidden: collapsed ? "" : null }, el("td", { colspan: cspan }));
           let built = false;
           const build = () => {
-            if (!built) { built = true; cdtr.firstChild.append(detailPanel(cr, cdetail)); }
+            // Return the reload promise (don't swallow it) so buildDetailForm can
+            // surface a failed re-fetch and re-enable its submit button instead of
+            // leaving the operator stuck on a false "Sent".
+            if (!built) { built = true; cdtr.firstChild.append(detailPanel(cr, cdetail, () => load())); }
           };
           if (!collapsed) build();
           ctoggle.addEventListener("click", /** @param {MouseEvent} ev */ (ev) => {
             ev.stopPropagation();
             const open = cdtr.hidden;
             cdtr.hidden = !open;
-            ctoggle.textContent = open ? "▾" : "▸";
+            setChevronOpen(ctoggle, open);
             if (open) build();
             if (cskey) writeCollapsed(cskey, !open);
           });
@@ -1788,8 +1845,11 @@ function renderDataGrid(node) {
         cbody.append(ctr);
         if (cdtr) cbody.append(cdtr);
       }
+    }
+    try {
+      await load();
     } catch (e) {
-      cbody.append(el("tr", {}, el("td", { colspan: cspan }, String(e.message || e))));
+      cbody.replaceChildren(el("tr", {}, el("td", { colspan: cspan }, String(e.message || e))));
     }
     return wrap;
   }
@@ -1800,8 +1860,12 @@ function renderDataGrid(node) {
    * and an optional escalation form.
    * @param {Record<string, any>} row
    * @param {any} [cfg] detail config; defaults to the top-level grid's `detail`
+   * @param {(() => void)} [onSuccess] invoked after the panel's escalation form
+   *   submits successfully. Defaults to a whole-page `pc:refresh` re-poll (the
+   *   top-level grid's behaviour); a child grid passes a child-scoped reload so
+   *   answering a nested escalation refreshes only that child grid, not the page.
    */
-  function detailPanel(row, cfg) {
+  function detailPanel(row, cfg, onSuccess) {
     const d = cfg || detail;
     const box = el("div", { class: "pc-detail" });
     if (d.linkField && row[d.linkField]) {
@@ -1825,7 +1889,7 @@ function renderDataGrid(node) {
       box.append(holder);
       childGrid(cg, row).then((w) => holder.replaceChildren(w));
     }
-    const form = detailForm(row, d.form);
+    const form = buildDetailForm(d.form, row, onSuccess || (() => { document.dispatchEvent(new CustomEvent("pc:refresh")); }));
     if (form) box.append(form);
     return box;
   }
@@ -1840,7 +1904,7 @@ function renderDataGrid(node) {
     if (hasExtra) {
       const actionCell = el("td", { class: "pc-row-actions" });
       if (detail) {
-        toggle = el("button", { class: "pc-btn pc-btn-sm pc-chevron" }, "▸");
+        toggle = chevronToggle("Toggle row details");
         actionCell.append(toggle);
       }
       for (const ra of rowActions) {
@@ -1872,12 +1936,12 @@ function renderDataGrid(node) {
         if (isOpen) { entry.built = true; dtr.firstChild.append(detailPanel(row)); }
       }
       const dtr = entry.dtr;
-      toggle.textContent = dtr.hidden ? "▸" : "▾";
+      setChevronOpen(toggle, !dtr.hidden);
       toggle.addEventListener("click", /** @param {MouseEvent} ev */ (ev) => {
         ev.stopPropagation();
         const open = dtr.hidden;
         dtr.hidden = !open;
-        toggle.textContent = open ? "▾" : "▸";
+        setChevronOpen(toggle, open);
         if (open) {
           if (key != null) expanded.add(key);
           if (!entry.built) { entry.built = true; dtr.firstChild.append(detailPanel(row)); }
@@ -2371,4 +2435,4 @@ function boot() {
 // renderer functions / RENDERERS registry can be imported directly.
 if (typeof document !== "undefined" && document.getElementById("page")) boot();
 
-export { RENDERERS, renderText, renderButton, renderProse, renderNav, navLink, wireNavBadge, applyNavBadge, teardown, fmtCellValue, gridCell };
+export { RENDERERS, renderText, renderButton, renderProse, renderNav, navLink, wireNavBadge, applyNavBadge, teardown, fmtCellValue, gridCell, buildDetailForm, chevronToggle, setChevronOpen };

package/src/runtime/browser/runtime.detailform.test.ts

@@ -0,0 +1,268 @@
+// Unit tests for buildDetailForm (#333) — the single shared implementation of the
+// `detail.form` answer/resume contract used by BOTH the top-level dataGrid detail
+// panel and a child-grid per-row expansion. Because #333 lets a child-grid row
+// host the same form, the contract must be exercised directly (render gating,
+// prompt echo, and the interpolated route-driven submit) so the top-level ↔
+// child-grid parity can't silently drift.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { buildDetailForm, chevronToggle, setChevronOpen } from "./runtime.browser.js";
+
+// ── Fake DOM with fire-able listeners ───────────────────────────────────────
+// Richer than the render-only fake in runtime.browser.test.ts: it records event
+// listeners (so a test can fire the submit click), exposes a settable textarea
+// `value`, a `firstChild`, and `replaceChildren` — the surface buildDetailForm's
+// interactive path touches. Every created node is collected on `created` so a
+// test can grab the textarea/button without a real querySelector.
+class FakeElement {
+  tagName: string;
+  attributes: Record<string, string> = {};
+  className = "";
+  children: Array<FakeElement | { text: string }> = [];
+  textContent = "";
+  dataset: Record<string, string> = {};
+  hidden = false;
+  disabled = false;
+  value = "";
+  style = { setProperty() {} };
+  listeners: Record<string, Array<(ev: unknown) => unknown>> = {};
+
+  constructor(tag: string) {
+    this.tagName = String(tag).toUpperCase();
+  }
+  setAttribute(k: string, v: unknown): void {
+    this.attributes[k] = String(v);
+    if (k === "class") this.className = String(v);
+  }
+  getAttribute(k: string): string | null {
+    return k in this.attributes ? this.attributes[k] : null;
+  }
+  addEventListener(type: string, fn: (ev: unknown) => unknown): void {
+    (this.listeners[type] ||= []).push(fn);
+  }
+  async fire(type: string): Promise<void> {
+    for (const fn of this.listeners[type] || []) await fn({ stopPropagation() {} });
+  }
+  append(...kids: Array<FakeElement | string>): void {
+    for (const kid of kids) {
+      if (typeof kid === "string") {
+        this.children.push({ text: kid });
+        this.textContent += kid;
+      } else {
+        this.children.push(kid);
+        this.textContent += kid.textContent || "";
+      }
+    }
+  }
+  replaceChildren(...kids: Array<FakeElement | string>): void {
+    this.children = [];
+    this.textContent = "";
+    this.append(...kids);
+  }
+  get firstChild(): FakeElement | { text: string } | null {
+    return this.children[0] ?? null;
+  }
+  querySelector(): null {
+    return null;
+  }
+}
+
+function installFakeDom(created: FakeElement[]): () => void {
+  const doc = {
+    createElement: (tag: string) => {
+      const n = new FakeElement(tag);
+      created.push(n);
+      return n;
+    },
+    getElementById: () => null,
+    dispatchEvent: () => true,
+  };
+  const prior = Reflect.getOwnPropertyDescriptor(globalThis, "document");
+  Reflect.set(globalThis, "document", doc);
+  return () => {
+    if (prior) Reflect.defineProperty(globalThis, "document", prior);
+    else Reflect.deleteProperty(globalThis, "document");
+  };
+}
+
+const ACTION = {
+  path: "/app/api/actions/complete-user-task",
+  body: { taskId: "{{row.task_id}}", variables: "{{form}}" },
+  successLabel: "Answered ✓",
+};
+const FORM = {
+  showWhenField: "answerable",
+  promptField: "question",
+  inputKey: "comment",
+  inputLabel: "Your answer",
+  submitLabel: "Answer & resume",
+  action: ACTION,
+};
+
+test("#333: buildDetailForm renders nothing when the row's showWhenField is falsy or missing", (t) => {
+  const created: FakeElement[] = [];
+  t.after(installFakeDom(created));
+  assert.equal(buildDetailForm(FORM, { answerable: false, question: "Why?" }, () => {}), null);
+  assert.equal(buildDetailForm(FORM, { question: "Why?" }, () => {}), null);
+  assert.equal(buildDetailForm(null, { answerable: true }, () => {}), null);
+});
+
+test("#333: buildDetailForm echoes the prompt and labels the field/submit from the form config", (t) => {
+  const created: FakeElement[] = [];
+  t.after(installFakeDom(created));
+  const box = buildDetailForm(FORM, { answerable: true, question: "Ship it?" }, () => {});
+  assert.ok(box, "an answerable row must render a form");
+  assert.match(box!.textContent, /Ship it\?/, "the promptField value is echoed");
+  const textarea = created.find((n) => n.tagName === "TEXTAREA");
+  const button = created.find((n) => n.tagName === "BUTTON");
+  assert.equal(textarea?.getAttribute("placeholder"), "Your answer");
+  assert.equal(button?.textContent, "Answer & resume");
+});
+
+test("#333: the answer form is screen-reader accessible — textarea has an aria-label and the status is a live region", (t) => {
+  const created: FakeElement[] = [];
+  t.after(installFakeDom(created));
+  const box = buildDetailForm(FORM, { answerable: true, question: "Ship it?" }, () => {});
+  assert.ok(box);
+  const textarea = created.find((n) => n.tagName === "TEXTAREA");
+  // The placeholder alone is not an accessible name; an explicit aria-label makes
+  // the field usable without a visible <label>.
+  assert.equal(textarea?.getAttribute("aria-label"), "Your answer");
+  const msg = created.find((n) => n.tagName === "P" && n.className.includes("pc-msg"));
+  assert.equal(msg?.getAttribute("role"), "status", "status message is a live region role");
+  assert.equal(msg?.getAttribute("aria-live"), "polite", "status transitions are announced politely");
+  // Explicit type="button" so the submit control can never trigger an unintended
+  // submit/navigation if the form is ever nested inside a real <form>.
+  const button = created.find((n) => n.tagName === "BUTTON");
+  assert.equal(button?.getAttribute("type"), "button", "submit control is an explicit type=button");
+});
+
+test("#333: the answer form's aria-label falls back to inputKey when inputLabel is absent", (t) => {
+  const created: FakeElement[] = [];
+  t.after(installFakeDom(created));
+  const noLabel = { ...FORM, inputLabel: undefined };
+  buildDetailForm(noLabel, { answerable: true }, () => {});
+  const textarea = created.find((n) => n.tagName === "TEXTAREA");
+  assert.equal(textarea?.getAttribute("aria-label"), "comment", "aria-label mirrors the placeholder fallback (inputKey)");
+});
+
+test("#333: chevronToggle is an accessible disclosure button and setChevronOpen keeps the glyph and aria-expanded in lock-step", (t) => {
+  const created: FakeElement[] = [];
+  t.after(installFakeDom(created));
+  const btn = chevronToggle("Toggle answer form");
+  assert.equal(btn.getAttribute("type"), "button", "explicit type so it never submits an enclosing form");
+  assert.equal(btn.getAttribute("aria-label"), "Toggle answer form", "has an accessible name");
+  assert.equal(btn.getAttribute("aria-expanded"), "false", "starts collapsed");
+  assert.equal(btn.textContent, "▸");
+
+  setChevronOpen(btn, true);
+  assert.equal(btn.textContent, "▾", "glyph flips to open");
+  assert.equal(btn.getAttribute("aria-expanded"), "true", "aria-expanded tracks the glyph");
+
+  setChevronOpen(btn, false);
+  assert.equal(btn.textContent, "▸");
+  assert.equal(btn.getAttribute("aria-expanded"), "false");
+});
+
+test("#333: chevronToggle falls back to a generic accessible name when none is given", (t) => {
+  const created: FakeElement[] = [];
+  t.after(installFakeDom(created));
+  const btn = chevronToggle();
+  assert.equal(btn.getAttribute("aria-label"), "Toggle details");
+});
+
+test("#333: submitting POSTs the interpolated {{row.*}}/{{form.*}} body, shows successLabel, and fires onSuccess", async (t) => {
+  const created: FakeElement[] = [];
+  t.after(installFakeDom(created));
+  /** @type {Array<{ url: unknown; init: any }>} */
+  const calls: Array<{ url: unknown; init: { method?: string; body?: string } }> = [];
+  const priorFetch = globalThis.fetch;
+  Reflect.set(globalThis, "fetch", async (url: unknown, init: { method?: string; body?: string }) => {
+    calls.push({ url, init });
+    return { ok: true, status: 200, json: async () => ({ ok: true }) };
+  });
+  t.after(() => Reflect.set(globalThis, "fetch", priorFetch));
+
+  let refreshed = 0;
+  const box = buildDetailForm(FORM, { answerable: true, question: "Ship it?", task_id: "T-42" }, () => {
+    refreshed++;
+  });
+  assert.ok(box);
+  const textarea = created.find((n) => n.tagName === "TEXTAREA");
+  const button = created.find((n) => n.tagName === "BUTTON");
+  assert.ok(textarea && button);
+  textarea!.value = "Looks good, proceed";
+  await button!.fire("click");
+
+  assert.equal(calls.length, 1, "exactly one route POST");
+  assert.equal(calls[0].init.method, "POST");
+  const sent = JSON.parse(String(calls[0].init.body));
+  assert.deepEqual(
+    sent,
+    { taskId: "T-42", variables: { comment: "Looks good, proceed" } },
+    "row token → task_id, whole-form splice → { comment }",
+  );
+  assert.equal(refreshed, 1, "onSuccess (child-grid reload / page re-poll) fires once");
+  const msg = created.find((n) => n.tagName === "P" && n.className.includes("ok"));
+  assert.equal(msg?.textContent, "Answered ✓", "the action successLabel is shown");
+});
+
+test("#333: a failed submit surfaces the error, re-enables submit, and does NOT fire onSuccess", async (t) => {
+  const created: FakeElement[] = [];
+  t.after(installFakeDom(created));
+  const priorFetch = globalThis.fetch;
+  Reflect.set(globalThis, "fetch", async () => ({ ok: false, status: 500, json: async () => ({ error: "boom" }) }));
+  t.after(() => Reflect.set(globalThis, "fetch", priorFetch));
+
+  let refreshed = 0;
+  const box = buildDetailForm(FORM, { answerable: true, question: "Ship it?", task_id: "T-9" }, () => {
+    refreshed++;
+  });
+  assert.ok(box);
+  const button = created.find((n) => n.tagName === "BUTTON");
+  await button!.fire("click");
+
+  assert.equal(refreshed, 0, "onSuccess must not fire on failure — the row stays");
+  assert.equal(button?.disabled, false, "submit is re-enabled so the operator can retry");
+  const msg = created.find((n) => n.tagName === "P" && n.className.includes("err"));
+  assert.equal(msg?.textContent, "boom", "the server error is surfaced");
+});
+
+test("#333: a failed onSuccess refresh is surfaced and re-enables submit — no silent failure / stuck button", async (t) => {
+  const created: FakeElement[] = [];
+  t.after(installFakeDom(created));
+  const priorFetch = globalThis.fetch;
+  Reflect.set(globalThis, "fetch", async () => ({ ok: true, status: 200, json: async () => ({ ok: true }) }));
+  t.after(() => Reflect.set(globalThis, "fetch", priorFetch));
+
+  // The submit itself succeeds, but the follow-up refresh (a child grid's
+  // re-fetch) rejects. buildDetailForm awaits onSuccess, so the reload failure
+  // must NOT be swallowed: the error is shown and the button re-enabled, instead
+  // of the operator being stuck on a permanently-disabled button under a false
+  // "Sent". Guards both suppressed advisories on runtime.browser.js:1581/1807.
+  const box = buildDetailForm(FORM, { answerable: true, question: "Ship it?", task_id: "T-7" }, async () => {
+    throw new Error("reload failed");
+  });
+  assert.ok(box);
+  const button = created.find((n) => n.tagName === "BUTTON");
+  await button!.fire("click");
+
+  assert.equal(button?.disabled, false, "submit re-enabled when the refresh fails so the operator isn't stuck");
+  const err = created.find((n) => n.tagName === "P" && n.className.includes("err"));
+  assert.equal(err?.textContent, "reload failed", "the refresh failure is surfaced, not swallowed");
+});
+
+test("#333: on a fully successful submit the button stays disabled — the refresh detaches/rebuilds the form", async (t) => {
+  const created: FakeElement[] = [];
+  t.after(installFakeDom(created));
+  const priorFetch = globalThis.fetch;
+  Reflect.set(globalThis, "fetch", async () => ({ ok: true, status: 200, json: async () => ({ ok: true }) }));
+  t.after(() => Reflect.set(globalThis, "fetch", priorFetch));
+
+  const box = buildDetailForm(FORM, { answerable: true, question: "Ship it?", task_id: "T-1" }, () => {});
+  assert.ok(box);
+  const button = created.find((n) => n.tagName === "BUTTON");
+  await button!.fire("click");
+
+  assert.equal(button?.disabled, true, "left disabled on success — the refresh replaces the form, so re-enabling is moot");
+});

package/src/runtime/core/host.ts

@@ -359,3 +359,39 @@ export interface EngineClient {
   /** Tear down all connections. */
   close(): Promise<void>;
 }
+
+/**
+ * The names of every method on {@link EngineClient} — the single *runtime* source of
+ * truth for the interface's surface. It is compile-time-pinned to `keyof EngineClient`
+ * in both directions (see the two assertions below): the `satisfies` rejects a stray or
+ * misspelled name, and the exhaustiveness assertion rejects an *omitted* one, so adding,
+ * renaming, or removing an `EngineClient` method that this list does not mirror fails
+ * `npm run typecheck`.
+ *
+ * A fake/adapter (e.g. `@nanobpm/urban-testkit`'s `WasmEngineClient`) can iterate this
+ * list to assert at *runtime* that it implements the full surface — catching the
+ * "the SDK grew a method the test double lags" seam-lag class (issue #341: `openUserTasks`,
+ * and `getForm` before it) that a purely structural `implements EngineClient` check no
+ * longer catches once the fake is published/compiled against an older `@nanobpm/urban`.
+ */
+export const ENGINE_CLIENT_METHODS = [
+  "deployResources",
+  "createInstance",
+  "cancelInstance",
+  "publishMessage",
+  "searchUserTasks",
+  "openUserTasks",
+  "getForm",
+  "completeUserTask",
+  "searchProcessInstances",
+  "registerWorker",
+  "close",
+] as const satisfies readonly (keyof EngineClient)[];
+
+// Compile-time exhaustiveness: every `EngineClient` method must appear in
+// `ENGINE_CLIENT_METHODS`. If one is omitted, `Exclude<...>` is a non-`never` union of
+// the missing keys, so this type resolves to `never` and the `true` assignment fails to
+// compile — the twin of the `satisfies` above, together pinning the list to
+// `keyof EngineClient` exactly (No Drift Surfaces).
+type MissingEngineClientMethods = Exclude<keyof EngineClient, (typeof ENGINE_CLIENT_METHODS)[number]>;
+const _engineClientMethodsAreExhaustive: [MissingEngineClientMethods] extends [never] ? true : never = true;