@nanobpm/urban 0.43.0 → 0.45.0

package/README.md

@@ -64,8 +64,8 @@ urban run        # start workers and serve surfaces
 ## Library API
 
 Everything the CLI does is available programmatically. Import the whole surface
-from `@nanobpm/urban`, or the focused subpaths `@nanobpm/urban/runtime` and
-`@nanobpm/urban/toolkit`.
+from `@nanobpm/urban`, or the focused subpaths `@nanobpm/urban/runtime`,
+`@nanobpm/urban/toolkit`, and `@nanobpm/urban/effect`.
 
 ### Runtime — run an app
 
@@ -244,6 +244,57 @@ survives restarts, model a timer **start**/**intermediate** event instead with
 `w.startOn(...)` / `w.timer(...)` from [`@nanobpm/workflow`](../workflow) — the
 engine owns those.
 
+### Effect — typed errors & scoped resources (`@nanobpm/urban/effect`)
+
+A tiny, **zero-dependency**, Effect-like core for the imperative seams (workers,
+provisioning, resource lifecycles) — without pulling in the `effect` package or
+its viral paradigm. It gives you the three ergonomics you actually reach for:
+
+- **Typed-error `Result<A, E>` with generator do-notation.** `gen(function* … )`
+  + `yield*` threads success values and short-circuits on the first failure,
+  automatically inferring the union of every failure type into `E` — like
+  `Effect.gen` + `yield*`.
+- **Tagged errors + exhaustive matching.** `tag("NotFound")` builds a discriminated
+  error; `matchTags` forces you to handle **every** variant (omitting one is a
+  compile error), like `Data.TaggedError` + `catchTags`.
+- **Scoped resources.** `scoped` + `acquireRelease` run every release on every exit
+  — success, failure, or thrown — LIFO, like `Effect.scoped`.
+
+```ts
+import { gen, ok, fail, tag, matchTags, scoped, acquireRelease } from "@nanobpm/urban/effect";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const parse = (s: string) => (s ? ok(s.length) : fail(tag("Empty")));
+const check = (n: number) => (n > 3 ? fail(tag("TooLong", { n })) : ok(n));
+
+const run = (s: string) =>
+  gen(function* () {
+    const n = yield* parse(s);        // E gains "Empty"
+    return yield* check(n);           // E gains "TooLong"
+  });                                 // Result<number, {_tag:"Empty"} | {_tag:"TooLong", n:number}>
+
+const r = run("hello");
+if (r._tag === "Fail") {
+  matchTags(r.error, {                // must handle both — omit one and it won't compile
+    Empty: () => "was empty",
+    TooLong: (e) => `too long: ${e.n}`,
+  });
+}
+
+// `acquireRelease`'s `acquire` is synchronous, so use sync fs APIs (or `await`
+// the acquisition yourself and register the disposer with `scope.add`).
+await scoped(async (scope) => {
+  const dir = acquireRelease(
+    scope,
+    () => mkdtempSync(join(tmpdir(), "urban-")),
+    (d) => rmSync(d, { recursive: true, force: true }),
+  ); // released on any exit
+  // …use dir…
+});
+```
+
 ## Related packages
 
 - [`@nanobpm/workflow`](../workflow) — the code-first process surface (`defineFlow`).

package/dist/effect/index.d.ts

@@ -0,0 +1,39 @@
+export type Result<A, E> = Ok<A> | Fail<E>;
+export declare class Ok<A> {
+    readonly _tag: "Ok";
+    readonly value: A;
+    constructor(value: A);
+    [Symbol.iterator](): Generator<never, A, unknown>;
+}
+export declare class Fail<E> {
+    readonly _tag: "Fail";
+    readonly error: E;
+    constructor(error: E);
+    [Symbol.iterator](): Generator<Fail<E>, never, unknown>;
+}
+export declare const ok: <A>(value: A) => Ok<A>;
+export declare const fail: <E>(error: E) => Fail<E>;
+export declare const isOk: <A, E>(r: Result<A, E>) => r is Ok<A>;
+export declare const isFail: <A, E>(r: Result<A, E>) => r is Fail<E>;
+export declare function gen<Y extends Fail<unknown>, A>(body: () => Generator<Y, A, unknown>): Result<A, Y["error"]>;
+export type OkOf<R> = R extends Ok<infer A> ? A : never;
+export type ErrOf<R> = R extends Fail<infer E> ? E : never;
+export declare const map: <R extends Result<unknown, unknown>, B>(r: R, f: (a: OkOf<R>) => B) => Result<B, ErrOf<R>>;
+export declare const mapError: <R extends Result<unknown, unknown>, E2>(r: R, f: (e: ErrOf<R>) => E2) => Result<OkOf<R>, E2>;
+export declare const match: <R extends Result<unknown, unknown>, T>(r: R, onOk: (a: OkOf<R>) => T, onFail: (e: ErrOf<R>) => T) => T;
+export type Tagged<Tag extends string> = {
+    readonly _tag: Tag;
+};
+export type TagUnion<Tag extends string, P> = Tag extends string ? Tagged<Tag> & P : never;
+export declare function tag<Tag extends string>(t: Tag): TagUnion<Tag, {}>;
+export declare function tag<Tag extends string, P extends object>(t: Tag, props: P & {
+    _tag?: never;
+}): TagUnion<Tag, P>;
+export declare const matchTags: <E extends Tagged<string>, R>(e: E, handlers: { [K in E["_tag"]]: (e: Extract<E, Tagged<K>>) => R; }) => R;
+export declare class Scope {
+    #private;
+    add(dispose: () => void | Promise<void>): void;
+    close(): Promise<void>;
+}
+export declare function acquireRelease<A>(scope: Scope, acquire: () => A, release: (a: A) => void | Promise<void>): A;
+export declare function scoped<A>(body: (scope: Scope) => A | Promise<A>): Promise<A>;

package/dist/effect/index.js

@@ -0,0 +1,133 @@
+// effectlite — a tiny, ZERO-DEPENDENCY, Effect-like core for Urban glue code.
+//
+// Urban's published surface is declarative JSON + a client renderer, so we do
+// NOT want the `effect` package (bundle weight + viral paradigm) in the runtime.
+// But the imperative seams — workers, provisioning, resource lifecycles — still
+// benefit from the three Effect ergonomics we actually reach for. effectlite
+// gives us those, in ~100 LOC of implementation with no runtime dependencies:
+//
+//   1. A typed-error `Result<A, E>` whose `E` composes automatically through
+//      generator do-notation (`gen(function*(){ const x = yield* step })`),
+//      short-circuiting on the first failure exactly like `Effect.gen` + `yield*`.
+//   2. `tag()` tagged errors (cf. `Data.TaggedError`) + exhaustive `matchTags`
+//      (cf. `catchTags`) — the compiler forces every failure mode to be handled.
+//   3. `scoped` + `acquireRelease` (cf. `Effect.scoped`) — releases run on every
+//      exit: success, failure, and thrown.
+//
+// It is synchronous over `Result`; the scope is async only so disposers may
+// await. Consume via `import { gen, ok, fail } from "@nanobpm/urban/effect"`.
+export class Ok {
+    _tag = "Ok";
+    value;
+    constructor(value) {
+        this.value = value;
+    }
+    // Delegated by `yield*`: returns the value, yields nothing to the driver.
+    *[Symbol.iterator]() {
+        return this.value;
+    }
+}
+export class Fail {
+    _tag = "Fail";
+    error;
+    constructor(error) {
+        this.error = error;
+    }
+    // Delegated by `yield*`: yields itself so the driver can short-circuit; never
+    // resumes (the driver abandons the generator on the first failure).
+    *[Symbol.iterator]() {
+        yield this;
+        throw new Error("effectlite: generator resumed after a failure");
+    }
+}
+export const ok = (value) => new Ok(value);
+export const fail = (error) => new Fail(error);
+export const isOk = (r) => r._tag === "Ok";
+export const isFail = (r) => r._tag === "Fail";
+// Run a generator that `yield*`s Results. Because only `Fail` yields to us, a
+// single `next()` either lands on the first failure or on the final return.
+// `Y` captures the UNION of every yielded `Fail<…>`; `Y["error"]` distributes
+// that index access into the Result's error channel (a union in ⇒ a union out).
+export function gen(body) {
+    // Typed as `Iterator` (not `Generator`) so `return` is the optional-arg
+    // variant — lets us close a short-circuited body without inventing a return value.
+    const it = body();
+    const step = it.next();
+    if (step.done)
+        return ok(step.value);
+    // Not done ⇒ a `Fail` yielded to short-circuit. Close the generator first so
+    // any `try/finally` in the body runs and captured resources aren't retained,
+    // then surface its error on the failure channel.
+    it.return?.();
+    return fail(step.value.error);
+}
+// Narrowing guards that carry the *extracted* channel type, so `r.value` /
+// `r.error` land as `OkOf<R>` / `ErrOf<R>` (not `unknown`) with no assertion —
+// keeping the combinators within the repo's no-type-assertion convention.
+const isOkOf = (r) => r._tag === "Ok";
+const isFailOf = (r) => r._tag === "Fail";
+export const map = (r, f) => {
+    if (isOkOf(r))
+        return ok(f(r.value));
+    if (isFailOf(r))
+        return r;
+    throw new Error("effectlite: Result was neither Ok nor Fail");
+};
+export const mapError = (r, f) => {
+    if (isFailOf(r))
+        return fail(f(r.error));
+    if (isOkOf(r))
+        return r;
+    throw new Error("effectlite: Result was neither Ok nor Fail");
+};
+export const match = (r, onOk, onFail) => {
+    if (isOkOf(r))
+        return onOk(r.value);
+    if (isFailOf(r))
+        return onFail(r.error);
+    throw new Error("effectlite: Result was neither Ok nor Fail");
+};
+export function tag(t, props) {
+    return { ...props, _tag: t };
+}
+// Handle every tag in the union — the handlers object is keyed by `E["_tag"]`,
+// so omitting a variant is a COMPILE error (no accidental dropped failure mode).
+export const matchTags = (e, handlers) => 
+// biome-ignore lint/plugin: the mapped handler type is precise for callers; internally we index it with the runtime tag, which needs this erasure to a plain record.
+handlers[e._tag](e);
+// ---------------------------------------------------------------------------
+// Scoped resources
+// ---------------------------------------------------------------------------
+export class Scope {
+    #disposers = [];
+    add(dispose) {
+        this.#disposers.push(dispose);
+    }
+    async close() {
+        // LIFO, best-effort — a failing disposer never blocks the others.
+        for (const d of this.#disposers.reverse()) {
+            try {
+                await d();
+            }
+            catch { /* best effort */ }
+        }
+        this.#disposers = [];
+    }
+}
+// Acquire a resource and register its release with the scope in one step.
+export function acquireRelease(scope, acquire, release) {
+    const a = acquire();
+    scope.add(() => release(a));
+    return a;
+}
+// Run `body` with a fresh scope; close it (releasing all resources) on every
+// exit path — return, Result failure, or thrown.
+export async function scoped(body) {
+    const scope = new Scope();
+    try {
+        return await body(scope);
+    }
+    finally {
+        await scope.close();
+    }
+}

