@nanobpm/urban 0.79.0 → 0.80.0

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

@@ -1859,6 +1859,101 @@ function buildDetailForm(f, row, onSuccess) {
   return box;
 }
 
+// Build a dataGrid detail's ENGINE-declared form (ADR 0026, #457). Where
+// buildDetailForm renders a page-authored `detail.form` (fields duplicated from a
+// deployed `.form`), this resolves the row's engine `formKey` and renders the
+// AUTHORITATIVE deployed form-js schema — so one grid can render the several
+// different typed forms carried by a heterogeneous task inbox, and no page-local
+// copy can drift from the deployed form. It reuses the ONE shared form-js renderer
+// (globalThis.NanoFormJs, embedded by the shell) and the shared `/app/actions/form`
+// resolution gate + `/app/actions/complete` completion — the same seams the
+// taskInbox surface uses, no fork.
+//
+// `cfg.formKeyField` (default "form_key") names the row column carrying the engine
+// formKey; `cfg.userTaskKeyField` (default "user_task_key") names the column
+// carrying the user-task key to complete. A row with no formKey degrades to a bare
+// "Complete" button (empty variables), matching taskInbox's no-form fallback.
+/** @param {any} cfg
+ *  @param {Record<string, any>} row
+ *  @param {() => void | Promise<void>} onSuccess
+ *  @returns {HTMLElement|null}
+ */
+function buildEngineForm(cfg, row, onSuccess) {
+  if (!cfg) return null;
+  const userTaskKey = row[cfg.userTaskKeyField || "user_task_key"];
+  // Without a user-task key there is nothing to complete — render nothing rather
+  // than a dead button.
+  if (userTaskKey == null || userTaskKey === "") return null;
+  const formKey = row[cfg.formKeyField || "form_key"];
+  const box = el("div", { class: "pc-subform" });
+  const msg = el("p", { class: "njf-msg", role: "status", "aria-live": "polite" });
+  /** @param {Record<string, any>} variables */
+  const complete = (variables) =>
+    getJSON("/app/actions/complete", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ userTaskKey, variables }),
+    }).then(() => onSuccess());
+  // No renderable form → the bare completion path (parity with taskInbox).
+  const renderBare = () => {
+    const bar = el("div", { class: "njf-actions" });
+    const b = el("button", { class: "pc-btn pc-btn-sm", type: "button" }, "Complete");
+    b.addEventListener("click", async () => {
+      b.disabled = true;
+      msg.className = "njf-msg";
+      msg.textContent = "Sending\u2026";
+      try {
+        await complete(Object.create(null));
+      } catch (e) {
+        b.disabled = false;
+        msg.className = "njf-msg err";
+        msg.textContent = String(e.message || e);
+      }
+    });
+    bar.append(b);
+    box.append(bar, msg);
+  };
+  if (formKey == null || formKey === "") {
+    renderBare();
+    return box;
+  }
+  box.append(el("p", { class: "njf-text" }, "loading form\u2026"));
+  getJSON("/app/actions/form?formKey=" + encodeURIComponent(String(formKey)))
+    .then((f) => {
+      box.replaceChildren();
+      const renderer = /** @type {any} */ (globalThis).NanoFormJs;
+      if (!f || !f.schema || !renderer) {
+        renderBare();
+        return;
+      }
+      box.append(
+        renderer.renderForm(f.schema, {
+          submitLabel: "Complete",
+          /** @param {Record<string, any>} variables */
+          onSubmit: (variables) => {
+            msg.className = "njf-msg";
+            msg.textContent = "Sending\u2026";
+            // Surface completion failures to the operator (parity with the bare-completion
+            // path). Rethrow so renderForm's catch still re-enables the submit button.
+            return complete(variables).catch((e) => {
+              msg.className = "njf-msg err";
+              msg.textContent = String(e.message || e);
+              throw e;
+            });
+          },
+        }),
+        msg,
+      );
+    })
+    .catch((e) => {
+      box.replaceChildren();
+      msg.className = "njf-msg err";
+      msg.textContent = "Failed to load form: " + String(e.message || e);
+      box.append(msg);
+    });
+  return box;
+}
+
 /** @param {any} node */
 function renderDataGrid(node) {
   const p = node.props;
@@ -2162,6 +2257,11 @@ function renderDataGrid(node) {
     }
     const form = buildDetailForm(d.form, row, onSuccess || (() => { document.dispatchEvent(new CustomEvent("pc:refresh")); }));
     if (form) box.append(form);
+    // An engine-declared form (ADR 0026/#457) sits ALONGSIDE the page-authored
+    // `detail.form`, not replacing it: a grid may render the deployed form-js schema
+    // for the row's user task instead of (or in addition to) a hand-authored copy.
+    const engineForm = buildEngineForm(d.engineForm, row, onSuccess || (() => { document.dispatchEvent(new CustomEvent("pc:refresh")); }));
+    if (engineForm) box.append(engineForm);
     return box;
   }
 
