@shortlink-org/portolan 0.2.4 → 0.4.0

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>
+  );
+}

package/src/flow/StepDetail.tsx

@@ -1,3 +1,7 @@
+import { RelationEvidencePanel } from "../components/RelationEvidence";
+import { stepRelationEvidence } from "./evidence";
+import { exampleRowsFor, formatMs } from "./examples";
+import { HTTPDestinationEvidence } from "../components/HTTPDestinationEvidence";
 import { useMemo } from "react";
 import { Link } from "react-router";
 import { AlertTriangle, FileCode2 } from "lucide-react";
@@ -190,6 +194,8 @@ function RpcDetail({ step, flow }: { step: Step; flow: Flow }) {
         </div>
       </header>
 
+      {step.destination ? <HTTPDestinationEvidence destination={step.destination} /> : null}
+
       <DetailSection title="Contract">
         <dl className="grid grid-cols-[minmax(7rem,auto)_minmax(0,1fr)] gap-x-4 gap-y-2">
           {answer ? (
@@ -712,12 +718,65 @@ function StoreCallDetail({ step, flow }: { step: Step; flow: Flow }) {
   );
 }
 
+/**
+ * What the recordings said about this step: each trace that showed it, how
+ * long the span took, and the names it carried. Examples of the step running,
+ * next to the step - the recording itself is on the flow page.
+ */
+function StepExamples({ step, flow }: { step: Step; flow: Flow }) {
+  const rows = exampleRowsFor(flow, step);
+  if (!flow.examples?.length) return null;
+
+  return (
+    <>
+      <Label>
+        Recorded{step.seen ? ` · seen in ${step.seen.traces} ${step.seen.traces === 1 ? "trace" : "traces"}` : ""}
+      </Label>
+      {rows.length === 0 ? (
+        <div className="mono text-muted">not shown in any recording kept as an example</div>
+      ) : (
+        <div className="flex flex-col gap-1.5">
+          {rows.map(({ example, shown }) => {
+            const attrs = Object.entries(shown.attributes ?? {}).sort(([a], [b]) => a.localeCompare(b));
+            return (
+              <div key={example.id} className="border px-2 py-1.5 border-line">
+                <div className="mono flex flex-wrap items-baseline gap-x-2 text-muted">
+                  <span className="text-ink" title={example.recording}>{example.traceId}</span>
+                  {shown.durationMs ? <span>{formatMs(shown.durationMs)}</span> : null}
+                  {example.recordedAt ? <span>{example.recordedAt.slice(0, 19).replace("T", " ")}Z</span> : null}
+                </div>
+                {shown.label && shown.label !== step.label ? <div className="mono mt-0.5 text-muted">{shown.label}</div> : null}
+                {attrs.length ? (
+                  /* One attribute per line, the key above its value, both
+                     allowed to wrap: the panel is narrow and a route or a
+                     destination is long, and a value cut off with an
+                     ellipsis is a value the reader has to hover for. */
+                  <dl className="mono mt-1 flex flex-col gap-y-1">
+                    {attrs.map(([key, value]) => (
+                      <div key={key} className="min-w-0">
+                        <dt className="text-faint">{key}</dt>
+                        <dd className="break-all whitespace-normal text-ink">{value}</dd>
+                      </div>
+                    ))}
+                  </dl>
+                ) : null}
+              </div>
+            );
+          })}
+        </div>
+      )}
+    </>
+  );
+}
+
 export function StepDetailBody({ step, flow }: { step: Step; flow: Flow }) {
   const decisions = step.ref ? (index.adrsByEvent.get(step.ref) ?? []) : [];
 
   return (
     <>
       <ExecutionContext step={step} flow={flow} />
+      <RelationEvidencePanel items={stepRelationEvidence(index, step)} renderSource={(where) => <SourceWhere where={where} flow={flow} structured />} />
+      <StepExamples step={step} flow={flow} />
 
       {/* A decision that names this step's event is the reason the step
           looks the way it does. It belongs next to the step, not three