@nanobpm/urban 0.54.0 → 0.56.0

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

@@ -0,0 +1,118 @@
+// Direct unit tests for the browser page runtime (#291). Because the runtime is
+// now REAL importable source — not a `String.raw` blob — we can import its
+// renderer functions and its RENDERERS registry and drive them with a minimal
+// fake DOM, instead of string-scraping the served module. This replaces the #290
+// regex drift guard (which had to regex the RENDERERS keys out of a string) with
+// a real import, and adds the first true renderer-level unit coverage.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { PAGE_NODE_TYPES } from "@nanobpm/nano-app-schema";
+import { RENDERERS, renderText } from "./runtime.browser.js";
+
+// ── Minimal fake DOM ────────────────────────────────────────────────────────
+// Just enough of the Element/Document surface that el()/renderText touch:
+// createElement, className, setAttribute, addEventListener, append (of child
+// nodes and text), and a readable textContent. Installed on globalThis so the
+// module's global `document` resolves to it when a renderer is invoked. The
+// module itself performs NO DOM access at import time (its boot() is gated), so
+// installing this only needs to happen before we CALL a renderer.
+class FakeElement {
+  tagName: string;
+  attributes: Record<string, string> = {};
+  className = "";
+  children: Array<FakeElement | { text: string }> = [];
+  textContent = "";
+  dataset: Record<string, string> = {};
+  hidden = false;
+  style = { setProperty() {} };
+
+  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(): void {}
+  append(...kids: Array<FakeElement | string>): void {
+    for (const kid of kids) {
+      if (typeof kid === "string") {
+        this.children.push({ text: kid });
+        this.textContent += kid;
+      } else {
+        this.children.push(kid);
+        this.textContent += kid.textContent || "";
+      }
+    }
+  }
+  querySelector(): null {
+    return null;
+  }
+}
+
+// Installs the fake DOM on globalThis and returns a restore function that undoes
+// the mutation, so a test can register `t.after(restore)` and never leak
+// `globalThis.document` into later tests (which would be racy if node:test ran
+// files/tests concurrently). Captures the prior descriptor so the original
+// value — including `undefined` — is faithfully restored.
+function installFakeDom(): () => void {
+  const doc = {
+    createElement: (tag: string) => new FakeElement(tag),
+    getElementById: () => null,
+  };
+  const prior = Reflect.getOwnPropertyDescriptor(globalThis, "document");
+  // Reflect.set writes through the untyped host boundary (globalThis.document is
+  // typed Document under the DOM lib; our fake only implements what the renderer
+  // touches) without an `as` cast (banned repo-wide).
+  Reflect.set(globalThis, "document", doc);
+  return () => {
+    if (prior) {
+      Reflect.defineProperty(globalThis, "document", prior);
+    } else {
+      Reflect.deleteProperty(globalThis, "document");
+    }
+  };
+}
+
+test("#291: RENDERERS is a real importable registry keyed exactly by PAGE_NODE_TYPES", () => {
+  // The drift lock is enforced at compile time by `RENDERERS satisfies
+  // Record<PageNodeType, Renderer>` in the source; this asserts the same at
+  // runtime via a real import (no string-scraping of the served module). If the
+  // schema gains a page-node type without a renderer here (or vice-versa) this
+  // fails loudly — the App would otherwise render an accepted node as a blank div.
+  assert.deepEqual(
+    Object.keys(RENDERERS).sort(),
+    [...PAGE_NODE_TYPES].sort(),
+    "RENDERERS keys must equal the shared PAGE_NODE_TYPES registry",
+  );
+  for (const [type, renderer] of Object.entries(RENDERERS)) {
+    assert.equal(typeof renderer, "function", `renderer for "${type}" must be a function`);
+  }
+});
+
+test("#291: renderText renders the heading/sub/body variant with the right tag + class", (t) => {
+  t.after(installFakeDom());
+  const heading = renderText({ type: "text", props: { variant: "heading", text: "Hello" } });
+  assert.equal(heading.tagName, "H1");
+  assert.equal(heading.className, "pc-heading");
+  assert.equal(heading.textContent, "Hello");
+
+  const sub = renderText({ type: "text", props: { variant: "sub", text: "Subtitle" } });
+  assert.equal(sub.tagName, "P");
+  assert.equal(sub.className, "pc-sub");
+
+  const body = renderText({ type: "text", props: { text: "Body copy" } });
+  assert.equal(body.tagName, "P");
+  assert.equal(body.className, "pc-body");
+  assert.equal(body.textContent, "Body copy");
+});
+
+test("#291: renderText degrades to empty text (never throws) on a missing text prop", (t) => {
+  t.after(installFakeDom());
+  const node = renderText({ type: "text", props: {} });
+  assert.equal(node.tagName, "P");
+  assert.equal(node.textContent, "");
+});

