@specific.dev/spectest 0.47.0 → 0.49.0

package/dist/annotate.d.ts

@@ -0,0 +1,101 @@
+import { type EmailEventMessage, type EmailEventSummary } 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[];
+}
+/** 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 = {
+    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;
+};
+/**
+ * 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;
+}
+/**
+ * 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,196 @@
+// 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);
+        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
+        : {};
+}
+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/browser.d.ts

@@ -359,4 +359,5 @@ export interface RecordableFields {
     attempts: number;
     artifactId: string;
     attribute: string;
+    files: string[];
 }

package/dist/daemon.js

@@ -34,6 +34,7 @@ import { summarizeBuildKit } from "./harness/buildkit-progress.js";
 import { LOG_DELTA_MAX_BYTES, capMiddle, streamDelta } from "./harness/log-delta.js";
 import { resolveHostPath as resolveVolumeHostPath, sanitizeSegment, } from "./harness/volume-paths.js";
 import { pollUntilReady } from "./harness/ready-poll.js";
+import { APP_DIR, WORKSPACE, resolveProjectPath } from "./project-files.js";
 import { isTextualContentType, looksBinary, omittedBody, parseContentLength, } from "./harness/http-body.js";
 import { encodeRegistry } from "./harness/names-registry.js";
 import { HOP_BY_HOP_HEADERS, augmentCorsResponse, corsPreflightResponse, isCorsPreflight, } from "./harness/http-proxy.js";
@@ -43,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 { recordEmail, recordEnv, recordExec, recordFake, recordHttp, recordTerminal, recordWait, reserveEvent, recorderEventCount, recorderMarkChildren, recorderTruncate, 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";
@@ -52,7 +54,6 @@ function namedServices(cfg) {
 }
 const DEFAULT_TEST_TIMEOUT_MS = 60_000;
 const NETWORK_NAME = process.env.SPECTEST_NETWORK ?? "spectest-net";
-const WORKSPACE = process.env.SPECTEST_WORKSPACE ?? "/workspace";
 // Stable hostname every service container resolves to the host (the
 // `spectest-br0` gateway) — so apps that build or pull images at runtime
 // can point a builder at `spectest-host:5000` (the zot Docker Hub mirror)
@@ -77,7 +78,9 @@ function hostCacheGateway() {
     }
     return _hostCacheGateway;
 }
-const APP_DIR = process.env.SPECTEST_APP_DIR ?? "/opt/spectest/app";
+// WORKSPACE (/workspace) and APP_DIR (/opt/spectest/app) both live in
+// project-files.ts, next to the rule that decides which copy of a project
+// file is the current one.
 // The bun the base snapshot installs (base.rs::BASE_SETUP_SH). The daemon
 // runs under it, and eval's dependency install shells out to it.
 const BUN_BIN = "/usr/local/bin/bun";
@@ -1028,7 +1031,7 @@ async function probeTcp(host, port) {
     return new Promise((resolve) => {
         const sock = net.createConnection({ host, port });
         let settled = false;
-        const finish = (v) => {
+        const finish = (ok, detail) => {
             if (settled)
                 return;
             settled = true;
@@ -1038,26 +1041,30 @@ async function probeTcp(host, port) {
             catch {
                 /* ignore */
             }
-            resolve(v);
+            resolve({ ok, detail });
         };
         sock.setTimeout(2000);
