@nanobpm/urban 0.51.0 → 0.53.0

package/src/runtime/core/modules/lineage-store.ts

@@ -0,0 +1,239 @@
+// lineage-store — the durable read-model projection behind the lineage primitive (issue #254).
+//
+// A framework-level, per-source sidecar (like the write-provenance table) that materialises the
+// lineage edges the SDK auto-threads (`_urban.lineage`) and — where the engine emits it — the
+// native execution edge (`parentProcessInstanceKey`, Magikcraft/nano-bpm#808). `getLineage(root)`
+// unions both and returns the stitched descendant tree for one root request. Apps attach their own
+// domain rows (PRs, tasks) to a node via {@link LineageStore.attach} WITHOUT the framework knowing
+// their schema — the extension point that lets intent→progress visualisation be app-agnostic.
+//
+// The tree assembly itself is the pure {@link buildLineageTree}; this store is only its thin,
+// idempotent persistence + query layer, so recording the same instance twice (an engine job
+// re-activation) collapses to a no-op.
+
+import type { SqliteDb } from "../host.ts";
+import {
+  buildLineageTree,
+  type LineageAttachment,
+  type LineageEdge,
+  type LineageEdgeType,
+  type LineageTree,
+  readLineage,
+} from "../lineage.ts";
+
+/** The lineage edge table name. Framework bookkeeping, so `_urban_`-prefixed to stay hidden from
+ * the domain model / DB Manager (see `SqliteGateway.schema()`), like the migrations ledger. */
+export const LINEAGE_EDGES_TABLE = "_urban_lineage_edges";
+/** The lineage attachment table name (app-registered domain rows on a node). `_urban_`-prefixed for
+ * the same reason as {@link LINEAGE_EDGES_TABLE}. */
+export const LINEAGE_ATTACHMENTS_TABLE = "_urban_lineage_attachments";
+
+/**
+ * The canonical lineage DDL — the single source of truth applied by
+ * {@link LineageStore.ensureSchema}, mirrored verbatim by the boot migration
+ * `db/migrations/004_urban_lineage.sql` (a drift-guard test asserts they match).
+ *
+ * Forward-only and additive. `_urban_lineage_edges` is keyed by `(instance_key, edge_type)` so a
+ * node can hold both its weak (envelope) and strong (execution) edge at once and a re-record is a
+ * no-op; `_urban_lineage_attachments` is keyed by `(node_key, kind, ref)` so re-attaching the same
+ * domain row is idempotent. Both carry `root_request_key` with an index so a `getLineage(root)`
+ * reads only that thread.
+ */
+export const LINEAGE_SCHEMA_SQL = `CREATE TABLE IF NOT EXISTS ${LINEAGE_EDGES_TABLE} (
+  root_request_key       TEXT NOT NULL,
+  instance_key           TEXT NOT NULL,
+  caused_by_instance_key TEXT,
+  edge_type              TEXT NOT NULL DEFAULT 'weak',
+  created_at             TEXT NOT NULL,
+  PRIMARY KEY (instance_key, edge_type)
+);
+CREATE INDEX IF NOT EXISTS idx_${LINEAGE_EDGES_TABLE}_root ON ${LINEAGE_EDGES_TABLE} (root_request_key);
+CREATE TABLE IF NOT EXISTS ${LINEAGE_ATTACHMENTS_TABLE} (
+  root_request_key TEXT NOT NULL,
+  node_key         TEXT NOT NULL,
+  kind             TEXT NOT NULL,
+  ref              TEXT NOT NULL,
+  label            TEXT,
+  created_at       TEXT NOT NULL,
+  PRIMARY KEY (node_key, kind, ref)
+);
+CREATE INDEX IF NOT EXISTS idx_${LINEAGE_ATTACHMENTS_TABLE}_root ON ${LINEAGE_ATTACHMENTS_TABLE} (root_request_key);`;
+
+/** A monotonic wall clock, injectable for deterministic `created_at` in tests. */
+export interface Clock {
+  now(): number;
+}
+
+/** The default clock: `Date.now()`. */
+export const systemClock: Clock = { now: () => Date.now() };
+
+/** A minimal job shape {@link LineageStore.recordFromJob} reads — a structural subset of the
+ *  runtime's `EngineJob` plus the future engine execution edge (`parentProcessInstanceKey`,
+ *  Magikcraft/nano-bpm#808), consumed as a strong edge where present. */
+export interface LineageJobLike {
+  readonly processInstanceKey?: string;
+  readonly variables?: Record<string, unknown>;
+  /** The engine-native execution parent, when the engine emits it (#808). */
+  readonly parentProcessInstanceKey?: string;
+}
+
+export interface LineageStoreOptions {
+  readonly clock?: Clock;
+}
+
+interface EdgeRow {
+  root_request_key: string;
+  instance_key: string;
+  caused_by_instance_key: string | null;
+  edge_type: string;
+}
+
+interface AttachmentRow {
+  root_request_key: string;
+  node_key: string;
+  kind: string;
+  ref: string;
+  label: string | null;
+}
+
+function normalizeEdgeType(raw: string): LineageEdgeType {
+  return raw === "strong" ? "strong" : "weak";
+}
+
+export class LineageStore {
+  readonly #db: SqliteDb;
+  readonly #clock: Clock;
+
+  constructor(db: SqliteDb, options: LineageStoreOptions = {}) {
+    this.#db = db;
+    this.#clock = options.clock ?? systemClock;
+  }
+
+  /** Apply the canonical lineage DDL (idempotent). Callers whose app DataLayer applies the boot
+   *  migration `db/migrations/004_urban_lineage.sql` do not need this; the runtime calls it so the
+   *  store is usable against a bare source too. The DDL is identical to the migration (drift-guarded). */
+  ensureSchema(): void {
+    this.#db.exec(LINEAGE_SCHEMA_SQL);
+  }
+
+  /**
+   * Record one lineage edge, idempotently. A re-record of the same `(instance_key, edge_type)` is a
+   * no-op (an engine may re-activate a job on retry), so recording is safe to drive from any
+   * at-least-once observation point. A blank `rootRequestKey` or `instanceKey` is ignored.
+   */
+  recordEdge(edge: LineageEdge): boolean {
+    if (!edge.rootRequestKey || !edge.instanceKey) return false;
+    const { changes } = this.#db.run(
+      `INSERT OR IGNORE INTO ${LINEAGE_EDGES_TABLE}
+         (root_request_key, instance_key, caused_by_instance_key, edge_type, created_at)
+       VALUES (?, ?, ?, ?, ?)`,
+      [
+        edge.rootRequestKey,
+        edge.instanceKey,
+        edge.causedByInstanceKey ?? null,
+        edge.edgeType,
+        new Date(this.#clock.now()).toISOString(),
+      ],
+    );
+    return changes > 0;
+  }
+
+  /**
+   * Record the WEAK edge carried by an instance's `_urban.lineage` envelope. `instanceKey` is the
+   * effect/descendant node (a created instance's returned key, or a running job's own instance).
+   * A no-op when the variables carry no valid envelope.
+   */
+  recordEnvelope(instanceKey: string | undefined, variables: unknown): boolean {
+    if (!instanceKey) return false;
+    const env = readLineage(variables);
+    if (!env) return false;
+    return this.recordEdge({
+      rootRequestKey: env.rootRequestKey,
+      instanceKey,
+      causedByInstanceKey: env.causedByInstanceKey,
+      edgeType: "weak",
+    });
+  }
+
+  /**
+   * Record every edge an activated job reveals about its own instance: the weak envelope edge, and
+   * — where the engine supplies `parentProcessInstanceKey` (#808) — the strong execution edge under
+   * the same root. The natural single observation point for the worker runtime, since every instance
+   * that does work activates a job carrying its envelope. Never throws for a malformed job.
+   */
+  recordFromJob(job: LineageJobLike): void {
+    const env = readLineage(job.variables);
+    if (!env || !job.processInstanceKey) return;
+    this.recordEnvelope(job.processInstanceKey, job.variables);
+    if (job.parentProcessInstanceKey) {
+      this.recordEdge({
+        rootRequestKey: env.rootRequestKey,
+        instanceKey: job.processInstanceKey,
+        causedByInstanceKey: job.parentProcessInstanceKey,
+        edgeType: "strong",
+      });
+    }
+  }
+
+  /**
+   * Attach an app-defined domain row to a lineage node, idempotently. The framework stores it
+   * opaquely by `(node_key, kind, ref)` — it never interprets the app's schema. This is the
+   * extension point that lets an app hang its PRs/tasks off the lineage tree.
+   */
+  attach(rootRequestKey: string, attachment: LineageAttachment): boolean {
+    if (!rootRequestKey || !attachment.nodeKey || !attachment.kind || !attachment.ref) return false;
+    const { changes } = this.#db.run(
+      `INSERT OR IGNORE INTO ${LINEAGE_ATTACHMENTS_TABLE}
+         (root_request_key, node_key, kind, ref, label, created_at)
+       VALUES (?, ?, ?, ?, ?, ?)`,
+      [
+        rootRequestKey,
+        attachment.nodeKey,
+        attachment.kind,
+        attachment.ref,
+        attachment.label ?? null,
+        new Date(this.#clock.now()).toISOString(),
+      ],
+    );
+    return changes > 0;
+  }
+
+  /** The persisted edges for one root, in insertion order. */
+  edges(rootRequestKey: string): LineageEdge[] {
+    const rows = this.#db.all<EdgeRow>(
+      `SELECT root_request_key, instance_key, caused_by_instance_key, edge_type
+         FROM ${LINEAGE_EDGES_TABLE} WHERE root_request_key = ? ORDER BY rowid`,
+      [rootRequestKey],
+    );
+    return rows.map((r) => ({
+      rootRequestKey: r.root_request_key,
+      instanceKey: r.instance_key,
+      causedByInstanceKey: r.caused_by_instance_key ?? undefined,
+      edgeType: normalizeEdgeType(r.edge_type),
+    }));
+  }
+
+  /** The persisted attachments for one root, in insertion order. */
+  attachments(rootRequestKey: string): LineageAttachment[] {
+    const rows = this.#db.all<AttachmentRow>(
+      `SELECT root_request_key, node_key, kind, ref, label
+         FROM ${LINEAGE_ATTACHMENTS_TABLE} WHERE root_request_key = ? ORDER BY rowid`,
+      [rootRequestKey],
+    );
+    return rows.map((r) => ({
+      nodeKey: r.node_key,
+      kind: r.kind,
+      ref: r.ref,
+      ...(r.label ? { label: r.label } : {}),
+    }));
+  }
+
+  /**
+   * The stitched descendant tree for `rootRequestKey`, unioning the weak (envelope) and strong
+   * (engine execution) edges and hanging each app attachment off its node. The generic read
+   * surface any Urban app queries for intent→progress.
+   */
+  getLineage(rootRequestKey: string): LineageTree {
+    return buildLineageTree(rootRequestKey, this.edges(rootRequestKey), this.attachments(rootRequestKey));
+  }
+}

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