package/dist/runtime/core/modules/pages.js

@@ -518,6 +518,12 @@ table.pc-grid th { font-weight:600; color:var(--nano-text-muted); }
 .pc-collapse-header { display:flex; align-items:center; gap:.5rem; width:100%; margin:0 0 .75rem; padding:0; background:transparent; border:0; color:inherit; font:inherit; font-size:1rem; font-weight:600; cursor:pointer; text-align:left; }
 .pc-chevron-inline { color:var(--nano-text-faint); font-size:.75rem; width:1em; }
 .pc-card-body[hidden] { display:none; }
+/* Grid group headers (dataGrid groupBy): a full-width, clickable band that
+   collapses/expands its member rows; the collapsed state is persisted. */
+.pc-group-header td { padding:0; background:var(--nano-inset); border-top:1px solid var(--nano-edge); }
+.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; }
 /* 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); }
@@ -534,6 +540,11 @@ table.pc-grid th { font-weight:600; color:var(--nano-text-muted); }
 .pc-main-col { flex:1 1 auto; min-width:0; }
 .pc-nav-title { font-weight:650; }
 .pc-bar { display:flex; align-items:center; gap:.6rem; flex-wrap:wrap; border-bottom:1px solid var(--nano-edge); padding-bottom:.6rem; margin-bottom:1.25rem; }
+/* Opt-in sticky bar: stays pinned to the viewport top while the page scrolls.
+   The negative inline margin + matching padding lets its background span the
+   body's 2rem inline padding so scrolled content never shows beside it, and a
+   solid app-colored background hides content passing underneath. */
+.pc-bar.pc-sticky { position:sticky; top:0; z-index:20; background:var(--nano-app); margin-inline:-2rem; padding-inline:2rem; padding-top:.6rem; }
 .pc-bar .pc-nav-title { margin-right:.5rem; }
 .pc-bar .pc-nav-items { display:flex; gap:.25rem; flex-wrap:wrap; }
 .pc-rail { display:flex; flex-direction:column; gap:.5rem; }
@@ -563,15 +574,34 @@ const PAGE_ID = /^[A-Za-z0-9_-]+$/;
 function safePageId(value) {
   return typeof value === "string" && PAGE_ID.test(value);
 }
