@specific.dev/spectest 0.48.0 → 0.50.0

package/dist/annotate.d.ts

@@ -0,0 +1,151 @@
+import { type EmailEventMessage, type EmailEventSummary, type StepBlock } from "./recorder.js";
+/** 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;
+}
+/**
+ * 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 declare function annotate<T, K extends AnnotationKind>(value: T, kind: K, options?: AnnotationOptions[K]): Annotated<T>;
+/** Open an annotation box. Returns `undefined` for any ordinary value, so
+ *  call sites can treat annotation as the exception it is. */
+export declare function readAnnotation(value: unknown): {
+    annotation: RenderAnnotation;
+    value: unknown;
+} | undefined;
+export {};

package/dist/annotate.js

@@ -0,0 +1,242 @@
+// 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, } 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");
+/** 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(value, kind, options) {
+    return box(value, lower(kind, options, value));
+}
+/** Turn a kind + its options into the event fields to record. */
+function lower(kind, options, value) {
+    switch (kind) {
+        case "email":
+            return lowerEmail(options, value);
+        case "chat":
+            return lowerChat(options, 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, value) {
+    // `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 = 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) {
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    const annotation = value[ANNOTATION];
+    if (!annotation)
+        return undefined;
+    return { annotation, value: value.value };
+}
+function box(value, annotation) {
+    return { [ANNOTATION]: annotation, value };
+}
+function isEmpty(o) {
+    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) {
+    return typeof v === "object" && v !== null
+        ? v
+        : {};
+}
+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, value) {
+    const source = deepUnwrap(options ?? value);
+    let list;
+    let title;
+    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) {
+    const msg = {};
+    // 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) {
+    const msg = {};
+    const from = text(src.from);
+    if (from)
+        msg.from = from;
+    for (const key of ["to", "cc", "bcc"]) {
+        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) {
+    const row = 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, html) {
+    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) {
+    if (typeof v === "string")
+        return v;
+    if (typeof v === "number" || typeof v === "boolean")
+        return String(v);
+    return "";
+}
+function addresses(v) {
+    if (typeof v === "string")
+        return v ? [v] : [];
+    if (!Array.isArray(v))
+        return [];
+    return v.map((a) => text(a)).filter((a) => a.length > 0);
+}

package/dist/daemon.js

@@ -44,7 +44,8 @@ import { runContainerArgs } from "./harness/container-run.js";
 import { assertAbsolute, certificateHostnames, defaultKeyMode, expandServiceToken, isNoopChown, mountFlag, needsIdTables, numericId, resolveChownIds, } from "./harness/file-mounts.js";
 import { conflict, notFound, requireString, } from "./harness/methods.js";
 import { openTerminal } from "./terminal.js";
-import { recordEnv, recordExec, recordFake, recordHttp, recordTerminal, recordWait, reserveEvent, recorderEventCount, recorderMarkChildren, recorderTruncate, startRecording, stopRecording, truncateUtf8, } from "./recorder.js";
+import { readAnnotation } from "./annotate.js";
+import { pauseRecording, recordEmail, recordEnv, recordExec, recordFake, recordHttp, recordStep, recordTerminal, recordWait, reserveEvent, recorderEventCount, recorderMarkChildren, recorderTruncate, resumeRecording, startRecording, stopRecording, truncateUtf8, } from "./recorder.js";
 import { deepUnwrap, wrap, wrapResponse } from "./inspect.js";
 import { clearRecordSecrets, setRecordSecrets } from "./record-secrets.js";
 import { encodeReplayBundle, replayChunk } from "./replay-bundle.js";
@@ -828,13 +829,126 @@ async function prepareServiceImage(svc, opts) {
     }
     return buildServiceImage(svc.name, image, tag);
 }
+/**
+ * What the folded CA step prints when it could not write the trust store
+ * at all — the one outcome that still needs {@link ensureCaTrustedImage},
+ * which can take root for the write.
+ *
+ * The step assembles this prefix from a shell variable so that the marker
+ * appears ONLY in the step's output. BuildKit echoes each instruction into
+ * the same log verbatim, so a marker written literally in the RUN would
+ * match on every build whether or not the step ever printed it.
+ */
+const CA_FOLD_UNWRITABLE = "[spectest-ca] trust store not writable";
+/**
+ * The CA-trust steps as a suffix appended to a dockerfile service's OWN
+ * Dockerfile, so one build produces the finished image instead of a build
+ * plus a derivative rebuild ({@link ensureCaTrustedImage}) per service.
+ * Returns null when there is no CA to layer, or when the PEM can't be
+ * quoted — the caller then falls back to the derivative build.
+ *
+ * The PEM is written INLINE rather than `COPY`d: the build context is
+ * `/workspace` under a per-service ignore file that the project itself
+ * contributes to (a `**` line with re-includes is the common idiom), and
+ * a context path we don't control is a context path that can be excluded.
+ * printf needs nothing but a shell.
+ *
+ * Two rules make this safe to bolt onto user code. It must never fail the
+ * build — every branch ends in an echo, so the RUN exits 0 whatever the
+ * image lacks — and it must never change the image, beyond the trust
+ * store: notably no `USER root`, since we cannot know statically what
+ * user to hand back. An image that declares a non-root user therefore
+ * fails to write and is finished by the derivative build, which inspects
+ * the built image and can escalate properly.
+ */
+async function caTrustSuffix() {
+    if (!existsSync(CA_PATH))
+        return null;
+    const pem = (await fs.readFile(CA_PATH, "utf8")).trim();
+    // A quote in the PEM would break out of the shell quoting below. PEM is
+    // base64 and dashes, so this is a guard, not a case we expect.
+    if (!pem || pem.includes("'"))
+        return null;
+    const args = pem
+        .split("\n")
+        .map((l) => `'${l.trimEnd()}'`)
+        .join(" ");
+    const dst = "/usr/local/share/ca-certificates/spectest-ca.crt";
+    return `
+# spectest: trust the environment's root CA. Appended by the harness —
+# not part of the project's Dockerfile.
+RUN P='[spectest-ca]'; \\
+    mkdir -p /usr/local/share/ca-certificates 2>/dev/null; \\
+    if printf '%s\\n' ${args} > ${dst} 2>/dev/null; then \\
+      if command -v update-ca-certificates >/dev/null 2>&1 && update-ca-certificates >/dev/null 2>&1; then \\
+        echo "$P trusted via update-ca-certificates"; \\
+      elif command -v update-ca-trust >/dev/null 2>&1 && cp ${dst} /etc/pki/ca-trust/source/anchors/spectest-ca.crt && update-ca-trust extract >/dev/null 2>&1; then \\
+        echo "$P trusted via update-ca-trust"; \\
+      else \\
+        echo "$P no system CA trust tool in image; env-var trust only"; \\
+      fi; \\
+    else \\
+      echo "$P trust store not writable by this image's user"; \\
+    fi
+`;
+}
+/**
+ * Build a dockerfile service's image.
+ *
+ * The CA-trust layer is folded into THIS build when it can be (see
+ * {@link caTrustSuffix}), so a service costs one image build and one
+ * export rather than two. The derivative build stays as the fallback for
+ * everything the folded form can't serve: an image with no shell to run
+ * the step (distroless, scratch — the appended RUN can't execute, so the
+ * build fails and we rebuild the project's Dockerfile untouched), and an
+ * image that declares a non-root user (the step runs as that user and
+ * can't write the trust store).
+ */
 async function buildServiceImage(name, image, tag) {
+    const suffix = await caTrustSuffix();
+    let attempt = await runServiceBuild(name, image, tag, suffix);
+    if (!attempt.ok && suffix) {
+        // Our step must not be able to break a project's build.
+        // eslint-disable-next-line no-console
+        console.warn(`[ca-trust] folded CA step could not run in ${name}'s image; rebuilding without it`);
+        attempt = await runServiceBuild(name, image, tag, null);
+    }
+    if (!attempt.ok) {
+        progressService(name, { status: "failed" });
+        throw new Error(`docker build for ${name} failed:\n${attempt.log}`);
+    }
+    // The derivative build is still needed for the one thing the folded step
+    // cannot do: write the trust store of an image that does not run as
+    // root. That is decided on the IMAGE, not on the build log — a CACHED
+    // layer prints nothing, so a log-only check would quietly stop
+    // re-applying the moment BuildKit had the layer. The log covers the
+    // rarer case of a root image whose /etc is read-only.
+    //
+    // An image with no trust tool at all needs nothing further: the
+    // derivative build would reach the same dead end, and `runContainer`'s
+    // env vars are the fallback either way.
+    const needsDerivative = !attempt.folded ||
+        attempt.log.includes(CA_FOLD_UNWRITABLE) ||
+        !(await imageRunsAsRoot(tag));
+    if (needsDerivative)
+        await ensureCaTrustedImage(name, tag);
+    return { tag, buildSteps: attempt.buildSteps };
+}
+/** Whether `tag`'s declared `USER` is root (or unset, which means root). */
+async function imageRunsAsRoot(tag) {
+    const user = (await docker(["image", "inspect", "--format", "{{.Config.User}}", tag], 60_000)).stdout.trim();
+    return user === "" || user === "root" || user === "0";
+}
+async function runServiceBuild(name, image, tag, caSuffix) {
     let buildSteps;
     {
+        const content = caSuffix
+            ? `${image.content.replace(/\n*$/, "\n")}${caSuffix}`
+            : image.content;
         const dfDir = path.join(WORKSPACE, ".spectest", "services", name);
         await fs.mkdir(dfDir, { recursive: true });
         const dfPath = path.join(dfDir, "Dockerfile");
-        await fs.writeFile(dfPath, image.content);
+        await fs.writeFile(dfPath, content);
         // Per-service ignore: BuildKit resolves `<Dockerfile>.dockerignore`
         // (next to the Dockerfile) in preference to the context root's
         // `.dockerignore`, so this build sees the defaults, the project's own
@@ -896,9 +1010,11 @@ async function buildServiceImage(name, image, tag) {
                 });
             }
         });