@@ -2849,4 +2949,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, renderAppView, navLink, sameOriginPath, wireNavBadge, applyNavBadge, teardown, fmtCellValue, gridCell, buildDetailForm, evalDetailCondition, normalizeDetailOptions, chevronToggle, setChevronOpen };
+export { RENDERERS, renderText, renderButton, renderProse, renderNav, renderAppView, navLink, sameOriginPath, wireNavBadge, applyNavBadge, teardown, fmtCellValue, gridCell, buildDetailForm, buildEngineForm, evalDetailCondition, normalizeDetailOptions, chevronToggle, setChevronOpen };

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

@@ -0,0 +1,158 @@
+// Unit tests for buildEngineForm (#457) — the dataGrid detail's ENGINE-declared
+// form path. Where buildDetailForm renders a page-authored `detail.form`, this
+// resolves the row's engine `formKey` via the shared `/app/actions/form` gate and
+// renders the AUTHORITATIVE deployed form-js schema with the shared renderer
+// (globalThis.NanoFormJs), completing the row's user task via
+// `/app/actions/complete`. A row with no formKey degrades to a bare completion,
+// matching the taskInbox no-form fallback.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { buildEngineForm } from "./runtime.browser.js";
+// Importing the shared renderer registers globalThis.NanoFormJs, which
+// buildEngineForm reads lazily when it renders a resolved schema.
+import "./formjs.browser.js";
+import { type FakeElement, installFakeDom } from "./fake-dom.test-utils.ts";
+
+interface FetchCall {
+  url: string;
+  method: string;
+  // Parsed request JSON body (or undefined), typed loosely so a test can assert on
+  // arbitrary shapes without ceremony — mirrors the runtime's JSDoc `any` payloads.
+  body?: any;
+}
+
+/** Install a fake `fetch` that resolves each request from a route→response map. */
+function installFakeFetch(
+  handler: (url: string, opts: { method?: string; body?: string }) => { status?: number; json?: unknown },
+  calls: FetchCall[],
+): () => void {
+  const prior = Reflect.getOwnPropertyDescriptor(globalThis, "fetch");
+  const fake = (input: string | URL, opts: { method?: string; body?: string } = {}) => {
+    const url = String(input);
+    calls.push({ url, method: opts.method ?? "GET", body: opts.body ? JSON.parse(opts.body) : undefined });
+    const res = handler(url, opts);
+    const status = res.status ?? 200;
+    return Promise.resolve({
+      ok: status >= 200 && status < 300,
+      status,
+      json: () =>
+        res.json === undefined ? Promise.reject(new Error("no body")) : Promise.resolve(res.json),
+      text: () => Promise.resolve(res.json === undefined ? "" : JSON.stringify(res.json)),
+    });
+  };
+  Reflect.set(globalThis, "fetch", fake);
+  return () => {
+    if (prior) Reflect.defineProperty(globalThis, "fetch", prior);
+    else Reflect.deleteProperty(globalThis, "fetch");
+  };
+}
+
+const CFG = { formKeyField: "form_key", userTaskKeyField: "user_task_key" };
+
+test("buildEngineForm renders nothing when the row has no user-task key", (t) => {
+  const created: FakeElement[] = [];
+  t.after(installFakeDom(created));
+  assert.equal(buildEngineForm(CFG, { form_key: "f1" }, () => {}), null);
+  assert.equal(buildEngineForm(null, { user_task_key: "u1" }, () => {}), null);
+});
+
+test("buildEngineForm resolves the row's formKey and completes with the entered variables", async (t) => {
+  const created: FakeElement[] = [];
+  const calls: FetchCall[] = [];
+  t.after(installFakeDom(created));
+  t.after(
+    installFakeFetch((url) => {
+      if (url.includes("/app/actions/form")) {
+        return { status: 200, json: { schema: { components: [{ type: "textfield", key: "note" }] } } };
+      }
+      return { status: 200, json: { ok: true } };
+    }, calls),
+  );
+  let refreshed = false;
+  const box = buildEngineForm(CFG, { form_key: "form-9", user_task_key: "ut-9" }, () => {
+    refreshed = true;
+  });
+  assert.ok(box);
+  // Let the form fetch + render settle.
+  await new Promise((r) => setTimeout(r, 0));
+  const formReq = calls.find((c) => c.url.includes("/app/actions/form"));
+  assert.ok(formReq, "the row's formKey is resolved via the shared gate");
+  assert.match(formReq!.url, /formKey=form-9/);
+  // The shared renderer built the field; fill it and submit.
+  const input = created.find((n) => n.tagName === "INPUT");
+  assert.ok(input, "the deployed form-js schema was rendered by the shared renderer");
+  input!.value = "done";
+  const form = created.find((n) => n.tagName === "FORM");
+  await form!.fire("submit");
+  await new Promise((r) => setTimeout(r, 0));
+  const completeReq = calls.find((c) => c.url.includes("/app/actions/complete"));
+  assert.ok(completeReq, "submitting completes the user task");
+  assert.equal(completeReq!.method, "POST");
+  assert.deepEqual(completeReq!.body, { userTaskKey: "ut-9", variables: { note: "done" } });
+  assert.equal(refreshed, true, "a successful completion invokes onSuccess (grid re-poll)");
+});
+
+test("buildEngineForm surfaces a completion failure in the rendered-form path", async (t) => {
+  const created: FakeElement[] = [];
+  const calls: FetchCall[] = [];
+  t.after(installFakeDom(created));
+  t.after(
+    installFakeFetch((url) => {
+      if (url.includes("/app/actions/form")) {
+        return { status: 200, json: { schema: { components: [{ type: "textfield", key: "note" }] } } };
+      }
+      return { status: 500 }; // completion fails
+    }, calls),
+  );
+  const box = buildEngineForm(CFG, { form_key: "form-e", user_task_key: "ut-e" }, () => {});
+  assert.ok(box);
+  await new Promise((r) => setTimeout(r, 0));
+  const form = created.find((n) => n.tagName === "FORM");
+  assert.ok(form, "the deployed schema was rendered");
+  await form!.fire("submit");
+  await new Promise((r) => setTimeout(r, 0));
+  const msg = created.find((n) => n.className.includes("njf-msg") && n.className.includes("err"));
+  assert.ok(msg, "a failed completion is surfaced to the operator (not silent)");
+  assert.notEqual(msg!.textContent, "", "the error message element has text");
+  const submit = created.find((n) => n.tagName === "BUTTON" && n.type === "submit");
+  assert.equal(submit!.disabled, false, "the submit button is re-enabled so the operator can retry");
+});
+
+test("buildEngineForm degrades to bare completion when the row has no formKey", async (t) => {
+  const created: FakeElement[] = [];
+  const calls: FetchCall[] = [];
+  t.after(installFakeDom(created));
+  t.after(installFakeFetch(() => ({ status: 200, json: { ok: true } }), calls));
+  const box = buildEngineForm(CFG, { user_task_key: "ut-2" }, () => {});
+  assert.ok(box);
+  // No form fetch — a bare "Complete" button is shown directly.
+  assert.equal(calls.length, 0, "no formKey ⇒ no form resolution request");
+  const button = created.find((n) => n.tagName === "BUTTON");
+  assert.ok(button);
+  assert.equal(button!.textContent, "Complete");
+  await button!.fire("click");
+  await new Promise((r) => setTimeout(r, 0));
+  const completeReq = calls.find((c) => c.url.includes("/app/actions/complete"));
+  assert.ok(completeReq, "the bare button completes the task");
+  assert.equal(completeReq!.body.userTaskKey, "ut-2");
+  assert.deepEqual(completeReq!.body.variables, {}, "bare completion sends empty variables");
+});
+
+test("buildEngineForm degrades to bare completion when the formKey resolves to no form (204)", async (t) => {
+  const created: FakeElement[] = [];
+  const calls: FetchCall[] = [];
+  t.after(installFakeDom(created));
+  t.after(
+    installFakeFetch((url) => {
+      if (url.includes("/app/actions/form")) return { status: 204 }; // no body
+      return { status: 200, json: { ok: true } };
+    }, calls),
+  );
+  const box = buildEngineForm(CFG, { form_key: "missing", user_task_key: "ut-3" }, () => {});
+  assert.ok(box);
+  await new Promise((r) => setTimeout(r, 0));
+  assert.ok(calls.some((c) => c.url.includes("/app/actions/form")), "an unresolved formKey still hits the gate");
+  const button = created.find((n) => n.tagName === "BUTTON" && n.textContent === "Complete");
+  assert.ok(button, "a 204 (no form) falls back to the bare completion button");
+});