-function currentPage() {
-  try {
-    const raw = decodeURIComponent((location.hash || "").replace(/^#\/?/, ""));
-    return safePageId(raw) ? raw : HOME;
-  } catch (e) {
-    return HOME;
-  }
+// A route is #/<page> or #/<page>/<url-encoded-param>. We split on the FIRST
+// "/" *before* decoding, so a param that itself contains encoded slashes or
+// hashes (e.g. a plan_key "owner/repo#123" carried as "owner%2Frepo%23123")
+// survives intact instead of the inner "%2F" being decoded into a second
+// segment. The page segment is still restricted to the safe id charset; the
+// param is opaque free text (bound only as a whitelisted '?' SQL value, or
+// interpolated as DOM text — never as HTML/markup).
+function parseRoute() {
+  const raw = (location.hash || "").replace(/^#\/?/, "");
+  const slash = raw.indexOf("/");
+  const pageRaw = slash >= 0 ? raw.slice(0, slash) : raw;
+  const paramRaw = slash >= 0 ? raw.slice(slash + 1) : "";
+  let page = HOME, param = "", pageOk = false;
+  try { const p = decodeURIComponent(pageRaw); if (safePageId(p)) { page = p; pageOk = true; } } catch (e) { /* keep HOME */ }
+  // Only carry the param when the page segment resolved to a real (safe-id) page.
+  // A malformed/unknown page like #/not-a-page/x falls back to HOME and must NOT
+  // inherit x, or that stray param would silently scope every eqParam grid and
+  // {{param}} on the home page to an entity the user never selected.
+  if (pageOk) { try { param = paramRaw ? decodeURIComponent(paramRaw) : ""; } catch (e) { param = ""; } }
+  return { page, param };
 }
+function currentPage() { return parseRoute().page; }
 let CURRENT = currentPage();
+// The current route param (the "/<param>" tail, or "" when absent). Exposed to a
+// page's datasource filters (a filter with { eqParam: true } binds its value to
+// this) and to {{param}} text interpolation, so one page template can scope
+// every section to a selected entity (e.g. an epic's plan_key).
+let PARAM = parseRoute().param;
 
 // Per-render teardown. Each dataGrid registers its poll interval + pc:refresh
 // listener here; navigating to another page runs every disposer before the new
@@ -740,10 +770,19 @@ function el(tag, attrs = {}, ...kids) {
   return n;
 }
 
+// Interpolate the {{param}} token in a schema-supplied string with the current
+// route param. The result is only ever set as DOM text (textContent), so the
+// substituted value cannot inject markup. Other tokens are left untouched.
+// A function replacement inserts PARAM literally; a plain string replacement would
+// treat replacement patterns inside PARAM (an id like the dollar-one token) as
+// special and render the wrong text.
+function interpParam(s) {
+  return typeof s === "string" ? s.replace(/\{\{param\}\}/g, () => PARAM) : s;
+}
 function renderText(node) {
   const v = node.props.variant;
   const cls = v === "heading" ? "pc-heading" : v === "sub" ? "pc-sub" : "pc-body";
-  return el(v === "heading" ? "h1" : "p", { class: cls }, node.props.text || "");
+  return el(v === "heading" ? "h1" : "p", { class: cls }, interpParam(node.props.text) || "");
 }
 
 // Copy text to the clipboard, resiliently. The async Clipboard API is tried
@@ -937,6 +976,20 @@ function gridCell(col, row) {
       );
     }
   }
+  if (col.link && col.link.kind === "page" && col.link.page && col.link.keyField) {
+    // An in-app link to another page, scoped to this row: #/<page>/<key>. The
+    // key (e.g. a plan_key "owner/repo#123") is URL-encoded into the route's
+    // param tail, which parseRoute() decodes back verbatim; the page id is
+    // validated against the safe-id charset and the key must be non-empty, so a
+    // blank/keyless cell stays plain text. Navigation is a pure hash change
+    // (no new tab, no server hit) — the SPA router re-renders in place.
+    const key = row[col.link.keyField];
+    const keyStr = key == null ? "" : String(key).trim();
+    if (text !== "" && safePageId(col.link.page) && keyStr !== "") {
+      const href = "#/" + encodeURIComponent(col.link.page) + "/" + encodeURIComponent(keyStr);
+      return el("td", {}, el("a", { class: "pc-link", href }, text));
+    }
+  }
   if (col.link && col.link.kind === "processExplorer" && col.link.keyField) {
     const key = row[col.link.keyField];
     const keyStr = key == null ? "" : String(key).trim();
@@ -1109,6 +1162,7 @@ function renderDataGrid(node) {
     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")));
@@ -1239,7 +1293,7 @@ function renderDataGrid(node) {
     return box;
   }
 
-  function renderRow(row) {
+  function renderRow(row, sink) {
     const cells = cols.map((c) => gridCell(c, row));
     const key = rowKeyOf(row);
     let toggle = null;
@@ -1257,6 +1311,9 @@ function renderDataGrid(node) {
     }
     const tr = el("tr", {}, ...cells);
     tbody.append(tr);
+    // When grouping, the caller collects every <tr> this row produced (the data
+    // row plus any detail row) so a group header can hide/show them as one unit.
+    if (sink) sink.push({ tr, isDetail: false, key });
     if (detail && toggle) {
       const isOpen = key != null && expanded.has(key);
       // Reuse an already-built detail row for an open PR across refreshes so its
@@ -1284,6 +1341,67 @@ function renderDataGrid(node) {
         }
       });
       tbody.append(dtr);
+      if (sink) sink.push({ tr: dtr, isDetail: true, key });
+    }
+  }
+
+  // Append the fetched rows into the tbody, either flat (default) or partitioned
+  // into collapsible groups when the grid declares 'groupBy: "<field>"'. Each
+  // group renders a clickable header row ("<Label> <value> (<count>)") that
+  // collapses/expands its member rows as one unit; the collapsed state is
+  // persisted (localStorage, keyed by page + node + group value) so it survives
+  // both the refresh poll and a full reload — the same durability the top-level
+  // 'collapsible' node wrapper gives. Group order is numeric-aware ascending
+  // (so waves 1,2,10 sort naturally), falling back to lexical for non-numeric
+  // keys. 'groupDefaultCollapsed' seeds each group collapsed until toggled.
+  function appendRows(rows) {
+    const groupBy = p.groupBy;
+    // Treat a non-string groupBy as "no grouping": labelBase calls groupBy.charAt()
+    // below, so a truthy non-string (number/object from a malformed page schema)
+    // would throw at render time and break the whole page instead of one grid.
+    if (!groupBy || typeof groupBy !== "string") { for (const row of rows) renderRow(row, null); return; }
+    const order = [];
+    const groups = new Map();
+    for (const row of rows) {
+      const gvRaw = row[groupBy];
+      const gv = gvRaw == null ? "" : String(gvRaw);
+      if (!groups.has(gv)) { groups.set(gv, []); order.push(gv); }
+      groups.get(gv).push(row);
+    }
+    order.sort((a, b) => {
+      const na = Number(a), nb = Number(b);
+      if (a !== "" && b !== "" && !Number.isNaN(na) && !Number.isNaN(nb)) return na - nb;
+      return a < b ? -1 : a > b ? 1 : 0;
+    });
+    const labelBase = p.groupLabel != null
+      ? String(p.groupLabel)
+      : groupBy.charAt(0).toUpperCase() + groupBy.slice(1);
+    for (const gv of order) {
+      const groupRows = groups.get(gv);
+      const gkey = "pc:collapsed:" + CURRENT + ":" + (node.id || p.title || "grid") + ":g:" + gv;
+      let gcollapsed = readCollapsed(gkey, !!p.groupDefaultCollapsed);
+      const chevron = el("span", { class: "pc-chevron-inline" }, gcollapsed ? "▸" : "▾");
+      const label = (gv === "" ? labelBase + " —" : labelBase + " " + gv) + " (" + groupRows.length + ")";
+      const btn = el("button", { class: "pc-group-toggle", type: "button" },
+        chevron, el("span", { class: "pc-group-title" }, label));
+      tbody.append(el("tr", { class: "pc-group-header" }, el("td", { colspan: span }, btn)));
+      const members = [];
+      for (const row of groupRows) renderRow(row, members);
+      const applyGroup = () => {
+        chevron.textContent = gcollapsed ? "▸" : "▾";
+        btn.setAttribute("aria-expanded", String(!gcollapsed));
+        for (const m of members) {
+          m.tr.hidden = gcollapsed
+            ? true
+            : (m.isDetail ? !(m.key != null && expanded.has(m.key)) : false);
+        }
+      };
+      btn.addEventListener("click", () => {
+        gcollapsed = !gcollapsed;
+        writeCollapsed(gkey, gcollapsed);
+        applyGroup();
+      });
+      applyGroup();
     }
   }
 
@@ -1299,7 +1417,15 @@ function renderDataGrid(node) {
 
   async function refresh() {
     try {
-      const { rows } = await getJSON(dataUrl(p.data.source, p.data.table, activeFilter, p.data.orderBy));
+      // A grid scoped to a route param (any eqParam filter) means "show the rows
+      // for the selected entity". With no param present, PARAM is empty and emitting
+      // a where clause of field-colon-empty would read server-side as field equals
+      // empty string and surface empty-valued rows. That is not the selected entity's
+      // rows (there is no selection), so short-circuit to zero rows without a request.
+      const paramScoped = (activeFilter || []).some((f) => f && f.eqParam);
+      const { rows } = paramScoped && PARAM === ""
+        ? { rows: [] }
+        : await getJSON(dataUrl(p.data.source, p.data.table, activeFilter, p.data.orderBy));
       // 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) {
@@ -1338,7 +1464,7 @@ function renderDataGrid(node) {
         }
       }
       tbody.replaceChildren();
-      for (const row of rows) renderRow(row);
+      appendRows(rows);
       if (!rows.length) tbody.append(el("tr", {}, el("td", { colspan: span }, "No rows")));
       if (keepFocus && active.isConnected) {
         active.focus();
@@ -1405,7 +1531,14 @@ function fillNav(list, items) {
 function renderNav(node) {
   const p = node.props || {};
   const rail = p.variant === "rail";
-  const nav = el("nav", { class: rail ? "pc-nav pc-rail" : "pc-nav pc-bar" });
+  // A bar nav can opt into staying pinned to the top of the viewport while the
+  // page scrolls (sticky) — useful on the long, multi-section operator pages so
+  // the page switcher is always reachable. Rails are already full-height, so the
+  // flag only applies to the bar variant.
+  const barSticky = !rail && p.sticky === true;
+  const nav = el("nav", {
+    class: (rail ? "pc-nav pc-rail" : "pc-nav pc-bar") + (barSticky ? " pc-sticky" : ""),
+  });
   if (p.title != null) nav.append(el("div", { class: "pc-nav-title" }, String(p.title)));
   const list = el("div", { class: "pc-nav-items" });
   nav.append(list);
@@ -1499,7 +1632,9 @@ function makeCollapsible(node, card) {
 // tearing down the previous page's grid polls first.
 async function renderPage() {
   teardown();
-  CURRENT = currentPage();
+  const route = parseRoute();
+  CURRENT = route.page;
+  PARAM = route.param;
   try {
     const doc = await getJSON("/app/pages/" + encodeURIComponent(CURRENT));
     document.title = (doc && doc.title) || "Urban App";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.43.0",
+	"version": "0.45.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",
@@ -47,6 +47,10 @@
 			"types": "./dist/worker.d.ts",
 			"default": "./dist/worker.js"
 		},
+		"./effect": {
+			"types": "./dist/effect/index.d.ts",
+			"default": "./dist/effect/index.js"
+		},
 		"./source": "./src/index.ts"
 	},
 	"files": [

package/src/effect/index.test.ts

@@ -0,0 +1,185 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  ok,
+  fail,
+  isOk,
+  isFail,
+  gen,
+  map,
+  mapError,
+  match,
+  tag,
+  matchTags,
+  scoped,
+  acquireRelease,
+  type Result,
+  type Tagged,
+} from "./index.ts";
+
+test("ok/fail construct and narrow", () => {
+  const a = ok(42);
+  const b = fail("boom");
+  assert.equal(isOk(a), true);
+  assert.equal(isFail(a), false);
+  assert.equal(isOk(b), false);
+  assert.equal(isFail(b), true);
+  if (isOk(a)) assert.equal(a.value, 42);
+  if (isFail(b)) assert.equal(b.error, "boom");
+});
+
+test("gen threads values through yield* on the happy path", () => {
+  const r = gen(function* () {
+    const x = yield* ok(2);
+    const y = yield* ok(3);
+    return x + y;
+  });
+  assert.equal(isOk(r), true);
+  if (isOk(r)) assert.equal(r.value, 5);
+});
+
+test("gen short-circuits on the first failure", () => {
+  const steps: string[] = [];
+  const r = gen(function* () {
+    steps.push("a");
+    const x = yield* ok(1);
+    steps.push("b");
+    yield* fail("nope");
+    steps.push("c"); // must not run
+    return x;
+  });
+  assert.equal(isFail(r), true);
+  if (isFail(r)) assert.equal(r.error, "nope");
+  assert.deepEqual(steps, ["a", "b"]);
+});
+
+test("gen unions error types from multiple failure sources", () => {
+  const parse = (s: string) => (s === "" ? fail(tag("Empty")) : ok(s.length));
+  const check = (n: number) => (n > 3 ? fail(tag("TooLong")) : ok(n));
+  const run = (s: string) =>
+    gen(function* () {
+      const n = yield* parse(s);
+      const ok2 = yield* check(n);
+      return ok2;
+    });
+
+  const good = run("ab");
+  assert.equal(isOk(good), true);
+  if (isOk(good)) assert.equal(good.value, 2);
+
+  const empty = run("");
+  assert.equal(isFail(empty), true);
+  if (isFail(empty)) assert.equal(empty.error._tag, "Empty");
+
+  const long = run("abcd");
+  assert.equal(isFail(long), true);
+  if (isFail(long)) assert.equal(long.error._tag, "TooLong");
+});
+
+test("gen closes the generator so try/finally runs on short-circuit", () => {
+  const events: string[] = [];
+  const r = gen(function* () {
+    try {
+      events.push("enter");
+      yield* fail("boom");
+      events.push("after-fail"); // must not run
+      return 1;
+    } finally {
+      events.push("cleanup"); // must run even though we short-circuited
+    }
+  });
+  assert.equal(isFail(r), true);
+  if (isFail(r)) assert.equal(r.error, "boom");
+  // The failure short-circuits before "after-fail", but the generator is closed
+  // so its `finally` still releases (LIFO: enter → cleanup, no after-fail).
+  assert.deepEqual(events, ["enter", "cleanup"]);
+});
+
+test("map/mapError/match", () => {
+  assert.equal(match(map(ok(2), (n) => n * 10), (a) => a, () => -1), 20);
+  const failed: Result<number, string> = fail("e");
+  assert.equal(match(map(failed, (n) => n * 10), (n) => String(n), (e) => e), "e");
+  assert.equal(match(mapError(fail("e"), (e) => e + "!"), () => "", (e) => e), "e!");
+  assert.equal(match(mapError(ok(7), (e: string) => e), (a) => a, () => -1), 7);
+});
+
+test("tag builds tagged errors with props", () => {
+  const e = tag("Http", { status: 404 });
+  assert.equal(e._tag, "Http");
+  assert.equal(e.status, 404);
+});
+
+test("tag without props carries only the tag (no phantom prop keys)", () => {
+  const e = tag("Empty");
+  assert.equal(e._tag, "Empty");
+  assert.deepEqual(Object.keys(e), ["_tag"]);
+});
+
+test("tag() sets _tag last so untyped props cannot clobber the discriminant", () => {
+  // Props arriving through an untyped boundary must never override the tag —
+  // otherwise a stray `_tag` would break the discriminant `matchTags` relies on.
+  const untyped: object = JSON.parse('{"_tag":"EVIL","detail":1}');
+  const e = tag("Real", untyped);
+  assert.equal(e._tag, "Real");
+});
+
+test("matchTags dispatches on the tag", () => {
+  type E = Tagged<"NotFound"> | (Tagged<"Denied"> & { who: string });
+  const describe = (e: E) =>
+    matchTags(e, {
+      NotFound: () => "missing",
+      Denied: (d) => `denied:${d.who}`,
+    });
+  assert.equal(describe(tag("NotFound")), "missing");
+  assert.equal(describe(tag("Denied", { who: "bob" })), "denied:bob");
+});
+
+test("tag distributes a union tag into a discriminated union for matchTags", () => {
+  // `outcome` is a plain string union, as returned by e.g. a land/merge step.
+  const dispatch = (outcome: "merged" | "queued" | "blocked", detail: string) =>
+    matchTags(tag(outcome, { detail }), {
+      merged: () => "done",
+      queued: () => "waiting",
+      // The shared `detail` prop is present on every variant.
+      blocked: (b) => `blocked:${b.detail}`,
+    });
+  assert.equal(dispatch("merged", "x"), "done");
+  assert.equal(dispatch("queued", "x"), "waiting");
+  assert.equal(dispatch("blocked", "perms"), "blocked:perms");
+});
+
+test("scoped releases resources LIFO on success", async () => {
+  const released: string[] = [];
+  const out = await scoped(async (scope) => {
+    acquireRelease(scope, () => "a", () => { released.push("a"); });
+    acquireRelease(scope, () => "b", () => { released.push("b"); });
+    return "done";
+  });
+  assert.equal(out, "done");
+  assert.deepEqual(released, ["b", "a"]);
+});
+
+test("scoped releases resources even when the body throws", async () => {
+  const released: string[] = [];
+  await assert.rejects(
+    scoped(async (scope) => {
+      acquireRelease(scope, () => "a", () => { released.push("a"); });
+      acquireRelease(scope, () => "b", () => { released.push("b"); });
+      throw new Error("kaboom");
+    }),
+    /kaboom/,
+  );
+  assert.deepEqual(released, ["b", "a"]);
+});
+
+test("scoped best-effort: a failing disposer does not block the others", async () => {
+  const released: string[] = [];
+  await scoped(async (scope) => {
+    acquireRelease(scope, () => "a", () => { released.push("a"); });
+    acquireRelease(scope, () => "b", () => { throw new Error("dispose fail"); });
+    acquireRelease(scope, () => "c", () => { released.push("c"); });
+    return null;
+  });
+  // b's disposer threw but a and c still ran (LIFO: c, [b throws], a).
+  assert.deepEqual(released, ["c", "a"]);
+});

package/src/effect/index.ts

@@ -0,0 +1,193 @@
+// effectlite — a tiny, ZERO-DEPENDENCY, Effect-like core for Urban glue code.
+//
+// Urban's published surface is declarative JSON + a client renderer, so we do
+// NOT want the `effect` package (bundle weight + viral paradigm) in the runtime.
+// But the imperative seams — workers, provisioning, resource lifecycles — still
+// benefit from the three Effect ergonomics we actually reach for. effectlite
+// gives us those, in ~100 LOC of implementation with no runtime dependencies:
+//
+//   1. A typed-error `Result<A, E>` whose `E` composes automatically through
+//      generator do-notation (`gen(function*(){ const x = yield* step })`),
+//      short-circuiting on the first failure exactly like `Effect.gen` + `yield*`.
+//   2. `tag()` tagged errors (cf. `Data.TaggedError`) + exhaustive `matchTags`
+//      (cf. `catchTags`) — the compiler forces every failure mode to be handled.
+//   3. `scoped` + `acquireRelease` (cf. `Effect.scoped`) — releases run on every
+//      exit: success, failure, and thrown.
+//
+// It is synchronous over `Result`; the scope is async only so disposers may
+// await. Consume via `import { gen, ok, fail } from "@nanobpm/urban/effect"`.
+
+// ---------------------------------------------------------------------------
+// Result + generator do-notation
+// ---------------------------------------------------------------------------
+
+export type Result<A, E> = Ok<A> | Fail<E>;
+
+export class Ok<A> {
+  readonly _tag = "Ok" as const;
+  readonly value: A;
+  constructor(value: A) {
+    this.value = value;
+  }
+  // Delegated by `yield*`: returns the value, yields nothing to the driver.
+  *[Symbol.iterator](): Generator<never, A, unknown> {
+    return this.value;
+  }
+}
+
+export class Fail<E> {
+  readonly _tag = "Fail" as const;
+  readonly error: E;
+  constructor(error: E) {
+    this.error = error;
+  }
+  // Delegated by `yield*`: yields itself so the driver can short-circuit; never
+  // resumes (the driver abandons the generator on the first failure).
+  *[Symbol.iterator](): Generator<Fail<E>, never, unknown> {
+    yield this;
+    throw new Error("effectlite: generator resumed after a failure");
+  }
+}
+
+export const ok = <A>(value: A): Ok<A> => new Ok(value);
+export const fail = <E>(error: E): Fail<E> => new Fail(error);
+
+export const isOk = <A, E>(r: Result<A, E>): r is Ok<A> => r._tag === "Ok";
+export const isFail = <A, E>(r: Result<A, E>): r is Fail<E> => r._tag === "Fail";
+
+// Run a generator that `yield*`s Results. Because only `Fail` yields to us, a
+// single `next()` either lands on the first failure or on the final return.
+// `Y` captures the UNION of every yielded `Fail<…>`; `Y["error"]` distributes
+// that index access into the Result's error channel (a union in ⇒ a union out).
+export function gen<Y extends Fail<unknown>, A>(
+  body: () => Generator<Y, A, unknown>,
+): Result<A, Y["error"]> {
+  // Typed as `Iterator` (not `Generator`) so `return` is the optional-arg
+  // variant — lets us close a short-circuited body without inventing a return value.
+  const it: Iterator<Y, A> = body();
+  const step = it.next();
+  if (step.done) return ok(step.value);
+  // Not done ⇒ a `Fail` yielded to short-circuit. Close the generator first so
+  // any `try/finally` in the body runs and captured resources aren't retained,
+  // then surface its error on the failure channel.
+  it.return?.();
+  return fail(step.value.error);
+}
+
+// ---------------------------------------------------------------------------
+// Combinators
+// ---------------------------------------------------------------------------
+
+// Extract the success/error channels from a `Result` (including a value typed as
+// the union `Result<A, E>`), so the combinators below infer `A`/`E` cleanly
+// instead of collapsing them to `unknown` on union inputs.
+export type OkOf<R> = R extends Ok<infer A> ? A : never;
+export type ErrOf<R> = R extends Fail<infer E> ? E : never;
+
+// Narrowing guards that carry the *extracted* channel type, so `r.value` /
+// `r.error` land as `OkOf<R>` / `ErrOf<R>` (not `unknown`) with no assertion —
+// keeping the combinators within the repo's no-type-assertion convention.
+const isOkOf = <R extends Result<unknown, unknown>>(r: R): r is R & Ok<OkOf<R>> => r._tag === "Ok";
+const isFailOf = <R extends Result<unknown, unknown>>(r: R): r is R & Fail<ErrOf<R>> => r._tag === "Fail";
+
+export const map = <R extends Result<unknown, unknown>, B>(
+  r: R,
+  f: (a: OkOf<R>) => B,
+): Result<B, ErrOf<R>> => {
+  if (isOkOf(r)) return ok(f(r.value));
+  if (isFailOf(r)) return r;
+  throw new Error("effectlite: Result was neither Ok nor Fail");
+};
+
+export const mapError = <R extends Result<unknown, unknown>, E2>(
+  r: R,
+  f: (e: ErrOf<R>) => E2,
+): Result<OkOf<R>, E2> => {
+  if (isFailOf(r)) return fail(f(r.error));
+  if (isOkOf(r)) return r;
+  throw new Error("effectlite: Result was neither Ok nor Fail");
+};
+
+export const match = <R extends Result<unknown, unknown>, T>(
+  r: R,
+  onOk: (a: OkOf<R>) => T,
+  onFail: (e: ErrOf<R>) => T,
+): T => {
+  if (isOkOf(r)) return onOk(r.value);
+  if (isFailOf(r)) return onFail(r.error);
+  throw new Error("effectlite: Result was neither Ok nor Fail");
+};
+
+// ---------------------------------------------------------------------------
+// Tagged errors + exhaustive matching
+// ---------------------------------------------------------------------------
+
+export type Tagged<Tag extends string> = { readonly _tag: Tag };
+
+// A distributive `Tagged<Tag> & P`: when `Tag` is a union (e.g. a
+// `"merged" | "queued" | "blocked"` outcome), this expands to a discriminated
+// UNION of tagged objects — `({_tag:"merged"} & P) | ({_tag:"queued"} & P) | …`
+// — not a single object with a union-typed `_tag`. That is what lets `matchTags`
+// `Extract` each variant and force an exhaustive handler per case.
+export type TagUnion<Tag extends string, P> = Tag extends string ? Tagged<Tag> & P : never;
+
+// Overloaded so the extra props type only appears when props are actually
+// passed: `tag("X")` is exactly `Tagged<"X">` (no phantom `& P` that could read
+// as `undefined` at runtime), while `tag("X", props)` carries them. Both return
+// the distributive `TagUnion`, so a union `Tag` expands to a discriminated union.
+// `props` is forbidden from carrying its own `_tag` (`{ _tag?: never }`) so it
+// cannot shadow the discriminant, and the runtime spreads `props` *first* so the
+// tag always wins even for props arriving through an untyped boundary.
+export function tag<Tag extends string>(t: Tag): TagUnion<Tag, {}>;
+export function tag<Tag extends string, P extends object>(
+  t: Tag,
+  props: P & { _tag?: never },
+): TagUnion<Tag, P>;
+export function tag(t: string, props?: object): Tagged<string> {
+  return { ...props, _tag: t };
+}
+
+// Handle every tag in the union — the handlers object is keyed by `E["_tag"]`,
+// so omitting a variant is a COMPILE error (no accidental dropped failure mode).
+export const matchTags = <E extends Tagged<string>, R>(
+  e: E,
+  handlers: { [K in E["_tag"]]: (e: Extract<E, Tagged<K>>) => R },
+): R =>
+  // biome-ignore lint/plugin: the mapped handler type is precise for callers; internally we index it with the runtime tag, which needs this erasure to a plain record.
+  (handlers as unknown as Record<string, (e: E) => R>)[e._tag](e);
+
+// ---------------------------------------------------------------------------
+// Scoped resources
+// ---------------------------------------------------------------------------
+
+export class Scope {
+  #disposers: Array<() => void | Promise<void>> = [];
+  add(dispose: () => void | Promise<void>): void {
+    this.#disposers.push(dispose);
+  }
+  async close(): Promise<void> {
+    // LIFO, best-effort — a failing disposer never blocks the others.
+    for (const d of this.#disposers.reverse()) {
+      try { await d(); } catch { /* best effort */ }
+    }
+    this.#disposers = [];
+  }
+}
+
+// Acquire a resource and register its release with the scope in one step.
+export function acquireRelease<A>(scope: Scope, acquire: () => A, release: (a: A) => void | Promise<void>): A {
+  const a = acquire();
+  scope.add(() => release(a));
+  return a;
+}
+
+// Run `body` with a fresh scope; close it (releasing all resources) on every
+// exit path — return, Result failure, or thrown.
+export async function scoped<A>(body: (scope: Scope) => A | Promise<A>): Promise<A> {
+  const scope = new Scope();
+  try {
+    return await body(scope);
+  } finally {
+    await scope.close();
+  }
+}

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

@@ -364,6 +364,84 @@ test("renderer wires a column's processExplorer link to the console explorer", a
   assert.match(js, /ev\.preventDefault\(\)/);
 });
 
+test("renderer binds a route param: parseRoute splits page/param, filters + text consume it (#134)", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // A route is #/<page>/<url-encoded-param>. parseRoute splits on the FIRST "/"
+  // BEFORE decoding so a param carrying encoded slashes/hashes (a plan_key like
+  // "owner/repo#123") survives; the param segment is decoded verbatim into PARAM.
+  assert.match(js, /const slash = raw\.indexOf\("\/"\)/);
+  assert.match(js, /const paramRaw = slash >= 0 \? raw\.slice\(slash \+ 1\) : ""/);
+  assert.match(js, /param = paramRaw \? decodeURIComponent\(paramRaw\) : ""/);
+  assert.match(js, /let PARAM = parseRoute\(\)\.param/);
+  // renderPage refreshes PARAM from the current route on every (re)render.
+  assert.match(js, /const route = parseRoute\(\);\s*CURRENT = route\.page;\s*PARAM = route\.param;/s);
+  // A datasource filter with { eqParam: true } binds its value to the live PARAM,
+  // so one page template scopes every section to the selected entity.
+  assert.match(js, /else if \(f\.eqParam\) qs\.push\("where=" \+ encodeURIComponent\(f\.field \+ ":" \+ PARAM\)\)/);
+  // {{param}} interpolates into text nodes as DOM text (never markup). A function
+  // replacement inserts PARAM literally, so replacement patterns inside a param id
+  // can't be reinterpreted.
+  assert.match(js, /function interpParam\(s\)/);
+  assert.match(js, /replace\(\/\\\{\\\{param\\\}\\\}\/g, \(\) => PARAM\)/);
+  assert.match(js, /interpParam\(node\.props\.text\)/);
+  // A grid whose active filter binds to the route param renders zero rows (no data
+  // request) when no param is present, rather than emitting a where clause of
+  // field-colon-empty (server reads that as field equals empty string and would
+  // surface empty-valued rows).
+  assert.match(js, /const paramScoped = \(activeFilter \|\| \[\]\)\.some\(\(f\) => f && f\.eqParam\)/);
+  assert.match(js, /paramScoped && PARAM === ""\s*\?\s*\{ rows: \[\] \}/s);
+});
+
+test("renderer wires a column's page link to an in-app scoped hash route", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // link: { kind: "page", page, keyField } → an in-app #/<page>/<key> hash link
+  // (no new tab, no server hit). The page id is safe-id-validated, the key is
+  // trimmed + URL-encoded into the param tail, and a blank/keyless cell stays text.
+  assert.match(js, /col\.link && col\.link\.kind === "page" && col\.link\.page && col\.link\.keyField/);
+  assert.match(js, /safePageId\(col\.link\.page\)/);
+  assert.match(js, /"#\/" \+ encodeURIComponent\(col\.link\.page\) \+ "\/" \+ encodeURIComponent\(keyStr\)/);
+  // In-app: NOT a new-tab link (no target/rel on this anchor).
+  assert.match(js, /el\("a", \{ class: "pc-link", href \}, text\)/);
+});
+
+test("renderer groups a dataGrid by a field into persisted collapsible bands (waves)", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // groupBy partitions rows into collapsible groups; each header toggles its
+  // members as a unit and the collapsed state is persisted (survives poll+reload).
+  assert.match(js, /function appendRows\(rows\)/);
+  assert.match(js, /const groupBy = p\.groupBy/);
+  assert.match(js, /if \(!groupBy \|\| typeof groupBy !== "string"\) \{ for \(const row of rows\) renderRow\(row, null\); return; \}/);
+  // Numeric-aware ascending group order (waves 1,2,10 sort naturally).
+  assert.match(js, /const na = Number\(a\), nb = Number\(b\)/);
+  // Collapsed state persisted per page + node + group value via the shared helpers.
+  assert.match(js, /readCollapsed\(gkey, !!p\.groupDefaultCollapsed\)/);
+  assert.match(js, /writeCollapsed\(gkey, gcollapsed\)/);
+  assert.match(js, /"pc:collapsed:" \+ CURRENT \+ ":" \+ \(node\.id \|\| p\.title \|\| "grid"\) \+ ":g:" \+ gv/);
+  // A collapsed group hides every member row; expanded restores data rows and
+  // leaves detail rows at their own expansion state.
+  assert.match(js, /m\.tr\.hidden = gcollapsed/);
+  assert.match(js, /class: "pc-group-header"/);
+  // The group toggle exposes its expanded/collapsed state to assistive tech,
+  // mirroring makeCollapsible's header (screen readers announce the change).
+  assert.match(js, /btn\.setAttribute\("aria-expanded", String\(!gcollapsed\)\)/);
+  // refresh() renders through appendRows so grouping applies on every poll.
+  assert.match(js, /tbody\.replaceChildren\(\);\s*appendRows\(rows\);/s);
+});
+
+test("renderer supports an opt-in sticky nav bar", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  const css = (await dispatch("GET", "/")).body ?? "";
+  // A bar nav with { sticky: true } gets the pc-sticky class (rails are excluded).
+  assert.match(js, /const barSticky = !rail && p\.sticky === true/);
+  assert.match(js, /\(barSticky \? " pc-sticky" : ""\)/);
+  // The CSS pins it to the viewport top with a solid background.
+  assert.match(css, /\.pc-bar\.pc-sticky \{[^}]*position:sticky[^}]*top:0/);
+});
+
 test("renderer exposes an embed-gated host-navigation bridge", async () => {
   const res = await dispatch("GET", "/app/runtime.js");
   const js = res.body ?? "";
@@ -489,8 +567,15 @@ test("the renderer routes between pages by hash and tears down grid polls", asyn
   assert.match(js, /const PAGE_ID = \/\^\[A-Za-z0-9_-/);
   assert.match(js, /function safePageId\(value\)/);
   assert.match(js, /function currentPage\(\)/);
-  assert.match(js, /try \{\s*const raw = decodeURIComponent/s);
-  assert.match(js, /catch \(e\) \{\s*return HOME;/s);
+  // The hash is parsed into a page + optional param by parseRoute(); the page
+  // segment is decoded and safe-id-validated (falling back to HOME).
+  assert.match(js, /function parseRoute\(\)/);
+  assert.match(js, /const raw = \(location\.hash \|\| ""\)\.replace/s);
+  assert.match(js, /if \(safePageId\(p\)\) \{ page = p; pageOk = true; \}/s);
+  // A stray param is only carried when the page segment resolved to a real page,
+  // so a malformed/unknown page (#/not-a-page/x) falls back to HOME without
+  // inheriting x (which would otherwise silently scope home's eqParam grids).
+  assert.match(js, /if \(pageOk\) \{ try \{ param = paramRaw \? decodeURIComponent\(paramRaw\) : ""; \}/s);
   assert.match(js, /location\.hash/);
   assert.match(js, /window\.addEventListener\("hashchange", renderPage\)/);
   assert.match(js, /async function renderPage\(\)/);

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

@@ -569,6 +569,12 @@ table.pc-grid th { font-weight:600; color:var(--nano-text-muted); }
 .pc-collapse-header { display:flex; align-items:center; gap:.5rem; width:100%; margin:0 0 .75rem; padding:0; background:transparent; border:0; color:inherit; font:inherit; font-size:1rem; font-weight:600; cursor:pointer; text-align:left; }
 .pc-chevron-inline { color:var(--nano-text-faint); font-size:.75rem; width:1em; }
 .pc-card-body[hidden] { display:none; }
+/* Grid group headers (dataGrid groupBy): a full-width, clickable band that
+   collapses/expands its member rows; the collapsed state is persisted. */
+.pc-group-header td { padding:0; background:var(--nano-inset); border-top:1px solid var(--nano-edge); }
+.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; }
 /* 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); }
@@ -585,6 +591,11 @@ table.pc-grid th { font-weight:600; color:var(--nano-text-muted); }
 .pc-main-col { flex:1 1 auto; min-width:0; }
 .pc-nav-title { font-weight:650; }
 .pc-bar { display:flex; align-items:center; gap:.6rem; flex-wrap:wrap; border-bottom:1px solid var(--nano-edge); padding-bottom:.6rem; margin-bottom:1.25rem; }
+/* Opt-in sticky bar: stays pinned to the viewport top while the page scrolls.
+   The negative inline margin + matching padding lets its background span the
+   body's 2rem inline padding so scrolled content never shows beside it, and a
+   solid app-colored background hides content passing underneath. */
+.pc-bar.pc-sticky { position:sticky; top:0; z-index:20; background:var(--nano-app); margin-inline:-2rem; padding-inline:2rem; padding-top:.6rem; }
 .pc-bar .pc-nav-title { margin-right:.5rem; }
 .pc-bar .pc-nav-items { display:flex; gap:.25rem; flex-wrap:wrap; }
 .pc-rail { display:flex; flex-direction:column; gap:.5rem; }
@@ -615,15 +626,34 @@ const PAGE_ID = /^[A-Za-z0-9_-]+$/;
 function safePageId(value) {
   return typeof value === "string" && PAGE_ID.test(value);
 }
-function currentPage() {
-  try {
-    const raw = decodeURIComponent((location.hash || "").replace(/^#\/?/, ""));
-    return safePageId(raw) ? raw : HOME;
-  } catch (e) {
-    return HOME;
-  }
+// A route is #/<page> or #/<page>/<url-encoded-param>. We split on the FIRST
+// "/" *before* decoding, so a param that itself contains encoded slashes or
+// hashes (e.g. a plan_key "owner/repo#123" carried as "owner%2Frepo%23123")
+// survives intact instead of the inner "%2F" being decoded into a second
+// segment. The page segment is still restricted to the safe id charset; the
+// param is opaque free text (bound only as a whitelisted '?' SQL value, or
+// interpolated as DOM text — never as HTML/markup).
+function parseRoute() {
+  const raw = (location.hash || "").replace(/^#\/?/, "");
+  const slash = raw.indexOf("/");
+  const pageRaw = slash >= 0 ? raw.slice(0, slash) : raw;
+  const paramRaw = slash >= 0 ? raw.slice(slash + 1) : "";
+  let page = HOME, param = "", pageOk = false;
+  try { const p = decodeURIComponent(pageRaw); if (safePageId(p)) { page = p; pageOk = true; } } catch (e) { /* keep HOME */ }
+  // Only carry the param when the page segment resolved to a real (safe-id) page.
+  // A malformed/unknown page like #/not-a-page/x falls back to HOME and must NOT
+  // inherit x, or that stray param would silently scope every eqParam grid and
+  // {{param}} on the home page to an entity the user never selected.
+  if (pageOk) { try { param = paramRaw ? decodeURIComponent(paramRaw) : ""; } catch (e) { param = ""; } }
+  return { page, param };
 }
+function currentPage() { return parseRoute().page; }
 let CURRENT = currentPage();
+// The current route param (the "/<param>" tail, or "" when absent). Exposed to a
+// page's datasource filters (a filter with { eqParam: true } binds its value to
+// this) and to {{param}} text interpolation, so one page template can scope
+// every section to a selected entity (e.g. an epic's plan_key).
+let PARAM = parseRoute().param;
 
 // Per-render teardown. Each dataGrid registers its poll interval + pc:refresh
 // listener here; navigating to another page runs every disposer before the new
@@ -792,10 +822,19 @@ function el(tag, attrs = {}, ...kids) {
   return n;
 }
 
+// Interpolate the {{param}} token in a schema-supplied string with the current
+// route param. The result is only ever set as DOM text (textContent), so the
+// substituted value cannot inject markup. Other tokens are left untouched.
+// A function replacement inserts PARAM literally; a plain string replacement would
+// treat replacement patterns inside PARAM (an id like the dollar-one token) as
+// special and render the wrong text.
+function interpParam(s) {
+  return typeof s === "string" ? s.replace(/\{\{param\}\}/g, () => PARAM) : s;
+}
 function renderText(node) {
   const v = node.props.variant;
   const cls = v === "heading" ? "pc-heading" : v === "sub" ? "pc-sub" : "pc-body";
-  return el(v === "heading" ? "h1" : "p", { class: cls }, node.props.text || "");
+  return el(v === "heading" ? "h1" : "p", { class: cls }, interpParam(node.props.text) || "");
 }
 
 // Copy text to the clipboard, resiliently. The async Clipboard API is tried
@@ -989,6 +1028,20 @@ function gridCell(col, row) {
       );
     }
   }
+  if (col.link && col.link.kind === "page" && col.link.page && col.link.keyField) {
+    // An in-app link to another page, scoped to this row: #/<page>/<key>. The
+    // key (e.g. a plan_key "owner/repo#123") is URL-encoded into the route's
+    // param tail, which parseRoute() decodes back verbatim; the page id is
+    // validated against the safe-id charset and the key must be non-empty, so a
+    // blank/keyless cell stays plain text. Navigation is a pure hash change
+    // (no new tab, no server hit) — the SPA router re-renders in place.
+    const key = row[col.link.keyField];
+    const keyStr = key == null ? "" : String(key).trim();
+    if (text !== "" && safePageId(col.link.page) && keyStr !== "") {
+      const href = "#/" + encodeURIComponent(col.link.page) + "/" + encodeURIComponent(keyStr);
+      return el("td", {}, el("a", { class: "pc-link", href }, text));
+    }
+  }
   if (col.link && col.link.kind === "processExplorer" && col.link.keyField) {
     const key = row[col.link.keyField];
     const keyStr = key == null ? "" : String(key).trim();
@@ -1161,6 +1214,7 @@ function renderDataGrid(node) {
     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")));
@@ -1291,7 +1345,7 @@ function renderDataGrid(node) {
     return box;
   }
 
-  function renderRow(row) {
+  function renderRow(row, sink) {
     const cells = cols.map((c) => gridCell(c, row));
     const key = rowKeyOf(row);
     let toggle = null;
@@ -1309,6 +1363,9 @@ function renderDataGrid(node) {
     }
     const tr = el("tr", {}, ...cells);
     tbody.append(tr);
+    // When grouping, the caller collects every <tr> this row produced (the data
+    // row plus any detail row) so a group header can hide/show them as one unit.
+    if (sink) sink.push({ tr, isDetail: false, key });
     if (detail && toggle) {
       const isOpen = key != null && expanded.has(key);
       // Reuse an already-built detail row for an open PR across refreshes so its
@@ -1336,6 +1393,67 @@ function renderDataGrid(node) {
         }
       });
       tbody.append(dtr);
+      if (sink) sink.push({ tr: dtr, isDetail: true, key });
+    }
+  }
+
+  // Append the fetched rows into the tbody, either flat (default) or partitioned
+  // into collapsible groups when the grid declares 'groupBy: "<field>"'. Each
+  // group renders a clickable header row ("<Label> <value> (<count>)") that
+  // collapses/expands its member rows as one unit; the collapsed state is
+  // persisted (localStorage, keyed by page + node + group value) so it survives
+  // both the refresh poll and a full reload — the same durability the top-level
+  // 'collapsible' node wrapper gives. Group order is numeric-aware ascending
+  // (so waves 1,2,10 sort naturally), falling back to lexical for non-numeric
+  // keys. 'groupDefaultCollapsed' seeds each group collapsed until toggled.
+  function appendRows(rows) {
+    const groupBy = p.groupBy;
+    // Treat a non-string groupBy as "no grouping": labelBase calls groupBy.charAt()
+    // below, so a truthy non-string (number/object from a malformed page schema)
+    // would throw at render time and break the whole page instead of one grid.
+    if (!groupBy || typeof groupBy !== "string") { for (const row of rows) renderRow(row, null); return; }
+    const order = [];
+    const groups = new Map();
+    for (const row of rows) {
+      const gvRaw = row[groupBy];
+      const gv = gvRaw == null ? "" : String(gvRaw);
+      if (!groups.has(gv)) { groups.set(gv, []); order.push(gv); }
+      groups.get(gv).push(row);
+    }
+    order.sort((a, b) => {
+      const na = Number(a), nb = Number(b);
+      if (a !== "" && b !== "" && !Number.isNaN(na) && !Number.isNaN(nb)) return na - nb;
+      return a < b ? -1 : a > b ? 1 : 0;
+    });
+    const labelBase = p.groupLabel != null
+      ? String(p.groupLabel)
+      : groupBy.charAt(0).toUpperCase() + groupBy.slice(1);
+    for (const gv of order) {
+      const groupRows = groups.get(gv);
+      const gkey = "pc:collapsed:" + CURRENT + ":" + (node.id || p.title || "grid") + ":g:" + gv;
+      let gcollapsed = readCollapsed(gkey, !!p.groupDefaultCollapsed);
+      const chevron = el("span", { class: "pc-chevron-inline" }, gcollapsed ? "▸" : "▾");
+      const label = (gv === "" ? labelBase + " —" : labelBase + " " + gv) + " (" + groupRows.length + ")";
+      const btn = el("button", { class: "pc-group-toggle", type: "button" },
+        chevron, el("span", { class: "pc-group-title" }, label));
+      tbody.append(el("tr", { class: "pc-group-header" }, el("td", { colspan: span }, btn)));
+      const members = [];
+      for (const row of groupRows) renderRow(row, members);
+      const applyGroup = () => {
+        chevron.textContent = gcollapsed ? "▸" : "▾";
+        btn.setAttribute("aria-expanded", String(!gcollapsed));
+        for (const m of members) {
+          m.tr.hidden = gcollapsed
+            ? true
+            : (m.isDetail ? !(m.key != null && expanded.has(m.key)) : false);
+        }
+      };
+      btn.addEventListener("click", () => {
+        gcollapsed = !gcollapsed;
+        writeCollapsed(gkey, gcollapsed);
+        applyGroup();
+      });
+      applyGroup();
     }
   }
 
@@ -1351,7 +1469,15 @@ function renderDataGrid(node) {
 
   async function refresh() {
     try {
-      const { rows } = await getJSON(dataUrl(p.data.source, p.data.table, activeFilter, p.data.orderBy));
+      // A grid scoped to a route param (any eqParam filter) means "show the rows
+      // for the selected entity". With no param present, PARAM is empty and emitting
+      // a where clause of field-colon-empty would read server-side as field equals
+      // empty string and surface empty-valued rows. That is not the selected entity's
+      // rows (there is no selection), so short-circuit to zero rows without a request.
+      const paramScoped = (activeFilter || []).some((f) => f && f.eqParam);
+      const { rows } = paramScoped && PARAM === ""
+        ? { rows: [] }
+        : await getJSON(dataUrl(p.data.source, p.data.table, activeFilter, p.data.orderBy));
       // 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) {
@@ -1390,7 +1516,7 @@ function renderDataGrid(node) {
         }
       }
       tbody.replaceChildren();
-      for (const row of rows) renderRow(row);
+      appendRows(rows);
       if (!rows.length) tbody.append(el("tr", {}, el("td", { colspan: span }, "No rows")));
       if (keepFocus && active.isConnected) {
         active.focus();
@@ -1457,7 +1583,14 @@ function fillNav(list, items) {
 function renderNav(node) {
   const p = node.props || {};
   const rail = p.variant === "rail";
-  const nav = el("nav", { class: rail ? "pc-nav pc-rail" : "pc-nav pc-bar" });
+  // A bar nav can opt into staying pinned to the top of the viewport while the
+  // page scrolls (sticky) — useful on the long, multi-section operator pages so
+  // the page switcher is always reachable. Rails are already full-height, so the
+  // flag only applies to the bar variant.
+  const barSticky = !rail && p.sticky === true;
+  const nav = el("nav", {
+    class: (rail ? "pc-nav pc-rail" : "pc-nav pc-bar") + (barSticky ? " pc-sticky" : ""),
+  });
   if (p.title != null) nav.append(el("div", { class: "pc-nav-title" }, String(p.title)));
   const list = el("div", { class: "pc-nav-items" });
   nav.append(list);
@@ -1551,7 +1684,9 @@ function makeCollapsible(node, card) {
 // tearing down the previous page's grid polls first.
 async function renderPage() {
   teardown();
-  CURRENT = currentPage();
+  const route = parseRoute();
+  CURRENT = route.page;
+  PARAM = route.param;
   try {
     const doc = await getJSON("/app/pages/" + encodeURIComponent(CURRENT));
     document.title = (doc && doc.title) || "Urban App";