@specific.dev/spectest 0.48.0 → 0.50.0

package/dist/index.d.ts

@@ -2,6 +2,9 @@ import { strict as nodeAssert } from "node:assert";
 export type { Carrier, Wrapped, WrappedObject, WrappedArray, WrappedResponse, Provenanced, SpectestFetch, Unwrap, } from "./inspect.js";
 import type { Provenanced, SpectestFetch, Wrapped } from "./inspect.js";
 export { field } from "./inspect.js";
+export { annotate } from "./annotate.js";
+export type { Annotated, AnnotationKind, AnnotationOptions, ChatAnnotation, ChatMessageAnnotation, EmailAnnotation, } from "./annotate.js";
+import type { Annotated } from "./annotate.js";
 export { SQL, type SqlClient, type SqlOptions } from "./sql.js";
 export { RedisClient, type RedisClientLike, type RedisOptions } from "./redis.js";
 export { S3Client, type S3ClientLike, type S3File, type S3ClientOptions } from "./s3.js";
@@ -1147,6 +1150,10 @@ export interface FakeDefinition<S = any, H extends Record<string, unknown> = Rec
      * Every call is tracked in the test timeline: it records a `fake` step
      * and the return value is tagged so a later `expect(...)` on it nests
      * under that step in the UI (same provenance as `fetch`/db results).
+     * The step renders the return value as JSON; wrap it in {@link annotate}
+     * to add a richer view (an email, today) that the step's panel leads with,
+     * the JSON one tab away — the test still receives the raw value, unchanged
+     * and unchanged in type.
      *
      * Receives the fake's `state` plus a {@link FakeContext} `ctx`, so a
      * helper can provision/teardown runtime services just like the handler.
@@ -1188,8 +1195,15 @@ export type FakesMap = Record<string, FakeDefinition<any, any>>;
  * `void` side-effect helpers) pass through untouched. Mirrors `Tagged<T>` in
  * `components/k3s.ts`, extended to cover synchronous returns. */
 type WrappedHelpers<H> = {
-    [K in keyof H]: H[K] extends (...args: infer A) => Promise<infer R> ? (...args: A) => Promise<Wrapped<R>> : H[K] extends (...args: infer A) => infer R ? (...args: A) => [R] extends [void] ? void : Wrapped<R> : H[K];
+    [K in keyof H]: H[K] extends (...args: infer A) => Promise<infer R> ? (...args: A) => Promise<Wrapped<Unannotated<R>>> : H[K] extends (...args: infer A) => infer R ? (...args: A) => [R] extends [void] ? void : Wrapped<Unannotated<R>> : H[K];
 };
+/** A helper's return type as the *test* sees it. {@link annotate} boxes the
+ * value in an {@link Annotated} to pick how the step renders; the daemon
+ * opens that box at the helper boundary, so the annotation never reaches
+ * the caller — in the types either. Distributes over a union, so a helper
+ * that annotates only when it has something (`return m && annotate(m, "email")`)
+ * still reads as `T | undefined`. */
+type Unannotated<R> = R extends Annotated<infer U> ? U : R;
 /** Awaited return type of a fake's `helpers` factory (with each result
  * inspect-wrapped, see {@link WrappedHelpers}), or `{ state: S }` (the
  * default) when the user didn't ship one. */

package/dist/index.js

@@ -16,6 +16,14 @@ import { adoptNullishTag, readRaw, readTag } from "./inspect.js";
 // always wrapped (in every context), so the method is always there; there is no
 // `unwrap(x)` free function. See the `.unwrap()` discipline section of `spectest docs`.
 export { field } from "./inspect.js";
+// Render annotations for fake helpers: a helper returns
+// `annotate(value, "email", { … })` or `annotate(value, "chat", { … })`
+// when its value is one of those, and the fake step it records gains a
+// nested event drawing it — an email mail-client style, a conversation as
+// bubbles — which the step's panel leads with, tabbing to the raw JSON
+// value. The kind picks the options' type, and the test still gets the raw
+// value, with the raw value's type — see `annotate.ts`.
+export { annotate } from "./annotate.js";
 // Instrumented client primitives — drop-in replacements for Bun's native
 // clients that record each operation on the test event log and return their
 // results inspect-wrapped, so `expect(...)` on a result links back to the op

