@specific.dev/spectest 0.49.0 → 0.51.0

package/dist/recorder.js

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

package/package.json

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

package/src/annotate.ts

@@ -33,8 +33,10 @@
 import { deepUnwrap } from "./inspect.js";
 import {
   truncateUtf8,
+  type ChatBlockMessage,
   type EmailEventMessage,
   type EmailEventSummary,
+  type StepBlock,
 } from "./recorder.js";
 
 /**
@@ -74,6 +76,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. */
@@ -85,7 +90,9 @@ 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;
@@ -95,6 +102,15 @@ export type RenderAnnotation = {
   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.
@@ -117,6 +133,46 @@ export interface EmailAnnotation {
   text?: string;
 }
 
+/**
+ * A conversation to draw as chat bubbles.
+ *
+ * Two sides and their text, which is all a transcript needs to read as one.
+ * It is drawn from the end user's point of view — their own messages on the
+ * right, the other party's on the left.
+ * Pass the messages alone (`annotate(v, "chat", messages)`), or this object
+ * when the thread has an identity worth showing. With no options at all the
+ * value itself is read as the message list.
+ */
+export interface ChatAnnotation {
+  messages: readonly ChatMessageAnnotation[];
+  /**
+   * The thread's identity — a phone number, a channel, whoever is on the
+   * other end — shown as a header over the bubbles. Optional: a fake with
+   * one conversation has nothing useful to put here, and the transcript
+   * reads fine without it.
+   */
+  title?: string;
+}
+
+/** One turn of a {@link ChatAnnotation}. */
+export interface ChatMessageAnnotation {
+  /**
+   * Who sent it. A transcript is drawn the way the **end user** would see
+   * it on their own screen, so `self` is the end user's own messages — the
+   * person using the app under test — and sits on the right; `other` is
+   * whoever they are talking to and sits on the left.
+   */
+  side: "self" | "other";
+  text: string;
+  /**
+   * This message arrived in *this* call: it slides in when the step opens,
+   * and again whenever it is reopened. Only the fake knows which turns are new —
+   * the dashboard sees one call, not the conversation's history — so it is
+   * the fake that marks them.
+   */
+  new?: boolean;
+}
+
 /** Listing rows carried on the event. The returned value is never capped. */
 const LIST_CAP = 50;
 
@@ -173,6 +229,8 @@ function lower<K extends AnnotationKind>(
   switch (kind) {
     case "email":
       return lowerEmail(options as AnnotationOptions["email"] | undefined, value);
+    case "chat":
+      return lowerChat(options as AnnotationOptions["chat"] | undefined, value);
     default:
       // Unreachable while `kind` is a key of AnnotationOptions; a kind added
       // to that interface without a case here lands on this line.
@@ -230,6 +288,51 @@ function fields(v: unknown): Record<string, unknown> {
     : {};
 }
 
+const NO_MESSAGES =
+  'annotate(value, "chat"): nothing to render — no messages found on the ' +
+  "value. Pass them explicitly, e.g. " +
+  'annotate(value, "chat", value.turns.map((t) => ({ side: t.fromCustomer ? "self" : "other", text: t.body }))).';
+
+function lowerChat(
+  options: AnnotationOptions["chat"] | undefined,
+  value: unknown,
+): RenderAnnotation {
+  const source: unknown = deepUnwrap(options ?? value);
+  let list: unknown;
+  let title: string | undefined;
+  if (Array.isArray(source)) {
+    list = source;
+  } else {
+    const bag = fields(source);
+    list = bag.messages;
+    title = text(bag.title) || undefined;
+  }
+  // An empty conversation is a real state (nothing said yet) and renders as
+  // one; a value with no `messages` at all is the author's mistake.
+  if (!Array.isArray(list)) throw new Error(NO_MESSAGES);
+  const messages = list.map((m) => chatMessageOf(fields(m)));
+  // The title travels twice on purpose: as the step's own summary, and as
+  // the transcript's header — the annotated view renders the blocks alone,
+  // so a title carried only on the step would never be seen.
+  return {
+    kind: "chat",
+    title,
+    blocks: [{ type: "chat", messages, ...(title ? { label: title } : {}) }],
+  };
+}
+
+function chatMessageOf(src: Record<string, unknown>): ChatBlockMessage {
+  const msg: ChatBlockMessage = {};
+  // Anything that isn't the end user's own message is drawn as the other
+  // party's, rather than a turn being dropped for a typo.
+  if (text(src.side) === "self") msg.side = "self";
+  else msg.side = "other";
+  const body = text(src.text);
+  if (body) msg.text = truncateUtf8(body).value;
+  if (src.new === true) msg.new = true;
+  return msg;
+}
+
 function messageOf(src: Record<string, unknown>): EmailEventMessage {
   const msg: EmailEventMessage = {};
   const from = text(src.from);

package/src/browser.ts

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

package/src/daemon.ts

@@ -114,17 +114,20 @@ import type { Mobile, MobileApp } from "./mobile.js";
 import { openTerminal } from "./terminal.js";
 import { readAnnotation, type RenderAnnotation } from "./annotate.js";
 import {
+  pauseRecording,
   recordEmail,
   recordEnv,
   recordExec,
   recordFake,
   recordHttp,
+  recordStep,
   recordTerminal,
   recordWait,
   reserveEvent,
   recorderEventCount,
   recorderMarkChildren,
   recorderTruncate,
+  resumeRecording,
   startRecording,
   stopRecording,
   truncateUtf8,
@@ -1113,17 +1116,141 @@ async function prepareServiceImage(
   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(): Promise<string | null> {
+  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: string,
   image: { content: string; exclude?: readonly string[] },
   tag: string,
 ): Promise<{ tag: string; buildSteps?: BuildStep[] }> {
+  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: string): Promise<boolean> {
+  const user = (
+    await docker(["image", "inspect", "--format", "{{.Config.User}}", tag], 60_000)
+  ).stdout.trim();
+  return user === "" || user === "root" || user === "0";
+}
+
+async function runServiceBuild(
+  name: string,
+  image: { content: string; exclude?: readonly string[] },
+  tag: string,
+  caSuffix: string | null,
+): Promise<{ ok: boolean; folded: boolean; log: string; buildSteps?: BuildStep[] }> {
   let buildSteps: BuildStep[] | undefined;
   {
+    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
@@ -1183,11 +1310,11 @@ async function buildServiceImage(
         });
       }
     });
+    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
@@ -1196,14 +1323,8 @@ async function buildServiceImage(
         .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 };
 }
 
 /**
@@ -2762,19 +2883,41 @@ function invokeFakeHelper(
     }, 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: unknown;
   try {
     result = fn.apply(thisArg, args);
   } catch (err) {
+    resumeRecording();
     recordError(err);
     throw err;
   }
   if (result instanceof Promise) {
-    return result.then(recordResult, (err) => {
-      recordError(err);
-      throw err;
-    });
+    return result.then(
+      (value) => {
+        resumeRecording();
+        return recordResult(value);
+      },
+      (err) => {
+        resumeRecording();
+        recordError(err);
+        throw err;
+      },
+    );
   }
+  resumeRecording();
   return recordResult(result);
 }
 
@@ -2811,6 +2954,19 @@ function recordAnnotationChild(
         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;
   }
 }
 

package/src/index.ts

@@ -35,16 +35,19 @@ import type { OpTag, Provenanced, SpectestFetch, Wrapped } from "./inspect.js";
 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";
 export type {
   Annotated,
   AnnotationKind,
   AnnotationOptions,
+  ChatAnnotation,
+  ChatMessageAnnotation,
   EmailAnnotation,
 } from "./annotate.js";
 import type { Annotated } from "./annotate.js";
@@ -2325,6 +2328,16 @@ function buildLocatorMatchers(
     const started = Date.now();
     const deadline = started + (timeout ?? DEFAULT_ACTION_TIMEOUT_MS);
     let actual: unknown;
+    // 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: boolean;
       try {
@@ -2341,7 +2354,7 @@ function buildLocatorMatchers(
       }
       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,
@@ -2355,7 +2368,7 @@ function buildLocatorMatchers(
       }
       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/src/locator.ts

@@ -322,8 +322,19 @@ 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
@@ -446,8 +457,23 @@ async function stampActionPoint(
     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 as unknown as {
+          __spectestRec?: { mirror?: { getId?: (n: Node) => number } };
+        };
+        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;
+        if (!r.width || !r.height) 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
@@ -457,20 +483,65 @@ async function stampActionPoint(
         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);
+      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: PWLocator,
+  rec: Partial<RecordableFields>,
+): Promise<void> {
+  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 as unknown as {
+          __spectestRec?: { mirror?: { getId?: (n: Node) => number } };
+        };
+        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 —
@@ -671,8 +742,13 @@ export function makeLocator(
     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: Partial<RecordableFields> = { selector: label };
+      if (opts && opts.reveal) {
+        await backend.silentRead((page) => stampRevealTarget(lower(page, chain), fields));
+      }
+      return backend.recordSettled(action, fields, waitedMs, error);
+    },
   };
 
   const loc: InternalLocator = {