@specific.dev/spectest 0.49.0 → 0.51.0

package/dist/annotate.d.ts

@@ -1,4 +1,4 @@
-import { type EmailEventMessage, type EmailEventSummary } from "./recorder.js";
+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`. */
@@ -25,6 +25,9 @@ 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;
@@ -34,7 +37,8 @@ export type AnnotationKind = keyof AnnotationOptions;
  * 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 = {
+export type RenderAnnotation = EmailRenderAnnotation | ChatRenderAnnotation;
+type EmailRenderAnnotation = {
     kind: "email";
     /** Single-message ops. */
     message?: EmailEventMessage;
@@ -43,6 +47,14 @@ export type RenderAnnotation = {
     /** 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.
@@ -64,6 +76,44 @@ export interface EmailAnnotation {
      *  "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

package/dist/annotate.js

@@ -82,6 +82,8 @@ 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.
@@ -129,6 +131,50 @@ function fields(v) {
         ? 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);

package/dist/browser.d.ts

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

package/dist/daemon.js

@@ -45,7 +45,7 @@ import { assertAbsolute, certificateHostnames, defaultKeyMode, expandServiceToke
 import { conflict, notFound, requireString, } from "./harness/methods.js";
 import { openTerminal } from "./terminal.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 { 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";
@@ -829,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
@@ -897,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
@@ -908,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
@@ -2294,20 +2403,39 @@ 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
@@ -2337,6 +2465,19 @@ function recordAnnotationChild(fakeName, member, annotation, durationMs, parentS
                 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) {

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export type { Carrier, Wrapped, WrappedObject, WrappedArray, WrappedResponse, Pr
 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";
+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";

package/dist/index.js

@@ -17,11 +17,12 @@ import { adoptNullishTag, readRaw, readTag } from "./inspect.js";
 // `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", { … })` when its value is an email, and the