-        sock.once("connect", () => finish(true));
-        sock.once("error", () => finish(false));
-        sock.once("timeout", () => finish(false));
+        sock.once("connect", () => finish(true, `connected to ${host}:${port}`));
+        sock.once("error", (err) => finish(false, `connect to ${host}:${port} failed: ${err.message}`));
+        sock.once("timeout", () => finish(false, `connect to ${host}:${port} got no reply within 2000ms`));
     });
 }
 async function probeHttp(host, port, urlPath, headers, expectStatus) {
+    const url = `http://${host}:${port}${urlPath}`;
     const ctrl = new AbortController();
     const to = setTimeout(() => ctrl.abort(), 5000);
     try {
-        const res = await fetch(`http://${host}:${port}${urlPath}`, {
-            signal: ctrl.signal,
-            headers,
-        });
-        return expectStatus !== undefined ? res.status === expectStatus : res.ok;
+        const res = await fetch(url, { signal: ctrl.signal, headers });
+        const ok = expectStatus !== undefined ? res.status === expectStatus : res.ok;
+        const want = expectStatus !== undefined ? String(expectStatus) : "2xx";
+        return { ok, detail: `GET ${url} → ${res.status} (wanted ${want})` };
     }
-    catch {
-        return false;
+    catch (err) {
+        const e = err;
+        const detail = e?.name === "AbortError"
+            ? `GET ${url} got no reply within 5000ms`
+            : `GET ${url} failed: ${e?.message ?? String(err)}`;
+        return { ok: false, detail };
     }
     finally {
         clearTimeout(to);
@@ -1065,28 +1072,64 @@ async function probeHttp(host, port, urlPath, headers, expectStatus) {
 }
 async function probeExec(name, command) {
     const r = await docker(["exec", name, "sh", "-c", command], 10_000);
-    return r.code === 0;
+    if (r.code === 0)
+        return { ok: true, detail: `\`${command}\` exited 0` };
+    // 124 is shx's own kill (see `shx`): the exec never answered, which says
+    // the docker daemon is wedged or starved rather than anything about the
+    // command's verdict.
+    const why = r.code === 124
+        ? `was killed after 10000ms with no reply`
+        : `exited ${r.code}`;
+    const output = firstLine(r.stderr) || firstLine(r.stdout);
+    return {
+        ok: false,
+        detail: `\`${command}\` ${why}${output ? `: ${output}` : ""}`,
+    };
+}
+/** First non-empty line, trimmed and capped — probe output goes into an
+ *  error message, not a log file. */
+function firstLine(s) {
+    const line = s.split("\n").find((l) => l.trim().length > 0)?.trim() ?? "";
+    return line.length > 200 ? `${line.slice(0, 200)}…` : line;
 }
 async function waitForReady(svc) {
     const check = svc.readyCheck;
     if (!check)
         return;
     const timeoutSecs = check.timeoutSecs ?? 60;
+    let last;
     const probe = async () => {
         if (check.type === "tcp")
-            return probeTcp(svc.name, check.port);
-        if (check.type === "http") {
-            return probeHttp(svc.name, check.port, check.path ?? "/", check.headers, check.expectStatus);
+            last = await probeTcp(svc.name, check.port);
+        else if (check.type === "http") {
+            last = await probeHttp(svc.name, check.port, check.path ?? "/", check.headers, check.expectStatus);
         }
-        return probeExec(svc.name, check.command);
+        else
+            last = await probeExec(svc.name, check.command);
+        return last.ok;
     };
     // Scheduling (the ramp, and not sleeping past the deadline) lives in
     // `harness/ready-poll.ts`; this supplies the probe and the diagnosis.
-    const { ready } = await pollUntilReady(probe, { kind: check.type, timeoutSecs });
+    const { ready, attempts, elapsedMs } = await pollUntilReady(probe, {
+        kind: check.type,
+        timeoutSecs,
+    });
     if (ready)
         return;
+    // The attempt count is half the diagnosis: a probe with a 10s timeout of
+    // its own can only run a handful of times in 60s, so "6 attempts" says the
+    // probes were hanging where "80 attempts" says they ran and kept saying no.
+    let msg = `service ${svc.name} not ready within ${timeoutSecs}s ` +
+        `(${attempts} ${check.type} probe${attempts === 1 ? "" : "s"} over ${Math.round(elapsedMs / 100) / 10}s).`;
+    if (last)
+        msg += `\nLast probe: ${last.detail}`;
     const logs = await docker(["logs", "--tail=200", svc.name], 30_000);
-    throw new Error(`service ${svc.name} not ready within ${timeoutSecs}s. Recent container logs:\n${logs.stdout}\n${logs.stderr}`);
+    const output = `${logs.stdout}\n${logs.stderr}`.trim();
+    // A service that logs nothing (`sleep infinity`, a quiet daemon) used to
+    // get an empty "Recent container logs:" heading, which reads as if the
+    // logs were the evidence and there simply weren't any.
+    msg += output ? `\nRecent container logs:\n${output}` : `\n(the container logged nothing)`;
+    throw new Error(msg);
 }
 /** Validate the `dependsOn` graph and return the name→service map used to
  *  walk it. Rules live in `harness/service-graph.ts`. */
@@ -2220,14 +2263,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({
@@ -2254,6 +2310,35 @@ function invokeFakeHelper(fakeName, member, fn, thisArg, callArgs) {
     }
     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;
+    }
+}
 function errMessage(err) {
     return err?.message ?? String(err);
 }
@@ -2926,7 +3011,8 @@ async function spectestContext(scope = {}) {
     const execTimeoutMs = scope.service ? COMPONENT_EXEC_DEFAULT_TIMEOUT_MS : undefined;
     return {
         projectRoot: WORKSPACE,
-        readProjectFile: (p) => fs.readFile(path.isAbsolute(p) ? p : path.join(WORKSPACE, p), "utf8"),
+        readProjectFile: (p) => fs.readFile(resolveProjectPath(p), "utf8"),
+        readProjectFileBytes: async (p) => new Uint8Array(await fs.readFile(resolveProjectPath(p))),
         exec: (service, command, opts) => componentExec(service, command, opts, execTimeoutMs),
         // Read `globalThis.fetch` at call time: the wrapper is installed for
         // the duration of a test / eval / project setup, so a context built
@@ -3342,22 +3428,31 @@ async function pollCall(description, fn, opts) {
     let value;
     let success = false;
     let predicateError;
-    // Record all iterations normally. Falsy iterations get truncated
-    // from the recorder so the timeline doesn't fill with polling
-    // noise; the LAST iteration's events stay, then get marked as
-    // children of the wait event so the UI can render them nested.
+    // Record all iterations normally, but keep only the newest one: a new
+    // attempt drops the events the previous attempt emitted, so the timeline
+    // never fills with polling noise. Whichever attempt is last when the loop
+    // ends — the winning one, or the final failed one — stays, and gets marked
+    // as a child of the wait event so the UI can render it nested.
+    //
+    // The failed attempt is kept deliberately. A poll that times out reports
+    // only "timed out after 120000ms (60 attempts)", which says nothing about
+    // WHY: an ingress answering an instant 404 for two minutes and a backend
+    // that never returns look identical in that message. The last attempt's
+    // events carry the status, the body and the duration, which is the whole
+    // difference between "the route was never programmed" and "the app hung".
     const beforePollIdx = recorderEventCount();
     let lastIterStartIdx = beforePollIdx;
-    let keptIterStartIdx = beforePollIdx;
     while (Date.now() - start < timeoutMs) {
         attempts += 1;
+        // Drop the *previous* attempt's events, not this one's — its events are
+        // the ones worth keeping until a newer attempt replaces them.
+        recorderTruncate(lastIterStartIdx);
         lastIterStartIdx = recorderEventCount();
         try {
             const v = await fn();
             if (v !== null && v !== undefined && v !== false) {
                 value = v;
                 success = true;
-                keptIterStartIdx = lastIterStartIdx;
                 break;
             }
         }
@@ -3365,17 +3460,10 @@ async function pollCall(description, fn, opts) {
             predicateError = err;
             break;
         }
-        // Failed iteration — drop the events it emitted.
-        recorderTruncate(lastIterStartIdx);
         if (Date.now() - start + intervalMs > timeoutMs)
             break;
         await new Promise((r) => setTimeout(r, intervalMs));
     }
-    if (!success) {
-        // Timeout or predicate error: drop every attempt's events. The
-        // wait event we emit below is the only trace.
-        recorderTruncate(beforePollIdx);
-    }
     const errMsg = predicateError !== undefined
         ? (predicateError?.message ?? String(predicateError))
         : success
@@ -3388,11 +3476,11 @@ async function pollCall(description, fn, opts) {
         passed: success,
         ...(errMsg !== undefined ? { error: errMsg } : {}),
     }, resv);
-    if (success && seq !== undefined) {
+    if (seq !== undefined) {
         // Group the kept iteration's events under the wait so the UI can
         // render them inside the wait card. The wait event itself is the
         // very last entry; markChildren skips it via the seq match.
-        recorderMarkChildren(keptIterStartIdx, seq);
+        recorderMarkChildren(lastIterStartIdx, seq);
     }
     if (predicateError !== undefined)
         throw predicateError;

package/dist/index.d.ts

@@ -2,12 +2,15 @@ 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, 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";
 export type { Browser, BrowserOptions, Keyboard, Mouse, Touchscreen } from "./browser.js";
 import type { Browser, BrowserOptions } from "./browser.js";
-export type { Locator, GetByRoleOptions, GetByTextOptions, FilterOptions, ClickOptions, BoundingBox, } from "./locator.js";
+export type { Locator, GetByRoleOptions, GetByTextOptions, FilterOptions, ClickOptions, BoundingBox, FilePayload, InputFiles, } from "./locator.js";
 import type { Locator } from "./locator.js";
 export type { UrlPattern } from "./url-match.js";
 import type { UrlPattern } from "./url-match.js";
@@ -215,6 +218,10 @@ export interface SpectestContext<S extends ServicesMap = ServicesMap, F extends
     /** Read a project file as UTF-8. Relative paths resolve against
      *  {@link projectRoot}; absolute paths are read as-is. */
     readProjectFile(path: string): Promise<string>;
+    /** Read a project file as bytes — a fixture to post, hash, or compare
+     *  against what the app under test received. Same path rules as
+     *  {@link readProjectFile}. */
+    readProjectFileBytes(path: string): Promise<Uint8Array>;
     /**
      * Run a command inside a service container. Pass an **array** for exact
      * argv with no shell (`["psql", "-f", "-"]`), or a **string** to run via
@@ -1143,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.
@@ -1184,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. */