recovery-probe 1.1.0-preview.2 → 1.1.0-preview.4

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 (55) hide show
  1. package/CHANGELOG.md +13 -0
  2. package/README.md +2 -0
  3. package/dist/cli/net.d.mts +3 -0
  4. package/dist/cli/net.mjs +17 -2
  5. package/dist/cli/observe.mjs +19 -8
  6. package/dist/core/regexp.d.mts +2 -0
  7. package/dist/core/regexp.mjs +2 -0
  8. package/dist/core/region-read.d.mts +4 -1
  9. package/dist/core/region-read.mjs +12 -9
  10. package/dist/hook/probe.cjs +4 -21
  11. package/dist/hook/types.d.cts +7 -0
  12. package/dist/hook/window.cjs +39 -0
  13. package/dist/hook/window.d.cts +16 -0
  14. package/dist/reports/templates/observation.html +1 -0
  15. package/dist/targets/visibility.d.mts +3 -1
  16. package/dist/targets/visibility.mjs +34 -4
  17. package/dist/transports/ipc/inspector.d.mts +6 -1
  18. package/dist/transports/ipc/inspector.mjs +1 -0
  19. package/dist/workflows/observe/capture.mjs +9 -0
  20. package/dist/workflows/observe/config.d.mts +9 -0
  21. package/dist/workflows/observe/config.mjs +13 -0
  22. package/dist/workflows/observe/file-faults.mjs +4 -11
  23. package/dist/workflows/observe/files.d.mts +1 -1
  24. package/dist/workflows/observe/files.mjs +3 -7
  25. package/dist/workflows/observe/kit.d.mts +8 -0
  26. package/dist/workflows/observe/kit.mjs +42 -0
  27. package/dist/workflows/observe/network.d.mts +1 -1
  28. package/dist/workflows/observe/network.mjs +4 -11
  29. package/dist/workflows/observe/page-input.mjs +1 -0
  30. package/dist/workflows/observe/recorder.mjs +3 -6
  31. package/dist/workflows/observe/render.mjs +23 -11
  32. package/dist/workflows/observe/report.d.mts +45 -3
  33. package/dist/workflows/observe/report.mjs +19 -0
  34. package/dist/workflows/observe/requests.d.mts +13 -0
  35. package/dist/workflows/observe/requests.mjs +58 -0
  36. package/dist/workflows/observe/sample.d.mts +10 -0
  37. package/dist/workflows/observe/sample.mjs +38 -0
  38. package/dist/workflows/observe/session.d.mts +14 -0
  39. package/dist/workflows/observe/session.mjs +36 -6
  40. package/dist/workflows/observe/spans.d.mts +51 -0
  41. package/dist/workflows/observe/spans.mjs +115 -0
  42. package/dist/workflows/observe/step-runner.d.mts +2 -1
  43. package/dist/workflows/observe/step-runner.mjs +12 -5
  44. package/dist/workflows/observe/steps.d.mts +18 -0
  45. package/dist/workflows/observe/steps.mjs +31 -2
  46. package/dist/workflows/observe/summaries.d.mts +8 -1
  47. package/dist/workflows/observe/summaries.mjs +41 -0
  48. package/docs/ipc.md +1 -1
  49. package/docs/mcp-demo.md +31 -0
  50. package/docs/mcp.md +9 -5
  51. package/docs/net.md +1 -1
  52. package/docs/observe.md +33 -0
  53. package/examples/mcp-demo.mjs +117 -0
  54. package/package.json +7 -4
  55. package/server.json +33 -0
package/CHANGELOG.md CHANGED
@@ -4,6 +4,19 @@ 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.4 (2026-11-14)
8
+
9
+ - `net` warns on stderr when no connection has reached the proxy after 30 seconds, and its summary says so when none did, with the `HTTPS_PROXY` value to start the app with. Before, a proxy the app never used ran silently until it stopped.
10
+ - `observe --steps` can fail the page's own requests, such as its images or reads: `{ "requests": { "url": "**/images/**", "fault": "abort" } }`, or `"fault": "status"` with a status from 400 to 599. A later step replaces the rules, `"restore"` removes them, and the capture removes them when it ends. The report counts what each rule failed under `requests`. A rule that failed nothing adds `REQUEST_FAULT_NOT_TRIGGERED`, and rules that could not be removed add `REQUEST_FAULTS_NOT_RESTORED`.
11
+ - `observe` with `spans` lists the OpenTelemetry spans the page exports over OTLP/HTTP JSON during the capture: matching names, timings, status, the interval each started in, and the values of allowlisted attributes only. With `contentImages`, each span says how long before or after the content fully loaded it ended, so an app's own load-time measurement can be checked against the screen.
12
+ - `observe` with `contentImages` counts the images inside the content marker's elements, `<img>` elements and CSS background images, in every sample. Each interval records `contentLoaded`: when the content last became fully loaded, with every image loaded or failed, and stayed unchanged. The terminal and HTML report show it per interval.
13
+
14
+ ## 1.1.0-preview.3 (2026-11-13)
15
+
16
+ - `observe` checks the target window when the capture starts and says when the page is hidden or draws no frames, the usual reason a click step times out. `restoreWindow` un-minimizes the window for the capture, and `keepRendering` (IPC) keeps a minimized or covered window drawing where it is by turning off its background throttling through the development hook. Both put the window back afterwards, and the report records it under `window`. The hook gains a `setBackgroundThrottling` control. `check`, `discover`, `action` and `refresh` now also warn about a hidden page, not only one that reports itself visible but draws nothing. These window messages now go to stderr, so `--json` output on stdout stays parseable.
17
+ - Add MCP Registry ownership and launch metadata with stable-only OIDC publication.
18
+ - Add a reproducible stdio MCP retry demonstration and clarify unattended setup and dependencies.
19
+
7
20
  ## 1.1.0-preview.2 (2026-10-28)