package/src/runtime/core/host.ts

@@ -249,6 +249,18 @@ export interface UserTaskSummary {
   readonly externalFormReference?: string;
 }
 
+/**
+ * The lifecycle-state-agnostic selectors for a user-task search: which process instance,
+ * assignee, and/or candidate group to match. Shared by {@link EngineClient.searchUserTasks}
+ * (which adds an optional `state`) and {@link EngineClient.openUserTasks} (which pins
+ * `state: "CREATED"` for you), so the two accessors cannot drift on how a task is selected.
+ */
+export interface UserTaskFilter {
+  processInstanceKey?: string;
+  assignee?: string;
+  candidateGroup?: string;
+}
+
 /**
  * A deployed form's form-js schema plus its identifying metadata, as
  * {@link EngineClient.getForm} returns it. `schema` is the parsed form-js document
@@ -292,13 +304,28 @@ export interface EngineClient {
    *  By default this is unfiltered by lifecycle state and may return tasks in any state
    *  (e.g. completed/canceled); pass `state: "CREATED"` to constrain the search to open
    *  (answerable) tasks. Each result carries the task's resolved form linkage
-   *  (`formKey`/`externalFormReference`) when present. */
-  searchUserTasks(filter?: {
-    processInstanceKey?: string;
-    assignee?: string;
-    candidateGroup?: string;
+   *  (`formKey`/`externalFormReference`) when present.
+   *
+   *  **Footgun:** because this defaults to *any* lifecycle state and lags a completion,
+   *  a just-answered task is still returned for a moment — so treating mere *existence*
+   *  of a result as "open / actionable" projects a completed task as if a human could
+   *  still act on it (a torn read-model row). {@link UserTaskSummary} deliberately omits
+   *  `state`, so a caller cannot re-filter results defensively. If you are deciding
+   *  whether a human can act — any reconcile / affordance path — use
+   *  {@link EngineClient.openUserTasks} instead; reserve `searchUserTasks` for the rare
+   *  legitimate "any lifecycle state" audit/read case. */
+  searchUserTasks(filter?: UserTaskFilter & {
     state?: UserTaskState;
   }): Promise<UserTaskSummary[]>;
+  /** The user tasks that are actually *open* (answerable) — semantically the accessor to
+   *  reach for whenever you are deciding whether a human can act (reconcile / affordance
+   *  paths). A thin, intent-named wrapper that pins the lifecycle-state invariant the SDK
+   *  documents: exactly `searchUserTasks({ ...filter, state: "CREATED" })`, since `CREATED`
+   *  is the only open state ({@link UserTaskState}). Unlike a bare `searchUserTasks`, it
+   *  cannot surface a completed/canceled task as if it were still actionable — the footgun
+   *  described on `searchUserTasks`. Same selectors as `searchUserTasks` minus `state`
+   *  (pinned to `CREATED`). */
+  openUserTasks(filter?: UserTaskFilter): Promise<UserTaskSummary[]>;
   /**
    * Fetch a deployed form's form-js schema for the `taskInbox` surface. Resolve by
    * `formKey` (the linkage the engine attaches to a user task) or, as a best-effort

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

@@ -29,6 +29,7 @@ const engine: EngineClient = {
   cancelInstance: async () => {},
   publishMessage: async () => {},
   searchUserTasks: async () => [],
+  openUserTasks: async () => [],
   getForm: async () => null,
   completeUserTask: async () => {},
   searchProcessInstances: async () => [],

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

@@ -13,6 +13,7 @@ const fakeEngine: EngineClient = {
   cancelInstance: async () => {},
   publishMessage: async () => {},
   searchUserTasks: async () => [],
+  openUserTasks: async () => [],
   getForm: async () => null,
   completeUserTask: async () => {},
   searchProcessInstances: async () => [],

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

@@ -28,6 +28,7 @@ const engine: EngineClient = {
   cancelInstance: async () => {},
   publishMessage: async () => {},
   searchUserTasks: async () => [],
+  openUserTasks: async () => [],
   getForm: async () => null,
   searchProcessInstances: async () => [],
   completeUserTask: async () => {},

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

@@ -73,6 +73,7 @@ function cancelEngine(opts: {
     createInstance: notUsed("createInstance"),
     publishMessage: notUsed("publishMessage"),
     searchUserTasks: notUsed("searchUserTasks"),
+    openUserTasks: notUsed("openUserTasks"),
     getForm: notUsed("getForm"),
     completeUserTask: notUsed("completeUserTask"),
     registerWorker: notUsed("registerWorker"),

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

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

package/src/runtime/core/modules/datasource.migrations.test.ts

@@ -16,6 +16,7 @@ const noEngine: EngineClient = {
   cancelInstance: async () => {},
   publishMessage: async () => {},
   searchUserTasks: async () => [],
+  openUserTasks: async () => [],
   getForm: async () => null,
   completeUserTask: async () => {},
   searchProcessInstances: async () => [],

package/src/runtime/core/modules/instance-tracking.test.ts

@@ -96,6 +96,7 @@ function fakeEngine(states: Record<string, ProcessInstanceSnapshot["state"]>): {
     cancelInstance: notUsed("cancelInstance"),
     publishMessage: notUsed("publishMessage"),
     searchUserTasks: notUsed("searchUserTasks"),
+    openUserTasks: notUsed("openUserTasks"),
     getForm: notUsed("getForm"),
     completeUserTask: notUsed("completeUserTask"),
     registerWorker: notUsed("registerWorker"),

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

@@ -1,5 +1,9 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import type { EngineClient, HttpRequest, HttpResponse } from "../host.ts";
 import { makeRouter } from "../router.ts";
 import { createPagesRoutes, type PagesDataSource, type PagesDeps } from "./pages.ts";
@@ -40,6 +44,7 @@ function fakeEngine(): { engine: EngineClient; calls: FakeEngineCalls } {
       calls.messages.push(input);
     },
     async searchUserTasks() { return []; },
+    async openUserTasks() { return []; },
     async getForm() { return null; },
     async completeUserTask() {},
     async searchProcessInstances() { return []; },
@@ -499,7 +504,7 @@ test("renderer binds a route param: parseRoute splits page/param, filters + text
   assert.match(js, /const slash = raw\.indexOf\("\/"\)/);
   assert.match(js, /const paramRaw = slash >= 0 \? raw\.slice\(slash \+ 1\) : ""/);
   assert.match(js, /param = paramRaw \? decodeURIComponent\(paramRaw\) : ""/);
-  assert.match(js, /let PARAM = parseRoute\(\)\.param/);
+  assert.match(js, /PARAM = parseRoute\(\)\.param/);
   // renderPage refreshes PARAM from the current route on every (re)render.
   assert.match(js, /const route = parseRoute\(\);\s*CURRENT = route\.page;\s*PARAM = route\.param;/s);
   // A datasource filter with { eqParam: true } binds its value to the live PARAM,
@@ -583,7 +588,7 @@ test("renderer exposes an embed-gated host-navigation bridge", async () => {
   // data can't smuggle a path. The same-origin gate reads parent.location.origin
   // in a try/catch (a cross-origin parent throws under the same-origin policy).
   assert.match(js, /window\.parent\.location\.origin === window\.location\.origin/);
-  assert.match(js, /const NANO_EMBEDDED =/);
+  assert.match(js, /NANO_EMBEDDED = computeEmbedded\(\)/);
   assert.match(js, /function hostNavigate\(target, params\)/);
   assert.match(js, /if \(!NANO_EMBEDDED\) return false;/);
   assert.match(
@@ -591,7 +596,7 @@ test("renderer exposes an embed-gated host-navigation bridge", async () => {
     /window\.parent\.postMessage\(\s*\{\s*type:\s*"nano-navigate",\s*target:\s*target,\s*params:\s*params\s*\}\s*,\s*window\.location\.origin\s*\)/,
   );
   // The theme bridge reuses the same embed flag (no second window.parent probe).
-  assert.match(js, /if \(NANO_EMBEDDED\) \{/);
+  assert.match(js, /function installThemeBridge\(\)\s*\{\s*if \(!NANO_EMBEDDED\) return;/);
 });
 
 test("the renderer honours numeric actionForm fields", async () => {
@@ -689,7 +694,7 @@ test("renderer makes collapsible nodes persist their state across sessions", asy
   assert.match(js, /localStorage\.setItem\(key, val \? "1" : "0"\)/);
   assert.match(js, /catch \(e\) \{\s*return dflt;/);
   // And the wrapper is actually applied at the dispatch layer.
-  assert.match(js, /makeCollapsible\(n, \(RENDERERS\[n\.type\]/);
+  assert.match(js, /makeCollapsible\(n, \(\/\*\* @type \{Record<string, Renderer>\} \*\/ \(RENDERERS\)\[n\.type\]/);
   // Non-card renderer output (e.g. text -> <p>) is nested whole inside a fresh
   // <section class="pc-card"> rather than having a <button>/<div> injected into
   // it — so the feature is valid markup across every node type, not just cards.
@@ -891,6 +896,46 @@ test("the renderer ships a button node that opens a copy-pasteable modal", async
 });
 
 
+test("row-action confirm/error route through the in-DOM modal, never native confirm()/alert() (#276)", async () => {
+  // A sandboxed iframe without `allow-modals` makes window.confirm() return false
+  // WITHOUT prompting and turns alert()/prompt() into no-ops — so every
+  // confirm-guarded row action silently dead-ended (the !confirm(...) guard was
+  // always true → fireAction never ran) and its errors vanished. The fix routes
+  // both through urban's in-DOM openModal overlay, which works with no host
+  // sandbox change.
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // The confirm gate awaits an in-DOM dialog and only proceeds on a real choice.
+  assert.match(js, /if \(ra\.confirm && !\(await confirmModal\(ra\.confirm\)\)\) return/);
+  // Errors surface through the in-DOM alert instead of the suppressed native one.
+  assert.match(js, /alertModal\(String\(e\.message \|\| e\)\)/);
+  // The primitives exist and are built on the shared openModal overlay (no drift).
+  assert.match(js, /function confirmModal\(message\)/);
+  assert.match(js, /return new Promise\(\(resolve\) => \{/);
+  assert.match(js, /function alertModal\(message\)/);
+  // A dropped guarded open (a modal already showing) resolves false, never hangs.
+  assert.match(js, /if \(!opened\) resolve\(false\)/);
+  // openModal grew action buttons + a single-fire result callback so it can back a
+  // decision dialog; a dismissal (Escape/backdrop/✕/page switch) resolves the
+  // caller's default (dismissValue).
+  assert.match(js, /Array\.isArray\(m\.actions\)/);
+  assert.match(js, /resultValue = a\.value; close\(\);/);
+  // Match the semantic call site only — teardown wraps onResult in a try/catch so
+  // a throwing callback can't abort focus restoration, so don't pin the control flow.
+  assert.match(js, /onResult\(resultValue\)/);
+  // Defect-class guard: NO native confirm()/alert()/prompt() CALL (invoked with a
+  // string/identifier/template argument) survives anywhere in the served bundle —
+  // they are all false/no-ops under a sandboxed iframe. This also catches qualified
+  // calls (window.confirm(...) / globalThis.alert(...)): the lookbehind only excludes
+  // a preceding word char (so confirmModal(...) / alertModal(...) don't match), not a
+  // preceding ".", so a member call still trips the guard. The argument-start class
+  // covers string/template literals and identifier heads including $ and _
+  // (e.g. confirm(_msg), alert($msg), prompt(`...`)). Empty-paren mentions in
+  // comments (e.g. "native confirm()") are documentation, not calls, so are not matched.
+  assert.doesNotMatch(js, /(?<!\w)(?:confirm|alert|prompt)\(\s*["'`$_a-zA-Z]/);
+});
+
+
 test("the renderer ships a data-bound prose/markdown list node (#274)", async () => {
   const res = await dispatch("GET", "/app/runtime.js");
   const js = res.body ?? "";
@@ -956,9 +1001,8 @@ test("the prose renderer ships a safe, dependency-free markdown → DOM converte
   // Underscore emphasis is word-boundary guarded so snake_case identifiers survive.
   assert.match(js, /function mdIsWordChar\(c\)/);
   assert.match(js, /!mdIsWordChar\(s\[i - 1\]\)/);
-  // The code backtick is built from a char code so this source stays inside the
-  // String.raw template literal.
-  assert.match(js, /const MD_BACKTICK = String\.fromCharCode\(96\)/);
+  // The markdown code backtick is a literal in the standalone runtime source.
+  assert.match(js, /const MD_BACKTICK = "`"/);
 });
 
 test("the shell styles the prose/markdown list at a comfortable reading measure (#274)", async () => {
@@ -1430,3 +1474,66 @@ test("shell CSS carries the .pc-pipe* track chrome reusing --nano-* tokens", asy
   assert.match(html, /\.pc-pipe-skip \{[^}]*border-style:dashed/);
   assert.match(html, /\.pc-pipe-upcoming \{[^}]*var\(--nano-text-faint\)/);
 });
+
+// NOTE (#291): the RENDERERS ↔ PAGE_NODE_TYPES drift guard no longer string-scrapes
+// the served module. RENDERERS is now compile-time locked (`satisfies
+// Record<PageNodeType, Renderer>`) in the real source, and verified at runtime by a
+// direct-import test in ../../browser/runtime.browser.test.ts — no regex needed.
+
+function hasStderr(err: unknown): err is { stderr: unknown } {
+  return typeof err === "object" && err !== null && "stderr" in err;
+}
+
+// Run `node --check` on a source string by writing it to a temp `.mjs` module and
+// invoking a child `node` process. Returns the check outcome: `ok` on exit 0, or the
+// captured stderr diagnostic when node rejects the module's syntax. This is the whole
+// CI guard — a stray brace / bad token in the served runtime becomes a failing test
+// here instead of a blank page in a browser that loads `/app/runtime.js`.
+function nodeCheck(source: string): { ok: boolean; stderr: string } {
+  const dir = mkdtempSync(join(tmpdir(), "urban-runtime-check-"));
+  const file = join(dir, "runtime.mjs");
+  try {
+    writeFileSync(file, source, "utf8");
+    // Spawn the real `node` binary explicitly. `process.execPath` points at the host
+    // runtime — which under `deno test` is the `deno` binary, whose `--check` runs the
+    // module instead of syntax-only parsing (blowing up on `document`). This guard is
+    // specifically `node --check`, so it must invoke `node` under every test runner.
+    execFileSync("node", ["--check", file], { stdio: "pipe" });
+    return { ok: true, stderr: "" };
+  } catch (err) {
+    const stderr = hasStderr(err) ? String(err.stderr ?? "") : String(err);
+    return { ok: false, stderr };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+test("the served runtime module passes `node --check` (no syntax errors)", async () => {
+  // The browser runtime is authored as a ~99 KB `String.raw` blob (RENDERER_JS) that
+  // is never type-checked, linted, or otherwise parsed at build time — a stray brace or
+  // bad token surfaces only when a browser loads `/app/runtime.js` and the module fails
+  // to evaluate, silently breaking every page action. This guard serves the module
+  // exactly as production does and runs `node --check` on it, so a syntax error fails CI
+  // instead of the browser. Interim step toward #291 (the full architectural fix).
+  const res = await dispatch("GET", "/app/runtime.js");
+  const source = res.body ?? "";
+  assert.ok(source.length > 0, "the runtime module must be served with a body");
+  const result = nodeCheck(source);
+  assert.ok(
+    result.ok,
+    `served runtime module has a syntax error (node --check):\n${result.stderr}`,
+  );
+});
+
+test("the syntax guard is red/green: an injected syntax error fails `node --check`", async () => {
+  // Prove the guard actually bites — a guard that can't fail is worthless. We take the
+  // real served module and splice in a deliberate syntax error (an unterminated function
+  // declaration), then assert `node --check` rejects it. This pins the guard against a
+  // future refactor that accidentally makes nodeCheck always pass (e.g. swallowing the
+  // child's non-zero exit), which would let a broken RENDERER_JS sail through CI.
+  const res = await dispatch("GET", "/app/runtime.js");
+  const broken = `${res.body ?? ""}\nfunction pcInjectedSyntaxError( {\n`;
+  const result = nodeCheck(broken);
+  assert.equal(result.ok, false, "an injected syntax error must fail `node --check`");
+  assert.match(result.stderr, /SyntaxError/);
+});