package/src/runtime/core/modules/formjs.gen.ts

@@ -0,0 +1,6 @@
+// @generated by scripts/gen-runtime.mjs — DO NOT EDIT.
+// Source: src/runtime/browser/formjs.browser.js (the shared, type-checked/linted/tested
+// form-js renderer). Regenerate with `npm run gen:runtime`; CI enforces this file
+// is byte-identical to a fresh generation via `git diff --exit-code` (npm run check:runtime).
+
+export const FORMJS_JS: string = "// @ts-check\n// ── Shared, XSS-safe form-js schema renderer (ADR 0026, extended by #457) ─────\n// This is the ONE client implementation of \"render a deployed `.form`'s form-js\n// schema and collect its field values\", shared verbatim by BOTH:\n//   • the `taskInbox` surface (surfaces.ts `inboxPage`), and\n//   • the pages `dataGrid` engine-form detail (runtime.browser.js).\n// It used to live inline in surfaces.ts; factoring it here means the two surfaces\n// can never fork the renderer or drift on how a form-js component maps to an input\n// and its submitted value.\n//\n// Like the rest of the browser runtime it is authored/type-checked/linted/tested\n// as real source and served as a generated string artifact (formjs.gen.ts, emitted\n// by scripts/gen-runtime.mjs). It performs NO DOM access at load — every DOM touch\n// is inside a function — so it is import-safe under Node/Deno for unit testing.\n//\n// SECURITY: every value the engine returns is placed via textContent / setAttribute\n// (never innerHTML), so nothing in the form schema can inject markup. The submitted\n// `variables` bag is null-prototype so an engine-supplied component key of\n// `__proto__`/`constructor` lands as a plain own property and can never mutate a\n// prototype (prototype-pollution class).\n\n/** Create an element, setting attributes via setAttribute and text via textContent only.\n * @param {string} tag\n * @param {Record<string, string>} [attrs]\n * @param {string} [text]\n * @returns {any}\n */\nfunction fjEl(tag, attrs, text) {\n  const e = document.createElement(tag);\n  if (attrs) for (const k in attrs) e.setAttribute(k, attrs[k]);\n  if (text != null) e.textContent = text;\n  return e;\n}\n\n/** A plain type=\"button\" with an optional click handler.\n * @param {string} label\n * @param {(() => void) | null} [onClick]\n * @returns {any}\n */\nfunction fjBtn(label, onClick) {\n  const b = document.createElement(\"button\");\n  b.type = \"button\";\n  b.textContent = label;\n  if (onClick) b.addEventListener(\"click\", onClick);\n  return b;\n}\n\n/** Build one form-js component into its field element and (for keyed inputs) a reader\n * that returns the entered `{ key, value }` or null when blank. Static (keyless)\n * components render as inert text; layout-only components are skipped (null).\n * @param {any} c\n * @returns {{ field: any, read?: () => ({ key: string, value: any } | null) } | null}\n */\nfunction buildField(c) {\n  const type = c && c.type;\n  // Static (keyless) components: show text as a paragraph, ignore layout-only ones.\n  if (type === \"text\") {\n    return { field: fjEl(\"p\", { class: \"njf-text\" }, typeof c.text === \"string\" ? c.text : \"\") };\n  }\n  const key = c && c.key;\n  if (!key) return null;\n  const wrap = fjEl(\"div\", { class: \"njf-field\" });\n  const label = typeof c.label === \"string\" && c.label ? c.label : key;\n  if (type === \"checkbox\") {\n    const input = document.createElement(\"input\");\n    input.type = \"checkbox\";\n    const lab = fjEl(\"label\", {});\n    lab.appendChild(input);\n    lab.appendChild(document.createTextNode(\" \" + label));\n    wrap.appendChild(lab);\n    return { field: wrap, read: () => ({ key, value: input.checked }) };\n  }\n  const labelEl = fjEl(\"label\", {}, label);\n  wrap.appendChild(labelEl);\n  let input;\n  if (type === \"textarea\") {\n    input = document.createElement(\"textarea\");\n  } else if (type === \"select\") {\n    input = document.createElement(\"select\");\n    input.appendChild(fjEl(\"option\", { value: \"\" }, \"\\u2014\"));\n    for (const o of Array.isArray(c.values) ? c.values : []) {\n      input.appendChild(fjEl(\"option\", { value: String(o.value) }, String(o.label != null ? o.label : o.value)));\n    }\n  } else if (type === \"radio\") {\n    const name = \"r\" + Math.random().toString(36).slice(2);\n    const group = fjEl(\"div\", {});\n    for (const o of Array.isArray(c.values) ? c.values : []) {\n      const rlab = fjEl(\"label\", {});\n      const r = document.createElement(\"input\");\n      r.type = \"radio\";\n      r.name = name;\n      r.value = String(o.value);\n      rlab.appendChild(r);\n      rlab.appendChild(document.createTextNode(\" \" + String(o.label != null ? o.label : o.value)));\n      group.appendChild(rlab);\n    }\n    wrap.appendChild(group);\n    return {\n      field: wrap,\n      read: () => {\n        const sel = group.querySelector(\"input:checked\");\n        return sel ? { key, value: sel.value } : null;\n      },\n    };\n  } else {\n    input = document.createElement(\"input\");\n    input.type = type === \"number\" ? \"number\" : type === \"datetime\" ? \"datetime-local\" : \"text\";\n  }\n  // Associate the label with the input (for/id) so screen readers announce it on focus.\n  const fieldId = \"f\" + Math.random().toString(36).slice(2);\n  input.id = fieldId;\n  labelEl.setAttribute(\"for\", fieldId);\n  wrap.appendChild(input);\n  const isNumber = type === \"number\";\n  return {\n    field: wrap,\n    read: () => {\n      const raw = input.value;\n      if (raw === \"\" || raw == null) return null;\n      if (isNumber) {\n        const n = Number(raw);\n        // A non-numeric value in a number field is only reachable via tampering (the browser\n        // blanks invalid type=number input). Treat it as absent rather than silently submitting\n        // NaN, which JSON.stringify serializes as null — quietly changing the submitted value.\n        return Number.isFinite(n) ? { key, value: n } : null;\n      }\n      return { key, value: raw };\n    },\n  };\n}\n\n/**\n * Render a form-js schema into a `<form>` element with a submit + optional cancel.\n * On submit it assembles every keyed field's value into one null-prototype\n * `variables` bag and calls `opts.onSubmit(variables)`; a rejected submit re-enables\n * the button so the operator can retry. `opts.onCancel`, when supplied, wires a\n * cancel button.\n * @param {any} schema the parsed form-js document (`{ components: [...] }`)\n * @param {{ heading?: string, submitLabel?: string, cancelLabel?: string,\n *           onSubmit: (variables: Record<string, any>) => (void | Promise<void>),\n *           onCancel?: () => void }} opts\n * @returns {any} the built <form> element\n */\nfunction renderForm(schema, opts) {\n  const form = document.createElement(\"form\");\n  form.className = \"njf-form\";\n  if (opts.heading) form.appendChild(fjEl(\"h2\", { class: \"njf-heading\" }, opts.heading));\n  const components = schema && Array.isArray(schema.components) ? schema.components : [];\n  /** @type {Array<() => ({ key: string, value: any } | null)>} */\n  const inputs = [];\n  for (const c of components) {\n    const built = buildField(c);\n    if (!built) continue;\n    form.appendChild(built.field);\n    if (built.read) inputs.push(built.read);\n  }\n  const submit = fjBtn(opts.submitLabel || \"Submit\", null);\n  submit.type = \"submit\";\n  const bar = fjEl(\"div\", { class: \"njf-actions\" });\n  bar.appendChild(submit);\n  if (opts.onCancel) bar.appendChild(fjBtn(opts.cancelLabel || \"Cancel\", opts.onCancel));\n  form.appendChild(bar);\n  form.addEventListener(\"submit\", (e) => {\n    e.preventDefault();\n    // Null-prototype: field keys come from the engine-supplied form schema. A component\n    // keyed '__proto__'/'constructor' must land as a plain own property (and round-trip\n    // through JSON), never mutate a prototype — no prototype pollution in the page runtime.\n    const variables = Object.create(null);\n    for (const read of inputs) {\n      const kv = read();\n      if (kv) variables[kv.key] = kv.value;\n    }\n    submit.disabled = true;\n    Promise.resolve()\n      .then(() => opts.onSubmit(variables))\n      .catch(() => {\n        submit.disabled = false;\n      });\n  });\n  return form;\n}\n\n\n// Expose the renderer as a browser global so both self-contained page bundles can\n// reach the ONE implementation without importing it: the taskInbox page embeds this\n// module inline and the pages shell does the same before loading the ES-module\n// runtime, which reads `globalThis.NanoFormJs` lazily when it renders an engine form.\n// Guarded so importing under Node/Deno for tests is a harmless no-op-ish assignment.\nif (typeof globalThis !== \"undefined\") {\n  /** @type {any} */ (globalThis).NanoFormJs = { buildField, renderForm };\n}\n";