8
21
 
9
22
  - 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.
package/README.md CHANGED
@@ -22,6 +22,8 @@ npx playwright install chromium
22
22
  npx recovery-probe demo
23
23
  ```
24
24
 
25
+ The next preview, `1.1.0-preview.4`, adds content-image load timing, request fault steps, exported span observation, and idle proxy warnings. After publication, install it with `npm install --save-dev recovery-probe@next playwright`. Until then, use the [source installation instructions](CONTRIBUTING.md#install-an-unpublished-source-preview).
26
+
25
27
  The demo runs two versions of a small app. Both load fine. Only the fixed one survives a 503, a dropped connection and a broken JSON response.
26
28
 
27
29
  ## Check your own app
@@ -1 +1,4 @@
1
+ import type { NetworkFaultProxy } from '../transports/net/types.mjs';
1
2
  export declare function netMain(args: string[]): Promise<void>;
3
+ /** Warns once when no connection reached the proxy within `delayMs`; returns a function that cancels it. */
4
+ export declare function warnIfIdle(proxy: Pick<NetworkFaultProxy, 'summary' | 'url'>, delayMs: number, warn?: (message: string) => void): () => void;
package/dist/cli/net.mjs CHANGED
@@ -3,6 +3,8 @@ import { startNetworkFaultProxy } from '../transports/net/proxy.mjs';
3
3
  import { validateNetworkRules } from '../transports/net/rules.mjs';
4
4
  import { untilStopped } from './until-stopped.mjs';
5
5
  import { integerOption, parseOptions, text } from './args.mjs';
6
+ // An app that is not running, or ignores HTTPS_PROXY, leaves the proxy silent.
7
+ const IDLE_WARNING_MS = 30_000;
6
8
  const USAGE = 'recovery-probe net [--rules FILE] [--port N] [--duration MS] [--out FILE] [--json]';
7
9
  const HELP = `${USAGE}
8
10
 
@@ -64,12 +66,14 @@ export async function netMain(args) {
64
66
  control: true,
65
67
  });
66
68
  const printFaults = faultPrinter(proxy);
69
+ const stopIdleWarning = warnIfIdle(proxy, IDLE_WARNING_MS);
67
70
  let watch;
68
71
  if (!options.json) {
69
72
  printStart(proxy, rules);
70
73
  watch = setInterval(printFaults, 250);
71
74
  }
72
75
  await untilStopped(options.duration);
76
+ stopIdleWarning();
73
77
  clearInterval(watch);
74
78
  if (!options.json)
75
79
  printFaults();
@@ -80,7 +84,7 @@ export async function netMain(args) {
80
84
  if (options.json)
81
85
  console.log(JSON.stringify(report, null, 2));
82
86
  else
83
- printSummary(report);
87
+ printSummary(report, proxy.url);
84
88
  process.exitCode = report.ok ? 0 : 2;
85
89
  }
