@nanobpm/urban 0.47.0 → 0.49.0

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

@@ -1,9 +1,22 @@
-// deploy — resolve the manifest `models` patterns and deploy the resources to the engine,
-// substituting any `{{name}}` templates into each resource first (see templates.ts).
+// deploy — resolve the app's deployable resources and send them to the engine.
+//
+// Resources are found by ONE of two paths:
+//   1. Convention (the default, ADR 0062): when the manifest declares no `models`, deployables are
+//      discovered by walking `resources/` — shallow, one level deep. `resources/` is deploy-only:
+//      everything under it (and nothing outside it) is deployed. Docs (`docs/`, `AGENTS.md`,
+//      top-level `*.md`) live outside `resources/` and are never swept in.
+//   2. Explicit override: when the manifest declares `models` globs, those are used exactly (the
+//      convention walk is skipped) — the escape hatch for a non-convention layout.
+//
+// Either way the deploy dedupe key is the resource's basename (filename only), so a basename
+// collision — two files with the same name in different directories — would silently clobber one
+// resource with another at the engine. We detect that up front and fail loudly instead.
 
 import type { RuntimeContext } from "../context.ts";
-import { expandPatterns } from "../glob.ts";
-import { applyTemplates, resolveTemplates } from "./templates.ts";
+import { discoverResources, expandPatterns } from "../glob.ts";
+
+/** The convention directory: deploy-only, walked one level deep when no `models` are declared. */
+export const RESOURCES_DIR = "resources";
 
 function contentTypeFor(path: string): string {
   if (path.endsWith(".bpmn")) return "text/xml";
@@ -17,47 +30,66 @@ function baseName(path: string): string {
   return i >= 0 ? path.slice(i + 1) : path;
 }
 
-/** Deploy all processes, decisions and forms declared under `models`. Each resource has its
- *  `{{name}}` placeholders substituted (manifest `models.templates`, then the programmatic
- *  `ctx.templates`, the latter winning) before it is sent to the engine. */
+/** Fail loudly when two resolved files share a basename (the deploy dedupe key), naming the
+ *  colliding paths so the author can rename or relocate one. */
+function assertNoBasenameCollisions(files: string[]): void {
+  const byName = new Map<string, string[]>();
+  for (const path of files) {
+    const name = baseName(path);
+    const list = byName.get(name);
+    if (list) list.push(path);
+    else byName.set(name, [path]);
+  }
+  const collisions = [...byName.entries()].filter(([, paths]) => paths.length > 1);
+  if (collisions.length === 0) return;
+  const detail = collisions
+    .map(([name, paths]) => `  ${name}: ${paths.slice().sort().join(", ")}`)
+    .join("\n");
+  throw new Error(
+    "deploy: basename collision — resources are deployed keyed by filename, so two files with " +
+      `the same name would clobber each other. Rename or relocate one of:\n${detail}`,
+  );
+}
+
+/**
+ * Deploy the app's processes, decisions and forms.
+ *
+ * With no manifest `models`, deployables are discovered by convention under `resources/` (shallow,
+ * one level deep). With `models` globs declared, those are used verbatim. Basename collisions are a
+ * hard error in either mode.
+ */
 export async function deployModels(ctx: RuntimeContext): Promise<{ deployed: number; files: string[] }> {
-  const models = ctx.manifest.models ?? {};
+  const models = ctx.manifest.models;
   const patterns = [
-    ...(models.processes ?? []),
-    ...(models.decisions ?? []),
-    ...(models.forms ?? []),
+    ...(models?.processes ?? []),
+    ...(models?.decisions ?? []),
+    ...(models?.forms ?? []),
   ];
-  const files = await expandPatterns(ctx.host, ctx.root, patterns);
+  // Convention is keyed off the *absence* of the `models` block, not an empty pattern set: a
+  // declared `models` (even one resolving to zero files) is an explicit override that must NOT
+  // silently fall back to the `resources/` walk (ADR 0062: "no `models` block → convention;
+  // `models` present → exact override").
+  const byConvention = models === undefined;
+  const files = byConvention
+    ? await discoverResources(ctx.host, ctx.root, RESOURCES_DIR)
+    : await expandPatterns(ctx.host, ctx.root, patterns);
   if (files.length === 0) {
-    ctx.host.log("info", "deploy: no model files matched", { patterns });
+    if (byConvention) {
+      ctx.host.log("info", "deploy: no resources found by convention", { dir: RESOURCES_DIR });
+    } else {
+      ctx.host.log("info", "deploy: no model files matched", { patterns });
+    }
     return { deployed: 0, files: [] };
   }
-  // Resolve templates once (manifest globs/dirs, then the programmatic deploy option). An empty
-  // map makes substitution a no-op, so apps that use no templates are unaffected.
-  const templates = await resolveTemplates(ctx.host, ctx.root, [models.templates, ctx.templates]);
-  const hasTemplates = Object.keys(templates).length > 0;
+  assertNoBasenameCollisions(files);
   const resources = await Promise.all(
-    files.map(async (path) => {
-      const contentType = contentTypeFor(path);
-      let content = await ctx.host.readTextFile(path);
-      // Only substitute into the model content types we know how to escape (XML for .bpmn/.dmn,
-      // JSON for .form). Unknown extensions map to application/octet-stream; running the default
-      // XML escaper over them could deterministically corrupt a non-XML/JSON resource that a
-      // manifest pattern matched by accident, so leave those files untouched.
-      if (hasTemplates && contentType !== "application/octet-stream") {
-        const applied = applyTemplates(content, contentType, templates);
-        content = applied.content;
-        if (applied.unresolved.length > 0) {
-          ctx.host.log("warn", "deploy: unresolved template placeholders", {
-            file: path,
-            unresolved: applied.unresolved,
-          });
-        }
-      }
-      return { name: baseName(path), content, contentType };
-    }),
+    files.map(async (path) => ({
+      name: baseName(path),
+      content: await ctx.host.readTextFile(path),
+      contentType: contentTypeFor(path),
+    })),
   );
   const { deployed } = await ctx.engine.deployResources(resources);
-  ctx.host.log("info", "deploy: models deployed", { deployed, files });
+  ctx.host.log("info", "deploy: resources deployed", { deployed, files, byConvention });
   return { deployed, files };
 }

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"),
+    getForm: notUsed("getForm"),
     completeUserTask: notUsed("completeUserTask"),
     registerWorker: notUsed("registerWorker"),
     close: notUsed("close"),
@@ -285,6 +286,95 @@ test("without statusField/activeStatuses, polls every row", async () => {
   await h.close();
 });
 
+test("terminalStatuses: reconciles a TERMINATED row in an un-enumerated non-terminal status (the allow-list regression)", async () => {
+  // The row's status ("awaiting_operator") is listed in NEITHER activeStatuses nor terminalStatuses
+  // — the exact drift an allow-list misses. A fail-open terminalStatuses selector still polls it.
+  const { engine, queries } = fakeEngine({ pi1: "TERMINATED" });
+  const h = await withHarness(engine, PLANS_DDL, async (t) => {
+    await t.insert({ plan_key: "p1", process_key: "pi1", status: "awaiting_operator", note: "hi" });
+  });
+  const sched = fakeScheduler();
+  const binding = planBinding({ activeStatuses: undefined, terminalStatuses: ["abandoned"] });
+  const handle = mount(h, [binding], sched);
+  await sched.advance(1000);
+  assert.deepEqual(queries, [["pi1"]]); // it WAS polled despite not being in any enumerated list
+  const row = await h.table.get("pi1");
+  assert.equal(row?.status, "abandoned"); // …and reconciled
+  await handle.stop();
+  await h.close();
+});
+
+test("terminalStatuses: a row already in a terminal status is not polled", async () => {
+  const { engine, queries } = fakeEngine({ pi1: "TERMINATED", pi2: "TERMINATED" });
+  const h = await withHarness(engine, PLANS_DDL, async (t) => {
+    await t.insert({ plan_key: "p1", process_key: "pi1", status: "awaiting_operator", note: null });
+    await t.insert({ plan_key: "p2", process_key: "pi2", status: "abandoned", note: null }); // terminal
+  });
+  const sched = fakeScheduler();
+  const binding = planBinding({ activeStatuses: undefined, terminalStatuses: ["abandoned"] });
+  const handle = mount(h, [binding], sched);
+  await sched.advance(1000);
+  assert.deepEqual(queries, [["pi1"]]); // pi2 was already terminal, excluded from the poll
+  await handle.stop();
+  await h.close();
+});
+
+test("terminalStatuses wins when a binding somehow declares both selectors (fail-open)", async () => {
+  // Validation rejects declaring both, but a hand-built binding must still behave predictably:
+  // terminalStatuses (the fail-open selector) takes precedence over activeStatuses.
+  const { engine, queries } = fakeEngine({ pi1: "TERMINATED" });
+  const h = await withHarness(engine, PLANS_DDL, async (t) => {
+    // status is NOT in activeStatuses — an allow-list would skip it — but IS non-terminal.
+    await t.insert({ plan_key: "p1", process_key: "pi1", status: "awaiting_operator", note: null });
+  });
+  const sched = fakeScheduler();
+  const binding = planBinding({ activeStatuses: ["planning"], terminalStatuses: ["abandoned"] });
+  const handle = mount(h, [binding], sched);
+  await sched.advance(1000);
+  assert.deepEqual(queries, [["pi1"]]); // polled via the terminalStatuses selector
+  assert.equal((await h.table.get("pi1"))?.status, "abandoned");
+  await handle.stop();
+  await h.close();
+});
+
+test("a malformed (non-array) terminalStatuses degrades to fail-open poll-all, not a Set-of-characters filter", async () => {
+  // A hand-built/JSON binding could carry a bare string. The buggy path (`new Set("ab")`) would
+  // filter rows by whether their status is one of those *characters* — silently dropping rows.
+  // The shared `isConfiguredStatusSelector` gate makes a malformed selector fall through to the
+  // fail-open poll-all path instead. Build the invalid fixture via JSON.parse (no `as` cast).
+  const { engine, queries } = fakeEngine({ pi1: "TERMINATED", pi2: "TERMINATED" });
+  const h = await withHarness(engine, PLANS_DDL, async (t) => {
+    // Both statuses are single characters that appear in "abandoned" — the buggy Set-of-chars
+    // filter would exclude them, polling nothing; the fail-open path polls both.
+    await t.insert({ plan_key: "p1", process_key: "pi1", status: "a", note: null });
+    await t.insert({ plan_key: "p2", process_key: "pi2", status: "b", note: null });
+  });
+  const malformed = JSON.parse('{"terminalStatuses":"abandoned","activeStatuses":null}');
+  const sched = fakeScheduler();
+  const binding = planBinding(malformed);
+  const handle = mount(h, [binding], sched);
+  await sched.advance(1000);
+  assert.deepEqual(queries[0]?.sort(), ["pi1", "pi2"]); // fail-open: every row polled
+  await handle.stop();
+  await h.close();
+});
+
+test("a malformed (non-array) activeStatuses degrades to fail-open poll-all instead of crashing .map", async () => {
+  const { engine, queries } = fakeEngine({ pi1: "TERMINATED", pi2: "TERMINATED" });
+  const h = await withHarness(engine, PLANS_DDL, async (t) => {
+    await t.insert({ plan_key: "p1", process_key: "pi1", status: "planning", note: null });
+    await t.insert({ plan_key: "p2", process_key: "pi2", status: "dispatched", note: null });
+  });
+  const malformed = JSON.parse('{"activeStatuses":"planning","terminalStatuses":null}');
+  const sched = fakeScheduler();
+  const binding = planBinding(malformed);
+  const handle = mount(h, [binding], sched);
+  await sched.advance(1000);
+  assert.deepEqual(queries[0]?.sort(), ["pi1", "pi2"]); // no crash; fail-open poll-all
+  await handle.stop();
+  await h.close();
+});
+
 test("defaults pollMs when the binding omits it", async () => {
   const { engine, queries } = fakeEngine({ pi1: "ACTIVE" });
   const h = await withHarness(engine, PLANS_DDL, async (t) => {

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

@@ -14,7 +14,7 @@
 // row). The poll is driven through the shared `SchedulerDeps` seam so tests are deterministic.
 
 import type { AppApi, Mounted, RuntimeContext } from "../context.ts";
-import type { InstanceTracking } from "../manifest.ts";
+import { type InstanceTracking, isConfiguredStatusSelector } from "../manifest.ts";
 import { defaultScheduler, MAX_TIMER_DELAY_MS, type SchedulerDeps } from "./scheduler.ts";
 
 /** Default poll interval when a binding does not set `pollMs`. */
@@ -65,13 +65,26 @@ async function reconcileOnce(
 ): Promise<{ scanned: number; reconciled: number }> {
   const table = api.data.table<Row>(binding.table, binding.keyField);
 
-  // Select the rows worth polling. With a statusField + activeStatuses, only rows in an
-  // active status are candidates, so a row already in a terminal status is skipped; without
-  // them every row is polled and a terminal instance's row is idempotently re-patched (the
-  // engine query returns only TERMINATED instances and the patch is a no-op once applied).
+  // Select the rows worth polling. Three modes, in precedence order:
+  //  - `terminalStatuses` (fail-open exclusion): poll every row whose `statusField` is NOT
+  //    a terminal value. A newly-added non-terminal status is polled by default, so it can't
+  //    silently fall out of reconciliation; only already-terminal rows are excluded (bounded).
+  //  - `activeStatuses` (fail-closed allow-list): poll only rows in an enumerated active status.
+  //  - neither: poll every row; a terminal instance's row is idempotently re-patched (the engine
+  //    query returns only TERMINATED instances and the patch is a no-op once applied).
+  // `terminalStatuses` and `activeStatuses` are mutually exclusive per binding (validation rejects
+  // both); if both are somehow present, `terminalStatuses` wins (the fail-open selector). Each
+  // selector is gated through the shared `isConfiguredStatusSelector` predicate (a non-empty array
+  // of non-empty strings) — the same one validation uses — so a malformed value (a bare string, an
+  // empty array) degrades to the fail-open poll-all path here instead of `new Set("abandoned")`
+  // silently filtering by character, or a non-array crashing `activeStatuses.map(...)`.
   let candidates: Row[];
   const statusField = binding.statusField;
-  if (statusField && binding.activeStatuses && binding.activeStatuses.length > 0) {
+  if (statusField && isConfiguredStatusSelector(binding.terminalStatuses)) {
+    const terminal = new Set(binding.terminalStatuses);
+    const all = await table.all();
+    candidates = all.filter((row) => !terminal.has(String(row[statusField])));
+  } else if (statusField && isConfiguredStatusSelector(binding.activeStatuses)) {
     const perStatus = await Promise.all(
       binding.activeStatuses.map((s): Promise<Row[]> => table.find({ [statusField]: s })),
     );

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

@@ -40,6 +40,7 @@ function fakeEngine(): { engine: EngineClient; calls: FakeEngineCalls } {
       calls.messages.push(input);
     },
     async searchUserTasks() { return []; },
+    async getForm() { return null; },
     async completeUserTask() {},
     async searchProcessInstances() { return []; },
     async registerWorker(jobType) { return { jobType, unsubscribe: async () => {} }; },
@@ -337,12 +338,37 @@ test("renderer wires a column's badge to a tone-classed pill shown only when pre
   // (default danger), the label defaults to "1", and the full field text becomes
   // the tooltip.
   assert.match(js, /if\s*\(col\.badge\)/);
-  assert.match(js, /text\.trim\(\)\s*===\s*""/);
+  assert.match(js, /rawText\.trim\(\)\s*===\s*""/);
   assert.match(js, /t\s*===\s*"warn"\s*\|\|\s*t\s*===\s*"ok"\s*\|\|\s*t\s*===\s*"info"\s*\?\s*t\s*:\s*"danger"/);
   assert.match(js, /col\.badge\.label\s*==\s*null\s*\?\s*"1"/);
   assert.match(js, /class:\s*"pc-badge pc-badge-"\s*\+\s*tone/);
-  assert.match(js, /title:\s*text/);
-  assert.match(js, /"aria-label":\s*text/);
+  assert.match(js, /title:\s*rawText/);
+  assert.match(js, /"aria-label":\s*rawText/);
+});
+
+test("renderer interpolates a column's per-cell template into DOM text (#214)", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // A column declaring `template: "{{a}}/{{b}}"` renders one cell by splicing the
+  // named row fields into a string, coerced to text and set only as DOM text
+  // (never markup). Guard the whole shape so the primitive can't silently
+  // regress: interpTemplate exists, replaces {{field}} tokens via a function
+  // replacement (so a "$"-bearing value can't be reinterpreted as a replacement
+  // pattern), coerces null/undefined to "" (unknown tokens render blank, no
+  // throw), and gridCell prefers a string col.template over the raw field value
+  // for the visible text while the badge stays keyed to the raw field.
+  assert.match(js, /function interpTemplate\(tpl, row\)/);
+  assert.match(js, /replace\(\/\\\{\\\{\(\[\^\{\}\]\+\)\\\}\\\}\/g,/);
+  assert.match(js, /const key = name\.trim\(\);/);
+  // Unknown tokens (no such own field) render blank and, crucially, an inherited
+  // Object.prototype key (toString, constructor, …) counts as unknown rather than
+  // resolving to prototype cruft — guard the own-property gate explicitly.
+  assert.match(js, /Object\.prototype\.hasOwnProperty\.call\(row, key\) \? row\[key\] : null/);
+  assert.match(js, /return v == null \? "" : String\(v\);/);
+  // gridCell keeps the raw single-field value separate (drives the badge gate)
+  // and lets a string template win for the rendered text.
+  assert.match(js, /const rawText = row\[col\.field\] == null \? "" : String\(row\[col\.field\]\);/);
+  assert.match(js, /const text = typeof col\.template === "string" \? interpTemplate\(col\.template, row\) : rawText;/);
 });
 
 test("renderer wires a column's processExplorer link to the console explorer", async () => {
@@ -576,6 +602,48 @@ test("renderer makes collapsible nodes persist their state across sessions", asy
   assert.match(js, /container\.append\(header, body\);\s*return container;/);
 });
 
+test("renderer surfaces a live row-count badge on a dataGrid's collapsible header (showCount)", async () => {
+  // A dataGrid opting in via `showCount:true` renders a count pill that reflects the
+  // currently-fetched, filtered (active-tab) row set, updates on every refresh (the
+  // refreshMs poll and pc:refresh), and — because makeCollapsible re-homes it into the
+  // collapse header — stays visible while the section is collapsed. Omitting showCount
+  // is a no-op (backward-compatible).
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // Opt-in badge, created only when showCount is set; class-tagged for re-homing + CSS.
+  assert.match(js, /const countBadge = p\.showCount \? el\("span", \{ class: "pc-badge pc-count-badge"/);
+  // The badge's accessible name carries the count (kept in sync on refresh) rather than a
+  // bare aria-label that would override the number screen readers need to announce.
+  assert.match(js, /"aria-label": rowCountLabel\(0\)/);
+  assert.match(js, /function rowCountLabel\(n\) \{ return n \+ \(n === 1 \? " row" : " rows"\); \}/);
+  // The <h2> (title and/or badge) renders when either the title or the badge is present.
+  assert.match(js, /if \(p\.title \|\| countBadge\) \{/);
+  // The badge is appended to the <h2>; the " " spacer is inserted only when a title is
+  // present, so a badge-only header can't render (or store) a stray leading space.
+  assert.match(js, /if \(countBadge\) \{ if \(p\.title\) h2\.append\(" "\); h2\.append\(countBadge\); \}/);
+  // Every refresh rewrites the count from the fetched, filtered row set (poll + pc:refresh),
+  // keeping both the visible text and the accessible label in sync.
+  assert.match(js, /if \(countBadge\) \{ countBadge\.textContent = String\(rows\.length\); countBadge\.setAttribute\("aria-label", rowCountLabel\(rows\.length\)\); \}/);
+  // makeCollapsible lifts the badge out of the <h2> before deriving the title (so the
+  // count can't leak into the label) and re-homes it in the header so it stays visible
+  // while collapsed (only the body is hidden).
+  assert.match(js, /const countBadge = h2 && h2\.querySelector \? h2\.querySelector\("\.pc-count-badge"\) : null;/);
+  assert.match(js, /if \(countBadge\) countBadge\.remove\(\);/);
+  assert.match(js, /if \(countBadge\) header\.append\(countBadge\);/);
+  // The derived collapse-header title is trimmed so a badge-only <h2> (no title) can't
+  // leave a lone whitespace node as the label (or leak whitespace into the storage key).
+  assert.match(js, /const titleText = props\.title \|\| \(h2 \? h2\.textContent\.trim\(\) : ""\) \|\| "Section";/);
+});
+
+test("the shell styles the row-count pill as a neutral count distinct from status badges", async () => {
+  const res = await dispatch("GET", "/");
+  const html = res.body ?? "";
+  const rule = (html.match(/\.pc-count-badge\s*\{[^}]*\}/) ?? [""])[0];
+  assert.ok(rule, ".pc-count-badge rule must be present");
+  assert.match(rule, /background:var\(--nano-inset\)/);
+  assert.match(rule, /color:var\(--nano-text\)/);
+});
+
 test("GET /app/pages/<id> returns the page json, 404 for unknown", async () => {
   const ok = await dispatch("GET", "/app/pages/home");
   assert.equal(ok.status, 200);

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

@@ -564,6 +564,9 @@ table.pc-grid th { font-weight:600; color:var(--nano-text-muted); }
 .pc-badge-warn { background:var(--nano-warn); color:#3a2a00; }
 .pc-badge-ok { background:var(--nano-ok); }
 .pc-badge-info { background:var(--nano-info); }
+/* Live row-count pill (dataGrid showCount): a subtle, neutral count distinct from
+   the coloured status badges, legible in the collapse header while collapsed. */
+.pc-count-badge { color:var(--nano-text); background:var(--nano-inset); border:1px solid var(--nano-edge); font-weight:600; }
 :root[data-appearance="light"] .pc-badge-warn { color:#fff; }
 @media (prefers-color-scheme: light) { :root:not([data-appearance]) .pc-badge-warn { color:#fff; } }
 .pc-child { margin:.6rem 0; }
@@ -838,6 +841,27 @@ function el(tag, attrs = {}, ...kids) {
 function interpParam(s) {
   return typeof s === "string" ? s.replace(/\{\{param\}\}/g, () => PARAM) : s;
 }
+
+// Interpolate {{field}} tokens in a column's per-cell template with values from
+// the row, coercing each to a string (null/undefined → ""). Like interpParam the
+// result is only ever set as DOM text (textContent via el()), so a substituted
+// row value cannot inject markup or attributes. A function replacement inserts
+// each value literally, so a "$"-bearing value can't be reinterpreted as a
+// replacement pattern. Unknown tokens (no such field) render empty rather than
+// throwing, matching interpParam. This is a dumb text formatter: no expressions,
+// arithmetic, or conditionals — just field splicing. Only the row's own
+// fields resolve (own-property gate, enumerable or not): an inherited
+// Object.prototype key (toString, constructor, …) counts as unknown and
+// renders "", so a token can't pick up prototype cruft instead of blank.
+function interpTemplate(tpl, row) {
+  return typeof tpl === "string"
+    ? tpl.replace(/\{\{([^{}]+)\}\}/g, (_m, name) => {
+        const key = name.trim();
+        const v = Object.prototype.hasOwnProperty.call(row, key) ? row[key] : null;
+        return v == null ? "" : String(v);
+      })
+    : tpl;
+}
 function renderText(node) {
   const v = node.props.variant;
   const cls = v === "heading" ? "pc-heading" : v === "sub" ? "pc-sub" : "pc-body";
@@ -1002,8 +1026,27 @@ function renderButton(node) {
 // host's own explorer view in place via the nano-navigate postMessage bridge
 // (a modified/middle click keeps the new-tab behavior). Shared by the top-level
 // grid and child grids.
+//
+// Cell TEXT (the 'text' local below): the visible string a cell renders. By
+// default it is the column's single 'field' value, but an optional
+// 'col.template' string wins: its {{field}} tokens are spliced from the row
+// (interpTemplate) into DOM text. A template lets one cell combine several
+// fields / add surrounding text (e.g. "{{current_wave}}/{{wave_count}}")
+// without denormalising a display column into the datasource. The template
+// drives the rendered text for the plain, linkField and link
+// (page/processExplorer) paths — a link's href still comes from its own
+// keyField/linkField, never the template. The 'badge' presence gate and its
+// tooltip stay keyed to the raw 'field' value (a badge shows a fixed glyph, not
+// the field text), so a template does not change badge behaviour. Sorting,
+// groupBy and orderBy also key off real fields, never the rendered template.
 function gridCell(col, row) {
-  const text = row[col.field] == null ? "" : String(row[col.field]);
+  // Raw single-field value: drives the badge presence gate + tooltip and any
+  // field-derived defaults. Kept separate from the (possibly templated) display
+  // text so a template never re-lights or blanks a badge.
+  const rawText = row[col.field] == null ? "" : String(row[col.field]);
+  // Visible text: a col.template (interpolated from the row) wins over the
+  // raw field value, else the field value is shown verbatim.
+  const text = typeof col.template === "string" ? interpTemplate(col.template, row) : rawText;
   // 1. badge — a compact status indicator. When the row's field value is
   //    non-empty (truthy after trimming) render a small circular badge (e.g. a
   //    red "1" dot flagging an incident) whose tooltip is the full field text;
@@ -1015,14 +1058,14 @@ function gridCell(col, row) {
   //    field text is also mirrored into aria-label so assistive tech announces
   //    the incident/status text (the visible "1" glyph alone is not meaningful).
   if (col.badge) {
-    if (text.trim() === "") return el("td", {});
+    if (rawText.trim() === "") return el("td", {});
     const t = col.badge.tone;
     const tone = t === "warn" || t === "ok" || t === "info" ? t : "danger";
     const label = col.badge.label == null ? "1" : String(col.badge.label);
     return el(
       "td",
       {},
-      el("span", { class: "pc-badge pc-badge-" + tone, title: text, "aria-label": text }, label),
+      el("span", { class: "pc-badge pc-badge-" + tone, title: rawText, "aria-label": rawText }, label),
     );
   }
   if (col.linkField) {
@@ -1226,10 +1269,25 @@ function renderActionForm(node) {
   return card;
 }
 
+// Accessible name for the row-count badge. The visible text is just a number, so an
+// aria-label would override it with a bare "row count" (the count — the important part —
+// is dropped). Instead name it "N row(s)" and keep it in sync with the text on refresh.
+// Single source of truth for both the initial render and every refresh below.
+function rowCountLabel(n) { return n + (n === 1 ? " row" : " rows"); }
+
 function renderDataGrid(node) {
   const p = node.props;
   const card = el("section", { class: "pc-card" });
-  if (p.title) card.append(el("h2", {}, p.title));
+  // Opt-in live row-count badge ("showCount"). Rendered inside the <h2> so a plain
+  // (non-collapsible) grid surfaces it beside the title; makeCollapsible re-homes it
+  // into the collapse header so it stays visible — and refresh-updated — while the
+  // section is collapsed. refresh() below rewrites its text on every poll/pc:refresh.
+  const countBadge = p.showCount ? el("span", { class: "pc-badge pc-count-badge", "aria-label": rowCountLabel(0) }, "0") : null;
+  if (p.title || countBadge) {
+    const h2 = el("h2", {}, p.title || "");
+    if (countBadge) { if (p.title) h2.append(" "); h2.append(countBadge); }
+    card.append(h2);
+  }
   const cols = p.columns || [];
   const tabs = p.tabs || [];
   const rowActions = p.rowActions || [];
@@ -1547,6 +1605,10 @@ function renderDataGrid(node) {
       const { rows } = paramScoped && PARAM === ""
         ? { rows: [] }
         : await getJSON(dataUrl(p.data.source, p.data.table, activeFilter, p.data.orderBy));
+      // Live row-count badge: reflect the currently-fetched, filtered (active-tab)
+      // set — exactly what the body renders — on every refresh (poll + pc:refresh),
+      // whether the section is expanded or collapsed.
+      if (countBadge) { countBadge.textContent = String(rows.length); countBadge.setAttribute("aria-label", rowCountLabel(rows.length)); }
       // Forget expansion / cached detail nodes for rows no longer present so the maps
       // don't grow without bound and a stale answer can't resurface on a key reuse.
       if (p.rowKey) {
@@ -1715,7 +1777,16 @@ function makeCollapsible(node, card) {
   const isCard = card.tagName === "SECTION";
   const container = isCard ? card : el("section", { class: "pc-card" });
   const h2 = isCard && card.querySelector ? card.querySelector("h2") : null;
-  const titleText = props.title || (h2 ? h2.textContent : "") || "Section";
+  // A dataGrid with "showCount" renders a live count badge inside its <h2>. Lift it
+  // out before deriving the title (so the count doesn't leak into the label text),
+  // then re-home it in the header alongside the title so it stays visible — and
+  // refresh-updated by the grid's own refresh() — while the section is collapsed.
+  const countBadge = h2 && h2.querySelector ? h2.querySelector(".pc-count-badge") : null;
+  if (countBadge) countBadge.remove();
+  // Trim the derived label: after the badge is lifted out, the leftover " " whitespace
+  // node from h2.append(" ", countBadge) would otherwise make a title-less section's
+  // header a lone space (and leak whitespace into the storage key). Fall back to "Section".
+  const titleText = props.title || (h2 ? h2.textContent.trim() : "") || "Section";
   if (h2) h2.remove();
   const body = el("div", { class: "pc-card-body" });
   if (isCard) {
@@ -1730,6 +1801,7 @@ function makeCollapsible(node, card) {
     chevron,
     el("span", { class: "pc-collapse-title" }, titleText),
   );
+  if (countBadge) header.append(countBadge);
   const storageKey = "pc:collapsed:" + CURRENT + ":" + (node.id || titleText);
   let collapsed = readCollapsed(storageKey, !!props.defaultCollapsed);
   function apply() {