@nanobpm/urban 0.48.0 → 0.49.0

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

@@ -40,6 +40,7 @@ function fakeEngine(): { engine: EngineClient; calls: FakeEngineCalls } {
       calls.messages.push(input);
     },
     async searchUserTasks() { return []; },
+    async getForm() { return null; },
     async completeUserTask() {},
     async searchProcessInstances() { return []; },
     async registerWorker(jobType) { return { jobType, unsubscribe: async () => {} }; },
@@ -601,6 +602,48 @@ test("renderer makes collapsible nodes persist their state across sessions", asy
   assert.match(js, /container\.append\(header, body\);\s*return container;/);
 });
 
+test("renderer surfaces a live row-count badge on a dataGrid's collapsible header (showCount)", async () => {
+  // A dataGrid opting in via `showCount:true` renders a count pill that reflects the
+  // currently-fetched, filtered (active-tab) row set, updates on every refresh (the
+  // refreshMs poll and pc:refresh), and — because makeCollapsible re-homes it into the
+  // collapse header — stays visible while the section is collapsed. Omitting showCount
+  // is a no-op (backward-compatible).
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // Opt-in badge, created only when showCount is set; class-tagged for re-homing + CSS.
+  assert.match(js, /const countBadge = p\.showCount \? el\("span", \{ class: "pc-badge pc-count-badge"/);
+  // The badge's accessible name carries the count (kept in sync on refresh) rather than a
+  // bare aria-label that would override the number screen readers need to announce.
+  assert.match(js, /"aria-label": rowCountLabel\(0\)/);
+  assert.match(js, /function rowCountLabel\(n\) \{ return n \+ \(n === 1 \? " row" : " rows"\); \}/);
+  // The <h2> (title and/or badge) renders when either the title or the badge is present.
+  assert.match(js, /if \(p\.title \|\| countBadge\) \{/);
+  // The badge is appended to the <h2>; the " " spacer is inserted only when a title is
+  // present, so a badge-only header can't render (or store) a stray leading space.
+  assert.match(js, /if \(countBadge\) \{ if \(p\.title\) h2\.append\(" "\); h2\.append\(countBadge\); \}/);
+  // Every refresh rewrites the count from the fetched, filtered row set (poll + pc:refresh),
+  // keeping both the visible text and the accessible label in sync.
+  assert.match(js, /if \(countBadge\) \{ countBadge\.textContent = String\(rows\.length\); countBadge\.setAttribute\("aria-label", rowCountLabel\(rows\.length\)\); \}/);
+  // makeCollapsible lifts the badge out of the <h2> before deriving the title (so the
+  // count can't leak into the label) and re-homes it in the header so it stays visible
+  // while collapsed (only the body is hidden).
+  assert.match(js, /const countBadge = h2 && h2\.querySelector \? h2\.querySelector\("\.pc-count-badge"\) : null;/);
+  assert.match(js, /if \(countBadge\) countBadge\.remove\(\);/);
+  assert.match(js, /if \(countBadge\) header\.append\(countBadge\);/);
+  // The derived collapse-header title is trimmed so a badge-only <h2> (no title) can't
+  // leave a lone whitespace node as the label (or leak whitespace into the storage key).
+  assert.match(js, /const titleText = props\.title \|\| \(h2 \? h2\.textContent\.trim\(\) : ""\) \|\| "Section";/);
+});
+
+test("the shell styles the row-count pill as a neutral count distinct from status badges", async () => {
+  const res = await dispatch("GET", "/");
+  const html = res.body ?? "";
+  const rule = (html.match(/\.pc-count-badge\s*\{[^}]*\}/) ?? [""])[0];
+  assert.ok(rule, ".pc-count-badge rule must be present");
+  assert.match(rule, /background:var\(--nano-inset\)/);
+  assert.match(rule, /color:var\(--nano-text\)/);
+});
+
 test("GET /app/pages/<id> returns the page json, 404 for unknown", async () => {
   const ok = await dispatch("GET", "/app/pages/home");
   assert.equal(ok.status, 200);

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

@@ -564,6 +564,9 @@ table.pc-grid th { font-weight:600; color:var(--nano-text-muted); }
 .pc-badge-warn { background:var(--nano-warn); color:#3a2a00; }
 .pc-badge-ok { background:var(--nano-ok); }
 .pc-badge-info { background:var(--nano-info); }
+/* Live row-count pill (dataGrid showCount): a subtle, neutral count distinct from
+   the coloured status badges, legible in the collapse header while collapsed. */
+.pc-count-badge { color:var(--nano-text); background:var(--nano-inset); border:1px solid var(--nano-edge); font-weight:600; }
 :root[data-appearance="light"] .pc-badge-warn { color:#fff; }
 @media (prefers-color-scheme: light) { :root:not([data-appearance]) .pc-badge-warn { color:#fff; } }
 .pc-child { margin:.6rem 0; }
@@ -1266,10 +1269,25 @@ function renderActionForm(node) {
   return card;
 }
 
+// Accessible name for the row-count badge. The visible text is just a number, so an
+// aria-label would override it with a bare "row count" (the count — the important part —
+// is dropped). Instead name it "N row(s)" and keep it in sync with the text on refresh.
+// Single source of truth for both the initial render and every refresh below.
+function rowCountLabel(n) { return n + (n === 1 ? " row" : " rows"); }
+
 function renderDataGrid(node) {
   const p = node.props;
   const card = el("section", { class: "pc-card" });
-  if (p.title) card.append(el("h2", {}, p.title));
+  // Opt-in live row-count badge ("showCount"). Rendered inside the <h2> so a plain
+  // (non-collapsible) grid surfaces it beside the title; makeCollapsible re-homes it
+  // into the collapse header so it stays visible — and refresh-updated — while the
+  // section is collapsed. refresh() below rewrites its text on every poll/pc:refresh.
+  const countBadge = p.showCount ? el("span", { class: "pc-badge pc-count-badge", "aria-label": rowCountLabel(0) }, "0") : null;
+  if (p.title || countBadge) {
+    const h2 = el("h2", {}, p.title || "");
+    if (countBadge) { if (p.title) h2.append(" "); h2.append(countBadge); }
+    card.append(h2);
+  }
   const cols = p.columns || [];
   const tabs = p.tabs || [];
   const rowActions = p.rowActions || [];
@@ -1587,6 +1605,10 @@ function renderDataGrid(node) {
       const { rows } = paramScoped && PARAM === ""
         ? { rows: [] }
         : await getJSON(dataUrl(p.data.source, p.data.table, activeFilter, p.data.orderBy));
+      // Live row-count badge: reflect the currently-fetched, filtered (active-tab)
+      // set — exactly what the body renders — on every refresh (poll + pc:refresh),
+      // whether the section is expanded or collapsed.
+      if (countBadge) { countBadge.textContent = String(rows.length); countBadge.setAttribute("aria-label", rowCountLabel(rows.length)); }
       // Forget expansion / cached detail nodes for rows no longer present so the maps
       // don't grow without bound and a stale answer can't resurface on a key reuse.
       if (p.rowKey) {
@@ -1755,7 +1777,16 @@ function makeCollapsible(node, card) {
   const isCard = card.tagName === "SECTION";
   const container = isCard ? card : el("section", { class: "pc-card" });
   const h2 = isCard && card.querySelector ? card.querySelector("h2") : null;
-  const titleText = props.title || (h2 ? h2.textContent : "") || "Section";
+  // A dataGrid with "showCount" renders a live count badge inside its <h2>. Lift it
+  // out before deriving the title (so the count doesn't leak into the label text),
+  // then re-home it in the header alongside the title so it stays visible — and
+  // refresh-updated by the grid's own refresh() — while the section is collapsed.
+  const countBadge = h2 && h2.querySelector ? h2.querySelector(".pc-count-badge") : null;
+  if (countBadge) countBadge.remove();
+  // Trim the derived label: after the badge is lifted out, the leftover " " whitespace
+  // node from h2.append(" ", countBadge) would otherwise make a title-less section's
+  // header a lone space (and leak whitespace into the storage key). Fall back to "Section".
+  const titleText = props.title || (h2 ? h2.textContent.trim() : "") || "Section";
   if (h2) h2.remove();
   const body = el("div", { class: "pc-card-body" });
   if (isCard) {
@@ -1770,6 +1801,7 @@ function makeCollapsible(node, card) {
     chevron,
     el("span", { class: "pc-collapse-title" }, titleText),
   );
+  if (countBadge) header.append(countBadge);
   const storageKey = "pc:collapsed:" + CURRENT + ":" + (node.id || titleText);
   let collapsed = readCollapsed(storageKey, !!props.defaultCollapsed);
   function apply() {

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

@@ -29,6 +29,7 @@ function ctxWith(surfaces: Record<string, unknown>): Parameters<typeof mountSurf
     cancelInstance: async () => {},
     publishMessage: async () => {},
     searchUserTasks: async () => [],
+    getForm: async () => null,
     completeUserTask: async () => {},
     searchProcessInstances: async () => [],
     registerWorker: async (jobType) => ({ jobType, unsubscribe: async () => {} }),
@@ -43,6 +44,7 @@ const fakeEngine: EngineClient = {
   cancelInstance: async () => {},
   publishMessage: async () => {},
   searchUserTasks: async () => [],
+  getForm: async () => null,
   completeUserTask: async () => {},
   searchProcessInstances: async () => [],
   registerWorker: async (jobType) => ({ jobType, unsubscribe: async () => {} }),
@@ -76,13 +78,204 @@ test("chat agent is HTML-escaped in the mount page", async () => {
   assert.ok(body.includes("&lt;img src=x onerror=alert(1)&gt;"), "agent is escaped");
 });
 
-test("task-inbox path is injected as a quoted JS literal (no script breakout)", async () => {
+test("task-inbox client derives its API base from location (reverse-proxy safe, no path embedding)", async () => {
+  // The client must NOT embed the manifest-supplied route base as an absolute
+  // literal: a hardcoded "/tasks" escapes the Nano console's path-prefixed
+  // reverse proxy (/console/app-view/<name>/tasks) — every fetch to
+  // "/tasks/api/…" 404s upstream. Deriving the base from location.pathname keeps
+  // the API calls document-relative (correct at the origin root AND under the
+  // proxy) and, as a bonus, removes the manifest→<script> injection surface
+  // entirely: nothing manifest-supplied is embedded in the page at all.
   const evil = "/tasks'});alert(1);//x";
   const s = mountSurfaces(ctxWith({ taskInbox: { enabled: true, path: evil } }), fakeApp);
   const page = s.routes.find((r) => r.source === "surface:taskInbox" && r.method === "GET" && !r.path.endsWith("/api/tasks"))!;
   const body = await render(page);
-  // The path is embedded via JSON.stringify, so the raw breakout sequence must
-  // not appear unescaped inside the <script>.
-  assert.ok(!body.includes("'});alert(1);//'"), "no raw single-quoted breakout");
-  assert.ok(body.includes(JSON.stringify(evil)), "path embedded as a JSON string literal");
+  // The manifest path (evil or otherwise) is never emitted into the page.
+  assert.ok(!body.includes("alert(1)"), "manifest path is not embedded — nothing to inject");
+  assert.ok(!body.includes(JSON.stringify(evil)), "manifest path is not embedded as a JS literal");
+  // The base is derived from where the page was actually served, so it inherits
+  // any reverse-proxy path prefix instead of a root-absolute mount path.
+  assert.ok(body.includes("location.pathname"), "client derives its API base from location.pathname");
+  assert.ok(!/const\s+BASE\s*=\s*["'/]/.test(body), "client does not embed an absolute route base");
 });
+
+/** Build an app handle backed by a specific engine (the flow tests drive the routes). */
+function appWith(engine: EngineClient): Parameters<typeof mountSurfaces>[1] {
+  return {
+    manifest: { schemaVersion: 1, id: "app", name: "App" },
+    data: new DataLayer(new Map(), undefined, {}),
+    engine,
+    env: () => undefined,
+    log: createLogger(() => {}),
+  };
+}
+
+/** Invoke a route handler with an optional query string and POST body. */
+async function call(
+  route: { handler: (req: HttpRequest) => HttpResponse | Promise<HttpResponse> },
+  opts: { method?: string; query?: string; body?: string } = {},
+): Promise<HttpResponse> {
+  return route.handler({
+    method: opts.method ?? "GET",
+    path: "/",
+    query: new URLSearchParams(opts.query ?? ""),
+    headers: new Headers(),
+    text: async () => opts.body ?? "",
+  });
+}
+
+function inboxRoutes(engine: EngineClient) {
+  const s = mountSurfaces(ctxWith({ taskInbox: { enabled: true, path: "/tasks" } }), appWith(engine));
+  const at = (suffix: string, method = "GET") =>
+    s.routes.find(
+      (r) => r.source === "surface:taskInbox" && r.method === method && r.path.endsWith(suffix),
+    )!;
+  return {
+    page: s.routes.find((r) => r.source === "surface:taskInbox" && r.method === "GET" && r.path === "/tasks")!,
+    tasks: at("/api/tasks"),
+    form: at("/api/form"),
+    complete: at("/api/complete", "POST"),
+  };
+}
+
+test("inbox page renders the client-side form fetch + renderer", async () => {
+  const { page } = inboxRoutes(fakeEngine);
+  const rendered = String((await call(page)).body);
+  assert.ok(rendered.includes("/api/form"), "page fetches the linked form");
+  assert.ok(rendered.includes("function renderForm"), "page has a form renderer");
+  assert.ok(rendered.includes("function buildField"), "page builds fields from the schema");
+  assert.ok(rendered.includes("/api/complete"), "page posts completion");
+  // Drift guard: the client script is a stringified <script> body, so it is invisible to
+  // the type checker. UserTaskSummary carries `formKey`/`externalFormReference` but no
+  // `formId`, so the client must never branch on a task-supplied `formId` (that phantom
+  // field would silently be `undefined`). Lock the drift closed.
+  assert.ok(!rendered.includes("formId"), "client script must not reference formId — UserTaskSummary carries none");
+  // Prototype-pollution guard: submit builds `variables` from engine-supplied component
+  // keys (a schema could key a field '__proto__'/'constructor'). It must use a null-
+  // prototype bag so an untrusted key lands as an own property, never mutating a prototype.
+  assert.ok(rendered.includes("Object.create(null)"), "client builds the variables bag with a null prototype");
+  assert.ok(!/const\s+variables\s*=\s*\{\}/.test(rendered), "client must not collect untrusted keys into a plain {} object");
+});
+
+test("/api/tasks surfaces the resolved form linkage", async () => {
+  let seenFilter: unknown;
+  const engine: EngineClient = {
+    ...fakeEngine,
+    searchUserTasks: async (filter) => {
+      seenFilter = filter;
+      return [
+        { userTaskKey: "1", elementId: "approve", formKey: "form-123" },
+        { userTaskKey: "2", elementId: "review" },
+      ];
+    },
+  };
+  const { tasks } = inboxRoutes(engine);
+  const res = await call(tasks, { query: "processInstanceKey=pi-9" });
+  assert.deepEqual(seenFilter, { processInstanceKey: "pi-9" });
+  const parsed = JSON.parse(String(res.body));
+  assert.equal(parsed[0].formKey, "form-123");
+  assert.equal(parsed[1].formKey, undefined);
+});
+
+test("/api/form resolves a linked form's schema", async () => {
+  let seen: unknown;
+  const schema = { type: "default", schemaVersion: 18, components: [{ type: "textfield", key: "name", label: "Name" }] };
+  const engine: EngineClient = {
+    ...fakeEngine,
+    getForm: async (input) => {
+      seen = input;
+      return { formKey: "form-123", schema };
+    },
+  };
+  const { form } = inboxRoutes(engine);
+  const res = await call(form, { query: "formKey=form-123" });
+  assert.deepEqual(seen, { formKey: "form-123", formId: undefined });
+  assert.equal(res.status, 200);
+  assert.deepEqual(JSON.parse(String(res.body)).schema, schema);
+});
+
+test("/api/form requires an identifier", async () => {
+  const { form } = inboxRoutes(fakeEngine);
+  const res = await call(form);
+  assert.equal(res.status, 400);
+});
+
+test("/api/form passes an empty formKey through so getForm can fall back to formId", async () => {
+  // A `?formKey=&formId=…` request must not be rejected at the boundary (only *both*
+  // identifiers absent is a 400) nor stripped here — resolving an empty key to its formId
+  // fallback is getForm's single responsibility (see nanosdk getForm empty/whitespace test).
+  let seen: unknown;
+  const engine: EngineClient = {
+    ...fakeEngine,
+    getForm: async (input) => {
+      seen = input;
+      return { formKey: "form-9", schema: { type: "default", components: [] } };
+    },
+  };
+  const { form } = inboxRoutes(engine);
+  const res = await call(form, { query: "formKey=&formId=form-9" });
+  assert.equal(res.status, 200);
+  assert.deepEqual(seen, { formKey: "", formId: "form-9" });
+});
+
+test("/api/form 400s a whitespace-only identifier instead of a spurious 204", async () => {
+  // A `?formKey=   ` (or `formId=   `) request provides no usable identifier. The route's
+  // presence gate must follow getForm's canonical rule (whitespace = absent) and 400,
+  // rather than letting the blank key slip past a raw truthiness check to getForm (→ null
+  // → 204). Guards the route↔getForm presence drift on the taskInbox form path — Red when
+  // the gate checks raw `!formKey && !formId`, since "   " is truthy.
+  const { form } = inboxRoutes(fakeEngine);
+  assert.equal((await call(form, { query: "formKey=%20%20%20" })).status, 400);
+  assert.equal((await call(form, { query: "formId=%20%20" })).status, 400);
+});
+
+test("/api/form returns 204 for a task with no resolvable form (no-form fallback)", async () => {
+  const engine: EngineClient = { ...fakeEngine, getForm: async () => null };
+  const { form } = inboxRoutes(engine);
+  const res = await call(form, { query: "formKey=missing" });
+  assert.equal(res.status, 204);
+  // The body must be empty: a "null" payload (json(null, 204)) makes the client's
+  // fetch helper throw on parse and surface "Failed to load form" instead of the
+  // no-form fallback. Guard the wire shape here and the client short-circuit below.
+  assert.equal(res.body, "");
+});
+
+test("inbox client fetch helper short-circuits 204 so the no-form fallback renders", async () => {
+  const { page } = inboxRoutes(fakeEngine);
+  const rendered = String((await call(page)).body);
+  // The api() helper must not call r.json() on a 204 (empty body → throw). It has
+  // to resolve to null so openForm() falls through to renderNoForm(t).
+  assert.ok(rendered.includes("r.status===204"), "api() short-circuits a 204 response");
+  assert.ok(rendered.includes("function renderNoForm"), "page has a no-form renderer");
+});
+
+test("number field reader guards against a non-numeric (tampered) value", async () => {
+  // A number field submits `Number(raw)`; a non-numeric value (only reachable via tampering
+  // — the browser blanks invalid type=number input) yields NaN, which JSON.stringify
+  // serializes as null, silently changing the submission. The inline reader must guard it
+  // with Number.isFinite so a bad value is treated as absent rather than submitted as NaN.
+  const { page } = inboxRoutes(fakeEngine);
+  const rendered = String((await call(page)).body);
+  assert.ok(rendered.includes("Number.isFinite"), "number field guards NaN via Number.isFinite");
+});
+
+test("/api/complete completes the task with the submitted variables", async () => {
+  const calls: { key: string; variables?: Record<string, unknown> }[] = [];
+  const engine: EngineClient = {
+    ...fakeEngine,
+    completeUserTask: async (key, variables) => {
+      calls.push({ key, variables });
+    },
+  };
+  const { complete } = inboxRoutes(engine);
+  const res = await call(complete, { method: "POST", body: JSON.stringify({ userTaskKey: "7", variables: { name: "Ada", agree: true } }) });
+  assert.equal(res.status, 200);
+  assert.deepEqual(calls, [{ key: "7", variables: { name: "Ada", agree: true } }]);
+});
+
+test("/api/complete rejects a body with no userTaskKey", async () => {
+  const { complete } = inboxRoutes(fakeEngine);
+  const res = await call(complete, { method: "POST", body: JSON.stringify({ variables: {} }) });
+  assert.equal(res.status, 400);
+});
+

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

@@ -1,10 +1,15 @@
 // surfaces — the hosted human surfaces (ADR 0026). Implements the `taskInbox` surface: a
-// small JSON+HTML task list backed by the engine's user-task search, that renders the
-// linked `.form` and posts completion back. The `chat` surface is stubbed as a mount point
-// (LLM wiring is a separate concern). Surfaces contribute routes to the shared server.
+// small JSON+HTML task list backed by the engine's user-task search. Each open task links to
+// its deployed `.form` via the engine-resolved `formKey`; the list fetches that form's form-js
+// schema (`GET base/api/form`), renders its fields client-side with a minimal built-in
+// renderer, and posts the entered field values as the completion `variables` (`POST
+// base/api/complete`). A task with no linked form keeps the bare key-list + raw-complete
+// behavior. The `chat` surface is stubbed as a mount point (LLM wiring is a separate concern).
+// Surfaces contribute routes to the shared server.
 
 import type { AppApi, RuntimeContext } from "../context.ts";
-import { html, json, normalizeRoutePath, type Route } from "../router.ts";
+import { presentFormIdentifier } from "../host.ts";
+import { html, json, noContent, normalizeRoutePath, type Route } from "../router.ts";
 import { mountActions } from "./actions.ts";
 import { mountApi } from "./api.ts";
 import { mountPages } from "./pages.ts";
@@ -22,23 +27,169 @@ export interface SurfacesHandle {
   describe(): Record<string, unknown>;
 }
 
-function inboxPage(basePath: string): string {
+function inboxPage(): string {
+  // Reverse-proxy safe: the client derives its API base from location.pathname
+  // (where THIS page was actually served) rather than an embedded absolute
+  // route base. A hardcoded "/tasks" would escape the Nano console's
+  // path-prefixed proxy (/console/app-view/<name>/tasks) — the API fetches must
+  // inherit that prefix. Deriving from location also removes the manifest→
+  // <script> injection surface entirely: nothing manifest-supplied is embedded.
+  // All task/form values are rendered via textContent / setAttribute — never
+  // innerHTML — so nothing the engine returns can inject markup.
   return `<!doctype html><meta charset="utf-8"><title>Task inbox</title>
 <style>body{font:14px system-ui,sans-serif;margin:2rem;max-width:52rem}
-li{margin:.4rem 0}code{background:#f4f4f4;padding:.1rem .3rem;border-radius:3px}</style>
+ul{list-style:none;padding:0}li{margin:.4rem 0;display:flex;align-items:center;gap:.5rem}
+code{background:#f4f4f4;padding:.1rem .3rem;border-radius:3px}
+button{font:inherit;padding:.2rem .6rem;cursor:pointer}
+form label{display:block;margin:.6rem 0 .2rem;font-weight:600}
+form .field input,form .field textarea,form .field select{font:inherit;padding:.3rem;width:100%;box-sizing:border-box;max-width:24rem}
+form .field input[type=checkbox],form .field input[type=radio]{width:auto}
+#form{margin-top:1.5rem;border-top:1px solid #ddd;padding-top:1rem}
+.muted{color:#666}</style>
 <h1>Task inbox</h1><ul id="tasks"><li>loading…</li></ul>
+<div id="form"></div>
 <script>
-fetch(${JSON.stringify(basePath)}+'/api/tasks').then(r=>r.json()).then(ts=>{
-  const ul=document.getElementById('tasks');
-  ul.replaceChildren();
-  if(!ts.length){const li=document.createElement('li');li.textContent='No open tasks.';ul.appendChild(li);return;}
-  for(const t of ts){const li=document.createElement('li');
-    const code=document.createElement('code');
-    code.textContent=t.elementId||t.userTaskKey;
-    li.appendChild(code);
-    li.appendChild(document.createTextNode(' — key '+t.userTaskKey));
-    ul.appendChild(li);}
-});
+const BASE=location.pathname.replace(/\/+$/,'');
+const tasksEl=document.getElementById('tasks');
+const formEl=document.getElementById('form');
+
+function api(path,opts){return fetch(BASE+path,opts).then(r=>{if(!r.ok)return r.text().then(t=>{throw new Error(t||r.status)});if(r.status===204)return null;return r.json();});}
+
+function loadTasks(){
+  formEl.replaceChildren();
+  tasksEl.replaceChildren(el('li',{},'loading…'));
+  return api('/api/tasks').then(ts=>{
+    tasksEl.replaceChildren();
+    if(!ts.length){tasksEl.appendChild(el('li',{},'No open tasks.'));return;}
+    for(const t of ts){
+      const li=document.createElement('li');
+      const code=el('code',{},t.elementId||t.userTaskKey);
+      li.appendChild(code);
+      li.appendChild(document.createTextNode(' — key '+t.userTaskKey));
+      if(t.formKey){
+        li.appendChild(btn('Open',()=>openForm(t)));
+      }else{
+        li.appendChild(btn('Complete',()=>complete(t.userTaskKey,{})));
+      }
+      tasksEl.appendChild(li);
+    }
+  }).catch(err=>tasksEl.replaceChildren(el('li',{class:'muted'},'Failed to load tasks: '+err.message)));
+}
+
+function openForm(t){
+  formEl.replaceChildren(el('p',{class:'muted'},'loading form…'));
+  const q='formKey='+encodeURIComponent(t.formKey);
+  api('/api/form?'+q).then(f=>{
+    formEl.replaceChildren();
+    if(!f||!f.schema){renderNoForm(t);return;}
+    renderForm(t,f.schema);
+  }).catch(err=>{formEl.replaceChildren(el('p',{class:'muted'},'Failed to load form: '+err.message));});
+}
+
+function renderNoForm(t){
+  formEl.appendChild(el('p',{class:'muted'},'This task has no renderable form.'));
+  const bar=el('div',{});
+  bar.appendChild(btn('Complete',()=>complete(t.userTaskKey,{})));
+  bar.appendChild(btn('Cancel',loadTasks));
+  formEl.appendChild(bar);
+}
+
+function renderForm(t,schema){
+  const form=document.createElement('form');
+  form.appendChild(el('h2',{},'Task '+(t.elementId||t.userTaskKey)));
+  const components=Array.isArray(schema.components)?schema.components:[];
+  const inputs=[];
+  for(const c of components){
+    const built=buildField(c);
+    if(!built)continue;
+    form.appendChild(built.field);
+    if(built.read)inputs.push(built.read);
+  }
+  const submit=btn('Submit',null);submit.type='submit';
+  const bar=el('div',{});bar.appendChild(submit);bar.appendChild(btn('Cancel',loadTasks));
+  form.appendChild(bar);
+  form.addEventListener('submit',e=>{
+    e.preventDefault();
+    // Null-prototype: field keys come from the engine-supplied form schema. A component
+    // keyed '__proto__'/'constructor' must land as a plain own property (and round-trip
+    // through JSON), never mutate a prototype — no prototype pollution in the page runtime.
+    const variables=Object.create(null);
+    for(const read of inputs){const kv=read();if(kv)variables[kv.key]=kv.value;}
+    submit.disabled=true;
+    complete(t.userTaskKey,variables).catch(()=>{submit.disabled=false;});
+  });
+  formEl.appendChild(form);
+}
+
+function buildField(c){
+  const type=c&&c.type;
+  // Static (keyless) components: show text as a paragraph, ignore layout-only ones.
+  if(type==='text'){return {field:el('p',{class:'muted'},typeof c.text==='string'?c.text:'')};}
+  const key=c&&c.key;
+  if(!key)return null;
+  const wrap=el('div',{class:'field'});
+  const label=typeof c.label==='string'&&c.label?c.label:key;
+  if(type==='checkbox'){
+    const input=document.createElement('input');input.type='checkbox';
+    const lab=el('label',{});lab.appendChild(input);lab.appendChild(document.createTextNode(' '+label));
+    wrap.appendChild(lab);
+    return {field:wrap,read:()=>({key,value:input.checked})};
+  }
+  const labelEl=el('label',{},label);
+  wrap.appendChild(labelEl);
+  let input;
+  if(type==='textarea'){input=document.createElement('textarea');}
+  else if(type==='select'){
+    input=document.createElement('select');
+    input.appendChild(el('option',{value:''},'—'));
+    for(const o of (Array.isArray(c.values)?c.values:[])){
+      input.appendChild(el('option',{value:String(o.value)},String(o.label!=null?o.label:o.value)));
+    }
+  }
+  else if(type==='radio'){
+    const name='r'+Math.random().toString(36).slice(2);
+    const group=el('div',{});
+    for(const o of (Array.isArray(c.values)?c.values:[])){
+      const rlab=el('label',{});
+      const r=document.createElement('input');r.type='radio';r.name=name;r.value=String(o.value);
+      rlab.appendChild(r);rlab.appendChild(document.createTextNode(' '+String(o.label!=null?o.label:o.value)));
+      group.appendChild(rlab);
+    }
+    wrap.appendChild(group);
+    return {field:wrap,read:()=>{const sel=group.querySelector('input:checked');return sel?{key,value:sel.value}:null;}};
+  }
+  else{
+    input=document.createElement('input');
+    input.type=(type==='number')?'number':(type==='datetime'?'datetime-local':'text');
+  }
+  // Associate the label with the input (for/id) so screen readers announce it on focus.
+  const fieldId='f'+Math.random().toString(36).slice(2);
+  input.id=fieldId;labelEl.setAttribute('for',fieldId);
+  wrap.appendChild(input);
+  const isNumber=type==='number';
+  return {field:wrap,read:()=>{
+    const raw=input.value;
+    if(raw===''||raw==null)return null;
+    if(isNumber){
+      const n=Number(raw);
+      // A non-numeric value in a number field is only reachable via tampering (the browser
+      // blanks invalid type=number input). Treat it as absent rather than silently submitting
+      // NaN, which JSON.stringify serializes as null — quietly changing the submitted value.
+      return Number.isFinite(n)?{key,value:n}:null;
+    }
+    return {key,value:raw};
+  }};
+}
+
+function complete(userTaskKey,variables){
+  return api('/api/complete',{method:'POST',headers:{'content-type':'application/json'},
+    body:JSON.stringify({userTaskKey,variables})}).then(loadTasks);
+}
+
+function el(tag,attrs,text){const e=document.createElement(tag);for(const k in attrs)e.setAttribute(k,attrs[k]);if(text!=null)e.textContent=text;return e;}
+function btn(label,onClick){const b=document.createElement('button');b.type='button';b.textContent=label;if(onClick)b.addEventListener('click',onClick);return b;}
+
+loadTasks();
 </script>`;
 }
 
@@ -56,7 +207,7 @@ export function mountSurfaces(ctx: RuntimeContext, app: AppApi): SurfacesHandle
       method: "GET",
       path: base,
       source: "surface:taskInbox",
-      handler: () => html(inboxPage(base)),
+      handler: () => html(inboxPage()),
     });
     routes.push({
       method: "GET",
@@ -68,6 +219,28 @@ export function mountSurfaces(ctx: RuntimeContext, app: AppApi): SurfacesHandle
         return json(tasks);
       },
     });
+    routes.push({
+      method: "GET",
+      path: `${base}/api/form`,
+      source: "surface:taskInbox",
+      handler: async (req) => {
+        const formKey = req.query.get("formKey") ?? undefined;
+        const formId = req.query.get("formId") ?? undefined;
+        // Reject only when *neither* identifier is present. Presence follows getForm's
+        // canonical rule (`presentFormIdentifier`: empty/whitespace = absent) so a
+        // whitespace-only `?formKey=   ` request 400s here instead of slipping past a raw
+        // truthiness check and returning a spurious 204. The raw values are still passed
+        // through unchanged — resolving a blank key to its `formId` fallback is getForm's
+        // single responsibility.
+        if (!presentFormIdentifier(formKey) && !presentFormIdentifier(formId))
+          return json({ error: "formKey or formId required" }, 400);
+        const form = await app.engine.getForm({ formKey, formId });
+        // A task whose form can't be resolved returns 204: the client renders the
+        // no-form fallback rather than erroring.
+        if (!form) return noContent();
+        return json(form);
+      },
+    });
     routes.push({
       method: "POST",
       path: `${base}/api/complete`,

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

@@ -30,6 +30,7 @@ class MiniEngine implements EngineClient {
     this.calls.push({ kind: "message", target: input.name, correlationKey: input.correlationKey, variables: input.variables });
   }
   async searchUserTasks(): Promise<[]> { return []; }
+  async getForm(): Promise<null> { return null; }
   async completeUserTask(): Promise<void> {}
   async searchProcessInstances(): Promise<[]> { return []; }
   async registerWorker(jobType: string): Promise<{ jobType: string; unsubscribe(): Promise<void> }> {

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

@@ -15,6 +15,7 @@ class MiniEngine implements EngineClient {
   async cancelInstance(): Promise<void> {}
   async publishMessage(): Promise<void> {}
   async searchUserTasks(): Promise<[]> { return []; }
+  async getForm(): Promise<null> { return null; }
   async completeUserTask(): Promise<void> {}
   async searchProcessInstances(): Promise<[]> { return []; }
   async close(): Promise<void> {}

package/src/runtime/core/router.test.ts

@@ -1,6 +1,6 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { normalizeRoutePath } from "./router.ts";
+import { noContent, normalizeRoutePath } from "./router.ts";
 
 test("normalizeRoutePath ensures a leading slash and trims trailing slashes", () => {
   assert.equal(normalizeRoutePath("hooks/x", "/fallback"), "/hooks/x");
@@ -20,3 +20,12 @@ test("normalizeRoutePath falls back when value is missing or collapses to root",
   assert.equal(normalizeRoutePath("/", "/tasks"), "/tasks");
   assert.equal(normalizeRoutePath("", "/tasks"), "/tasks");
 });
+
+test("noContent emits a 204 with an empty body and no content-type", () => {
+  const res = noContent();
+  assert.equal(res.status, 204);
+  // 204 must carry no body: a "null" (or any) payload violates the semantics and
+  // makes a body-parsing client throw. Guard against a json(null, 204) regression.
+  assert.equal(res.body, "");
+  assert.equal(res.headers?.["content-type"], undefined);
+});