86
90
  async function readRules(path) {
@@ -89,6 +93,15 @@ async function readRules(path) {
89
93
  const parsed = JSON.parse(await readFile(path, 'utf8'));
90
94
  return validateNetworkRules(Array.isArray(parsed) ? parsed : parsed?.rules);
91
95
  }
96
+ const startHint = (url) => `Is the app running, and was it started with HTTPS_PROXY=${url}?`;
97
+ /** Warns once when no connection reached the proxy within `delayMs`; returns a function that cancels it. */
98
+ export function warnIfIdle(proxy, delayMs, warn = (message) => console.error(message)) {
99
+ const timer = setTimeout(() => {
100
+ if (proxy.summary().connections === 0)
101
+ warn(`Recovery Probe: no connection has reached the proxy in ${delayMs / 1000} s. ${startHint(proxy.url)}`);
102
+ }, delayMs);
103
+ return () => clearTimeout(timer);
104
+ }
92
105
  /** Prints the faulted connections since its last call. */
93
106
  function faultPrinter(proxy) {
94
107
  let printed = 0;
@@ -130,8 +143,10 @@ function netReport(proxy, rules) {
130
143
  eventsDropped: summary.eventsDropped,
131
144
  };
132
145
  }
133
- function printSummary(report) {
146
+ function printSummary(report, url) {
134
147
  console.log(`\n${report.connections} connection(s) through the proxy`);
148
+ if (report.connections === 0)
149
+ console.log(`No connection reached the proxy. ${startHint(url)}`);
135
150
  report.rules.forEach((rule, index) => console.log(` rule ${index + 1}: ${rule.fault} ${rule.host} faulted ${rule.applied} of ${rule.matching} matching`));
136
151
  if (!report.ok)
137
152
  console.log('\nFAULT_NOT_TRIGGERED: a rule faulted no connection. Check that the app uses HTTPS_PROXY and the host names.');
@@ -4,7 +4,7 @@ import { resolve, join } from 'node:path';
4
4
  import { createInterface } from 'node:readline';
5
5
  import { observationConfig, } from '../workflows/observe/config.mjs';
6
6
  import { connectNetworkSteps, observeSession, } from '../workflows/observe/session.mjs';
7
- import { observationSummary, actionSummary, networkStepSummary, fileFaultSummary, } from '../workflows/observe/summaries.mjs';
7
+ import { observationSummary, actionSummary, networkStepSummary, requestStepSummary, fileFaultSummary, contentLoadedSummary, spanNotes, spanSummary, } from '../workflows/observe/summaries.mjs';
8
8
  import { renderObservationReport } from '../workflows/observe/render.mjs';
9
9
  import { comparisonDigest } from '../workflows/observe/comparisons.mjs';
10
10
  import { observationSteps, } from '../workflows/observe/steps.mjs';
@@ -26,8 +26,9 @@ UNEXPECTED_ROW_STATE reports a tracked row shown in a state listed in rows.unexp
26
26
  --steps runs an explicit, opt-in list of same-document navigations, clicks, waits,
27
27
  expectations and interval marks during the capture. Steps act on the app: use a
28
28
  test account. An expect step that sees nothing in time adds EXPECTATION_NOT_MET.
29
+ Request steps fail the page's own requests, such as its images, by URL glob;
29
30
  --network names a running recovery-probe net, so network steps can fail the app's
30
- own HTTPS connections; they are removed when the capture ends.
31
+ own HTTPS connections. Both are removed when the capture ends.
31
32
  --files compares a directory's files at each interval and reports files the app
32
33
  removed or shrank (LOCAL_FILES_REMOVED, a lead). Paths stay in a private files.json.
33
34
  File steps remove, truncate or corrupt a file under it; a file the app has not
@@ -100,6 +101,7 @@ async function readInputs(options) {
100
101
  const steps = options.steps
101
102
  ? await readConfig(options.steps, (list) => observationSteps(list, {
102
103
  network: Boolean(options.network),
104
+ requests: true,
103
105
  files: Boolean(options.files),
104
106
  }))
105
107
  : null;
@@ -171,6 +173,8 @@ async function writeObservation(directory, config, steps, { report, files }) {
171
173
  function printObservation(report, config, directory) {
172
174
  const lines = [
173
175
  ...report.intervals.map(intervalLine),
176
+ ...(report.spans?.spans ?? []).map((span) => `Span ${spanSummary(span)}`),
177
+ ...(report.spans ? spanNotes(report.spans) : []),
174
178
  ...report.findings.map(findingLine),
175
179
  ...(report.actionEffects ?? []).map(actionSummary),
176
180
  ...comparisonDigest(report),
@@ -184,9 +188,11 @@ function printObservation(report, config, directory) {
184
188
  console.error(report.error);
185
189
  console.log(`Capture: ${report.status} (not a health verdict)\nReport: ${join(directory, 'report.html')}`);
186
190
  }
187
- function intervalLine({ index, reads, findings }) {
191
+ function intervalLine(interval) {
192
+ const { index, reads, findings } = interval;
188
193
  const raised = findings.length ? '; ' + findings.join(', ') : '';
189
- return `Interval ${index}: ${reads?.calls ?? '?'} reads, ${reads?.successes ?? '?'} successes, ${reads?.errors ?? '?'} errors${raised}`;
194
+ const loaded = contentLoadedSummary(interval);
195
+ return `Interval ${index}: ${reads?.calls ?? '?'} reads, ${reads?.successes ?? '?'} successes, ${reads?.errors ?? '?'} errors${loaded ? '; ' + loaded : ''}${raised}`;
190
196
  }
191
197
  function findingLine(finding) {
192
198
  const code = NAMED_FINDINGS.includes(finding.code) ? `${finding.code} — ` : '';
@@ -195,10 +201,15 @@ function findingLine(finding) {
195
201
  function printStepOutcomes(report) {
196
202
  if (report.operator)
197
203
  console.log(`Scripted steps: ${report.operator.status}${report.operator.error ? ' — ' + report.operator.error : ''}`);
198
- for (const record of report.network?.faults ?? [])
199
- console.log(networkStepSummary(record));
200
- if (report.network?.restoreError)
201
- console.error(`Network faults were not removed: ${report.network.restoreError}. Stop recovery-probe net to restore the app's network.`);
204
+ printFaults(report.network, networkStepSummary, (error) => `Network faults were not removed: ${error}. Stop recovery-probe net to restore the app's network.`);
205
+ printFaults(report.requests, requestStepSummary, (error) => `Request faults were not removed: ${error}.`);
202
206
  for (const record of report.fileFaults ?? [])
203
207
  console.log(fileFaultSummary(record));
204
208
  }
209
+ /** What each fault step did, and an error when its faults could not be removed. */
210
+ function printFaults(evidence, summary, unrestored) {
211
+ for (const record of evidence?.faults ?? [])
212
+ console.log(summary(record));
213
+ if (evidence?.restoreError)
214
+ console.error(unrestored(evidence.restoreError));
215
+ }
@@ -0,0 +1,2 @@
1
+ /** `value` with RegExp syntax characters escaped, so a RegExp matches it literally. */
2
+ export declare const escapeRegExp: (value: string) => string;
@@ -0,0 +1,2 @@
1
+ /** `value` with RegExp syntax characters escaped, so a RegExp matches it literally. */
2
+ export const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
@@ -1,4 +1,4 @@
1
- import type { RecordedAction } from '../workflows/observe/kit.mjs';
1
+ import type { ContentImages, RecordedAction } from '../workflows/observe/kit.mjs';
2
2
  import type { SelectorSpec } from './selector.mjs';
3
3
  /** What an observation reads; a plain region selector reads the region alone. */
4
4
  export interface ObservationReadInput {
@@ -6,6 +6,8 @@ export interface ObservationReadInput {
6
6
  contentSelector: SelectorSpec;
7
7
  detail?: string;
8
8
  kitToken?: string;
9
+ /** Also counts the images inside the matched content. */
10
+ images?: boolean;
9
11
  rows?: {
10
12
  selector: SelectorSpec;
11
13
  key?: SelectorSpec;
@@ -22,6 +24,7 @@ export interface RegionRead {
22
24
  texts: string[];
23
25
  truncated: boolean;
24
26
  };
27
+ contentImages?: ContentImages;
25
28
  rows?: {
26
29
  truncated: boolean;
27
30
  /** `marker` is the index of the first configured marker found in the row. */
@@ -52,18 +52,21 @@ export function readRegion(selector) {
52
52
  const contentOf = (root, spec) => {
53
53
  const matches = select(root, spec);
54
54
  const texts = [];
55
+ const elements = [];
55
56
  let remaining = 200000;
56
57
  let truncated = matches.length > 1000;
57
58
  for (const e of [...matches].slice(0, 1000)) {
58
59
  if (!visible(e))
59
60
  continue;
61
+ elements.push(e);
60
62
  const text = innerText(e);
61
63
  if (text.length > remaining)
62
64
  truncated = true;
63
65
  texts.push(text.slice(0, remaining));
64
66
  remaining = Math.max(0, remaining - text.length);
65
67
  }
66
- return { texts, truncated };
68
+ // The elements stay in the page: only the texts are returned.
69
+ return { content: { texts, truncated }, elements };
67
70
  };
68
71
  // Row key and state text are returned transiently; Node hashes keys and keeps only allowlisted states.
69
72
  const rowsOf = (root, r) => {
@@ -172,8 +175,7 @@ export function readRegion(selector) {
172
175
  ? {
173
176
  presence: 'visible',
174
177
  contentCount: observed.content.texts.length,
175
- content: observed.content,
176
- rows: observed.rows,
178
+ ...observed,
177
179
  }
178
180
  : {}),
179
181
  region: regionSelector
@@ -187,12 +189,11 @@ export function readRegion(selector) {
187
189
  ...indicatorsOf(root, text),
188
190
  };
189
191
  };
190
- const contentRead = ({ content, rows }) => ({
192
+ const contentRead = (observed) => ({
191
193
  presence: 'visible',
192
- contentCount: content.texts.length,
193
- content,
194
- rows,
195
- truncated: content.truncated,
194
+ contentCount: observed.content.texts.length,
195
+ ...observed,
196
+ truncated: observed.content.truncated,
196
197
  ...page(),
197
198
  });
198
199
  const read = () => {
@@ -210,9 +211,11 @@ export function readRegion(selector) {
210
211
  return structuralRead(root, regionSelector);
211
212
  if (!visible(root))
212
213
  return { presence: 'hidden', contentCount: 0, ...page() };
214
+ const { content, elements } = contentOf(root, observation.contentSelector);
213
215
  const observed = {
214
- content: contentOf(root, observation.contentSelector),
216
+ content,
215
217
  rows: observation.rows ? rowsOf(root, observation.rows) : undefined,
218
+ ...(observation.images ? { contentImages: kit?.imagesIn(elements) } : {}),
216
219
  };
217
220
  return observation.detail === 'content'
218
221
  ? contentRead(observed)
@@ -6,6 +6,7 @@ const checks_cjs_1 = require("./checks.cjs");
6
6
  const pushes_cjs_1 = require("./pushes.cjs");
7
7
  const state_cjs_1 = require("./state.cjs");
8
8
  const stats_cjs_1 = require("./stats.cjs");
9
+ const window_cjs_1 = require("./window.cjs");
9
10
  const installed = new WeakSet();
10
11
  // No Electron import: use its public registration API, supplied by the development app.
11
12
  function installIpcProbe(
@@ -30,6 +31,7 @@ class ProbeHook {
30
31
  #registered = new Set();
31
32
  #seenIds = new Set();
32
33
  #pushes;
34
+ #windows;
33
35
  #active = true;
34
36
  #state = null;
35
37
  #timer;
@@ -37,6 +39,7 @@ class ProbeHook {
37
39
  this.#ipcMain = ipcMain;
38
40
  this.#original = ipcMain.handle;
39
41
  this.#sender = settings.sender;
42
+ this.#windows = (0, window_cjs_1.windowControls)(settings.sender);
40
43
  this.#classify = settings.classify;
41
44
  this.#allowed = new Set(settings.channels);
42
45
  this.#allowedPushes = new Set(settings.pushChannels);
@@ -50,8 +53,7 @@ class ProbeHook {
50
53
  identify: ((challenge) => this.identify(challenge)),
51
54
  begin: (options) => this.begin(options),
52
55
  snapshot: () => this.snapshot(),
53
- windowState: () => this.windowState(),
54
- setWindowMinimized: (minimized) => this.setWindowMinimized(minimized),
56
+ ...this.#windows,
55
57
  reset: (id) => this.reset(id),
56
58
  dispose: () => this.dispose(),
57
59
  };
@@ -114,19 +116,6 @@ class ProbeHook {
114
116
  ? JSON.parse(JSON.stringify({ ...state, capturedAt: Date.now() }))
115
117
  : null;
116
118
  }
117
- windowState() {
118
- return { minimized: this.#window().isMinimized() };
119
- }
120
- setWindowMinimized(minimized) {
121
- if (typeof minimized !== 'boolean')
122
- throw new Error('Expected boolean window state');
123
- const window = this.#window();
124
- if (minimized)
125
- window.minimize();
126
- else
127
- window.restore();
128
- return { minimized: window.isMinimized() };
129
- }
130
119
  reset(id) {
131
120
  if (id !== undefined && this.#state && id !== this.#state.id)
132
121
  throw new Error('Stale run ID');
@@ -149,12 +138,6 @@ class ProbeHook {
149
138
  if (previous && Object.values(previous.channels).some((c) => c.pending))
150
139
  throw new Error('Previous real calls are still pending; wait before beginning another run');
151
140
  }
152
- #window() {
153
- const window = this.#sender()?.getOwnerBrowserWindow?.();
154
- if (!window || window.isDestroyed())
155
- throw new Error('Window control unavailable');
156
- return window;
157
- }
158
141
  #disarm() {
159
142
  clearTimeout(this.#timer);
160
143
  this.#pushes.unwrap();
@@ -5,6 +5,9 @@ export interface ProbeWebContents {
5
5
  getURL(): string;
6
6
  executeJavaScript(code: string): Promise<unknown>;
7
7
  send?(channel: string, ...args: unknown[]): void;
8
+ /** Used for the opt-in control that keeps a minimized or covered window drawing frames. */
9
+ setBackgroundThrottling?(allowed: boolean): void;
10
+ getBackgroundThrottling?(): boolean;
8
11
  /** Used for the opt-in window minimize/restore controls. */
9
12
  getOwnerBrowserWindow?(): {
10
13
  isDestroyed(): boolean;
@@ -109,6 +112,10 @@ export interface IpcProbe {
109
112
  setWindowMinimized(minimized: boolean): {
110
113
  minimized: boolean;
111
114
  };
115
+ setBackgroundThrottling(allowed: boolean): {
116
+ allowed: boolean;
117
+ previous: boolean;
118
+ };
112
119
  reset(id?: string): IpcSnapshot | null;
113
120
  dispose(): void;
114
121
  }
@@ -0,0 +1,39 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.windowControls = windowControls;
4
+ function windowControls(sender) {
5
+ const window = () => {
6
+ const owner = sender()?.getOwnerBrowserWindow?.();
7
+ if (!owner || owner.isDestroyed())
8
+ throw new Error('Window control unavailable');
9
+ return owner;
10
+ };
11
+ return {
12
+ windowState: () => ({ minimized: window().isMinimized() }),
13
+ setWindowMinimized(minimized) {
14
+ if (typeof minimized !== 'boolean')
15
+ throw new Error('Expected boolean window state');
16
+ const owner = window();
17
+ if (minimized)
18
+ owner.minimize();
19
+ else
20
+ owner.restore();
21
+ return { minimized: owner.isMinimized() };
22
+ },
23
+ /** Throttled, a minimized or covered window draws no frames, so clicks wait forever. */
24
+ setBackgroundThrottling(allowed) {
25
+ if (typeof allowed !== 'boolean')
26
+ throw new Error('Expected boolean background throttling');
27
+ const contents = sender();
28
+ if (!contents?.setBackgroundThrottling || contents.isDestroyed())
29
+ throw new Error('Rendering control unavailable');
30
+ // Electron throttles by default; older versions cannot report it.
31
+ const previous = contents.getBackgroundThrottling?.() ?? true;
32
+ contents.setBackgroundThrottling(allowed);
33
+ return {
34
+ allowed: contents.getBackgroundThrottling?.() ?? allowed,
35
+ previous,
36
+ };
37
+ },
38
+ };
39
+ }
@@ -0,0 +1,16 @@
1
+ import type { ProbeWebContents } from './types.cjs';
2
+ type Sender = () => ProbeWebContents | undefined | null;
3
+ export declare function windowControls(sender: Sender): {
4
+ windowState: () => {
5
+ minimized: boolean;
6
+ };
7
+ setWindowMinimized(minimized: boolean): {
8
+ minimized: boolean;
9
+ };
10
+ /** Throttled, a minimized or covered window draws no frames, so clicks wait forever. */
11
+ setBackgroundThrottling(allowed: boolean): {
12
+ allowed: boolean;
13
+ previous: boolean;
14
+ };
15
+ };
16
+ export {};
@@ -51,6 +51,7 @@
51
51
  {{{intervals}}}
52
52
  </tbody>
53
53
  </table>
54
+ {{{spans}}}
54
55
  {{{findings}}}
55
56
  {{{operator}}}
56
57
  {{{actions}}}
@@ -18,8 +18,10 @@ export interface WindowReport {
18
18
  initial: WindowVisibility;
19
19
  restoration?: Awaited<ReturnType<PreparedVisibility['revert']>>;
20
20
  }
21
- export declare function prepareVisibility(page: Page, { restoreWindow, control, announce, }?: {
21
+ export declare function prepareVisibility(page: Page, { restoreWindow, keepRendering, control, announce, }?: {
22
22
  restoreWindow?: boolean;
23
+ /** Keeps a minimized or covered Electron window drawing frames, through the IPC hook. */
24
+ keepRendering?: boolean;
23
25
  control?: IpcInspector;
24
26
  announce?: (message: string) => void;
25
27
  }): Promise<{
@@ -107,13 +107,43 @@ async function setWindowState(page, control, initial, state) {
107
107
  await session.detach();
108
108
  }
109
109
  }
110
- export async function prepareVisibility(page, { restoreWindow = false, control, announce = console.log, } = {}) {
110
+ /** Warns when the page is hidden or draws no frames, which stalls clicks. */
111
+ function warnUnlessDrawing(window, announce) {
112
+ const draws = window.visibility === 'visible' &&
113
+ !(window.rendering && NOT_RENDERING[window.rendering]);
114
+ if (!draws)
115
+ announce(`Recovery Probe: ${window.diagnosis}. Clicks may time out, and the run may not match what a user sees.`);
116
+ }
117
+ /** Turns off the window's background throttling through the IPC hook; returns how to turn it back. */
118
+ async function keepDrawing(control, announce) {
119
+ if (!control)
120
+ throw new Error('keepRendering needs the IPC development hook');
121
+ const { previous } = await control
122
+ .call('setBackgroundThrottling', false)
123
+ .catch((error) => {
124
+ throw new Error(`keepRendering needs this version's development hook; restart the app so it loads it (${error.message})`);
125
+ });
126
+ announce('Recovery Probe: keeping the target window drawing frames while it is minimized or covered; its background throttling is restored afterwards.');
127
+ return async () => {
128
+ const { allowed } = await control.call('setBackgroundThrottling', previous);
129
+ if (allowed !== previous)
130
+ throw new Error('Background throttling restoration unverified');
131
+ };
132
+ }
133
+ export async function prepareVisibility(page, { restoreWindow = false, keepRendering = false, control,
134
+ // stderr, so a command's JSON on stdout stays parseable.
135
+ announce = (message) => console.error(message), } = {}) {
111
136
  const initial = await windowVisibility(page, control);
112
- if (initial.rendering && NOT_RENDERING[initial.rendering])
113
- announce(`Recovery Probe: ${initial.diagnosis}. Clicks may time out, and the run may not match what a user sees.`);
137
+ const restoring = restoreWindow && initial.windowState === 'minimized';
138
+ if (!restoring && !keepRendering)
139
+ warnUnlessDrawing(initial, announce);
114
140
  const set = (state) => setWindowState(page, control, initial, state);
141
+ const restoreDrawing = keepRendering
142
+ ? await keepDrawing(control, announce)
143
+ : undefined;
115
144
  let changed = false;
116
145
  const revert = async () => {
146
+ await restoreDrawing?.();
117
147
  if (!changed)
118
148
  return { changed: false, restored: true };
119
149
  await set(initial.windowState);
@@ -122,7 +152,7 @@ export async function prepareVisibility(page, { restoreWindow = false, control,
122
152
  throw new Error('Window state restoration unverified');
123
153
  return { changed: true, restored: true, final };
124
154
  };
125
- if (restoreWindow && initial.windowState === 'minimized') {
155
+ if (restoring) {
126
156
  announce('Recovery Probe: restoring the minimized target window for this run; its original state will be restored afterwards.');
127
157
  changed = true; // An unsuccessful reply may still have executed.
128
158
  await unminimize(page, control, set, revert);
@@ -10,9 +10,14 @@ export interface IpcInspector {
10
10
  call(method: 'setWindowMinimized', minimized: boolean): Promise<{
11
11
  minimized: boolean;
12
12
  }>;
13
+ call(method: 'setBackgroundThrottling', allowed: boolean): Promise<{
14
+ allowed: boolean;
15
+ previous: boolean;
16
+ }>;
13
17
  close(): void;
14
18
  }
15
- type ProbeControl = 'identify' | 'begin' | 'snapshot' | 'reset' | 'windowState' | 'setWindowMinimized';
19
+ type ProbeControl = (typeof CONTROLS)[number];
20
+ declare const CONTROLS: readonly ["identify", "begin", "snapshot", "reset", "windowState", "setWindowMinimized", "setBackgroundThrottling"];
16
21
  export declare function connectIpcInspector(endpoint?: string): Promise<IpcInspector>;
17
22
  /** Advanced protocol transport; only the documented probe control methods are allowed. */
18
23
  export declare function callIpcInspector(send: (method: string, params: Record<string, unknown>) => Promise<unknown>, method: ProbeControl, argument?: unknown): Promise<any>;
@@ -7,6 +7,7 @@ const CONTROLS = [
7
7
  'reset',
8
8
  'windowState',
9
9
  'setWindowMinimized',
10
+ 'setBackgroundThrottling',
10
11
  ];
11
12
  export async function connectIpcInspector(endpoint = 'http://127.0.0.1:9229') {
12
13
  const socket = await InspectorSocket.open(await debuggerUrl(endpoint));
@@ -4,6 +4,7 @@ import { setTimeout as sleep } from 'node:timers/promises';
4
4
  import { readRegion, } from '../../core/region-read.mjs';
5
5
  import { summarizeRegion } from '../../core/screen.mjs';
6
6
  import { observationConfig } from './config.mjs';
7
+ import { relateSpans, SpanRecorder } from './spans.mjs';
7
8
  import { installObserverKit, removeObserverKit } from './kit.mjs';
8
9
  import { pageReadInput, pageSelectors } from './page-input.mjs';
9
10
  import { ObservationRecorder } from './recorder.mjs';
@@ -31,6 +32,7 @@ class Capture {
31
32
  #readInput;
32
33
  #operator = new OperatorRun();
33
34
  #slowProbe;
35
+ #spans;
34
36
  #started = 0;
35
37
  /** Set once the adapter is reading; the capture has a clock from then on. */
36
38
  #clock;
@@ -56,6 +58,9 @@ class Capture {
56
58
  this.#slowProbe = config.slowReads
57
59
  ? new SlowReadProbe(page, config.slowReads, this.#kitToken)
58
60
  : undefined;
61
+ this.#spans = config.spans
62
+ ? new SpanRecorder(page, config.spans)
63
+ : undefined;
59
64
  }
60
65
  async run() {
61
66
  const report = this.#recorder.report;
@@ -89,6 +94,7 @@ class Capture {
89
94
  report.metadata.ipcHook = this.#adapter.metadata?.() ?? null;
90
95
  this.#started = performance.now();
91
96
  this.#clock = { elapsed: this.#elapsed, startedEpoch: Date.now() };
97
+ this.#spans?.start(this.#clock.startedEpoch);
92
98
  this.#lastSnapshot = await this.#adapter.snapshot();
93
99
  report.startedAt = this.#lastSnapshot.startedAt;
94
100
  this.#recorder.openInterval(this.#lastSnapshot, this.#elapsed());
@@ -199,9 +205,12 @@ class Capture {
199
205
  this.#page.off('domcontentloaded', this.#noteDocumentLoad);
200
206
  const readLog = this.#adapter.readLog?.();
201
207
  await this.#slowProbe?.stop();
208
+ if (this.#spans)
209
+ recorder.report.spans = this.#spans.stop();
202
210
  await this.#removeKit();
203
211
  await this.#stopAdapter();
204
212
  recorder.conclude(this.#slowReadsEnd(readLog));
213
+ relateSpans(recorder.report);
205
214
  }
206
215
  #slowReadsEnd(readLog) {
207
216
  const probe = this.#slowProbe;
@@ -1,6 +1,7 @@
1
1
  import { type SelectorSpec } from '../../core/selector.mjs';
2
2
  import type { ObservedActionConfig } from './kit.mjs';
3
3
  import { type SlowReadsConfig } from './slow-reads/config.mjs';
4
+ import { type SpansConfig } from './spans.mjs';
4
5
  export interface RowsConfig {
5
6
  selector: SelectorSpec;
6
7
  key?: SelectorSpec;
@@ -33,10 +34,18 @@ export interface ObservationConfig {
33
34
  rows?: RowsConfig;
34
35
  actions?: ObservedActionConfig[];
35
36
  slowReads?: SlowReadsConfig;
37
+ /** Lists the spans the page exports over OTLP/HTTP JSON during the capture. */
38
+ spans?: SpansConfig;
36
39
  lagThresholdMs: number;
37
40
  minUnchangedReads: number;
38
41
  detail: 'content' | 'region';
39
42
  observationMs: number;
40
43
  sampleMs: number;
44
+ /** Un-minimizes the target window for the capture and minimizes it again afterwards. */
45
+ restoreWindow: boolean;
46
+ /** Keeps a minimized or covered window drawing frames for the capture, through the IPC hook. */
47
+ keepRendering: boolean;
48
+ /** Counts the content as loaded only once the images inside it have loaded or failed. */
49
+ contentImages: boolean;
41
50
  }
42
51
  export declare function observationConfig(input: unknown): ObservationConfig;
@@ -2,6 +2,7 @@ import { ensure, ensureRanges, isIntegerIn, isNonEmptyString, isRecord, isUnique
2
2
  import { selectorSpec } from '../../core/selector.mjs';
3
3
  import { slowReadsConfig } from './slow-reads/config.mjs';
4
4
  import { hasOnlyKeys, validateHttpTarget, validateIpcTarget, } from './target-config.mjs';
5
+ import { spansConfig } from './spans.mjs';
5
6
  const NAME = /^[\w.-]{1,40}$/;
6
7
  /** Every state label a row can have besides 'none' and 'other'. */
7
8
  export const stateLabels = (r) => [
@@ -23,11 +24,15 @@ const DEFAULTS = {
23
24
  rows: undefined,
24
25
  actions: undefined,
25
26
  slowReads: undefined,
27
+ spans: undefined,
26
28
  lagThresholdMs: 2000,
27
29
  minUnchangedReads: 2,
28
30
  detail: 'content',
29
31
  observationMs: 30000,
30
32
  sampleMs: 100,
33
+ restoreWindow: false,
34
+ keepRendering: false,
35
+ contentImages: false,
31
36
  };
32
37
  const RANGES = [
33
38
  ['observationMs', 500, 600000],
@@ -51,12 +56,20 @@ export function observationConfig(input) {
51
56
  c.actions = actionsConfig(c.actions);
52
57
  if (c.slowReads !== undefined)
53
58
  c.slowReads = slowReadsConfig(c.slowReads);
59
+ if (c.spans !== undefined)
60
+ c.spans = spansConfig(c.spans);
61
+ validateFlags(c);
54
62
  if (c.transport === 'http')
55
63
  validateHttpTarget(c);
56
64
  else
57
65
  validateIpcTarget(c);
58
66
  return c;
59
67
  }
68
+ function validateFlags(c) {
69
+ for (const key of ['restoreWindow', 'keepRendering', 'contentImages'])
70
+ ensure(typeof c[key] === 'boolean', `${key} must be boolean`);
71
+ ensure(!c.keepRendering || c.transport === 'ipc', 'keepRendering needs transport ipc and the development hook');
72
+ }
60
73
  const isLoopbackDevtools = (url) => ['http:', 'ws:'].includes(url.protocol) &&
61
74
  ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname) &&
62
75
  !url.username &&