package/dist/recorder.d.ts

@@ -1,4 +1,4 @@
-export type TestEvent = ExecEvent | AssertionEvent | HttpEvent | KubeEvent | BrowserEvent | DbEvent | RedisEvent | S3Event | TerminalEvent | TerminalStepEvent | WaitEvent | FakeEvent | EnvEvent | EmailEvent;
+export type TestEvent = ExecEvent | AssertionEvent | HttpEvent | KubeEvent | BrowserEvent | DbEvent | RedisEvent | S3Event | TerminalEvent | TerminalStepEvent | WaitEvent | FakeEvent | EnvEvent | EmailEvent | StepEvent;
 interface BaseEvent {
     /** Order of *start* within the test. Reserved when an op begins (see
      *  `reserveEvent`), so an op whose nested children finish — and record —
@@ -18,6 +18,15 @@ interface BaseEvent {
      * timelines. The parent event is identified by its `seq`.
      */
     parentSeq?: number;
+    /**
+     * Set when this event is not an op of its own but *another view of its
+     * parent's value* — what a fake helper's `annotate(...)` records
+     * (`annotate.ts`). The two kinds of `parentSeq` child read differently
+     * and render differently: a `ctx.poll` iteration is work the step did,
+     * and belongs below it; an annotation is the same value drawn better,
+     * and belongs in place of it (the dashboard tabs between the two).
+     */
+    annotation?: boolean;
 }
 export interface ExecEvent extends BaseEvent {
     kind: "exec";
@@ -311,14 +320,17 @@ export interface EmailEventMessage {
         size: number;
     }[];
 }
