@shortlink-org/portolan 0.3.0 → 0.4.0

package/src/er/layout.test.ts

@@ -8,7 +8,8 @@ import { describe, expect, it } from "vitest";
 import { buildIndex, validateCatalog } from "../catalog";
 import { pathologicalCatalog, wideCatalog } from "../lib/scenarios";
 import { erSpec } from "./spec";
-import { layoutEr, layoutInput } from "./layout";
+import type { ErNode, ErSpec } from "./spec";
+import { canGroup, groupsOf, hideGroups, layoutEr, layoutInput } from "./layout";
 
 describe("layoutInput", () => {
   const bad = pathologicalCatalog();
@@ -82,7 +83,89 @@ describe("layoutEr", () => {
 
   it("answers for an empty store without asking elk anything", async () => {
     const result = await layoutEr({ nodes: [], edges: [] });
-    expect(result).toEqual({ positions: {}, width: 0, height: 0 });
+    expect(result).toEqual({ positions: {}, width: 0, height: 0, groups: [] });
+  });
+});
+
+describe("grouping a big schema", () => {
+  /** A card with only what grouping and packing read off it. */
+  const card = (id: string, aggregate: string | null): ErNode =>
+    ({ id, aggregate, width: 208, height: 120, name: id.split(".").at(-1) }) as unknown as ErNode;
+  /** `count` tables over `aggregates` groups, plus `loose` that persist nothing. */
+  const schema = (count: number, aggregates: string[], loose = 0): ErSpec => {
+    const nodes: ErNode[] = [];
+    for (let i = 0; i < count; i += 1) {
+      nodes.push(card(`s.t${i}`, aggregates[i % aggregates.length] ?? null));
+    }
+    for (let i = 0; i < loose; i += 1) nodes.push(card(`s.l${i}`, null));
+    return { nodes, edges: [] };
+  };
+
+  it("groups the cards by the model they persist, biggest first, the loose ones last", () => {
+    const spec = schema(7, ["a.big", "a.small", "a.big"], 2);
+    const groups = groupsOf(spec.nodes, (a) => a.split(".").at(-1)?.toUpperCase() ?? a);
+    expect(groups.map((g) => `${g.name}:${g.nodes.length}`)).toEqual(["BIG:5", "SMALL:2", "other:2"]);
+    expect(groups[2]?.aggregate).toBeNull();
+  });
+
+  it("offers grouping only past the size where one flow becomes a column", () => {
+    expect(canGroup(schema(39, ["a", "b", "c"]))).toBe(false);
+    expect(canGroup(schema(60, ["a", "b"]))).toBe(false);
+    expect(canGroup(schema(60, ["a", "b", "c"]))).toBe(true);
+    // Loose tables count as size but not as a group.
+    expect(canGroup(schema(10, ["a", "b", "c"], 40))).toBe(true);
+    expect(canGroup(schema(10, ["a", "b"], 40))).toBe(false);
+  });
+
+  it("packs the groups and keeps every card inside its own frame", async () => {
+    const spec = schema(48, ["a.x", "a.y", "a.z"], 6);
+    // A key inside a group and one across, which the packing ignores.
+    spec.edges.push(
+      { id: "in", kind: "fk", from: "s.t3", to: "s.t0", fromColumn: "x_id", toColumn: "id", onDelete: null } as unknown as ErSpec["edges"][number],
+      { id: "across", kind: "fk", from: "s.t1", to: "s.t0", fromColumn: "x_id", toColumn: "id", onDelete: null } as unknown as ErSpec["edges"][number],
+    );
+    const laid = await layoutEr(spec, { grouped: true, aspectRatio: 2 });
+    expect(laid.groups.map((g) => g.id)).toEqual(["a.x", "a.y", "a.z", "other"]);
+    for (const node of spec.nodes) {
+      const at = laid.positions[node.id];
+      expect(at).toBeDefined();
+      const frame = laid.groups.find((g) => g.id === (node.aggregate ?? "other"));
+      expect(frame).toBeDefined();
+      if (!at || !frame) continue;
+      expect(at.x).toBeGreaterThanOrEqual(frame.x);
+      expect(at.y).toBeGreaterThanOrEqual(frame.y);
+      expect(at.x + node.width).toBeLessThanOrEqual(frame.x + frame.width + 0.5);
+      expect(at.y + node.height).toBeLessThanOrEqual(frame.y + frame.height + 0.5);
+    }
+    // Frames do not overlap.
+    for (const a of laid.groups) {
+      for (const b of laid.groups) {
+        if (a.id === b.id) continue;
+        const apart = a.x + a.width <= b.x || b.x + b.width <= a.x || a.y + a.height <= b.y || b.y + b.height <= a.y;
+        expect(apart).toBe(true);
+      }
+    }
+    // Packed near the box's shape rather than as a column.
+    expect(laid.width / laid.height).toBeGreaterThan(1);
+    // The key inside a group put its parent left of its child.
+    expect(laid.positions["s.t0"]?.x ?? 0).toBeLessThan(laid.positions["s.t3"]?.x ?? 0);
+  });
+
+  it("hides a group with every edge that touched it, and leaves the rest as it was", () => {
+    const spec = schema(6, ["a.x", "a.y"], 2);
+    spec.edges.push(
+      { id: "in-x", kind: "fk", from: "s.t2", to: "s.t0", fromColumn: "x_id", toColumn: "id", onDelete: null } as unknown as ErSpec["edges"][number],
+      { id: "x-y", kind: "fk", from: "s.t1", to: "s.t0", fromColumn: "x_id", toColumn: "id", onDelete: null } as unknown as ErSpec["edges"][number],
+    );
+    expect(hideGroups(spec, new Set())).toBe(spec);
+    const without = hideGroups(spec, new Set(["a.y", "other"]));
+    expect(without.nodes.map((n) => n.id)).toEqual(["s.t0", "s.t2", "s.t4"]);
+    expect(without.edges.map((e) => e.id)).toEqual(["in-x"]);
+  });
+
+  it("stays one flow unless asked", async () => {
+    const laid = await layoutEr(schema(45, ["a", "b", "c"]));
+    expect(laid.groups).toEqual([]);
   });
 });
 

package/src/er/layout.ts

@@ -11,14 +11,38 @@
 // reads: source on the left, the view computed from it on the right. Reversing
 // it too would put every view before the tables it reads, which is the one
 // arrangement that makes a lineage picture unreadable.
+//
+// A big schema is laid out in two steps rather than one. A single layered
+// pass over a hundred-odd tables comes out as a column: the graph is shallow
+// and wide, one layer holds fifty cards, and no direction fixes that -
+// measured on a 138-table schema, left-to-right, top-down and every wrapping
+// option elk has all fit the canvas at a tenth of scale. What the tables do
+// have is the model group each one persists, so the cards of one group are
+// laid out among themselves and the groups are packed as rectangles to the
+// canvas's own proportions, which fits the same schema at nearly three times
+// the scale and reads by module rather than as one sheet.
+
+import { layoutGroupsWithElk, layoutWithElk } from "../graph/elk";
+import type { ErNode, ErSpec } from "./spec";
 
-import { layoutWithElk } from "../graph/elk";
-import type { ErSpec } from "./spec";
+export interface ErGroupFrame {
+  id: string;
+  name: string;
+  /** The aggregate the group is, or null for the tables that persist none. */
+  aggregate: string | null;
+  count: number;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
 
 export interface ErLayout {
   positions: Record<string, { x: number; y: number }>;
   width: number;
   height: number;
+  /** Empty when the layout is one flow. */
+  groups: ErGroupFrame[];
 }
 
 export interface ErLayoutInput {
@@ -57,11 +81,122 @@ export function layoutInput(spec: ErSpec): ErLayoutInput {
   };
 }
 
+/** Fewer tables than this is a schema one layered pass draws fine. */
+export const GROUP_MIN_TABLES = 40;
+/** Fewer model groups than this and grouping would draw one big frame. */
+export const GROUP_MIN_GROUPS = 3;
+
+/** What every table that persists no model is grouped under. */
+export const UNGROUPED = "other";
+
+export interface ErGrouping {
+  id: string;
+  name: string;
+  aggregate: string | null;
+  nodes: string[];
+}
+
+/**
+ * The cards by the model group they persist, biggest group first and the
+ * ungrouped rest last - which is the order the packing takes them in, and
+ * big-first is what packs tightest.
+ */
+export function groupsOf(
+  nodes: readonly Pick<ErNode, "id" | "aggregate">[],
+  nameOf: (aggregate: string) => string,
+): ErGrouping[] {
+  const byAggregate = new Map<string | null, string[]>();
+  for (const node of nodes) {
+    const key = node.aggregate;
+    byAggregate.set(key, [...(byAggregate.get(key) ?? []), node.id]);
+  }
+  const groups: ErGrouping[] = [];
+  for (const [aggregate, ids] of byAggregate) {
+    groups.push({
+      id: aggregate ?? UNGROUPED,
+      name: aggregate ? nameOf(aggregate) : UNGROUPED,
+      aggregate,
+      nodes: ids,
+    });
+  }
+  groups.sort((a, b) => {
+    if (a.aggregate === null) return 1;
+    if (b.aggregate === null) return -1;
+    return b.nodes.length - a.nodes.length || a.id.localeCompare(b.id);
+  });
+  return groups;
+}
+
+/** The group a card belongs to: its aggregate, or the ungrouped rest. */
+export function groupKey(node: Pick<ErNode, "aggregate">): string {
+  return node.aggregate ?? UNGROUPED;
+}
+
+/**
+ * The spec without the groups a reader hid: their cards gone, and with them
+ * every edge that touched one. What is left lays out and searches like a
+ * smaller schema, which is the point of hiding.
+ */
+export function hideGroups(spec: ErSpec, hidden: ReadonlySet<string>): ErSpec {
+  if (hidden.size === 0) return spec;
+  const nodes = spec.nodes.filter((n) => !hidden.has(groupKey(n)));
+  const kept = new Set(nodes.map((n) => n.id));
+  return {
+    nodes,
+    edges: spec.edges.filter((e) => kept.has(e.from) && kept.has(e.to)),
+  };
+}
+
+/** Whether a schema is big enough, and grouped enough, for the two-step layout to help. */
+export function canGroup(spec: ErSpec): boolean {
+  if (spec.nodes.length < GROUP_MIN_TABLES) return false;
+  const aggregates = new Set(spec.nodes.map((n) => n.aggregate).filter((a): a is string => a !== null));
+  return aggregates.size >= GROUP_MIN_GROUPS;
+}
+
+export interface ErLayoutOptions {
+  /** Lay the cards out by model group and pack the groups. */
+  grouped?: boolean;
+  /** Width over height of the box the picture is for; the packing aims at it. */
+  aspectRatio?: number;
+  /** What a group is called on its frame, by the aggregate it is. */
+  nameOf?: (aggregate: string) => string;
+}
+
 /** Lays a spec out left to right, roots first. Falls back to a column on failure. */
-export async function layoutEr(spec: ErSpec): Promise<ErLayout> {
+export async function layoutEr(spec: ErSpec, options: ErLayoutOptions = {}): Promise<ErLayout> {
   const input = layoutInput(spec);
   if (input.nodes.length === 0) {
-    return { positions: {}, width: 0, height: 0 };
+    return { positions: {}, width: 0, height: 0, groups: [] };
+  }
+
+  if (options.grouped) {
+    const nameOf = options.nameOf ?? ((aggregate: string) => aggregate.split(".").at(-1) ?? aggregate);
+    const groups = groupsOf(spec.nodes, nameOf);
+    const groupOf = new Map<string, string>();
+    for (const group of groups) {
+      for (const id of group.nodes) groupOf.set(id, group.id);
+    }
+    const sizes = new Map(input.nodes.map((n) => [n.id, n]));
+    const result = await layoutGroupsWithElk({
+      groups: groups.map((group) => ({
+        id: group.id,
+        nodes: group.nodes.map((id) => sizes.get(id)).filter((n): n is NonNullable<typeof n> => n !== undefined),
+        edges: input.edges.filter((e) => groupOf.get(e.source) === group.id && groupOf.get(e.target) === group.id),
+      })),
+      aspectRatio: options.aspectRatio ?? 2,
+      layerSpacing: 120,
+      nodeSpacing: 24,
+    });
+    return {
+      positions: result.positions,
+      width: result.width,
+      height: result.height,
+      groups: groups.map((group) => {
+        const frame = result.frames[group.id] ?? { x: 0, y: 0, width: 0, height: 0 };
+        return { id: group.id, name: group.name, aggregate: group.aggregate, count: group.nodes.length, ...frame };
+      }),
+    };
   }
 
   const { positions, width, height } = await layoutWithElk({
@@ -73,5 +208,5 @@ export async function layoutEr(spec: ErSpec): Promise<ErLayout> {
     layerSpacing: 170,
     nodeSpacing: 28,
   });
-  return { positions, width, height };
+  return { positions, width, height, groups: [] };
 }

package/src/er/spec.test.ts

@@ -294,6 +294,23 @@ describe("matchingNodes", () => {
   it("matches nothing on an empty term", () => {
     expect(matchingNodes(spec, "  ").size).toBe(0);
   });
+
+  it("puts the best hit first: the table named so, then names, then columns and SQL", () => {
+    // `orders` is the table's own name; the two views contain it in theirs
+    // and come after, in the order they are drawn.
+    expect([...matchingNodes(spec, "orders")]).toEqual([
+      "shop.oms.pg.orders",
+      "shop.oms.pg.v_open_orders",
+      "shop.oms.pg.mv_orders_daily",
+    ]);
+    // A hit by name outranks a hit by column: `order_items` is named for
+    // orders, `outbox` only keys on one.
+    const byOrder = [...matchingNodes(spec, "order")];
+    expect(byOrder.indexOf("shop.oms.pg.order_items")).toBeLessThan(
+      byOrder.indexOf("shop.oms.pg.outbox") < 0 ? Infinity : byOrder.indexOf("shop.oms.pg.outbox"),
+    );
+    expect(byOrder[0]).toBe("shop.oms.pg.orders");
+  });
 });
 
 describe("the pathological store", () => {

package/src/er/spec.ts

@@ -407,20 +407,33 @@ export function outboundLineage(
 /**
  * Cards matching a search term, by name, column name, or the aggregate they
  * hold. Returns ids so the canvas can light them without re-deriving anything.
+ *
+ * The set is ordered, best match first, because the canvas jumps to the first
+ * one and cycles from there: a card whose name IS the term, then cards whose
+ * name contains it, then the aggregate, then a column, the doc or the SQL.
+ * Within a rank, the order the spec lists them in - which is the order they
+ * are drawn in.
  */
 export function matchingNodes(spec: ErSpec, term: string): Set<string> {
   const needle = term.trim().toLowerCase();
   if (!needle) return new Set();
-  const out = new Set<string>();
+  const ranked: { id: string; rank: number }[] = [];
   for (const node of spec.nodes) {
-    const hay = [
-      node.name,
-      node.aggregate ?? "",
-      node.doc ?? "",
-      node.view?.definition ?? "",
-      ...node.columns.map((c) => c.name),
-    ];
-    if (hay.some((h) => h.toLowerCase().includes(needle))) out.add(node.id);
+    const name = node.name.toLowerCase();
+    const rank =
+      name === needle
+        ? 0
+        : name.includes(needle)
+          ? 1
+          : (node.aggregate ?? "").toLowerCase().includes(needle)
+            ? 2
+            : [node.doc ?? "", node.view?.definition ?? "", ...node.columns.map((c) => c.name)].some(
+                  (h) => h.toLowerCase().includes(needle),
+                )
+              ? 3
+              : -1;
+    if (rank >= 0) ranked.push({ id: node.id, rank });
   }
-  return out;
+  ranked.sort((a, b) => a.rank - b.rank);
+  return new Set(ranked.map((r) => r.id));
 }

package/src/flow/Recordings.test.tsx

@@ -0,0 +1,52 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { renderToStaticMarkup } from "react-dom/server";
+import { MemoryRouter } from "react-router";
+import { describe, expect, it } from "vitest";
+
+import { rawCatalog as raw } from "../test-catalog";
+import type { Catalog, Flow } from "../catalog";
+import { RecordingsChip } from "./Recordings";
+
+const catalog = raw as unknown as Catalog;
+const checkout = catalog.flows.find((f) => f.slug === "checkout") as Flow;
+
+/**
+ * Rendered once, statically: no local server answers here, so the chip is
+ * what a published site shows - the recordings the catalog carries, or
+ * nothing.
+ */
+function render(flow: Flow, exampleId: string | null = null) {
+  const client = new QueryClient({ defaultOptions: { queries: { retry: false, enabled: false } } });
+  return renderToStaticMarkup(
+    <QueryClientProvider client={client}>
+      <MemoryRouter>
+        <RecordingsChip flow={flow} exampleId={exampleId} onExample={() => {}} />
+      </MemoryRouter>
+    </QueryClientProvider>,
+  );
+}
+
+const example = (traceId: string) => ({
+  id: `examples/shop/telemetry/traces.jsonl#${traceId}`,
+  recording: "examples/shop/telemetry/traces.jsonl",
+  traceId,
+  durationMs: 12.5,
+  steps: [{ step: "s1", durationMs: 12.5 }],
+});
+
+describe("the recordings chip", () => {
+  it("counts the flow's recordings and says which one is lit", () => {
+    const flow = { ...checkout, examples: [example("aaaaaaaa1"), example("bbbbbbbb2")] };
+    const markup = render(flow);
+    expect(markup).toContain("recordings · 2");
+    expect(markup).toContain("Recordings — 2 recordings");
+
+    const lit = render(flow, flow.examples[1]!.id);
+    expect(lit).toContain("lighting #bbbbbbbb");
+    expect(lit).toContain("border-accent");
+  });
+
+  it("is not on the page at all when there is nothing to show and nowhere to add", () => {
+    expect(render({ ...checkout, examples: undefined })).toBe("");
+  });
+});

package/src/flow/Recordings.tsx

@@ -0,0 +1,236 @@
+// The recordings a flow has been seen running in, and the way to add one.
+//
+// A recording is an example of the flow: which steps ran, how long each took,
+// what the spans were called. It is evidence, so it sits in the evidence row
+// as a chip - "recordings · 2" - and opens behind it, the way the catalog
+// stamp does: the rail is for the steps, and a list that is read once and
+// then left alone should not take a row of it for good. Choosing a recording
+// lights the steps it showed on the picture; the step's own panel says what
+// the span carried. In local mode the same panel takes a new recording, runs
+// the generator over a copy with it in place, and shows what changed before
+// anything is written.
+
+import { useRef, useState } from "react";
+import { useQuery } from "@tanstack/react-query";
+import { Popover, PopoverButton, PopoverPanel } from "@headlessui/react";
+import { Disc3, LoaderCircle, Upload } from "lucide-react";
+import { Link } from "react-router";
+import type { Flow, FlowExample } from "../catalog";
+import { Modal } from "../components/Overlay";
+import { useToastStore } from "../app/toast";
+import { plural, relativeTime } from "../lib/format";
+import { startTraceTrial } from "../lib/local-api";
+import { localStatusQuery } from "../lib/queries";
+import { projectForFlow, projectsForFlow } from "../lib/trace-project";
+import { paths } from "../routes";
+import { formatMs, stepsShownBy } from "./examples";
+import { TraceTrialPanel } from "./TraceTrial";
+import { forgetTraceTrial, recallTraceTrial, rememberTraceTrial, sessionStore } from "./trace-trial-resume";
+
+function shortRecording(recording: string): string {
+  const parts = recording.split("/");
+  return parts.length > 2 ? `…/${parts.slice(-2).join("/")}` : recording;
+}
+
+export function RecordingsChip({
+  flow,
+  exampleId,
+  onExample,
+}: {
+  flow: Flow;
+  /** The example lit on the picture, or null. */
+  exampleId: string | null;
+  onExample: (id: string | null) => void;
+}) {
+  const status = useQuery(localStatusQuery());
+  const local = status.isSuccess;
+  const projects = status.data?.setup.projects ?? [];
+  /**
+   * A run the page did not start, or lost: keeping a recording writes
+   * portolan.json, which restarts the dev server and reloads the page
+   * under the dialog. The run goes on; the page says so.
+   */
+  const activeRun = status.data?.activeRun ?? null;
+  const say = useToastStore((s) => s.say);
+  const input = useRef<HTMLInputElement | null>(null);
+  // Picked back up from before a reload, when this page was watching one:
+  // keeping a recording reloads the page twice, and the dialog outlives it.
+  const [resumed] = useState(() => recallTraceTrial(sessionStore(), flow.slug));
+  const [runId, setRunId] = useState<string | null>(resumed?.runId ?? null);
+  const [busy, setBusy] = useState(false);
+  const watch = (id: string) => {
+    rememberTraceTrial(sessionStore(), flow.slug, { runId: id, writeRunId: null });
+    setRunId(id);
+  };
+  const done = () => {
+    forgetTraceTrial(sessionStore());
+    setRunId(null);
+  };
+  const examples = flow.examples ?? [];
+  const project = local ? projectForFlow(projects, flow) : null;
+  const candidates = local ? projectsForFlow(projects, flow) : [];
+  const [chosenProject, setChosenProject] = useState<string>("");
+  const target = project?.id ?? chosenProject;
+  const lit = exampleId ? examples.find((e) => e.id === exampleId) : undefined;
+
+  async function upload(file: File) {
+    if (!target) return;
+    setBusy(true);
+    try {
+      const started = await startTraceTrial(file, target);
+      watch(started.runId);
+    } catch (cause) {
+      say(cause instanceof Error ? cause.message : String(cause));
+    } finally {
+      setBusy(false);
+      if (input.current) input.current.value = "";
+    }
+  }
+
+  if (examples.length === 0 && !local) return null;
+
+  const summary = examples.length
+    ? `${examples.length} ${plural(examples.length, "recording")}${lit ? ` · lighting #${lit.traceId.slice(0, 8)}` : ""}`
+    : "no recordings yet";
+
+  return (
+    <>
+      <Popover className="relative">
+        <PopoverButton
+          title={`Recordings this flow was seen running in — ${summary}`}
+          aria-label={`Recordings — ${summary}`}
+          className={({ open }) =>
+            `chip transition-colors focus:outline-none ${open || lit ? "border-accent text-accent" : "border-line text-muted hover:text-ink"}`
+          }
+        >
+          <Disc3 size={11} aria-hidden />
+          {examples.length ? `recordings · ${examples.length}` : "add recording"}
+          {activeRun && runId === null ? <LoaderCircle size={11} className="animate-spin text-accent" aria-hidden /> : null}
+        </PopoverButton>
+        <PopoverPanel
+          anchor={{ to: "bottom start", gap: 4, padding: 8 }}
+          className="palette-in z-50 w-[30rem] max-w-[92vw] rounded-control border bg-canvas p-2 border-line-strong shadow-md focus:outline-none"
+        >
+          <div className="flex items-center gap-2 px-1">
+            <span className="label text-faint">recordings</span>
+            <span className="mono text-muted">{examples.length}</span>
+            {activeRun && runId === null ? (
+              <Link to={paths.settings()} className="mono ml-auto flex items-center gap-1 text-muted hover:text-ink" title="A generator run is in progress; the page reloads when it has written">
+                <LoaderCircle size={12} className="animate-spin text-accent" aria-hidden /> {activeRun.mode === "write" ? "regenerating…" : "run in progress…"}
+              </Link>
+            ) : local ? (
+              <span className="ml-auto flex items-center gap-1.5">
+                {candidates.length > 1 && !project ? (
+                  <select
+                    className="mono rounded-control border border-line bg-canvas px-1 py-0.5 text-ink"
+                    value={chosenProject}
+                    onChange={(e) => setChosenProject(e.target.value)}
+                    aria-label="Project to keep the recording under"
+                  >
+                    <option value="">project…</option>
+                    {candidates.map((p) => <option key={p.id} value={p.id}>{p.name}</option>)}
+                  </select>
+                ) : null}
+                <button
+                  type="button"
+                  className="tbtn"
+                  disabled={busy || !target}
+                  title={target ? `Upload an OTLP JSON recording; it is kept under ${target} after you review what it shows` : candidates.length ? "Choose the project the recording belongs to" : "No project in this flow's context to keep a recording under"}
+                  onClick={() => input.current?.click()}
+                >
+                  <Upload size={13} aria-hidden /> add
+                </button>
+              </span>
+            ) : null}
+          </div>
+
+          {examples.length ? (
+            <ul className="mt-1.5 flex max-h-72 flex-col gap-0.5 overflow-y-auto">
+              {examples.map((example) => (
+                <ExampleRow
+                  key={example.id}
+                  example={example}
+                  on={exampleId === example.id}
+                  onToggle={() => onExample(exampleId === example.id ? null : example.id)}
+                />
+              ))}
+            </ul>
+          ) : local ? (
+            <p className="mt-1.5 px-1 text-muted">
+              No recording shows this flow yet. Add an OTLP JSON export of a trace that runs through it, or see <Link to={paths.settingsRecordings()} className="text-accent hover:underline">recordings</Link> in settings.
+            </p>
+          ) : null}
+          {examples.length ? (
+            <p className="mt-1.5 px-1 text-faint">Choose one to light the steps it showed on the picture; a step's panel says what its span carried.</p>
+          ) : null}
+        </PopoverPanel>
+      </Popover>
+
+      {/* Outside the panel, which is gone the moment it closes: the file
+          input the button clicks and the dialog the upload opens must outlive
+          the popover. */}
+      {local ? (
+        <input
+          ref={input}
+          type="file"
+          accept=".jsonl,.json,.ndjson,application/json"
+          className="hidden"
+          onChange={(e) => { const file = e.target.files?.[0]; if (file) void upload(file); }}
+        />
+      ) : null}
+
+      <Modal open={runId !== null} onClose={() => {}} label="Recording" width="min(760px,94vw)">
+        <div className="flex items-center gap-3 border-b border-line px-5 py-4">
+          <div className="flex-1">
+            <div className="font-semibold text-ink">Recording of {flow.name}</div>
+            <div className="mono mt-0.5 text-muted">read against the catalog, nothing written yet</div>
+          </div>
+        </div>
+        <div className="min-h-0 flex-1 overflow-y-auto p-5">
+          {runId ? (
+            /* Keyed by the run: a dialog closing on one run and opening on
+               the next within the exit animation must not hand the next run
+               the state of the one before. */
+            <TraceTrialPanel
+              key={runId}
+              runId={runId}
+              initialWriteRunId={resumed?.runId === runId ? resumed.writeRunId : null}
+              onWriteStarted={(writeRunId) => rememberTraceTrial(sessionStore(), flow.slug, { runId, writeRunId })}
+              onDone={done}
+            />
+          ) : null}
+        </div>
+      </Modal>
+    </>
+  );
+}
+
+function ExampleRow({
+  example,
+  on,
+  onToggle,
+}: {
+  example: FlowExample;
+  on: boolean;
+  onToggle: () => void;
+}) {
+  return (
+    <li>
+      <button
+        type="button"
+        aria-pressed={on}
+        onClick={onToggle}
+        className={`flex w-full flex-wrap items-baseline gap-x-2 rounded-control px-1.5 py-1 text-left hover:bg-surface ${on ? "bg-surface" : ""}`}
+        title={`${example.recording} · trace ${example.traceId}`}
+      >
+        <span className="mono truncate text-ink">{shortRecording(example.recording)}</span>
+        <span className="mono text-faint">#{example.traceId.slice(0, 8)}</span>
+        <span className="mono ml-auto text-muted">
+          {stepsShownBy(example).length} {plural(stepsShownBy(example).length, "step")}
+          {example.durationMs ? ` · ${formatMs(example.durationMs)}` : ""}
+          {example.recordedAt ? ` · ${relativeTime(example.recordedAt)}` : ""}
+        </span>
+      </button>
+    </li>
+  );
+}