@nanobpm/urban 0.79.0 → 0.80.0

package/dist/runtime/core/modules/surfaces.js

@@ -6,8 +6,9 @@
 // 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 { presentFormIdentifier } from "../host.js";
-import { html, json, noContent, normalizeRoutePath } from "../router.js";
+import { html, json, normalizeRoutePath } from "../router.js";
+import { FORMJS_JS } from "./formjs.gen.js";
+import { completeUserTaskResponse, resolveFormResponse } from "./forms.js";
 import { mountActions } from "./actions.js";
 import { mountAgent } from "./agent.js";
 import { mountApi } from "./api.js";
@@ -30,13 +31,15 @@ function inboxPage() {
 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}
+.njf-field label{display:block;margin:.6rem 0 .2rem;font-weight:600}
+.njf-field input,.njf-field textarea,.njf-field select{font:inherit;padding:.3rem;width:100%;box-sizing:border-box;max-width:24rem}
+.njf-field input[type=checkbox],.njf-field input[type=radio]{width:auto}
+.njf-actions{margin-top:.6rem}
 #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>${FORMJS_JS}</script>
 <script>
 const BASE=location.pathname.replace(/[/]+$/,'');
 const tasksEl=document.getElementById('tasks');
@@ -71,7 +74,14 @@ function openForm(t){
   api('/api/form?'+q).then(f=>{
     formEl.replaceChildren();
     if(!f||!f.schema){renderNoForm(t);return;}
-    renderForm(t,f.schema);
+    // Reuse the ONE shared form-js renderer (NanoFormJs) — no fork with the pages surface.
+    formEl.appendChild(NanoFormJs.renderForm(f.schema,{
+      heading:'Task '+(t.elementId||t.userTaskKey),
+      submitLabel:'Submit',
+      cancelLabel:'Cancel',
+      onSubmit:(variables)=>complete(t.userTaskKey,variables),
+      onCancel:loadTasks,
+    }));
   }).catch(err=>{formEl.replaceChildren(el('p',{class:'muted'},'Failed to load form: '+err.message));});
 }
 
@@ -83,93 +93,6 @@ function renderNoForm(t){
   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);
@@ -222,42 +145,13 @@ export function mountSurfaces(ctx, app) {
             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);
-            },
+            handler: async (req) => resolveFormResponse(app.engine, req.query.get("formKey") ?? undefined, req.query.get("formId") ?? undefined),
         });
         routes.push({
             method: "POST",
             path: `${base}/api/complete`,
             source: "surface:taskInbox",
-            handler: async (req) => {
-                let body;
-                try {
-                    body = JSON.parse((await req.text()) || "{}");
-                }
-                catch {
-                    return json({ error: "invalid JSON body" }, 400);
-                }
-                if (!body.userTaskKey)
-                    return json({ error: "userTaskKey required" }, 400);
-                await app.engine.completeUserTask(body.userTaskKey, body.variables);
-                return json({ ok: true });
-            },
+            handler: async (req) => completeUserTaskResponse(app.engine, await req.text()),
         });
     }
     const chat = surfaces.chat;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.79.0",
+	"version": "0.80.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/fake-dom.test-utils.ts