-/** One row of a mailbox listing embedded on an {@link EmailEvent}. */
-export interface EmailEventSummary {
-    from?: string;
-    to?: string[];
-    subject?: string;
-    /** Plain-text preview of the body. */
+/**
+ * One row of a mailbox listing embedded on an {@link EmailEvent}. A row is a
+ * message: the dashboard lists rows as `to` + subject and expands the one you
+ * click into the same view a single-message op renders, so whatever body the
+ * producer has belongs here. Mailpit's list API returns no bodies, so
+ * `email()`'s own listings fill only the header fields plus `snippet` — a row
+ * with no body expands to its preview instead.
+ */
+export interface EmailEventSummary extends EmailEventMessage {
+    /** Plain-text preview of the body, shown when the row carries no body. */
     snippet?: string;
-    date?: string;
 }
 /**
  * One call to an email service's helpers (`ctx.svc.<name>.lastEmail(...)`
@@ -332,9 +344,13 @@ export interface EmailEventSummary {
  */
 export interface EmailEvent extends BaseEvent {
     kind: "email";
-    /** Service key of the mail server (`ctx.svc.<service>`). */
+    /** Service key of the mail server (`ctx.svc.<service>`) — or the fake's
+     *  name, when a fake helper annotated its return with `annotate(v, "email")`
+     *  (`annotate.ts`) and this event hangs off that call's `fake` one as a
+     *  `parentSeq` child. */
     service: string;
-    /** Helper called, e.g. `"lastEmail"`. */
+    /** Helper called, e.g. `"lastEmail"` — the fake's member name for an
+     *  annotated fake-helper call. */
     op: string;
     /** Human-readable match criteria, e.g. `to alice@example.com`. */
     query?: string;
@@ -541,6 +557,74 @@ export declare function recordTerminal(ev: Omit<TerminalEvent, "seq" | "tOffsetM
 export declare function recordTerminalStep(ev: Omit<TerminalStepEvent, "seq" | "tOffsetMs" | "kind">, reservation?: EventReservation): number | undefined;
 export declare function recordFake(ev: Omit<FakeEvent, "seq" | "tOffsetMs" | "kind">, reservation?: EventReservation): number | undefined;
 export declare function recordEnv(ev: Omit<EnvEvent, "seq" | "tOffsetMs" | "kind">, reservation?: EventReservation): number | undefined;
+/**
+ * One block of step detail, in the dashboard's presentation vocabulary
+ * (`crates/control-plane/src/web/blocks.rs`, which owns the closed set).
+ * A server that predates a block type skips it rather than failing, so a
+ * newer SDK's step degrades to the blocks the server knows.
+ */
+export type StepBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "code";
+    code: string;
+    lang?: string;
+    label?: string;
+} | {
+    type: "json";
+    value: unknown;
+    label?: string;
+} | {
+    type: "kv";
+    rows: {
+        label: string;
+        value?: string;
+        error?: boolean;
+    }[];
+} | {
+    type: "table";
+    columns: string[];
+    rows: unknown[][];
+} | {
+    type: "htmlSandbox";
+    html: string;
+    label?: string;
+} | {
+    type: "chat";
+    messages: ChatBlockMessage[];
+    label?: string;
+};
+/** One message of a `chat` block. */
+export interface ChatBlockMessage {
+    /** Who sent it. The transcript is drawn as the end user would see it, so
+     *  `self` (the end user's own messages) sits on the right and `other` on
+     *  the left. */
+    side?: "self" | "other";
+    text?: string;
+    /** Arrived in *this* step: drawn with an entrance animation. Only the
+     *  producer knows this, so only the producer sets it. */
+    new?: boolean;
+}
+/**
+ * A step that describes itself in presentation terms — a title plus an
+ * ordered list of blocks — instead of as one of the recorder's hard-coded
+ * kinds. This is the seam that lets a component ship a new kind of step
+ * with no server change: `kind` stays an opaque grouping/diff-alignment
+ * label and never decides how the step draws.
+ */
+export interface StepEvent extends BaseEvent {
+    /** Opaque. Groups the step and aligns it across runs; never matched on
+     *  to pick a renderer. */
+    kind: string;
+    /** The step's one-line summary in the timeline. */
+    title: string;
+    blocks?: StepBlock[];
+    status?: "passed" | "failed" | "error";
+    durationMs?: number;
+    error?: string;
+}
+export declare function recordStep(ev: Omit<StepEvent, "seq" | "tOffsetMs">, reservation?: EventReservation): number | undefined;
 export declare function recordEmail(ev: Omit<EmailEvent, "seq" | "tOffsetMs" | "kind">, reservation?: EventReservation): number | undefined;
 /**
  * Recorded once per `ctx.poll(...)` call. Stands in for the suppressed

package/dist/recorder.js

@@ -49,14 +49,24 @@ class Recorder {
             this.events.length = toLen;
         }
     }
-    /** Stamp `parentSeq` onto every event at index >= `startIdx`. Used
-     *  by `ctx.poll` to group the kept iteration's events under the
-     *  resulting wait event. */
+    /** Stamp `parentSeq` onto every event at index >= `startIdx` that isn't
+     *  already grouped under something else. Used by `ctx.poll` to group the
+     *  kept iteration's events under the resulting wait event.
+     *
+     *  An event that already carries a `parentSeq` keeps it: it belongs to a
+     *  step *inside* this one, and re-parenting it here would flatten the
+     *  nesting the UI renders from. The case that made this matter is a fake
+     *  helper called in a poll predicate — its `annotate(...)` child is the
+     *  fake call's value, and stamping the wait's seq over it made the WAIT
+     *  render as an email/chat while the fake call showed raw JSON. Its
+     *  ancestor is still the wait, one level up through the fake event. */
     markChildren(startIdx, parentSeq) {
         for (let i = startIdx; i < this.events.length; i++) {
             const ev = this.events[i];
             if (ev.seq === parentSeq)
                 continue;
+            if (ev.parentSeq !== undefined)
+                continue;
             ev.parentSeq = parentSeq;
         }
     }
@@ -178,6 +188,9 @@ export function recordFake(ev, reservation) {
 export function recordEnv(ev, reservation) {
     return active() ? current.push({ kind: "env", ...ev }, reservation) : undefined;
 }
+export function recordStep(ev, reservation) {
+    return active() ? current.push(ev, reservation) : undefined;
+}
 export function recordEmail(ev, reservation) {
     return active() ? current.push({ kind: "email", ...ev }, reservation) : undefined;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.48.0",
+  "version": "0.50.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/annotate.ts

@@ -0,0 +1,395 @@
+// Render annotations — how a fake tells the dashboard to draw a helper's
+// return value as something richer than JSON.
+//
+// A fake helper call is recorded as a `fake` step and its return value is
+// rendered as pretty JSON, which is the right default for arbitrary data.
+// When the value *is* a domain object the timeline already draws well — an
+// email, today — the fake says so: `return annotate(msg, "email", {…})`.
+// The call is still recorded as the `fake` step it is; the annotation rides
+// *under* it as a child event (`parentSeq`, marked `annotation`) of the kind
+// that already knows how to draw this — for `"email"`, the very event the
+// built-in `email()` component's mailbox helpers record — so the dashboard
+// renders it mail-client style (header block + sandboxed HTML body) with no
+// new rendering code. It leads the step's detail panel; the raw JSON value
+// is a tab away.
+//
+// One function, keyed by kind: the kind is a key of `AnnotationOptions`, so
+// the options argument is typed against the kind that was named, and a new
+// kind is an entry in that interface (+ a case in `lower`, + an arm in
+// `daemon.ts::recordAnnotatedCall`) rather than a new export.
+//
+// The test is unaffected. `annotate` returns a box that the daemon opens at
+// the helper boundary (`daemon.ts::invokeFakeHelper`), so the caller gets
+// the raw value back, inspect-wrapped as always, and the *type* it sees is
+// still the raw value's (`WrappedHelpers` in index.ts unwraps `Annotated`).
+// Assertions keep linking to the fake step, exactly as for an unannotated
+// helper. The annotation is a rendering hint and nothing else.
+//
+// This is a fake-helper mechanism: those calls go through a tracking proxy
+// that can open the box. A *service* helper (`ctx.svc.<name>.…`) is the raw
+// record its factory returned, so an annotation there would reach the test
+// as an opaque value — don't.
+
+import { deepUnwrap } from "./inspect.js";
+import {
+  truncateUtf8,
+  type ChatBlockMessage,
+  type EmailEventMessage,
+  type EmailEventSummary,
+  type StepBlock,
+} from "./recorder.js";
+
+/**
+ * Runtime marker on the box `annotate(...)` returns. `Symbol.for` rather
+ * than a module-local symbol so a second copy of the SDK still recognises
+ * a box minted by the first — the duplicate-module-instance hazard that
+ * silently drops assertion events when the SDK lands in an app dir twice
+ * (see `sdk.rs`).
+ */
+const ANNOTATION = Symbol.for("spectest.render-annotation");
+
+/** Phantom brand — `Annotated<T>` is nominally distinct from `T`, so the
+ *  box can't be read as the value by accident inside the fake, and the
+ *  helper types can recognise it and hand the *test* back a plain `T`. */
+declare const ANNOTATED: unique symbol;
+
+/**
+ * A value plus a rendering hint, as returned by {@link annotate}. Return it
+ * straight from a fake helper: the daemon unwraps it, so the test receives
+ * the value itself and `ctx.fakes.<name>.<fn>()` is typed as if the
+ * annotation weren't there.
+ */
+export interface Annotated<T> {
+  readonly [ANNOTATED]: T;
+}
+
+/**
+ * Every annotation kind, and the options each one takes. This interface is
+ * the whole type contract of {@link annotate}: naming a kind picks the type
+ * of the options argument, so a stray field or a value that belongs to
+ * another kind is a compile error at the call site.
+ *
+ * A new kind is an entry here, a case in `lower`, and an arm in
+ * `daemon.ts::recordAnnotationChild`.
+ */
+export interface AnnotationOptions {
+  /** Draw the value as an email — one message, or a list of them for a
+   *  mailbox listing. See {@link EmailAnnotation}. */
+  email: EmailAnnotation | readonly EmailAnnotation[];
+  /** Draw the value as a chat transcript — bubbles by role, with the
+   *  messages that arrived in this call marked. See {@link ChatAnnotation}. */
+  chat: ChatAnnotation | readonly ChatMessageAnnotation[];
+}
+
+/** The kinds {@link annotate} accepts. */
+export type AnnotationKind = keyof AnnotationOptions;
+
+/**
+ * What an annotation lowers to: the fields of the child event the daemon
+ * records under the call's own `fake` one. Tagged by that event's `kind` —
+ * which needn't be the annotation kind's name, since an annotation names
+ * what the value *is* and the event names how it's drawn.
+ */
+export type RenderAnnotation = EmailRenderAnnotation | ChatRenderAnnotation;
+
+type EmailRenderAnnotation = {
+  kind: "email";
+  /** Single-message ops. */
+  message?: EmailEventMessage;
+  /** Listing ops. */
+  messages?: EmailEventSummary[];
+  /** Total matches (a listing is capped on the event, never in the value). */
+  count?: number;
+};
+
+/** A chat lowers to a step that describes itself in presentation terms — a
+ *  title plus blocks — rather than to a kind of its own: `blocks.rs` owns
+ *  the drawing vocabulary, and a transcript is one of its block types. */
+type ChatRenderAnnotation = {
+  kind: "chat";
+  title?: string;
+  blocks: StepBlock[];
+};
+
+/**
+ * The email fields to render. Every one is optional — pass what the fake
+ * has. Addresses take a single string or a list.
+ *
+ * The event can also carry a date, per-row previews and attachment
+ * metadata, which the built-in `email()` component fills from a really
+ * captured message; a fake's mail was never sent, so those are deliberately
+ * not offered here. A listing row's preview is derived from the body.
+ */
+export interface EmailAnnotation {
+  from?: string;
+  to?: string | readonly string[];
+  cc?: string | readonly string[];
+  bcc?: string | readonly string[];
+  subject?: string;
+  /** HTML body. Rendered in a fully sandboxed iframe (scripts off). */
+  html?: string;
+  /** Plain-text body. Shown on its own when there's no HTML, folded into a
+   *  "Plain-text version" disclosure when there is. */
+  text?: string;
+}
+
+/**
+ * A conversation to draw as chat bubbles.
+ *
+ * Two sides and their text, which is all a transcript needs to read as one.
+ * It is drawn from the end user's point of view — their own messages on the
+ * right, the other party's on the left.
+ * Pass the messages alone (`annotate(v, "chat", messages)`), or this object
+ * when the thread has an identity worth showing. With no options at all the
+ * value itself is read as the message list.
+ */
+export interface ChatAnnotation {
+  messages: readonly ChatMessageAnnotation[];
+  /**
+   * The thread's identity — a phone number, a channel, whoever is on the
+   * other end — shown as a header over the bubbles. Optional: a fake with
+   * one conversation has nothing useful to put here, and the transcript
+   * reads fine without it.
+   */
+  title?: string;
+}
+
+/** One turn of a {@link ChatAnnotation}. */
+export interface ChatMessageAnnotation {
+  /**
+   * Who sent it. A transcript is drawn the way the **end user** would see
+   * it on their own screen, so `self` is the end user's own messages — the
+   * person using the app under test — and sits on the right; `other` is
+   * whoever they are talking to and sits on the left.
+   */
+  side: "self" | "other";
+  text: string;
+  /**
+   * This message arrived in *this* call: it slides in when the step opens,
+   * and again whenever it is reopened. Only the fake knows which turns are new —
+   * the dashboard sees one call, not the conversation's history — so it is
+   * the fake that marks them.
+   */
+  new?: boolean;
+}
+
+/** Listing rows carried on the event. The returned value is never capped. */
+const LIST_CAP = 50;
+
+/** How much of a body becomes a listing row's preview. */
+const SNIPPET_CHARS = 200;
+
+const NO_FIELDS =
+  'annotate(value, "email"): nothing to render — no email fields found on ' +
+  "the value. Pass them explicitly, e.g. " +
+  'annotate(value, "email", { to: value.recipient, subject: value.title, ' +
+  "html: value.body }).";
+
+/**
+ * Say what a fake helper's return value *is*, so the timeline can draw it
+ * as that on top of the JSON it always shows. The call stays an ordinary
+ * fake step; the rendered view nests inside it. The value is returned to
+ * the test unchanged (and unchanged in type).
+ *
+ * ```ts
+ * helpers: ({ state }) => ({
+ *   lastReceipt() {
+ *     const r = state.receipts.at(-1);
+ *     return r && annotate(r, "email", {
+ *       from: "receipts@stripe.test",
+ *       to: r.customer,
+ *       subject: `Receipt for ${r.description}`,
+ *       html: r.body,
+ *     });
+ *   },
+ * })
+ * ```
+ *
+ * `kind` picks what the options are: `"email"` takes an
+ * {@link EmailAnnotation} (or a list of them, which renders a mailbox
+ * listing instead of one message). Every field is optional, and with no
+ * options at all they're read off the value itself — enough when it already
+ * carries `from`/`to`/`subject`/`html`/`text`. Throws if there is nothing to
+ * render, rather than recording an empty step.
+ */
+export function annotate<T, K extends AnnotationKind>(
+  value: T,
+  kind: K,
+  options?: AnnotationOptions[K],
+): Annotated<T> {
+  return box(value, lower(kind, options, value));
+}
+
+/** Turn a kind + its options into the event fields to record. */
+function lower<K extends AnnotationKind>(
+  kind: K,
+  options: AnnotationOptions[K] | undefined,
+  value: unknown,
+): RenderAnnotation {
+  switch (kind) {
+    case "email":
+      return lowerEmail(options as AnnotationOptions["email"] | undefined, value);
+    case "chat":
+      return lowerChat(options as AnnotationOptions["chat"] | undefined, value);
+    default:
+      // Unreachable while `kind` is a key of AnnotationOptions; a kind added
+      // to that interface without a case here lands on this line.
+      throw new Error(`annotate(): unknown annotation kind ${String(kind)}`);
+  }
+}
+
+function lowerEmail(
+  options: AnnotationOptions["email"] | undefined,
+  value: unknown,
+): RenderAnnotation {
+  // `deepUnwrap` only where fields are *read* — a value off another
+  // instrumented call is a provenance carrier, and `String(carrier)` would
+  // otherwise be its coerced shape rather than the address it holds. The
+  // value handed back to the test is never touched.
+  const source: unknown = deepUnwrap(options ?? value);
+  if (Array.isArray(source)) {
+    const messages = source.slice(0, LIST_CAP).map((m) => summaryOf(fields(m)));
+    if (source.length > 0 && messages.every((m) => isEmpty(m))) {
+      throw new Error(NO_FIELDS);
+    }
+    return { kind: "email", messages, count: source.length };
+  }
+  const message = messageOf(fields(source));
+  if (isEmpty(message)) throw new Error(NO_FIELDS);
+  return { kind: "email", message };
+}
+
+/** Open an annotation box. Returns `undefined` for any ordinary value, so
+ *  call sites can treat annotation as the exception it is. */
+export function readAnnotation(
+  value: unknown,
+): { annotation: RenderAnnotation; value: unknown } | undefined {
+  if (typeof value !== "object" || value === null) return undefined;
+  const annotation = (value as Record<symbol, unknown>)[ANNOTATION] as
+    | RenderAnnotation
+    | undefined;
+  if (!annotation) return undefined;
+  return { annotation, value: (value as { value: unknown }).value };
+}
+
+function box<T>(value: T, annotation: RenderAnnotation): Annotated<T> {
+  return { [ANNOTATION]: annotation, value } as unknown as Annotated<T>;
+}
+
+function isEmpty(o: object): boolean {
+  return Object.keys(o).length === 0;
+}
+
+/** The value as a field bag — anything that isn't an object contributes
+ *  nothing, and falls through to the `NO_FIELDS` error. */
+function fields(v: unknown): Record<string, unknown> {
+  return typeof v === "object" && v !== null
+    ? (v as Record<string, unknown>)
+    : {};
+}
+
+const NO_MESSAGES =
+  'annotate(value, "chat"): nothing to render — no messages found on the ' +
+  "value. Pass them explicitly, e.g. " +
+  'annotate(value, "chat", value.turns.map((t) => ({ side: t.fromCustomer ? "self" : "other", text: t.body }))).';
+
+function lowerChat(
+  options: AnnotationOptions["chat"] | undefined,
+  value: unknown,
+): RenderAnnotation {
+  const source: unknown = deepUnwrap(options ?? value);
+  let list: unknown;
+  let title: string | undefined;
+  if (Array.isArray(source)) {
+    list = source;
+  } else {
+    const bag = fields(source);
+    list = bag.messages;
+    title = text(bag.title) || undefined;
+  }
+  // An empty conversation is a real state (nothing said yet) and renders as
+  // one; a value with no `messages` at all is the author's mistake.
+  if (!Array.isArray(list)) throw new Error(NO_MESSAGES);
+  const messages = list.map((m) => chatMessageOf(fields(m)));
+  // The title travels twice on purpose: as the step's own summary, and as
+  // the transcript's header — the annotated view renders the blocks alone,
+  // so a title carried only on the step would never be seen.
+  return {
+    kind: "chat",
+    title,
+    blocks: [{ type: "chat", messages, ...(title ? { label: title } : {}) }],
+  };
+}
+
+function chatMessageOf(src: Record<string, unknown>): ChatBlockMessage {
+  const msg: ChatBlockMessage = {};
+  // Anything that isn't the end user's own message is drawn as the other
+  // party's, rather than a turn being dropped for a typo.
+  if (text(src.side) === "self") msg.side = "self";
+  else msg.side = "other";
+  const body = text(src.text);
+  if (body) msg.text = truncateUtf8(body).value;
+  if (src.new === true) msg.new = true;
+  return msg;
+}
+
+function messageOf(src: Record<string, unknown>): EmailEventMessage {
+  const msg: EmailEventMessage = {};
+  const from = text(src.from);
+  if (from) msg.from = from;
+  for (const key of ["to", "cc", "bcc"] as const) {
+    const addrs = addresses(src[key]);
+    if (addrs.length > 0) msg[key] = addrs;
+  }
+  const subject = text(src.subject);
+  if (subject) msg.subject = subject;
+  const html = text(src.html);
+  if (html) {
+    const t = truncateUtf8(html);
+    msg.html = t.value;
+    if (t.truncated) msg.htmlTruncated = true;
+  }
+  const body = text(src.text);
+  if (body) {
+    const t = truncateUtf8(body);
+    msg.text = t.value;
+    if (t.truncated) msg.textTruncated = true;
+  }
+  return msg;
+}
+
+/** A listing row is a whole message plus its preview line — the dashboard
+ *  expands the row you click into the full view, so the body has to ride
+ *  along rather than being summarised away. */
+function summaryOf(src: Record<string, unknown>): EmailEventSummary {
+  const row: EmailEventSummary = messageOf(src);
+  const snippet = preview(text(src.text), text(src.html));
+  if (snippet) row.snippet = snippet;
+  return row;
+}
+
+/** A listing row's preview: the plain-text body if there is one, else the
+ *  HTML with its tags stripped — enough to tell two messages apart. */
+function preview(body: string, html: string): string {
+  const raw = body || html.replace(/<[^>]*>/g, " ");
+  const collapsed = raw.replace(/\s+/g, " ").trim();
+  return collapsed.length > SNIPPET_CHARS
+    ? `${collapsed.slice(0, SNIPPET_CHARS)}…`
+    : collapsed;
+}
+
+/** Scalars render as themselves; anything else (an object, a nested array)
+ *  is not an address or a subject line and is dropped rather than shown as
+ *  `[object Object]`. */
+function text(v: unknown): string {
+  if (typeof v === "string") return v;
+  if (typeof v === "number" || typeof v === "boolean") return String(v);
+  return "";
+}
+
+function addresses(v: unknown): string[] {
+  if (typeof v === "string") return v ? [v] : [];
+  if (!Array.isArray(v)) return [];
+  return v.map((a) => text(a)).filter((a) => a.length > 0);
+}
+