@nanobpm/urban 0.59.0 → 0.61.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.59.0",
+	"version": "0.61.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/runtime.browser.js

@@ -1631,10 +1631,13 @@ function renderDataGrid(node) {
   }
 
   /** @param {Record<string, any>} row
+   * @param {any} formCfg the panel's own form config (top-level or child grid); a
+   *   missing/undefined form means this panel has no form — it must NOT fall back to
+   *   the top-level grid's form, or a child panel would render the parent's form.
    * @returns {HTMLElement|null}
    */
-  function detailForm(row) {
-    const f = detail.form;
+  function detailForm(row, formCfg) {
+    const f = formCfg;
     if (!f || !row[f.showWhenField]) return null;
     const box = el("div", { class: "pc-subform" });
     if (f.title) box.append(el("div", { class: "pc-subform-title" }, f.title));
@@ -1673,21 +1676,61 @@ function renderDataGrid(node) {
     const ccols = cg.columns || [];
     const croles = classifyColumns(ccols);
     const chasHidden = croles.indexOf("hidden") >= 0;
+    // Per-row expansion for child grids: a `detail` (alias `expandable`) block
+    // gives each child row a chevron that reveals the same detailPanel() content
+    // the top-level grid uses (link + fields + nested child grids + form). Rows are
+    // collapsed by default; `detail.defaultCollapsed`/`detail.collapsed` (default
+    // true) seeds the initial state, and — when the child grid declares a `rowKey`
+    // — the per-row collapse is persisted in localStorage keyed by page + node +
+    // parent rowKey + child rowKey, so it survives the top-level grid's refresh
+    // poll (which rebuilds this whole subtree) and a full reload, mirroring how
+    // groupBy group-collapse is persisted. Absent a `detail` block the child grid
+    // is byte-for-byte unchanged (backward compatible).
+    const cdetail = cg.detail || cg.expandable || null;
+    const chasExpand = cdetail != null;
+    const cextra = (cg.lazyField ? 1 : 0) + (chasExpand ? 1 : 0);
+    const cdefaultCollapsed = chasExpand
+      ? (cdetail.defaultCollapsed != null
+        ? !!cdetail.defaultCollapsed
+        : cdetail.collapsed != null
+          ? !!cdetail.collapsed
+          : true)
+      : true;
+    const cnodeId = node.id || p.title || "grid";
+    const cchildId = cg.node || cg.table || cg.title || "child";
+    // The parent-row discriminator is the value this child grid is queried by
+    // (row[cg.parentField]) — NOT the top-level grid's rowKey. That keeps per-row
+    // collapse state unique per parent row even when the parent grid declares no
+    // rowKey (rowKeyOf(row) would then be null and every parent row would collide
+    // under the literal "_"). When no parent discriminator is available there is no
+    // safe key, so persistence is disabled (ckeyBase null) instead of colliding.
+    const cparentKey = cg.parentField != null && row[cg.parentField] != null
+      ? String(row[cg.parentField]) : null;
+    const ckeyBase = cparentKey == null ? null
+      : "pc:collapsed:" + CURRENT + ":" + cnodeId + ":" + cchildId + ":" + cparentKey + ":r:";
+    /** @param {Record<string, any>} cr @returns {string|null} */
+    const crowKeyOf = (cr) => {
+      if (!cg.rowKey) return null;
+      const v = cr[cg.rowKey];
+      return v == null ? null : String(v);
+    };
     const cbody = el("tbody", {});
-    const ccolgroup = buildColgroup(ccols, cg.lazyField ? 1 : 0);
+    const ccolgroup = buildColgroup(ccols, cextra);
     const cthead = el("thead", {}, el("tr", {}, ...ccols.map((c) => el("th", {}, c.header || c.field)),
-      ...(cg.lazyField ? [el("th", {}, "")] : [])));
+      ...(cg.lazyField ? [el("th", {}, "")] : []),
+      ...(chasExpand ? [el("th", {}, "")] : [])));
     const ctable = ccolgroup
       ? el("table", { class: "pc-grid" }, ccolgroup, cthead, cbody)
       : el("table", { class: "pc-grid" }, cthead, cbody);
     wrap.append(ctable);
-    /** @type {any} */
-    var cspan;
+    // Compute the colspan eagerly (before the fetch) so BOTH the success path and
+    // the catch's error row have a valid, table-spanning colspan — if getJSON()
+    // throws, a lazily-assigned cspan would still be undefined here.
+    const cspan = String((ccols.length || 1) + cextra);
     try {
       /** @type {{ rows: Array<Record<string, any>> }} */
       const { rows } = await getJSON(dataUrl(cg.source || "app", cg.table,
         [{ field: cg.childField, eq: row[cg.parentField] }], cg.orderBy));
-      cspan = String((ccols.length || 1) + (cg.lazyField ? 1 : 0));
       if (!rows.length) {
         cbody.append(el("tr", {}, el("td", { colspan: cspan }, "None")));
       }
@@ -1709,6 +1752,33 @@ function renderDataGrid(node) {
           }
           cells.push(cell);
         }
+        // Per-row expander cell (trailing, after any lazyField cell): a chevron
+        // that reveals this row's detailPanel in a following full-width row. The
+        // panel is built lazily on first open (and eagerly when the row starts
+        // expanded), matching the top-level grid.
+        /** @type {any} */
+        let cdtr = null;
+        if (chasExpand) {
+          const crk = crowKeyOf(cr);
+          const cskey = ckeyBase && crk != null ? ckeyBase + crk : null;
+          const collapsed = cskey ? readCollapsed(cskey, cdefaultCollapsed) : cdefaultCollapsed;
+          const ctoggle = el("button", { class: "pc-btn pc-btn-sm pc-chevron" }, collapsed ? "▸" : "▾");
+          cells.push(el("td", { class: "pc-row-actions" }, ctoggle));
+          cdtr = el("tr", { hidden: collapsed ? "" : null }, el("td", { colspan: cspan }));
+          let built = false;
+          const build = () => {
+            if (!built) { built = true; cdtr.firstChild.append(detailPanel(cr, cdetail)); }
+          };
+          if (!collapsed) build();
+          ctoggle.addEventListener("click", /** @param {MouseEvent} ev */ (ev) => {
+            ev.stopPropagation();
+            const open = cdtr.hidden;
+            cdtr.hidden = !open;
+            ctoggle.textContent = open ? "▾" : "▸";
+            if (open) build();
+            if (cskey) writeCollapsed(cskey, !open);
+          });
+        }
         // Child grids classify columns into the same mobile roles (including
         // "hidden") as the top-level grid, so they need the same per-row "More"
         // toggle — without it a mobile:{priority:"hidden"} child column would be
@@ -1716,6 +1786,7 @@ function renderDataGrid(node) {
         const ctr = el("tr", {}, ...cells);
         if (chasHidden) ctr.append(mobileMoreCell(ctr));
         cbody.append(ctr);
+        if (cdtr) cbody.append(cdtr);
       }
     } catch (e) {
       cbody.append(el("tr", {}, el("td", { colspan: cspan }, String(e.message || e))));
@@ -1723,11 +1794,18 @@ function renderDataGrid(node) {
     return wrap;
   }
 
-  /** @param {Record<string, any>} row */
-  function detailPanel(row) {
+  /** Build an expandable-row detail panel. Used by the top-level grid (with the
+   * closure `detail` config) and by child grids (which pass their own `cg.detail`
+   * as `cfg`) so both share one look/behaviour — link, fields, nested child grids
+   * and an optional escalation form.
+   * @param {Record<string, any>} row
+   * @param {any} [cfg] detail config; defaults to the top-level grid's `detail`
+   */
+  function detailPanel(row, cfg) {
+    const d = cfg || detail;
     const box = el("div", { class: "pc-detail" });
-    if (detail.linkField && row[detail.linkField]) {
-      const href = String(row[detail.linkField]);
+    if (d.linkField && row[d.linkField]) {
+      const href = String(row[d.linkField]);
       // Render as a link only for http(s); anything else (e.g. a javascript: URL
       // smuggled through row data) is shown as inert text. External links get
       // rel="noopener noreferrer" so the opened page can't reach window.opener.
@@ -1737,17 +1815,17 @@ function renderDataGrid(node) {
         box.append(el("span", { class: "pc-link" }, href));
       }
     }
-    for (const df of detail.fields || []) {
+    for (const df of d.fields || []) {
       box.append(el("div", { class: "pc-detail-field" },
         el("span", { class: "pc-detail-label" }, df.label || df.field),
         el("span", {}, row[df.field] == null ? "" : String(row[df.field]))));
     }
-    for (const cg of detail.children || []) {
+    for (const cg of d.children || []) {
       const holder = el("div", {});
       box.append(holder);
       childGrid(cg, row).then((w) => holder.replaceChildren(w));
     }
-    const form = detailForm(row);
+    const form = detailForm(row, d.form);
     if (form) box.append(form);
     return box;
   }
@@ -1976,7 +2054,9 @@ function renderDataGrid(node) {
 // ({ label, page } -> an in-app #/<page> hash link, highlighted when it's the
 // current page) or to an external URL ({ label, href } -> a hardened new-tab
 // link; only http(s) is honoured). With items:"auto" (or omitted) the nav
-// lists every page from the /app/pages index, using each page's title.
+// lists every page from the /app/pages index, using each page's title. An item
+// may also carry a `badge` ({ source, table, filter, tone, refreshMs,
+// hideWhenZero }) that renders a live count pill from the /app/data gateway.
 /** @param {any} item
  * @returns {HTMLAnchorElement|null}
  */
@@ -1995,8 +2075,87 @@ function navLink(item) {
   /** @type {Array<Node|string>} */
   const kids = [];
   if (item.icon != null) kids.push(el("span", { class: "pc-nav-icon" }, String(item.icon)));
-  kids.push(el("span", { class: "pc-nav-label" }, String(item.label != null ? item.label : (item.page || item.href))));
-  return el("a", attrs, ...kids);
+  const labelText = String(item.label != null ? item.label : (item.page || item.href));
+  kids.push(el("span", { class: "pc-nav-label" }, labelText));
+  const link = el("a", attrs, ...kids);
+  // A nav item may carry a live count badge sourced from a datasource (e.g. the
+  // Tasks tab showing how many escalations await a human). It reuses the same
+  // /app/data gateway + .pc-badge tone pills as dataGrid, and polls on refreshMs.
+  // Absent/invalid badge → the link is exactly as before (backward compatible).
+  wireNavBadge(link, labelText, item.badge);
+  return link;
+}
+
+// Attach + drive a nav item's live count badge. Best-effort throughout: a bad
+// config or a failed fetch degrades to no badge, never a broken nav link. The
+// pill is appended hidden and only appears once a fetch yields a count (and, when
+// hideWhenZero, only when that count is > 0). The accessible name of the whole
+// link is kept in sync ("Tasks (3 open)") so assistive tech announces the count,
+// which the small "3" glyph alone would not convey; the pill itself is aria-hidden
+// to avoid a double announcement.
+/** @param {HTMLElement} link
+ * @param {string} baseLabel
+ * @param {any} badge
+ */
+function wireNavBadge(link, baseLabel, badge) {
+  if (!badge || typeof badge !== "object") return;
+  if (typeof badge.table !== "string" || badge.table === "") return;
+  const source = typeof badge.source === "string" && badge.source !== "" ? badge.source : "app";
+  const t = badge.tone;
+  const tone = t === "warn" || t === "ok" || t === "info" || t === "danger" ? t : "danger";
+  const hideWhenZero = badge.hideWhenZero === true;
+  const pill = el("span", { class: "pc-badge pc-nav-badge pc-badge-" + tone, "aria-hidden": "true" });
+  pill.hidden = true;
+  link.append(pill);
+  const filter = Array.isArray(badge.filter) ? badge.filter : [];
+  const paramScoped = filter.some(/** @param {any} f */(f) => f && f.eqParam);
+  const refresh = () => {
+    // A param-scoped badge ("count for the selected entity") with no route param
+    // present would otherwise build the URL with dataUrl baking in an empty PARAM
+    // and query field="", surfacing a wrong count. Match the dataGrid/list pollers:
+    // degrade to 0 (hidden when hideWhenZero) without a request instead.
+    if (paramScoped && PARAM === "") {
+      applyNavBadge(link, pill, baseLabel, hideWhenZero, 0);
+      return;
+    }
+    const url = dataUrl(source, badge.table, filter, null);
+    const countUrl = url + (url.indexOf("?") >= 0 ? "&" : "?") + "count=1";
+    getJSON(countUrl)
+      .then(/** @param {any} res */(res) => applyNavBadge(link, pill, baseLabel, hideWhenZero, res && res.count))
+      .catch(() => applyNavBadge(link, pill, baseLabel, hideWhenZero, NaN));
+  };
+  refresh();
+  const ms = Number(badge.refreshMs);
+  if (Number.isFinite(ms) && ms > 0) {
+    const timer = setInterval(refresh, ms);
+    disposers.push(() => clearInterval(timer));
+  }
+}
+
+// Reflect a fetched count into the pill + the link's accessible name. A
+// non-finite/negative count (a failed or malformed fetch) hides the pill and
+// restores the plain label — the nav degrades quietly rather than showing a
+// broken/"NaN" badge. hideWhenZero also hides the pill at exactly 0.
+/** @param {HTMLElement} link
+ * @param {any} pill
+ * @param {string} baseLabel
+ * @param {boolean} hideWhenZero
+ * @param {any} count
+ */
+function applyNavBadge(link, pill, baseLabel, hideWhenZero, count) {
+  const n = Number(count);
+  if (!Number.isFinite(n) || n < 0 || (n === 0 && hideWhenZero)) {
+    pill.hidden = true;
+    pill.textContent = "";
+    link.setAttribute("aria-label", baseLabel);
+    return;
+  }
+  const shown = String(Math.floor(n));
+  pill.hidden = false;
+  pill.textContent = shown;
+  const aria = baseLabel + " (" + shown + " open)";
+  pill.setAttribute("title", aria);
+  link.setAttribute("aria-label", aria);
 }
 /** @param {HTMLElement} list
  * @param {any[]} items
@@ -2212,4 +2371,4 @@ function boot() {
 // renderer functions / RENDERERS registry can be imported directly.
 if (typeof document !== "undefined" && document.getElementById("page")) boot();
 
-export { RENDERERS, renderText, renderButton, renderProse, renderNav, fmtCellValue, gridCell };
+export { RENDERERS, renderText, renderButton, renderProse, renderNav, navLink, wireNavBadge, applyNavBadge, teardown, fmtCellValue, gridCell };

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

@@ -7,7 +7,7 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { PAGE_NODE_TYPES } from "@nanobpm/nano-app-schema";
-import { RENDERERS, renderText, fmtCellValue, gridCell } from "./runtime.browser.js";
+import { RENDERERS, renderText, navLink, wireNavBadge, applyNavBadge, teardown, fmtCellValue, gridCell } from "./runtime.browser.js";
 
 // ── Minimal fake DOM ────────────────────────────────────────────────────────
 // Just enough of the Element/Document surface that el()/renderText touch:
@@ -158,3 +158,183 @@ test("#327: gridCell applies col.format to the cell text, leaving an unformatted
   const plain = gridCell({ field: "updated_at", header: "Updated" }, { updated_at: iso }, "secondary");
   assert.equal(plain.textContent, iso);
 });
+
+// Find the first descendant span carrying `cls` in a FakeElement tree. Accepts
+// `any` so it can walk either a FakeElement or a renderer's DOM-typed return.
+function findByClass(node: any, cls: string): FakeElement | null {
+  for (const kid of node.children) {
+    if (kid instanceof FakeElement) {
+      if (kid.className.split(/\s+/).includes(cls)) return kid;
+      const deep = findByClass(kid, cls);
+      if (deep) return deep;
+    }
+  }
+  return null;
+}
+
+// Install a fake `fetch` on globalThis returning a fixed JSON body, so navLink's
+// badge poll resolves deterministically without a real network call. Returns a
+// restore fn (register with t.after) so it never leaks into other tests.
+function installFakeFetch(body: unknown): () => void {
+  const prior = Reflect.getOwnPropertyDescriptor(globalThis, "fetch");
+  Reflect.set(globalThis, "fetch", () =>
+    Promise.resolve({ ok: true, json: () => Promise.resolve(body) }),
+  );
+  return () => {
+    if (prior) Reflect.defineProperty(globalThis, "fetch", prior);
+    else Reflect.deleteProperty(globalThis, "fetch");
+  };
+}
+
+test("#338: navLink without a badge is unchanged — no pill, no aria-label override", (t) => {
+  t.after(installFakeDom());
+  const link = navLink({ label: "Home", page: "home" });
+  assert.ok(link, "expected a nav link");
+  assert.equal(link.tagName, "A");
+  assert.equal(findByClass(link, "pc-nav-badge"), null, "no badge pill without item.badge");
+  assert.equal(link.getAttribute("aria-label"), null, "aria-label untouched without a badge");
+});
+
+test("#338: navLink with a badge appends a hidden tone-classed pill and polls a count", async (t) => {
+  t.after(installFakeDom());
+  t.after(installFakeFetch({ count: 3 }));
+  const link = navLink({
+    label: "Tasks",
+    page: "tasks",
+    badge: { source: "app", table: "user_tasks", filter: [], tone: "danger" },
+  });
+  assert.ok(link);
+  const pill = findByClass(link, "pc-nav-badge");
+  assert.ok(pill, "expected a badge pill for item.badge");
+  assert.ok(pill.className.includes("pc-badge"), "reuses the .pc-badge pill");
+  assert.ok(pill.className.includes("pc-badge-danger"), "carries the requested tone class");
+  // The poll resolves asynchronously; flush microtasks then assert the live count.
+  await new Promise((r) => setTimeout(r, 0));
+  assert.equal(pill.hidden, false, "pill shows once a positive count arrives");
+  assert.equal(pill.textContent, "3");
+  assert.equal(link.getAttribute("aria-label"), "Tasks (3 open)", "accessible name carries the count");
+});
+
+test("#338: navLink badge degrades to no pill (never a broken nav) when the fetch fails", async (t) => {
+  t.after(installFakeDom());
+  const prior = Reflect.getOwnPropertyDescriptor(globalThis, "fetch");
+  Reflect.set(globalThis, "fetch", () => Promise.reject(new Error("boom")));
+  t.after(() => {
+    if (prior) Reflect.defineProperty(globalThis, "fetch", prior);
+    else Reflect.deleteProperty(globalThis, "fetch");
+  });
+  const link = navLink({ label: "Tasks", page: "tasks", badge: { table: "user_tasks" } });
+  const pill = findByClass(link, "pc-nav-badge");
+  assert.ok(pill);
+  await new Promise((r) => setTimeout(r, 0));
+  assert.equal(pill.hidden, true, "a failed fetch leaves the pill hidden");
+  assert.equal(pill.textContent, "");
+});
+
+test("#338: applyNavBadge honours hideWhenZero and mirrors the count into the accessible name", (t) => {
+  const restore = installFakeDom();
+  t.after(restore);
+  const doc: { createElement: (tag: string) => FakeElement } = Reflect.get(globalThis, "document");
+  // The renderer's applyNavBadge is DOM-typed (HTMLElement); the fake elements
+  // satisfy the subset it touches, so the locals are `any` (no banned `as` cast).
+  const mk = (): { link: any; pill: any } => ({ link: doc.createElement("a"), pill: doc.createElement("span") });
+
+  // Positive count → visible pill + "(n open)" accessible name.
+  const a = mk();
+  applyNavBadge(a.link, a.pill, "Tasks", true, 5);
+  assert.equal(a.pill.hidden, false);
+  assert.equal(a.pill.textContent, "5");
+  assert.equal(a.link.getAttribute("aria-label"), "Tasks (5 open)");
+
+  // Zero with hideWhenZero → nothing (a quiet nav stays clean), label reset.
+  const b = mk();
+  applyNavBadge(b.link, b.pill, "Tasks", true, 0);
+  assert.equal(b.pill.hidden, true);
+  assert.equal(b.pill.textContent, "");
+  assert.equal(b.link.getAttribute("aria-label"), "Tasks");
+
+  // Zero WITHOUT hideWhenZero → the pill still shows "0".
+  const c = mk();
+  applyNavBadge(c.link, c.pill, "Tasks", false, 0);
+  assert.equal(c.pill.hidden, false);
+  assert.equal(c.pill.textContent, "0");
+
+  // A non-finite/malformed count degrades to hidden, never "NaN".
+  const d = mk();
+  applyNavBadge(d.link, d.pill, "Tasks", false, Number.NaN);
+  assert.equal(d.pill.hidden, true);
+  assert.equal(d.pill.textContent, "");
+});
+
+test("#338: wireNavBadge registers its poll interval with the per-page teardown so page switches stop it", (t) => {
+  // Defect-class guard: any refreshMs poller MUST clear its interval on teardown,
+  // or navigating between pages leaks a setInterval that fetches forever and pins
+  // the old link/pill alive via closure. This drives wireNavBadge with stubbed
+  // timers + fetch and asserts teardown() actually clears the interval it started.
+  const restore = installFakeDom();
+  t.after(restore);
+  const doc: { createElement: (tag: string) => FakeElement } = Reflect.get(globalThis, "document");
+
+  const cleared: number[] = [];
+  let nextId = 1;
+  const started: number[] = [];
+  const priorSet = Reflect.getOwnPropertyDescriptor(globalThis, "setInterval");
+  const priorClear = Reflect.getOwnPropertyDescriptor(globalThis, "clearInterval");
+  const priorFetch = Reflect.getOwnPropertyDescriptor(globalThis, "fetch");
+  Reflect.set(globalThis, "setInterval", (): number => {
+    const id = nextId++;
+    started.push(id);
+    return id;
+  });
+  Reflect.set(globalThis, "clearInterval", (id: number): void => {
+    cleared.push(id);
+  });
+  // getJSON awaits fetch(); a rejection is swallowed by wireNavBadge's .catch, so
+  // the immediate poll degrades quietly without an unhandled rejection.
+  Reflect.set(globalThis, "fetch", () => Promise.reject(new Error("offline")));
+  t.after(() => {
+    if (priorSet) Reflect.defineProperty(globalThis, "setInterval", priorSet);
+    if (priorClear) Reflect.defineProperty(globalThis, "clearInterval", priorClear);
+    if (priorFetch) Reflect.defineProperty(globalThis, "fetch", priorFetch);
+    else Reflect.deleteProperty(globalThis, "fetch");
+  });
+
+  const link: any = doc.createElement("a");
+  wireNavBadge(link, "Tasks", { source: "app", table: "tasks", refreshMs: 5000 });
+  assert.equal(started.length, 1, "wireNavBadge should start exactly one poll interval");
+  assert.equal(cleared.length, 0, "interval must not be cleared before teardown");
+
+  teardown();
+  assert.deepEqual(cleared, started, "teardown() must clear the interval wireNavBadge started");
+});
+
+test("#338: a param-scoped nav badge with no route param degrades to 0 without querying field=\"\"", (t) => {
+  // Defect-class guard mirroring the dataGrid/list pollers: a badge whose filter is
+  // param-scoped ({ eqParam: true }) but with an empty route PARAM must NOT build a
+  // where=field: query (which the server reads as field equals empty string and can
+  // surface a wrong count). It must short-circuit to a 0/hidden badge with no fetch.
+  const restore = installFakeDom();
+  t.after(restore);
+  const doc: { createElement: (tag: string) => FakeElement } = Reflect.get(globalThis, "document");
+
+  let fetchCalls = 0;
+  const priorFetch = Reflect.getOwnPropertyDescriptor(globalThis, "fetch");
+  Reflect.set(globalThis, "fetch", () => {
+    fetchCalls++;
+    return Promise.reject(new Error("should not fetch"));
+  });
+  t.after(() => {
+    if (priorFetch) Reflect.defineProperty(globalThis, "fetch", priorFetch);
+    else Reflect.deleteProperty(globalThis, "fetch");
+  });
+
+  // PARAM defaults to "" (no renderPage has run), so a param-scoped badge is the
+  // empty-selection case the guard must short-circuit.
+  const link: any = doc.createElement("a");
+  wireNavBadge(link, "Tasks", { source: "app", table: "tasks", filter: [{ field: "owner", eqParam: true }] });
+
+  assert.equal(fetchCalls, 0, "param-scoped badge with empty PARAM must not issue a count query");
+  const pill: any = link.children[link.children.length - 1];
+  assert.equal(pill.textContent, "0", "badge degrades to 0 rather than an empty-string-filtered count");
+  assert.equal(pill.hidden, false, "0 is shown (hideWhenZero is off) rather than a stale count");
+});

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

@@ -1047,6 +1047,33 @@ test("GET /app/data whitelists filter columns", async () => {
   assert.equal(bad.status, 400);
 });
 
+test("#338: GET /app/data?count=1 returns a COUNT(*), honouring the same whitelisted where", async () => {
+  // count mode issues a COUNT(*) (not SELECT *) so a nav badge can show a live
+  // number without transferring rows; the where filter is still column-whitelisted.
+  let seenSql = "";
+  let seenParams: unknown[] = [];
+  const { router } = build({
+    query: async (sql: string, params?: unknown[]) => {
+      if (/PRAGMA table_info/i.test(sql)) {
+        return [{ name: "id" }, { name: "status" }, { name: "total" }];
+      }
+      seenSql = sql;
+      seenParams = params ?? [];
+      return [{ n: 7 }];
+    },
+  });
+  const res = await router(req("GET", "/app/data/app/orders", { query: "count=1&where=status:new" }));
+  assert.equal(res.status, 200);
+  assert.equal(JSON.parse(res.body ?? "{}").count, 7);
+  assert.match(seenSql, /SELECT COUNT\(\*\) AS n FROM/i, "count mode must issue a COUNT(*), not SELECT *");
+  assert.doesNotMatch(seenSql, /LIMIT/i, "a count has no LIMIT");
+  assert.deepEqual(seenParams, ["new"], "the where value is still bound as a parameter");
+
+  // An unknown filter column is rejected in count mode too (no whitelist bypass).
+  const bad = await router(req("GET", "/app/data/app/orders", { query: "count=1&where=evil:1" }));
+  assert.equal(bad.status, 400);
+});
+
 test("POST /app/actions/start/<process> creates an instance", async () => {
   const { router, calls } = build();
   const res = await router(req("POST", "/app/actions/start/my-proc", { body: { variables: { a: 1 } } }));
@@ -1314,6 +1341,84 @@ test("child grids reuse the same per-row More toggle for hidden columns (#268)",
   assert.match(js, /if \(chasHidden\) ctr\.append\(mobileMoreCell\(ctr\)\);/);
 });
 
+test("child grids support per-row detail expansion, collapsed by default (#332)", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // A child grid opts into per-row expansion with a `detail` (alias `expandable`)
+  // block that reuses the top-level grid's detailPanel() — so a nested table (e.g.
+  // a Convergence "Rounds" child) can render each row as an expandable, collapsed
+  // affordance instead of dumping the whole history flat.
+  assert.match(js, /const cdetail = cg\.detail \|\| cg\.expandable \|\| null;/);
+  assert.match(js, /const chasExpand = cdetail != null;/);
+  // The expander shares the top-level detail look: a pc-chevron button in a
+  // pc-row-actions cell, revealing detailPanel(cr, cdetail) in a following row.
+  assert.match(js, /class: "pc-btn pc-btn-sm pc-chevron" \}, collapsed \? "▸" : "▾"/);
+  assert.match(js, /cells\.push\(el\("td", \{ class: "pc-row-actions" \}, ctoggle\)\);/);
+  assert.match(js, /cdtr\.firstChild\.append\(detailPanel\(cr, cdetail\)\)/);
+  // Rows are collapsed by default; detail.defaultCollapsed/detail.collapsed (both
+  // defaulting to true) seed the initial state.
+  assert.match(js, /cdetail\.defaultCollapsed != null/);
+  assert.match(js, /cdetail\.collapsed != null/);
+  // detailPanel is now config-parametrised so the top-level grid and child grids
+  // share one implementation (link + fields + nested children + form).
+  assert.match(js, /function detailPanel\(row, cfg\)/);
+  assert.match(js, /const d = cfg \|\| detail;/);
+});
+
+test("child-grid per-row collapse state is persisted across the refresh poll (#332)", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // The top-level grid rebuilds each child grid on every refreshMs poll, so an
+  // open row would collapse on the next tick without durable state. Per-row
+  // collapse is persisted in localStorage — keyed by page + node + parent
+  // discriminator + child rowKey — via the same readCollapsed/writeCollapsed
+  // helpers groupBy group-collapse uses, so it survives both the poll and a full
+  // reload.
+  assert.match(js, /const cskey = ckeyBase && crk != null \? ckeyBase \+ crk : null;/);
+  assert.match(js, /readCollapsed\(cskey, cdefaultCollapsed\)/);
+  assert.match(js, /if \(cskey\) writeCollapsed\(cskey, !open\);/);
+  assert.match(js, /"pc:collapsed:" \+ CURRENT \+ ":" \+ cnodeId \+ ":" \+ cchildId/);
+});
+
+test("child-grid collapse key is scoped by row[cg.parentField], not the parent grid's rowKey (#332)", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // The parent-row discriminator in the localStorage key MUST be the value the
+  // child grid is queried by (row[cg.parentField]) — NOT rowKeyOf(row), which is
+  // null whenever the top-level grid declares no `rowKey`. With the old rowKeyOf
+  // key every parent row collapsed under the literal "_", so opening one parent's
+  // child row silently toggled the same-keyed child row under every other parent.
+  assert.match(
+    js,
+    /const cparentKey = cg\.parentField != null && row\[cg\.parentField\] != null\s*\?\s*String\(row\[cg\.parentField\]\) : null;/,
+  );
+  // No safe key ⇒ persistence disabled (ckeyBase null), never a colliding "_".
+  assert.match(js, /const ckeyBase = cparentKey == null \? null/);
+  assert.doesNotMatch(js, /cparentKey == null \? "_" : cparentKey/);
+});
+
+test("child-grid detail panel never falls back to the top-level grid's form (#332)", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // detailPanel(cr, cdetail) renders a child grid's own detail config. Its form is
+  // detailForm(row, d.form): when the child config declares no `form` the panel
+  // must have NO form — it must NOT implicitly reuse the top-level grid's
+  // detail.form. So detailForm uses its argument verbatim rather than falling back
+  // to `detail && detail.form` when the argument is undefined.
+  assert.match(js, /function detailForm\(row, formCfg\) \{\s*const f = formCfg;/);
+  assert.doesNotMatch(js, /formCfg !== undefined \? formCfg : \(detail && detail\.form\)/);
+});
+
+test("child-grid fetch failure renders a full-width error row (#332)", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // The child grid's colspan is computed eagerly, BEFORE the getJSON() fetch, so
+  // the catch path's error row (colspan: cspan) spans the whole table even when
+  // the fetch throws. A lazily-assigned cspan would be undefined in the catch.
+  assert.match(js, /const cspan = String\(\(ccols\.length \|\| 1\) \+ cextra\);\s*try \{/);
+  assert.match(js, /\} catch \(e\) \{\s*cbody\.append\(el\("tr", \{\}, el\("td", \{ colspan: cspan \}/);
+});
+
 test("the renderer honours an optional Tier-2 page-level mobile layout variant (#268)", async () => {
   const res = await dispatch("GET", "/app/runtime.js");
   const js = res.body ?? "";

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

@@ -92,6 +92,15 @@ function javascript(
  * (checked against `schema()`), so `/app/data/:table` can never inject SQL. */
 const IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
 
+// A query flag (e.g. ?count=1) is "on" when present and not one of the falsy
+// spellings. A bare `?count` (empty string) still counts as on, so a caller can
+// opt in without inventing a value.
+function isTruthyParam(v: string | null): boolean {
+  if (v === null) return false;
+  const s = v.trim().toLowerCase();
+  return s !== "0" && s !== "false" && s !== "no";
+}
+
 /**
  * Build the page-runtime routes over an injected datasource + engine. Pure over its deps
  * so it is unit-testable without a real host/server (see pages.test.ts).
@@ -272,6 +281,24 @@ export function createPagesRoutes(opts: PagesOptions, deps: PagesDeps): Route[]
         orderSql = ` ORDER BY ${quoteIdent(field)} ${dir}`;
       }
       const whereSql = clauses.length ? ` WHERE ${clauses.join(" AND ")}` : "";
+      // ?count=1 → a lightweight COUNT(*) instead of the rows themselves. The same
+      // whitelisted where clauses apply, so a caller (e.g. a nav item's live count
+      // badge) gets exactly the number of matching rows without transferring or
+      // materialising them. ORDER BY / LIMIT are irrelevant to a count and skipped.
+      if (isTruthyParam(req.query.get("count"))) {
+        try {
+          const rows = await db.query(
+            `SELECT COUNT(*) AS n FROM ${quoteIdent(table)}${whereSql}`,
+            params,
+          );
+          const first = Array.isArray(rows) && rows.length > 0 ? rows[0] : undefined;
+          const rawCount = isRecord(first) ? first.n : 0;
+          const count = Number(rawCount);
+          return json({ count: Number.isFinite(count) ? count : 0 });
+        } catch (e) {
+          return json({ error: errorMessage(e) }, 500);
+        }
+      }
       try {
         const rows = await db.query(
           `SELECT * FROM ${quoteIdent(table)}${whereSql}${orderSql} LIMIT ${rowLimit}`,
@@ -682,6 +709,11 @@ table.pc-grid th { font-weight:600; color:var(--nano-text-muted); }
 .pc-nav-link:hover { background:var(--nano-hover); color:var(--nano-text); }
 .pc-nav-link.active { background:var(--nano-accent); color:var(--nano-on-accent); }
 .pc-nav-icon { line-height:1; }
+/* A nav item's live count pill (item.badge). Slightly more compact than the base
+   .pc-badge so it sits neatly beside a nav label; [hidden] must win over the
+   .pc-badge inline-flex display so hideWhenZero / a failed fetch truly hides it. */
+.pc-nav-badge { min-width:1.1rem; height:1.1rem; font-size:.68rem; padding:0 .35rem; margin-left:.1rem; }
+.pc-nav-badge[hidden] { display:none; }
 .pc-nav-empty { color:var(--nano-text-faint); font-size:.85rem; padding:.4rem .7rem; }
 /* The per-row mobile "More" toggle (revealing mobile:{priority:"hidden"} columns)
    only exists for the card view — hidden on the desktop table, shown by the