@nanobpm/urban 0.78.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/dist/runtime/core/modules/workers.js

@@ -8,6 +8,9 @@ import { runInJobContext } from "../execContext.js";
 import { readLineage } from "../lineage.js";
 import { LineageStore } from "./lineage-store.js";
 import { readModelRegistry } from "../read-model.js";
+import { registerCanonicalProjections } from "./canonical-projections.js";
+import { InstanceStateStore } from "./instance-state-store.js";
+import { OpenUserTasksStore } from "./open-user-tasks-store.js";
 import { defaultScheduler, schedulerClock } from "./scheduler.js";
 /** Adapt an engine SDK client into the LLM module's `DecisionEvaluator`, parsing the
  *  decision's JSON-string `output` into the value fed back to the LLM job. Validates the
@@ -119,6 +122,28 @@ function tryProvisionReadModelViews(app, log) {
         log("warn", "read-models: failed to provision managed VIEWs", { error: String(err) });
     }
 }
+/**
+ * Provision the canonical engine-truth projection sidecars (ADR 0065, proposal point #1) on the app's
+ * DEFAULT data source — `_urban_open_user_tasks` and `_urban_instance_state`, the sources a read model
+ * `EXISTS`-derives its status edges from. Exactly the per-source boot path `tryLineageStore` uses: an
+ * app with no datasource provisions nothing, and a schema failure degrades to no projection tables
+ * rather than a failed worker mount. The DSL projection-name registration is done unconditionally by
+ * the caller (so read models compile even without a datasource); this only creates the physical tables.
+ */
+function tryProvisionCanonicalProjections(app, log) {
+    if (!app.data.hasDefaultSource()) {
+        log("debug", "canonical-projections: no default data source; projection tables not provisioned");
+        return;
+    }
+    try {
+        const { db } = app.data.source();
+        new OpenUserTasksStore(db).ensureSchema();
+        new InstanceStateStore(db).ensureSchema();
+    }
+    catch (err) {
+        log("warn", "canonical-projections: failed to provision projection tables", { error: String(err) });
+    }
+}
 /** Record an activated job's lineage edge, never letting a projection write break the job. */
 function recordJobLineage(store, job, log) {
     try {
@@ -169,6 +194,14 @@ export async function mountWorkers(ctx, app, sched = defaultScheduler()) {
     // The framework read-model VIEWs (ADR 0065): apply every registered managed VIEW to the app's
     // default data source, the same per-source boot path lineage uses. A no-op until a sibling task
     // registers a read model into `readModelRegistry`.
+    //
+    // Register the canonical engine-truth projections (`urban_open_user_tasks`, `urban_instance_state`)
+    // FIRST and unconditionally: a read model's managed VIEW resolves each projection name to its
+    // physical `_urban_` table at DDL-compile time, so the name→table mapping must exist before
+    // `tryProvisionReadModelViews` compiles any VIEW that `EXISTS`-references a projection. Then
+    // provision the projection tables per source (absent-safe), and finally the read-model VIEWs.
+    registerCanonicalProjections();
+    tryProvisionCanonicalProjections(app, ctx.host.log);
     tryProvisionReadModelViews(app, ctx.host.log);
     // Cache module loads so a multi-type handler module is imported once.
     const moduleCache = new Map();

package/dist/runtime/index.d.ts

@@ -42,6 +42,11 @@ export { LINEAGE_ATTACHMENTS_TABLE, LINEAGE_EDGES_TABLE, LINEAGE_SCHEMA_SQL, Lin
 export type { Clock as LineageClock, LineageJobLike, LineageStoreOptions, } from "./core/modules/lineage-store.ts";
 export { and, assertReadModelParity, assertSqlIdentifier, caseWhen, col, compileToFn, compileToSqlSelect, defineReadModel, deriveReadModelViewDdl, eq, exists, gt, gte, lit, lt, lte, neq, not, or, pcol, ProjectionRegistry, projectionRegistry, ReadModelRegistry, readModelRegistry, when, } from "./core/read-model.ts";
 export type { AndExpr, BaseRow, CaseExpr, ColExpr, CompareExpr, CompareOp, DerivationFn, ExistsExpr, Expr, Literal, LitExpr, NotExpr, OrExpr, ParityDb, ParityOptions, ParitySample, ProjColExpr, ProjectionRows, ProjectionSource, ReadModel, ReadModelDecl, SqlCompileOptions, WhenClause, } from "./core/read-model.ts";
+export { CANONICAL_PROJECTIONS, registerCanonicalProjections, } from "./core/modules/canonical-projections.ts";
+export { OPEN_USER_TASKS_PROJECTION, OPEN_USER_TASKS_SCHEMA_SQL, OPEN_USER_TASKS_TABLE, OpenUserTasksStore, } from "./core/modules/open-user-tasks-store.ts";
+export type { OpenUserTaskRow, OpenUserTasksStoreOptions, } from "./core/modules/open-user-tasks-store.ts";
+export { INSTANCE_STATE_PROJECTION, INSTANCE_STATE_SCHEMA_SQL, INSTANCE_STATE_TABLE, InstanceStateStore, } from "./core/modules/instance-state-store.ts";
+export type { InstanceStateRow, InstanceStateStoreOptions, } from "./core/modules/instance-state-store.ts";
 export { buildScopeIndex, derivePhase, deriveInstancePhases, furthestReached, rollupLineagePhase, SCOPE_CONTAINERS, } from "./core/phase.ts";
 export type { CrumbKind, CrumbSource, DerivePhaseOptions, FurthestReached, InstancePhase, LineagePhaseRollup, Phase, PhaseCrumb, PhaseGranularity, ProvenanceProgressRow, ScopeElement, ScopeIndex, } from "./core/phase.ts";
 export { deployModels, RESOURCES_DIR } from "./core/modules/deploy.ts";

package/dist/runtime/index.js

@@ -53,7 +53,14 @@ export { LINEAGE_ATTACHMENTS_TABLE, LINEAGE_EDGES_TABLE, LINEAGE_SCHEMA_SQL, Lin
 //   • `projectionRegistry` — register a canonical engine-truth projection NAME usable in `exists(...)`.
 //     The `canonical-projections` task registers `urban_open_user_tasks` / `urban_instance_state`.
 export { and, assertReadModelParity, assertSqlIdentifier, caseWhen, col, compileToFn, compileToSqlSelect, defineReadModel, deriveReadModelViewDdl, eq, exists, gt, gte, lit, lt, lte, neq, not, or, pcol, ProjectionRegistry, projectionRegistry, ReadModelRegistry, readModelRegistry, when, } from "./core/read-model.js";
-// Phase — the framework-level *domain phase* primitive (issue #266): derive "which phase is this
+// Canonical engine-truth projection sidecars (ADR 0065, proposal point #1): two framework-owned,
+// per-source projections the DSL `exists(...)` derives over — `urban_open_user_tasks` (which instances
+// are parked on a human) and `urban_instance_state` (per-instance engine lifecycle state). Provisioned
+// next to the lineage sidecar in core/modules/workers.ts; registered into `projectionRegistry` under
+// their stable DSL names via `registerCanonicalProjections()`.
+export { CANONICAL_PROJECTIONS, registerCanonicalProjections, } from "./core/modules/canonical-projections.js";
+export { OPEN_USER_TASKS_PROJECTION, OPEN_USER_TASKS_SCHEMA_SQL, OPEN_USER_TASKS_TABLE, OpenUserTasksStore, } from "./core/modules/open-user-tasks-store.js";
+export { INSTANCE_STATE_PROJECTION, INSTANCE_STATE_SCHEMA_SQL, INSTANCE_STATE_TABLE, InstanceStateStore, } from "./core/modules/instance-state-store.js";
 // instance in?" from the BPMN scope hierarchy + write-provenance (Tier 0, zero declaration), an
 // optional `nano:phase` override (Tier 1), and a lineage rollup for the epic frontier (Tier 2).
 export { buildScopeIndex, derivePhase, deriveInstancePhases, furthestReached, rollupLineagePhase, SCOPE_CONTAINERS, } from "./core/phase.js";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.78.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 };
+}