package/src/runtime/core/modules/forms.test.ts

@@ -0,0 +1,122 @@
+// The shared engine-form server seams (ADR 0026, #457): the /api/form resolution
+// gate and the user-task completion, factored out of surfaces.ts so the taskInbox
+// surface and the pages grid detail share ONE implementation. These tests pin the
+// gate's contract directly (both callers depend on it identically).
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import type { EngineClient, FormSchema } from "../host.ts";
+import { completeUserTaskResponse, resolveFormResponse } from "./forms.ts";
+
+function formEngine(getForm: EngineClient["getForm"]): Pick<EngineClient, "getForm"> {
+  return { getForm };
+}
+
+test("resolveFormResponse 400s when neither identifier is present (empty/whitespace = absent)", async () => {
+  const engine = formEngine(async () => {
+    throw new Error("getForm must not be called when no identifier is present");
+  });
+  for (const [formKey, formId] of [
+    [undefined, undefined],
+    ["", ""],
+    ["   ", undefined],
+    [undefined, "\t"],
+  ] as const) {
+    const res = await resolveFormResponse(engine, formKey, formId);
+    assert.equal(res.status, 400);
+  }
+});
+
+test("resolveFormResponse passes raw identifiers through to getForm and returns its schema", async () => {
+  const seen: { formKey?: string; formId?: string }[] = [];
+  const schema: FormSchema = { formKey: "form-1", schema: { components: [] } };
+  const engine = formEngine(async (input) => {
+    seen.push(input);
+    return schema;
+  });
+  const res = await resolveFormResponse(engine, "form-1", undefined);
+  assert.equal(res.status, 200);
+  assert.ok(res.body);
+  assert.deepEqual(JSON.parse(res.body), schema);
+  // A blank formKey is passed through unchanged so getForm can fall back to formId
+  // (that fallback is getForm's single responsibility, not the gate's).
+  await resolveFormResponse(engine, "", "the-form-id");
+  assert.deepEqual(seen, [
+    { formKey: "form-1", formId: undefined },
+    { formKey: "", formId: "the-form-id" },
+  ]);
+});
+
+test("resolveFormResponse 204s (no body) when getForm can't resolve a form", async () => {
+  const res = await resolveFormResponse(formEngine(async () => null), "missing", undefined);
+  assert.equal(res.status, 204);
+  assert.equal(res.body, "");
+});
+
+test("completeUserTaskResponse completes the task with the submitted variables", async () => {
+  const calls: { key: string; variables?: Record<string, unknown> }[] = [];
+  const engine: Pick<EngineClient, "completeUserTask"> = {
+    async completeUserTask(key, variables) {
+      calls.push({ key, variables });
+    },
+  };
+  const res = await completeUserTaskResponse(engine, JSON.stringify({ userTaskKey: "ut-7", variables: { a: 1 } }));
+  assert.equal(res.status, 200);
+  assert.ok(res.body);
+  assert.deepEqual(JSON.parse(res.body), { ok: true });
+  assert.deepEqual(calls, [{ key: "ut-7", variables: { a: 1 } }]);
+});
+
+test("completeUserTaskResponse 400s on a missing userTaskKey or malformed body — no completion attempted", async () => {
+  let called = false;
+  const engine: Pick<EngineClient, "completeUserTask"> = {
+    async completeUserTask() {
+      called = true;
+    },
+  };
+  assert.equal((await completeUserTaskResponse(engine, JSON.stringify({ variables: {} }))).status, 400);
+  assert.equal((await completeUserTaskResponse(engine, "{ not json")).status, 400);
+  assert.equal(called, false);
+});
+
+test("completeUserTaskResponse 400s on a non-object JSON body — no crash, no completion attempted", async () => {
+  let called = false;
+  const engine: Pick<EngineClient, "completeUserTask"> = {
+    async completeUserTask() {
+      called = true;
+    },
+  };
+  // `JSON.parse("null")` returns `null`, and a bare scalar/array parses to a
+  // non-record — reading `.userTaskKey` off those must 400, never throw a 500.
+  for (const bodyText of ["null", "123", '"a string"', "true", "[]"]) {
+    const res = await completeUserTaskResponse(engine, bodyText);
+    assert.equal(res.status, 400, `body=${bodyText} should 400`);
+  }
+  assert.equal(called, false);
+});
+
+test("completeUserTaskResponse 400s on non-object variables — no completion attempted", async () => {
+  let called = false;
+  const engine: Pick<EngineClient, "completeUserTask"> = {
+    async completeUserTask() {
+      called = true;
+    },
+  };
+  for (const variables of [1, "x", true, [], null]) {
+    const res = await completeUserTaskResponse(engine, JSON.stringify({ userTaskKey: "ut-1", variables }));
+    assert.equal(res.status, 400, `variables=${JSON.stringify(variables)} should 400`);
+  }
+  assert.equal(called, false);
+});
+
+test("completeUserTaskResponse allows an omitted variables (undefined)", async () => {
+  const calls: { key: string; variables?: Record<string, unknown> }[] = [];
+  const engine: Pick<EngineClient, "completeUserTask"> = {
+    async completeUserTask(key, variables) {
+      calls.push({ key, variables });
+    },
+  };
+  const res = await completeUserTaskResponse(engine, JSON.stringify({ userTaskKey: "ut-2" }));
+  assert.equal(res.status, 200);
+  assert.deepEqual(calls, [{ key: "ut-2", variables: undefined }]);
+});

