recovery-probe 1.0.0 → 1.1.0-preview.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/README.md +4 -2
  3. package/dist/cli/observe.mjs +1 -0
  4. package/dist/core/server.d.mts +3 -1
  5. package/dist/core/server.mjs +8 -0
  6. package/dist/targets/cdp-bridge/bridge.mjs +10 -1
  7. package/dist/targets/cdp-bridge/websocket.d.mts +6 -0
  8. package/dist/targets/cdp-bridge/websocket.mjs +29 -10
  9. package/dist/tools/mcp/server.mjs +12 -2
  10. package/dist/transports/http/observer.d.mts +4 -1
  11. package/dist/transports/http/observer.mjs +12 -2
  12. package/dist/transports/http/read-log.d.mts +22 -0
  13. package/dist/transports/http/read-log.mjs +36 -0
  14. package/dist/transports/net/control.mjs +7 -1
  15. package/dist/transports/net/rules.mjs +2 -1
  16. package/dist/workflows/observe/adapters.d.mts +3 -0
  17. package/dist/workflows/observe/adapters.mjs +7 -1
  18. package/dist/workflows/observe/capture.mjs +39 -52
  19. package/dist/workflows/observe/config.d.mts +2 -0
  20. package/dist/workflows/observe/config.mjs +6 -46
  21. package/dist/workflows/observe/operator.d.mts +13 -0
  22. package/dist/workflows/observe/operator.mjs +50 -0
  23. package/dist/workflows/observe/recorder.d.mts +11 -1
  24. package/dist/workflows/observe/recorder.mjs +39 -2
  25. package/dist/workflows/observe/report.d.mts +3 -0
  26. package/dist/workflows/observe/sample.d.mts +1 -0
  27. package/dist/workflows/observe/sample.mjs +1 -1
  28. package/dist/workflows/observe/slow-reads/bridge.d.mts +26 -0
  29. package/dist/workflows/observe/slow-reads/bridge.mjs +81 -0
  30. package/dist/workflows/observe/slow-reads/config.d.mts +13 -0
  31. package/dist/workflows/observe/slow-reads/config.mjs +26 -0
  32. package/dist/workflows/observe/slow-reads/evidence.d.mts +75 -0
  33. package/dist/workflows/observe/slow-reads/evidence.mjs +142 -0
  34. package/dist/workflows/observe/slow-reads/probe.d.mts +29 -0
  35. package/dist/workflows/observe/slow-reads/probe.mjs +54 -0
  36. package/dist/workflows/observe/slow-reads/renderer-load.d.mts +23 -0
  37. package/dist/workflows/observe/slow-reads/renderer-load.mjs +47 -0
  38. package/dist/workflows/observe/slow-reads/summary.d.mts +8 -0
  39. package/dist/workflows/observe/slow-reads/summary.mjs +61 -0
  40. package/dist/workflows/observe/summaries.mjs +1 -0
  41. package/dist/workflows/observe/target-config.d.mts +3 -0
  42. package/dist/workflows/observe/target-config.mjs +49 -0
  43. package/docs/android.md +2 -0
  44. package/docs/ipc.md +1 -1
  45. package/docs/net.md +3 -2
  46. package/docs/observe.md +54 -1
  47. package/package.json +3 -3