-// fake step it records gains a nested `email` event — the same one the
-// built-in `email()` component records — so the step's panel can draw the
-// mail, 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`.
+// `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
@@ -523,6 +524,15 @@ function buildLocatorMatchers(loc, negated, message) {
         const started = Date.now();
         const deadline = started + (timeout ?? DEFAULT_ACTION_TIMEOUT_MS);
         let actual;
+        // Whether this matcher's subject is meant to be on screen, i.e. whether
+        // the step should carry a reveal target for the replay (see
+        // `LocatorProbe.settle`). Only the visibility matchers flip with `negated`
+        // — `not.toHaveText(...)` is still an element the reader should be looking
+        // at — and `toHaveCount(0)` is the third way of saying "expect nothing".
+        const visibility = matcher === "toBeVisible" || matcher === "toBeHidden";
+        const expectsGone = (visibility && (matcher === "toBeHidden") !== negated) ||
+            (matcher === "toHaveCount" && expected === 0);
+        const settleOpts = { reveal: !expectsGone };
         for (;;) {
             let satisfied;
             try {
@@ -540,7 +550,7 @@ function buildLocatorMatchers(loc, negated, message) {
             }
             const passed = satisfied !== negated;
             if (passed) {
-                const sourceSeq = await probe.settle(matcher, Date.now() - started);
+                const sourceSeq = await probe.settle(matcher, Date.now() - started, undefined, settleOpts);
                 recordAssertion({
                     matcher,
                     negated,
@@ -554,7 +564,7 @@ function buildLocatorMatchers(loc, negated, message) {
             }
             if (Date.now() >= deadline) {
                 const msg = describe(actual);
-                const sourceSeq = await probe.settle(matcher, Date.now() - started, msg);
+                const sourceSeq = await probe.settle(matcher, Date.now() - started, msg, settleOpts);
                 recordAssertion({
                     matcher,
                     negated,

package/dist/locator.d.ts

@@ -151,8 +151,16 @@ export interface LocatorProbe {
      *  locator's `expect(...)` matcher assertion nests under, and return its seq
      *  (provenance + replay seek). `action` is the matcher name, `waitedMs` the
      *  poll time, `error` marks the step failed on a timed-out matcher. Returns
-     *  `undefined` when nothing is recording. */
-    settle(action: string, waitedMs: number, error?: string): Promise<number | undefined>;
+     *  `undefined` when nothing is recording.
+     *
+     *  `opts.reveal` additionally stamps the element's rrweb node id for the
+     *  replay viewer (see {@link stampRevealTarget}). The caller decides,
+     *  because only it knows whether the matcher expects the element on screen:
+     *  probing for one a passing `toBeHidden()` says is gone would do nothing
+     *  but wait out the probe's own timeout. */
+    settle(action: string, waitedMs: number, error?: string, opts?: {
+        reveal?: boolean;
+    }): Promise<number | undefined>;
 }
 /** Silent (non-recorded) reads an `expect(browser)` matcher polls — the
  *  session twin of {@link LocatorProbe}. Lives here, next to it, so `index.ts`

package/dist/locator.js

@@ -244,9 +244,22 @@ async function stampActionPoint(loc, rec, position) {
         const pt = await loc.evaluate((el, pos) => {
             if (window.top !== window)
                 return null;
+            // rrweb's id for this element, in the same one round trip. It is what
+            // the replay actually needs: a coordinate is measured against the VM's
+            // layout a moment BEFORE playwright's own actionability wait, so an
+            // element still animating in (or one the dashboard's fonts lay out a
+            // little differently) leaves the recorded point beside the element
+            // rather than on it — measured 27px low on a modal with an entrance
+            // animation. The id lets the viewer place the cursor from the replay's
+            // own layout instead. Stamped even when the point below is not, since
+            // the viewer can scroll an off-screen element into view.
+            const w = window;
+            const getId = w.__spectestRec?.mirror?.getId;
+            const rawId = typeof getId === "function" ? getId.call(w.__spectestRec.mirror, el) : 0;
+            const nodeId = typeof rawId === "number" && rawId > 0 ? rawId : 0;
             const r = el.getBoundingClientRect();
             if (!r.width || !r.height)
-                return null;
+                return nodeId ? { nodeId } : null;
             // Playwright clicks the element's centre unless the caller named a
             // point — which it takes relative to the PADDING box, so an element
             // with a border (a plain `<button>` has 2px of it) sits that far off
@@ -255,17 +268,57 @@ async function stampActionPoint(loc, rec, position) {
             const x = cs ? r.left + parseFloat(cs.borderLeftWidth) + pos.x : r.left + r.width / 2;
             const y = cs ? r.top + parseFloat(cs.borderTopWidth) + pos.y : r.top + r.height / 2;
             const onScreen = x >= 0 && y >= 0 && x <= window.innerWidth && y <= window.innerHeight;
-            return onScreen ? { x, y } : null;
+            return onScreen ? { x, y, nodeId } : { nodeId };
         }, position, { timeout: POINT_PROBE_MS });
-        if (pt) {
+        if (pt && pt.x !== undefined) {
             rec.x = Math.round(pt.x);
             rec.y = Math.round(pt.y);
         }
+        if (pt && pt.nodeId)
+            rec.targetNodeId = pt.nodeId;
     }
     catch {
         /* Element not ready / gone / strict violation — the action reports it. */
     }
 }
+/** Stamp the rrweb node id of the element a settled `expect(locator)` step is
+ *  about, so the dashboard can bring it into the replay's view.
+ *
+ *  Playwright's idea of "visible" is a non-empty box that isn't hidden — it
+ *  says nothing about the viewport, so an element below the fold passes
+ *  `toBeVisible()`. The replay then shows the recorded viewport, which is a
+ *  frame the asserted element isn't in: the reader sees a page that looks
+ *  unrelated to the step. The id is the element's identity in the recording
+ *  (rrweb's own mirror, the same id space its mutation events carry), so the
+ *  viewer can find the node in the replayed DOM and scroll it into view —
+ *  measured against the replay's real layout rather than a rect we recorded
+ *  here, and correct for an element inside a scrollable container too.
+ *
+ *  Best-effort like {@link stampActionPoint}, and only for the top-level
+ *  document: a frame's recorder has its own mirror, whose ids mean nothing in
+ *  the main frame's stream. An unserialized node (`getId` → -1) or no recorder
+ *  leaves the step unstamped, which just means the viewer doesn't scroll. */
+async function stampRevealTarget(loc, rec) {
+    try {
+        const id = await loc.evaluate((el) => {
+            if (window.top !== window)
+                return 0;
+            // The bootstrap stashes rrweb's `record` here; `mirror` is its
+            // node ↔ id map, shared by every snapshot it takes (see browser.ts).
+            const w = window;
+            const getId = w.__spectestRec?.mirror?.getId;
+            if (typeof getId !== "function")
+                return 0;
+            const id = getId.call(w.__spectestRec.mirror, el);
+            return typeof id === "number" && id > 0 ? id : 0;
+        }, undefined, { timeout: POINT_PROBE_MS });
+        if (id)
+            rec.targetNodeId = id;
+    }
+    catch {
+        /* Element gone / not attached / strict violation — no reveal target. */
+    }
+}
 /** Fold a {@link InputFiles} argument into the one playwright takes: repo
  *  paths resolved to their in-VM location (see project-files.ts), built files
  *  given a default mime type and a real `Buffer`. The names come back too —
@@ -320,7 +373,13 @@ export function makeLocator(backend, strategy, chain) {
         count: () => backend.silentRead((page) => lower(page, chain).count()),
         isEnabled: (timeout) => backend.silentRead((page) => lower(page, chain).isEnabled({ timeout })),
         isChecked: (timeout) => backend.silentRead((page) => lower(page, chain).isChecked({ timeout })),
-        settle: (action, waitedMs, error) => backend.recordSettled(action, { selector: label }, waitedMs, error),
+        settle: async (action, waitedMs, error, opts) => {
+            const fields = { selector: label };
+            if (opts && opts.reveal) {
+                await backend.silentRead((page) => stampRevealTarget(lower(page, chain), fields));
+            }
+            return backend.recordSettled(action, fields, waitedMs, error);
+        },
     };
     const loc = {
         [LOCATOR_BRAND]: true,

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 —
@@ -418,6 +418,15 @@ export interface BrowserEvent extends BaseEvent {
     dy?: number;
     x?: number;
     y?: number;
+    /**
+     * rrweb node id of the element a settled `expect(locator)` step asserted on
+     * — the element's identity in this session's recording. Playwright calls an
+     * element below the fold visible, so the frame the step seeks to need not
+     * contain it; with this the viewer finds the node in the replayed DOM and
+     * scrolls it into view. Absent when the SDK couldn't measure it (an element
+     * in a frame, one rrweb hasn't serialized, a matcher whose subject is gone).
+     */
+    targetNodeId?: number;
     /** Screenshot image format. */
     format?: string;
     /** For `waitFor`: how many times the predicate was polled. */
@@ -557,6 +566,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