package/src/runtime/core/modules/forms.ts

@@ -0,0 +1,67 @@
+// Shared engine-form plumbing (ADR 0026, extended to the pages surface).
+//
+// The `taskInbox` surface pioneered rendering a user task's *engine-declared*
+// form: resolve the task's `formKey`/`formId` via `EngineClient.getForm(...)`,
+// render the returned form-js schema client-side, and post the entered values
+// as the completion `variables`. The pages `dataGrid` engine-form detail (#457)
+// needs the SAME two server seams — the `/api/form` resolution gate and the
+// task-completion endpoint — so they live here ONCE and are wired by both
+// `surfaces.ts` (taskInbox) and `pages.ts` (the grid detail). No fork: a single
+// resolution gate, and the `host.ts` `presentFormIdentifier` presence rule stays
+// the single source of truth for "was an identifier provided".
+
+import type { EngineClient, HttpResponse } from "../host.ts";
+import { presentFormIdentifier } from "../host.ts";
+import { isRecord } from "../guards.ts";
+import { json, noContent } from "../router.ts";
+
+/**
+ * The shared `/api/form` resolution gate. Rejects only when *neither* identifier
+ * is present — presence follows getForm's canonical rule (`presentFormIdentifier`:
+ * empty/whitespace = absent) so a whitespace-only `?formKey=   ` 400s here instead
+ * of slipping past a raw truthiness check and returning a spurious 204. The raw
+ * values are passed through unchanged — resolving a blank key to its `formId`
+ * fallback is getForm's single responsibility. A form that can't be resolved
+ * returns 204 so the client renders the no-form fallback rather than erroring.
+ */
+export async function resolveFormResponse(
+  engine: Pick<EngineClient, "getForm">,
+  formKey: string | undefined,
+  formId: string | undefined,
+): Promise<HttpResponse> {
+  if (!presentFormIdentifier(formKey) && !presentFormIdentifier(formId))
+    return json({ error: "formKey or formId required" }, 400);
+  const form = await engine.getForm({ formKey, formId });
+  if (!form) return noContent();
+  return json(form);
+}
+
+/**
+ * The shared user-task completion endpoint. Parses `{ userTaskKey, variables }`
+ * from the request body and completes the task via `EngineClient.completeUserTask`.
+ * A body that isn't a JSON object (`null`, a scalar, an array) 400s instead of
+ * throwing a 500; a missing/blank `userTaskKey` 400s; a malformed body 400s; a
+ * present but non-object `variables` (number, string, array, `null`) 400s so the
+ * completion contract stays well-defined at this shared seam. Used by both the
+ * taskInbox surface and the pages grid's engine-form detail so the completion
+ * contract can't drift between them.
+ */
+export async function completeUserTaskResponse(
+  engine: Pick<EngineClient, "completeUserTask">,
+  bodyText: string,
+): Promise<HttpResponse> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(bodyText || "{}");
+  } catch {
+    return json({ error: "invalid JSON body" }, 400);
+  }
+  if (!isRecord(parsed)) return json({ error: "invalid JSON body" }, 400);
+  const { userTaskKey, variables } = parsed;
+  if (typeof userTaskKey !== "string" || !userTaskKey)
+    return json({ error: "userTaskKey required" }, 400);
+  if (variables !== undefined && !isRecord(variables))
+    return json({ error: "variables must be a JSON object" }, 400);
+  await engine.completeUserTask(userTaskKey, variables);
+  return json({ ok: true });
+}