@@ -0,0 +1,114 @@
+// A small fake DOM for unit-testing the browser runtime's element-building code
+// (the shared form-js renderer and the dataGrid engine-form path) under Node,
+// without a real browser. Records every created node so a test can grab an input
+// or button and fire its listeners. Kept intentionally minimal — it supports only
+// the DOM surface those functions touch.
+
+export class FakeElement {
+  tagName: string;
+  attributes: Record<string, string> = {};
+  className = "";
+  children: Array<FakeElement | { text: string }> = [];
+  textContent = "";
+  hidden = false;
+  disabled = false;
+  value = "";
+  checked = false;
+  type = "";
+  name = "";
+  id = "";
+  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, ev: unknown = { preventDefault() {}, stopPropagation() {} }): Promise<void> {
+    for (const fn of this.listeners[type] || []) await fn(ev);
+  }
+  append(...kids: Array<FakeElement | { text: string } | string>): void {
+    for (const kid of kids) {
+      if (typeof kid === "string") {
+        this.children.push({ text: kid });
+        this.textContent += kid;
+      } else if ("text" in kid) {
+        this.children.push(kid);
+        this.textContent += kid.text;
+      } else {
+        this.children.push(kid);
+        this.textContent += kid.textContent || "";
+      }
+    }
+  }
+  appendChild(kid: FakeElement | { text: string }): void {
+    this.append(kid);
+  }
+  replaceChildren(...kids: Array<FakeElement | { text: string } | string>): void {
+    this.children = [];
+    this.textContent = "";
+    this.append(...kids);
+  }
+  get firstChild(): FakeElement | { text: string } | null {
+    return this.children[0] ?? null;
+  }
+  querySelector(selector: string): FakeElement | null {
+    const walk = (nodes: Array<FakeElement | { text: string }>): FakeElement | null => {
+      for (const kid of nodes) {
+        if (kid instanceof FakeElement) {
+          if (fakeSelectorMatches(kid, selector)) return kid;
+          const found = walk(kid.children);
+          if (found) return found;
+        }
+      }
+      return null;
+    };
+    return walk(this.children);
+  }
+}
+
+// Minimal CSS-selector matcher for the DOM surface the browser runtime touches
+// (currently the radio group's `input:checked` lookup). Supports an optional tag
+// name plus `:checked`; any other pseudo/selector deliberately fails to match so
+// unsupported queries surface rather than silently returning a wrong node.
+function fakeSelectorMatches(node: FakeElement, selector: string): boolean {
+  const parts = selector.trim().split(":");
+  const tag = parts[0];
+  if (tag && node.tagName !== tag.toUpperCase()) return false;
+  for (const pseudo of parts.slice(1)) {
+    if (pseudo === "checked") {
+      if (!node.checked) return false;
+    } else {
+      return false;
+    }
+  }
+  return true;
+}
+
+/** Install a fake `document` on globalThis; returns a restore function. */
+export function installFakeDom(created: FakeElement[]): () => void {
+  const doc = {
+    createElement: (tag: string) => {
+      const n = new FakeElement(tag);
+      created.push(n);
+      return n;
+    },
+    createTextNode: (text: string) => ({ text: String(text) }),
+    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");
+  };
+}

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

