@piwitests/reporter 0.47.0 → 0.49.0

package/dist/index.js

@@ -56,9 +56,9 @@ function defaultDesktopConfigPath() {
 }
 function readDesktopConfig(filePath) {
   try {
-    const parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
-    const url = parsed?.url;
-    const token = parsed?.token;
+    const parsed2 = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    const url = parsed2?.url;
+    const token = parsed2?.token;
     if (typeof url !== "string" || !url) return null;
     if (typeof token !== "string" || !token) return null;
     return { url, token };
@@ -91,7 +91,7 @@ var DEFAULTS = {
   defaultCapture: true,
   checkBaseUrl: false,
   streaming: true,
-  streamingBatchSize: 5,
+  streamingBatchSize: 20,
   streamingBatchDelay: 2e3,
   maxStreamBufferBytes: 100 * 1024 * 1024,
   submitTimeout: 15 * 60 * 1e3,
@@ -145,6 +145,10 @@ var PIWI_ENV_KEYS = {
   aiResponseWaitTimeout: "PIWI_AI_RESPONSE_WAIT_TIMEOUT",
   aiScreenshotFallback: "PIWI_AI_SCREENSHOT_FALLBACK"
 };
+var PIWI_LOCAL_DEBUG_ENV = {
+  pauseAt: "PIWI_PAUSE_AT",
+  editorSend: "PIWI_EDITOR_SEND"
+};
 var PIWI_DESKTOP_CONFIG_ENV = "PIWI_DESKTOP_CONFIG";
 var PIWI_DEFAULTED_CAPTURE_ENV = "PIWI_DEFAULTED_CAPTURE";
 var PIWI_SELECTION_ENV = {
@@ -320,8 +324,8 @@ var Logger = class {
 // src/internal/transport/http-client.ts
 function parseErrorMessage(text) {
   try {
-    const parsed = JSON.parse(text);
-    const message = parsed?.message;
+    const parsed2 = JSON.parse(text);
+    const message = parsed2?.message;
     return typeof message === "string" ? message : void 0;
   } catch {
     return void 0;
@@ -1865,6 +1869,20 @@ var StreamManager = class {
     this.heartbeatStopped = false;
     this.lastActivityAt = 0;
     this.heartbeatInterval = 15e3;
+    /**
+     * The heartbeat interval while nobody watches the run: during a long test no
+     * other request goes out, so the heartbeat's answer is how the reporter learns
+     * that someone opened the run.
+     */
+    this.unwatchedHeartbeatInterval = 5e3;
+    /**
+     * Whether anyone has the run open live on the dashboard, from the `watched`
+     * flag of the last answer to an events or heartbeat request; `null` until the
+     * dashboard says, and for a dashboard that does not. Step events are live
+     * progress only (each `complete` event carries its test's steps), so none are
+     * queued while it is `false`.
+     */
+    this.watched = null;
     /** Tracks cases whose files have already been uploaded live, so `uploadRemaining` can skip them. */
     this.uploadedCaseFiles = /* @__PURE__ */ new WeakSet();
     /** Set when a test-result event left the live stream undelivered: too large to send, or still queued when the drain gave up. */
@@ -2035,8 +2053,13 @@ var StreamManager = class {
       this.pendingBeginEvents.enqueue(event);
     }
   }
-  /** Queue a test-case event. Triggers an immediate flush when the batch size is reached, otherwise schedules a timer-based flush. */
+  /**
+   * Queue a test-case event. Triggers an immediate flush when the batch size is
+   * reached, otherwise schedules a timer-based flush. A step event is dropped
+   * while nobody watches the run.
+   */
   queueEvent(event) {
+    if (this.watched === false && (event.type === "step-begin" || event.type === "step-end")) return;
     this.pendingEvents.enqueue(event);
     if (this.pendingEvents.length >= this.options.streamingBatchSize) {
       this.flush();
@@ -2064,11 +2087,12 @@ var StreamManager = class {
     while (chunks.length > 0) {
       const chunk = chunks.shift();
       try {
-        await this.httpClient.postJSON(
+        const response = await this.httpClient.postJSON(
           `/api/test-runs/${this._runId}/events`,
           { streamToken: this._token, testCases: chunk },
           this._auth
         );
+        this.noteWatched(response);
         this.retryCount = 0;
         this.lastActivityAt = Date.now();
       } catch (error) {
@@ -2142,13 +2166,29 @@ var StreamManager = class {
       if (this.pendingEvents.length > 0) this.flush();
     }, delay);
   }
+  // Take the dashboard's answer on whether anyone watches the run. An answer
+  // without the flag (an older dashboard) keeps step events flowing.
+  noteWatched(response) {
+    const watched = response?.watched;
+    const next = typeof watched === "boolean" ? watched : null;
+    if (next !== null && next !== this.watched) {
+      this.logger.debug(
+        next ? "The run is open on the dashboard: streaming live steps." : "Nobody is watching the run: live steps are not sent."
+      );
+    }
+    this.watched = next;
+  }
+  // Idle time after which a heartbeat goes out.
+  heartbeatDelay() {
+    return this.watched === false ? this.unwatchedHeartbeatInterval : this.heartbeatInterval;
+  }
   // Schedule the next idle heartbeat. Self-rescheduling; cleared by stopHeartbeat.
   scheduleHeartbeat() {
     if (this.heartbeatStopped || this.heartbeatTimer) return;
     this.heartbeatTimer = setTimeout(() => {
       this.heartbeatTimer = null;
       void this.sendHeartbeat();
-    }, this.heartbeatInterval);
+    }, this.heartbeatDelay());
   }
   // Ping the server only when the run has actually been idle. Real event traffic
   // already bumps the server's activity timestamp, so a recent flush (or pending
@@ -2156,16 +2196,17 @@ var StreamManager = class {
   async sendHeartbeat() {
     if (this.heartbeatStopped || !this._enabled || !this._runId || !this._token) return;
     const idleFor = Date.now() - this.lastActivityAt;
-    if (idleFor < this.heartbeatInterval || this.pendingEvents.length > 0) {
+    if (idleFor < this.heartbeatDelay() || this.pendingEvents.length > 0) {
       this.scheduleHeartbeat();
       return;
     }
     try {
-      await this.httpClient.postJSON(
+      const response = await this.httpClient.postJSON(
         `/api/test-runs/${this._runId}/heartbeat`,
         { streamToken: this._token },
         this._auth
       );
+      this.noteWatched(response);
       this.lastActivityAt = Date.now();
     } catch (error) {
       this.logger.debug(`Heartbeat failed: ${errorMessage(error)}`);
@@ -3743,9 +3784,9 @@ function loadAriaSampleSet(projectName) {
   let set = null;
   try {
     const raw = fs11.readFileSync(getAriaSampleFilePath(projectName), "utf8");
-    const parsed = JSON.parse(raw);
-    if (parsed.projectName === projectName && Array.isArray(parsed.identities)) {
-      set = new Set(parsed.identities.filter((x) => typeof x === "string"));
+    const parsed2 = JSON.parse(raw);
+    if (parsed2.projectName === projectName && Array.isArray(parsed2.identities)) {
+      set = new Set(parsed2.identities.filter((x) => typeof x === "string"));
     }
   } catch {
     set = null;
@@ -3896,14 +3937,14 @@ var COMMITTED_MANIFEST_FILE = "piwi.manifest.json";
 var INSTRUMENTATION_MANIFEST_PATH = "/__piwi/manifest";
 var INSTRUMENTATION_HEADERS = ["x-piwi-logs", "x-piwi-trace"];
 function parseManifestJson(text) {
-  let parsed;
+  let parsed2;
   try {
-    parsed = JSON.parse(text);
+    parsed2 = JSON.parse(text);
   } catch {
     return null;
   }
-  if (!parsed || typeof parsed !== "object") return null;
-  const obj = parsed;
+  if (!parsed2 || typeof parsed2 !== "object") return null;
+  const obj = parsed2;
   const routes = Array.isArray(obj.routes) ? obj.routes.filter((r) => !!r && typeof r === "object").filter((r) => typeof r.method === "string" && typeof r.pattern === "string").map((r) => ({
     method: r.method,
     pattern: r.pattern,
@@ -4107,8 +4148,8 @@ function parseRouteKey(routeKey2) {
   return { method: routeKey2.slice(0, space).toUpperCase(), pattern: routeKey2.slice(space + 1) };
 }
 function patternToRegex(pattern) {
-  const path31 = pattern.split("?")[0] ?? pattern;
-  const escaped = path31.replace(/[.*+?^${}()|[\]\\]/g, "\\$&").replace(/:[A-Za-z0-9_]+/g, "[^/]+");
+  const path32 = pattern.split("?")[0] ?? pattern;
+  const escaped = path32.replace(/[.*+?^${}()|[\]\\]/g, "\\$&").replace(/:[A-Za-z0-9_]+/g, "[^/]+");
   return new RegExp(`^${escaped}$`);
 }
 function suitePathEqual(a, b) {
@@ -4131,13 +4172,13 @@ function matchProbeItem(plan, test) {
 function requestMatchesRoute(method, url, routeKey2) {
   const { method: rm, pattern } = parseRouteKey(routeKey2);
   if (rm && rm !== method.toUpperCase()) return false;
-  let path31;
+  let path32;
   try {
-    path31 = new URL(url).pathname;
+    path32 = new URL(url).pathname;
   } catch {
-    path31 = url.split("?")[0] ?? url;
+    path32 = url.split("?")[0] ?? url;
   }
-  return patternToRegex(pattern).test(path31);
+  return patternToRegex(pattern).test(path32);
 }
 function createProbeState() {
   return { navigated: false, matches: 0 };
@@ -4159,10 +4200,10 @@ function isProbeMode() {
 function loadPlan() {
   if (planCache !== void 0) return planCache;
   planCache = null;
-  const path31 = process.env[PIWI_PROBE_ENV.plan];
-  if (path31) {
+  const path32 = process.env[PIWI_PROBE_ENV.plan];
+  if (path32) {
     try {
-      planCache = JSON.parse(fs14.readFileSync(path31, "utf8"));
+      planCache = JSON.parse(fs14.readFileSync(path32, "utf8"));
     } catch {
       planCache = null;
     }
@@ -4184,10 +4225,10 @@ function outcomeFromStatus(status, applied) {
   return status === "failed" || status === "timedOut" || status === "interrupted" ? "noticed" : "not-noticed";
 }
 function recordProbeOutcome(line) {
-  const path31 = process.env[PIWI_PROBE_ENV.results];
-  if (!path31) return;
+  const path32 = process.env[PIWI_PROBE_ENV.results];
+  if (!path32) return;
   try {
-    fs14.appendFileSync(path31, `${JSON.stringify(line)}
+    fs14.appendFileSync(path32, `${JSON.stringify(line)}
 `);
   } catch {
   }
@@ -4410,8 +4451,8 @@ var FLAKE_LAB_RUN_METADATA_KEY = "piwiFlakeLab";
 // ../core/src/page-key.ts
 function normalizeRoute(url) {
   try {
-    const parsed = new URL(url);
-    let pathname = parsed.pathname;
+    const parsed2 = new URL(url);
+    let pathname = parsed2.pathname;
     pathname = pathname.replace(/\/eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+(?=\/|$)/g, "/:jwt");
     pathname = pathname.replace(/\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}(?=\/|$)/gi, "/:uuid");
     pathname = pathname.replace(/\/[0-9ABCDEFGHJKMNPQRSTVWXYZ]{26}(?=\/|$)/gi, "/:ulid");
@@ -4419,8 +4460,8 @@ function normalizeRoute(url) {
     pathname = pathname.replace(/\/[0-9a-f]{32,}(?=\/|$)/gi, "/:token");
     pathname = pathname.replace(/\/\d+(?=\/|$)/g, "/:id");
     let queryString = "";
-    if (parsed.search) {
-      const params = new URLSearchParams(parsed.search);
+    if (parsed2.search) {
+      const params = new URLSearchParams(parsed2.search);
       const redacted = new URLSearchParams();
       for (const [key] of params) {
         redacted.set(key, "<redacted>");
@@ -4472,24 +4513,24 @@ function faultRouteAction(fault) {
   return fault === "slow" ? { kind: "delay", ms: SLOW_FAULT_DELAY_MS } : null;
 }
 function dropOneField(body) {
-  let parsed;
+  let parsed2;
   try {
-    parsed = JSON.parse(body);
+    parsed2 = JSON.parse(body);
   } catch {
     return body;
   }
-  if (Array.isArray(parsed)) {
+  if (Array.isArray(parsed2)) {
     let key;
-    for (const el of parsed) {
+    for (const el of parsed2) {
       if (el && typeof el === "object" && !Array.isArray(el)) {
         key ??= Object.keys(el)[0];
         if (key) delete el[key];
       }
     }
-    return JSON.stringify(parsed);
+    return JSON.stringify(parsed2);
   }
-  if (parsed && typeof parsed === "object") {
-    const obj = parsed;
+  if (parsed2 && typeof parsed2 === "object") {
+    const obj = parsed2;
     const key = Object.keys(obj)[0];
     if (key) delete obj[key];
     return JSON.stringify(obj);
@@ -5297,8 +5338,8 @@ function ciBuildUrlFromMetadata(metadata) {
 
 // src/internal/submit/run-submitter.ts
 var MAX_TIMER_DELAY_MS = 2 ** 31 - 1;
-function markSubmitFallback(run, path31, reason) {
-  run.metadata.ingestHealth = { submitFallback: { path: path31, reason } };
+function markSubmitFallback(run, path32, reason) {
+  run.metadata.ingestHealth = { submitFallback: { path: path32, reason } };
 }
 var RunSubmitter = class {
   /**
@@ -7858,7 +7899,7 @@ function resourceTimeline(samples, censuses) {
   let startedAt = hasSamples ? samples.startedAt : Infinity;
   for (const { events } of workers) startedAt = Math.min(startedAt, events[0][0]);
   const shift = hasSamples ? samples.startedAt - startedAt : 0;
-  const relative13 = (points, by) => points.map(([at, value]) => [Math.round(at + by), value]);
+  const relative14 = (points, by) => points.map(([at, value]) => [Math.round(at + by), value]);
   const trees = hasSamples ? workerTreesByIndex(samples, censuses) : [];
   const perWorker = Math.max(
     60,
@@ -7866,17 +7907,17 @@ function resourceTimeline(samples, censuses) {
   );
   return {
     startedAt,
-    cpuPct: hasSamples ? downsamplePoints(relative13(samples.cpuPct, shift), TIMELINE_SERIES_CAP, "mean") : [],
-    memoryBytes: hasSamples ? downsamplePoints(relative13(samples.memoryBytes, shift), TIMELINE_SERIES_CAP, "max") : [],
+    cpuPct: hasSamples ? downsamplePoints(relative14(samples.cpuPct, shift), TIMELINE_SERIES_CAP, "mean") : [],
+    memoryBytes: hasSamples ? downsamplePoints(relative14(samples.memoryBytes, shift), TIMELINE_SERIES_CAP, "max") : [],
     pages: workers.map(({ worker, events }) => {
-      const points = relative13(events, -startedAt);
+      const points = relative14(events, -startedAt);
       const last = points.pop();
       return { worker, points: [...downsamplePoints(points, TIMELINE_WORKER_POINTS_CAP - 1, "max"), last] };
     }),
     workers: trees.map((tree) => ({
       worker: tree.worker,
-      cpuCores: downsamplePoints(relative13(tree.cpuCores, shift), perWorker, "mean"),
-      memoryBytes: downsamplePoints(relative13(tree.memoryBytes, shift), perWorker, "max")
+      cpuCores: downsamplePoints(relative14(tree.cpuCores, shift), perWorker, "mean"),
+      memoryBytes: downsamplePoints(relative14(tree.memoryBytes, shift), perWorker, "max")
     }))
   };
 }
@@ -8039,8 +8080,8 @@ function formatTimeout(ms) {
 }
 function routeOf(url) {
   try {
-    const parsed = new URL(url);
-    return `${parsed.pathname}${parsed.search}` || "/";
+    const parsed2 = new URL(url);
+    return `${parsed2.pathname}${parsed2.search}` || "/";
   } catch {
     return url;
   }
@@ -8060,14 +8101,14 @@ function textOfGetByText(locator) {
   const m = /^getByText\(\s*(['"`])((?:\\.|(?!\1)[^\\\n\r\u2028\u2029])*)\1\s*(?:,\s*\{[^}]*\})?\s*\)$/.exec(locator);
   return m ? m[2] : null;
 }
-function receivedDisplay(parsed) {
-  const received = parsed.received ?? "";
-  if (parsed.assertion !== "toHaveURL") return received;
+function receivedDisplay(parsed2) {
+  const received = parsed2.received ?? "";
+  if (parsed2.assertion !== "toHaveURL") return received;
   const m = /^"?(https?:\/\/[^"\s]+)"?$/.exec(received);
   return m ? `"${routeOf(m[1])}"` : received;
 }
-function firstLineFallback(parsed) {
-  const line = (parsed.messageHead.split("\n")[0] ?? "").replace(/^Error:\s*/, "").replace(MASK_TOKEN_RE, "\u2026");
+function firstLineFallback(parsed2) {
+  const line = (parsed2.messageHead.split("\n")[0] ?? "").replace(/^Error:\s*/, "").replace(MASK_TOKEN_RE, "\u2026");
   return truncateValue(line || "Unknown error", HEADLINE_MAX_CHARS);
 }
 var Line = class {
@@ -8104,148 +8145,148 @@ function timeoutSuffix(timeoutMs) {
 function timeoutParen(timeoutMs) {
   return timeoutMs !== null ? ` (${formatTimeout(timeoutMs)})` : "";
 }
-function buildActionTimeout(parsed, opts) {
+function buildActionTimeout(parsed2, opts) {
   const line = new Line();
-  const verb = ACTION_VERBS[parsed.action ?? ""] ?? parsed.action ?? "action";
-  const state = STATE_PHRASES[parsed.lastState];
-  if (parsed.locator && state) {
-    return subject(line, parsed.locator, opts).text(` ${state} \u2014 ${verb} timed out`).text(timeoutSuffix(parsed.timeoutMs));
+  const verb = ACTION_VERBS[parsed2.action ?? ""] ?? parsed2.action ?? "action";
+  const state = STATE_PHRASES[parsed2.lastState];
+  if (parsed2.locator && state) {
+    return subject(line, parsed2.locator, opts).text(` ${state} \u2014 ${verb} timed out`).text(timeoutSuffix(parsed2.timeoutMs));
   }
-  if (parsed.locator && parsed.lastState === "resolved-count" && parsed.resolvedCount !== null) {
-    const count = parsed.resolvedCount;
-    return subject(line, parsed.locator, opts).text(` matched ${count === 0 ? "no" : count} ${countNoun(parsed.locator, count)} \u2014 ${verb} timed out`).text(timeoutSuffix(parsed.timeoutMs));
+  if (parsed2.locator && parsed2.lastState === "resolved-count" && parsed2.resolvedCount !== null) {
+    const count = parsed2.resolvedCount;
+    return subject(line, parsed2.locator, opts).text(` matched ${count === 0 ? "no" : count} ${countNoun(parsed2.locator, count)} \u2014 ${verb} timed out`).text(timeoutSuffix(parsed2.timeoutMs));
   }
-  if (parsed.locator) {
-    return line.text(`${verb} on `).locator(opts.locator ?? parsed.locator).text(" timed out").text(timeoutSuffix(parsed.timeoutMs));
+  if (parsed2.locator) {
+    return line.text(`${verb} on `).locator(opts.locator ?? parsed2.locator).text(" timed out").text(timeoutSuffix(parsed2.timeoutMs));
   }
-  const call = parsed.subject && parsed.action ? `${parsed.subject}.${parsed.action}` : verb;
-  return line.text(`${call} timed out`).text(timeoutSuffix(parsed.timeoutMs));
+  const call = parsed2.subject && parsed2.action ? `${parsed2.subject}.${parsed2.action}` : verb;
+  return line.text(`${call} timed out`).text(timeoutSuffix(parsed2.timeoutMs));
 }
-function buildAssertion(parsed, opts) {
+function buildAssertion(parsed2, opts) {
   const line = new Line();
-  const matcher = parsed.assertion ?? "expect";
-  const notFound = parsed.lastState === "not-found" || parsed.lastState === "resolved-count" && parsed.resolvedCount === 0 || /element\(s\) not found/.test(parsed.received ?? "");
-  const expected = parsed.expected ? truncateValue(parsed.expected, opts.valueMax) : null;
-  const received = parsed.received ? truncateValue(receivedDisplay(parsed), opts.valueMax) : null;
-  if (matcher === "toHaveCount" && parsed.locator) {
-    const want = Number(parsed.expected);
-    const got = notFound ? 0 : Number(parsed.received);
+  const matcher = parsed2.assertion ?? "expect";
+  const notFound = parsed2.lastState === "not-found" || parsed2.lastState === "resolved-count" && parsed2.resolvedCount === 0 || /element\(s\) not found/.test(parsed2.received ?? "");
+  const expected = parsed2.expected ? truncateValue(parsed2.expected, opts.valueMax) : null;
+  const received = parsed2.received ? truncateValue(receivedDisplay(parsed2), opts.valueMax) : null;
+  if (matcher === "toHaveCount" && parsed2.locator) {
+    const want = Number(parsed2.expected);
+    const got = notFound ? 0 : Number(parsed2.received);
     const wantText = Number.isFinite(want) ? String(want) : expected ?? "?";
-    const noun2 = countNoun(parsed.locator, Number.isFinite(want) ? want : 2);
+    const noun2 = countNoun(parsed2.locator, Number.isFinite(want) ? want : 2);
     const gotText = Number.isFinite(got) ? got === 0 ? "none" : String(got) : received ?? "none";
-    return line.text(`Expected ${wantText} ${noun2}, found ${gotText} \u2014 `).locator(opts.locator ?? parsed.locator).text(" toHaveCount");
+    return line.text(`Expected ${wantText} ${noun2}, found ${gotText} \u2014 `).locator(opts.locator ?? parsed2.locator).text(" toHaveCount");
   }
   const state = STATE_MATCHERS[matcher];
   if (state) {
-    const unmet = parsed.negated ? `stayed ${state.met}` : state.unmet;
-    if (!parsed.locator) return line.text(`Expected ${state.met}, page ${unmet}`).text(timeoutParen(parsed.timeoutMs));
+    const unmet = parsed2.negated ? `stayed ${state.met}` : state.unmet;
+    if (!parsed2.locator) return line.text(`Expected ${state.met}, page ${unmet}`).text(timeoutParen(parsed2.timeoutMs));
     if (notFound && matcher !== "toBeVisible" && matcher !== "toBeAttached") {
-      return subject(line, parsed.locator, opts).text(` was not found on the page \u2014 expected ${state.met}`).text(timeoutParen(parsed.timeoutMs));
+      return subject(line, parsed2.locator, opts).text(` was not found on the page \u2014 expected ${state.met}`).text(timeoutParen(parsed2.timeoutMs));
     }
-    return subject(line, parsed.locator, opts).text(` ${unmet}`).text(timeoutParen(parsed.timeoutMs));
+    return subject(line, parsed2.locator, opts).text(` ${unmet}`).text(timeoutParen(parsed2.timeoutMs));
   }
   const noun = VALUE_MATCHERS[matcher];
   if (noun) {
-    if (parsed.locator && notFound) {
-      return subject(line, parsed.locator, opts).text(" was not found on the page \u2014 expected ").text(`${noun} `).value(expected ?? "").text(timeoutParen(parsed.timeoutMs));
+    if (parsed2.locator && notFound) {
+      return subject(line, parsed2.locator, opts).text(" was not found on the page \u2014 expected ").text(`${noun} `).value(expected ?? "").text(timeoutParen(parsed2.timeoutMs));
     }
     line.text(`Expected ${noun} `);
     if (expected) line.value(expected);
     else line.text("to match");
     if (received) line.text(", got ").value(received);
-    if (parsed.locator)
-      line.text(" \u2014 ").locator(opts.locator ?? parsed.locator).text(` ${matcher}`);
+    if (parsed2.locator)
+      line.text(" \u2014 ").locator(opts.locator ?? parsed2.locator).text(` ${matcher}`);
     else if (matcher === "toHaveURL" || matcher === "toHaveTitle") line.text(` \u2014 page ${matcher}`);
     return line;
   }
-  if (matcher === "toPass") return line.text("expect.toPass never passed").text(timeoutParen(parsed.timeoutMs));
+  if (matcher === "toPass") return line.text("expect.toPass never passed").text(timeoutParen(parsed2.timeoutMs));
   if (expected || received) {
     line.text("Expected ");
     if (expected) line.value(expected);
     else line.text("a different value");
     if (received) line.text(", got ").value(received);
     line.text(` \u2014 ${matcher}`);
-    if (parsed.locator) line.text(" on ").locator(opts.locator ?? parsed.locator);
+    if (parsed2.locator) line.text(" on ").locator(opts.locator ?? parsed2.locator);
     return line;
   }
-  if (parsed.locator) {
-    return subject(line, parsed.locator, opts).text(` failed ${matcher}`).text(timeoutParen(parsed.timeoutMs));
+  if (parsed2.locator) {
+    return subject(line, parsed2.locator, opts).text(` failed ${matcher}`).text(timeoutParen(parsed2.timeoutMs));
   }
   return line.text(`${matcher} assertion failed`);
 }
-function buildStrictMode(parsed, opts) {
+function buildStrictMode(parsed2, opts) {
   const line = new Line();
-  const count = parsed.resolvedCount ?? 0;
-  if (!parsed.locator) return line.text(`Locator matched ${count} elements \u2014 strict mode`);
-  return line.locator(opts.locator ?? parsed.locator).text(` matched ${count} ${countNoun(parsed.locator, count)} \u2014 strict mode`);
+  const count = parsed2.resolvedCount ?? 0;
+  if (!parsed2.locator) return line.text(`Locator matched ${count} elements \u2014 strict mode`);
+  return line.locator(opts.locator ?? parsed2.locator).text(` matched ${count} ${countNoun(parsed2.locator, count)} \u2014 strict mode`);
 }
-function buildNavigation(parsed, opts) {
+function buildNavigation(parsed2, opts) {
   const line = new Line();
-  const code = parsed.networkErrorCode?.replace(/^net::/, "") ?? null;
+  const code = parsed2.networkErrorCode?.replace(/^net::/, "") ?? null;
   if (code) {
     const phrase = NETWORK_ERRORS[code] ?? `${code.replace(/^(?:ERR|NS_ERROR)_/, "").replace(/_/g, " ").toLowerCase().replace(/^\w/, (c) => c.toUpperCase())} loading`;
     line.text(phrase);
-    if (parsed.url) line.text(" ").value(truncateValue(parsed.url, opts.valueMax * 2));
+    if (parsed2.url) line.text(" ").value(truncateValue(parsed2.url, opts.valueMax * 2));
     return line;
   }
-  const route = parsed.url ? routeOf(parsed.url) : null;
-  const timedOut = parsed.timeoutMs !== null || parsed.errorName === "TimeoutError";
-  if (parsed.action === "waitForURL" || parsed.action === "waitForNavigation") {
+  const route = parsed2.url ? routeOf(parsed2.url) : null;
+  const timedOut = parsed2.timeoutMs !== null || parsed2.errorName === "TimeoutError";
+  if (parsed2.action === "waitForURL" || parsed2.action === "waitForNavigation") {
     line.text("Never navigated to ");
     if (route) line.value(truncateValue(route, opts.valueMax));
     else line.text("the expected URL");
-    return line.text(` \u2014 ${parsed.action} timed out`).text(timeoutSuffix(parsed.timeoutMs));
+    return line.text(` \u2014 ${parsed2.action} timed out`).text(timeoutSuffix(parsed2.timeoutMs));
   }
   line.text("Navigation");
   if (route) line.text(" to ").value(truncateValue(route, opts.valueMax));
-  if (timedOut) return line.text(" timed out").text(timeoutSuffix(parsed.timeoutMs));
+  if (timedOut) return line.text(" timed out").text(timeoutSuffix(parsed2.timeoutMs));
   return line.text(" failed");
 }
-function buildTestTimeout(parsed, opts, ctx) {
-  const line = new Line().text("Test timed out").text(timeoutSuffix(parsed.timeoutMs));
-  if (parsed.timeoutPhase) {
-    const phase = parsed.timeoutPhase;
+function buildTestTimeout(parsed2, opts, ctx) {
+  const line = new Line().text("Test timed out").text(timeoutSuffix(parsed2.timeoutMs));
+  if (parsed2.timeoutPhase) {
+    const phase = parsed2.timeoutPhase;
     const isHook = /^(?:before|after)(?:Each|All)$/.test(phase);
     return line.text(isHook ? ` in the "${phase}" hook` : ` while tearing down "${phase}"`);
   }
-  if (parsed.isNavigationFailure && parsed.url) {
-    return line.text(" while navigating to ").value(truncateValue(routeOf(parsed.url), opts.valueMax));
+  if (parsed2.isNavigationFailure && parsed2.url) {
+    return line.text(" while navigating to ").value(truncateValue(routeOf(parsed2.url), opts.valueMax));
   }
-  if (parsed.assertion && parsed.locator) {
-    const state = STATE_MATCHERS[parsed.assertion];
+  if (parsed2.assertion && parsed2.locator) {
+    const state = STATE_MATCHERS[parsed2.assertion];
     line.text(state ? ` while waiting for ` : " while expecting ");
-    subject(line, parsed.locator, opts);
-    return line.text(state ? ` to be ${state.met}` : ` ${parsed.assertion}`);
+    subject(line, parsed2.locator, opts);
+    return line.text(state ? ` to be ${state.met}` : ` ${parsed2.assertion}`);
   }
-  if (parsed.action && parsed.locator) {
-    const gerund = ACTION_GERUNDS[parsed.action] ?? `${ACTION_VERBS[parsed.action] ?? parsed.action} on`;
+  if (parsed2.action && parsed2.locator) {
+    const gerund = ACTION_GERUNDS[parsed2.action] ?? `${ACTION_VERBS[parsed2.action] ?? parsed2.action} on`;
     line.text(` while ${gerund} `);
-    return subject(line, parsed.locator, opts);
+    return subject(line, parsed2.locator, opts);
   }
-  if (parsed.subject && parsed.action) return line.text(` during ${parsed.subject}.${parsed.action}`);
+  if (parsed2.subject && parsed2.action) return line.text(` during ${parsed2.subject}.${parsed2.action}`);
   const step = ctx?.lastStepTitle?.trim();
   if (step) return line.text(" while ").value(`"${truncateValue(step, opts.valueMax * 1.5)}"`);
   return line;
 }
-function buildCrash(parsed, opts) {
+function buildCrash(parsed2, opts) {
   const line = new Line();
-  const what = /Page crashed/i.test(parsed.messageHead) ? "Page crashed" : "Page or browser closed";
-  if (parsed.action) {
-    const verb = ACTION_VERBS[parsed.action] ?? parsed.action;
+  const what = /Page crashed/i.test(parsed2.messageHead) ? "Page crashed" : "Page or browser closed";
+  if (parsed2.action) {
+    const verb = ACTION_VERBS[parsed2.action] ?? parsed2.action;
     line.text(`${what} during ${verb}`);
-    if (parsed.locator) line.text(" on ").locator(opts.locator ?? parsed.locator);
+    if (parsed2.locator) line.text(" on ").locator(opts.locator ?? parsed2.locator);
     return line;
   }
-  if (parsed.assertion && parsed.locator) {
-    return line.text(`${what} while expecting `).locator(opts.locator ?? parsed.locator).text(` ${parsed.assertion}`);
+  if (parsed2.assertion && parsed2.locator) {
+    return line.text(`${what} while expecting `).locator(opts.locator ?? parsed2.locator).text(` ${parsed2.assertion}`);
   }
   return line.text(what);
 }
 var CUSTOM_MESSAGE_MAX_CHARS = 60;
 var SENTENCE_CASE_WORD_RE = /^[A-Z][a-z]*(?![A-Za-z])/;
-function withLeads(line, parsed, ctx) {
-  const hook = ctx?.failedIn && !parsed.timeoutPhase ? ctx.failedIn.hook : null;
-  const message = parsed.customMessage ? truncateValue(parsed.customMessage, CUSTOM_MESSAGE_MAX_CHARS) : null;
+function withLeads(line, parsed2, ctx) {
+  const hook = ctx?.failedIn && !parsed2.timeoutPhase ? ctx.failedIn.hook : null;
+  const message = parsed2.customMessage ? truncateValue(parsed2.customMessage, CUSTOM_MESSAGE_MAX_CHARS) : null;
   if (!hook && !message) return line;
   const led = new Line();
   if (hook) led.text(`In ${hook}${message ? ", " : ": "}`);
@@ -8258,49 +8299,49 @@ function withLeads(line, parsed, ctx) {
   });
   return led;
 }
-function build(parsed, opts, ctx) {
-  return withLeads(buildLine(parsed, opts, ctx), parsed, ctx);
+function build(parsed2, opts, ctx) {
+  return withLeads(buildLine(parsed2, opts, ctx), parsed2, ctx);
 }
-function buildLine(parsed, opts, ctx) {
-  switch (parsed.kind) {
+function buildLine(parsed2, opts, ctx) {
+  switch (parsed2.kind) {
     case "action-timeout":
-      return buildActionTimeout(parsed, opts);
+      return buildActionTimeout(parsed2, opts);
     case "assertion":
     case "assertion-timeout":
-      return buildAssertion(parsed, opts);
+      return buildAssertion(parsed2, opts);
     case "strict-mode":
-      return buildStrictMode(parsed, opts);
+      return buildStrictMode(parsed2, opts);
     case "navigation":
-      return buildNavigation(parsed, opts);
+      return buildNavigation(parsed2, opts);
     case "test-timeout":
-      return buildTestTimeout(parsed, opts, ctx);
+      return buildTestTimeout(parsed2, opts, ctx);
     case "crash":
-      return buildCrash(parsed, opts);
+      return buildCrash(parsed2, opts);
     default:
-      return new Line().text(firstLineFallback(parsed));
+      return new Line().text(firstLineFallback(parsed2));
   }
 }
-function detailOf(parsed, headline) {
-  switch (parsed.kind) {
+function detailOf(parsed2, headline) {
+  switch (parsed2.kind) {
     case "test-timeout":
     case "action-timeout": {
-      const state = parsed.lastStateLine;
-      if (!state || parsed.lastState === "not-found" || headline.includes(state)) return null;
+      const state = parsed2.lastStateLine;
+      if (!state || parsed2.lastState === "not-found" || headline.includes(state)) return null;
       return truncateValue(state, HEADLINE_MAX_CHARS);
     }
     case "assertion":
     case "assertion-timeout": {
-      const received = parsed.received;
+      const received = parsed2.received;
       if (received && !/element\(s\) not found/.test(received)) {
-        const shown = truncateValue(receivedDisplay(parsed), SHORT_VALUE_MAX_CHARS).slice(0, 8);
+        const shown = truncateValue(receivedDisplay(parsed2), SHORT_VALUE_MAX_CHARS).slice(0, 8);
         if (!headline.includes(shown)) return truncateValue(`Received: ${received}`, HEADLINE_MAX_CHARS);
       }
-      const state = parsed.lastStateLine;
+      const state = parsed2.lastStateLine;
       if (!state || /^(?:waiting for |unexpected value )/.test(state)) return null;
       return truncateValue(state, HEADLINE_MAX_CHARS);
     }
     case "navigation":
-      return parsed.networkErrorCode ?? parsed.lastStateLine;
+      return parsed2.networkErrorCode ?? parsed2.lastStateLine;
     case "strict-mode":
     case "crash":
       return null;
@@ -8308,16 +8349,16 @@ function detailOf(parsed, headline) {
       return null;
   }
 }
-function describeFailure(parsed, ctx) {
+function describeFailure(parsed2, ctx) {
   const attempts = [
-    { locator: parsed.locator, valueMax: VALUE_MAX_CHARS },
-    { locator: parsed.leafLocator ?? parsed.locator, valueMax: VALUE_MAX_CHARS },
-    { locator: parsed.leafLocator ?? parsed.locator, valueMax: SHORT_VALUE_MAX_CHARS }
+    { locator: parsed2.locator, valueMax: VALUE_MAX_CHARS },
+    { locator: parsed2.leafLocator ?? parsed2.locator, valueMax: VALUE_MAX_CHARS },
+    { locator: parsed2.leafLocator ?? parsed2.locator, valueMax: SHORT_VALUE_MAX_CHARS }
   ];
-  let line = build(parsed, attempts[0], ctx);
+  let line = build(parsed2, attempts[0], ctx);
   for (const opts of attempts.slice(1)) {
     if (line.toString().length <= HEADLINE_MAX_CHARS) break;
-    line = build(parsed, opts, ctx);
+    line = build(parsed2, opts, ctx);
   }
   let parts = line.parts.map((p) => ({ ...p, text: p.text.replace(MASK_TOKEN_RE, "\u2026") }));
   let headline = parts.map((p) => p.text).join("");
@@ -8327,10 +8368,10 @@ function describeFailure(parsed, ctx) {
     parts.push({ kind: "text", text: "\u2026" });
   }
   if (!headline.trim()) {
-    headline = firstLineFallback(parsed);
+    headline = firstLineFallback(parsed2);
     parts = [{ kind: "text", text: headline }];
   }
-  return { headline, detail: detailOf(parsed, headline), parts };
+  return { headline, detail: detailOf(parsed2, headline), parts };
 }
 function clipParts(parts, max) {
   const out = [];
@@ -9040,7 +9081,7 @@ async function resolveSelection(options = {}) {
 }
 
 // src/internal/capture/capture-fixtures.ts
-var path27 = __toESM(require("path"));
+var path28 = __toESM(require("path"));
 var import_node_zlib2 = require("zlib");
 
 // ../picker-dom/src/probe.ts
@@ -10103,6 +10144,83 @@ function showPickerChoices(arg) {
   doc.body.appendChild(wrap);
 }
 
+// ../picker-dom/src/overlay-pause.ts
+function showPauseBar(arg) {
+  const g = globalThis;
+  const doc = g.document;
+  delete g.__piwiPauseState;
+  if (!doc || !doc.body) {
+    g.__piwiPauseState = "resume";
+    return;
+  }
+  if (typeof g.__piwiPauseCleanup === "function") g.__piwiPauseCleanup();
+  const Z = 2147483600;
+  const bar = doc.createElement("div");
+  bar.id = "__piwi-pause-bar";
+  bar.setAttribute("role", "toolbar");
+  bar.setAttribute("aria-label", "Piwi: test paused");
+  bar.style.cssText = `position:fixed;top:0;left:0;right:0;z-index:${Z + 4};display:flex;align-items:center;gap:12px;flex-wrap:wrap;padding:8px 12px;background:#111827;color:#f9fafb;border-bottom:2px solid #a78bfa;box-shadow:0 4px 20px rgba(0,0,0,.35);font:13px/1.5 system-ui,sans-serif;`;
+  const where = doc.createElement("div");
+  where.style.cssText = "font-weight:600;white-space:nowrap;";
+  where.textContent = `Paused at ${arg.place}${arg.attempt ? ` \xB7 attempt ${arg.attempt}` : ""}`;
+  const what = doc.createElement("code");
+  what.style.cssText = "flex:1;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;color:#d8b4fe;font:12px/1.5 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;";
+  what.textContent = arg.locator ? `${arg.action} \xB7 ${arg.locator}` : arg.action;
+  what.title = what.textContent;
+  bar.appendChild(where);
+  bar.appendChild(what);
+  const done = (choice) => {
+    cleanup();
+    g.__piwiPauseState = choice;
+  };
+  const onKey = (e) => {
+    if (e.key !== "Escape") return;
+    e.preventDefault();
+    e.stopImmediatePropagation();
+    done("resume");
+  };
+  const cleanup = () => {
+    doc.removeEventListener("keydown", onKey, true);
+    bar.remove();
+    delete g.__piwiPauseCleanup;
+  };
+  const buttons = [
+    ["Resume", "resume", "Run on to the next breakpoint (Esc)", true],
+    ["Step", "step", "Pause again at the next action", false],
+    ["Pick a locator", "pick", "Pick an element on the page and confirm a locator for it", false],
+    ["Finish", "finish", "Run on and pause no more in this test", false]
+  ];
+  for (const [label, choice, hint, primary] of buttons) {
+    const btn = doc.createElement("button");
+    btn.type = "button";
+    btn.textContent = label;
+    btn.title = hint;
+    btn.style.cssText = "border-radius:6px;padding:4px 12px;cursor:pointer;font:600 12px/1.5 system-ui,sans-serif;" + (primary ? "background:#7c3aed;color:#fff;border:1px solid #7c3aed;" : "background:#1f2937;color:#f3f4f6;border:1px solid #374151;");
+    btn.addEventListener("click", (e) => {
+      e.preventDefault();
+      e.stopImmediatePropagation();
+      done(choice);
+    });
+    bar.appendChild(btn);
+  }
+  g.__piwiPauseCleanup = cleanup;
+  doc.addEventListener("keydown", onKey, true);
+  doc.body.appendChild(bar);
+}
+function pauseAnswered() {
+  const g = globalThis;
+  if (g.__piwiPauseState !== void 0) return true;
+  return !g.document?.getElementById("__piwi-pause-bar");
+}
+function takePauseState() {
+  const g = globalThis;
+  const state = g.__piwiPauseState;
+  if (typeof g.__piwiPauseCleanup === "function") g.__piwiPauseCleanup();
+  delete g.__piwiPauseCleanup;
+  delete g.__piwiPauseState;
+  return typeof state === "string" ? state : null;
+}
+
 // ../core/src/locator-generation.ts
 var TAG_TO_ROLE = {
   a: "link",
@@ -11139,11 +11257,11 @@ function deriveFailedLocator(testInfo) {
 ${err.stack ?? ""}`.replace(ANSI_RE2, "");
     const line = /^\s*Locator:\s*(.+)$/m.exec(text);
     if (!line) continue;
-    const parsed = parseLeafLocatorExpression(line[1].trim());
-    if (!parsed) continue;
+    const parsed2 = parseLeafLocatorExpression(line[1].trim());
+    if (!parsed2) continue;
     const loc = err.location;
     const location = loc ? `${path25.relative(process.cwd(), loc.file).split(path25.sep).join("/")}:${loc.line}:${loc.column}` : null;
-    return { method: parsed.method, args: parsed.args, location };
+    return { method: parsed2.method, args: parsed2.args, location };
   }
   return null;
 }
@@ -11165,25 +11283,16 @@ async function cleanupPicker(page) {
   } catch {
   }
 }
-async function runLocatorPicker(page, testInfo, failed, probe) {
+async function pickLocator(page, probe, failing) {
   try {
-    testInfo.setTimeout(0);
-    const rendered = failed ? renderFailing(failed) : null;
-    console.log(
-      `
-[piwi] "${testInfo.title}" ${testInfo.status} \u2014 ${rendered ? "locator picker" : "inspector"} open in the browser: ${rendered ? `click the element that should replace ${rendered}` : "click any element to generate locators for it"} (\u2191/\u2193 to select a parent/child, Esc to skip).`
-    );
-    const overlayArg = { transport: "global", failing: rendered };
+    const overlayArg = { transport: "global", failing };
     await page.evaluate(installPickerOverlay, overlayArg);
     await page.waitForFunction(() => globalThis.__piwiPickState !== void 0, void 0, {
       timeout: 0,
       polling: 250
     });
     const state = await page.evaluate(() => globalThis.__piwiPickState);
-    if (state !== "picked") {
-      await cleanupPicker(page);
-      return null;
-    }
+    if (state !== "picked") return null;
     const handle = await page.evaluateHandle(() => globalThis.__piwiPickedElement);
     const attrs = await handle.evaluate(probe.fn, probe.arg);
     await handle.dispose();
@@ -11221,11 +11330,10 @@ async function runLocatorPicker(page, testInfo, failed, probe) {
     );
     if (ranked.length === 0) {
       console.log("[piwi] No stable locator could be generated for the picked element \u2014 nothing recorded.");
-      await cleanupPicker(page);
       return null;
     }
     await page.evaluate(showPickerChoices, {
-      failing: rendered,
+      failing,
       choices: ranked.map((r) => ({ locator: r.locator, score: r.score }))
     });
     await page.waitForFunction(() => globalThis.__piwiPickChoice !== void 0, void 0, {
@@ -11233,31 +11341,45 @@ async function runLocatorPicker(page, testInfo, failed, probe) {
       polling: 250
     });
     const choice = await page.evaluate(() => globalThis.__piwiPickChoice);
-    await cleanupPicker(page);
     if (typeof choice !== "number" || choice < 0 || choice >= ranked.length) return null;
     const picked = { ...ranked[choice], pickedByUser: true };
-    const alternatives = [picked, ...ranked.filter((_, i) => i !== choice)];
-    const element = {
-      tagName: attrs.tagName,
-      attributes: attrs.attributes,
-      textContent: attrs.textContent,
-      accessibleName,
-      center: attrs.center,
-      ...attrs.rolePosition ? { rolePosition: attrs.rolePosition } : {},
-      ...attrs.ancestors && attrs.ancestors.length > 0 ? { ancestors: attrs.ancestors } : {}
+    return {
+      picked,
+      alternatives: [picked, ...ranked.filter((_, i) => i !== choice)],
+      element: {
+        tagName: attrs.tagName,
+        attributes: attrs.attributes,
+        textContent: attrs.textContent,
+        accessibleName,
+        center: attrs.center,
+        ...attrs.rolePosition ? { rolePosition: attrs.rolePosition } : {},
+        ...attrs.ancestors && attrs.ancestors.length > 0 ? { ancestors: attrs.ancestors } : {}
+      },
+      ...anchors.length > 0 ? { anchors } : {}
     };
+  } finally {
+    await cleanupPicker(page);
+  }
+}
+async function runLocatorPicker(page, testInfo, failed, probe) {
+  try {
+    testInfo.setTimeout(0);
+    const rendered = failed ? renderFailing(failed) : null;
+    console.log(
+      `
+[piwi] "${testInfo.title}" ${testInfo.status} \u2014 ${rendered ? "locator picker" : "inspector"} open in the browser: ${rendered ? `click the element that should replace ${rendered}` : "click any element to generate locators for it"} (\u2191/\u2193 to select a parent/child, Esc to skip).`
+    );
+    const pick = await pickLocator(page, probe, rendered);
+    if (!pick) return null;
     const location = failed?.location ?? null;
     console.log(
       failed ? `[piwi] Replacement picked for ${rendered}${location ? ` at ${location}` : ""}:
-[piwi]   ${picked.locator}` : `[piwi] Locator picked while inspecting:
-[piwi]   ${picked.locator}`
+[piwi]   ${pick.picked.locator}` : `[piwi] Locator picked while inspecting:
+[piwi]   ${pick.picked.locator}`
     );
     return {
       failing: failed ? { method: failed.method, args: failed.args, rendered, location } : null,
-      picked,
-      alternatives,
-      element,
-      ...anchors.length > 0 ? { anchors } : {}
+      ...pick
     };
   } catch {
     return null;
@@ -11290,10 +11412,207 @@ function applyPickToSnapshots(snapshots, pick) {
   return true;
 }
 
+// src/internal/capture/pause-at.ts
+var path26 = __toESM(require("path"));
+
+// ../core/src/editor-send.ts
+var LOOPBACK_HOSTS = /* @__PURE__ */ new Set(["127.0.0.1", "localhost", "[::1]"]);
+function parsePairing(text) {
+  const trimmed = text.trim();
+  const hash = trimmed.indexOf("#");
+  if (hash < 0) return null;
+  const url = trimmed.slice(0, hash);
+  const token = trimmed.slice(hash + 1);
+  if (!/^[A-Za-z0-9_-]{16,}$/.test(token)) return null;
+  let parsed2;
+  try {
+    parsed2 = new URL(url);
+  } catch {
+    return null;
+  }
+  if (parsed2.protocol !== "http:" || !LOOPBACK_HOSTS.has(parsed2.hostname) || !parsed2.port) return null;
+  return { url: `${parsed2.origin}${parsed2.pathname}`, token };
+}
+function isInsidePath(file) {
+  if (!file || file.length > 1e3 || file.includes("\0")) return false;
+  if (file.startsWith("/") || file.startsWith("\\") || /^[A-Za-z]:/.test(file)) return false;
+  return file.split(/[\\/]/).every((part) => part !== "..");
+}
+
+// src/internal/capture/pause-at.ts
+var PauseSet = class {
+  constructor(lines) {
+    this.lines = lines;
+  }
+  get size() {
+    return this.lines.size;
+  }
+  /** Whether a call site (`file:line:col`, as `captureCallerLocation` writes it) is on one of the lines. */
+  matches(callerLocation) {
+    if (!callerLocation) return false;
+    const col = callerLocation.lastIndexOf(":");
+    return col > 0 && this.lines.has(callerLocation.slice(0, col));
+  }
+};
+var EMPTY = new PauseSet(/* @__PURE__ */ new Set());
+function callSiteFile(file, cwd) {
+  const slashed = file.replace(/\\/g, "/");
+  const absolute = path26.isAbsolute(file) || path26.isAbsolute(slashed) || /^[A-Za-z]:\//.test(slashed);
+  let rel = absolute ? path26.relative(cwd, file) : path26.normalize(slashed);
+  rel = rel.split(path26.sep).join("/").replace(/\\/g, "/");
+  if (rel.startsWith("./")) rel = rel.slice(2);
+  return rel;
+}
+var ignoredLogged = /* @__PURE__ */ new Set();
+function parsePauseAt(value, cwd = process.cwd()) {
+  if (!value?.trim()) return EMPTY;
+  const lines = /* @__PURE__ */ new Set();
+  for (const raw of value.split(";")) {
+    const entry = raw.trim();
+    if (!entry) continue;
+    const m = /^(.+):(\d+)$/.exec(entry);
+    const line = m ? Number(m[2]) : 0;
+    if (!m?.[1] || line < 1) {
+      if (!ignoredLogged.has(entry)) {
+        ignoredLogged.add(entry);
+        console.log(`[piwi] ${PIWI_LOCAL_DEBUG_ENV.pauseAt}: ignoring "${entry}": expected file:line`);
+      }
+      continue;
+    }
+    lines.add(`${callSiteFile(m[1], cwd)}:${line}`);
+  }
+  return lines.size ? new PauseSet(lines) : EMPTY;
+}
+var parsed = null;
+function currentPauseSet() {
+  const value = process.env[PIWI_LOCAL_DEBUG_ENV.pauseAt];
+  if (!parsed || parsed.value !== value) parsed = { value, set: parsePauseAt(value) };
+  return parsed.set;
+}
+function pauseGateFromTestInfo(testInfo) {
+  const use = testInfo.project?.use ?? {};
+  return { ci: process.env.CI, headless: use.headless };
+}
+function pauseSkipReason(gate) {
+  if (isCi(gate.ci)) return "running under CI \u2014 breakpoints pause local runs only";
+  if (gate.headless !== false)
+    return "the browser is headless \u2014 re-run with --headed (or set use: { headless: false })";
+  return null;
+}
+function rearmedTimeout(before, pausedMs) {
+  return before > 0 ? before + Math.max(0, Math.round(pausedMs)) : 0;
+}
+function pausePlace(callerLocation) {
+  const col = callerLocation.lastIndexOf(":");
+  const fileLine = col > 0 ? callerLocation.slice(0, col) : callerLocation;
+  return fileLine.slice(fileLine.lastIndexOf("/") + 1);
+}
+function assertionLabel(expression, isNot) {
+  const [first = "", ...rest] = expression.split(".").filter(Boolean);
+  const name = first + rest.map((p) => p.charAt(0).toUpperCase() + p.slice(1)).join("");
+  return `${isNot ? "not." : ""}${name || "expect"}`;
+}
+function pickPlace(callerLocation) {
+  const m = /^(.+):(\d+):\d+$/.exec(callerLocation);
+  if (!m) return null;
+  const file = m[1];
+  if (!isInsidePath(file)) return null;
+  return { file, line: Number(m[2]) };
+}
+function pickPayload(locator, callerLocation) {
+  const at = pickPlace(callerLocation);
+  return at ? { kind: "locator", text: locator, at } : { kind: "locator", text: locator };
+}
+var postFailureLogged = false;
+async function postPickToEditor(pairingAddress, payload, fetchImpl = fetch) {
+  if (!pairingAddress) return false;
+  const logOnce = (why) => {
+    if (postFailureLogged) return;
+    postFailureLogged = true;
+    console.log(`[piwi] Could not send the picked locator to the editor: ${why}.`);
+  };
+  const pairing = parsePairing(pairingAddress);
+  if (!pairing) {
+    logOnce(`${PIWI_LOCAL_DEBUG_ENV.editorSend} is not a pairing address`);
+    return false;
+  }
+  try {
+    const response = await fetchImpl(pairing.url, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${pairing.token}`, "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+      signal: AbortSignal.timeout(5e3)
+    });
+    if (response.ok) return true;
+    logOnce(`the editor answered ${response.status}`);
+  } catch (error) {
+    logOnce(error instanceof Error ? error.message : String(error));
+  }
+  return false;
+}
+var skipLogged = false;
+function logPauseSkipOnce(reason) {
+  if (skipLogged) return;
+  skipLogged = true;
+  console.log(`[piwi] ${PIWI_LOCAL_DEBUG_ENV.pauseAt} is set but breakpoints are skipped: ${reason}`);
+}
+var HIGHLIGHT_MS = 2e3;
+async function pauseHere(page, testInfo, point, probe, onPick) {
+  const before = testInfo.timeout;
+  const started = Date.now();
+  let shown = null;
+  try {
+    testInfo.setTimeout(0);
+    const highlight = point.target?.highlight;
+    if (typeof highlight === "function") {
+      let timer;
+      shown = await Promise.race([
+        Promise.resolve().then(() => highlight.call(point.target)).catch(() => null),
+        new Promise((resolve7) => {
+          timer = setTimeout(() => resolve7(null), HIGHLIGHT_MS);
+        })
+      ]);
+      clearTimeout(timer);
+    }
+    const arg = {
+      place: pausePlace(point.location),
+      attempt: testInfo.retry > 0 ? testInfo.retry + 1 : null,
+      action: point.action,
+      locator: point.locator
+    };
+    console.log(
+      `[piwi] Paused at ${point.location} before ${point.locator ? `${point.action} \xB7 ${point.locator}` : point.action}: Resume, Step, Pick a locator or Finish in the browser (Esc resumes).`
+    );
+    for (; ; ) {
+      await page.evaluate(showPauseBar, arg);
+      await page.waitForFunction(pauseAnswered, void 0, { timeout: 0, polling: 250 });
+      const choice = await page.evaluate(takePauseState);
+      if (choice === "resume" || choice === "step" || choice === "finish") return choice;
+      if (choice !== "pick") continue;
+      const picked = await pickLocator(page, probe, null).catch(() => null);
+      if (picked) await onPick(picked);
+    }
+  } catch {
+    return "resume";
+  } finally {
+    try {
+      const dispose = shown?.dispose;
+      const hide = page.hideHighlight;
+      if (typeof dispose === "function") await dispose.call(shown);
+      else if (typeof hide === "function") await hide.call(page);
+    } catch {
+    }
+    try {
+      testInfo.setTimeout(rearmedTimeout(before, Date.now() - started));
+    } catch {
+    }
+  }
+}
+
 // src/internal/capture/code-reach.ts
 var crypto3 = __toESM(require("crypto"));
 var fs22 = __toESM(require("fs"));
-var path26 = __toESM(require("path"));
+var path27 = __toESM(require("path"));
 var import_node_child_process3 = require("child_process");
 
 // ../core/src/source-map.ts
@@ -11556,12 +11875,12 @@ function repositoryRoot(from) {
     }).trim();
   } catch {
   }
-  cachedRepoRoot = { from, root: path26.resolve(root) };
+  cachedRepoRoot = { from, root: path27.resolve(root) };
   return cachedRepoRoot.root;
 }
 function codeReachRoots(configDir, configured) {
   const repoRoot = repositoryRoot(configDir);
-  const roots = configured?.length ? configured.map((r) => path26.resolve(configDir, r)) : [configDir];
+  const roots = configured?.length ? configured.map((r) => path27.resolve(configDir, r)) : [configDir];
   return { roots: [.../* @__PURE__ */ new Set([...roots, repoRoot])], repoRoot };
 }
 function isFile(file) {
@@ -11574,10 +11893,10 @@ function isFile(file) {
 function resolveSourcePath(source, roots) {
   const normalized = normalizeSourcePath(source);
   if (!normalized || /(?:^|\/)node_modules\//.test(normalized)) return null;
-  if (path26.isAbsolute(normalized) && isFile(normalized)) return path26.resolve(normalized);
-  const relative13 = normalized.replace(/^\/+/, "");
+  if (path27.isAbsolute(normalized) && isFile(normalized)) return path27.resolve(normalized);
+  const relative14 = normalized.replace(/^\/+/, "");
   for (const root of roots) {
-    const candidate = path26.resolve(root, relative13);
+    const candidate = path27.resolve(root, relative14);
     if (isFile(candidate)) return candidate;
   }
   return null;
@@ -11593,10 +11912,10 @@ function viteBases(entries) {
 function fileForUrl(url, roots, bases) {
   let pathname;
   try {
-    const parsed = new URL(url);
-    if (parsed.protocol !== "http:" && parsed.protocol !== "https:" && parsed.protocol !== "file:") return null;
-    pathname = parsed.pathname;
-    const base = bases.get(parsed.origin);
+    const parsed2 = new URL(url);
+    if (parsed2.protocol !== "http:" && parsed2.protocol !== "https:" && parsed2.protocol !== "file:") return null;
+    pathname = parsed2.pathname;
+    const base = bases.get(parsed2.origin);
     if (base && pathname.startsWith(base)) pathname = pathname.slice(base.length - 1);
   } catch {
     return null;
@@ -11609,7 +11928,7 @@ function fileForUrl(url, roots, bases) {
   return file;
 }
 function relativeToRepo(file, repoRoot) {
-  return path26.relative(repoRoot, file).split(path26.sep).join("/");
+  return path27.relative(repoRoot, file).split(path27.sep).join("/");
 }
 function scriptHash(entry) {
   return crypto3.createHash("sha1").update(entry.source ?? "").digest("hex");
@@ -11779,6 +12098,7 @@ function createSink() {
     flake: null,
     pickOffered: false,
     userPick: null,
+    pause: null,
     locatorPages: new LocatorPageLog(),
     codeReach: null
   };
@@ -11795,11 +12115,11 @@ function configuredCodeReachRoots() {
   const raw = process.env.PIWI_CODE_REACH_ROOTS?.trim();
   if (!raw) return null;
   try {
-    const parsed = JSON.parse(raw);
-    if (Array.isArray(parsed)) return parsed.filter((r) => typeof r === "string" && r !== "");
+    const parsed2 = JSON.parse(raw);
+    if (Array.isArray(parsed2)) return parsed2.filter((r) => typeof r === "string" && r !== "");
   } catch {
   }
-  return raw.split(path27.delimiter).filter(Boolean);
+  return raw.split(path28.delimiter).filter(Boolean);
 }
 async function stopSinkCodeReach(sink, closing) {
   const session = sink.codeReach;
@@ -11814,7 +12134,7 @@ async function stopSinkCodeReach(sink, closing) {
     if (!entries) return;
     const info = sink.testInfo;
     const configFile = info?.config.configFile;
-    const configDir = configFile ? path27.dirname(configFile) : info?.config.rootDir ?? process.cwd();
+    const configDir = configFile ? path28.dirname(configFile) : info?.config.rootDir ?? process.cwd();
     session.files = await resolveCodeReach(
       entries,
       codeReachRoots(configDir, configuredCodeReachRoots()),
@@ -12233,6 +12553,53 @@ function recordLocatorPage(sink, page, locator, location, arrival) {
   } catch {
   }
 }
+function pausesAt(pause, callerLocation) {
+  return !pause.finished && (pause.next || pause.set.matches(callerLocation));
+}
+function locatorSource(target, method, args) {
+  try {
+    const text = String(target);
+    if (text && !text.startsWith("[object")) return text;
+  } catch {
+  }
+  return renderFailing({ method, args });
+}
+async function pauseBefore(sink, page, target, callerLocation, action, origin) {
+  const pause = sink.pause;
+  const testInfo = sink.testInfo;
+  if (!pause || !testInfo || !callerLocation) return;
+  pause.next = false;
+  try {
+    const locator = locatorSource(target, origin.method, origin.args);
+    const onPick = async (picked) => {
+      const pick = {
+        failing: { method: origin.method, args: origin.args, rendered: locator, location: callerLocation },
+        ...picked
+      };
+      applyPickToSnapshots(sink.capturedLocators, pick);
+      sink.probedLocations.add(callerLocation);
+      const place = callerLocation.slice(0, callerLocation.lastIndexOf(":"));
+      console.log(`[piwi] Locator picked at ${place}: ${picked.picked.locator}`);
+      await postPickToEditor(
+        process.env[PIWI_LOCAL_DEBUG_ENV.editorSend],
+        pickPayload(picked.picked.locator, callerLocation)
+      );
+    };
+    const choice = await internalCall(
+      page,
+      () => pauseHere(
+        page,
+        testInfo,
+        { location: callerLocation, action, locator, target },
+        { fn: probeElementAttrs, arg: CAPTURED_ATTRS_ARG },
+        onPick
+      )
+    );
+    if (choice === "step") pause.next = true;
+    else if (choice === "finish") pause.finished = true;
+  } catch {
+  }
+}
 function wrapLocator(page, locator, originMethod, originArgs) {
   return new Proxy(locator, {
     get(target, prop) {
@@ -12254,6 +12621,12 @@ function wrapLocator(page, locator, originMethod, originArgs) {
           const isNot = Boolean(callArgs[1]?.isNot);
           const callerLocation = sink ? captureCallerLocation() : null;
           if (sink) recordLocatorPage(sink, page, target, callerLocation, noteLocatorCall(page, EXPECT_METHOD, true));
+          if (sink?.pause && pausesAt(sink.pause, callerLocation)) {
+            await pauseBefore(sink, page, target, callerLocation, assertionLabel(expression, isNot), {
+              method: originMethod,
+              args: originArgs
+            });
+          }
           if (!sink || isNot || !EXPECT_CAPTURE_EXPRESSIONS.has(expression)) {
             return callMethod(target, prop, callArgs);
           }
@@ -12292,6 +12665,9 @@ function wrapLocator(page, locator, originMethod, originArgs) {
           args: originArgs,
           raw: `${originMethod}(${JSON.stringify(originArgs)})`
         };
+        if (sink.pause && pausesAt(sink.pause, callerLocation)) {
+          await pauseBefore(sink, page, target, callerLocation, String(prop), used);
+        }
         const alreadyProbed = callerLocation !== null && sink.probedLocations.has(callerLocation);
         let seq = -1;
         if (!alreadyProbed) {
@@ -12752,6 +13128,12 @@ var piwiFixtures = {
       if (conflict) throw new Error(conflict);
       const sink = createSink();
       sink.testInfo = testInfo;
+      const pauseSet = currentPauseSet();
+      if (pauseSet.size) {
+        const reason = pauseSkipReason(pauseGateFromTestInfo(testInfo));
+        if (reason) logPauseSkipOnce(reason);
+        else sink.pause = { set: pauseSet, next: false, finished: false };
+      }
       if (isFlakeMode()) {
         const plan = loadFlakePlan();
         const role = flakeRoleForTest(plan, {
@@ -12831,12 +13213,12 @@ function extendPiwiFixtures(test) {
 
 // src/internal/ai/ai-fixtures.ts
 var fs24 = __toESM(require("fs"));
-var path30 = __toESM(require("path"));
+var path31 = __toESM(require("path"));
 var import_test = require("@playwright/test");
 
 // src/internal/ai/artifact.ts
 var fs23 = __toESM(require("fs"));
-var path28 = __toESM(require("path"));
+var path29 = __toESM(require("path"));
 var ARTIFACT_VERSION = 1;
 var LOCATOR_METHOD_SET2 = new Set(LOCATOR_METHODS);
 var ACTION_METHOD_SET2 = new Set(ACTION_METHODS);
@@ -12940,7 +13322,7 @@ function writeEntry(file, entry) {
   const canonical = serializeEntry(entry);
   return withEntryLock(file, () => {
     if (fs23.existsSync(file) && fs23.readFileSync(file, "utf8") === canonical) return { written: false };
-    fs23.mkdirSync(path28.dirname(file), { recursive: true });
+    fs23.mkdirSync(path29.dirname(file), { recursive: true });
     const tmp = `${file}.${process.pid}.tmp`;
     fs23.writeFileSync(tmp, canonical);
     fs23.renameSync(tmp, file);
@@ -12949,7 +13331,7 @@ function writeEntry(file, entry) {
 }
 function withEntryLock(file, fn) {
   const lock = `${file}.lock`;
-  fs23.mkdirSync(path28.dirname(file), { recursive: true });
+  fs23.mkdirSync(path29.dirname(file), { recursive: true });
   const deadline = Date.now() + 5e3;
   for (; ; ) {
     try {
@@ -12978,7 +13360,7 @@ function withEntryLock(file, fn) {
 
 // src/internal/ai/keys.ts
 var crypto4 = __toESM(require("crypto"));
-var path29 = __toESM(require("path"));
+var path30 = __toESM(require("path"));
 var DEFAULT_AI_DIR = "__piwi__";
 function normalizeTemplate(template) {
   return template.trim().replace(/\s+/g, " ").toLowerCase();
@@ -12992,13 +13374,13 @@ function slug(text, maxLength = 40) {
   return (base || "x").slice(0, maxLength).replace(/-+$/g, "") || "x";
 }
 function entryDir(specFile, dir = DEFAULT_AI_DIR) {
-  return path29.join(path29.dirname(specFile), dir, path29.basename(specFile));
+  return path30.join(path30.dirname(specFile), dir, path30.basename(specFile));
 }
 function entryPath(params) {
   const basis = `${normalizeTemplate(params.testTitle)}::${normalizeTemplate(params.template)}`;
   const hash = hashTemplate(basis, params.ordinal ?? 0);
   const name = `${slug(params.testTitle)}.${slug(params.template)}.${hash}.json`;
-  return path29.join(entryDir(params.specFile, params.dir), name);
+  return path30.join(entryDir(params.specFile, params.dir), name);
 }
 function parseLocation2(location) {
   const match = /:(\d+):(\d+)$/.exec(location);
@@ -13178,9 +13560,9 @@ function renderSourceArg(arg) {
   if (Array.isArray(arg)) return `[${arg.map(renderSourceArg).join(", ")}]`;
   return `{ ${Object.entries(arg).map(([key, value]) => `${key}: ${renderSourceArg(value)}`).join(", ")} }`;
 }
-function locatorSource(loc) {
+function locatorSource2(loc) {
   const head = `${loc.method}(${loc.args.map(renderSourceArg).join(", ")})`;
-  const tail = (loc.chain ?? []).map(locatorSource).join(".");
+  const tail = (loc.chain ?? []).map(locatorSource2).join(".");
   return tail ? `${head}.${tail}` : head;
 }
 function describePostcondition(post) {
@@ -13512,18 +13894,18 @@ function testIdentity(testInfo) {
   return titles.length > 0 ? titles.join(" \u203A ") : testInfo.title;
 }
 function relativeToCwd(file) {
-  return path30.relative(process.cwd(), file).split(path30.sep).join("/");
+  return path31.relative(process.cwd(), file).split(path31.sep).join("/");
 }
 function recordIntents(intents, entry) {
   const add = (locator, kind) => {
     intents.set(`${entry.template}\0${locator}`, { template: entry.template, locator, kind });
   };
   if (entry.kind === "locator") {
-    add(locatorSource(entry.locator), "locator");
+    add(locatorSource2(entry.locator), "locator");
     return;
   }
-  for (const step of entry.steps) add(locatorSource(step.locator), "run");
-  if (entry.postcondition.locator) add(locatorSource(entry.postcondition.locator), "run");
+  for (const step of entry.steps) add(locatorSource2(step.locator), "run");
+  if (entry.postcondition.locator) add(locatorSource2(entry.postcondition.locator), "run");
 }
 function missMessage(template, testTitle, relPath) {
   return [