package/src/runtime/core/modules/gen-artifacts.test.ts

@@ -0,0 +1,41 @@
+// Drift gate for the generated browser-runtime artifacts, enforced INSIDE the test
+// suite (which CI already runs) rather than in a workflow step. The browser runtime
+// and the shared form-js renderer are authored as real, type-checked/linted/tested
+// source (runtime.browser.js, formjs.browser.js) and emitted to committed string
+// artifacts (runtime.gen.ts, formjs.gen.ts) by scripts/gen-runtime.mjs. If either
+// checked-in artifact drifts from a fresh generation, the served bundle no longer
+// matches its source and a stale renderer could ship — so we regenerate-and-compare
+// here and fail on any drift, the same guarantee `npm run check:runtime` gives.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+// Resolve the generator relative to THIS file (cwd varies: `npm test` runs from the
+// package root, but a runner may invoke us from elsewhere).
+const GEN_SCRIPT = fileURLToPath(new URL("../../../../scripts/gen-runtime.mjs", import.meta.url));
+
+function hasStderr(e: unknown): e is { stderr?: unknown; stdout?: unknown } {
+  return typeof e === "object" && e !== null && ("stderr" in e || "stdout" in e);
+}
+
+test("the committed runtime + formjs artifacts are byte-identical to a fresh generation (no drift)", () => {
+  // `--check` regenerates both artifacts in-memory and diffs them against the
+  // committed files, exiting non-zero (with a diagnostic) on any drift. Spawn the real
+  // `node` binary explicitly: under `deno test`, `process.execPath` is the `deno`
+  // binary, which cannot run this Node script — mirrors the pages.test.ts node --check
+  // guard. Regenerate + commit locally with `npm run gen:runtime -w packages/urban`.
+  let ok = true;
+  let diagnostic = "";
+  try {
+    execFileSync("node", [GEN_SCRIPT, "--check"], { stdio: "pipe" });
+  } catch (err) {
+    ok = false;
+    diagnostic = hasStderr(err) ? `${String(err.stdout ?? "")}${String(err.stderr ?? "")}` : String(err);
+  }
+  assert.ok(
+    ok,
+    `a committed generated artifact is stale — run \`npm run gen:runtime -w packages/urban\` and commit the result.\n${diagnostic}`,
+  );
+});

