recovery-probe 1.0.0 → 1.1.0-preview.1

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 (36) hide show
  1. package/CHANGELOG.md +5 -0
  2. package/dist/cli/observe.mjs +1 -0
  3. package/dist/transports/http/observer.d.mts +4 -1
  4. package/dist/transports/http/observer.mjs +12 -2
  5. package/dist/transports/http/read-log.d.mts +22 -0
  6. package/dist/transports/http/read-log.mjs +36 -0
  7. package/dist/workflows/observe/adapters.d.mts +3 -0
  8. package/dist/workflows/observe/adapters.mjs +7 -1
  9. package/dist/workflows/observe/capture.mjs +39 -52
  10. package/dist/workflows/observe/config.d.mts +2 -0
  11. package/dist/workflows/observe/config.mjs +6 -46
  12. package/dist/workflows/observe/operator.d.mts +13 -0
  13. package/dist/workflows/observe/operator.mjs +50 -0
  14. package/dist/workflows/observe/recorder.d.mts +11 -1
  15. package/dist/workflows/observe/recorder.mjs +39 -2
  16. package/dist/workflows/observe/report.d.mts +3 -0
  17. package/dist/workflows/observe/sample.d.mts +1 -0
  18. package/dist/workflows/observe/sample.mjs +1 -1
  19. package/dist/workflows/observe/slow-reads/bridge.d.mts +26 -0
  20. package/dist/workflows/observe/slow-reads/bridge.mjs +81 -0
  21. package/dist/workflows/observe/slow-reads/config.d.mts +13 -0
  22. package/dist/workflows/observe/slow-reads/config.mjs +26 -0
  23. package/dist/workflows/observe/slow-reads/evidence.d.mts +75 -0
  24. package/dist/workflows/observe/slow-reads/evidence.mjs +142 -0
  25. package/dist/workflows/observe/slow-reads/probe.d.mts +29 -0
  26. package/dist/workflows/observe/slow-reads/probe.mjs +54 -0
  27. package/dist/workflows/observe/slow-reads/renderer-load.d.mts +23 -0
  28. package/dist/workflows/observe/slow-reads/renderer-load.mjs +47 -0
  29. package/dist/workflows/observe/slow-reads/summary.d.mts +8 -0
  30. package/dist/workflows/observe/slow-reads/summary.mjs +61 -0
  31. package/dist/workflows/observe/summaries.mjs +1 -0
  32. package/dist/workflows/observe/target-config.d.mts +3 -0
  33. package/dist/workflows/observe/target-config.mjs +49 -0
  34. package/docs/android.md +1 -0
  35. package/docs/observe.md +52 -1
  36. package/package.json +2 -2
