@nanobpm/urban 0.53.0 → 0.55.0

package/dist/runtime/core/host.d.ts

@@ -216,6 +216,17 @@ export interface UserTaskSummary {
     /** An external form reference (a form linked outside the deployment), if any. */
     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
@@ -267,13 +278,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/dist/runtime/core/modules/pages.js

@@ -575,6 +575,30 @@ table.pc-grid th { font-weight:600; color:var(--nano-text-muted); }
 .pc-group-toggle { display:flex; align-items:center; gap:.5rem; width:100%; padding:.4rem .6rem; background:transparent; border:0; color:inherit; font:inherit; font-weight:600; cursor:pointer; text-align:left; }
 .pc-group-toggle:hover { background:var(--nano-hover); }
 .pc-group-title { font-size:.9rem; }
+/* Data-bound prose/markdown list (renderProse, #274). Long-form narrative
+   records — plan-review findings, coordination notes, escalation bodies — read
+   as a stacked, full-width document at a comfortable measure (~66ch) instead of
+   being jammed into a grid column. Each item stacks a small header over a
+   markdown-rendered body; the body max-width is set inline per node (props.measure)
+   with this rule as the no-JS fallback. */
+.pc-prose-list { display:flex; flex-direction:column; gap:1.1rem; }
+.pc-prose-item { border-top:1px solid var(--nano-edge); padding-top:.9rem; }
+.pc-prose-item:first-child { border-top:0; padding-top:0; }
+.pc-prose-head { font-size:.8rem; font-weight:600; color:var(--nano-text-muted); text-transform:uppercase; letter-spacing:.03em; margin:0 0 .35rem; }
+.pc-prose-empty { color:var(--nano-text-faint); }
+.pc-prose-body { max-width:66ch; }
+.pc-prose-body > :first-child { margin-top:0; }
+.pc-prose-body > :last-child { margin-bottom:0; }
+.pc-md-p { margin:.55rem 0; overflow-wrap:anywhere; }
+.pc-md-h { font-size:1.05rem; font-weight:650; margin:.95rem 0 .4rem; }
+.pc-md-list { margin:.45rem 0; padding-left:1.35rem; }
+.pc-md-list li { margin:.15rem 0; }
+.pc-md-quote { margin:.6rem 0; padding:.1rem .9rem; border-left:3px solid var(--nano-edge-strong); color:var(--nano-text-muted); }
+.pc-md-pre { background:var(--nano-inset); border:1px solid var(--nano-edge); border-radius:.4rem; padding:.7rem .8rem; overflow:auto; margin:.6rem 0; }
+.pc-md-pre code { font:.82rem/1.5 ui-monospace,SFMono-Regular,Menlo,monospace; color:var(--nano-text); white-space:pre; }
+.pc-md-code { background:var(--nano-inset); border-radius:.3rem; padding:.05rem .3rem; font:.85em ui-monospace,SFMono-Regular,Menlo,monospace; }
+.pc-md-hr { border:0; border-top:1px solid var(--nano-edge); margin:1rem 0; }
+.pc-prose-body a { color:var(--nano-accent-strong); }
 /* A standalone button node + the modal it opens (e.g. a copy-pasteable prompt). */
 .pc-buttonrow { margin:1rem 0; }
 .pc-btn-ghost { background:transparent; color:var(--nano-text-muted); border:1px solid var(--nano-edge); }
@@ -682,8 +706,8 @@ table.pc-grid th { font-weight:600; color:var(--nano-text-muted); }
 `;
 // The schema-driven browser renderer (ADR 0042 §3). Plain ES module string served at
 // /app/runtime.js — it does NOT ship Craft.js (authoring is console-side only). It
-// fetches the home page's page.json and renders text / actionForm / dataGrid nodes,
-// wiring actionForm → /app/actions/start and dataGrid → /app/data (with a refresh).
+// fetches the home page's page.json and renders text / actionForm / dataGrid / prose
+// nodes, wiring actionForm → /app/actions/start and dataGrid/prose → /app/data (with a refresh).
 const RENDERER_JS = String.raw `
 const root = document.getElementById("page");
 const HOME = root.dataset.home || "home";
@@ -991,7 +1015,9 @@ function resolveCopyText(text) {
 function openModal(m) {
   // Only one modal at a time — drop a second (e.g. double-click) open so we
   // never stack overlays or register duplicate document-level keydown handlers.
-  if (modalOpen) return;
+  // Return null (not a close fn) so a guarded caller (confirmModal) can tell the
+  // open was dropped and resolve rather than hang.
+  if (modalOpen) return null;
   modalOpen = true;
   const overlay = el("div", { class: "pc-modal-overlay" });
   // role="dialog" + aria-modal need an accessible name: label by the visible
@@ -1010,6 +1036,13 @@ function openModal(m) {
   // Remember what had focus so we can restore it on close — a keyboard/screen
   // reader user returns to where they were instead of being dumped at <body>.
   const prevFocus = document.activeElement;
+  // A dismissal (✕/Close button, backdrop, Escape, page switch) resolves with
+  // m.dismissValue; an action button overrides it before closing. onResult fires
+  // exactly once, from close(), so every exit path (button OR dismiss) reports a
+  // result — this is what lets confirmModal() gate on a real user choice inside a
+  // sandboxed iframe where native confirm() would silently return false (#276).
+  const onResult = typeof m.onResult === "function" ? m.onResult : null;
+  let resultValue = m.dismissValue;
   let closed = false;
   function close() {
     if (closed) return;
@@ -1022,6 +1055,9 @@ function openModal(m) {
     // accrete dead close() closures until the next page navigation runs teardown.
     const i = disposers.indexOf(close);
     if (i !== -1) disposers.splice(i, 1);
+    // A consumer-provided result callback must never abort teardown: if it throws,
+    // swallow it so focus restoration below (and Escape/backdrop close) still runs.
+    if (onResult) { try { onResult(resultValue); } catch (_e) {} }
     if (prevFocus && typeof prevFocus.focus === "function") prevFocus.focus();
   }
   // Focusable descendants of the dialog, in DOM order, for the Tab focus trap.
@@ -1054,7 +1090,29 @@ function openModal(m) {
   }
   const closeBtn = el("button", { class: "pc-btn pc-btn-sm pc-btn-ghost", type: "button" }, m.closeLabel || "Close");
   closeBtn.addEventListener("click", close);
-  actions.append(closeBtn);
+  // Custom action buttons (m.actions) turn this into a decision dialog — each
+  // sets the result then closes; the plain Close button is the default when none
+  // are given. This is the in-DOM replacement for native confirm()/alert(): one
+  // overlay + focus-trap + teardown machinery, no drift (AGENTS.md).
+  let focusBtn = closeBtn;
+  if (Array.isArray(m.actions) && m.actions.length) {
+    let firstActionBtn = null;
+    let defaultBtn = null;
+    for (const a of m.actions) {
+      const cls = "pc-btn pc-btn-sm" + (a.variant === "ghost" ? " pc-btn-ghost" : "");
+      const ab = el("button", { class: cls, type: "button" }, a.label);
+      ab.addEventListener("click", () => { resultValue = a.value; close(); });
+      actions.append(ab);
+      if (!firstActionBtn) firstActionBtn = ab;
+      if (a.default) defaultBtn = ab;
+    }
+    // Default focus lands on the FIRST action (typically Cancel), never the last:
+    // for confirmModal that keeps a stray Enter from accidentally triggering the
+    // destructive Confirm. An action can opt into autofocus with default:true.
+    focusBtn = defaultBtn || firstActionBtn;
+  } else {
+    actions.append(closeBtn);
+  }
   dialog.append(actions);
   overlay.append(dialog);
   // A click on the backdrop (never the dialog itself) dismisses.
@@ -1064,7 +1122,36 @@ function openModal(m) {
   // A page switch runs teardown() before the next render — dispose the modal
   // there too so navigating away never leaves a stale overlay + keydown listener.
   disposers.push(close);
-  closeBtn.focus();
+  focusBtn.focus();
+  return close;
+}
+
+// In-DOM confirm — an accessible replacement for native confirm() that works in
+// a sandboxed iframe (without allow-modals native confirm() silently returns
+// false, dead-ending every confirm-guarded action; #276). Renders the message
+// with Cancel/Confirm and resolves the user's choice; a dismissal (Escape /
+// backdrop / ✕) resolves false. If a modal is already open the guarded open is
+// dropped — resolve false so the caller doesn't hang.
+function confirmModal(message) {
+  return new Promise((resolve) => {
+    const opened = openModal({
+      title: "Confirm",
+      description: String(message),
+      dismissValue: false,
+      actions: [
+        { label: "Cancel", value: false, variant: "ghost" },
+        { label: "Confirm", value: true },
+      ],
+      onResult: (v) => resolve(!!v),
+    });
+    if (!opened) resolve(false);
+  });
+}
+
+// In-DOM error surface — replaces native alert(), which a sandboxed iframe also
+// suppresses, so action failures reported through it were invisible (#276).
+function alertModal(message) {
+  openModal({ title: "Error", description: String(message) });
 }
 
 // A standalone button node. Clicking it opens props.modal — used e.g. to surface
@@ -1682,6 +1769,248 @@ function renderActionForm(node) {
 // Single source of truth for both the initial render and every refresh below.
 function rowCountLabel(n) { return n + (n === 1 ? " row" : " rows"); }
 
+// Build the /app/data/<source>/<table> URL a data-bound list renderer fetches,
+// threading the whitelisted where/order query params. Shared by dataGrid and the
+// prose renderer so the two can't drift on how a filter/orderBy is encoded. A
+// filter is { field, in:[…] } (IN set), { field, eqParam:true } (bound to the
+// current route PARAM — "show the selected entity's rows"), or { field, eq } (a
+// literal equals); orderBy is { field, dir }. The source/table/field names are
+// server-side whitelisted (the /app/data route rejects unknown columns).
+function dataUrl(source, tbl, filters, order) {
+  let u = "/app/data/" + encodeURIComponent(source) + "/" + encodeURIComponent(tbl);
+  const qs = [];
+  for (const f of filters || []) {
+    if (Array.isArray(f.in)) qs.push("where=" + encodeURIComponent(f.field + ":in:" + f.in.join(",")));
+    else if (f.eqParam) qs.push("where=" + encodeURIComponent(f.field + ":" + PARAM));
+    else qs.push("where=" + encodeURIComponent(f.field + ":" + f.eq));
+  }
+  if (order && order.field) qs.push("order=" + encodeURIComponent(order.field + ":" + (order.dir || "asc")));
+  return qs.length ? u + "?" + qs.join("&") : u;
+}
+
+// ── Minimal, safe Markdown → DOM (no innerHTML) — used by the prose renderer ──
+// A dependency-free CommonMark subset. It NEVER sets innerHTML: every block and
+// inline token is materialised as a known element via el(), with text set through
+// textContent / createTextNode — so a record's body field may carry markdown
+// WITHOUT ever becoming an HTML/script injection vector (the same text-only
+// guarantee interpTemplate gives a grid cell). Supported: ATX headings
+// (#..######), fenced + inline code, bold (**/__), italic (*/_), links
+// [text](url) (http/https/mailto only — every other scheme degrades to its plain
+// label), unordered (-,*,+) and ordered (1. / 1)) lists, blockquotes (>),
+// thematic breaks (---), and blank-line-separated paragraphs. The backtick used
+// for code spans/fences is built from a char code so this source stays inside the
+// String.raw template literal (which is itself delimited by a backtick).
+const MD_BACKTICK = String.fromCharCode(96);
+function mdIsWordChar(c) { return typeof c === "string" && /[0-9A-Za-z]/.test(c); }
+// Only http(s)/mailto hrefs become anchors; anything else (javascript:, data:,
+// vbscript:, a bare relative path, …) returns "" so the caller renders the label
+// as plain text rather than a clickable, potentially-hostile link.
+function mdSafeHref(href) {
+  const h = String(href == null ? "" : href).trim();
+  return /^(?:https?:|mailto:)/i.test(h) ? h : "";
+}
+// Find the closing run of 'marker' at or after 'from'. For underscore emphasis the
+// close must not be intra-word (a following alphanumeric means snake_case, not a
+// delimiter), so keep scanning past such runs; -1 when there is no valid close.
+function mdFindClose(s, marker, from, underscore) {
+  let j = from;
+  while (true) {
+    const k = s.indexOf(marker, j);
+    if (k < 0) return -1;
+    if (!underscore || !mdIsWordChar(s[k + marker.length])) return k;
+    j = k + marker.length;
+  }
+}
+function mdInline(text) {
+  const s = String(text == null ? "" : text);
+  const nodes = [];
+  let buf = "";
+  const flush = () => { if (buf) { nodes.push(document.createTextNode(buf)); buf = ""; } };
+  let i = 0;
+  while (i < s.length) {
+    const ch = s[i];
+    // Backslash escape: the next char is emitted literally, never as a delimiter.
+    if (ch === "\\" && i + 1 < s.length) { buf += s[i + 1]; i += 2; continue; }
+    // Inline code span — verbatim, no nested inline parsing.
+    if (ch === MD_BACKTICK) {
+      const end = s.indexOf(MD_BACKTICK, i + 1);
+      if (end > i) { flush(); nodes.push(el("code", { class: "pc-md-code" }, s.slice(i + 1, end))); i = end + 1; continue; }
+    }
+    // Strong (** or __). Underscore only when it opens on a word boundary so an
+    // identifier like a__b doesn't get mangled into emphasis.
+    if ((ch === "*" || ch === "_") && s[i + 1] === ch) {
+      const underscore = ch === "_";
+      if (!underscore || !mdIsWordChar(s[i - 1])) {
+        const marker = ch + ch;
+        const end = mdFindClose(s, marker, i + 2, underscore);
+        if (end > i + 1) { flush(); nodes.push(el("strong", {}, ...mdInline(s.slice(i + 2, end)))); i = end + 2; continue; }
+      }
+    }
+    // Emphasis (* or _), same word-boundary guard for underscore.
+    if (ch === "*" || ch === "_") {
+      const underscore = ch === "_";
+      if (!underscore || !mdIsWordChar(s[i - 1])) {
+        const end = mdFindClose(s, ch, i + 1, underscore);
+        if (end > i + 1) { flush(); nodes.push(el("em", {}, ...mdInline(s.slice(i + 1, end)))); i = end + 1; continue; }
+      }
+    }
+    // Link [label](href): href sanitised; an unsafe scheme drops to the label text.
+    if (ch === "[") {
+      const close = s.indexOf("]", i + 1);
+      if (close > i && s[close + 1] === "(") {
+        const paren = s.indexOf(")", close + 2);
+        if (paren > close) {
+          const href = mdSafeHref(s.slice(close + 2, paren));
+          const label = mdInline(s.slice(i + 1, close));
+          flush();
+          if (href) nodes.push(el("a", { href: href, target: "_blank", rel: "noopener noreferrer" }, ...label));
+          else for (const l of label) nodes.push(l);
+          i = paren + 1; continue;
+        }
+      }
+    }
+    buf += ch; i++;
+  }
+  flush();
+  return nodes;
+}
+// Regexes that classify a block-opening line; shared by the block loop and the
+// paragraph terminator so the two can't disagree on where a paragraph ends.
+const MD_HEADING = /^(#{1,6})\s+(.*)$/;
+const MD_QUOTE = /^>\s?/;
+const MD_UL = /^[-*+]\s+/;
+const MD_OL = /^\d+[.)]\s+/;
+const MD_HR = /^([-*_])(?:\s*\1){2,}\s*$/;
+function mdBlockStart(t) {
+  return t.slice(0, 3) === MD_BACKTICK + MD_BACKTICK + MD_BACKTICK
+    || MD_HEADING.test(t) || MD_QUOTE.test(t) || MD_UL.test(t) || MD_OL.test(t) || MD_HR.test(t);
+}
+// Parse a markdown string into an array of block-level DOM nodes.
+function mdToNodes(src) {
+  const out = [];
+  const fence = MD_BACKTICK + MD_BACKTICK + MD_BACKTICK;
+  const lines = String(src == null ? "" : src).replace(/\r\n?/g, "\n").split("\n");
+  let i = 0;
+  while (i < lines.length) {
+    const t = lines[i].trim();
+    if (t === "") { i++; continue; }
+    // Fenced code block — content is verbatim (no inline parsing).
+    if (t.slice(0, 3) === fence) {
+      const body = [];
+      i++;
+      while (i < lines.length && lines[i].trim().slice(0, 3) !== fence) { body.push(lines[i]); i++; }
+      if (i < lines.length) i++; // consume the closing fence
+      out.push(el("pre", { class: "pc-md-pre" }, el("code", {}, body.join("\n"))));
+      continue;
+    }
+    // Thematic break (checked before lists so "***"/"---" isn't read as a bullet).
+    if (MD_HR.test(t)) { out.push(el("hr", { class: "pc-md-hr" })); i++; continue; }
+    // ATX heading.
+    const h = MD_HEADING.exec(t);
+    if (h) { out.push(el("h" + h[1].length, { class: "pc-md-h" }, ...mdInline(h[2].trim()))); i++; continue; }
+    // Blockquote — strip one '>' per line and re-parse the inner block(s).
+    if (MD_QUOTE.test(t)) {
+      const inner = [];
+      while (i < lines.length && MD_QUOTE.test(lines[i].trim())) { inner.push(lines[i].trim().replace(MD_QUOTE, "")); i++; }
+      const bq = el("blockquote", { class: "pc-md-quote" });
+      for (const b of mdToNodes(inner.join("\n"))) bq.append(b);
+      out.push(bq); continue;
+    }
+    // Unordered list.
+    if (MD_UL.test(t)) {
+      const ul = el("ul", { class: "pc-md-list" });
+      while (i < lines.length && MD_UL.test(lines[i].trim())) {
+        ul.append(el("li", {}, ...mdInline(lines[i].trim().replace(MD_UL, ""))));
+        i++;
+      }
+      out.push(ul); continue;
+    }
+    // Ordered list.
+    if (MD_OL.test(t)) {
+      const ol = el("ol", { class: "pc-md-list" });
+      while (i < lines.length && MD_OL.test(lines[i].trim())) {
+        ol.append(el("li", {}, ...mdInline(lines[i].trim().replace(MD_OL, ""))));
+        i++;
+      }
+      out.push(ol); continue;
+    }
+    // Paragraph — soft-wrapped lines joined with a space until a blank line or the
+    // next block opener.
+    const para = [];
+    while (i < lines.length) {
+      const lt = lines[i].trim();
+      if (lt === "" || mdBlockStart(lt)) break;
+      para.push(lt); i++;
+    }
+    out.push(el("p", { class: "pc-md-p" }, ...mdInline(para.join(" "))));
+  }
+  return out;
+}
+
+// A data-bound prose/markdown list (#274). Binds a datasource like dataGrid
+// (props.data = { source, table, orderBy, filter }) but renders each row as a
+// stacked prose block — a small header template (props.header, e.g.
+// "Round {{round}} · {{approved}}") over one body field (props.body) rendered as
+// sanitised markdown at a comfortable measure (props.measure ch, ~66 default).
+// This is the primitive for narrative records (plan-review findings, coordination
+// notes, escalation bodies) that read as a document, not a squeezed table cell.
+// It inherits collapsible/defaultCollapsed for free via makeCollapsible (which
+// unwraps the <h2> title), and refreshMs polling + pc:refresh like dataGrid.
+function renderProse(node) {
+  const p = node.props || {};
+  const data = p.data || {};
+  const card = el("section", { class: "pc-card" });
+  if (p.title) card.append(el("h2", {}, p.title));
+  const listEl = el("div", { class: "pc-prose-list" });
+  card.append(listEl);
+  const headerTpl = typeof p.header === "string" ? p.header : null;
+  const bodyField = p.body;
+  // Clamp the reading measure to a sane range so a malformed schema can't set a
+  // 5000ch (full-bleed) or 2ch (one-word-per-line) body. ~66ch is the default.
+  let measure = Number(p.measure);
+  if (!Number.isFinite(measure)) measure = 66;
+  measure = Math.max(40, Math.min(100, Math.round(measure)));
+  const activeFilter = Array.isArray(data.filter) ? data.filter : [];
+
+  function itemFor(row) {
+    const item = el("article", { class: "pc-prose-item" });
+    if (headerTpl) item.append(el("div", { class: "pc-prose-head" }, interpTemplate(headerTpl, row)));
+    const bodyEl = el("div", { class: "pc-prose-body", style: "max-width:" + measure + "ch" });
+    // Own-property gate (matching interpTemplate) so a body field name that
+    // collides with a prototype key can't pick up prototype cruft.
+    const raw = bodyField != null && Object.prototype.hasOwnProperty.call(row, bodyField) && row[bodyField] != null
+      ? String(row[bodyField])
+      : "";
+    for (const b of mdToNodes(raw)) bodyEl.append(b);
+    item.append(bodyEl);
+    return item;
+  }
+
+  async function refresh() {
+    try {
+      // A param-scoped list ("show the selected entity's records") with no route
+      // param present renders nothing rather than a field=empty-string query.
+      const paramScoped = (activeFilter || []).some((f) => f && f.eqParam);
+      const { rows } = paramScoped && PARAM === ""
+        ? { rows: [] }
+        : await getJSON(dataUrl(data.source, data.table, activeFilter, data.orderBy));
+      listEl.replaceChildren();
+      if (!rows.length) { listEl.append(el("p", { class: "pc-prose-empty" }, p.empty || "No records")); return; }
+      for (const row of rows) listEl.append(itemFor(row));
+    } catch (e) {
+      listEl.replaceChildren(el("p", { class: "pc-msg err" }, String((e && e.message) || e)));
+    }
+  }
+  document.addEventListener("pc:refresh", refresh);
+  disposers.push(() => document.removeEventListener("pc:refresh", refresh));
+  if (p.refreshMs && p.refreshMs > 0) {
+    const timer = setInterval(refresh, p.refreshMs);
+    disposers.push(() => clearInterval(timer));
+  }
+  refresh();
+  return card;
+}
+
 function renderDataGrid(node) {
   const p = node.props;
   const card = el("section", { class: "pc-card" });
@@ -1755,18 +2084,6 @@ function renderDataGrid(node) {
     return v == null ? null : String(v);
   };
 
-  function dataUrl(source, tbl, filters, order) {
-    let u = "/app/data/" + encodeURIComponent(source) + "/" + encodeURIComponent(tbl);
-    const qs = [];
-    for (const f of filters || []) {
-      if (Array.isArray(f.in)) qs.push("where=" + encodeURIComponent(f.field + ":in:" + f.in.join(",")));
-      else if (f.eqParam) qs.push("where=" + encodeURIComponent(f.field + ":" + PARAM));
-      else qs.push("where=" + encodeURIComponent(f.field + ":" + f.eq));
-    }
-    if (order && order.field) qs.push("order=" + encodeURIComponent(order.field + ":" + (order.dir || "asc")));
-    return qs.length ? u + "?" + qs.join("&") : u;
-  }
-
   async function fireAction(action, row) {
     // Route-driven row action: POST the action's body template (default {})
     // to its route path, with {{row.KEY}} tokens resolved from this row.
@@ -1778,14 +2095,18 @@ function renderDataGrid(node) {
     const b = el("button", { class: "pc-btn pc-btn-sm" }, ra.label);
     b.addEventListener("click", async (ev) => {
       ev.stopPropagation();
-      if (ra.confirm && !confirm(ra.confirm)) return;
+      // In-DOM confirm/error (openModal) instead of native confirm()/alert():
+      // a sandboxed iframe without allow-modals makes native confirm() return
+      // false and alert() a no-op, so every confirm-guarded action silently
+      // dead-ended and its errors vanished (#276).
+      if (ra.confirm && !(await confirmModal(ra.confirm))) return;
       b.disabled = true;
       try {
         await fireAction(ra.action, row);
         document.dispatchEvent(new CustomEvent("pc:refresh"));
       } catch (e) {
         b.disabled = false;
-        alert(String(e.message || e));
+        alertModal(String(e.message || e));
       }
     });
     return b;
@@ -2172,7 +2493,7 @@ function renderNav(node) {
   return nav;
 }
 
-const RENDERERS = { text: renderText, actionForm: renderActionForm, dataGrid: renderDataGrid, nav: renderNav, button: renderButton };
+const RENDERERS = { text: renderText, actionForm: renderActionForm, dataGrid: renderDataGrid, prose: renderProse, nav: renderNav, button: renderButton };
 
 // Durable per-node UI state. localStorage is keyed by the home page id + node
 // id so two grids on the same page (or the same grid across pages) don't clash,

package/dist/runtime/engine/nanosdk.d.ts

@@ -1,4 +1,4 @@
-import type { EngineClient, FormSchema, JobHandler, ProcessInstanceSnapshot, ProcessInstanceState, UserTaskState, UserTaskSummary, WorkerSubscription } from "../core/host.ts";
+import type { EngineClient, FormSchema, JobHandler, ProcessInstanceSnapshot, ProcessInstanceState, UserTaskState, UserTaskSummary, UserTaskFilter, WorkerSubscription } from "../core/host.ts";
 import type { EngineSdkClient } from "./sdk.ts";
 /** Coerce an engine response's process-instance key to a non-empty string, or
  * throw — a missing key means a malformed/partial response, not a real instance. */
@@ -136,12 +136,13 @@ export declare class SdkEngineClient implements EngineClient {
         correlationKey?: string;
         variables?: Record<string, unknown>;
     }): Promise<void>;
-    searchUserTasks(filter?: {
-        processInstanceKey?: string;
-        assignee?: string;
-        candidateGroup?: string;
+    searchUserTasks(filter?: UserTaskFilter & {
         state?: UserTaskState;
     }): Promise<UserTaskSummary[]>;
+    /** The open (answerable) user tasks — `searchUserTasks` pinned to `state: "CREATED"`.
+     *  The single safe accessor for reconcile/affordance paths (see `EngineClient.openUserTasks`);
+     *  derives from `searchUserTasks` so the two cannot drift. */
+    openUserTasks(filter?: UserTaskFilter): Promise<UserTaskSummary[]>;
     getForm(input: {
         formKey?: string;
         formId?: string;

package/dist/runtime/engine/nanosdk.js

@@ -127,6 +127,12 @@ export class SdkEngineClient {
                 }];
         });
     }
+    /** The open (answerable) user tasks — `searchUserTasks` pinned to `state: "CREATED"`.
+     *  The single safe accessor for reconcile/affordance paths (see `EngineClient.openUserTasks`);
+     *  derives from `searchUserTasks` so the two cannot drift. */
+    openUserTasks(filter) {
+        return this.searchUserTasks({ ...filter, state: "CREATED" });
+    }
     async getForm(input) {
         // The engine addresses deployed forms by key (`GET /forms/{formKey}`). A user task's
         // `formKey` is the engine's resolution of its `formId` linkage to the latest deployed

package/dist/runtime/index.d.ts

@@ -8,7 +8,7 @@ export { bindModeToHost, expandEnv, expandEnvString, isBindMode, loadManifest, p
 export type { ActionDecl, AppManifest, BindMode, ChatSurface, DataSource, DomainField, DomainType, LlmBinding, NetworkConfig, PagesSurface, Surfaces, TaskInboxSurface, Trigger, Worker, } from "./core/manifest.ts";
 export { collectManifestIssues, ManifestValidationError, validateManifest, } from "./core/validate.ts";
 export type { ValidationIssue } from "./core/validate.ts";
-export type { EngineClient, EngineJob, FormSchema, HostContext, HttpHandler, HttpRequest, HttpResponse, HttpServer, JobHandler, ProcessInstanceSnapshot, ProcessInstanceState, SqliteDb, UserTaskState, UserTaskSummary, WatchHandle, WorkerSubscription, } from "./core/host.ts";
+export type { EngineClient, EngineJob, FormSchema, HostContext, HttpHandler, HttpRequest, HttpResponse, HttpServer, JobHandler, ProcessInstanceSnapshot, ProcessInstanceState, SqliteDb, UserTaskState, UserTaskSummary, UserTaskFilter, WatchHandle, WorkerSubscription, } from "./core/host.ts";
 export { buildFormSchema, parseFormSchema, pickFormLinkage, presentFormIdentifier, resolveFormIdentifier, } from "./core/form-contract.ts";
 export type { AppApi, Mounted, RuntimeContext } from "./core/context.ts";
 export { createLogger } from "./core/logger.ts";

package/package.json

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