package/src/runtime/core/modules/pages.test.ts

@@ -1950,3 +1950,102 @@ test("the nested serve declines (does not shadow) a same-path trigger route regi
   assert.equal(hook.status, 202);
   assert.deepEqual(JSON.parse(hook.body ?? "{}"), { queued: true });
 });
+
+// ── engine-declared forms in a dataGrid detail (ADR 0026 / #457) ────────────
+// The pages surface exposes the SAME two seams the taskInbox surface uses:
+//   GET  /app/actions/form?formKey=…   → resolve a deployed .form's form-js schema
+//   POST /app/actions/complete         → complete the row's user task
+// so one grid can render the several different typed forms a heterogeneous task
+// inbox carries, instead of duplicating each into a page-local `detail.form`.
+
+/** A recording engine for the form-resolution + completion seams. `resolveForm`
+ * supplies the getForm result while the wrapper still records every call, so a test
+ * can assert BOTH the resolved schema and the exact `{formKey, formId}` the shared
+ * presence gate passed through. */
+function formEngine(
+  resolveForm: (input: { formKey?: string; formId?: string }) => Awaited<ReturnType<EngineClient["getForm"]>> = () => null,
+): {
+  engine: EngineClient;
+  formCalls: { formKey?: string; formId?: string }[];
+  completeCalls: { userTaskKey: string; variables?: Record<string, unknown> }[];
+} {
+  const formCalls: { formKey?: string; formId?: string }[] = [];
+  const completeCalls: { userTaskKey: string; variables?: Record<string, unknown> }[] = [];
+  const { engine } = fakeEngine();
+  const withSeams: EngineClient = {
+    ...engine,
+    async getForm(input: { formKey?: string; formId?: string }) {
+      formCalls.push(input);
+      return resolveForm(input);
+    },
+    async completeUserTask(userTaskKey: string, variables?: Record<string, unknown>) {
+      completeCalls.push({ userTaskKey, variables });
+    },
+  };
+  return { engine: withSeams, formCalls, completeCalls };
+}
+
+function formRouter(engine: EngineClient) {
+  const routes = createPagesRoutes({ pagesDir: "pages", homePage: "home", sourceName: "app" }, {
+    db: fakeDb(),
+    engine,
+    readPage: async () => JSON.stringify({ title: "Home", nodes: [] }),
+    listPages: async () => ["home"],
+  });
+  return makeRouter(routes);
+}
+
+test("GET /app/actions/form resolves a row's engine formKey to its form-js schema", async () => {
+  const schema = { type: "default", components: [{ type: "textfield", key: "note" }] };
+  const { engine, formCalls } = formEngine((input) => ({ formKey: input.formKey, schema }));
+  const res = await formRouter(engine)(req("GET", "/app/actions/form", { query: "formKey=form-123" }));
+  assert.equal(res.status, 200);
+  assert.deepEqual(JSON.parse(res.body ?? "{}").schema, schema);
+  assert.deepEqual(formCalls, [{ formKey: "form-123", formId: undefined }]);
+});
+
+test("GET /app/actions/form 400s when neither formKey nor formId is present (shared presence gate)", async () => {
+  const { engine } = formEngine();
+  const res = await formRouter(engine)(req("GET", "/app/actions/form"));
+  assert.equal(res.status, 400);
+  const blank = await formRouter(engine)(req("GET", "/app/actions/form", { query: "formKey=%20%20" }));
+  assert.equal(blank.status, 400, "a whitespace-only formKey is absent per the host.ts presence rule");
+});
+
+test("GET /app/actions/form 204s when the form can't be resolved (client falls back to bare completion)", async () => {
+  // getForm returns null (default) → 204, matching the taskInbox no-form fallback.
+  const { engine } = formEngine();
+  const res = await formRouter(engine)(req("GET", "/app/actions/form", { query: "formKey=missing" }));
+  assert.equal(res.status, 204);
+  assert.equal(res.body ?? "", "");
+});
+
+test("POST /app/actions/complete completes the row's user task with the submitted variables", async () => {
+  const { engine, completeCalls } = formEngine();
+  const res = await formRouter(engine)(
+    req("POST", "/app/actions/complete", { body: { userTaskKey: "ut-9", variables: { note: "ok" } } }),
+  );
+  assert.equal(res.status, 200);
+  assert.deepEqual(JSON.parse(res.body ?? "{}"), { ok: true });
+  assert.deepEqual(completeCalls, [{ userTaskKey: "ut-9", variables: { note: "ok" } }]);
+});
+
+test("POST /app/actions/complete supports the no-form bare completion (empty variables)", async () => {
+  const { engine, completeCalls } = formEngine();
+  const res = await formRouter(engine)(req("POST", "/app/actions/complete", { body: { userTaskKey: "ut-1" } }));
+  assert.equal(res.status, 200);
+  assert.deepEqual(completeCalls, [{ userTaskKey: "ut-1", variables: undefined }]);
+});
+
+test("POST /app/actions/complete 400s without a userTaskKey", async () => {
+  const { engine, completeCalls } = formEngine();
+  const res = await formRouter(engine)(req("POST", "/app/actions/complete", { body: { variables: {} } }));
+  assert.equal(res.status, 400);
+  assert.equal(completeCalls.length, 0, "no completion is attempted for a keyless body");
+});
+
+test("the pages shell embeds the shared form-js renderer (NanoFormJs) for engine forms", async () => {
+  const res = await dispatch("GET", "/");
+  assert.match(res.body ?? "", /NanoFormJs/, "the shell exposes the shared renderer as a global");
+  assert.match(res.body ?? "", /function renderForm/, "the shared renderer is embedded, not forked");
+});