@nanobpm/urban 0.52.0 → 0.53.0

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

@@ -484,6 +484,14 @@ function rendererShell(homePage: string, apiDocsPath?: string): string {
 // console, so the defaults below stand on their own: dark by default, light when
 // the OS asks for it and nothing has themed us. `--pc-*` are kept as thin
 // aliases so existing class rules re-resolve through the shared tokens.
+// The single mobile breakpoint (max-width) for the urban responsive primitive
+// (#268). ONE source of truth: it is interpolated into both the shell CSS
+// `@media` query (which drives the pure-CSS card flip / nav collapse / button
+// stacking) AND the runtime's `matchMedia` mode-switch (which only Tier-2's
+// optional page-level `mobile` layout variant needs), so the two can never
+// drift apart on where "narrow" begins.
+const MOBILE_MAX_WIDTH = "640px";
+
 const RENDERER_CSS = `
 :root {
   color-scheme: dark;
@@ -579,6 +587,30 @@ table.pc-grid th { font-weight:600; color:var(--nano-text-muted); }
 .pc-count-badge { color:var(--nano-text); background:var(--nano-inset); border:1px solid var(--nano-edge); font-weight:600; }
 :root[data-appearance="light"] .pc-badge-warn { color:#fff; }
 @media (prefers-color-scheme: light) { :root:not([data-appearance]) .pc-badge-warn { color:#fff; } }
+/* Pipeline / stepper cell (issue #265): a per-row, multi-stage horizontal
+   progress track rendered by pipelineCell. Only the track/stage chrome lives
+   here (the .pc-pipe classes); the active-stage badge and locus links reuse the
+   .pc-badge and .pc-link classes.
+   All colours come from the shared --nano-* tokens so light/dark themes work.
+   Stage treatments: done = filled/ok-tinted, active = lit accent, active+ok =
+   success (✓), active+failed = danger (✕), active+blocked = warn (⊘), upcoming =
+   faint/ghosted, skip (not-in-path) = dashed. */
+.pc-pipe { display:flex; align-items:center; flex-wrap:wrap; gap:.15rem; font-size:.8rem; }
+.pc-pipe-stage { display:inline-flex; align-items:center; gap:.3rem; padding:.12rem .5rem; border:1px solid var(--nano-edge); border-radius:999px; background:transparent; color:var(--nano-text-muted); white-space:nowrap; }
+.pc-pipe-label { color:inherit; }
+.pc-pipe-mark { font-weight:700; line-height:1; }
+.pc-pipe-conn { flex:0 0 auto; width:.9rem; height:2px; border-radius:1px; background:var(--nano-edge); }
+.pc-pipe-conn.filled { background:var(--nano-ok); }
+.pc-pipe-done { color:var(--nano-text); border-color:var(--nano-ok); background:var(--nano-hover); }
+.pc-pipe-active { color:var(--nano-text); font-weight:650; border-color:var(--nano-accent); background:var(--nano-hover); box-shadow:0 0 0 1px var(--nano-accent) inset; }
+.pc-pipe-active.pc-pipe-ok { border-color:var(--nano-ok); box-shadow:0 0 0 1px var(--nano-ok) inset; }
+.pc-pipe-active.pc-pipe-ok .pc-pipe-mark { color:var(--nano-ok); }
+.pc-pipe-active.pc-pipe-failed { border-color:var(--nano-danger); box-shadow:0 0 0 1px var(--nano-danger) inset; }
+.pc-pipe-active.pc-pipe-failed .pc-pipe-mark { color:var(--nano-danger); }
+.pc-pipe-active.pc-pipe-blocked { border-color:var(--nano-warn); box-shadow:0 0 0 1px var(--nano-warn) inset; }
+.pc-pipe-active.pc-pipe-blocked .pc-pipe-mark { color:var(--nano-warn); }
+.pc-pipe-upcoming { color:var(--nano-text-faint); border-color:var(--nano-edge); opacity:.75; }
+.pc-pipe-skip { color:var(--nano-text-faint); border-style:dashed; opacity:.6; }
 .pc-child { margin:.6rem 0; }
 .pc-child-title { font-size:.8rem; font-weight:600; color:var(--nano-text-muted); margin-bottom:.25rem; }
 .pc-transcript { white-space:pre-wrap; max-height:22rem; overflow:auto; background:var(--nano-inset); padding:.5rem; border-radius:.4rem; font-size:.8rem; margin-top:.4rem; }
@@ -626,6 +658,79 @@ table.pc-grid th { font-weight:600; color:var(--nano-text-muted); }
 .pc-nav-link.active { background:var(--nano-accent); color:var(--nano-on-accent); }
 .pc-nav-icon { line-height:1; }
 .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
+   mobile @media below. Base-hidden here so a grid renders byte-for-byte
+   unchanged on desktop even when it carries hidden-column hints. */
+.pc-mcard-toggle { display:none; }
+/* ── Urban responsive / mobile primitive (#268) ──────────────────────────
+   Below MOBILE_MAX_WIDTH every app adapts to a phone with ZERO page-schema
+   change. The dense dataGrid — the one primitive CSS alone can't reflow — flips
+   from a wide <table> to a stacked card list purely from the per-cell
+   'data-label' the renderer already stamps on (no JS branching): thead is
+   hidden, each <tr> becomes a bordered card and each <td> a full-width
+   label:value line whose label is the column header. The nav collapses to a
+   thumb-reachable scrollable bottom bar, buttons/form actions go full-width
+   single column, and text reflows on its own. The breakpoint is interpolated
+   from the shared MOBILE_MAX_WIDTH constant so it can't drift from the runtime's
+   matchMedia. */
+@media (max-width:${MOBILE_MAX_WIDTH}) {
+  body { padding:1rem; }
+  /* dataGrid → card list. Once cells are display:block the fixed colgroup width
+     is irrelevant, so a wide table stops overflowing the phone. table-layout is
+     reset to auto so the block cells size to content. */
+  table.pc-grid { table-layout:auto; }
+  table.pc-grid, table.pc-grid tbody, table.pc-grid tr, table.pc-grid td { display:block; width:auto; }
+  table.pc-grid colgroup, table.pc-grid thead { display:none; }
+  table.pc-grid tr { border:1px solid var(--nano-edge); border-radius:.6rem; padding:.55rem .75rem; margin:.6rem 0; background:var(--nano-panel); }
+  table.pc-grid td { border-bottom:0; padding:.15rem 0; display:flex; gap:.75rem; justify-content:space-between; align-items:baseline; }
+  /* label:value — the column header (data-label) prefixes the value as a muted
+     caption on the same line. Suppressed for the title, chip, actions and any
+     colspan (group/empty/error) cells below. */
+  table.pc-grid td[data-label]::before { content:attr(data-label); color:var(--nano-text-muted); font-size:.72rem; font-weight:600; text-transform:uppercase; letter-spacing:.03em; flex:0 0 auto; }
+  /* The derived (or mobile:{priority:"primary"}-hinted) card title leads the
+     card: larger, full width, no label caption. */
+  table.pc-grid td.pc-mcell-primary { display:block; font-size:1rem; font-weight:650; padding-top:.15rem; }
+  table.pc-grid td.pc-mcell-primary::before { content:none; }
+  /* A badge column becomes a left-aligned status chip with no caption. */
+  table.pc-grid td.pc-mcell-chip { justify-content:flex-start; }
+  table.pc-grid td.pc-mcell-chip::before { content:none; }
+  /* An empty badge cell (row value blank) still carries the chip class but has no
+     child content; without this it renders as a blank flex row (padding/gap) that
+     leaves a stray empty line in the card. Collapse those empty chip cells (#268). */
+  table.pc-grid td.pc-mcell-chip:empty { display:none; }
+  /* Low-value (mobile:{priority:"hidden"}) columns drop off the card until the
+     row's "More" toggle opens them; on desktop they render as normal columns. */
+  table.pc-grid td.pc-mcell-hidden { display:none; }
+  table.pc-grid tr.pc-open td.pc-mcell-hidden { display:flex; }
+  .pc-mcard-toggle { display:block; padding:.3rem 0 0; }
+  .pc-mcard-toggle .pc-more { width:100%; margin-right:0; }
+  /* Row actions stack full-width under the card body. */
+  table.pc-grid td.pc-row-actions { display:flex; flex-wrap:wrap; gap:.4rem; text-align:left; padding-top:.45rem; white-space:normal; }
+  table.pc-grid td.pc-row-actions::before { content:none; }
+  table.pc-grid td.pc-row-actions .pc-btn { flex:1 1 auto; margin-right:0; }
+  /* Group-header + empty/error rows span the full card width with no caption. */
+  table.pc-grid td[colspan] { display:block; }
+  table.pc-grid td[colspan]::before { content:none; }
+  .pc-group-header td { padding:0; }
+  /* Nav → horizontally-scrollable bar (bar) / inline stack (rail). The bar keeps
+     its normal top-of-flow position and scrolls sideways when the pages overflow;
+     an opt-in sticky bar stays pinned to the top via the desktop .pc-sticky rule
+     (top:0). A rail drops its fixed side column and flows inline. */
+  .pc-layout { display:block; }
+  .pc-rail-wrap { position:static; flex-basis:auto; width:auto; margin:0 0 1rem; }
+  .pc-rail .pc-nav-items { flex-direction:row; flex-wrap:wrap; }
+  .pc-bar { flex-wrap:nowrap; overflow-x:auto; }
+  .pc-bar.pc-sticky { position:sticky; }
+  .pc-bar .pc-nav-items { flex-wrap:nowrap; }
+  .pc-nav-link { white-space:nowrap; }
+  .pc-tabs { overflow-x:auto; }
+  /* Buttons / form actions go full-width single-column. */
+  .pc-buttonrow .pc-btn, .pc-card .pc-btn { width:100%; }
+  .pc-modal { max-width:100%; }
+  .pc-modal-actions { flex-direction:column; }
+  .pc-modal-actions .pc-btn { width:100%; }
+}
 `;
 
 // The schema-driven browser renderer (ADR 0042 §3). Plain ES module string served at
@@ -636,6 +741,14 @@ const RENDERER_JS = String.raw`
 const root = document.getElementById("page");
 const HOME = root.dataset.home || "home";
 
+// Single mobile breakpoint, interpolated from the same MOBILE_MAX_WIDTH constant
+// as the shell CSS @media so the JS mode-switch and the pure-CSS card flip can
+// never drift on where "narrow" begins (#268). Only Tier-2 (an optional
+// page-level 'mobile' layout variant) needs this JS switch — the dataGrid card
+// flip, nav collapse and button/form stacking are all pure CSS + data-label.
+const MOBILE_MQ = window.matchMedia("(max-width:${MOBILE_MAX_WIDTH})");
+function isNarrow() { return MOBILE_MQ.matches; }
+
 // ── Multi-page routing (hash-based, reverse-proxy safe) ──────────────────
 // Pages are selected by the URL fragment (#/<page>) so navigation never hits
 // the server and works identically at the origin root and under the Nano
@@ -674,6 +787,12 @@ let CURRENT = currentPage();
 // 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;
+// Monotonic render token. renderPage() is async and fires from both hashchange
+// and the matchMedia viewport-crossing handler, so two invocations can overlap
+// and their fetches resolve out of order. Each render captures the token it
+// bumped to; after its await it only touches the DOM if it is still the latest,
+// so a stale navigation/viewport render can't overwrite a newer one.
+let renderSeq = 0;
 
 // Per-render teardown. Each dataGrid registers its poll interval + pc:refresh
 // listener here; navigating to another page runs every disposer before the new
@@ -1058,7 +1177,45 @@ function renderButton(node) {
 // width/weight — see buildColgroup — to give the clip a bounded column). The
 // subtitle is ALWAYS plain DOM text, never an href source. With none of these
 // set the cell is a single inline node exactly as before (see cellTd).
-function gridCell(col, row) {
+// Build an in-app hash route to another page, scoped to a row key: #/<page>/<key>.
+// The page id is validated against the safe-id charset and the key must be
+// non-empty (after trimming); either failing yields "" (no link). The key is
+// URL-encoded into the route's param tail, which parseRoute() decodes back
+// verbatim, so row data can't smuggle a path or scheme. SINGLE source of truth
+// for the page-link href so the grid's link cell and the pipeline locus link
+// (issue #265) can't drift on how the route is built.
+function pageHashHref(page, key) {
+  const keyStr = key == null ? "" : String(key).trim();
+  if (!safePageId(page) || keyStr === "") return "";
+  return "#/" + encodeURIComponent(page) + "/" + encodeURIComponent(keyStr);
+}
+
+// Coerce a not-in-path value (issue #265) into a Set of stage keys. Accepts an
+// array of keys or a comma/whitespace-separated string; null/undefined → empty
+// set. Used to mark the stages a given row skips (dashed/omitted).
+function toStageSet(v) {
+  // Trim + drop-empties on BOTH inputs so array entries with stray whitespace
+  // (e.g. from CSV/JSON munging) match stages[].key just like the string path.
+  if (Array.isArray(v)) return new Set(v.map((s) => String(s).trim()).filter((s) => s !== ""));
+  if (v == null) return new Set();
+  return new Set(String(v).split(/[\s,]+/).filter((s) => s !== ""));
+}
+
+function gridCell(col, row, role) {
+  // Mobile card attributes stamped on every td so a dataGrid can flip to a
+  // stacked card list below the breakpoint with no JS branching (#268):
+  // 'data-label' drives the pure-CSS label:value line (the column header, or a
+  // mobile:{label} override), and the role class picks the card region (title /
+  // status chip / secondary field / hidden). The role is derived by convention
+  // (classifyColumns) and refinable per-column via col.mobile.priority.
+  const mrole = role || "secondary";
+  const mlabel =
+    col.mobile && typeof col.mobile.label === "string"
+      ? col.mobile.label
+      : col.header != null
+        ? String(col.header)
+        : String(col.field == null ? "" : col.field);
+  const mob = { class: "pc-mcell pc-mcell-" + mrole, "data-label": mlabel };
   // Raw single-field value: drives the badge presence gate + tooltip and any
   // field-derived defaults. Kept separate from the (possibly templated) display
   // text so a template never re-lights or blanks a badge.
@@ -1077,13 +1234,17 @@ function gridCell(col, row) {
   //    field text is also mirrored into aria-label so assistive tech announces
   //    the incident/status text (the visible "1" glyph alone is not meaningful).
   if (col.badge) {
-    if (rawText.trim() === "") return el("td", {});
+    // Even when blank, stamp data-label (the "every td carries data-label"
+    // invariant): the cell still collapses on mobile via the pc-mcell-chip:empty
+    // rule (attributes don't defeat :empty), so this keeps empty and non-empty
+    // badge cells consistent without re-lighting the label.
+    if (rawText.trim() === "") return el("td", { class: "pc-mcell pc-mcell-chip", "data-label": mlabel });
     const t = col.badge.tone;
     const tone = t === "warn" || t === "ok" || t === "info" ? t : "danger";
     const label = col.badge.label == null ? "1" : String(col.badge.label);
     return el(
       "td",
-      {},
+      mob,
       el("span", { class: "pc-badge pc-badge-" + tone, title: rawText, "aria-label": rawText }, label),
     );
   }
@@ -1096,6 +1257,14 @@ function gridCell(col, row) {
     col.subtitleField != null && row[col.subtitleField] != null ? String(row[col.subtitleField]) : "";
   const subText = typeof col.subtitleTemplate === "string" ? interpTemplate(col.subtitleTemplate, row) : subRaw;
   const truncate = col.truncate === true;
+  // pipeline (issue #265): a dataGrid column declaring kind:"pipeline" renders
+  // the ordered stages as a per-row horizontal progress track (upstream-filled
+  // → active-lit → downstream-ghosted, not-in-path dashed). It owns the whole
+  // cell, so it returns here before the link chain below. Gated purely on the
+  // discriminator so every existing column mode is untouched when it is absent;
+  // unknown/missing pipeline config degrades to plain cell text (never throws),
+  // exactly as an unrecognised link.kind falls back today.
+  if (col.kind === "pipeline") return pipelineCell(col, row, text, subText, truncate, mob);
   // Primary inline content: an anchor for a valid link mode (checked in the same
   // badge < linkField < link(page) < link(processExplorer) precedence as before),
   // else the plain display text. Each link mode only claims the cell while
@@ -1109,16 +1278,13 @@ function gridCell(col, row) {
     }
   }
   if (primary === text && 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
+    // An in-app link to another page, scoped to this row: #/<page>/<key>. Built
+    // via pageHashHref (the single source of truth for the route): 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);
+    const href = pageHashHref(col.link.page, row[col.link.keyField]);
+    if (text !== "" && href !== "") {
       primary = el("a", { class: "pc-link", href }, text);
     }
   }
@@ -1145,7 +1311,7 @@ function gridCell(col, row) {
       }, text);
     }
   }
-  return cellTd(primary, text, subText, truncate);
+  return cellTd(primary, text, subText, truncate, mob);
 }
 
 // Compose a grid <td> from its primary inline content (a string or an anchor),
@@ -1160,9 +1326,12 @@ function gridCell(col, row) {
 // aria-label= are ALSO mirrored onto it: HTML does not inherit those to
 // descendants, so hovering the link text or naming the anchor for assistive tech
 // would otherwise miss the full value the wrapper carries. The subtitle is set as
-// DOM text only — never an href.
-function cellTd(primary, primaryText, subText, truncate) {
-  if (subText === "" && !truncate) return el("td", {}, primary);
+// DOM text only — never an href. 'tdAttrs' (the mobile card attrs: data-label +
+// role class, see gridCell) is applied to whichever <td> shape is returned so
+// the CSS-only card flip labels every cell identically (#268).
+function cellTd(primary, primaryText, subText, truncate, tdAttrs) {
+  const td = tdAttrs || {};
+  if (subText === "" && !truncate) return el("td", td, primary);
   const mainAttrs = { class: "pc-cell-main" + (truncate ? " pc-truncate" : "") };
   if (truncate && primaryText !== "") {
     mainAttrs.title = primaryText; mainAttrs["aria-label"] = primaryText;
@@ -1171,10 +1340,178 @@ function cellTd(primary, primaryText, subText, truncate) {
     }
   }
   const main = el("div", mainAttrs, primary);
-  if (subText === "") return el("td", {}, main);
+  if (subText === "") return el("td", td, main);
   const subAttrs = { class: "pc-cell-sub" + (truncate ? " pc-truncate" : "") };
   if (truncate) { subAttrs.title = subText; subAttrs["aria-label"] = subText; }
-  return el("td", {}, main, el("div", subAttrs, subText));
+  return el("td", td, main, el("div", subAttrs, subText));
+}
+
+// Classify each grid column into a mobile-card region so a dataGrid flips to a
+// stacked card list below the breakpoint with ZERO page-schema change (#268).
+// Convention (Tier 0): the first non-badge column is the card title (primary), a
+// badge column is a status chip, and everything else is a secondary label:value
+// row. Tier 1 refines it — a column may carry mobile:{priority:"primary" |
+// "secondary" | "hidden"}: an explicit "primary" suppresses the auto title pick
+// so a later column can lead the card, "hidden" drops the column off the card
+// (behind the row's "More" toggle), and "secondary" forces a plain field row.
+function classifyColumns(cols) {
+  const list = cols || [];
+  const explicitPrimary = list.some((c) => c && c.mobile && c.mobile.priority === "primary");
+  let titleTaken = explicitPrimary;
+  return list.map((col) => {
+    const pr = col && col.mobile ? col.mobile.priority : null;
+    if (pr === "primary") return "primary";
+    if (pr === "secondary") return "secondary";
+    if (pr === "hidden") return "hidden";
+    if (col && col.badge) return "chip";
+    if (!titleTaken) { titleTaken = true; return "primary"; }
+    return "secondary";
+  });
+}
+
+// Per-row mobile "More" toggle cell: reveals the mobile:{priority:"hidden"} columns
+// a narrow viewport drops off the card. The cell is base-hidden (display:none) so
+// the desktop table is byte-for-byte unchanged; clicking flips .pc-open on the row,
+// swaps the label, and updates aria-expanded so the reveal state is exposed to
+// assistive tech (#268). One implementation shared by the top-level grid and child
+// grids so the affordance — and its accessibility — can't drift between them.
+function mobileMoreCell(tr) {
+  const moreBtn = el("button",
+    { class: "pc-btn pc-btn-sm pc-btn-ghost pc-more", type: "button", "aria-expanded": "false" }, "More");
+  moreBtn.addEventListener("click", () => {
+    const open = tr.classList.toggle("pc-open");
+    moreBtn.textContent = open ? "Less" : "More";
+    moreBtn.setAttribute("aria-expanded", String(open));
+  });
+  return el("td", { class: "pc-mcard-toggle" }, moreBtn);
+}
+
+// Pipeline / stepper cell (issue #265) — a dataGrid column with kind:"pipeline"
+// renders a per-row, multi-stage horizontal progress track. It is RENDER-ONLY:
+// stage state is read straight from the row fields the app supplies; no
+// app-specific stage derivation lives here. Column config (all fields are the
+// NAMES of row fields, mirroring the issue sketch):
+//   { kind:"pipeline",
+//     stages:[{key,label},...],   // ordered stage definitions (required)
+//     activeField:"stage",        // row field → the current stage's key
+//     stateField:"stage_state",   // row field → ok | active | failed | blocked
+//     badgeField:"attention",     // optional row field → badge text shown on the active stage
+//     notInPathField:"skipped",   // optional row field → stages this row skips
+//     notInPath:["converging"],   // static fallback used only when no field given
+//     locus:{ field:"pr_key", stage?:"<key>",
+//             link:{ kind:"page", page:"home" } } }  // optional out-link
+// Rendering: stages BEFORE the active one are filled/completed, the active stage
+// is lit (its treatment driven by stateField — success ✓ vs failure ✕ vs blocked
+// ⊘ are made unmistakably distinct), in-path stages AFTER it are ghosted, and any
+// stage in the row's not-in-path set is dashed. Reuses the .pc-badge and .pc-link
+// classes and the shared pageHashHref route builder — no parallel implementations. Unknown or
+// missing config (no stages array) degrades gracefully to plain cell text.
+function pipelineCell(col, row, text, subText, truncate, tdAttrs) {
+  // Drop null/undefined entries defensively: a schema with a hole must still
+  // render (never throws on s.key) — same graceful-degradation goal as below.
+  const stages = Array.isArray(col.stages) ? col.stages.filter((s) => s != null) : [];
+  // Graceful fallback: an unrecognised/empty pipeline config renders plain text,
+  // exactly like an unknown link.kind — never throws.
+  if (stages.length === 0) return cellTd(text, text, subText, truncate, tdAttrs);
+  // The current stage's key, matched against stages[].key to find the active index.
+  // The row value is trimmed for consistency with the other row-derived keys
+  // (pageHashHref, toStageSet), so a whitespace-padded value still matches its stage
+  // instead of leaving the whole track rendered as upcoming.
+  // Stage keys identify a single stage, so stop at the first match: the result is
+  // deterministic even if a config accidentally repeats a key, and we avoid scanning
+  // the remaining stages on every row.
+  const activeKey = col.activeField != null && row[col.activeField] != null ? String(row[col.activeField]).trim() : "";
+  let activeIdx = -1;
+  for (let i = 0; i < stages.length; i++) {
+    if (String(stages[i].key) === activeKey) {
+      activeIdx = i;
+      break;
+    }
+  }
+  // The active stage's state drives its lit/failed/blocked treatment. Anything
+  // outside the allow-list (or absent) is treated as an in-progress "active".
+  const stRaw = col.stateField != null && row[col.stateField] != null ? String(row[col.stateField]) : "";
+  const state = stRaw === "ok" || stRaw === "failed" || stRaw === "blocked" ? stRaw : "active";
+  // Not-in-path (skipped) stages: driven per-row from notInPathField when given,
+  // else the static notInPath config (per the issue: "per row, from a field").
+  const skip =
+    col.notInPathField != null && row[col.notInPathField] != null
+      ? toStageSet(row[col.notInPathField])
+      : toStageSet(col.notInPath);
+  // Optional active-stage badge (escalation/attention → warn, blocked/failure →
+  // danger), reusing .pc-badge tone classes — no new badge styles. The badge text
+  // is a single row-level value (row[badgeField]) shown only on the active stage.
+  const badgeText = col.badgeField != null && row[col.badgeField] != null ? String(row[col.badgeField]) : "";
+  const badgeTone = state === "failed" || state === "blocked" ? "danger" : "warn";
+  // Optional locus out-link: the relevant stage (default the active one, or
+  // locus.stage by key) becomes an in-app page link when the row's locus key is
+  // non-empty. Href comes from the shared pageHashHref builder (safePageId guard,
+  // encodeURIComponent) — a blank key yields "" so the stage stays plain.
+  const locus = col.locus;
+  const locusKey = locus && locus.field != null && row[locus.field] != null ? String(row[locus.field]) : "";
+  const locusHref =
+    locus && locus.link && locus.link.kind === "page" && locus.link.page ? pageHashHref(locus.link.page, locusKey) : "";
+  const track = el("div", {
+    class: "pc-pipe",
+    role: "list",
+    "aria-label": "Progress" + (activeIdx >= 0 ? ": " + labelOf(stages[activeIdx]) : ""),
+  });
+  for (let i = 0; i < stages.length; i++) {
+    const s = stages[i];
+    // Active wins over skip: if the active stage's key is also in the not-in-path
+    // set, it must still render as the current step (active styling + aria-current),
+    // never as skipped. Excluding activeIdx here keeps that precedence consistent
+    // across the stage class, the aria-current mark, and the connector fill below.
+    const skipped = i !== activeIdx && skip.has(String(s.key));
+    // Connector between adjacent stages; filled up to and including the active
+    // stage, but never across a not-in-path stage — a skipped predecessor breaks
+    // the fill so we don't visually imply it was on the path.
+    if (i > 0) {
+      const filled =
+        activeIdx >= 0 && i <= activeIdx && !skipped && !skip.has(String(stages[i - 1].key)) ? " filled" : "";
+      track.append(el("span", { class: "pc-pipe-conn" + filled, "aria-hidden": "true" }));
+    }
+    let cls;
+    let word;
+    let glyph = "";
+    let current = false;
+    if (skipped) {
+      cls = "pc-pipe-skip"; word = "skipped";
+    } else if (activeIdx >= 0 && i < activeIdx) {
+      cls = "pc-pipe-done"; word = "completed";
+    } else if (i === activeIdx) {
+      current = true;
+      if (state === "failed") { cls = "pc-pipe-active pc-pipe-failed"; word = "failed"; glyph = "\u2715"; }
+      else if (state === "blocked") { cls = "pc-pipe-active pc-pipe-blocked"; word = "blocked"; glyph = "\u2298"; }
+      else if (state === "ok") { cls = "pc-pipe-active pc-pipe-ok"; word = "done"; glyph = "\u2713"; }
+      else { cls = "pc-pipe-active"; word = "current"; }
+    } else {
+      cls = "pc-pipe-upcoming"; word = "upcoming";
+    }
+    const isLocus = locusHref !== "" && (locus.stage != null ? String(s.key) === String(locus.stage) : i === activeIdx);
+    const label = labelOf(s);
+    const labelNode = isLocus
+      ? el("a", { class: "pc-link pc-pipe-label", href: locusHref }, label)
+      : el("span", { class: "pc-pipe-label" }, label);
+    const attrs = { class: "pc-pipe-stage " + cls, role: "listitem", "aria-label": label + " \u2014 " + word };
+    if (current) attrs["aria-current"] = "step";
+    const stage = el("span", attrs, labelNode);
+    if (glyph !== "") stage.append(el("span", { class: "pc-pipe-mark", "aria-hidden": "true" }, glyph));
+    if (current && badgeText.trim() !== "") {
+      stage.append(el("span", { class: "pc-badge pc-badge-" + badgeTone, title: badgeText, "aria-label": badgeText }, badgeText));
+    }
+    track.append(stage);
+  }
+  // The mobile card attrs (data-label + role class, #268) stamped by gridCell are
+  // merged onto the pipeline <td> too, alongside its own pc-pipe-cell class, so a
+  // pipeline column labels and classifies identically under the CSS-only card flip.
+  const cellAttrs = { ...(tdAttrs || {}), class: (tdAttrs && tdAttrs.class ? tdAttrs.class + " " : "") + "pc-pipe-cell" };
+  return el("td", cellAttrs, track);
+}
+
+// A stage's visible label: its declared label, else its key as a fallback.
+function labelOf(stage) {
+  return stage.label == null ? String(stage.key) : String(stage.label);
 }
 
 // Parse a "<number>%" width into its numeric percentage, or null if the string
@@ -1412,6 +1749,12 @@ function renderDataGrid(node) {
     card.append(h2);
   }
   const cols = p.columns || [];
+  // Mobile card roles per column (derived by convention, refined by
+  // col.mobile.priority) so the grid can flip to a stacked card list on a phone
+  // (#268). 'hasHidden' gates the per-row "More" toggle that reveals the columns
+  // a mobile:{priority:"hidden"} hint drops off the card.
+  const roles = classifyColumns(cols);
+  const hasHidden = roles.indexOf("hidden") >= 0;
   const tabs = p.tabs || [];
   const rowActions = p.rowActions || [];
   const detail = p.detail || null;
@@ -1535,6 +1878,8 @@ function renderDataGrid(node) {
     const wrap = el("div", { class: "pc-child" });
     if (cg.title) wrap.append(el("div", { class: "pc-child-title" }, cg.title));
     const ccols = cg.columns || [];
+    const croles = classifyColumns(ccols);
+    const chasHidden = croles.indexOf("hidden") >= 0;
     const cbody = el("tbody", {});
     const ccolgroup = buildColgroup(ccols, cg.lazyField ? 1 : 0);
     const cthead = el("thead", {}, el("tr", {}, ...ccols.map((c) => el("th", {}, c.header || c.field)),
@@ -1551,7 +1896,7 @@ function renderDataGrid(node) {
         cbody.append(el("tr", {}, el("td", { colspan: cspan }, "None")));
       }
       for (const cr of rows) {
-        const cells = ccols.map((c) => gridCell(c, cr));
+        const cells = ccols.map((c, i) => gridCell(c, cr, croles[i]));
         if (cg.lazyField) {
           const lf = cg.lazyField;
           const has = cr[lf.field] != null && String(cr[lf.field]).trim() !== "";
@@ -1568,7 +1913,13 @@ function renderDataGrid(node) {
           }
           cells.push(cell);
         }
-        cbody.append(el("tr", {}, ...cells));
+        // 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
+        // permanently unreachable on a narrow viewport (#268).
+        const ctr = el("tr", {}, ...cells);
+        if (chasHidden) ctr.append(mobileMoreCell(ctr));
+        cbody.append(ctr);
       }
     } catch (e) {
       cbody.append(el("tr", {}, el("td", { colspan: cspan }, String(e.message || e))));
@@ -1605,7 +1956,7 @@ function renderDataGrid(node) {
   }
 
   function renderRow(row, sink) {
-    const cells = cols.map((c) => gridCell(c, row));
+    const cells = cols.map((c, i) => gridCell(c, row, roles[i]));
     const key = rowKeyOf(row);
     let toggle = null;
     if (hasExtra) {
@@ -1620,7 +1971,12 @@ function renderDataGrid(node) {
       }
       cells.push(actionCell);
     }
+    // Per-row "More" toggle: only when a mobile:{priority:"hidden"} hint drops
+    // columns off the card. Appended after the <tr> is built (the toggle wires a
+    // click against its own row) and shared with child grids via mobileMoreCell so
+    // the reveal affordance and its aria state can't drift (#268).
     const tr = el("tr", {}, ...cells);
+    if (hasHidden) tr.append(mobileMoreCell(tr));
     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.
@@ -1951,19 +2307,31 @@ function makeCollapsible(node, card) {
   return container;
 }
 
+// Tier-2 escape hatch (#268): a page may declare a distinct 'mobile' layout
+// variant — its own node list — for the rare case the derived card flip isn't
+// enough (reorder/omit sections, swap a dense grid for a summary card). It is
+// used ONLY on a narrow viewport; the default 'nodes' render everywhere else,
+// and anything malformed falls back to them, so the variant is purely additive.
+function pickNodes(doc) {
+  if (isNarrow() && doc && doc.mobile && Array.isArray(doc.mobile.nodes)) return doc.mobile.nodes;
+  return (doc && doc.nodes) || [];
+}
+
 // Render the page named by the current hash route. A rail nav is lifted into a
 // left <aside> and the rest of the nodes flow into a content column; otherwise
 // (bar nav or none) nodes render in document order. Re-runs on every hashchange,
 // tearing down the previous page's grid polls first.
 async function renderPage() {
   teardown();
+  const mySeq = ++renderSeq;
   const route = parseRoute();
   CURRENT = route.page;
   PARAM = route.param;
   try {
     const doc = await getJSON("/app/pages/" + encodeURIComponent(CURRENT));
+    if (mySeq !== renderSeq) return;
     document.title = (doc && doc.title) || "Urban App";
-    const nodes = (doc && doc.nodes) || [];
+    const nodes = pickNodes(doc);
     const built = nodes.map((n) => ({ n, node: makeCollapsible(n, (RENDERERS[n.type] || (() => el("div")))(n)) }));
     const rail = built.find((b) => b.n.type === "nav" && b.n.props && b.n.props.variant === "rail");
     if (rail) {
@@ -1974,10 +2342,20 @@ async function renderPage() {
       root.replaceChildren(...built.map((b) => b.node));
     }
   } catch (e) {
+    if (mySeq !== renderSeq) return;
     root.replaceChildren(el("p", { class: "pc-msg err" }, "Failed to load page: " + String((e && e.message) || e)));
   }
 }
 window.addEventListener("hashchange", renderPage);
+// Re-render when the viewport crosses the mobile breakpoint so a Tier-2 'mobile'
+// variant swaps in/out on rotation or a window resize (the grid card flip, nav
+// collapse and button stacking are pure CSS and need no re-render). teardown()
+// inside renderPage stops the outgoing page's grid polls first. Prefer the modern
+// addEventListener but fall back to the deprecated addListener so older Safari/iOS
+// (< 14), where MediaQueryList.addEventListener is unimplemented, still swaps the
+// Tier-2 variant on rotation/resize instead of silently failing to register.
+if (typeof MOBILE_MQ.addEventListener === "function") MOBILE_MQ.addEventListener("change", renderPage);
+else if (typeof MOBILE_MQ.addListener === "function") MOBILE_MQ.addListener(renderPage);
 renderPage();
 `;
 

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

@@ -11,6 +11,7 @@ import type { AppApi, RuntimeContext } from "../context.ts";
 import { presentFormIdentifier } from "../host.ts";
 import { html, json, noContent, normalizeRoutePath, type Route } from "../router.ts";
 import { mountActions } from "./actions.ts";
+import { mountAgent } from "./agent.ts";
 import { mountApi } from "./api.ts";
 import { mountPages } from "./pages.ts";
 
@@ -299,6 +300,14 @@ export function mountSurfaces(ctx: RuntimeContext, app: AppApi): SurfacesHandle
     enabled.push("api");
   }
 
+  // The app-scoped institutional-memory brief (ADR 0060 §2): `/app/agent` + `/app/agent.json`,
+  // the app-level mirror of the node `/agent`. Mounted unconditionally (before the generic pages
+  // routes, though its exact paths never collide) — the brief is a property of the app's models,
+  // not an opt-in surface, and reads through to the `urban gen`-derived artifacts.
+  const agent = mountAgent(ctx);
+  routes.push(...agent.routes);
+  enabled.push("agent@/app/agent");
+
   // The pages surface (the schema-driven page runtime) mounts its own routes.
   const pages = mountPages(ctx, app);
   if (pages.routes.length > 0) {