@@ -0,0 +1,192 @@
+// @ts-check
+// ── Shared, XSS-safe form-js schema renderer (ADR 0026, extended by #457) ─────
+// This is the ONE client implementation of "render a deployed `.form`'s form-js
+// schema and collect its field values", shared verbatim by BOTH:
+//   • the `taskInbox` surface (surfaces.ts `inboxPage`), and
+//   • the pages `dataGrid` engine-form detail (runtime.browser.js).
+// It used to live inline in surfaces.ts; factoring it here means the two surfaces
+// can never fork the renderer or drift on how a form-js component maps to an input
+// and its submitted value.
+//
+// Like the rest of the browser runtime it is authored/type-checked/linted/tested
+// as real source and served as a generated string artifact (formjs.gen.ts, emitted
+// by scripts/gen-runtime.mjs). It performs NO DOM access at load — every DOM touch
+// is inside a function — so it is import-safe under Node/Deno for unit testing.
+//
+// SECURITY: every value the engine returns is placed via textContent / setAttribute
+// (never innerHTML), so nothing in the form schema can inject markup. The submitted
+// `variables` bag is null-prototype so an engine-supplied component key of
+// `__proto__`/`constructor` lands as a plain own property and can never mutate a
+// prototype (prototype-pollution class).
+
+/** Create an element, setting attributes via setAttribute and text via textContent only.
+ * @param {string} tag
+ * @param {Record<string, string>} [attrs]
+ * @param {string} [text]
+ * @returns {any}
+ */
+function fjEl(tag, attrs, text) {
+  const e = document.createElement(tag);
+  if (attrs) for (const k in attrs) e.setAttribute(k, attrs[k]);
+  if (text != null) e.textContent = text;
+  return e;
+}
+
+/** A plain type="button" with an optional click handler.
+ * @param {string} label
+ * @param {(() => void) | null} [onClick]
+ * @returns {any}
+ */
+function fjBtn(label, onClick) {
+  const b = document.createElement("button");
+  b.type = "button";
+  b.textContent = label;
+  if (onClick) b.addEventListener("click", onClick);
+  return b;
+}
+
+/** Build one form-js component into its field element and (for keyed inputs) a reader
+ * that returns the entered `{ key, value }` or null when blank. Static (keyless)
+ * components render as inert text; layout-only components are skipped (null).
+ * @param {any} c
+ * @returns {{ field: any, read?: () => ({ key: string, value: any } | null) } | null}
+ */
+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: fjEl("p", { class: "njf-text" }, typeof c.text === "string" ? c.text : "") };
+  }
+  const key = c && c.key;
+  if (!key) return null;
+  const wrap = fjEl("div", { class: "njf-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 = fjEl("label", {});
+    lab.appendChild(input);
+    lab.appendChild(document.createTextNode(" " + label));
+    wrap.appendChild(lab);
+    return { field: wrap, read: () => ({ key, value: input.checked }) };
+  }
+  const labelEl = fjEl("label", {}, label);
+  wrap.appendChild(labelEl);
+  let input;
+  if (type === "textarea") {
+    input = document.createElement("textarea");
+  } else if (type === "select") {
+    input = document.createElement("select");
+    input.appendChild(fjEl("option", { value: "" }, "\u2014"));
+    for (const o of Array.isArray(c.values) ? c.values : []) {
+      input.appendChild(fjEl("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 = fjEl("div", {});
+    for (const o of Array.isArray(c.values) ? c.values : []) {
+      const rlab = fjEl("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 };
+    },
+  };
+}
+
+/**
+ * Render a form-js schema into a `<form>` element with a submit + optional cancel.
+ * On submit it assembles every keyed field's value into one null-prototype
+ * `variables` bag and calls `opts.onSubmit(variables)`; a rejected submit re-enables
+ * the button so the operator can retry. `opts.onCancel`, when supplied, wires a
+ * cancel button.
+ * @param {any} schema the parsed form-js document (`{ components: [...] }`)
+ * @param {{ heading?: string, submitLabel?: string, cancelLabel?: string,
+ *           onSubmit: (variables: Record<string, any>) => (void | Promise<void>),
+ *           onCancel?: () => void }} opts
+ * @returns {any} the built <form> element
+ */
+function renderForm(schema, opts) {
+  const form = document.createElement("form");
+  form.className = "njf-form";
+  if (opts.heading) form.appendChild(fjEl("h2", { class: "njf-heading" }, opts.heading));
+  const components = schema && Array.isArray(schema.components) ? schema.components : [];
+  /** @type {Array<() => ({ key: string, value: any } | null)>} */
+  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 = fjBtn(opts.submitLabel || "Submit", null);
+  submit.type = "submit";
+  const bar = fjEl("div", { class: "njf-actions" });
+  bar.appendChild(submit);
+  if (opts.onCancel) bar.appendChild(fjBtn(opts.cancelLabel || "Cancel", opts.onCancel));
+  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;
+    Promise.resolve()
+      .then(() => opts.onSubmit(variables))
+      .catch(() => {
+        submit.disabled = false;
+      });
+  });
+  return form;
+}
+
+export { buildField, renderForm };
+
+// Expose the renderer as a browser global so both self-contained page bundles can
+// reach the ONE implementation without importing it: the taskInbox page embeds this
+// module inline and the pages shell does the same before loading the ES-module
+// runtime, which reads `globalThis.NanoFormJs` lazily when it renders an engine form.
+// Guarded so importing under Node/Deno for tests is a harmless no-op-ish assignment.
+if (typeof globalThis !== "undefined") {
+  /** @type {any} */ (globalThis).NanoFormJs = { buildField, renderForm };
+}

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

@@ -0,0 +1,136 @@
+// Unit tests for the shared form-js renderer (formjs.browser.js, ADR 0026/#457):
+// the ONE client implementation of "render a deployed .form's form-js schema and
+// collect its field values", shared by BOTH the taskInbox surface and the pages
+// dataGrid engine-form detail. Importing the module also registers it as the
+// `globalThis.NanoFormJs` global that the pages runtime consumes.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { buildField, renderForm } from "./formjs.browser.js";
+import { type FakeElement, installFakeDom } from "./fake-dom.test-utils.ts";
+
+test("NanoFormJs is registered as a browser global on import", () => {
+  const g = Reflect.get(globalThis, "NanoFormJs");
+  assert.ok(g, "importing the module exposes globalThis.NanoFormJs");
+});
+
+test("buildField skips keyless layout components and renders static text", (t) => {
+  const created: FakeElement[] = [];
+  t.after(installFakeDom(created));
+  assert.equal(buildField({ type: "spacer" }), null, "a keyless, non-text component is skipped");
+  const textOnly = buildField({ type: "text", text: "Read me" });
+  assert.ok(textOnly && !textOnly.read, "a static text component has no reader");
+  assert.equal(textOnly!.field.textContent, "Read me");
+});
+
+test("buildField reads a textfield's entered value, and omits a blank one", (t) => {
+  const created: FakeElement[] = [];
+  t.after(installFakeDom(created));
+  const built = buildField({ type: "textfield", key: "note", label: "Note" });
+  assert.ok(built?.read);
+  const input = created.find((n) => n.tagName === "INPUT");
+  assert.ok(input);
+  input!.value = "hello";
+  assert.deepEqual(built!.read!(), { key: "note", value: "hello" });
+  input!.value = "";
+  assert.equal(built!.read!(), null, "a blank field is omitted from the submitted variables");
+});
+
+test("buildField coerces a number field and drops a non-finite value", (t) => {
+  const created: FakeElement[] = [];
+  t.after(installFakeDom(created));
+  const built = buildField({ type: "number", key: "qty" });
+  const input = created.find((n) => n.tagName === "INPUT");
+  input!.value = "42";
+  assert.deepEqual(built!.read!(), { key: "qty", value: 42 });
+  input!.value = "not-a-number";
+  assert.equal(built!.read!(), null, "a tampered non-numeric number field is treated as absent, never NaN→null");
+});
+
+test("buildField maps a checkbox to a boolean value", (t) => {
+  const created: FakeElement[] = [];
+  t.after(installFakeDom(created));
+  const built = buildField({ type: "checkbox", key: "agree", label: "Agree" });
+  const input = created.find((n) => n.tagName === "INPUT");
+  input!.checked = true;
+  assert.deepEqual(built!.read!(), { key: "agree", value: true });
+});
+
+test("buildField reads the checked radio option (and omits an unselected group)", (t) => {
+  const created: FakeElement[] = [];
+  t.after(installFakeDom(created));
+  const built = buildField({
+    type: "radio",
+    key: "size",
+    label: "Size",
+    values: [
+      { value: "s", label: "Small" },
+      { value: "l", label: "Large" },
+    ],
+  });
+  assert.ok(built?.read);
+  assert.equal(built!.read!(), null, "an unselected radio group is omitted from the submitted variables");
+  const radios = created.filter((n) => n.tagName === "INPUT" && n.type === "radio");
+  assert.equal(radios.length, 2);
+  radios[1].checked = true;
+  assert.deepEqual(built!.read!(), { key: "size", value: "l" }, "read() finds the checked option via querySelector('input:checked')");
+});
+
+test("renderForm submits a null-prototype variables bag (prototype-pollution safe)", async (t) => {
+  const created: FakeElement[] = [];
+  t.after(installFakeDom(created));
+  const schema = {
+    components: [
+      { type: "textfield", key: "note" },
+      { type: "textfield", key: "__proto__" },
+    ],
+  };
+  let submitted: Record<string, unknown> | undefined;
+  const form = renderForm(schema, {
+    heading: "Task A",
+    onSubmit: (variables) => {
+      submitted = variables;
+    },
+  });
+  const inputs = created.filter((n) => n.tagName === "INPUT");
+  inputs[0].value = "hi";
+  inputs[1].value = "evil";
+  await form.fire("submit");
+  assert.ok(submitted);
+  assert.equal(Object.getPrototypeOf(submitted!), null, "the variables bag has a null prototype");
+  assert.equal(submitted!.note, "hi");
+  assert.equal(Object.prototype.hasOwnProperty.call(submitted!, "__proto__"), true, "an untrusted key lands as an own property");
+  assert.equal(Object.getPrototypeOf({}), Object.prototype, "no prototype was mutated");
+});
+
+test("renderForm re-enables the submit button when onSubmit rejects (retryable)", async (t) => {
+  const created: FakeElement[] = [];
+  t.after(installFakeDom(created));
+  const form = renderForm(
+    { components: [{ type: "textfield", key: "x" }] },
+    {
+      onSubmit: () => Promise.reject(new Error("boom")),
+    },
+  );
+  const submit = created.find((n) => n.tagName === "BUTTON" && n.type === "submit");
+  assert.ok(submit);
+  await form.fire("submit");
+  // The rejected onSubmit settles a microtask later; flush it.
+  await Promise.resolve();
+  await Promise.resolve();
+  assert.equal(submit!.disabled, false, "a failed submit re-enables the button so the operator can retry");
+});
+
+test("renderForm wires a cancel button only when onCancel is supplied", async (t) => {
+  const created: FakeElement[] = [];
+  t.after(installFakeDom(created));
+  renderForm({ components: [] }, { onSubmit: () => {} });
+  assert.equal(created.filter((n) => n.tagName === "BUTTON").length, 1, "no cancel button without onCancel");
+  created.length = 0;
+  let cancelled = false;
+  renderForm({ components: [] }, { onSubmit: () => {}, onCancel: () => (cancelled = true) });
+  const buttons = created.filter((n) => n.tagName === "BUTTON");
+  assert.equal(buttons.length, 2, "a cancel button is added when onCancel is supplied");
+  await buttons[1].fire("click");
+  assert.equal(cancelled, true, "clicking cancel invokes onCancel");
+});