@@ -344,6 +344,14 @@ test("renderer wires a column's badge to a tone-classed pill shown only when pre
   assert.match(js, /class:\s*"pc-badge pc-badge-"\s*\+\s*tone/);
   assert.match(js, /title:\s*rawText/);
   assert.match(js, /"aria-label":\s*rawText/);
+  // Even a blank badge cell stamps data-label, upholding the "every td carries
+  // data-label" invariant so empty and non-empty badge cells stay consistent
+  // (the mobile pc-mcell-chip:empty rule still collapses it — attributes don't
+  // defeat :empty).
+  assert.match(
+    js,
+    /rawText\.trim\(\)\s*===\s*""\s*\)\s*return el\("td",\s*\{ class: "pc-mcell pc-mcell-chip", "data-label": mlabel \}\)/,
+  );
 });
 
 test("renderer interpolates a column's per-cell template into DOM text (#214)", async () => {
@@ -386,7 +394,7 @@ test("renderer renders a column's subtitle as a muted second line, never an href
   assert.match(js, /class: "pc-cell-sub"/);
   // Absent subtitle (empty) and no truncation collapses back to the single inline
   // node, so existing grids render exactly as before (backward compatible).
-  assert.match(js, /if \(subText === "" && !truncate\) return el\("td", \{\}, primary\);/);
+  assert.match(js, /if \(subText === "" && !truncate\) return el\("td", td, primary\);/);
 });
 
 test("renderer truncates a column to one line with an ellipsis + full-text tooltip (#257)", async () => {
@@ -515,11 +523,15 @@ 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.
+  // (no new tab, no server hit). The route is built by the shared pageHashHref
+  // helper: 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\)/);
+  assert.match(js, /const href = pageHashHref\(col\.link\.page, row\[col\.link\.keyField\]\)/);
+  // pageHashHref is the single source of truth: safe-id guard + encoded route.
+  assert.match(js, /function pageHashHref\(page, key\)/);
+  assert.match(js, /if \(!safePageId\(page\) \|\| keyStr === ""\) return ""/);
+  assert.match(js, /"#\/" \+ encodeURIComponent\(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\)/);
 });
@@ -781,6 +793,14 @@ test("the renderer routes between pages by hash and tears down grid polls", asyn
   assert.match(js, /location\.hash/);
   assert.match(js, /window\.addEventListener\("hashchange", renderPage\)/);
   assert.match(js, /async function renderPage\(\)/);
+  // renderPage() fires from both hashchange and the matchMedia viewport handler,
+  // so overlapping async renders must not apply out of order: each captures a
+  // monotonic token and bails after its await if a newer render superseded it
+  // (guarding both the success path and the stale error render).
+  assert.match(js, /let renderSeq = 0/);
+  assert.match(js, /const mySeq = \+\+renderSeq/);
+  assert.match(js, /const doc = await getJSON\([\s\S]*?\);\s*if \(mySeq !== renderSeq\) return;/);
+  assert.match(js, /catch \(e\) \{\s*if \(mySeq !== renderSeq\) return;/);
   // Navigation runs every registered disposer first, so a switched-away grid's
   // poll interval + pc:refresh listener are removed rather than leaking forever.
   assert.match(js, /const disposers = \[\]/);
@@ -1039,3 +1059,287 @@ test("rowLimit respects an explicit 0 and falls back for non-finite values", asy
   await run(undefined);
   assert.deepEqual(limits, ["0", "200", "200"]);
 });
+
+test("the shell ships a mobile @media block that flips a dataGrid into a card list (#268)", async () => {
+  const res = await dispatch("GET", "/");
+  const html = res.body ?? "";
+  // Tier 0 — zero-declaration responsive default: a single (max-width) breakpoint
+  // reflows every app for a phone. 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 stamps on (no JS branching).
+  const media = (html.match(/@media \(max-width:640px\) \{[\s\S]*?\n\}/) ?? [""])[0];
+  assert.ok(media, "a (max-width) media block must be present");
+  // thead hidden, rows/cells become blocks (the card flip).
+  assert.match(media, /table\.pc-grid colgroup, table\.pc-grid thead \{ display:none; \}/);
+  assert.match(media, /table\.pc-grid, table\.pc-grid tbody, table\.pc-grid tr, table\.pc-grid td \{ display:block[^}]*\}/);
+  // The column header prefixes each value as a label:value line via data-label.
+  assert.match(media, /td\[data-label\]::before \{ content:attr\(data-label\)/);
+  // The derived title leads the card with no caption; a badge column is a chip.
+  assert.match(media, /td\.pc-mcell-primary::before \{ content:none; \}/);
+  assert.match(media, /td\.pc-mcell-chip::before \{ content:none; \}/);
+  // An empty badge cell (blank field value) carries the chip class but no content;
+  // it must collapse on mobile so it doesn't leave a stray blank flex row in the card.
+  assert.match(media, /td\.pc-mcell-chip:empty \{ display:none; \}/);
+  // Low-value (hidden) columns drop off the card until the row's More toggle opens them.
+  assert.match(media, /td\.pc-mcell-hidden \{ display:none; \}/);
+  assert.match(media, /tr\.pc-open td\.pc-mcell-hidden \{ display:flex; \}/);
+});
+
+test("the shell mobile block collapses the nav and stacks buttons/form actions (#268)", async () => {
+  const res = await dispatch("GET", "/");
+  const html = res.body ?? "";
+  const media = (html.match(/@media \(max-width:640px\) \{[\s\S]*?\n\}/) ?? [""])[0];
+  // nav → scrollable bottom-ish bar (bar) / inline stack (rail); buttons and
+  // modal/form actions go full-width single column; text reflows on its own.
+  assert.match(media, /\.pc-bar \{ flex-wrap:nowrap; overflow-x:auto; \}/);
+  assert.match(media, /\.pc-rail \.pc-nav-items \{ flex-direction:row/);
+  assert.match(media, /\.pc-buttonrow \.pc-btn, \.pc-card \.pc-btn \{ width:100%; \}/);
+  assert.match(media, /\.pc-modal-actions \{ flex-direction:column; \}/);
+  // Row actions stack full-width under the card body.
+  assert.match(media, /td\.pc-row-actions \{ display:flex/);
+  // The per-row "More" toggle is base-hidden (outside the media block) so a grid
+  // with hidden-column hints renders unchanged on desktop, shown only on mobile.
+  assert.match(html, /\.pc-mcard-toggle \{ display:none; \}/);
+  assert.match(media, /\.pc-mcard-toggle \{ display:block/);
+});
+
+test("the mobile breakpoint has one source of truth shared by CSS and matchMedia (#268)", async () => {
+  // AGENTS.md: no drift surfaces. The breakpoint must appear identically in the
+  // shell CSS @media and the runtime's matchMedia — both interpolated from the
+  // single MOBILE_MAX_WIDTH constant — so "narrow" can never diverge between the
+  // pure-CSS card flip and the Tier-2 JS mode-switch.
+  const shell = (await dispatch("GET", "/")).body ?? "";
+  const js = (await dispatch("GET", "/app/runtime.js")).body ?? "";
+  assert.match(shell, /@media \(max-width:640px\)/);
+  assert.match(js, /window\.matchMedia\("\(max-width:640px\)"\)/);
+});
+
+test("the renderer classifies grid columns into mobile card regions by convention (#268)", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // Tier 0 heuristic (classifyColumns): the first non-badge column is the card
+  // title (primary), a badge column is a status chip, the rest are secondary
+  // label:value rows. Tier 1 refines it — mobile.priority ("primary"|"secondary"
+  // |"hidden") wins, and an explicit "primary" suppresses the auto title pick.
+  assert.match(js, /function classifyColumns\(cols\)/);
+  assert.match(js, /const explicitPrimary = list\.some\(\(c\) => c && c\.mobile && c\.mobile\.priority === "primary"\);/);
+  assert.match(js, /if \(pr === "primary"\) return "primary";/);
+  assert.match(js, /if \(pr === "hidden"\) return "hidden";/);
+  assert.match(js, /if \(col && col\.badge\) return "chip";/);
+  assert.match(js, /if \(!titleTaken\) \{ titleTaken = true; return "primary"; \}/);
+});
+
+test("the renderer stamps every grid cell with a data-label + mobile role class (#268)", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // Every td carries data-label (the mobile.label override or the column header)
+  // and a pc-mcell-<role> class so the card flip is pure CSS. The role is derived
+  // per column (classifyColumns) and threaded through gridCell into cellTd.
+  assert.match(js, /col\.mobile && typeof col\.mobile\.label === "string"\s*\n?\s*\? col\.mobile\.label/);
+  assert.match(js, /const mob = \{ class: "pc-mcell pc-mcell-" \+ mrole, "data-label": mlabel \};/);
+  assert.match(js, /function gridCell\(col, row, role\)/);
+  assert.match(js, /const cells = cols\.map\(\(c, i\) => gridCell\(c, row, roles\[i\]\)\);/);
+  assert.match(js, /return cellTd\(primary, text, subText, truncate, mob\);/);
+  // cellTd applies the mobile attrs to whichever td shape it returns.
+  assert.match(js, /function cellTd\(primary, primaryText, subText, truncate, tdAttrs\)/);
+  assert.match(js, /const td = tdAttrs \|\| \{\};/);
+});
+
+test("the renderer adds a per-row More toggle only when a column is mobile-hidden (#268)", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // Tier 1: mobile:{priority:"hidden"} columns are revealed behind a per-row
+  // "More" toggle. The toggle cell is base-hidden and shown only inside the
+  // mobile @media, so desktop is unchanged; it appears only when the grid
+  // actually has a hidden column. The cell is built by the shared mobileMoreCell
+  // helper and appended to the row (both the top-level grid and child grids use it).
+  assert.match(js, /const hasHidden = roles\.indexOf\("hidden"\) >= 0;/);
+  assert.match(js, /if \(hasHidden\) tr\.append\(mobileMoreCell\(tr\)\);/);
+  assert.match(js, /function mobileMoreCell\(tr\)/);
+  assert.match(js, /class: "pc-mcard-toggle"/);
+  assert.match(js, /const open = tr\.classList\.toggle\("pc-open"\);/);
+  assert.match(js, /moreBtn\.textContent = open \? "Less" : "More";/);
+});
+
+test("the per-row More toggle exposes its reveal state via aria-expanded (#268)", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // The toggle is a button that shows/hides card content, so assistive tech needs
+  // aria-expanded: it starts collapsed ("false") and is updated on every toggle.
+  assert.match(js, /"aria-expanded": "false"/);
+  assert.match(js, /moreBtn\.setAttribute\("aria-expanded", String\(open\)\);/);
+});
+
+test("child grids reuse the same per-row More toggle for hidden columns (#268)", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // Child grids classify columns into the same mobile roles (including "hidden"),
+  // so — like the top-level grid — they must render the shared More toggle, or a
+  // mobile:{priority:"hidden"} child column would be permanently unreachable on a
+  // narrow viewport. Derived from the same mobileMoreCell helper (no drift).
+  assert.match(js, /const chasHidden = croles\.indexOf\("hidden"\) >= 0;/);
+  assert.match(js, /if \(chasHidden\) ctr\.append\(mobileMoreCell\(ctr\)\);/);
+});
+
+test("the renderer honours an optional Tier-2 page-level mobile layout variant (#268)", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // Tier 2 escape hatch: a page may declare a distinct `mobile` node list used
+  // ONLY on a narrow viewport (matchMedia), with the default nodes everywhere
+  // else and a fallback for anything malformed. The page re-renders when the
+  // viewport crosses the breakpoint so the variant swaps in/out on rotation.
+  assert.match(js, /function pickNodes\(doc\)/);
+  assert.match(js, /if \(isNarrow\(\) && doc && doc\.mobile && Array\.isArray\(doc\.mobile\.nodes\)\) return doc\.mobile\.nodes;/);
+  assert.match(js, /const nodes = pickNodes\(doc\);/);
+  assert.match(js, /MOBILE_MQ\.addEventListener\("change", renderPage\);/);
+  // …but degrade gracefully on older Safari/iOS (< 14) where MediaQueryList
+  // lacks addEventListener, else the Tier-2 variant would never swap on rotation.
+  assert.match(js, /typeof MOBILE_MQ\.addEventListener === "function"/);
+  assert.match(js, /else if \(typeof MOBILE_MQ\.addListener === "function"\) MOBILE_MQ\.addListener\(renderPage\);/);
+});
+
+// --- Pipeline / stepper cell renderer (issue #265) ---------------------------
+// These guard the runtime shape the way the other column-mode tests do: the
+// renderer JS is asserted for the pipeline logic, and the shell CSS for the
+// .pc-pipe* chrome. Together they lock the six rendering requirements so the
+// primitive can't silently regress.
+
+test("renderer gates the pipeline cell on kind:\"pipeline\" and leaves other modes untouched", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // A dataGrid column declaring kind:"pipeline" is dispatched to pipelineCell;
+  // the gate is a pure discriminator so absent it, every existing column mode
+  // (badge/linkField/link/template/truncate) renders exactly as before.
+  assert.match(js, /if\s*\(col\.kind === "pipeline"\) return pipelineCell\(col, row, text, subText, truncate, mob\)/);
+  assert.match(js, /function pipelineCell\(col, row, text, subText, truncate, tdAttrs\)/);
+});
+
+test("pipeline orders stages upstream-filled / active-lit / downstream-ghosted from activeField", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // The active stage is located by matching activeField's value against
+  // stages[].key; stages before it are done/filled, the match is lit (active),
+  // and in-path stages after it are ghosted/upcoming. The lookup breaks on the
+  // first key match so a repeated key resolves deterministically to the first stage.
+  assert.match(js, /const activeKey = col\.activeField != null/);
+  // The row value is trimmed so a whitespace-padded key still matches its stage.
+  assert.match(js, /\? String\(row\[col\.activeField\]\)\.trim\(\) : ""/);
+  assert.match(js, /if \(String\(stages\[i\]\.key\) === activeKey\) \{\s*activeIdx = i;\s*break;\s*\}/);
+  assert.match(js, /i < activeIdx\) \{\s*cls = "pc-pipe-done"; word = "completed";/);
+  assert.match(js, /cls = "pc-pipe-upcoming"; word = "upcoming";/);
+  // The connector fills up to the active stage, but a not-in-path predecessor
+  // breaks the fill so a skipped stage is never implied to be on the path.
+  assert.match(js, /const filled =\s*activeIdx >= 0 && i <= activeIdx && !skipped && !skip\.has\(String\(stages\[i - 1\]\.key\)\)/);
+  assert.match(js, /class: "pc-pipe-conn" \+ filled/);
+});
+
+test("pipeline reads the not-in-path set per-row from a field, falling back to static config", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // Skipped stages are dashed (.pc-pipe-skip). The set comes from notInPathField
+  // on the row when given, else the static col.notInPath — via toStageSet, which
+  // accepts an array or a comma/space-separated string, trimming + dropping
+  // empties on BOTH paths so whitespace-padded array keys still match.
+  assert.match(js, /col\.notInPathField != null && row\[col\.notInPathField\] != null/);
+  assert.match(js, /toStageSet\(row\[col\.notInPathField\]\)/);
+  assert.match(js, /toStageSet\(col\.notInPath\)/);
+  assert.match(js, /cls = "pc-pipe-skip"; word = "skipped";/);
+  assert.match(js, /function toStageSet\(v\)/);
+  assert.match(js, /Array\.isArray\(v\)\) return new Set\(v\.map\(\(s\) => String\(s\)\.trim\(\)\)\.filter\(\(s\) => s !== ""\)\)/);
+});
+
+test("pipeline keeps the active stage current even if its key is also in the not-in-path set (active wins over skip)", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // Precedence guard: the skipped predicate excludes the active index so a stage
+  // that is both the active stage AND in the not-in-path set still renders as the
+  // current step (active styling + aria-current), never as dashed/skipped. The
+  // skip branch is checked before i === activeIdx, so without this exclusion the
+  // active stage would silently lose aria-current="step".
+  assert.match(js, /const skipped = i !== activeIdx && skip\.has\(String\(s\.key\)\);/);
+});
+
+test("pipeline renders failure distinctly from success on the active stage (stateField)", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // stateField drives the active stage's terminal treatment: ok → success ✓,
+  // failed → ✕, blocked → ⊘ — each a distinct class + glyph so success and
+  // failure are unmistakably different.
+  assert.match(js, /stRaw === "ok" \|\| stRaw === "failed" \|\| stRaw === "blocked" \? stRaw : "active"/);
+  assert.match(js, /state === "failed"\) \{ cls = "pc-pipe-active pc-pipe-failed"; word = "failed"; glyph = "\\u2715";/);
+  assert.match(js, /state === "ok"\) \{ cls = "pc-pipe-active pc-pipe-ok"; word = "done"; glyph = "\\u2713";/);
+  assert.match(js, /state === "blocked"\) \{ cls = "pc-pipe-active pc-pipe-blocked"; word = "blocked"; glyph = "\\u2298";/);
+});
+
+test("pipeline renders an active-stage badge from badgeField reusing .pc-badge tone classes", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // The badge sits on the active stage, only when badgeField is non-empty, and
+  // reuses the existing .pc-badge tone classes (no new badge styles): warn for
+  // attention/escalation, danger for blocked/failure.
+  assert.match(js, /const badgeText = col\.badgeField != null && row\[col\.badgeField\] != null/);
+  assert.match(js, /const badgeTone = state === "failed" \|\| state === "blocked" \? "danger" : "warn"/);
+  assert.match(js, /current && badgeText\.trim\(\) !== ""/);
+  assert.match(js, /class: "pc-badge pc-badge-" \+ badgeTone, title: badgeText, "aria-label": badgeText/);
+});
+
+test("pipeline builds a locus link via the shared pageHashHref route builder, only when the key is non-empty", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // The locus stage becomes a #/<page>/<key> in-app link built by the SAME
+  // pageHashHref helper the grid's page-link cell uses (single source of truth):
+  // safePageId guard + encodeURIComponent, a blank key yields "" so no link, and
+  // the anchor reuses .pc-link — no duplicated href construction.
+  assert.match(js, /function pageHashHref\(page, key\)/);
+  assert.match(js, /return "#\/" \+ encodeURIComponent\(page\) \+ "\/" \+ encodeURIComponent\(keyStr\)/);
+  // The grid page-link cell was refactored onto the shared builder too.
+  assert.match(js, /const href = pageHashHref\(col\.link\.page, row\[col\.link\.keyField\]\)/);
+  // The locus link uses it and the shared .pc-link class; blank key → "" → plain.
+  assert.match(js, /pageHashHref\(locus\.link\.page, locusKey\)/);
+  assert.match(js, /el\("a", \{ class: "pc-link pc-pipe-label", href: locusHref \}, label\)/);
+});
+
+test("pipeline exposes step semantics to assistive tech (role/list + aria-current)", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // The track is a labelled list; each stage is a listitem with an aria-label
+  // stating its label + status word; the current stage is marked aria-current.
+  assert.match(js, /class: "pc-pipe",\s*role: "list",\s*"aria-label": "Progress"/);
+  assert.match(js, /role: "listitem", "aria-label": label \+ " \\u2014 " \+ word/);
+  assert.match(js, /if \(current\) attrs\["aria-current"\] = "step"/);
+});
+
+test("pipeline degrades to plain cell text on missing/unknown config (never throws)", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // No stages array → the cell falls back to plain text via cellTd, matching how
+  // an unknown link.kind falls back today. Null/undefined entries are filtered so
+  // a schema hole never throws on s.key.
+  assert.match(js, /const stages = Array\.isArray\(col\.stages\) \? col\.stages\.filter\(\(s\) => s != null\) : \[\]/);
+  assert.match(js, /if \(stages\.length === 0\) return cellTd\(text, text, subText, truncate, tdAttrs\)/);
+});
+
+test("pipeline cell inherits the mobile card attrs so it labels/classifies under the card flip (#268)", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // The pipeline <td> merges gridCell's mobile card attrs (data-label + role
+  // class) alongside its own pc-pipe-cell class, so a pipeline column is not left
+  // out of the CSS-only card flip. Single source of truth: the same `mob` object
+  // every other cell path receives.
+  assert.match(js, /const cellAttrs = \{ \.\.\.\(tdAttrs \|\| \{\}\), class: \(tdAttrs && tdAttrs\.class \? tdAttrs\.class \+ " " : ""\) \+ "pc-pipe-cell" \}/);
+  assert.match(js, /return el\("td", cellAttrs, track\)/);
+});
+
+test("shell CSS carries the .pc-pipe* track chrome reusing --nano-* tokens", async () => {
+  const res = await dispatch("GET", "/");
+  const html = res.body ?? "";
+  // Structural track/stage styles only (badges/links reuse .pc-badge and .pc-link);
+  // all colours resolve through the shared token vocabulary so themes work.
+  assert.match(html, /\.pc-pipe \{ display:flex;/);
+  assert.match(html, /\.pc-pipe-done \{[^}]*border-color:var\(--nano-ok\)/);
+  assert.match(html, /\.pc-pipe-active \{[^}]*border-color:var\(--nano-accent\)/);
+  assert.match(html, /\.pc-pipe-active\.pc-pipe-failed \{[^}]*border-color:var\(--nano-danger\)/);
+  assert.match(html, /\.pc-pipe-active\.pc-pipe-ok \{[^}]*border-color:var\(--nano-ok\)/);
+  assert.match(html, /\.pc-pipe-skip \{[^}]*border-style:dashed/);
+  assert.match(html, /\.pc-pipe-upcoming \{[^}]*var\(--nano-text-faint\)/);
+});