@nanobpm/urban 0.50.0 → 0.52.0

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

@@ -0,0 +1,177 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createNodeHost } from "../../adapters/node.ts";
+import type { SqliteDb } from "../host.ts";
+import { makeGateway } from "./gateway.ts";
+import {
+  LINEAGE_ATTACHMENTS_TABLE,
+  LINEAGE_EDGES_TABLE,
+  LINEAGE_SCHEMA_SQL,
+  LineageStore,
+} from "./lineage-store.ts";
+
+async function withStore(fn: (store: LineageStore, db: SqliteDb) => void | Promise<void>): Promise<void> {
+  const dir = await mkdtemp(join(tmpdir(), "urban-lineage-"));
+  const host = createNodeHost({ cwd: dir, log: () => {} });
+  const db = host.openSqlite(join(dir, "test.db"));
+  const store = new LineageStore(db, { clock: { now: () => 0 } });
+  store.ensureSchema();
+  try {
+    await fn(store, db);
+  } finally {
+    db.close();
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
+function normaliseSql(sql: string): string {
+  return sql
+    .split("\n")
+    .map((line) => line.replace(/--.*$/, ""))
+    .join("\n")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+const migrationPath = fileURLToPath(new URL("../../../../../../db/migrations/004_urban_lineage.sql", import.meta.url));
+
+test("the lineage projection tables are framework bookkeeping — `_urban_`-prefixed and hidden from the domain model", async () => {
+  // The gateway hides `_urban_%` / `_nano_%` tables from the domain model / DB Manager. These
+  // projection tables are framework sidecars (not user/domain tables), so their names MUST carry
+  // that prefix or they would leak into apps' schemas.
+  assert.match(LINEAGE_EDGES_TABLE, /^_urban_/, "lineage edge table must be `_urban_`-prefixed to stay hidden");
+  assert.match(LINEAGE_ATTACHMENTS_TABLE, /^_urban_/, "lineage attachment table must be `_urban_`-prefixed to stay hidden");
+  await withStore(async (_store, db) => {
+    const surfaced = (await makeGateway(db).schema()).map((t) => t.name);
+    assert.ok(!surfaced.includes(LINEAGE_EDGES_TABLE), "lineage edge table must not surface in the domain model");
+    assert.ok(!surfaced.includes(LINEAGE_ATTACHMENTS_TABLE), "lineage attachment table must not surface in the domain model");
+  });
+});
+
+test("the boot migration and LineageStore's DDL do not drift", () => {
+  const migrationSql = readFileSync(migrationPath, "utf8");
+  assert.equal(
+    normaliseSql(migrationSql),
+    normaliseSql(LINEAGE_SCHEMA_SQL),
+    "db/migrations/004_urban_lineage.sql must match LINEAGE_SCHEMA_SQL — update both together",
+  );
+});
+
+test("the boot migration is forward-only and additive (IF NOT EXISTS, no drops/alters)", () => {
+  const migrationSql = readFileSync(migrationPath, "utf8");
+  assert.match(migrationSql, /CREATE TABLE IF NOT EXISTS _urban_lineage_edges/);
+  assert.match(migrationSql, /CREATE TABLE IF NOT EXISTS _urban_lineage_attachments/);
+  assert.doesNotMatch(migrationSql, /\bDROP\b/i);
+  assert.doesNotMatch(migrationSql, /\bALTER\b/i);
+  // Numbering is a shared surface; guard the prefix so a rebase renumber is caught here.
+  assert.match(migrationPath, /[/\\]004_urban_lineage\.sql$/);
+});
+
+test("ensureSchema creates both lineage tables idempotently", async () => {
+  await withStore((store, db) => {
+    store.ensureSchema();
+    store.ensureSchema();
+    const tables = db
+      .all<{ name: string }>("SELECT name FROM sqlite_master WHERE type='table' AND name IN (?, ?)", [
+        LINEAGE_EDGES_TABLE,
+        LINEAGE_ATTACHMENTS_TABLE,
+      ])
+      .map((r) => r.name)
+      .sort();
+    assert.deepEqual(tables, [LINEAGE_ATTACHMENTS_TABLE, LINEAGE_EDGES_TABLE].sort());
+  });
+});
+
+test("recordEdge is idempotent (a re-record of the same node/edge-type is a no-op)", async () => {
+  await withStore((store) => {
+    const edge = {
+      rootRequestKey: "root",
+      instanceKey: "child",
+      causedByInstanceKey: "root",
+      edgeType: "weak" as const,
+    };
+    assert.equal(store.recordEdge(edge), true);
+    assert.equal(store.recordEdge(edge), false, "re-record collapses to a no-op");
+    assert.equal(store.edges("root").length, 1);
+  });
+});
+
+test("recordEnvelope records the weak edge carried by an instance's _urban.lineage", async () => {
+  await withStore((store) => {
+    const recorded = store.recordEnvelope("child", {
+      _urban: { lineage: { rootRequestKey: "root", causedByInstanceKey: "root" } },
+    });
+    assert.equal(recorded, true);
+    assert.deepEqual(store.edges("root"), [
+      { rootRequestKey: "root", instanceKey: "child", causedByInstanceKey: "root", edgeType: "weak" },
+    ]);
+    // No envelope → nothing recorded.
+    assert.equal(store.recordEnvelope("x", { plain: 1 }), false);
+  });
+});
+
+test("recordFromJob records both the weak envelope edge and the strong execution edge (#808)", async () => {
+  await withStore((store) => {
+    store.recordFromJob({
+      processInstanceKey: "child",
+      parentProcessInstanceKey: "parent",
+      variables: { _urban: { lineage: { rootRequestKey: "root", causedByInstanceKey: "cause" } } },
+    });
+    const edges = store.edges("root");
+    assert.equal(edges.length, 2);
+    const strong = edges.find((e) => e.edgeType === "strong");
+    assert.deepEqual(strong, {
+      rootRequestKey: "root",
+      instanceKey: "child",
+      causedByInstanceKey: "parent",
+      edgeType: "strong",
+    });
+    // getLineage unions them: the strong execution edge wins for the node.
+    const tree = store.getLineage("root");
+    const node = tree.nodes.find((n) => n.instanceKey === "child");
+    assert.equal(node?.edgeType, "strong");
+  });
+});
+
+test("attach hangs an app domain row off a node, idempotently, and getLineage returns it", async () => {
+  await withStore((store) => {
+    store.recordEnvelope("child", { _urban: { lineage: { rootRequestKey: "root", causedByInstanceKey: "root" } } });
+    assert.equal(store.attach("root", { nodeKey: "child", kind: "pull_request", ref: "o/r#7", label: "PR 7" }), true);
+    assert.equal(store.attach("root", { nodeKey: "child", kind: "pull_request", ref: "o/r#7", label: "PR 7" }), false);
+    const tree = store.getLineage("root");
+    const child = tree.root.children[0];
+    assert.equal(child.instanceKey, "child");
+    assert.deepEqual(child.attachments, [{ nodeKey: "child", kind: "pull_request", ref: "o/r#7", label: "PR 7" }]);
+  });
+});
+
+test("getLineage returns the full descendant tree keyed by rootRequestKey", async () => {
+  await withStore((store) => {
+    // A root fans out to two children; one child spawns a grandchild.
+    store.recordEdge({ rootRequestKey: "root", instanceKey: "root", edgeType: "weak" });
+    store.recordEnvelope("c1", { _urban: { lineage: { rootRequestKey: "root", causedByInstanceKey: "root" } } });
+    store.recordEnvelope("c2", { _urban: { lineage: { rootRequestKey: "root", causedByInstanceKey: "root" } } });
+    store.recordEnvelope("g1", { _urban: { lineage: { rootRequestKey: "root", causedByInstanceKey: "c1" } } });
+
+    const tree = store.getLineage("root");
+    assert.equal(tree.rootRequestKey, "root");
+    assert.equal(tree.root.instanceKey, "root");
+    assert.deepEqual(tree.root.children.map((c) => c.instanceKey).sort(), ["c1", "c2"]);
+    const c1 = tree.root.children.find((c) => c.instanceKey === "c1");
+    assert.deepEqual(c1?.children.map((c) => c.instanceKey), ["g1"]);
+  });
+});
+
+test("getLineage returns a lone-root tree for a root with no recorded descendants", async () => {
+  await withStore((store) => {
+    const tree = store.getLineage("unknown-root");
+    assert.equal(tree.root.instanceKey, "unknown-root");
+    assert.deepEqual(tree.root.children, []);
+    assert.equal(tree.nodes.length, 1);
+  });
+});

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

@@ -371,6 +371,91 @@ test("renderer interpolates a column's per-cell template into DOM text (#214)",
   assert.match(js, /const text = typeof col\.template === "string" \? interpTemplate\(col\.template, row\) : rawText;/);
 });
 
+test("renderer renders a column's subtitle as a muted second line, never an href (#257)", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // A column may render an optional muted second line beneath the primary text
+  // (the identity key under a title, GitHub/Linear style). The value comes from
+  // col.subtitleField (raw) or col.subtitleTemplate (interpolated), null/absent →
+  // "" → no extra line. Guard the shape: subtitleTemplate wins via interpTemplate,
+  // the subtitle is emitted as a .pc-cell-sub DOM-text line, and — crucially for
+  // the security posture — it is NEVER an href source (only linkField/keyField
+  // drive anchors; the subtitle stays plain text).
+  assert.match(js, /col\.subtitleField != null && row\[col\.subtitleField\] != null \? String\(row\[col\.subtitleField\]\) : ""/);
+  assert.match(js, /const subText = typeof col\.subtitleTemplate === "string" \? interpTemplate\(col\.subtitleTemplate, row\) : subRaw;/);
+  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\);/);
+});
+
+test("renderer truncates a column to one line with an ellipsis + full-text tooltip (#257)", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // col.truncate:true clamps the primary (and any subtitle) line to a single row
+  // with an ellipsis, carrying the full value in a native title= tooltip and
+  // aria-label so the clipped text stays recoverable on hover and to assistive
+  // tech. Guard the shape: opt-in on `=== true`, a .pc-truncate class is added to
+  // the line, and the full text is mirrored into title/aria-label.
+  assert.match(js, /const truncate = col\.truncate === true;/);
+  assert.match(js, /"pc-cell-main"\s*\+\s*\(truncate \? " pc-truncate" : ""\)/);
+  assert.match(js, /mainAttrs\.title = primaryText; mainAttrs\["aria-label"\] = primaryText;/);
+  // title/aria-label are NOT inherited by descendants in HTML, so a link cell's
+  // <a> primary would miss the full-text tooltip/accessible name the wrapper div
+  // carries. Guard that they're also mirrored onto the primary element itself when
+  // it's a node (an anchor), so link cells get the same full-text recovery as text.
+  assert.match(js, /if \(primary && typeof primary\.setAttribute === "function"\) \{/);
+  assert.match(js, /primary\.setAttribute\("title", primaryText\); primary\.setAttribute\("aria-label", primaryText\);/);
+  assert.match(js, /"pc-cell-sub"\s*\+\s*\(truncate \? " pc-truncate" : ""\)/);
+});
+
+test("renderer emits a <colgroup> sizing columns by width/weight (#257)", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // A column may declare an explicit `width` ("40%", "22rem") or a relative
+  // integer `weight`, so table-layout:fixed stops splitting width equally. This
+  // emits a <colgroup> of <col style="width:…"> (fixed layout honours <col>
+  // widths). Guard the shape: an explicit width string wins verbatim, a positive
+  // weight is normalised across weighted columns into a percentage of the width
+  // the explicit columns leave (the remainder), unsized columns get no width
+  // (share the remainder), and no colgroup is emitted at all when no column
+  // declares sizing (so unsized grids are unchanged).
+  assert.match(js, /function buildColgroup\(cols, extraCount\)/);
+  assert.match(js, /if \(!hasSizing\) return null;/);
+  assert.match(js, /function hasExplicitWidth\(col\)/);
+  assert.match(js, /if \(hasExplicitWidth\(col\)\) return col\.width;/);
+  assert.match(js, /Math\.round\(\(col\.weight \/ weightTotal\) \* remainderPct \* 100\) \/ 100 \+ "%"/);
+  assert.match(js, /el\("col", w \? \{ style: "width:" \+ w \} : \{\}\)/);
+  // Regression (#258 review): mixing explicit % widths with weighted columns
+  // must not oversubscribe past 100% — weighted columns share only the remainder
+  // (100 - sum of explicit %), and only when every explicit width is a
+  // percentage (rem/px explicit widths fall back to a share of the full width).
+  assert.match(js, /const remainderPct = allExplicitArePct \? Math\.max\(0, 100 - explicitPctTotal\) : 100;/);
+  // Regression (#258 review): a column carrying both an explicit width and a
+  // weight uses its width verbatim and never consumes its weight, so it must be
+  // excluded from weightTotal or the truly-weighted columns' share is shrunk.
+  assert.match(js, /if \(!hasExplicitWidth\(c\) && typeof c\.weight === "number" && c\.weight > 0\) weightTotal \+= c\.weight;/);
+  assert.match(js, /function colWidthPct\(width\)/);
+  // The colgroup precedes <thead> in the table, and only when sizing is present.
+  assert.match(js, /\? el\("table", \{ class: "pc-grid" \}, colgroup, thead, tbody\)/);
+});
+
+test("the shell styles the subtitle line muted and the truncate clamp to one line (#257)", async () => {
+  const res = await dispatch("GET", "/");
+  const html = res.body ?? "";
+  // The muted subtitle line and the one-line clamp are styled in the shell CSS
+  // (served with the shell HTML, like the other pc-grid rules). Guard both rules.
+  const subRule = (html.match(/\.pc-cell-sub\s*\{[^}]*\}/) ?? [""])[0];
+  assert.ok(subRule, ".pc-cell-sub rule must be present");
+  assert.match(subRule, /color:var\(--nano-text-muted\)/);
+  assert.match(subRule, /font-size:\.8rem/);
+  const truncRule = (html.match(/\.pc-truncate\s*\{[^}]*\}/) ?? [""])[0];
+  assert.ok(truncRule, ".pc-truncate rule must be present");
+  assert.match(truncRule, /white-space:nowrap/);
+  assert.match(truncRule, /overflow:hidden/);
+  assert.match(truncRule, /text-overflow:ellipsis/);
+});
+
 test("renderer wires a column's processExplorer link to the console explorer", async () => {
   const res = await dispatch("GET", "/app/runtime.js");
   const js = res.body ?? "";