+        const log = `${build.stderr.trim()}\n${build.stdout.trim()}`;
         if (build.code !== 0) {
-            progressService(name, { status: "failed" });
-            throw new Error(`docker build for ${name} failed:\n${build.stderr.trim()}\n${build.stdout.trim()}`);
+            // The caller decides whether this is fatal: a failure with the CA
+            // step appended is retried without it before anyone hears about it.
+            return { ok: false, folded: caSuffix !== null, log };
         }
         if (useBuildKit) {
             // Keep only the slowest dozen steps ≥1s — enough to profile, small
@@ -907,14 +1023,8 @@ async function buildServiceImage(name, image, tag) {
                 .filter((s) => s.secs >= 1)
                 .slice(0, 12);
         }
+        return { ok: true, folded: caSuffix !== null, log, buildSteps };
     }
-    // Layer the spectest CA into the image's system trust store so apps
-    // that read the system bundle (Go, Java, CLIs that don't honour the
-    // SSL_CERT_FILE env vars) accept HTTPS to fakes. Best-effort: images
-    // without `update-ca-certificates` / `update-ca-trust` (distroless,
-    // scratch) fall through to the env-var path that `runContainer` sets.
-    await ensureCaTrustedImage(name, tag);
-    return { tag, buildSteps };
 }
 /**
  * Build a derivative image on top of `tag` that copies the spectest
@@ -2262,14 +2372,27 @@ function invokeFakeHelper(fakeName, member, fn, thisArg, callArgs) {
     const args = callArgs.map((a) => deepUnwrap(a));
     const safeArgs = args.map((a) => safeSerialize(a));
     const recordResult = (value) => {
+        // A helper may box its return in a render annotation
+        // (`annotate(v, "email", …)`). The box never reaches the test, and it
+        // never replaces the step either: the call is recorded as the ordinary
+        // `fake` event it is, and the annotation rides *under* it as a child
+        // event (`parentSeq`), which the dashboard folds into the fake step's
+        // detail panel. So the timeline reads the same as any other helper
+        // call, with the richer view one click in.
+        const annotated = readAnnotation(value);
+        const raw = annotated ? annotated.value : value;
+        const durationMs = Date.now() - t;
         const seq = recordFake({
             fake: fakeName,
             member,
             args: safeArgs,
-            result: safeSerialize(value),
-            durationMs: Date.now() - t,
+            result: safeSerialize(raw),
+            durationMs,
         }, resv);
-        return wrap(value, seq);
+        if (annotated && seq !== undefined) {
+            recordAnnotationChild(fakeName, member, annotated.annotation, durationMs, seq);
+        }
+        return wrap(raw, seq);
     };
     const recordError = (err) => {
         recordFake({
@@ -2280,22 +2403,83 @@ function invokeFakeHelper(fakeName, member, fn, thisArg, callArgs) {
             error: errMessage(err),
         }, resv);
     };
+    // A helper call is ONE step. Whatever the fake does inside it — a fetch to
+    // deliver a webhook, a call to its own API — is the fake's plumbing, not
+    // something the test did, and it would otherwise land on the timeline as
+    // an `http` step the test never made. The built-in `email()` helpers
+    // already pause around their internal polls by hand for exactly this
+    // reason (`components/email.ts`); doing it here gives every user-authored
+    // fake the same contract without having to know about it.
+    //
+    // The pause spans the helper's `await`s, so genuinely concurrent test work
+    // (`Promise.all([helper(), ctx.fetch(…)])`) loses its events too. That is
+    // the same trade `email()` has always made, and sequential test code — all
+    // of it, in practice — is unaffected.
+    pauseRecording();
     let result;
     try {
         result = fn.apply(thisArg, args);
     }
     catch (err) {
+        resumeRecording();
         recordError(err);
         throw err;
     }
     if (result instanceof Promise) {
-        return result.then(recordResult, (err) => {
+        return result.then((value) => {
+            resumeRecording();
+            return recordResult(value);
+        }, (err) => {
+            resumeRecording();
             recordError(err);
             throw err;
         });
     }
+    resumeRecording();
     return recordResult(result);
 }
+/** Record a fake-helper call's render annotation as a child of the call's
+ * own `fake` event — the same `parentSeq` grouping `ctx.poll` uses for the
+ * iteration it kept, so the annotated view folds into the fake step's
+ * detail panel instead of taking a timeline row of its own.
+ *
+ * The child is the event kind that already knows how to draw this: an
+ * `email` annotation records the very event the built-in `email()`
+ * component's mailbox helpers record, so it renders with no new code. It
+ * carries the fake's name and member as its service/op, and the parent's
+ * duration, since it describes that same call.
+ *
+ * Only the success path is annotated: a helper that threw returned no value
+ * to annotate, so it's a plain `fake` error event. */
+function recordAnnotationChild(fakeName, member, annotation, durationMs, parentSeq) {
+    switch (annotation.kind) {
+        case "email":
+            recordEmail({
+                parentSeq,
+                annotation: true,
+                service: fakeName,
+                op: member,
+                message: annotation.message,
+                messages: annotation.messages,
+                count: annotation.count,
+                durationMs,
+            });
+            break;
+        case "chat":
+            // A chat has no event kind of its own: it describes itself in
+            // presentation terms (title + blocks), which is the seam a new step
+            // type is supposed to use. `kind` stays an opaque grouping label.
+            recordStep({
+                kind: "chat",
+                parentSeq,
+                annotation: true,
+                title: annotation.title ?? `${fakeName}.${member}`,
+                blocks: annotation.blocks,
+                durationMs,
+            });
+            break;
+    }
+}
 function errMessage(err) {
     return err?.message ?? String(err);
 }