@specific.dev/spectest 0.50.0 → 0.52.0

package/dist/browser.d.ts

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

package/dist/daemon.js

@@ -46,7 +46,7 @@ import { conflict, notFound, requireString, } from "./harness/methods.js";
 import { openTerminal } from "./terminal.js";
 import { readAnnotation } from "./annotate.js";
 import { pauseRecording, recordEmail, recordEnv, recordExec, recordFake, recordHttp, recordStep, recordTerminal, recordWait, reserveEvent, recorderEventCount, recorderMarkChildren, recorderTruncate, resumeRecording, startRecording, stopRecording, truncateUtf8, } from "./recorder.js";
-import { deepUnwrap, wrap, wrapResponse } from "./inspect.js";
+import { deepUnwrap, readRaw, wrap, wrapResponse } from "./inspect.js";
 import { clearRecordSecrets, setRecordSecrets } from "./record-secrets.js";
 import { encodeReplayBundle, replayChunk } from "./replay-bundle.js";
 function namedServices(cfg) {
@@ -3074,17 +3074,41 @@ const TEST_DATA = new Map();
  *  test timeout instead, and a project `setup` — which routinely waits on
  *  rollouts — stays unbounded, so neither gets a default. */
 const COMPONENT_EXEC_DEFAULT_TIMEOUT_MS = 120_000;
-/** Raw `docker exec` with optional piped stdin. Array command = exact
- * argv (no shell); string = `sh -lc`. Non-zero exit is reported via
- * `exitCode`, never thrown. Unlike the test-context `exec` this records
- * nothing — setup/helpers-factory time has no test timeline. */
+/** The running test case's recording `exec`, installed by `runOne`
+ *  for the length of the case and cleared again in its `finally`. It is
+ *  read at *call* time, which is the whole point: a component's context —
+ *  a `helpers` factory's, a service `setup` hook's — is built once during
+ *  bootstrap and cached, so the `exec` those hooks destructure can never
+ *  be the test's own. Without this, everything a service helper did was
+ *  invisible: `ctx.svc.<name>.<helper>()` shelling into a container
+ *  recorded no step, and a helper called inside a `ctx.poll` predicate
+ *  left the wait with nothing to render inside it (the poll keeps the
+ *  events of its last attempt — there were none). Undefined outside a
+ *  test, so bootstrap and project setup stay uninstrumented. */
+let RECORDING_EXEC;
+/** `docker exec` with optional piped stdin. Array command = exact argv
+ * (no shell); string = `sh -lc`. Non-zero exit is reported via
+ * `exitCode`, never thrown.
+ *
+ * Records a step when a test is running (through `RECORDING_EXEC`, which
+ * also captures the asciicast), and nothing at bootstrap. Either way the
+ * caller gets the PLAIN `ExecResult`, never the test context's
+ * provenance-wrapped one: component code is ordinary code written against
+ * the declared type, and a wrapper is an object — `res.exitCode !== 0`
+ * would be true for every exit code, and a client branching on `typeof`
+ * would take the wrong arm. Provenance has nothing to point at here
+ * anyway, since the helper's return value is not what the step recorded. */
 function componentExec(service, command, opts, defaultTimeoutMs) {
     assertKnownOpts("ctx.exec", opts, EXEC_OPT_KEYS);
     const timeoutMs = opts?.timeoutMs ?? defaultTimeoutMs;
-    return execInService(service, command, {
+    const merged = {
         ...opts,
         ...(timeoutMs !== undefined ? { timeoutMs } : {}),
-    });
+    };
+    const recording = RECORDING_EXEC;
+    if (recording)
+        return recording(service, command, merged).then(readRaw);
+    return execInService(service, command, merged);
 }
 /** Transitive `dependsOn` closure of a service, by name. */
 function transitiveDeps(service) {
@@ -3918,6 +3942,12 @@ async function runOne(testCase) {
         testName: testCase.name,
         parent,
     };
+    // Let a component's `exec` record for the length of this case. The
+    // context a `helpers` factory or a service `setup` hook holds was built
+    // at bootstrap and carries `componentExec`, which reads this at call
+    // time — so from here on a service helper's `docker exec` lands on the
+    // timeline (and in the cast) exactly like the test's own `ctx.exec`.
+    RECORDING_EXEC = recordedExec;
     const timeoutMs = testCase.timeoutMs ?? DEFAULT_TEST_TIMEOUT_MS;
     let timer;
     const timedOut = new Promise((_, reject) => {
@@ -3946,6 +3976,7 @@ async function runOne(testCase) {
     finally {
         if (timer)
             clearTimeout(timer);
+        RECORDING_EXEC = undefined;
         restoreFetch();
         restoreConsole();
         // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/dist/index.js

@@ -524,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 {
@@ -541,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,
@@ -555,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

@@ -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. */

package/package.json

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

package/src/browser.ts

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

package/src/daemon.ts

@@ -134,7 +134,7 @@ import {
   type TestEvent,
   type OmittedBody,
 } from "./recorder.js";
-import { deepUnwrap, wrap, wrapResponse } from "./inspect.js";
+import { deepUnwrap, readRaw, wrap, wrapResponse } from "./inspect.js";
 import type { Wrapped, WrappedResponse } from "./inspect.js";
 import { clearRecordSecrets, setRecordSecrets } from "./record-secrets.js";
 import { encodeReplayBundle, replayChunk } from "./replay-bundle.js";
@@ -3773,10 +3773,37 @@ const TEST_DATA = new Map<string, unknown>();
  *  rollouts — stays unbounded, so neither gets a default. */
 const COMPONENT_EXEC_DEFAULT_TIMEOUT_MS = 120_000;
 
-/** Raw `docker exec` with optional piped stdin. Array command = exact
- * argv (no shell); string = `sh -lc`. Non-zero exit is reported via
- * `exitCode`, never thrown. Unlike the test-context `exec` this records
- * nothing — setup/helpers-factory time has no test timeline. */
+/** The running test case's recording `exec`, installed by `runOne`
+ *  for the length of the case and cleared again in its `finally`. It is
+ *  read at *call* time, which is the whole point: a component's context —
+ *  a `helpers` factory's, a service `setup` hook's — is built once during
+ *  bootstrap and cached, so the `exec` those hooks destructure can never
+ *  be the test's own. Without this, everything a service helper did was
+ *  invisible: `ctx.svc.<name>.<helper>()` shelling into a container
+ *  recorded no step, and a helper called inside a `ctx.poll` predicate
+ *  left the wait with nothing to render inside it (the poll keeps the
+ *  events of its last attempt — there were none). Undefined outside a
+ *  test, so bootstrap and project setup stay uninstrumented. */
+let RECORDING_EXEC:
+  | ((
+      service: string,
+      command: string | string[],
+      opts?: ExecOpts,
+    ) => Promise<ExecResult>)
+  | undefined;
+
+/** `docker exec` with optional piped stdin. Array command = exact argv
+ * (no shell); string = `sh -lc`. Non-zero exit is reported via
+ * `exitCode`, never thrown.
+ *
+ * Records a step when a test is running (through `RECORDING_EXEC`, which
+ * also captures the asciicast), and nothing at bootstrap. Either way the
+ * caller gets the PLAIN `ExecResult`, never the test context's
+ * provenance-wrapped one: component code is ordinary code written against
+ * the declared type, and a wrapper is an object — `res.exitCode !== 0`
+ * would be true for every exit code, and a client branching on `typeof`
+ * would take the wrong arm. Provenance has nothing to point at here
+ * anyway, since the helper's return value is not what the step recorded. */
 function componentExec(
   service: string,
   command: string | string[],
@@ -3785,10 +3812,13 @@ function componentExec(
 ): Promise<ExecResult> {
   assertKnownOpts("ctx.exec", opts, EXEC_OPT_KEYS);
   const timeoutMs = opts?.timeoutMs ?? defaultTimeoutMs;
-  return execInService(service, command, {
+  const merged = {
     ...opts,
     ...(timeoutMs !== undefined ? { timeoutMs } : {}),
-  });
+  };
+  const recording = RECORDING_EXEC;
+  if (recording) return recording(service, command, merged).then(readRaw);
+  return execInService(service, command, merged);
 }
 
 // ────────────────────────────────────────────────────────────────────────
@@ -4796,6 +4826,13 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
     parent,
   };
 
+  // Let a component's `exec` record for the length of this case. The
+  // context a `helpers` factory or a service `setup` hook holds was built
+  // at bootstrap and carries `componentExec`, which reads this at call
+  // time — so from here on a service helper's `docker exec` lands on the
+  // timeline (and in the cast) exactly like the test's own `ctx.exec`.
+  RECORDING_EXEC = recordedExec;
+
   const timeoutMs = testCase.timeoutMs ?? DEFAULT_TEST_TIMEOUT_MS;
   let timer: NodeJS.Timeout | undefined;
   const timedOut = new Promise<never>((_, reject) => {
@@ -4825,6 +4862,7 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
     };
   } finally {
     if (timer) clearTimeout(timer);
+    RECORDING_EXEC = undefined;
     restoreFetch();
     restoreConsole();
     // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/src/index.ts

@@ -2328,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 {
@@ -2344,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,
@@ -2358,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 = {

package/src/recorder.ts

@@ -473,6 +473,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. */