package/CHANGELOG.md CHANGED
@@ -4,6 +4,11 @@ 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.1 (2026-10-27)
8
+
9
+ - `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.
10
+ - 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.
11
+
7
12
  ## 1.0.0 (2026-10-27)
8
13
 
9
14
  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.
@@ -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')) {
@@ -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
+ }
@@ -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';
@@ -1,6 +1,7 @@
1
1
  import { ensure, ensureRanges, isIntegerIn, isNonEmptyString, isRecord, isUnique, withDefaults, } from '../../core/validate.mjs';
2
2
  import { selectorSpec } from '../../core/selector.mjs';
3
- const LABEL = /^[\w.:/-]{1,100}$/;
3
+ import { slowReadsConfig } from './slow-reads/config.mjs';
4
+ import { hasOnlyKeys, validateHttpTarget, validateIpcTarget, } from './target-config.mjs';
4
5
  const NAME = /^[\w.-]{1,40}$/;
5
6
  /** Every state label a row can have besides 'none' and 'other'. */
6
7
  export const stateLabels = (r) => [
@@ -21,6 +22,7 @@ const DEFAULTS = {
21
22
  contentSelector: undefined,
22
23
  rows: undefined,
23
24
  actions: undefined,
25
+ slowReads: undefined,
24
26
  lagThresholdMs: 2000,
25
27
  minUnchangedReads: 2,
26
28
  detail: 'content',
@@ -28,7 +30,7 @@ const DEFAULTS = {
28
30
  sampleMs: 100,
29
31
  };
30
32
  const RANGES = [
31
- ['observationMs', 500, 120000],
33
+ ['observationMs', 500, 600000],
32
34
  ['sampleMs', 50, 1000],
33
35
  ['lagThresholdMs', 500, 60000],
34
36
  ['minUnchangedReads', 1, 20],
@@ -47,6 +49,8 @@ export function observationConfig(input) {
47
49
  c.rows = rowsConfig(c.rows);
48
50
  if (c.actions !== undefined)
49
51
  c.actions = actionsConfig(c.actions);
52
+ if (c.slowReads !== undefined)
53
+ c.slowReads = slowReadsConfig(c.slowReads);
50
54
  if (c.transport === 'http')
51
55
  validateHttpTarget(c);
52
56
  else
@@ -57,10 +61,6 @@ const isLoopbackDevtools = (url) => ['http:', 'ws:'].includes(url.protocol) &&
57
61
  ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname) &&
58
62
  !url.username &&
59
63
  !url.password;
60
- // Arrays pass too; the checks that follow it reject them.
61
- const hasOnlyKeys = (value, keys) => Boolean(value) &&
62
- typeof value === 'object' &&
63
- Object.keys(value).every((key) => keys.includes(key));
64
64
  function actionsConfig(value) {
65
65
  ensure(Array.isArray(value) && value.length > 0 && value.length <= 20, 'actions must list 1–20 { name, selector } entries');
66
66
  const actions = value.map((action, i) => {
@@ -74,46 +74,6 @@ function actionsConfig(value) {
74
74
  ensure(isUnique(actions.map((action) => action.name)), 'action names must be unique');
75
75
  return actions;
76
76
  }
77
- function validateHttpTarget(c) {
78
- const url = new URL(c.endpoint);
79
- ensure(['http:', 'https:'].includes(url.protocol) &&
80
- !url.username &&
81
- !url.password &&
82
- !url.search &&
83
- !url.hash, 'endpoint must be HTTP(S) origin/path without credentials, query or fragment');
84
- c.endpoint = url.href;
85
- ensure(c.channel === undefined &&
86
- c.methods === undefined &&
87
- c.dataEvents === undefined, 'channel, methods and dataEvents are only supported with IPC');
88
- }
89
- function validateIpcTarget(c) {
90
- ensure(isNonEmptyString(c.channel), 'channel is required');
91
- ensure(c.endpoint === undefined && c.page === undefined && c.pageUrl === undefined, 'IPC selects the window owned by its development hook');
92
- if (c.methods !== undefined)
93
- c.methods = labels(c.methods, 'methods');
94
- if (c.dataEvents !== undefined)
95
- c.dataEvents = dataEventsConfig(c.dataEvents);
96
- }
97
- function dataEventsConfig(value) {
98
- const message = 'dataEvents must be { channel, methods? }';
99
- ensure(hasOnlyKeys(value, ['channel', 'methods']), message);
100
- const events = value;
101
- ensure(isNonEmptyString(events.channel), message);
102
- return {
103
- channel: events.channel,
104
- ...(events.methods === undefined
105
- ? {}
106
- : { methods: labels(events.methods, 'dataEvents.methods') }),
107
- };
108
- }
109
- function labels(value, key) {
110
- ensure(Array.isArray(value) &&
111
- value.length > 0 &&
112
- value.length <= 50 &&
113
- value.every((v) => typeof v === 'string' && LABEL.test(v)) &&
114
- isUnique(value), `${key} must list 1–50 unique labels matching ${LABEL}`);
115
- return [...value];
116
- }
117
77
  const ROW_KEYS = new Set([
118
78
  'selector',
119
79
  'key',
@@ -0,0 +1,13 @@
1
+ import type { ObservationHooks } from './capture.mjs';
2
+ import type { ObservationOperator } from './report.mjs';
3
+ /** Runs the optional operator (for example --steps) beside the capture, with its interval markers. */
4
+ export declare class OperatorRun {
5
+ #private;
6
+ start(operator: ObservationHooks['operator'], elapsed: () => number): void;
7
+ /** The next interval to open: one the operator asked for, or one `takeMarker` reports. */
8
+ nextMarker(takeMarker: ObservationHooks['takeMarker']): {
9
+ resolve?: (index: number | null) => void;
10
+ } | null | undefined;
11
+ /** Stops the operator and returns its outcome, or undefined when there was none. */
12
+ finish(): Promise<ObservationOperator | undefined>;
13
+ }
@@ -0,0 +1,50 @@
1
+ const OPERATOR_STOP_MS = 5000;
2
+ /** Runs the optional operator (for example --steps) beside the capture, with its interval markers. */
3
+ export class OperatorRun {
4
+ #abort = new AbortController();
5
+ #markerRequests = [];
6
+ #run;
7
+ start(operator, elapsed) {
8
+ if (!operator)
9
+ return;
10
+ const abort = this.#abort;
11
+ const mark = () => new Promise((resolve) => this.#markerRequests.push({ resolve }));
12
+ this.#run = Promise.resolve()
13
+ .then(() => operator({ mark, signal: abort.signal, elapsed }))
14
+ .then((steps) => ({
15
+ status: 'complete',
16
+ ...(Array.isArray(steps) ? { steps } : {}),
17
+ }), (error) => ({
18
+ status: abort.signal.aborted ? 'stopped' : 'failed',
19
+ error: error.message,
20
+ ...(Array.isArray(error.results) ? { steps: error.results } : {}),
21
+ }));
22
+ }
23
+ /** The next interval to open: one the operator asked for, or one `takeMarker` reports. */
24
+ nextMarker(takeMarker) {
25
+ if (this.#markerRequests.length)
26
+ return this.#markerRequests.shift();
27
+ return takeMarker?.() ? {} : null;
28
+ }
29
+ /** Stops the operator and returns its outcome, or undefined when there was none. */
30
+ async finish() {
31
+ this.#abort.abort();
32
+ for (const pending of this.#markerRequests)
33
+ pending.resolve?.(null);
34
+ if (!this.#run)
35
+ return undefined;
36
+ let timer;
37
+ // An operator that ignores the stop signal must not hold cleanup hostage.
38
+ const outcome = await Promise.race([
39
+ this.#run,
40
+ new Promise((resolve) => {
41
+ timer = setTimeout(() => resolve({
42
+ status: 'stopped',
43
+ error: `Operator did not stop within ${OPERATOR_STOP_MS} ms`,
44
+ }), OPERATOR_STOP_MS);
45
+ }),
46
+ ]);
47
+ clearTimeout(timer);
48
+ return outcome;
49
+ }
50
+ }
@@ -5,6 +5,8 @@ import { type CaptureReport } from './initial-report.mjs';
5
5
  import { type ReadSnapshot } from './reads.mjs';
6
6
  import { type SamplingTimings } from './sampling.mjs';
7
7
  import { type ObservationInterval, type SummarizedRows, type TimelineEvent } from './report.mjs';
8
+ import type { ReadLogSnapshot } from '../../transports/http/read-log.mjs';
9
+ import type { LoadSample, ProbeStatus } from './slow-reads/probe.mjs';
8
10
  /** A screen read between two read snapshots, so each read lands in one sample. */
9
11
  export interface Sample {
10
12
  before: ReadSnapshot;
@@ -14,6 +16,14 @@ export interface Sample {
14
16
  rows: SummarizedRows | null;
15
17
  actions: RegionRead['actions'];
16
18
  phases: SamplingTimings;
19
+ /** Renderer and bridge load, when `slowReads` is configured. */
20
+ load?: LoadSample | null;
21
+ }
22
+ /** What slow-read evidence needs from the end of the capture. */
23
+ export interface SlowReadsEnd {
24
+ readLog: ReadLogSnapshot | undefined;
25
+ probe: ProbeStatus;
26
+ startedEpoch: number;
17
27
  }
18
28
  /** Capture time: milliseconds since the capture started, and when that was. */
19
29
  export interface Clock {
@@ -35,5 +45,5 @@ export declare class ObservationRecorder {
35
45
  /** Records how long sampling ran and the last read snapshot, before any cleanup. */
36
46
  endSampling(elapsedMs: number, lastSnapshot: ReadSnapshot | undefined): void;
37
47
  /** Adds what can only be judged over the whole capture, and whether it is complete. */
38
- conclude(): void;
48
+ conclude(slowReads?: SlowReadsEnd): void;
39
49
  }