package/CHANGELOG.md CHANGED
@@ -4,6 +4,18 @@ All notable changes to Recovery Probe are documented here. The project follows [
4
4
 
5
5
  Version 0.2.0 is the first npm release. Earlier 0.1.x revisions were repository-only prototypes.
6
6
 
7
+ ## 1.1.0-preview.2 (2026-10-28)
8
+
9
+ - Reject browser-origin WebSocket connections and untrusted Host headers on the Android CDP bridge before opening an upstream connection. Validate the network proxy control API's Host header to block DNS rebinding.
10
+ - Bound complete inbound CDP WebSocket messages, including continuation frames, and close oversized messages with code 1009.
11
+ - Suppress MCP tool responses after cancellation and emit `structuredContent` only for object results.
12
+ - Match network host names with or without a final DNS dot. Document wildcard apex behavior, unrestricted local CONNECT tunneling, and the `webContents.send` scope of IPC push counting.
13
+
14
+ ## 1.1.0-preview.1 (2026-10-27)
15
+
16
+ - `observe` with `slowReads` explains slow screens over HTTP. For each read it records when it started and finished, how long the network took, when its content first showed, and how busy the page's main thread was in between. Optionally it also counts the requests waiting on a page bridge, such as an Android WebMessageListener object. A `SLOW_READ` lead says whether the time went to the network, to a busy main thread or to something else.
17
+ - With `slowReads`, a screen read that takes longer than 5 seconds no longer ends the capture, and HTTP captures can run for up to 10 minutes. IPC captures keep the 2-minute limit set by the development hook.
18
+
7
19
  ## 1.0.0 (2026-10-27)
8
20
 
9
21
  The first release with an explicit 1.x compatibility commitment. It removes the old command spellings and brings in everything since 0.6.0: the 0.7.0 and 0.8.0 previews below. The README defines the supported interfaces and experimental exceptions, and explains that failed checks can save unredacted screen-text quotes of up to 200 characters.
package/README.md CHANGED
@@ -1,8 +1,10 @@
1
1
  # Recovery Probe
2
2
 
3
- See what your app shows when a data request fails.
3
+ Stop assuming your code works. Test what actually happens.
4
4
 
5
- Most apps don't crash when a read fails. The list goes empty, the spinner never stops, or the screen keeps showing old data. There's no error and nothing in the logs, so it ships. Recovery Probe fails those reads on purpose, runs the same screen healthy for comparison, and tells you what changed.
5
+ Recovery Probe helps developers and AI coding agents discover bugs that ordinary tests can miss. It deliberately triggers failures in web and Electron applications, observes how the UI responds, and produces evidence you can use to reproduce, fix, and verify problems.
6
+
7
+ A failed request should not silently turn a populated screen into “No items found.” Recovery Probe helps you reproduce that failure and check whether the application recovers as expected.
6
8
 
7
9
  [![CI](https://github.com/BojanKovachki/recovery-probe/actions/workflows/validate.yml/badge.svg)](https://github.com/BojanKovachki/recovery-probe/actions/workflows/validate.yml)
8
10
  [![npm](https://img.shields.io/npm/v/recovery-probe.svg)](https://www.npmjs.com/package/recovery-probe)
@@ -39,6 +39,7 @@ const NAMED_FINDINGS = [
39
39
  'UNEXPECTED_ROW_STATE',
40
40
  'LOCAL_FILE_NOT_REPAIRED',
41
41
  'EXPECTATION_NOT_MET',
42
+ 'SLOW_READ',
42
43
  ];
43
44
  export async function observeMain(args) {
44
45
  if (!args.length || args.includes('--help')) {
@@ -1,4 +1,6 @@
1
- import type { Server } from 'node:http';
1
+ import type { IncomingMessage, Server } from 'node:http';
2
+ /** Reject DNS aliases and ambiguous authorities before exposing local controls. */
3
+ export declare function hasLoopbackHost(request: IncomingMessage): boolean;
2
4
  /** Listens on 127.0.0.1 and returns the port; port 0 picks a free one. */
3
5
  export declare function listenOnLoopback(server: Server, port: number): Promise<number>;
4
6
  /** Closes the server and the connections it still holds. */
@@ -1,3 +1,11 @@
1
+ /** Reject DNS aliases and ambiguous authorities before exposing local controls. */
2
+ export function hasLoopbackHost(request) {
3
+ const hosts = request.headersDistinct.host;
4
+ if (hosts?.length !== 1 || !request.socket.localPort)
5
+ return false;
6
+ const port = request.socket.localPort;
7
+ return hosts[0] === `127.0.0.1:${port}` || hosts[0] === `localhost:${port}`;
8
+ }
1
9
  /** Listens on 127.0.0.1 and returns the port; port 0 picks a free one. */
2
10
  export async function listenOnLoopback(server, port) {
3
11
  await new Promise((resolve, reject) => {
@@ -1,5 +1,5 @@
1
1
  import { createServer, } from 'node:http';
2
- import { closeServer, listenOnLoopback } from '../../core/server.mjs';
2
+ import { closeServer, hasLoopbackHost, listenOnLoopback, } from '../../core/server.mjs';
3
3
  import { BRIDGE_ID_BASE, TargetFilter } from './filter.mjs';
4
4
  import { acceptWebSocket } from './websocket.mjs';
5
5
  /** A page with nothing loaded, as Android keeps for a WebView that has no window yet. */
@@ -30,6 +30,10 @@ export async function startCdpBridge({ upstream, hide = isBlankPage, port = 0, }
30
30
  };
31
31
  }
32
32
  async function answer(context, request, response) {
33
+ if (!hasLoopbackHost(request)) {
34
+ response.writeHead(403).end('Forbidden');
35
+ return;
36
+ }
33
37
  try {
34
38
  // Clients ask for both /json/version and /json/version/.
35
39
  const path = new URL(request.url ?? '/', 'http://bridge').pathname.replace(/\/$/, '');
@@ -64,6 +68,11 @@ async function visibleTargets(context) {
64
68
  }
65
69
  /** Connects one client to the device's browser endpoint, through a target filter. */
66
70
  function bridgeClient(context, peers, request, socket) {
71
+ // Native CDP clients send no Origin. Even an empty or null browser origin is denied.
72
+ if (!hasLoopbackHost(request) || request.headers.origin !== undefined) {
73
+ socket.end('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n');
74
+ return;
75
+ }
67
76
  if (new URL(request.url ?? '/', 'http://bridge').pathname !==
68
77
  '/devtools/browser') {
69
78
  socket.end('HTTP/1.1 404 Not Found\r\n\r\n');
@@ -6,3 +6,9 @@ export interface WebSocketPeer {
6
6
  }
7
7
  /** Accepts a WebSocket upgrade (RFC 6455) and delivers its text messages. */
8
8
  export declare function acceptWebSocket(request: IncomingMessage, socket: Duplex, onMessage: (text: string) => void, onClose: () => void): WebSocketPeer;
9
+ export declare class ServerWebSocket implements WebSocketPeer {
10
+ #private;
11
+ constructor(socket: Duplex, onMessage: (text: string) => void, onClose: () => void, maxMessage?: number);
12
+ readonly send: (text: string) => void;
13
+ readonly close: (code?: number) => void;
14
+ }
@@ -27,13 +27,15 @@ function payloadLength(buffered) {
27
27
  return { length, offset: 2 };
28
28
  }
29
29
  /** The first whole frame and its size in bytes, or undefined until it has all arrived. */
30
- function readFrame(buffered) {
30
+ function readFrame(buffered, remaining) {
31
31
  if (buffered.length < 2)
32
32
  return undefined;
33
33
  const header = payloadLength(buffered);
34
34
  if (!header)
35
35
  return undefined;
36
- if (header.length > MAX_MESSAGE)
36
+ const opcode = buffered[0] & 0x0f;
37
+ const limit = opcode < 0x8 ? remaining : 125;
38
+ if (header.length > limit)
37
39
  return 'too-large';
38
40
  const masked = (buffered[1] & 0x80) !== 0;
39
41
  const start = header.offset + (masked ? 4 : 0);
@@ -57,22 +59,26 @@ export function acceptWebSocket(request, socket, onMessage, onClose) {
57
59
  `Sec-WebSocket-Accept: ${accept}\r\n\r\n`);
58
60
  return new ServerWebSocket(socket, onMessage, onClose);
59
61
  }
60
- class ServerWebSocket {
62
+ export class ServerWebSocket {
61
63
  #socket;
62
64
  #onMessage;
63
65
  #onClose;
66
+ #maxMessage;
64
67
  #closed = false;
65
68
  #buffered = Buffer.alloc(0);
66
69
  #message = [];
67
- constructor(socket, onMessage, onClose) {
70
+ #messageBytes = 0;
71
+ constructor(socket, onMessage, onClose, maxMessage = MAX_MESSAGE) {
68
72
  this.#socket = socket;
69
73
  this.#onMessage = onMessage;
70
74
  this.#onClose = onClose;
75
+ this.#maxMessage = maxMessage;
71
76
  socket.on('data', (chunk) => this.#receive(chunk));
72
77
  socket.on('close', () => {
73
78
  if (this.#closed)
74
79
  return;
75
80
  this.#closed = true;
81
+ this.#clear();
76
82
  this.#onClose();
77
83
  });
78
84
  socket.on('error', () => socket.destroy());
@@ -81,11 +87,14 @@ class ServerWebSocket {
81
87
  if (!this.#closed)
82
88
  this.#frame(0x1, Buffer.from(text));
83
89
  };
84
- close = () => {
90
+ close = (code = 1000) => {
85
91
  if (this.#closed)
86
92
  return;
87
93
  this.#closed = true;
88
- this.#frame(0x8, Buffer.from([0x03, 0xe8])); // 1000: normal closure
94
+ const payload = Buffer.alloc(2);
95
+ payload.writeUInt16BE(code);
96
+ this.#frame(0x8, payload);
97
+ this.#clear();
89
98
  this.#socket.end();
90
99
  this.#onClose();
91
100
  };
@@ -93,27 +102,37 @@ class ServerWebSocket {
93
102
  this.#socket.write(Buffer.concat([frameHeader(opcode, payload.length), payload]));
94
103
  }
95
104
  #receive(chunk) {
105
+ if (this.#closed)
106
+ return;
96
107
  this.#buffered = Buffer.concat([this.#buffered, chunk]);
97
- for (;;) {
98
- const read = readFrame(this.#buffered);
108
+ while (!this.#closed) {
109
+ const read = readFrame(this.#buffered, this.#maxMessage - this.#messageBytes);
99
110
  if (read === undefined)
100
111
  return;
101
112
  if (read === 'too-large')
102
- return this.close();
113
+ return this.close(1009);
103
114
  this.#buffered = this.#buffered.subarray(read.size);
104
115
  if (read.frame.opcode === 0x8)
105
116
  return this.close();
106
117
  this.#handle(read.frame);
107
118
  }
108
119
  }
120
+ #clear() {
121
+ this.#buffered = Buffer.alloc(0);
122
+ this.#message = [];
123
+ this.#messageBytes = 0;
124
+ }
109
125
  #handle({ fin, opcode, payload }) {
110
126
  if (opcode === 0x9)
111
127
  this.#frame(0xa, payload);
112
128
  else if (opcode === 0x1 || opcode === 0x2 || opcode === 0x0) {
113
- this.#message.push(payload);
129
+ if (payload.length)
130
+ this.#message.push(payload);
131
+ this.#messageBytes += payload.length;
114
132
  if (fin) {
115
133
  const text = Buffer.concat(this.#message).toString('utf8');
116
134
  this.#message = [];
135
+ this.#messageBytes = 0;
117
136
  this.#onMessage(text);
118
137
  }
119
138
  }
@@ -121,13 +121,23 @@ class McpServer {
121
121
  this.#running.set(id, controller);
122
122
  try {
123
123
  const result = await tool.run((params.arguments ?? {}), { signal: controller.signal });
124
+ if (controller.signal.aborted)
125
+ return undefined;
124
126
  return reply(id, {
125
- content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
126
- structuredContent: result,
127
+ content: [
128
+ { type: 'text', text: JSON.stringify(result, null, 2) ?? 'null' },
129
+ ],
130
+ ...(result !== null &&
131
+ typeof result === 'object' &&
132
+ !Array.isArray(result)
133
+ ? { structuredContent: result }
134
+ : {}),
127
135
  isError: false,
128
136
  });
129
137
  }
130
138
  catch (error) {
139
+ if (controller.signal.aborted)
140
+ return undefined;
131
141
  // A tool failure is a result the model can read and act on, not a protocol error.
132
142
  return reply(id, {
133
143
  content: [{ type: 'text', text: error.message }],
@@ -21,6 +21,8 @@ export interface HttpObserverOptions {
21
21
  times?: number;
22
22
  /** Matching reads that pass before the first fault: 1 fails the 2nd read. */
23
23
  skip?: number;
24
+ /** Keep a record per read of `endpoint`. Only for runs without a fault. */
25
+ logReads?: boolean;
24
26
  }
25
27
  /** A request the page made, and whether it could be or was selected for a fault. */
26
28
  export interface ReadCoverage {
@@ -34,7 +36,7 @@ export interface ReadCoverage {
34
36
  export declare function observeHttp(page: Page, options: HttpObserverOptions): Promise<HttpObserver>;
35
37
  declare class HttpObserver {
36
38
  #private;
37
- constructor(page: Page, { endpoint, requiredEndpoints, fault, times, skip, }: HttpObserverOptions);
39
+ constructor(page: Page, { endpoint, requiredEndpoints, fault, times, skip, logReads, }: HttpObserverOptions);
38
40
  attach(): Promise<void>;
39
41
  snapshot(): {
40
42
  startedAt: number;
@@ -49,6 +51,7 @@ declare class HttpObserver {
49
51
  channels: Record<string, ReadChannelStats>;
50
52
  };
51
53
  coverage(): ReadCoverage[];
54
+ readLog(): import("./read-log.mjs").ReadLogSnapshot | undefined;
52
55
  /** Stops faulting and waits for the injected responses. */
53
56
  disarm(): Promise<void>;
54
57
  /** Disarms, then stops listening. */
@@ -1,6 +1,7 @@
1
1
  import { performance } from 'node:perf_hooks';
2
2
  import { pageIdentity } from '../../core/urls.mjs';
3
3
  import { fulfillFault } from './route.mjs';
4
+ import { ReadLog } from './read-log.mjs';
4
5
  const MAX_COVERAGE = 100;
5
6
  const emptyRow = () => ({
6
7
  calls: 0,
@@ -32,6 +33,7 @@ class HttpObserver {
32
33
  #requests = new Map();
33
34
  #coverage = new Map();
34
35
  #operations = new Set();
36
+ #readLog;
35
37
  #skipped = 0;
36
38
  #reserved = 0;
37
39
  #applied = 0;
@@ -40,7 +42,7 @@ class HttpObserver {
40
42
  #active = true;
41
43
  #injectionError = false;
42
44
  #routed;
43
- constructor(page, { endpoint, requiredEndpoints = [], fault, times = 1, skip = 0, }) {
45
+ constructor(page, { endpoint, requiredEndpoints = [], fault, times = 1, skip = 0, logReads = false, }) {
44
46
  this.#page = page;
45
47
  this.#endpoint = endpoint;
46
48
  this.#fault = fault;
@@ -49,6 +51,7 @@ class HttpObserver {
49
51
  this.#channels = Object.fromEntries([endpoint, ...requiredEndpoints].map((e) => [e, emptyRow()]));
50
52
  this.#startedAt = Date.now();
51
53
  this.#routed = Boolean(fault);
54
+ this.#readLog = logReads && !fault ? new ReadLog() : undefined;
52
55
  }
53
56
  async attach() {
54
57
  const page = this.#page;
@@ -82,6 +85,9 @@ class HttpObserver {
82
85
  coverage() {
83
86
  return [...this.#coverage.values()];
84
87
  }
88
+ readLog() {
89
+ return this.#readLog?.snapshot();
90
+ }
85
91
  /** Stops faulting and waits for the injected responses. */
86
92
  async disarm() {
87
93
  this.#active = false;
@@ -132,12 +138,14 @@ class HttpObserver {
132
138
  row.pending++;
133
139
  row.firstReadAt ??= Date.now();
134
140
  row.lastReadAt = Date.now();
141
+ const target = url === this.#endpoint;
135
142
  this.#requests.set(r, {
136
143
  row,
137
144
  start: performance.now(),
138
145
  injected: false,
139
146
  afterFault: this.#reserved === this.#times && this.#injectedAt !== null,
140
- target: url === this.#endpoint,
147
+ target,
148
+ record: target ? this.#readLog?.start() : undefined,
141
149
  });
142
150
  }
143
151
  #cover(method, url) {
@@ -171,6 +179,8 @@ class HttpObserver {
171
179
  row.pending--;
172
180
  if (meta.injected)
173
181
  return;
182
+ if (meta.record)
183
+ this.#readLog.finish(meta.record, r, response);
174
184
  const completed = Date.now();
175
185
  row.firstCompletedAt ??= completed;
176
186
  row.lastCompletedAt = completed;
@@ -0,0 +1,22 @@
1
+ import type { Request, Response } from 'playwright';
2
+ /** One read of the selected endpoint: when it started and finished, and how. */
3
+ export interface ReadRecord {
4
+ startedAt: number;
5
+ completedAt: number | null;
6
+ status: number | null;
7
+ outcome: 'pending' | 'success' | 'error' | 'failed';
8
+ /** Request start to the last response byte, as the browser timed it. */
9
+ networkMs: number | null;
10
+ }
11
+ export interface ReadLogSnapshot {
12
+ reads: ReadRecord[];
13
+ truncated: boolean;
14
+ }
15
+ /** Keeps a record per read, so a slow read can be told apart from a slow screen. */
16
+ export declare class ReadLog {
17
+ #private;
18
+ /** Starts a record, or returns undefined once the log is full. */
19
+ start(): ReadRecord | undefined;
20
+ finish(record: ReadRecord, request: Request, response: Response | null): void;
21
+ snapshot(): ReadLogSnapshot;
22
+ }
@@ -0,0 +1,36 @@
1
+ const MAX_READS = 500;
2
+ /** Keeps a record per read, so a slow read can be told apart from a slow screen. */
3
+ export class ReadLog {
4
+ #reads = [];
5
+ #truncated = false;
6
+ /** Starts a record, or returns undefined once the log is full. */
7
+ start() {
8
+ if (this.#reads.length >= MAX_READS) {
9
+ this.#truncated = true;
10
+ return undefined;
11
+ }
12
+ const record = {
13
+ startedAt: Date.now(),
14
+ completedAt: null,
15
+ status: null,
16
+ outcome: 'pending',
17
+ networkMs: null,
18
+ };
19
+ this.#reads.push(record);
20
+ return record;
21
+ }
22
+ finish(record, request, response) {
23
+ record.completedAt = Date.now();
24
+ record.status = response?.status() ?? null;
25
+ record.outcome = !response ? 'failed' : response.ok() ? 'success' : 'error';
26
+ record.networkMs = networkMs(request);
27
+ }
28
+ snapshot() {
29
+ return { reads: structuredClone(this.#reads), truncated: this.#truncated };
30
+ }
31
+ }
32
+ // Timing fields are -1 when the browser did not measure them, for example a cache hit.
33
+ function networkMs(request) {
34
+ const { responseEnd } = request.timing();
35
+ return responseEnd >= 0 ? Math.round(responseEnd) : null;
36
+ }
@@ -1,3 +1,4 @@
1
+ import { hasLoopbackHost } from '../../core/server.mjs';
1
2
  import { CONTROL_HEADER, CONTROL_PATH } from './client.mjs';
2
3
  const MAX_CONTROL_BODY = 64 * 1024;
3
4
  const failure = (message, status) => Object.assign(new Error(message), { status });
@@ -23,7 +24,12 @@ export function controlListener(handle) {
23
24
  response.writeHead(501).end('Recovery Probe tunnels HTTPS (CONNECT) only');
24
25
  return;
25
26
  }
26
- // A web page cannot send this header without a preflight, which is never answered.
27
+ // A same-origin page after DNS rebinding can send the control header too.
28
+ if (!hasLoopbackHost(request)) {
29
+ reply(403, { error: 'Use the proxy loopback host and port' });
30
+ return;
31
+ }
32
+ // Other web pages cannot send this header without a preflight, never answered here.
27
33
  if (request.headers[CONTROL_HEADER] !== 'network') {
28
34
  reply(403, { error: `Send the ${CONTROL_HEADER}: network header` });
29
35
  return;
@@ -3,7 +3,8 @@ import { ensure, isNonEmptyString } from '../../core/validate.mjs';
3
3
  const FAULTS = new Set(['refuse', 'reset', 'stall', 'delay']);
4
4
  const isWholeNumber = (value) => Number.isInteger(value) && value >= 0;
5
5
  export function hostMatches(pattern, host) {
6
- const name = host.toLowerCase();
6
+ const name = host.toLowerCase().replace(/\.$/, '');
7
+ pattern = pattern.toLowerCase().replace(/\.$/, '');
7
8
  if (pattern === '*')
8
9
  return true;
9
10
  if (pattern.startsWith('*.'))
@@ -3,11 +3,14 @@ import type { IpcInspector } from '../../transports/ipc/inspector.mjs';
3
3
  import type { ObservationConfig } from './config.mjs';
4
4
  import type { ReadSnapshot } from './reads.mjs';
5
5
  import type { ObservationMetadata } from './report.mjs';
6
+ import type { ReadLogSnapshot } from '../../transports/http/read-log.mjs';
6
7
  export interface ObservationAdapter {
7
8
  start(): Promise<void>;
8
9
  snapshot(): ReadSnapshot | Promise<ReadSnapshot>;
9
10
  stop(): Promise<Record<string, unknown> | undefined>;
10
11
  metadata?(): ObservationMetadata['ipcHook'];
12
+ /** A record per read, when the transport keeps one. */
13
+ readLog?(): ReadLogSnapshot | undefined;
11
14
  }
12
15
  export declare function ipcObservationAdapter(control: IpcInspector, config: ObservationConfig, senderId: number): ObservationAdapter;
13
16
  export declare function httpObservationAdapter(page: Page, config: ObservationConfig): ObservationAdapter;
@@ -94,11 +94,17 @@ export function httpObservationAdapter(page, config) {
94
94
  let observer;
95
95
  return {
96
96
  async start() {
97
- observer = await observeHttp(page, { endpoint: config.endpoint });
97
+ observer = await observeHttp(page, {
98
+ endpoint: config.endpoint,
99
+ logReads: Boolean(config.slowReads),
100
+ });
98
101
  },
99
102
  snapshot() {
100
103
  return observer.snapshot();
101
104
  },
105
+ readLog() {
106
+ return observer?.readLog();
107
+ },
102
108
  async stop() {
103
109
  await observer?.stop();
104
110
  return { transport: 'http', listenersDetached: true };
@@ -7,10 +7,11 @@ import { observationConfig } from './config.mjs';
7
7
  import { installObserverKit, removeObserverKit } from './kit.mjs';
8
8
  import { pageReadInput, pageSelectors } from './page-input.mjs';
9
9
  import { ObservationRecorder } from './recorder.mjs';
10
+ import { OperatorRun } from './operator.mjs';
10
11
  import { summarizeRows } from './rows.mjs';
12
+ import { SlowReadProbe } from './slow-reads/probe.mjs';
11
13
  import { boundedUiRead } from './ui-read.mjs';
12
14
  const MAX_INTERVALS = 50;
13
- const OPERATOR_STOP_MS = 5000;
14
15
  /**
15
16
  * Observe only. No reload, navigation, routing, focus changes or final UI reset.
16
17
  * An optional `operator` function may act on the app (for example explicit --steps); it
@@ -28,8 +29,8 @@ class Capture {
28
29
  #recorder;
29
30
  #kitToken = randomUUID();
30
31
  #readInput;
31
- #markerRequests = [];
32
- #operatorAbort = new AbortController();
32
+ #operator = new OperatorRun();
33
+ #slowProbe;
33
34
  #started = 0;
34
35
  /** Set once the adapter is reading; the capture has a clock from then on. */
35
36
  #clock;
@@ -37,7 +38,6 @@ class Capture {
37
38
  #pageErrors = 0;
38
39
  #newDocument = false;
39
40
  #adapterStarted = false;
40
- #operatorRun;
41
41
  #elapsed = () => Math.round(performance.now() - this.#started);
42
42
  #countPageError = () => {
43
43
  this.#pageErrors++;
@@ -53,6 +53,9 @@ class Capture {
53
53
  this.#hooks = hooks;
54
54
  this.#recorder = new ObservationRecorder(config);
55
55
  this.#readInput = pageReadInput(config, this.#kitToken);
56
+ this.#slowProbe = config.slowReads
57
+ ? new SlowReadProbe(page, config.slowReads, this.#kitToken)
58
+ : undefined;
56
59
  }
57
60
  async run() {
58
61
  const report = this.#recorder.report;
@@ -78,6 +81,7 @@ class Capture {
78
81
  async #start() {
79
82
  const report = this.#recorder.report;
80
83
  await this.#installKit();
84
+ await this.#slowProbe?.start();
81
85
  this.#page.on('pageerror', this.#countPageError);
82
86
  this.#page.on('domcontentloaded', this.#noteDocumentLoad);
83
87
  this.#adapterStarted = true;
@@ -89,7 +93,7 @@ class Capture {
89
93
  report.startedAt = this.#lastSnapshot.startedAt;
90
94
  this.#recorder.openInterval(this.#lastSnapshot, this.#elapsed());
91
95
  await this.#hooks.onReady?.();
92
- this.#startOperator();
96
+ this.#operator.start(this.#hooks.operator, this.#elapsed);
93
97
  }
94
98
  /** One renderer call installs the kit and validates every selector, mounted or not. */
95
99
  async #installKit() {
@@ -98,23 +102,6 @@ class Capture {
98
102
  const validate = pageSelectors(this.#config);
99
103
  await boundedUiRead(() => this.#page.evaluate(installObserverKit, { token, actions, validate }), this.#hooks.signal);
100
104
  }
101
- #startOperator() {
102
- const operator = this.#hooks.operator;
103
- if (!operator)
104
- return;
105
- const abort = this.#operatorAbort;
106
- const mark = () => new Promise((resolve) => this.#markerRequests.push({ resolve }));
107
- this.#operatorRun = Promise.resolve()
108
- .then(() => operator({ mark, signal: abort.signal, elapsed: this.#elapsed }))
109
- .then((steps) => ({
110
- status: 'complete',
111
- ...(Array.isArray(steps) ? { steps } : {}),
112
- }), (error) => ({
113
- status: abort.signal.aborted ? 'stopped' : 'failed',
114
- error: error.message,
115
- ...(Array.isArray(error.results) ? { steps: error.results } : {}),
116
- }));
117
- }
118
105
  async #sampleUntilDone() {
119
106
  const report = this.#recorder.report;
120
107
  const { observationMs, sampleMs } = this.#config;
@@ -135,13 +122,8 @@ class Capture {
135
122
  await sleep(waitMs);
136
123
  }
137
124
  }
138
- #nextMarker() {
139
- if (this.#markerRequests.length)
140
- return this.#markerRequests.shift();
141
- return this.#hooks.takeMarker?.() ? {} : null;
142
- }
143
125
  async #openMarkedInterval() {
144
- const marker = this.#nextMarker();
126
+ const marker = this.#operator.nextMarker(this.#hooks.takeMarker);
145
127
  if (!marker)
146
128
  return;
147
129
  if (this.#recorder.report.intervals.length >= MAX_INTERVALS)
@@ -160,7 +142,16 @@ class Capture {
160
142
  const before = await this.#adapter.snapshot();
161
143
  const uiStart = performance.now();
162
144
  const fromMs = this.#elapsed();
163
- const { rendererReadMs, rows, actions, ...raw } = await boundedUiRead(() => this.#page.evaluate(readRegion, this.#readInput), this.#hooks.signal);
145
+ // Slow-read evidence waits out a busy renderer: that wait is what it measures.
146
+ const timeoutMs = c.slowReads ? c.observationMs : undefined;
147
+ const signal = this.#hooks.signal;
148
+ const slowProbe = this.#slowProbe;
149
+ const [{ rendererReadMs, rows, actions, ...raw }, load] = await Promise.all([
150
+ boundedUiRead(() => this.#page.evaluate(readRegion, this.#readInput), signal, timeoutMs),
151
+ slowProbe
152
+ ? boundedUiRead(() => slowProbe.read(), signal, timeoutMs)
153
+ : null,
154
+ ]);
164
155
  const summarizeStart = performance.now();
165
156
  // A read without text or content (an absent or hidden region) summarizes to itself.
166
157
  const ui = summarizeRegion(raw);
@@ -175,6 +166,7 @@ class Capture {
175
166
  ui,
176
167
  rows: summarizedRows,
177
168
  actions,
169
+ load,
178
170
  phases: {
179
171
  beforeSnapshotMs: uiStart - beforeStart,
180
172
  uiRoundTripMs: summarizeStart - uiStart,
@@ -193,38 +185,33 @@ class Capture {
193
185
  }
194
186
  async #finish() {
195
187
  const recorder = this.#recorder;
196
- this.#operatorAbort.abort();
197
- for (const pending of this.#markerRequests)
198
- pending.resolve?.(null);
199
- await this.#finishOperator();
188
+ const operator = await this.#operator.finish();
189
+ if (operator) {
190
+ recorder.report.operator = operator;
191
+ if (operator.status !== 'complete')
192
+ recorder.gap('OPERATOR_STEPS_INCOMPLETE');
193
+ }
200
194
  const elapsedMs = this.#clock ? this.#elapsed() : 0;
201
195
  if (recorder.intervalOpen)
202
196
  recorder.closeInterval(this.#lastSnapshot, elapsedMs);
203
197
  recorder.endSampling(elapsedMs, this.#lastSnapshot);
204
198
  this.#page.off('pageerror', this.#countPageError);
205
199
  this.#page.off('domcontentloaded', this.#noteDocumentLoad);
200
+ const readLog = this.#adapter.readLog?.();
201
+ await this.#slowProbe?.stop();
206
202
  await this.#removeKit();
207
203
  await this.#stopAdapter();
208
- recorder.conclude();
204
+ recorder.conclude(this.#slowReadsEnd(readLog));
209
205
  }
210
- async #finishOperator() {
211
- if (!this.#operatorRun)
212
- return;
213
- let timer;
214
- // An operator that ignores the stop signal must not hold cleanup hostage.
215
- const outcome = await Promise.race([
216
- this.#operatorRun,
217
- new Promise((resolve) => {
218
- timer = setTimeout(() => resolve({
219
- status: 'stopped',
220
- error: `Operator did not stop within ${OPERATOR_STOP_MS} ms`,
221
- }), OPERATOR_STOP_MS);
222
- }),
223
- ]);
224
- this.#recorder.report.operator = outcome;
225
- clearTimeout(timer);
226
- if (outcome.status !== 'complete')
227
- this.#recorder.gap('OPERATOR_STEPS_INCOMPLETE');
206
+ #slowReadsEnd(readLog) {
207
+ const probe = this.#slowProbe;
208
+ if (!probe || !this.#clock)
209
+ return undefined;
210
+ return {
211
+ readLog,
212
+ probe: probe.status,
213
+ startedEpoch: this.#clock.startedEpoch,
214
+ };
228
215
  }
229
216
  // Bounded: a replaced or unresponsive document must not delay owned IPC cleanup.
230
217
  async #removeKit() {
@@ -1,5 +1,6 @@
1
1
  import { type SelectorSpec } from '../../core/selector.mjs';
2
2
  import type { ObservedActionConfig } from './kit.mjs';
3
+ import { type SlowReadsConfig } from './slow-reads/config.mjs';
3
4
  export interface RowsConfig {
4
5
  selector: SelectorSpec;
5
6
  key?: SelectorSpec;
@@ -31,6 +32,7 @@ export interface ObservationConfig {
31
32
  contentSelector: SelectorSpec;
32
33
  rows?: RowsConfig;
33
34
  actions?: ObservedActionConfig[];
35
+ slowReads?: SlowReadsConfig;
34
36
  lagThresholdMs: number;
35
37
  minUnchangedReads: number;
36
38
  detail: 'content' | 'region';