recovery-probe 0.3.0 → 0.4.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.
- package/CHANGELOG.md +9 -0
- package/README.md +1 -0
- package/bin/observe.mjs +20 -8
- package/docs/ipc.md +2 -0
- package/docs/observe.md +83 -1
- package/package.json +5 -5
- package/src/ipc-observation.mjs +24 -8
- package/src/ipc-probe.cjs +61 -10
- package/src/ipc-probe.d.cts +21 -4
- package/src/observation-kit.mjs +96 -0
- package/src/observation-report.mjs +53 -1
- package/src/observe-steps.mjs +87 -0
- package/src/observe.mjs +238 -29
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,15 @@ 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
|
+
## 0.4.0-preview.1 (2026-10-15)
|
|
8
|
+
|
|
9
|
+
- Record configured user actions during observation (name, time, real-input flag) and report the tracked rows that appeared or changed after each action.
|
|
10
|
+
- Track rows with hashed keys or configured aliases and allowlisted state labels. Add the `DELAYED_UI_UPDATE` observation: a row state that persisted across completed selected reads and then changed without a data event in the sampled window.
|
|
11
|
+
- Accept `{ css, role, name, text }` selectors for content, rows and actions.
|
|
12
|
+
- Let the development IPC hook count calls per method label on shared channels (`classify`) and observe main-to-renderer pushes as data events (`pushChannels`, `classifyPush`) without storing arguments or payloads. Select them with `methods` and `dataEvents`.
|
|
13
|
+
- Omit per-completion comparisons for busy targets with an explicit note, and print one comparison line per interval.
|
|
14
|
+
- Add opt-in `observe --steps` for explicit same-document navigation, clicks with real input events, waits and interval marks. Observation without steps still never acts.
|
|
15
|
+
|
|
7
16
|
## 0.3.0 (2026-10-14)
|
|
8
17
|
|
|
9
18
|
- Promote the validated 0.3.0 preview series to the stable npm `latest` channel: guided web/Electron setup, HTTP/IPC discovery and recovery checks, refresh experiments, fault-free observation, and a runnable CI example.
|
package/README.md
CHANGED
|
@@ -45,6 +45,7 @@ Content comparisons preserve the first observed result and summarize later sampl
|
|
|
45
45
|
| Compare an Electron screen under IPC faults | `recovery-probe ipc --discover --config FILE` | [IPC setup and discovery](docs/ipc.md) |
|
|
46
46
|
| Test a refresh after content has already loaded | `recovery-probe refresh --config FILE --json` | [Refresh experiments](docs/refresh.md) |
|
|
47
47
|
| Observe cached content without a reload | `recovery-probe observe --config FILE` | [Observation](docs/observe.md) |
|
|
48
|
+
| Time row states after a user action, with optional scripted steps | `recovery-probe observe --config FILE [--steps FILE]` | [Actions, rows and delayed UI updates](docs/observe.md#actions-tracked-rows-and-delayed-ui-updates) |
|
|
48
49
|
| Run a repeatable synthetic recovery check in CI | `npm run test:ci-example` (source checkout) | [CI example](docs/ci.md) |
|
|
49
50
|
| Add an explicit recovery assertion to a test | `withFault` or `createFaultFetch` | Examples below |
|
|
50
51
|
| Propose and verify a source change | Opt-in repair workflow | [Repair setup and limits](docs/repair.md) |
|
package/bin/observe.mjs
CHANGED
|
@@ -5,11 +5,12 @@ import { createInterface } from 'node:readline';
|
|
|
5
5
|
import { connectDesktop, selectDesktopPage, desktopPages } from '../src/desktop.mjs';
|
|
6
6
|
import { connectIpcInspector } from '../src/ipc-inspector.mjs';
|
|
7
7
|
import { observationConfig, runObservation, httpObservationAdapter, ipcObservationAdapter } from '../src/observe.mjs';
|
|
8
|
-
import { observationMetadata, samplingMetrics, observationSummary, renderObservationReport,
|
|
8
|
+
import { observationMetadata, samplingMetrics, observationSummary, renderObservationReport, actionSummary, comparisonDigest } from '../src/observation-report.mjs';
|
|
9
|
+
import { observationSteps, runSteps } from '../src/observe-steps.mjs';
|
|
9
10
|
|
|
10
11
|
export async function observeMain(args) {
|
|
11
12
|
if (!args.length || args.includes('--help')) {
|
|
12
|
-
console.log(`recovery-probe observe --config FILE [--out NEW_DIRECTORY] [--json] [--interactive]
|
|
13
|
+
console.log(`recovery-probe observe --config FILE [--out NEW_DIRECTORY] [--json] [--interactive] [--steps FILE]
|
|
13
14
|
|
|
14
15
|
Fault-free observation of an existing browser or Electron renderer.
|
|
15
16
|
No reload, navigation, focus change, fault injection or final UI reset.
|
|
@@ -17,18 +18,21 @@ Choose transport: http or ipc and explicit regionSelector/contentSelector CSS ma
|
|
|
17
18
|
Sampling defaults to detail: "content"; use "region" for full DOM diagnostics.
|
|
18
19
|
Navigate manually during the bounded capture. Enter marks a new interval in an
|
|
19
20
|
interactive terminal; --interactive also enables newline markers on piped input.
|
|
20
|
-
Ctrl+C saves partial evidence. CONTENT_BEFORE_READ
|
|
21
|
+
Ctrl+C saves partial evidence. CONTENT_BEFORE_READ and DELAYED_UI_UPDATE are observations, not defects.
|
|
22
|
+
--steps runs an explicit, opt-in list of same-document navigations, clicks, waits and
|
|
23
|
+
interval marks during the capture. Steps act on the app: use a test account.
|
|
21
24
|
IPC requires the observation-capable development hook. See docs/observe.md.`);
|
|
22
25
|
return;
|
|
23
26
|
}
|
|
24
27
|
const options = {};
|
|
25
28
|
for (let i = 0; i < args.length; i++) {
|
|
26
29
|
if (['--json', '--interactive'].includes(args[i])) options[args[i].slice(2)] = true;
|
|
27
|
-
else if (['--config', '--out'].includes(args[i]) && args[i + 1] && !args[i + 1].startsWith('--')) options[args[i].slice(2)] = args[++i];
|
|
28
|
-
else throw Error('Use observe --config FILE [--out NEW_DIRECTORY] [--json] [--interactive]');
|
|
30
|
+
else if (['--config', '--out', '--steps'].includes(args[i]) && args[i + 1] && !args[i + 1].startsWith('--')) options[args[i].slice(2)] = args[++i];
|
|
31
|
+
else throw Error('Use observe --config FILE [--out NEW_DIRECTORY] [--json] [--interactive] [--steps FILE]');
|
|
29
32
|
}
|
|
30
33
|
if (!options.config) throw Error('--config is required');
|
|
31
34
|
const config = observationConfig(JSON.parse(await readFile(options.config, 'utf8')));
|
|
35
|
+
const steps = options.steps ? observationSteps(JSON.parse(await readFile(options.steps, 'utf8'))) : null;
|
|
32
36
|
let directory;
|
|
33
37
|
if (options.out) { directory = resolve(options.out); await mkdir(directory, { mode: 0o700 }); }
|
|
34
38
|
else { const parent = resolve('.recovery-probe'); await mkdir(parent, { recursive: true, mode: 0o700 }); directory = await mkdtemp(join(parent, 'observe-')); }
|
|
@@ -68,7 +72,9 @@ IPC requires the observation-capable development hook. See docs/observe.md.`);
|
|
|
68
72
|
input.on('line', () => { pendingMarkers = Math.min(50, pendingMarkers + 1); });
|
|
69
73
|
input.on('SIGINT', stop);
|
|
70
74
|
}
|
|
71
|
-
console.error(
|
|
75
|
+
console.error(steps
|
|
76
|
+
? `Observing for ${config.observationMs} ms without reloading. Running ${steps.length} scripted steps; they act on the app. Ctrl+C saves partial evidence.`
|
|
77
|
+
: `Observing for ${config.observationMs} ms without reloading. Navigate in the app now.${input ? ' Press Enter before each action to mark a new interval.' : ''} Ctrl+C saves partial evidence.`);
|
|
72
78
|
},
|
|
73
79
|
takeMarker() {
|
|
74
80
|
if (!pendingMarkers) return false;
|
|
@@ -76,6 +82,8 @@ IPC requires the observation-capable development hook. See docs/observe.md.`);
|
|
|
76
82
|
return true;
|
|
77
83
|
},
|
|
78
84
|
onInterval() { console.error('New observation interval.'); },
|
|
85
|
+
...(steps ? { operator: ({ mark, signal, elapsed }) => runSteps(page, steps, { mark, signal, elapsed,
|
|
86
|
+
log: r => console.error(`Step ${r.index} ${r.kind}${r.name ? ' ' + r.name : ''}: ${r.status} at ${(r.endedMs / 1000).toFixed(1)} s${r.error ? ' — ' + r.error : ''}`) }) } : {}),
|
|
79
87
|
});
|
|
80
88
|
} catch (error) {
|
|
81
89
|
report ??= { schemaVersion: 1, metadata: observationMetadata(), sampling: samplingMetrics(config.sampleMs).snapshot(), mode: 'fault-free observation', status: 'incomplete', captureComplete: false, intervals: [], findings: [], reloads: 0, injected: 0 };
|
|
@@ -88,13 +96,17 @@ IPC requires the observation-capable development hook. See docs/observe.md.`);
|
|
|
88
96
|
}
|
|
89
97
|
report.metadata.browserVersion = browserVersion;
|
|
90
98
|
await writeFile(join(directory, 'scenario.json'), JSON.stringify(config, null, 2), { mode: 0o600 });
|
|
99
|
+
if (steps) await writeFile(join(directory, 'steps.json'), JSON.stringify(steps, null, 2), { mode: 0o600 });
|
|
91
100
|
await writeFile(join(directory, 'report.json'), JSON.stringify(report, null, 2), { mode: 0o600 });
|
|
92
101
|
await writeFile(join(directory, 'report.html'), renderObservationReport(report), { mode: 0o600 });
|
|
93
102
|
if (options.json) console.log(JSON.stringify({ ...report, reportPath: join(directory, 'report.json') }));
|
|
94
103
|
else {
|
|
95
104
|
for (const i of report.intervals) console.log(`Interval ${i.index}: ${i.reads?.calls ?? '?'} reads, ${i.reads?.successes ?? '?'} successes, ${i.reads?.errors ?? '?'} errors${i.findings.length ? '; ' + i.findings.join(', ') : ''}`);
|
|
96
|
-
for (const finding of report.findings) console.log(`Interval ${finding.interval}: ${observationSummary(finding)}`);
|
|
97
|
-
for (const
|
|
105
|
+
for (const finding of report.findings) console.log(`Interval ${finding.interval}: ${finding.code === 'DELAYED_UI_UPDATE' ? 'DELAYED_UI_UPDATE — ' : ''}${observationSummary(finding)}`);
|
|
106
|
+
for (const effect of report.actionEffects ?? []) console.log(actionSummary(effect));
|
|
107
|
+
for (const line of comparisonDigest(report)) console.log(line);
|
|
108
|
+
for (const note of report.notes ?? []) console.log(`Note: ${note.note}`);
|
|
109
|
+
if (report.operator) console.log(`Scripted steps: ${report.operator.status}${report.operator.error ? ' — ' + report.operator.error : ''}`);
|
|
98
110
|
console.log(`Sampling: ${config.detail}; requested delay ${config.sampleMs} ms; measured mean cadence ${report.sampling.startToStart.meanMs ?? 'unavailable'} ms.`);
|
|
99
111
|
if (report.error) console.error(report.error);
|
|
100
112
|
console.log(`Capture: ${report.status} (not a health verdict)\nReport: ${join(directory, 'report.html')}`);
|
package/docs/ipc.md
CHANGED
|
@@ -39,6 +39,8 @@ Replace channel names with the exact existing read channels. Include the second
|
|
|
39
39
|
|
|
40
40
|
Set `RECOVERY_PROBE_IPC=1` and `RECOVERY_PROBE_IPC_MODULE` to the absolute `.cjs` path from step 1 when starting the development app. No company application's production dependency needs changing. Do not expose controls through preload or contextBridge.
|
|
41
41
|
|
|
42
|
+
For fault-free observation the hook also accepts optional `classify`, `pushChannels` and `classifyPush` options, which count calls per method label on shared channels and main-to-renderer pushes without storing arguments or payloads. See [Actions, tracked rows and delayed UI updates](observe.md#actions-tracked-rows-and-delayed-ui-updates).
|
|
43
|
+
|
|
42
44
|
Registration is captured using the public `ipcMain.handle` API. Install before registration, once per process. Unaffected calls keep their original arguments, receiver and return value/Promise. The adapter observes completion without recording arguments, results or full errors. Calling `dispose()` disarms and restores the registration function; existing dispatchers become transparent. Restart the development app to remove them entirely.
|
|
43
45
|
|
|
44
46
|
## 3. Enable both local debugging interfaces
|
package/docs/observe.md
CHANGED
|
@@ -106,9 +106,91 @@ In 0.3.0, each retained comparison also has `followUp` evidence from later compl
|
|
|
106
106
|
|
|
107
107
|
Tracking ends at the next operator interval or capture termination, including interruption. These are sampled comparisons, not a settling rule, continuous-visibility claim, identity assertion or recovery verdict. Read completions and later UI changes are not proof of causality. The existing 1000-comparison cap also bounds follow-up tracking.
|
|
108
108
|
|
|
109
|
+
## Actions, tracked rows and delayed UI updates
|
|
110
|
+
|
|
111
|
+
Available from **0.4.0-preview.1** (npm `next` tag; install that exact version). The development IPC hook must come from the same version.
|
|
112
|
+
|
|
113
|
+
These options are opt-in and extend the same fault-free capture. They answer "how long after the user's action did the screen show the right state, and did data arrive before it?"
|
|
114
|
+
|
|
115
|
+
```json
|
|
116
|
+
{
|
|
117
|
+
"transport": "ipc",
|
|
118
|
+
"channel": "app:invoke",
|
|
119
|
+
"methods": ["queue.read"],
|
|
120
|
+
"dataEvents": { "channel": "app:event", "methods": ["queue.changed"] },
|
|
121
|
+
"regionSelector": "#queue",
|
|
122
|
+
"contentSelector": { "css": "button.item-action", "text": "Move up" },
|
|
123
|
+
"rows": {
|
|
124
|
+
"selector": "li[data-item]",
|
|
125
|
+
"key": ".item-name",
|
|
126
|
+
"state": { "css": "button.item-action", "role": "button" },
|
|
127
|
+
"states": ["Pause", "Move up", "Resume"],
|
|
128
|
+
"aliases": { "second": "Exact name of the second item" }
|
|
129
|
+
},
|
|
130
|
+
"actions": [{ "name": "start", "selector": { "role": "button", "name": "Start" } }],
|
|
131
|
+
"lagThresholdMs": 2000,
|
|
132
|
+
"minUnchangedReads": 2,
|
|
133
|
+
"observationMs": 45000
|
|
134
|
+
}
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
### Selectors
|
|
138
|
+
|
|
139
|
+
`contentSelector`, `rows.selector`, `rows.key`, `rows.state` and action selectors accept a CSS string or `{ "css", "role", "name", "text" }`. `role` matches an explicit `role` attribute or the element's implicit role (button, link, row, cell, listitem, heading and similar). `name` matches the accessible name approximated as `aria-label`, `aria-labelledby` text, visible text, `title` or `alt`. `text` matches the element's normalized visible text exactly. `name` requires `role`. These literal values stay in the private `scenario.json`; the report never copies them.
|
|
140
|
+
|
|
141
|
+
### Actions
|
|
142
|
+
|
|
143
|
+
`actions` records clicks on configured elements during the capture: the configured action name, the time, and whether the browser marked the event as real user input (`trusted`). No other event data is stored. Each report action lists the tracked rows that appeared or changed afterwards, relative to the action (`actionEffects`). Times come from the page and observer wall clocks on the same machine.
|
|
144
|
+
|
|
145
|
+
### Tracked rows
|
|
146
|
+
|
|
147
|
+
`rows` follows each visible row in the region. The row key text is hashed (`key:` plus 16 hex characters) unless it exactly matches a configured alias, so the report can say "row ‘second’" without storing its text. The state element's text is recorded only if it is in the `states` allowlist; other text becomes `other`, and a missing state element becomes `none`. Row identity is only as stable as the key text you select: choose a name, not a progress value.
|
|
148
|
+
|
|
149
|
+
### Shared IPC channels and data events
|
|
150
|
+
|
|
151
|
+
When one IPC channel carries many kinds of calls (for example an SDK bridge), counting every call makes read evidence meaningless. Give the development hook a `classify(channel, args)` function that returns a short method label (`/^[\w.:/-]{1,100}$/`); the hook counts calls per label and never stores arguments. A classifier error or invalid label counts as `unclassified` and never affects the real call. Then select the read methods with `methods`.
|
|
152
|
+
|
|
153
|
+
Main-to-renderer pushes can be observed as data-change events. List their channels in the hook's `pushChannels`, optionally with `classifyPush(channel, args)`, and select them with `dataEvents`. The hook wraps `send` on the target window's WebContents only while an observation lease is active, counts sends and their times, never stores payloads, and removes the wrapper at the end of the lease. Fault plans never observe pushes.
|
|
154
|
+
|
|
155
|
+
```js
|
|
156
|
+
installIpcProbe(ipcMain, {
|
|
157
|
+
enabled: true, channels: ['app:invoke'], sender: () => mainWindow?.webContents,
|
|
158
|
+
classify: (_channel, [payload]) => methodNameOf(payload), // your app-specific, development-only code
|
|
159
|
+
pushChannels: ['app:event'], classifyPush: (_channel, [payload]) => eventNameOf(payload),
|
|
160
|
+
});
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
### `DELAYED_UI_UPDATE`
|
|
164
|
+
|
|
165
|
+
Reported when a tracked row kept an allowlisted state across at least `minUnchangedReads` completed selected reads and for at least `lagThresholdMs`, and then changed to another allowlisted state without a data event in the sampled change window. With `dataEvents` configured, the last data event must also be at least `lagThresholdMs` older than the change (basis `NO_DATA_EVENT_BEFORE_UI_CHANGE`). Without data events the basis is `UNCHANGED_ACROSS_READS`, because a later read could have carried the change. Confidence is medium only when data events are configured and the persisted state began within `lagThresholdMs` of a recorded action, the typical shape of optimistic UI state that outlives the real state; everything else is a low-confidence lead. A state driven by reads you did not select (for example per-item status calls) can also produce a low-confidence lead. The finding records the row, both states, how long the earlier state persisted, the completed reads and data events while it persisted, and the time since the last related action.
|
|
166
|
+
|
|
167
|
+
This is a lead, not a verdict. Read contents are never recorded, so the tool cannot prove that the data said the new state earlier. Typical causes are optimistic UI state that outlives the real state, timers, or render paths that ignore fresh data. Changes are only evaluated between consecutive samples of a visible row.
|
|
168
|
+
|
|
169
|
+
### Busy targets
|
|
170
|
+
|
|
171
|
+
If the selected target completes more than two reads per sample on average, per-completion comparisons cannot attribute UI changes. They are omitted and the report adds a `READ_COMPLETION_COMPARISONS_OMITTED` note; select `methods` to narrow the target. The terminal prints one comparison line per interval instead of one per comparison.
|
|
172
|
+
|
|
173
|
+
### Scripted steps (`--steps`)
|
|
174
|
+
|
|
175
|
+
`observe --config FILE --steps steps.json` runs an explicit operator script during the capture. Steps act on the app, so use them only with a test account and data you may change.
|
|
176
|
+
|
|
177
|
+
```json
|
|
178
|
+
[
|
|
179
|
+
{ "click": { "role": "button", "name": "Start A" } },
|
|
180
|
+
{ "wait": 1000 },
|
|
181
|
+
{ "mark": true },
|
|
182
|
+
{ "click": { "role": "button", "name": "Start B" }, "name": "start-second" },
|
|
183
|
+
{ "waitFor": "li[data-item]", "timeoutMs": 5000 },
|
|
184
|
+
{ "navigate": "#/queue" },
|
|
185
|
+
{ "wait": 12000 }
|
|
186
|
+
]
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
Each step has exactly one of `mark` (start a new interval and wait for it), `navigate` (same-document `#fragment` only; a document load would reset the state under observation), `click` (exactly one visible match, real input events through Playwright), `waitFor` (first visible match) or `wait` (milliseconds). `name` and `timeoutMs` are optional. Steps start once the capture is observing, run in order, and stop when the capture ends. A failed or unfinished script is reported in `operator` and adds the `OPERATOR_STEPS_INCOMPLETE` coverage gap. The validated steps are saved as a private `steps.json` next to the report. Without `--steps`, observation still never acts.
|
|
190
|
+
|
|
109
191
|
## Interpretation
|
|
110
192
|
|
|
111
|
-
Local `report.json` and `report.html` contain interval read counts, starts/completions, first-content sample bounds, and a change-only sampled timeline. `scenario.json` records the selected scope. No screenshots, response bodies or raw UI values are saved. Region text and repeated values are hashed; hashes are **not anonymization**, particularly for predictable text. Treat reports and selectors as private evidence.
|
|
193
|
+
Local `report.json` and `report.html` contain interval read counts, starts/completions, first-content sample bounds, and a change-only sampled timeline. `scenario.json` records the selected scope. No screenshots, response bodies, IPC arguments, push payloads or raw UI values are saved; tracked row keys are hashed and row states are kept only when allowlisted. Region text and repeated values are hashed; hashes are **not anonymization**, particularly for predictable text. Treat reports and selectors as private evidence.
|
|
112
194
|
|
|
113
195
|
`CONTENT_BEFORE_READ` means the configured content marker was sampled as visible with **no observed completion during that interval**. Its basis distinguishes zero observed starts from an outstanding read. This is an observation requiring interpretation, not a defect verdict. It may include content already present at the interval's first sample; that is recorded explicitly. A read begun in a previous interval is represented by `pendingAtStart`.
|
|
114
196
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "recovery-probe",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.0-preview.1",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Test recovery from failed reads in web and Electron desktop apps, during loading and refresh.",
|
|
6
6
|
"license": "MIT",
|
|
@@ -86,7 +86,7 @@
|
|
|
86
86
|
},
|
|
87
87
|
"publishConfig": {
|
|
88
88
|
"access": "public",
|
|
89
|
-
"tag": "
|
|
89
|
+
"tag": "next"
|
|
90
90
|
},
|
|
91
91
|
"keywords": [
|
|
92
92
|
"playwright",
|
|
@@ -104,7 +104,7 @@
|
|
|
104
104
|
"scripts": {
|
|
105
105
|
"test": "npm run test:core",
|
|
106
106
|
"test:core": "node --test test/fetch-core.test.mjs",
|
|
107
|
-
"test:browser": "node --test test/recovery.integration.test.mjs test/discovery.integration.test.mjs test/discovery-calibration.integration.test.mjs test/attach.integration.test.mjs test/refresh.integration.test.mjs test/observe.integration.test.mjs",
|
|
107
|
+
"test:browser": "node --test test/recovery.integration.test.mjs test/discovery.integration.test.mjs test/discovery-calibration.integration.test.mjs test/attach.integration.test.mjs test/refresh.integration.test.mjs test/observe.integration.test.mjs test/observe-queue.integration.test.mjs",
|
|
108
108
|
"test:package": "node --test test/package.integration.test.mjs",
|
|
109
109
|
"test:all": "npm run test:core && npm run test:package && npm run test:browser && npm run test:desktop && npm run test:repair && npm run test:guided && npm run test:ipc && npm run test:ci-example",
|
|
110
110
|
"demo": "node bin/core-demo.mjs",
|
|
@@ -115,8 +115,8 @@
|
|
|
115
115
|
"test:repair": "node --test test/repair.test.mjs test/repair.integration.test.mjs test/web.integration.test.mjs",
|
|
116
116
|
"test:repair:electron": "node --test test/repair.electron.test.mjs",
|
|
117
117
|
"test:guided": "node --test test/guided-start.test.mjs test/guided-start.integration.test.mjs",
|
|
118
|
-
"test:ipc": "node --test test/ipc-probe.test.mjs test/ipc-control.test.mjs test/ipc-observation.test.mjs test/visibility.test.mjs test/refresh.test.mjs test/observe.test.mjs test/observation-report.test.mjs",
|
|
119
|
-
"test:ipc:electron": "node --test --test-concurrency=1 test/ipc.electron.test.mjs test/observe.electron.test.mjs",
|
|
118
|
+
"test:ipc": "node --test test/ipc-probe.test.mjs test/ipc-control.test.mjs test/ipc-observation.test.mjs test/visibility.test.mjs test/refresh.test.mjs test/observe.test.mjs test/observation-report.test.mjs test/observe-features.test.mjs",
|
|
119
|
+
"test:ipc:electron": "node --test --test-concurrency=1 test/ipc.electron.test.mjs test/observe.electron.test.mjs test/observe-queue.electron.test.mjs",
|
|
120
120
|
"benchmark:observe": "node scripts/benchmark-observe.mjs",
|
|
121
121
|
"test:ci-example": "node examples/ci/verify.mjs"
|
|
122
122
|
}
|
package/src/ipc-observation.mjs
CHANGED
|
@@ -5,10 +5,16 @@ const hash = value => createHash('sha256').update(value).digest('hex');
|
|
|
5
5
|
export function readRegion(selector) {
|
|
6
6
|
const readStarted = performance.now();
|
|
7
7
|
const observation = typeof selector === 'object' && selector !== null ? selector : null;
|
|
8
|
-
|
|
8
|
+
// Observation may use the capture's in-page kit for text/role selectors, rows and actions.
|
|
9
|
+
const kit = observation ? globalThis.__recoveryProbeObserve : undefined;
|
|
10
|
+
if (observation?.kitToken && kit?.token !== observation.kitToken) throw new Error('OBSERVER_KIT_MISSING: the page was replaced or another observation owns it');
|
|
11
|
+
const select = (root, spec) => kit ? kit.select(root, spec) : [...root.querySelectorAll(spec)];
|
|
12
|
+
const normalize = value => String(value ?? '').replace(/\s+/g, ' ').trim();
|
|
13
|
+
const actions = () => observation?.kitToken ? kit.drainActions() : undefined;
|
|
14
|
+
const finish = value => observation ? { ...value, actions: actions(), rendererReadMs: performance.now() - readStarted } : value;
|
|
9
15
|
if (observation) {
|
|
10
16
|
selector = observation.regionSelector;
|
|
11
|
-
document
|
|
17
|
+
select(document, observation.contentSelector); // Validate even when the region is absent.
|
|
12
18
|
}
|
|
13
19
|
const roots = selector ? document.querySelectorAll(selector) : null;
|
|
14
20
|
if (observation && roots?.length === 0) return finish({ presence: 'absent', contentCount: 0, visible: document.visibilityState === 'visible', online: navigator.onLine });
|
|
@@ -24,20 +30,30 @@ export function readRegion(selector) {
|
|
|
24
30
|
return visibility.get(e);
|
|
25
31
|
};
|
|
26
32
|
if (observation && !visible(root)) return finish({ presence: 'hidden', contentCount: 0, visible: document.visibilityState === 'visible', online: navigator.onLine });
|
|
27
|
-
let content;
|
|
33
|
+
let content, rows;
|
|
28
34
|
if (observation) {
|
|
29
|
-
const matches = root
|
|
35
|
+
const matches = select(root, observation.contentSelector);
|
|
30
36
|
const texts = [];
|
|
31
37
|
let remaining = 200000, truncated = matches.length > 1000;
|
|
32
38
|
for (const e of [...matches].slice(0, 1000)) {
|
|
33
39
|
if (!visible(e)) continue;
|
|
34
|
-
const text = (e.innerText
|
|
40
|
+
const text = normalize(e.innerText);
|
|
35
41
|
if (text.length > remaining) truncated = true;
|
|
36
42
|
texts.push(text.slice(0, remaining)); remaining = Math.max(0, remaining - text.length);
|
|
37
43
|
}
|
|
38
44
|
content = { texts, truncated };
|
|
45
|
+
// Row key and state text are returned transiently; Node hashes keys and keeps only allowlisted states.
|
|
46
|
+
if (observation.rows) {
|
|
47
|
+
const r = observation.rows;
|
|
48
|
+
const elements = select(root, r.selector).filter(visible);
|
|
49
|
+
rows = { truncated: elements.length > 500, items: elements.slice(0, 500).map(element => {
|
|
50
|
+
const keyElement = r.key ? select(element, r.key).find(visible) : element;
|
|
51
|
+
const stateElement = select(element, r.state).find(visible);
|
|
52
|
+
return { key: keyElement ? normalize(keyElement.innerText).slice(0, 500) : '', state: stateElement ? normalize(stateElement.innerText).slice(0, 100) : null };
|
|
53
|
+
}) };
|
|
54
|
+
}
|
|
39
55
|
if (observation.detail === 'content') return finish({ presence: 'visible', contentCount: texts.length,
|
|
40
|
-
content, truncated, visible: document.visibilityState === 'visible', online: navigator.onLine });
|
|
56
|
+
content, rows, truncated, visible: document.visibilityState === 'visible', online: navigator.onLine });
|
|
41
57
|
}
|
|
42
58
|
const nodes = [...root.querySelectorAll('*')].filter(visible).slice(0, 5000);
|
|
43
59
|
const count = s => [...root.querySelectorAll(s)].filter(visible).length;
|
|
@@ -81,7 +97,7 @@ export function readRegion(selector) {
|
|
|
81
97
|
}
|
|
82
98
|
}
|
|
83
99
|
return finish({ text, structure, groups, distributions,
|
|
84
|
-
...(observation ? { presence: 'visible', contentCount: content.texts.length, content } : {}),
|
|
100
|
+
...(observation ? { presence: 'visible', contentCount: content.texts.length, content, rows } : {}),
|
|
85
101
|
region: selector ? 'selected' : root === document.body ? 'body' : 'main',
|
|
86
102
|
truncated: root.querySelectorAll('*').length > 5000 || Boolean(content?.truncated),
|
|
87
103
|
visible: document.visibilityState === 'visible', online: navigator.onLine,
|
|
@@ -94,7 +110,7 @@ export function readRegion(selector) {
|
|
|
94
110
|
});
|
|
95
111
|
}
|
|
96
112
|
export function summarizeRegion(raw) {
|
|
97
|
-
const { text, distributions = {}, content, rendererReadMs: _timing, ...summary } = raw;
|
|
113
|
+
const { text, distributions = {}, content, rows: _rows, actions: _actions, rendererReadMs: _timing, ...summary } = raw;
|
|
98
114
|
if (content) summary.content = { basis: 'ordered-visible-marker-text', count: content.texts.length,
|
|
99
115
|
textLength: content.texts.reduce((sum, value) => sum + value.length, 0),
|
|
100
116
|
textFingerprint: hash(JSON.stringify(content.texts)), truncated: content.truncated };
|
package/src/ipc-probe.cjs
CHANGED
|
@@ -2,24 +2,34 @@
|
|
|
2
2
|
const { version } = require('../package.json');
|
|
3
3
|
|
|
4
4
|
const installed = new WeakSet();
|
|
5
|
+
const MAX_LABELS = 200;
|
|
6
|
+
// Labels are developer-chosen method names, never argument values.
|
|
7
|
+
const label = value => typeof value === 'string' && /^[\w.:/-]{1,100}$/.test(value) ? value : null;
|
|
8
|
+
const readStats = () => ({ calls: 0, successes: 0, errors: 0, pending: 0, firstReadAt: null, lastReadAt: null, firstCompletedAt: null, lastCompletedAt: null, lastSuccessAt: null });
|
|
5
9
|
|
|
6
10
|
// No Electron import: use its public registration API, supplied by the development app.
|
|
7
|
-
exports.installIpcProbe = function installIpcProbe(ipcMain, { channels, sender, enabled = false } = {}) {
|
|
11
|
+
exports.installIpcProbe = function installIpcProbe(ipcMain, { channels, sender, enabled = false, classify, pushChannels = [], classifyPush } = {}) {
|
|
8
12
|
if (enabled !== true) throw new Error('IPC probe requires explicit development-only enablement');
|
|
9
13
|
if (!Array.isArray(channels) || !channels.length || channels.some(c => typeof c !== 'string' || !c.trim()) || new Set(channels).size !== channels.length) throw new Error('Provide unique, explicitly allowed read channels');
|
|
10
14
|
if (typeof sender !== 'function' || typeof ipcMain?.handle !== 'function') throw new Error('Provide ipcMain and a sender function returning the target WebContents');
|
|
15
|
+
if (classify !== undefined && typeof classify !== 'function') throw new Error('classify must be a function returning a method label');
|
|
16
|
+
if (classifyPush !== undefined && typeof classifyPush !== 'function') throw new Error('classifyPush must be a function returning an event label');
|
|
17
|
+
if (!Array.isArray(pushChannels) || pushChannels.some(c => typeof c !== 'string' || !c.trim()) || new Set(pushChannels).size !== pushChannels.length) throw new Error('pushChannels must be unique channel names');
|
|
11
18
|
if (installed.has(ipcMain)) throw new Error('IPC probe already installed; restart the development app to reinstall');
|
|
12
19
|
const allowed = new Set(channels);
|
|
20
|
+
const allowedPushes = new Set(pushChannels);
|
|
13
21
|
const registered = new Set();
|
|
14
22
|
const original = ipcMain.handle;
|
|
15
23
|
let active = true;
|
|
16
24
|
let state = null;
|
|
17
25
|
let timer;
|
|
26
|
+
let wrappedSend = null;
|
|
18
27
|
const seenIds = new Set();
|
|
28
|
+
const capabilities = () => ({ maxFaultCount: 10, observation: true, readTimestamps: true, methods: Boolean(classify), pushes: allowedPushes.size > 0 });
|
|
19
29
|
const identify = challenge => {
|
|
20
30
|
const contents = sender();
|
|
21
31
|
if (!contents || contents.isDestroyed()) throw new Error('Target WebContents is not available');
|
|
22
|
-
const identity = { version, runtime: { node: process.versions.node, electron: process.versions.electron ?? null, chrome: process.versions.chrome ?? null }, senderId: contents.id, pageUrl: contents.getURL(), registered: [...registered],
|
|
32
|
+
const identity = { version, runtime: { node: process.versions.node, electron: process.versions.electron ?? null, chrome: process.versions.chrome ?? null }, senderId: contents.id, pageUrl: contents.getURL(), registered: [...registered], pushChannels: [...allowedPushes], capabilities: capabilities() };
|
|
23
33
|
if (challenge === undefined) return identity;
|
|
24
34
|
if (typeof challenge !== 'string' || !/^[a-f0-9-]{36}$/.test(challenge)) throw new Error('Invalid window challenge');
|
|
25
35
|
return contents.executeJavaScript(`globalThis.__recoveryProbeWindowNonce === ${JSON.stringify(challenge)}`).then(matches => {
|
|
@@ -31,7 +41,37 @@ exports.installIpcProbe = function installIpcProbe(ipcMain, { channels, sender,
|
|
|
31
41
|
const contents = sender();
|
|
32
42
|
return contents && !contents.isDestroyed() && event?.sender === contents && contents.mainFrame && event.senderFrame === contents.mainFrame;
|
|
33
43
|
};
|
|
34
|
-
|
|
44
|
+
// A classifier failure or an unexpected label must never affect the real call.
|
|
45
|
+
const classifyCall = (fn, channel, args, table) => {
|
|
46
|
+
if (!fn) return null;
|
|
47
|
+
let name;
|
|
48
|
+
try { name = label(fn(channel, args)) ?? 'unclassified'; } catch { name = 'unclassified'; }
|
|
49
|
+
return table[name] || Object.keys(table).length < MAX_LABELS ? name : '(other)';
|
|
50
|
+
};
|
|
51
|
+
const unwrapSend = () => {
|
|
52
|
+
if (!wrappedSend) return;
|
|
53
|
+
const { contents, wrapper } = wrappedSend;
|
|
54
|
+
// Only remove our own instance property; the prototype method stays untouched.
|
|
55
|
+
if (!contents.isDestroyed?.() && Object.hasOwn(contents, 'send') && contents.send === wrapper) delete contents.send;
|
|
56
|
+
wrappedSend = null;
|
|
57
|
+
};
|
|
58
|
+
const wrapSend = (contents, current) => {
|
|
59
|
+
if (!allowedPushes.size || typeof contents?.send !== 'function') return;
|
|
60
|
+
const send = contents.send;
|
|
61
|
+
const wrapper = function (channel, ...args) {
|
|
62
|
+
if (state === current && current.observingUntil && Date.now() < current.observingUntil && allowedPushes.has(channel)) {
|
|
63
|
+
const at = Date.now();
|
|
64
|
+
const row = current.pushes[channel];
|
|
65
|
+
row.count++; row.firstAt ??= at; row.lastAt = at;
|
|
66
|
+
const name = classifyCall(classifyPush, channel, args, row.methods);
|
|
67
|
+
if (name) { const m = row.methods[name] ??= { count: 0, firstAt: null, lastAt: null }; m.count++; m.firstAt ??= at; m.lastAt = at; }
|
|
68
|
+
}
|
|
69
|
+
return Reflect.apply(send, this, [channel, ...args]);
|
|
70
|
+
};
|
|
71
|
+
Object.defineProperty(contents, 'send', { value: wrapper, configurable: true, writable: true });
|
|
72
|
+
wrappedSend = { contents, wrapper };
|
|
73
|
+
};
|
|
74
|
+
const disarm = () => { clearTimeout(timer); unwrapSend(); if (state) { state.armed = null; state.observingUntil = null; } };
|
|
35
75
|
const snapshot = () => {
|
|
36
76
|
if ((state?.armed && Date.now() >= state.armed.expiresAt) || (state?.observingUntil && Date.now() >= state.observingUntil)) disarm();
|
|
37
77
|
return state ? JSON.parse(JSON.stringify({ ...state, capturedAt: Date.now() })) : null;
|
|
@@ -52,8 +92,13 @@ exports.installIpcProbe = function installIpcProbe(ipcMain, { channels, sender,
|
|
|
52
92
|
if (state && Object.values(state.channels).some(c => c.pending)) throw new Error('Previous real calls are still pending; wait before beginning another run');
|
|
53
93
|
const identity = identify();
|
|
54
94
|
disarm(); seenIds.add(id);
|
|
55
|
-
state = { id, channel, senderId: identity.senderId, startedAt: Date.now(), observation, observingUntil: observation ? Date.now() + ttlMs : null, injected: 0, injectedAt: null, successfulAfterFault: 0, armed: fault ? { fault, remaining: times, expiresAt: Date.now() + ttlMs } : null, channels: Object.create(null) };
|
|
56
|
-
for (const name of watched) state.channels[name] = {
|
|
95
|
+
state = { id, channel, senderId: identity.senderId, startedAt: Date.now(), observation, observingUntil: observation ? Date.now() + ttlMs : null, injected: 0, injectedAt: null, successfulAfterFault: 0, armed: fault ? { fault, remaining: times, expiresAt: Date.now() + ttlMs } : null, channels: Object.create(null), pushes: Object.create(null) };
|
|
96
|
+
for (const name of watched) state.channels[name] = { ...readStats(), realCalls: 0, maxDurationMs: 0, ...(classify ? { methods: Object.create(null) } : {}) };
|
|
97
|
+
// Pushes are observation evidence only; they are never counted during fault plans.
|
|
98
|
+
if (observation) {
|
|
99
|
+
for (const name of allowedPushes) state.pushes[name] = { count: 0, firstAt: null, lastAt: null, methods: Object.create(null) };
|
|
100
|
+
wrapSend(sender(), state);
|
|
101
|
+
}
|
|
57
102
|
if (fault || observation) { timer = setTimeout(disarm, ttlMs); timer.unref?.(); }
|
|
58
103
|
return snapshot();
|
|
59
104
|
};
|
|
@@ -67,6 +112,9 @@ exports.installIpcProbe = function installIpcProbe(ipcMain, { channels, sender,
|
|
|
67
112
|
if (!row) return Reflect.apply(real, this, [event, ...args]);
|
|
68
113
|
row.calls++;
|
|
69
114
|
row.firstReadAt ??= Date.now(); row.lastReadAt = Date.now();
|
|
115
|
+
const name = row.methods ? classifyCall(classify, channel, args, row.methods) : null;
|
|
116
|
+
const method = name ? row.methods[name] ??= readStats() : null;
|
|
117
|
+
if (method) { method.calls++; method.firstReadAt ??= row.lastReadAt; method.lastReadAt = row.lastReadAt; }
|
|
70
118
|
if (current.armed && Date.now() >= current.armed.expiresAt) disarm();
|
|
71
119
|
if (channel === current.channel && current.armed) {
|
|
72
120
|
const fault = current.armed.fault;
|
|
@@ -75,15 +123,18 @@ exports.installIpcProbe = function installIpcProbe(ipcMain, { channels, sender,
|
|
|
75
123
|
return fault === 'null-result' ? Promise.resolve(null) : Promise.reject(new Error('Recovery Probe: injected IPC rejection'));
|
|
76
124
|
}
|
|
77
125
|
row.realCalls++; row.pending++;
|
|
126
|
+
if (method) method.pending++;
|
|
78
127
|
const started = Date.now();
|
|
79
128
|
const afterFault = current.injected > 0;
|
|
80
129
|
const finish = success => {
|
|
81
130
|
const completed = Date.now();
|
|
82
|
-
row
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
131
|
+
for (const stats of method ? [row, method] : [row]) {
|
|
132
|
+
stats.firstCompletedAt ??= completed; stats.lastCompletedAt = completed;
|
|
133
|
+
if (success) { stats.lastSuccessAt = completed; stats.successes++; } else stats.errors++;
|
|
134
|
+
stats.pending--;
|
|
135
|
+
}
|
|
136
|
+
row.maxDurationMs = Math.max(row.maxDurationMs, Date.now() - started);
|
|
137
|
+
if (success && afterFault && channel === current.channel) current.successfulAfterFault++;
|
|
87
138
|
};
|
|
88
139
|
let result;
|
|
89
140
|
try { result = Reflect.apply(real, this, [event, ...args]); }
|
package/src/ipc-probe.d.cts
CHANGED
|
@@ -1,16 +1,25 @@
|
|
|
1
1
|
export interface ProbeWebContents {
|
|
2
2
|
id: number; mainFrame: unknown; isDestroyed(): boolean; getURL(): string; executeJavaScript(code: string): Promise<unknown>;
|
|
3
|
+
send?(channel: string, ...args: unknown[]): void;
|
|
3
4
|
}
|
|
5
|
+
export interface IpcReadStats { calls: number; successes: number; errors: number; pending: number; firstReadAt: number | null; lastReadAt: number | null; firstCompletedAt: number | null; lastCompletedAt: number | null; lastSuccessAt: number | null }
|
|
6
|
+
export interface IpcPushStats { count: number; firstAt: number | null; lastAt: number | null }
|
|
4
7
|
export interface IpcSnapshot {
|
|
5
8
|
id: string; channel: string; senderId: number; injected: number;
|
|
6
9
|
startedAt: number; capturedAt: number; observation: boolean; observingUntil: number | null;
|
|
7
10
|
injectedAt: number | null; successfulAfterFault: number;
|
|
8
11
|
armed: { fault: 'rejection' | 'null-result'; remaining: number; expiresAt: number } | null;
|
|
9
|
-
channels: Record<string,
|
|
12
|
+
channels: Record<string, IpcReadStats & { realCalls: number; maxDurationMs: number; methods?: Record<string, IpcReadStats> }>;
|
|
13
|
+
/** Present for observation plans when push channels are configured. Counts and times only; no payloads. */
|
|
14
|
+
pushes: Record<string, IpcPushStats & { methods: Record<string, IpcPushStats> }>;
|
|
15
|
+
}
|
|
16
|
+
export interface IpcIdentity {
|
|
17
|
+
version: string; runtime: { node: string; electron: string | null; chrome: string | null }; senderId: number; pageUrl: string; registered: string[]; pushChannels: string[];
|
|
18
|
+
capabilities: { maxFaultCount: number; observation: true; readTimestamps: true; methods: boolean; pushes: boolean };
|
|
10
19
|
}
|
|
11
20
|
export interface IpcProbe {
|
|
12
|
-
identify():
|
|
13
|
-
identify(challenge: string): Promise<
|
|
21
|
+
identify(): IpcIdentity;
|
|
22
|
+
identify(challenge: string): Promise<IpcIdentity>;
|
|
14
23
|
begin(options: { id: string; channel: string; requiredChannels?: string[]; times?: number; ttlMs?: number } & ({ observation: true; fault?: never } | { observation?: false; fault?: 'rejection' | 'null-result' })): IpcSnapshot;
|
|
15
24
|
snapshot(): IpcSnapshot | null;
|
|
16
25
|
windowState(): { minimized: boolean };
|
|
@@ -18,4 +27,12 @@ export interface IpcProbe {
|
|
|
18
27
|
reset(id?: string): IpcSnapshot | null;
|
|
19
28
|
dispose(): void;
|
|
20
29
|
}
|
|
21
|
-
export function installIpcProbe(ipcMain: { handle(channel: string, listener: (...args: any[]) => any): void }, options: {
|
|
30
|
+
export function installIpcProbe(ipcMain: { handle(channel: string, listener: (...args: any[]) => any): void }, options: {
|
|
31
|
+
enabled: boolean; channels: string[]; sender: () => ProbeWebContents | undefined | null;
|
|
32
|
+
/** Development-only: returns a method label (/^[\w.:/-]{1,100}$/) for a call. Arguments are never stored. */
|
|
33
|
+
classify?: (channel: string, args: unknown[]) => string | null | undefined;
|
|
34
|
+
/** Main-to-renderer channels whose sends to the target window are counted during observation. */
|
|
35
|
+
pushChannels?: string[];
|
|
36
|
+
/** Development-only: returns an event label for a push. Payloads are never stored. */
|
|
37
|
+
classifyPush?: (channel: string, args: unknown[]) => string | null | undefined;
|
|
38
|
+
}): IpcProbe;
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
// In-page helpers for fault-free observation. Installed once per capture without
|
|
2
|
+
// reloading; removed at the end. Records only configured action names, times and
|
|
3
|
+
// whether the browser marked the click as a real user input.
|
|
4
|
+
|
|
5
|
+
const SELECTOR_KEYS = ['css', 'role', 'name', 'text'];
|
|
6
|
+
|
|
7
|
+
/** Node-side validation of a CSS string or { css, role, name, text } selector. */
|
|
8
|
+
export function selectorSpec(value, key) {
|
|
9
|
+
if (typeof value === 'string') {
|
|
10
|
+
if (!value.trim()) throw Error(`${key} must be a non-empty CSS selector`);
|
|
11
|
+
return value;
|
|
12
|
+
}
|
|
13
|
+
if (!value || typeof value !== 'object' || Array.isArray(value)) throw Error(`${key} must be a CSS selector string or { css, role, name, text }`);
|
|
14
|
+
for (const property of Object.keys(value)) if (!SELECTOR_KEYS.includes(property)) throw Error(`Unsupported ${key} property: ${property}`);
|
|
15
|
+
if (value.css === undefined && value.role === undefined) throw Error(`${key} needs css or role`);
|
|
16
|
+
if (value.css !== undefined && (typeof value.css !== 'string' || !value.css.trim())) throw Error(`${key}.css must be a non-empty CSS selector`);
|
|
17
|
+
if (value.role !== undefined && (typeof value.role !== 'string' || !/^[a-z]{2,30}$/.test(value.role))) throw Error(`${key}.role must be an ARIA role name`);
|
|
18
|
+
for (const property of ['name', 'text']) {
|
|
19
|
+
if (value[property] !== undefined && (typeof value[property] !== 'string' || !value[property].trim() || value[property].length > 200)) throw Error(`${key}.${property} must be 1–200 characters`);
|
|
20
|
+
}
|
|
21
|
+
if (value.name !== undefined && value.role === undefined) throw Error(`${key}.name requires role`);
|
|
22
|
+
return { ...value };
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
// Runs in the page. Self-contained: page.evaluate serializes this function.
|
|
26
|
+
export function installObserverKit({ token, actions, validate = [] }) {
|
|
27
|
+
const existing = globalThis.__recoveryProbeObserve;
|
|
28
|
+
if (existing) {
|
|
29
|
+
if (existing.token === token) return true;
|
|
30
|
+
// A capture polls its kit on every sample; one unpolled for 15 s was abandoned (for example a crashed CLI).
|
|
31
|
+
if (Date.now() - existing.lastPolledAt() < 15000) throw new Error('OBSERVER_ALREADY_ACTIVE: another observation owns this page');
|
|
32
|
+
existing.stop();
|
|
33
|
+
}
|
|
34
|
+
const normalize = value => String(value ?? '').replace(/\s+/g, ' ').trim();
|
|
35
|
+
const implicitRole = e => {
|
|
36
|
+
const tag = e.tagName.toLowerCase();
|
|
37
|
+
if (tag === 'button') return 'button';
|
|
38
|
+
if (tag === 'a' && e.hasAttribute('href')) return 'link';
|
|
39
|
+
if (tag === 'input') {
|
|
40
|
+
const type = (e.getAttribute('type') || 'text').toLowerCase();
|
|
41
|
+
if (['button', 'submit', 'reset', 'image'].includes(type)) return 'button';
|
|
42
|
+
return type === 'checkbox' || type === 'radio' ? type : 'textbox';
|
|
43
|
+
}
|
|
44
|
+
return { tr: 'row', td: 'cell', th: 'columnheader', li: 'listitem', ul: 'list', ol: 'list', table: 'table', img: 'img', textarea: 'textbox', select: 'combobox', nav: 'navigation', main: 'main', dialog: 'dialog' }[tag]
|
|
45
|
+
?? (/^h[1-6]$/.test(tag) ? 'heading' : null);
|
|
46
|
+
};
|
|
47
|
+
const roleOf = e => normalize(e.getAttribute('role')).split(' ')[0] || implicitRole(e);
|
|
48
|
+
// Approximation of the accessible name: aria-label, aria-labelledby, visible text, title/alt.
|
|
49
|
+
const nameOf = e => {
|
|
50
|
+
const labelledBy = normalize(e.getAttribute('aria-labelledby'));
|
|
51
|
+
const byIds = labelledBy ? labelledBy.split(' ').map(id => document.getElementById(id)?.innerText ?? '').join(' ') : '';
|
|
52
|
+
return normalize(e.getAttribute('aria-label') || byIds || e.innerText || e.getAttribute('title') || e.getAttribute('alt') || '');
|
|
53
|
+
};
|
|
54
|
+
const matches = (e, spec) => {
|
|
55
|
+
if (typeof spec === 'string') return e.matches(spec);
|
|
56
|
+
return (!spec.css || e.matches(spec.css)) && (!spec.role || roleOf(e) === spec.role)
|
|
57
|
+
&& (spec.name === undefined || nameOf(e) === spec.name) && (spec.text === undefined || normalize(e.innerText) === spec.text);
|
|
58
|
+
};
|
|
59
|
+
const select = (root, spec) => typeof spec === 'string'
|
|
60
|
+
? [...root.querySelectorAll(spec)]
|
|
61
|
+
: [...root.querySelectorAll(spec.css ?? '*')].filter(e => matches(e, spec));
|
|
62
|
+
const closest = (element, spec) => {
|
|
63
|
+
for (let node = element; node && node.nodeType === 1; node = node.parentElement) if (matches(node, spec)) return node;
|
|
64
|
+
return null;
|
|
65
|
+
};
|
|
66
|
+
// Validate every selector now, so a CSS error surfaces before the capture starts.
|
|
67
|
+
for (const spec of [...validate, ...actions.map(action => action.selector)]) select(document, spec);
|
|
68
|
+
const buffer = [];
|
|
69
|
+
let polledAt = Date.now();
|
|
70
|
+
const onClick = event => {
|
|
71
|
+
const target = event.target instanceof Element ? event.target : null;
|
|
72
|
+
if (!target) return;
|
|
73
|
+
for (const action of actions) {
|
|
74
|
+
if (!closest(target, action.selector)) continue;
|
|
75
|
+
buffer.push({ name: action.name, at: Date.now(), trusted: event.isTrusted });
|
|
76
|
+
if (buffer.length > 500) buffer.shift();
|
|
77
|
+
}
|
|
78
|
+
};
|
|
79
|
+
if (actions.length) document.addEventListener('click', onClick, true);
|
|
80
|
+
Object.defineProperty(globalThis, '__recoveryProbeObserve', {
|
|
81
|
+
configurable: true,
|
|
82
|
+
value: Object.freeze({ token, select, normalize, lastPolledAt: () => polledAt,
|
|
83
|
+
drainActions: () => { polledAt = Date.now(); return buffer.splice(0); },
|
|
84
|
+
stop: () => document.removeEventListener('click', onClick, true) }),
|
|
85
|
+
});
|
|
86
|
+
return true;
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
// Runs in the page.
|
|
90
|
+
export function removeObserverKit(token) {
|
|
91
|
+
const kit = globalThis.__recoveryProbeObserve;
|
|
92
|
+
if (!kit || kit.token !== token) return false;
|
|
93
|
+
kit.stop();
|
|
94
|
+
delete globalThis.__recoveryProbeObserve;
|
|
95
|
+
return true;
|
|
96
|
+
}
|
|
@@ -110,17 +110,69 @@ export function contentComparisons() {
|
|
|
110
110
|
};
|
|
111
111
|
}
|
|
112
112
|
|
|
113
|
+
const seconds = ms => (Math.round(ms / 100) / 10).toFixed(1);
|
|
114
|
+
const range = ([low, high]) => { const a = seconds(Math.max(0, low)), b = seconds(high); return a === b ? `about ${a} s` : `${a}–${b} s`; };
|
|
115
|
+
const rowName = row => row.startsWith('key:') ? `row ${row.slice(4, 12)}` : `row ‘${row}’`;
|
|
116
|
+
|
|
113
117
|
export function observationSummary(finding) {
|
|
118
|
+
if (finding.code === 'DELAYED_UI_UPDATE') {
|
|
119
|
+
const data = finding.basis === 'NO_DATA_EVENT_BEFORE_UI_CHANGE'
|
|
120
|
+
? `; no data event arrived in the change window${finding.sinceLastDataEventMs === null ? '' : ` (the last one was ${seconds(finding.sinceLastDataEventMs)} s earlier)`}`
|
|
121
|
+
: '; data events were not observed for this target';
|
|
122
|
+
const action = finding.afterAction ? ` The change came ${range(finding.afterAction.changedAfterActionMs)} after action ‘${finding.afterAction.name}’${finding.previousStateStartedAfterActionMs == null ? '; the earlier state did not start right after an action' : '; the earlier state started right after it'}.` : '';
|
|
123
|
+
return `${rowName(finding.row)[0].toUpperCase()}${rowName(finding.row).slice(1)} stayed ${finding.from} for ${seconds(finding.persistedMs)} s across ${finding.unchangedReadCompletions} completed selected reads, then changed to ${finding.to}${data}.${action}`;
|
|
124
|
+
}
|
|
114
125
|
if (finding.basis === 'NO_READ_OBSERVED_IN_INTERVAL') return 'Content was visible without a new selected read in this interval.';
|
|
115
126
|
if (finding.basis === 'NO_COMPLETION_OBSERVED_IN_INTERVAL') return 'Content was visible before any selected read completed in this interval (a read was pending or had started).';
|
|
116
127
|
return 'Content/read ordering was observed; inspect the evidence.';
|
|
117
128
|
}
|
|
118
129
|
|
|
130
|
+
/** Rows that appeared or changed after each configured action, relative to the action time. */
|
|
131
|
+
export function actionEffects(report) {
|
|
132
|
+
const actions = report.actions ?? [];
|
|
133
|
+
const same = (ref, action) => ref && ref.name === action.name && ref.atMs === action.atMs;
|
|
134
|
+
return actions.map(action => {
|
|
135
|
+
const appeared = (report.rows ?? []).filter(r => same(r.firstSeen.afterAction, action)).map(r => ({
|
|
136
|
+
row: r.row, state: r.firstSeen.state, appearedAfterMs: [r.firstSeen.fromMs - action.atMs, r.firstSeen.toMs - action.atMs],
|
|
137
|
+
changes: r.transitions.filter(t => same(t.afterAction, action)).map(t => ({ from: t.from, to: t.to, afterActionMs: [t.afterMs - action.atMs, t.byMs - action.atMs] })),
|
|
138
|
+
}));
|
|
139
|
+
const changed = (report.rows ?? []).filter(r => !same(r.firstSeen.afterAction, action)).flatMap(r => r.transitions.filter(t => same(t.afterAction, action))
|
|
140
|
+
.map(t => ({ row: r.row, from: t.from, to: t.to, afterActionMs: [t.afterMs - action.atMs, t.byMs - action.atMs] })));
|
|
141
|
+
return { ...action, appeared, changed };
|
|
142
|
+
});
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
export function actionSummary(effect) {
|
|
146
|
+
// Rows without a tracked state that merely appeared (for example after navigating) are counted, not listed.
|
|
147
|
+
const quiet = effect.appeared.filter(a => ['none', 'other'].includes(a.state) && !a.changes.length);
|
|
148
|
+
const parts = effect.appeared.filter(a => !quiet.includes(a)).map(a => `${rowName(a.row)} appeared ${range(a.appearedAfterMs)} later as ${a.state}${a.changes.map(c => `, then ${c.from} → ${c.to} ${range(c.afterActionMs)} after the action`).join('')}`);
|
|
149
|
+
parts.push(...effect.changed.map(c => `${rowName(c.row)} changed ${c.from} → ${c.to} ${range(c.afterActionMs)} after the action`));
|
|
150
|
+
if (quiet.length) parts.push(`${quiet.length} row${quiet.length === 1 ? '' : 's'} without a tracked state appeared`);
|
|
151
|
+
return `Action ‘${effect.name}’ at ${seconds(effect.atMs)} s (${effect.trusted ? 'trusted input' : 'scripted, untrusted event'}): ${parts.length ? parts.join('; ') : 'no tracked row appeared or changed'}.`;
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
/** One line per interval instead of one per comparison. */
|
|
155
|
+
export function comparisonDigest(report) {
|
|
156
|
+
const byInterval = new Map();
|
|
157
|
+
for (const c of report.comparisons ?? []) {
|
|
158
|
+
const entry = byInterval.get(c.interval) ?? {};
|
|
159
|
+
const key = `${c.basis === 'READ_COMPLETION' ? 'read-completion' : 'interval-return'} ${c.result}${c.basis === 'INTERVAL_RETURN' && c.result === 'changed' && c.followUp?.firstBaselineMatch ? ' (later matched)' : ''}`;
|
|
160
|
+
entry[key] = (entry[key] ?? 0) + 1;
|
|
161
|
+
byInterval.set(c.interval, entry);
|
|
162
|
+
}
|
|
163
|
+
return [...byInterval].map(([index, entry]) => `Interval ${index} comparisons: ${Object.entries(entry).map(([key, n]) => `${n} ${key}`).join(', ')}.`);
|
|
164
|
+
}
|
|
165
|
+
|
|
119
166
|
const escape = value => String(value).replace(/[&<>"']/g, c => ({ '&': '&', '<': '<', '>': '>', '"': '"', "'": ''' }[c]));
|
|
120
167
|
export function renderObservationReport(report) {
|
|
121
168
|
const rows = report.intervals.map(i => `<tr><td>${i.index}</td><td>${i.reads?.calls ?? 'unknown'}</td><td>${i.reads?.successes ?? 'unknown'}</td><td>${i.reads?.errors ?? 'unknown'}</td><td>${i.firstContent ? `${i.firstContent.fromMs - i.startMs}–${i.firstContent.toMs - i.startMs} ms` : 'not sampled'}</td></tr>`).join('');
|
|
122
169
|
const sampling = report.sampling;
|
|
123
170
|
const comparisons = (report.comparisons ?? []).map(c => `<p>Interval ${escape(c.interval)}: ${escape(c.summary)} ${c.completions ? `(${c.completions.successes} successful, ${c.completions.errors} failed read completions)` : `(${c.reads.calls} selected reads started in this interval)`} ${escape(comparisonFollowUpSummary(c))}</p>`).join('');
|
|
124
171
|
const phases = Object.entries(sampling?.phases ?? {}).map(([name, s]) => `<tr><td>${escape(name)}</td><td>${s.meanMs}</td><td>${s.maxMs}</td></tr>`).join('');
|
|
125
|
-
|
|
172
|
+
const effects = report.actionEffects ?? [];
|
|
173
|
+
const actionsHtml = effects.length ? `<h2>Actions</h2>${effects.map(e => `<p>${escape(actionSummary(e))}</p>`).join('')}` : '';
|
|
174
|
+
const rowsHtml = report.rows?.length ? `<h2>Tracked rows</h2><table><thead><tr><th>Row</th><th>First seen</th><th>State changes</th><th>Last state</th></tr></thead><tbody>${report.rows.map(r => `<tr><td>${escape(rowName(r.row))}</td><td>${seconds(r.firstSeen.fromMs)}–${seconds(r.firstSeen.toMs)} s as ${escape(r.firstSeen.state)}</td><td>${r.transitions.map(t => `${escape(t.from)} → ${escape(t.to)} at ${seconds(t.afterMs)}–${seconds(t.byMs)} s`).join('<br>') || 'none'}</td><td>${escape(r.lastState)}</td></tr>`).join('')}</tbody></table><p>Row keys are hashed unless an alias was configured. States outside the configured allowlist are recorded as “other”.</p>` : '';
|
|
175
|
+
const notes = (report.notes ?? []).map(n => `<p>Note: ${escape(n.note)}</p>`).join('');
|
|
176
|
+
const operatorHtml = report.operator ? `<p>Scripted steps: ${escape(report.operator.status)}${report.operator.error ? ` — ${escape(report.operator.error)}` : ''}.</p>` : '';
|
|
177
|
+
return `<!doctype html><meta charset="utf-8"><title>Recovery Probe observation</title><style>body{font:16px system-ui;max-width:1000px;margin:40px auto;padding:20px}td,th{text-align:left;padding:8px}pre{white-space:pre-wrap;overflow-wrap:anywhere}</style><h1>Fault-free observation</h1><p>Capture: ${escape(report.status)}. This is not a recovery or account-isolation verdict.</p><p>Recovery Probe ${escape(report.metadata?.recoveryProbeVersion ?? 'unknown')} · Node ${escape(report.metadata?.runtime?.node ?? 'unknown')} · Browser ${escape(report.metadata?.browserVersion ?? 'unknown')} · IPC hook ${escape(report.metadata?.ipcHook?.version ?? 'unknown / not applicable')}</p>${sampling ? `<p>Configured delay: ${sampling.requestedDelayMs} ms. Completed samples: ${sampling.completedSamples}. Mean sample duration: ${sampling.sampleDuration.meanMs ?? 'unavailable'} ms. Mean start-to-start cadence: ${sampling.startToStart.meanMs ?? 'unavailable'} ms (maximum ${sampling.startToStart.maxMs ?? 'unavailable'} ms).</p><p>${escape(sampling.note)}</p>` : ''}<p>Sampling detail: ${escape(report.detail ?? 'region (legacy)')}. Marker counts describe the configured content selector; generic region item counts are heuristics.</p>${phases ? `<table><thead><tr><th>Measured phase</th><th>Mean ms</th><th>Maximum ms</th></tr></thead><tbody>${phases}</tbody></table><p>Renderer read time is included in the UI round trip, not additional to it.</p>` : ''}<p>${escape(report.limitation ?? report.error)}</p><table><thead><tr><th>Interval</th><th>Reads started</th><th>Successes</th><th>Errors</th><th>First content sample bounds</th></tr></thead><tbody>${rows}</tbody></table>${report.findings.map(f => `<p>Interval ${f.interval}: ${escape(observationSummary(f))} <strong>${escape(f.code)}</strong> — ${escape(f.basis)}</p>`).join('')}${operatorHtml}${actionsHtml}${rowsHtml}${notes}${comparisons}<p>Comparisons concern sampled marker text and count, not ownership or freshness. A completion does not guarantee the UI has consumed its result.</p><p>Cleanup: ${escape(report.cleanup ?? 'unknown')}. The observation snapshot is from before cleanup; cleanupEvidence records the separate cleanup check when available.</p><details><summary>Evidence and coverage</summary><pre>${escape(JSON.stringify(report, null, 2))}</pre></details>`;
|
|
126
178
|
}
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
import { selectorSpec } from './observation-kit.mjs';
|
|
2
|
+
|
|
3
|
+
// Opt-in scripted operator for `observe --steps`. Steps act on the app (same-document
|
|
4
|
+
// navigation, clicks, waits and interval marks); observation itself never acts.
|
|
5
|
+
const NAME = /^[\w.-]{1,40}$/;
|
|
6
|
+
const KINDS = ['mark', 'navigate', 'click', 'waitFor', 'wait'];
|
|
7
|
+
|
|
8
|
+
export function observationSteps(input) {
|
|
9
|
+
const steps = Array.isArray(input) ? input : input?.steps;
|
|
10
|
+
if (!Array.isArray(steps) || !steps.length || steps.length > 50) throw Error('steps must list 1–50 steps');
|
|
11
|
+
return steps.map((step, i) => {
|
|
12
|
+
if (!step || typeof step !== 'object' || Array.isArray(step)) throw Error(`steps[${i}] must be an object`);
|
|
13
|
+
const kinds = KINDS.filter(k => Object.hasOwn(step, k));
|
|
14
|
+
if (kinds.length !== 1) throw Error(`steps[${i}] needs exactly one of ${KINDS.join(', ')}`);
|
|
15
|
+
const [kind] = kinds;
|
|
16
|
+
for (const key of Object.keys(step)) if (![kind, 'name', 'timeoutMs'].includes(key)) throw Error(`Unsupported steps[${i}] property: ${key}`);
|
|
17
|
+
if (step.name !== undefined && (typeof step.name !== 'string' || !NAME.test(step.name))) throw Error(`steps[${i}].name must match ${NAME}`);
|
|
18
|
+
const timeoutMs = step.timeoutMs ?? (kind === 'waitFor' ? 15000 : 10000);
|
|
19
|
+
if (!Number.isInteger(timeoutMs) || timeoutMs < 100 || timeoutMs > 60000) throw Error(`steps[${i}].timeoutMs must be 100–60000`);
|
|
20
|
+
const named = step.name ? { name: step.name } : {};
|
|
21
|
+
if (kind === 'mark') {
|
|
22
|
+
if (step.mark !== true) throw Error(`steps[${i}].mark must be true`);
|
|
23
|
+
return { kind, ...named };
|
|
24
|
+
}
|
|
25
|
+
if (kind === 'navigate') {
|
|
26
|
+
// Same-document fragment navigation only: a document load would reset the state under observation.
|
|
27
|
+
if (typeof step.navigate !== 'string' || !/^#\S{0,500}$/.test(step.navigate)) throw Error(`steps[${i}].navigate must be a same-document #fragment`);
|
|
28
|
+
return { kind, target: step.navigate, ...named };
|
|
29
|
+
}
|
|
30
|
+
if (kind === 'wait') {
|
|
31
|
+
if (!Number.isInteger(step.wait) || step.wait < 0 || step.wait > 60000) throw Error(`steps[${i}].wait must be 0–60000 ms`);
|
|
32
|
+
return { kind, ms: step.wait, ...named };
|
|
33
|
+
}
|
|
34
|
+
return { kind, target: selectorSpec(step[kind], `steps[${i}].${kind}`), timeoutMs, ...named };
|
|
35
|
+
});
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
const escapeRegExp = value => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
|
39
|
+
export function locate(page, spec) {
|
|
40
|
+
if (typeof spec === 'string') return page.locator(spec);
|
|
41
|
+
let locator = spec.css ? page.locator(spec.css) : null;
|
|
42
|
+
if (spec.role) {
|
|
43
|
+
const byRole = page.getByRole(spec.role, spec.name === undefined ? {} : { name: spec.name, exact: true });
|
|
44
|
+
locator = locator ? locator.and(byRole) : byRole;
|
|
45
|
+
}
|
|
46
|
+
if (spec.text !== undefined) locator = locator.filter({ hasText: new RegExp(`^\\s*${escapeRegExp(spec.text)}\\s*$`) });
|
|
47
|
+
return locator;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
function abortable(promise, signal) {
|
|
51
|
+
return new Promise((resolve, reject) => {
|
|
52
|
+
if (signal.aborted) { reject(Error('STEPS_STOPPED')); return; }
|
|
53
|
+
const stop = () => reject(Error('STEPS_STOPPED'));
|
|
54
|
+
signal.addEventListener('abort', stop, { once: true });
|
|
55
|
+
promise.then(value => { signal.removeEventListener('abort', stop); resolve(value); }, error => { signal.removeEventListener('abort', stop); reject(error); });
|
|
56
|
+
});
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/** Runs steps in order. Clicks require exactly one visible match and use real input events. */
|
|
60
|
+
export async function runSteps(page, steps, { mark, signal, elapsed, log = () => {} }) {
|
|
61
|
+
const results = [];
|
|
62
|
+
for (const [index, step] of steps.entries()) {
|
|
63
|
+
const result = { index, kind: step.kind, ...(step.name ? { name: step.name } : {}), startedMs: elapsed() };
|
|
64
|
+
results.push(result);
|
|
65
|
+
try {
|
|
66
|
+
if (step.kind === 'mark') result.interval = await abortable(mark(), signal);
|
|
67
|
+
else if (step.kind === 'navigate') await abortable(page.evaluate(fragment => { location.hash = fragment; }, step.target), signal);
|
|
68
|
+
else if (step.kind === 'wait') await abortable(new Promise(resolve => setTimeout(resolve, step.ms)), signal);
|
|
69
|
+
else if (step.kind === 'waitFor') await abortable(locate(page, step.target).filter({ visible: true }).first().waitFor({ state: 'visible', timeout: step.timeoutMs }), signal);
|
|
70
|
+
else {
|
|
71
|
+
const target = locate(page, step.target).filter({ visible: true });
|
|
72
|
+
const count = await abortable(target.count(), signal);
|
|
73
|
+
if (count !== 1) throw Error(`STEP_TARGET_NOT_UNIQUE: expected exactly one visible match, found ${count}`);
|
|
74
|
+
await abortable(target.click({ timeout: step.timeoutMs }), signal);
|
|
75
|
+
}
|
|
76
|
+
result.status = 'done';
|
|
77
|
+
} catch (error) {
|
|
78
|
+
result.status = 'failed';
|
|
79
|
+
result.error = String(error.message).split('\n')[0].slice(0, 300);
|
|
80
|
+
throw Object.assign(Error(`Step ${index} (${step.kind}) failed: ${result.error}`), { results });
|
|
81
|
+
} finally {
|
|
82
|
+
result.endedMs = elapsed();
|
|
83
|
+
log(result);
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
return results;
|
|
87
|
+
}
|
package/src/observe.mjs
CHANGED
|
@@ -1,21 +1,27 @@
|
|
|
1
|
-
import { observationMetadata, samplingMetrics, observationSummary, contentComparisons } from './observation-report.mjs';
|
|
1
|
+
import { observationMetadata, samplingMetrics, observationSummary, contentComparisons, actionEffects } from './observation-report.mjs';
|
|
2
2
|
import { performance } from 'node:perf_hooks';
|
|
3
|
-
import { randomUUID } from 'node:crypto';
|
|
3
|
+
import { randomUUID, createHash } from 'node:crypto';
|
|
4
4
|
import { readRegion, summarizeRegion } from './ipc-observation.mjs';
|
|
5
5
|
import { observeHttp } from './http-observer.mjs';
|
|
6
|
+
import { selectorSpec, installObserverKit, removeObserverKit } from './observation-kit.mjs';
|
|
7
|
+
|
|
8
|
+
const LABEL = /^[\w.:/-]{1,100}$/;
|
|
9
|
+
const NAME = /^[\w.-]{1,40}$/;
|
|
6
10
|
|
|
7
11
|
export function observationConfig(input) {
|
|
8
12
|
if (!input || typeof input !== 'object' || Array.isArray(input)) throw Error('Observation config must be an object');
|
|
9
13
|
const c = { transport: undefined, cdp: 'http://127.0.0.1:9222', inspector: 'http://127.0.0.1:9229', page: undefined, pageUrl: undefined,
|
|
10
|
-
channel: undefined,
|
|
14
|
+
channel: undefined, methods: undefined, dataEvents: undefined, endpoint: undefined, regionSelector: undefined, contentSelector: undefined,
|
|
15
|
+
rows: undefined, actions: undefined, lagThresholdMs: 2000, minUnchangedReads: 2, detail: 'content', observationMs: 30000, sampleMs: 100 };
|
|
11
16
|
for (const key of Object.keys(input)) {
|
|
12
17
|
if (!Object.hasOwn(c, key)) throw Error(`Unsupported observation option: ${key}`);
|
|
13
18
|
c[key] = input[key];
|
|
14
19
|
}
|
|
15
20
|
if (!['http', 'ipc'].includes(c.transport)) throw Error('transport must be http or ipc');
|
|
16
21
|
if (!['content', 'region'].includes(c.detail)) throw Error('detail must be content or region');
|
|
17
|
-
|
|
18
|
-
|
|
22
|
+
if (typeof c.regionSelector !== 'string' || !c.regionSelector.trim()) throw Error('regionSelector must be an explicit CSS selector');
|
|
23
|
+
c.contentSelector = selectorSpec(c.contentSelector, 'contentSelector');
|
|
24
|
+
for (const [key, low, high] of [['observationMs', 500, 120000], ['sampleMs', 50, 1000], ['lagThresholdMs', 500, 60000], ['minUnchangedReads', 1, 20]]) {
|
|
19
25
|
if (!Number.isInteger(c[key]) || c[key] < low || c[key] > high) throw Error(`${key} must be ${low}–${high}`);
|
|
20
26
|
}
|
|
21
27
|
if (c.page !== undefined && (!Number.isInteger(c.page) || c.page < 0)) throw Error('page must be a non-negative integer');
|
|
@@ -23,18 +29,79 @@ export function observationConfig(input) {
|
|
|
23
29
|
const url = new URL(c[key]);
|
|
24
30
|
if (!['http:', 'ws:'].includes(url.protocol) || !['localhost', '127.0.0.1', '[::1]'].includes(url.hostname) || url.username || url.password) throw Error(`${key} must be a loopback HTTP or WebSocket address without credentials`);
|
|
25
31
|
}
|
|
32
|
+
if (c.rows !== undefined) c.rows = rowsConfig(c.rows);
|
|
33
|
+
if (c.actions !== undefined) {
|
|
34
|
+
if (!Array.isArray(c.actions) || !c.actions.length || c.actions.length > 20) throw Error('actions must list 1–20 { name, selector } entries');
|
|
35
|
+
c.actions = c.actions.map((a, i) => {
|
|
36
|
+
if (!a || typeof a !== 'object' || Object.keys(a).some(k => !['name', 'selector'].includes(k))) throw Error(`actions[${i}] must be { name, selector }`);
|
|
37
|
+
if (typeof a.name !== 'string' || !NAME.test(a.name)) throw Error(`actions[${i}].name must match ${NAME}`);
|
|
38
|
+
return { name: a.name, selector: selectorSpec(a.selector, `actions[${i}].selector`) };
|
|
39
|
+
});
|
|
40
|
+
if (new Set(c.actions.map(a => a.name)).size !== c.actions.length) throw Error('action names must be unique');
|
|
41
|
+
}
|
|
26
42
|
if (c.transport === 'http') {
|
|
27
43
|
const url = new URL(c.endpoint);
|
|
28
44
|
if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) throw Error('endpoint must be HTTP(S) origin/path without credentials, query or fragment');
|
|
29
45
|
c.endpoint = url.href;
|
|
30
|
-
if (c.channel !== undefined) throw Error('channel
|
|
46
|
+
if (c.channel !== undefined || c.methods !== undefined || c.dataEvents !== undefined) throw Error('channel, methods and dataEvents are only supported with IPC');
|
|
31
47
|
} else {
|
|
32
48
|
if (typeof c.channel !== 'string' || !c.channel.trim()) throw Error('channel is required');
|
|
33
49
|
if (c.endpoint !== undefined || c.page !== undefined || c.pageUrl !== undefined) throw Error('IPC selects the window owned by its development hook');
|
|
50
|
+
if (c.methods !== undefined) c.methods = labels(c.methods, 'methods');
|
|
51
|
+
if (c.dataEvents !== undefined) {
|
|
52
|
+
const d = c.dataEvents;
|
|
53
|
+
if (!d || typeof d !== 'object' || Object.keys(d).some(k => !['channel', 'methods'].includes(k)) || typeof d.channel !== 'string' || !d.channel.trim()) throw Error('dataEvents must be { channel, methods? }');
|
|
54
|
+
c.dataEvents = { channel: d.channel, ...(d.methods === undefined ? {} : { methods: labels(d.methods, 'dataEvents.methods') }) };
|
|
55
|
+
}
|
|
34
56
|
}
|
|
35
57
|
return c;
|
|
36
58
|
}
|
|
37
59
|
|
|
60
|
+
function labels(value, key) {
|
|
61
|
+
if (!Array.isArray(value) || !value.length || value.length > 50 || value.some(v => typeof v !== 'string' || !LABEL.test(v)) || new Set(value).size !== value.length) throw Error(`${key} must list 1–50 unique labels matching ${LABEL}`);
|
|
62
|
+
return [...value];
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
function rowsConfig(r) {
|
|
66
|
+
if (!r || typeof r !== 'object' || Array.isArray(r)) throw Error('rows must be { selector, key?, state, states, aliases? }');
|
|
67
|
+
for (const k of Object.keys(r)) if (!['selector', 'key', 'state', 'states', 'aliases'].includes(k)) throw Error(`Unsupported rows property: ${k}`);
|
|
68
|
+
const states = r.states;
|
|
69
|
+
if (!Array.isArray(states) || !states.length || states.length > 20 || states.some(s => typeof s !== 'string' || !s.trim() || s.length > 60) || new Set(states).size !== states.length) throw Error('rows.states must list 1–20 unique visible state labels (1–60 characters)');
|
|
70
|
+
const aliases = r.aliases ?? {};
|
|
71
|
+
if (typeof aliases !== 'object' || Array.isArray(aliases) || Object.keys(aliases).length > 20) throw Error('rows.aliases must map up to 20 alias names to row key text');
|
|
72
|
+
for (const [alias, text] of Object.entries(aliases)) if (!NAME.test(alias) || typeof text !== 'string' || !text.trim() || text.length > 200) throw Error(`rows.aliases.${alias} must map a name matching ${NAME} to 1–200 characters of key text`);
|
|
73
|
+
return { selector: selectorSpec(r.selector, 'rows.selector'), ...(r.key === undefined ? {} : { key: selectorSpec(r.key, 'rows.key') }),
|
|
74
|
+
state: selectorSpec(r.state, 'rows.state'), states: [...states], aliases: { ...aliases } };
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
const zero = { calls: 0, successes: 0, errors: 0, pending: 0, firstReadAt: null, lastReadAt: null, firstCompletedAt: null, lastCompletedAt: null, lastSuccessAt: null };
|
|
78
|
+
// The selected read: a whole channel/endpoint, or only the configured method labels on a shared channel.
|
|
79
|
+
function selectedReads(snapshot, c) {
|
|
80
|
+
const row = snapshot.channels[c.transport === 'ipc' ? c.channel : c.endpoint];
|
|
81
|
+
if (!c.methods || !row) return row;
|
|
82
|
+
const total = { ...zero };
|
|
83
|
+
for (const name of c.methods) {
|
|
84
|
+
const m = row.methods?.[name];
|
|
85
|
+
if (!m) continue;
|
|
86
|
+
for (const k of ['calls', 'successes', 'errors', 'pending']) total[k] += m[k];
|
|
87
|
+
for (const k of ['lastReadAt', 'lastCompletedAt', 'lastSuccessAt']) total[k] = Math.max(total[k] ?? 0, m[k] ?? 0) || null;
|
|
88
|
+
for (const k of ['firstReadAt', 'firstCompletedAt']) total[k] = m[k] === null ? total[k] : Math.min(total[k] ?? Infinity, m[k]);
|
|
89
|
+
}
|
|
90
|
+
return total;
|
|
91
|
+
}
|
|
92
|
+
function dataEvents(snapshot, c) {
|
|
93
|
+
if (!c.dataEvents) return null;
|
|
94
|
+
const p = snapshot.pushes?.[c.dataEvents.channel];
|
|
95
|
+
if (!p) return { count: 0, lastAt: null };
|
|
96
|
+
if (!c.dataEvents.methods) return { count: p.count, lastAt: p.lastAt };
|
|
97
|
+
let count = 0, lastAt = null;
|
|
98
|
+
for (const name of c.dataEvents.methods) {
|
|
99
|
+
const m = p.methods?.[name];
|
|
100
|
+
if (m) { count += m.count; lastAt = Math.max(lastAt ?? 0, m.lastAt ?? 0) || lastAt; }
|
|
101
|
+
}
|
|
102
|
+
return { count, lastAt };
|
|
103
|
+
}
|
|
104
|
+
|
|
38
105
|
export function ipcObservationAdapter(control, config, senderId) {
|
|
39
106
|
let id, metadata = null;
|
|
40
107
|
return {
|
|
@@ -42,7 +109,9 @@ export function ipcObservationAdapter(control, config, senderId) {
|
|
|
42
109
|
async start() {
|
|
43
110
|
const identity = await control.call('identify');
|
|
44
111
|
if (!identity.capabilities?.observation || !identity.capabilities?.readTimestamps) throw Error('IPC_OBSERVATION_UNSUPPORTED: restart the development app with the new observation-capable hook');
|
|
45
|
-
|
|
112
|
+
if (config.methods && !identity.capabilities.methods) throw Error('IPC_METHODS_UNSUPPORTED: configure a classify function in the development hook');
|
|
113
|
+
if (config.dataEvents && (!identity.capabilities.pushes || !identity.pushChannels?.includes(config.dataEvents.channel))) throw Error('IPC_PUSHES_UNSUPPORTED: list dataEvents.channel in the development hook pushChannels');
|
|
114
|
+
metadata = { version: identity.version ?? null, runtime: { node: identity.runtime?.node ?? null, electron: identity.runtime?.electron ?? null, chrome: identity.runtime?.chrome ?? null }, capabilities: { observation: identity.capabilities.observation, readTimestamps: identity.capabilities.readTimestamps, maxFaultCount: identity.capabilities.maxFaultCount ?? null, methods: identity.capabilities.methods ?? false, pushes: identity.capabilities.pushes ?? false } };
|
|
46
115
|
if (identity.senderId !== senderId) throw Error('IPC_TARGET_CHANGED');
|
|
47
116
|
const previous = await control.call('snapshot');
|
|
48
117
|
if (previous?.armed || previous?.observingUntil) throw Error('IPC_PLAN_ALREADY_ACTIVE');
|
|
@@ -78,8 +147,81 @@ export function httpObservationAdapter(page, config) {
|
|
|
78
147
|
const counts = row => ({ calls: row.calls, successes: row.successes, errors: row.errors, pending: row.pending });
|
|
79
148
|
const delta = (row, base) => ({ calls: row.calls - base.calls, successes: row.successes - base.successes, errors: row.errors - base.errors, pending: row.pending, pendingAtStart: base.pending });
|
|
80
149
|
const age = (snapshot, at) => at === null ? null : Math.max(0, snapshot.capturedAt - at);
|
|
150
|
+
const completedOf = row => row.successes + row.errors;
|
|
151
|
+
const rowKeyHash = text => createHash('sha256').update(text).digest('hex').slice(0, 16);
|
|
152
|
+
|
|
153
|
+
// Row keys are hashed; only allowlisted state labels and configured aliases are kept.
|
|
154
|
+
export function summarizeRows(raw, r) {
|
|
155
|
+
if (!raw) return null;
|
|
156
|
+
const aliasOf = new Map(Object.entries(r.aliases).map(([alias, text]) => [text.replace(/\s+/g, ' ').trim(), alias]));
|
|
157
|
+
const seen = new Map();
|
|
158
|
+
const items = raw.items.map(({ key, state }) => {
|
|
159
|
+
let id = aliasOf.get(key) ?? `key:${rowKeyHash(key)}`;
|
|
160
|
+
const n = (seen.get(id) ?? 0) + 1; seen.set(id, n);
|
|
161
|
+
if (n > 1) id += `#${n}`;
|
|
162
|
+
return { row: id, state: state === null ? 'none' : r.states.includes(state) ? state : 'other' };
|
|
163
|
+
});
|
|
164
|
+
return { truncated: raw.truncated, items };
|
|
165
|
+
}
|
|
81
166
|
|
|
82
|
-
|
|
167
|
+
/**
|
|
168
|
+
* Tracks allowlisted row states across samples. A state that survived several completed
|
|
169
|
+
* selected reads and then changed with no data event to explain it is reported as
|
|
170
|
+
* DELAYED_UI_UPDATE: an observation that needs review, not a defect verdict.
|
|
171
|
+
*/
|
|
172
|
+
export function rowTracker(c) {
|
|
173
|
+
const rows = new Map(), findings = [], actions = [];
|
|
174
|
+
const tracked = state => c.rows.states.includes(state);
|
|
175
|
+
const lastActionBefore = ms => actions.filter(a => a.atMs <= ms).at(-1) ?? null;
|
|
176
|
+
return {
|
|
177
|
+
addActions(list) { actions.push(...list); },
|
|
178
|
+
add(s) {
|
|
179
|
+
for (const { row, state } of s.rows?.items ?? []) {
|
|
180
|
+
const entry = rows.get(row);
|
|
181
|
+
if (!entry) {
|
|
182
|
+
const action = lastActionBefore(s.toMs);
|
|
183
|
+
rows.set(row, { row, firstSeen: { interval: s.interval, fromMs: s.fromMs, toMs: s.toMs, state, afterAction: action && { name: action.name, atMs: action.atMs } },
|
|
184
|
+
transitions: [], current: { state, first: s, last: s } });
|
|
185
|
+
continue;
|
|
186
|
+
}
|
|
187
|
+
const { first, last } = entry.current;
|
|
188
|
+
if (entry.current.state === state) { entry.current.last = s; continue; }
|
|
189
|
+
const transition = { from: entry.current.state, to: state, interval: s.interval, afterMs: last.toMs, byMs: s.toMs };
|
|
190
|
+
const action = lastActionBefore(s.toMs);
|
|
191
|
+
if (action) transition.afterAction = { name: action.name, atMs: action.atMs };
|
|
192
|
+
entry.transitions.push(transition);
|
|
193
|
+
// Evaluate only consecutive observations of a visible row with both states allowlisted.
|
|
194
|
+
if (last.index === s.index - 1 && tracked(transition.from) && tracked(state)) {
|
|
195
|
+
const unchangedReads = last.completed - first.completed;
|
|
196
|
+
const persistedMs = last.toMs - first.fromMs;
|
|
197
|
+
const noDataInWindow = s.data === null || s.data.count === last.data.count;
|
|
198
|
+
const sinceDataMs = s.data?.lastAtMs == null ? null : transition.afterMs - s.data.lastAtMs;
|
|
199
|
+
const dataQuiet = s.data === null || sinceDataMs === null || sinceDataMs >= c.lagThresholdMs;
|
|
200
|
+
if (persistedMs >= c.lagThresholdMs && unchangedReads >= c.minUnchangedReads && noDataInWindow && dataQuiet) {
|
|
201
|
+
// A stale state that began right after a user action (for example an optimistic label) is the strongest lead.
|
|
202
|
+
const stateAction = lastActionBefore(first.toMs);
|
|
203
|
+
const startedAfterActionMs = stateAction && first.fromMs - stateAction.atMs <= c.lagThresholdMs ? Math.max(0, first.fromMs - stateAction.atMs) : null;
|
|
204
|
+
const finding = { code: 'DELAYED_UI_UPDATE', kind: 'observation', confidence: s.data && startedAfterActionMs !== null ? 'medium' : 'low',
|
|
205
|
+
basis: s.data ? 'NO_DATA_EVENT_BEFORE_UI_CHANGE' : 'UNCHANGED_ACROSS_READS', interval: s.interval, row,
|
|
206
|
+
from: transition.from, to: state, changedAfterMs: transition.afterMs, changedByMs: transition.byMs,
|
|
207
|
+
previousStateSinceMs: first.fromMs, previousStateStartedAfterActionMs: startedAfterActionMs, persistedMs, unchangedReadCompletions: unchangedReads,
|
|
208
|
+
dataEventsWhilePersisted: s.data ? last.data.count - first.data.count : null, sinceLastDataEventMs: sinceDataMs,
|
|
209
|
+
afterAction: transition.afterAction ? { ...transition.afterAction, changedAfterActionMs: [transition.afterMs - transition.afterAction.atMs, transition.byMs - transition.afterAction.atMs] } : null,
|
|
210
|
+
note: 'Row state persisted across completed selected reads and then changed without a data event in the sampled window. Read contents are not recorded, so this needs review against the application logic; it is not a defect verdict.' };
|
|
211
|
+
finding.summary = observationSummary(finding);
|
|
212
|
+
findings.push(finding);
|
|
213
|
+
}
|
|
214
|
+
}
|
|
215
|
+
entry.current = { state, first: s, last: s };
|
|
216
|
+
}
|
|
217
|
+
},
|
|
218
|
+
snapshot() {
|
|
219
|
+
return { rows: [...rows.values()].map(({ row, firstSeen, transitions, current }) => ({ row, firstSeen, transitions, lastState: current.state })), findings };
|
|
220
|
+
},
|
|
221
|
+
};
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
async function boundedUiRead(action, signal, timeoutMs = 5000) {
|
|
83
225
|
let timer, cancel;
|
|
84
226
|
try {
|
|
85
227
|
return await Promise.race([
|
|
@@ -88,7 +230,7 @@ async function boundedUiRead(action, signal) {
|
|
|
88
230
|
return action();
|
|
89
231
|
}),
|
|
90
232
|
new Promise((_, reject) => {
|
|
91
|
-
timer = setTimeout(() => reject(Error(
|
|
233
|
+
timer = setTimeout(() => reject(Error(`UI_SAMPLE_TIMEOUT: renderer did not respond within ${timeoutMs} ms`)), timeoutMs);
|
|
92
234
|
cancel = () => reject(Error('CAPTURE_INTERRUPTED'));
|
|
93
235
|
signal?.addEventListener('abort', cancel, { once: true });
|
|
94
236
|
}),
|
|
@@ -96,76 +238,118 @@ async function boundedUiRead(action, signal) {
|
|
|
96
238
|
} finally { clearTimeout(timer); signal?.removeEventListener('abort', cancel); }
|
|
97
239
|
}
|
|
98
240
|
|
|
99
|
-
/**
|
|
100
|
-
|
|
241
|
+
/**
|
|
242
|
+
* Observe only. No reload, navigation, routing, focus changes or final UI reset.
|
|
243
|
+
* An optional `operator` function may act on the app (for example explicit --steps); it
|
|
244
|
+
* receives `mark()` to open a new interval and its outcome is reported separately.
|
|
245
|
+
*/
|
|
246
|
+
export async function runObservation(page, input, adapter, { signal, takeMarker = () => false, onReady = () => {}, onInterval = () => {}, onSample = () => {}, operator } = {}) {
|
|
101
247
|
const c = observationConfig(input);
|
|
102
248
|
const target = c.transport === 'ipc' ? c.channel : c.endpoint;
|
|
103
249
|
const metrics = samplingMetrics(c.sampleMs);
|
|
104
250
|
const comparisons = contentComparisons();
|
|
105
|
-
const
|
|
106
|
-
|
|
251
|
+
const tracker = c.rows ? rowTracker(c) : null;
|
|
252
|
+
const report = { schemaVersion: 1, metadata: observationMetadata(), mode: 'fault-free observation', transport: c.transport, target, ...(c.methods ? { targetMethods: c.methods } : {}),
|
|
253
|
+
generatedAt: new Date().toISOString(), status: 'incomplete', captureComplete: false, observationMs: c.observationMs, sampleMs: c.sampleMs, detail: c.detail,
|
|
254
|
+
intervals: [], findings: [], comparisons: [], timeline: [], ...(c.actions ? { actions: [] } : {}), notes: [],
|
|
107
255
|
injected: 0, reloads: 0, cleanup: 'not-started',
|
|
108
256
|
coverage: { historyBeforeCapture: 'unknown', pendingBeforeCapture: 'unknown', scope: 'One selected renderer and read target; only calls starting during capture are counted.', gaps: [] },
|
|
109
|
-
limitation: 'Observations are not recovery passes or account-isolation verdicts. Cache reuse may be legitimate. Intervals start at capture or an operator marker, not at a proven mount or identity change. HTTP success means a completed 2xx response, not valid JSON or UI correctness. UI changes between samples can be missed. Only hashes, structural counts and read metadata are stored; hashes are not anonymization.' };
|
|
110
|
-
let lastSnapshot, interval, started, previousSignature, samples = 0;
|
|
111
|
-
let attempted = false, pageErrors = 0, newDocument = false;
|
|
257
|
+
limitation: 'Observations are not recovery passes or account-isolation verdicts. Cache reuse may be legitimate. Intervals start at capture or an operator marker, not at a proven mount or identity change. HTTP success means a completed 2xx response, not valid JSON or UI correctness. UI changes between samples can be missed. Only hashes, structural counts, allowlisted row states, configured action names and read metadata are stored; hashes are not anonymization.' };
|
|
258
|
+
let lastSnapshot, interval, started, startedEpoch, previousSignature, samples = 0, kitToken;
|
|
259
|
+
let attempted = false, pageErrors = 0, newDocument = false, operatorRun, markerRequests = [];
|
|
260
|
+
const operatorAbort = new AbortController();
|
|
112
261
|
const errors = () => { pageErrors++; };
|
|
113
262
|
// A document load destroys the state being investigated. SPA route changes are allowed.
|
|
114
263
|
const documentLoaded = () => { newDocument = true; };
|
|
115
264
|
const elapsed = () => Math.round(performance.now() - started);
|
|
265
|
+
const channelRow = s => s.channels[target];
|
|
116
266
|
const openInterval = s => {
|
|
117
|
-
const row = s
|
|
118
|
-
interval = { index: report.intervals.length + 1, startMs: elapsed(), startCounts: counts(row), firstContent: null, samples: 0, findings: []
|
|
267
|
+
const row = selectedReads(s, c);
|
|
268
|
+
interval = { index: report.intervals.length + 1, startMs: elapsed(), startCounts: counts(row), firstContent: null, samples: 0, findings: [],
|
|
269
|
+
...(c.methods ? { startChannelCounts: counts(channelRow(s)) } : {}), ...(c.dataEvents ? { startDataEvents: dataEvents(s, c).count } : {}) };
|
|
119
270
|
report.intervals.push(interval);
|
|
120
271
|
previousSignature = undefined;
|
|
121
272
|
};
|
|
122
273
|
const closeInterval = () => {
|
|
123
274
|
if (!interval || !lastSnapshot) return;
|
|
124
275
|
interval.endMs = elapsed();
|
|
125
|
-
interval.reads = delta(lastSnapshot
|
|
276
|
+
interval.reads = delta(selectedReads(lastSnapshot, c), interval.startCounts);
|
|
277
|
+
if (c.methods) interval.channelReads = delta(channelRow(lastSnapshot), interval.startChannelCounts);
|
|
278
|
+
if (c.dataEvents) interval.dataEvents = dataEvents(lastSnapshot, c).count - interval.startDataEvents;
|
|
279
|
+
delete interval.startChannelCounts; delete interval.startDataEvents;
|
|
126
280
|
};
|
|
127
281
|
const gap = code => { if (!report.coverage.gaps.includes(code)) report.coverage.gaps.push(code); };
|
|
282
|
+
const takeAnyMarker = () => {
|
|
283
|
+
if (markerRequests.length) return markerRequests.shift();
|
|
284
|
+
return takeMarker() ? {} : null;
|
|
285
|
+
};
|
|
128
286
|
try {
|
|
129
|
-
|
|
130
|
-
|
|
287
|
+
kitToken = randomUUID();
|
|
288
|
+
const readInput = { regionSelector: c.regionSelector, contentSelector: c.contentSelector, detail: c.detail, kitToken, ...(c.rows ? { rows: { selector: c.rows.selector, key: c.rows.key, state: c.rows.state } } : {}) };
|
|
289
|
+
// One renderer call installs the kit and validates every selector without requiring the region to be mounted yet.
|
|
290
|
+
const validate = [c.regionSelector, c.contentSelector, ...(c.rows ? [c.rows.selector, ...(c.rows.key ? [c.rows.key] : []), c.rows.state] : [])];
|
|
291
|
+
await boundedUiRead(() => page.evaluate(installObserverKit, { token: kitToken, actions: c.actions ?? [], validate }), signal);
|
|
131
292
|
page.on('pageerror', errors); page.on('domcontentloaded', documentLoaded);
|
|
132
293
|
attempted = true;
|
|
133
294
|
await adapter.start();
|
|
134
295
|
report.metadata.ipcHook = adapter.metadata?.() ?? null;
|
|
135
|
-
started = performance.now();
|
|
296
|
+
started = performance.now(); startedEpoch = Date.now();
|
|
136
297
|
lastSnapshot = await adapter.snapshot();
|
|
137
298
|
report.startedAt = lastSnapshot.startedAt;
|
|
138
299
|
openInterval(lastSnapshot);
|
|
139
300
|
await onReady();
|
|
301
|
+
if (operator) {
|
|
302
|
+
const mark = () => new Promise(resolve => markerRequests.push({ resolve }));
|
|
303
|
+
operatorRun = Promise.resolve().then(() => operator({ mark, signal: operatorAbort.signal, elapsed }))
|
|
304
|
+
.then(steps => ({ status: 'complete', ...(Array.isArray(steps) ? { steps } : {}) }),
|
|
305
|
+
error => ({ status: operatorAbort.signal.aborted ? 'stopped' : 'failed', error: error.message, ...(Array.isArray(error.results) ? { steps: error.results } : {}) }));
|
|
306
|
+
}
|
|
140
307
|
while (true) {
|
|
141
308
|
if (signal?.aborted) { report.status = 'interrupted'; break; }
|
|
142
309
|
if (newDocument) throw Error('DOCUMENT_REPLACED: capture stopped; the in-memory state may have been reset');
|
|
143
|
-
|
|
310
|
+
const marker = takeAnyMarker();
|
|
311
|
+
if (marker) {
|
|
144
312
|
if (report.intervals.length >= 50) throw Error('INTERVAL_LIMIT_REACHED');
|
|
145
313
|
// Use a fresh boundary snapshot; do not attribute between-sample reads to the next interval.
|
|
146
314
|
lastSnapshot = await adapter.snapshot(); closeInterval(); openInterval(lastSnapshot);
|
|
147
315
|
await onInterval(interval.index);
|
|
316
|
+
marker.resolve?.(interval.index);
|
|
148
317
|
}
|
|
149
318
|
const beforeStart = performance.now();
|
|
150
319
|
const before = await adapter.snapshot();
|
|
151
320
|
const uiStart = performance.now();
|
|
152
321
|
const sampleStart = elapsed();
|
|
153
|
-
const { rendererReadMs, ...raw } = await boundedUiRead(() => page.evaluate(readRegion,
|
|
322
|
+
const { rendererReadMs, rows: rawRows, actions: rawActions, ...raw } = await boundedUiRead(() => page.evaluate(readRegion, readInput), signal);
|
|
154
323
|
const summarizeStart = performance.now();
|
|
155
324
|
const ui = raw.presence === 'visible' ? summarizeRegion(raw) : raw;
|
|
325
|
+
const rows = c.rows ? summarizeRows(rawRows, c.rows) : null;
|
|
156
326
|
const afterStart = performance.now();
|
|
157
327
|
const after = await adapter.snapshot();
|
|
158
328
|
const afterEnd = performance.now();
|
|
159
329
|
if (newDocument) throw Error('DOCUMENT_REPLACED: capture stopped; the in-memory state may have been reset');
|
|
160
330
|
lastSnapshot = after;
|
|
161
|
-
const row = after
|
|
331
|
+
const row = selectedReads(after, c);
|
|
162
332
|
if (!row || !Object.hasOwn(row, 'lastCompletedAt')) throw Error('READ_TIMESTAMPS_UNAVAILABLE');
|
|
163
333
|
if (!ui.visible) gap('HIDDEN_DOCUMENT');
|
|
164
334
|
if (ui.truncated) gap('TRUNCATED_REGION');
|
|
335
|
+
if (rows?.truncated) gap('TRUNCATED_ROWS');
|
|
165
336
|
const readCounts = delta(row, interval.startCounts);
|
|
166
|
-
const
|
|
167
|
-
|
|
168
|
-
|
|
337
|
+
const data = dataEvents(after, c);
|
|
338
|
+
const event = { interval: interval.index, fromMs: sampleStart, toMs: elapsed(), ui, ...(rows ? { rows } : {}),
|
|
339
|
+
reads: readCounts, before: counts(selectedReads(before, c)), after: counts(row),
|
|
340
|
+
lastReadAgeMs: age(after, row.lastReadAt), lastCompletionAgeMs: age(after, row.lastCompletedAt),
|
|
341
|
+
...(data ? { dataEvents: data.count - interval.startDataEvents, lastDataEventAgeMs: age(after, data.lastAt) } : {}), pageErrors };
|
|
342
|
+
if (rawActions?.length && report.actions) {
|
|
343
|
+
for (const a of rawActions) {
|
|
344
|
+
const atMs = a.at - startedEpoch;
|
|
345
|
+
const owner = [...report.intervals].reverse().find(i => i.startMs <= atMs) ?? report.intervals[0];
|
|
346
|
+
const action = { name: a.name, atMs, trusted: a.trusted, interval: owner.index };
|
|
347
|
+
if (report.actions.length < 200) report.actions.push(action); else gap('ACTION_LIMIT_REACHED');
|
|
348
|
+
}
|
|
349
|
+
tracker?.addActions(report.actions.slice(-rawActions.length));
|
|
350
|
+
}
|
|
351
|
+
tracker?.add({ index: samples, interval: interval.index, fromMs: sampleStart, toMs: event.toMs, rows,
|
|
352
|
+
completed: completedOf(row), data: data && { count: data.count, lastAtMs: data.lastAt === null ? null : data.lastAt - startedEpoch } });
|
|
169
353
|
if (ui.visible && ui.contentCount > 0 && !interval.firstContent) {
|
|
170
354
|
interval.firstContent = { fromMs: sampleStart, toMs: event.toMs, alreadyPresentAtFirstSample: interval.samples === 0,
|
|
171
355
|
reads: readCounts, lastReadAgeMs: event.lastReadAgeMs, lastCompletionAgeMs: event.lastCompletionAgeMs };
|
|
@@ -178,7 +362,7 @@ export async function runObservation(page, input, adapter, { signal, takeMarker
|
|
|
178
362
|
finding.summary = observationSummary(finding);
|
|
179
363
|
interval.findings.push(finding.code); report.findings.push(finding);
|
|
180
364
|
}
|
|
181
|
-
const signature = JSON.stringify([interval.index, ui, readCounts, pageErrors]);
|
|
365
|
+
const signature = JSON.stringify([interval.index, ui, rows, readCounts, event.dataEvents, pageErrors]);
|
|
182
366
|
if (signature !== previousSignature) {
|
|
183
367
|
if (report.timeline.length < 1000) report.timeline.push(event); else gap('TIMELINE_LIMIT_REACHED');
|
|
184
368
|
previousSignature = signature;
|
|
@@ -197,6 +381,15 @@ export async function runObservation(page, input, adapter, { signal, takeMarker
|
|
|
197
381
|
report.status = signal?.aborted ? 'interrupted' : 'incomplete';
|
|
198
382
|
if (!signal?.aborted) report.error = error.message;
|
|
199
383
|
} finally {
|
|
384
|
+
operatorAbort.abort();
|
|
385
|
+
for (const pending of markerRequests) pending.resolve?.(null);
|
|
386
|
+
if (operatorRun) {
|
|
387
|
+
let timer;
|
|
388
|
+
// An operator that ignores the stop signal must not hold cleanup hostage.
|
|
389
|
+
report.operator = await Promise.race([operatorRun, new Promise(resolve => { timer = setTimeout(() => resolve({ status: 'stopped', error: 'Operator did not stop within 5000 ms' }), 5000); })]);
|
|
390
|
+
clearTimeout(timer);
|
|
391
|
+
if (report.operator.status !== 'complete') gap('OPERATOR_STEPS_INCOMPLETE');
|
|
392
|
+
}
|
|
200
393
|
if (interval) closeInterval();
|
|
201
394
|
report.elapsedMs = started === undefined ? 0 : elapsed();
|
|
202
395
|
report.samples = samples;
|
|
@@ -204,10 +397,26 @@ export async function runObservation(page, input, adapter, { signal, takeMarker
|
|
|
204
397
|
report.snapshot = lastSnapshot;
|
|
205
398
|
report.snapshotStage = 'before-cleanup';
|
|
206
399
|
page.off('pageerror', errors); page.off('domcontentloaded', documentLoaded);
|
|
400
|
+
// Bounded: a replaced or unresponsive document must not delay owned IPC cleanup.
|
|
401
|
+
if (kitToken) { try { await boundedUiRead(() => page.evaluate(removeObserverKit, kitToken), undefined, 1000); } catch { /* Nothing left to remove. */ } }
|
|
207
402
|
if (attempted) {
|
|
208
403
|
try { report.cleanupEvidence = await adapter.stop() ?? null; report.cleanup = 'complete'; }
|
|
209
404
|
catch (error) { report.cleanup = 'unverified'; report.cleanupError = error.message; report.status = 'incomplete'; }
|
|
210
405
|
}
|
|
406
|
+
if (tracker) {
|
|
407
|
+
const t = tracker.snapshot();
|
|
408
|
+
report.rows = t.rows;
|
|
409
|
+
report.findings.push(...t.findings);
|
|
410
|
+
}
|
|
411
|
+
if (report.actions) report.actionEffects = actionEffects(report);
|
|
412
|
+
// Read-completion comparisons are not meaningful when many selected reads finish during every sample.
|
|
413
|
+
const completions = report.intervals.reduce((sum, i) => sum + (i.reads ? i.reads.successes + i.reads.errors : 0), 0);
|
|
414
|
+
if (samples > 0 && completions / samples > 2) {
|
|
415
|
+
const omitted = report.comparisons.filter(cmp => cmp.basis === 'READ_COMPLETION').length;
|
|
416
|
+
report.comparisons = report.comparisons.filter(cmp => cmp.basis !== 'READ_COMPLETION');
|
|
417
|
+
report.notes.push({ code: 'READ_COMPLETION_COMPARISONS_OMITTED', completionsPerSample: Math.round(completions / samples * 100) / 100, omitted,
|
|
418
|
+
note: 'The selected target completed more than two reads per sample on average, so per-completion comparisons cannot attribute UI changes. Select specific methods to narrow the target.' });
|
|
419
|
+
}
|
|
211
420
|
if (samples > 0 && !report.intervals.some(i => i.firstContent)) gap('CONTENT_MARKER_NOT_OBSERVED');
|
|
212
421
|
report.captureComplete = report.status === 'complete' && report.coverage.gaps.length === 0;
|
|
213
422
|
}
|