browser-commander 0.17.2 → 0.19.0

package/.jscpd-baseline.json

@@ -14,7 +14,6 @@
     "0b48b63049c42591": 1,
     "0b8c71391c107a5e": 1,
     "0ba2d165b56db0b3": 1,
-    "0c8a29320e45bdfa": 1,
     "0ca2d9c2f2b44d6c": 1,
     "0caa402c4eae32d8": 1,
     "0fd23be8410c2c95": 1,
@@ -28,7 +27,6 @@
     "16340a16ed52849e": 1,
     "17c26c0db2d35ad1": 1,
     "193b46c0e7f72053": 1,
-    "1ac9fbd87efdb313": 1,
     "1ad4dc7e19a77f68": 1,
     "1c1baf1bc8ea0eae": 1,
     "1cbd39b416a2b94b": 1,
@@ -48,6 +46,7 @@
     "266b9cb95f783cdf": 1,
     "26bb09996580437c": 1,
     "26ebb2e251c9a39e": 1,
+    "29edfb9e08094991": 1,
     "2a78ee4b05679c8d": 1,
     "2b1a759e2cfd21a2": 1,
     "2c0f8b5c6f28420b": 1,
@@ -57,6 +56,7 @@
     "2f9e15467cc2f12a": 1,
     "3101802d3ea65339": 1,
     "33357ce94e07cc4b": 1,
+    "35cf2769645f3234": 1,
     "37bd4114d0089f49": 1,
     "389df6fb4b8315a1": 1,
     "39eaada6d1879f4a": 1,
@@ -77,15 +77,12 @@
     "4c3b94caa28045d0": 1,
     "4e090d6bb30e6551": 1,
     "4f3c541b3f3e3f23": 1,
-    "4fe5663c69a426cb": 1,
-    "505d98bd14b63a6c": 1,
     "5085765e1f103f3e": 1,
     "5184c90c9f8406c3": 1,
     "520a28ee2ced56c2": 1,
     "53519ec61a6ba319": 1,
     "53f7e3f3e444a37d": 1,
     "5587ec0cdb7b96e6": 1,
-    "559b5241047cd753": 1,
     "562ebfb882d4aa8f": 1,
     "56b5df15ee61887d": 1,
     "56b7675e4ce57335": 1,
@@ -102,11 +99,12 @@
     "608e1dd27138ec6f": 1,
     "6098544c77ff17a2": 1,
     "60d0c58a01fc8746": 1,
+    "61ae5da6cc003836": 1,
     "61bcadcd8dc9f63e": 1,
-    "63a3b672c8d8b50b": 1,
     "63ff613b1780c67a": 1,
     "642cc89ed49f8a21": 1,
     "6479c3604c153ec4": 1,
+    "6699064d6e8e09ba": 1,
     "66fb97eebd7ff0dc": 1,
     "67a95e428b8fa31c": 1,
     "6880d620e0e67229": 1,
@@ -115,10 +113,13 @@
     "6af3c307939ef75e": 1,
     "6b35b48512756192": 1,
     "6cd00d6b6a039022": 1,
+    "6da3fe1d15b66ae0": 1,
     "6e2457cd3e1f69e7": 1,
+    "6f30e86d1407e88c": 1,
     "6fa62e2642cc73c3": 1,
     "7009c5e9bd61dbe8": 1,
     "709348ea44394b52": 1,
+    "72705e6a2212d7b2": 1,
     "731fbc5d4188839a": 1,
     "73dbf56d17ab79ed": 1,
     "760d9925f6e3ca85": 1,
@@ -141,28 +142,22 @@
     "8678919f1350f154": 1,
     "86aae81b1aa0d21b": 1,
     "87484a2744e09748": 1,
-    "87514cf1299c9c0e": 1,
     "876d2c8edfc8c40a": 1,
     "8b013ac20e436d76": 1,
     "8c2b1408886c1db1": 1,
-    "8cb9a984bf19a062": 1,
     "8ec18cdbd4a96518": 1,
-    "8ecf2e554a04d2ef": 1,
     "91049efadc65169b": 1,
     "9134185980de8a17": 1,
     "916833bafca4fa63": 1,
     "91a538e4a0c28f25": 1,
-    "929fba5228e9fdac": 1,
     "92ddafa7e65be7eb": 1,
     "94821a4d1b745dfd": 1,
-    "94d89888ac9da9a9": 1,
     "97c5a112fdde7be8": 1,
     "98cc22079feaa004": 1,
     "990d87f21678fa96": 1,
     "9a72b1c2f22156ca": 1,
     "9b6ef4df04562546": 1,
     "9c055dfd90c369bf": 1,
-    "9cb19f1b972e811e": 1,
     "9ee57dcd5e7a6691": 1,
     "9fbb8296259dedbe": 1,
     "a0183465782b0b15": 1,
@@ -175,25 +170,26 @@
     "a78d76908162699e": 1,
     "a9bd4ffef6da5faf": 1,
     "a9d71c2e50f1b832": 1,
-    "abe5a58f2b2cc593": 1,
     "acc95d694eb2f581": 1,
     "ad4469f2e8131535": 1,
     "ad4cfa76daa1b6fc": 1,
+    "ad50b48938af8aef": 1,
     "adae1329361a81a1": 1,
     "ae477ba64bafba3f": 1,
     "aee1e5c65f783848": 1,
     "aee45e8b58c2d87f": 1,
+    "af702b20ebd45ef2": 1,
     "af9d6a2f4eba146e": 1,
     "b010686af23efa90": 1,
     "b2a0686231220c8a": 1,
     "b35ff46c365dcd18": 1,
     "b41581af204af40e": 1,
-    "b62f3449cde7991d": 1,
     "b71fa5250da28739": 1,
     "b740ecac685a15fe": 1,
     "b8c2d21f2a26f77d": 1,
     "bb269582b94ed42d": 1,
     "bb3e6d0f7e7edccd": 1,
+    "bc9115be3a462930": 1,
     "bccf0d5cc57c08df": 1,
     "bd0ae42c13d5b4f9": 1,
     "bd6c62a6e1c6a071": 1,
@@ -209,6 +205,7 @@
     "c415ffcd004d6518": 1,
     "c461a83b51eb7740": 1,
     "c9cf3c28bed33a5b": 1,
+    "cab590a1d04b5a05": 1,
     "cbd444e9a6a9072e": 1,
     "cd49f39b43d14635": 1,
     "cebff7d1cc87f646": 1,
@@ -221,7 +218,6 @@
     "d1a4a8e6a523b752": 1,
     "d1e5c2961267399a": 1,
     "d2ed3d02dd6a2d8c": 1,
-    "d4eec99f58906a63": 1,
     "d6157a86fea41907": 1,
     "d6fa9884eee815f0": 1,
     "d86bafb915488255": 1,
@@ -239,7 +235,6 @@
     "ea1195048ded896c": 1,
     "ea88711c5deb1fe5": 1,
     "eb9a70c2a21094ff": 1,
-    "ebd08637a2d7bcf3": 1,
     "ebe03c5f8c2f5147": 1,
     "ee19c8b9b332ee98": 1,
     "eeca0ccf8d821f21": 1,
@@ -253,11 +248,11 @@
     "f4bfa7e503443cd1": 1,
     "f6678d6748e9c902": 1,
     "f67a07a611f39cb2": 1,
+    "f7b1f9d699bcd580": 1,
     "f911821aa7dda47f": 1,
     "f97bf515bfd95829": 1,
     "fae844842fba705b": 1,
     "faf76ec43b2dbbaa": 1,
-    "fb3a2e9ace145907": 1,
     "fc6ed7d760c98f51": 1,
     "fccfd8b004c12dd4": 1,
     "fe859df9f97c75d4": 1

package/CHANGELOG.md

@@ -1,5 +1,73 @@
 # Changelog
 
+## 0.19.0
+
+### Minor Changes
+
+- 4401d63: Record traces continuously across navigation and live state, and export them as
+  Links Notation.
+
+  `startTrace({mode: 'continuous'})` now keeps recording when the page navigates,
+  changes route or creates a frame: the observers are reinstalled from an init
+  script that runs before the page's own code, so nothing that happens during a
+  load is lost. What a person changes but the DOM does not show - typing,
+  checking, selecting, focus and scroll - is recorded as semantic live-state
+  records and applied on replay, child-list records carry the position a node was
+  inserted at or removed from, and every record carries stable trace, browser
+  context, page, navigation, frame and action identities. `initialCheckpoint` (on
+  by default) captures the page before the first action so the first interval has
+  a base to replay onto, and the viewer says what it is: a diagnostic replay of
+  what was recorded, not a re-execution of the session.
+
+  `writeTraceLinks(trace, './run.lino', {include})` writes a portable Links
+  Notation view of a bundle, and `startTrace({links: {output}})` writes the same
+  view incrementally as the run happens. One link per line: one per ordered
+  timeline event with its sequence, time, kind, owner ids, actor, action, target
+  and outcome; one per checkpoint naming its HTML, state and screenshot members by
+  their path inside the bundle; one per control that changed between two
+  checkpoints. Dropped and partial records are explicit, binary content is never
+  duplicated, and redaction is whatever the bundle already decided. The JSON
+  bundle stays authoritative - this is an adapter, not a replacement.
+
+  A managed download whose CDP completion arrives before the file does is no
+  longer reported as a missing file: the staged bytes are waited for, and a
+  timeout or a genuinely missing file is still a failure rather than a path that
+  does not exist.
+
+## 0.18.0
+
+### Minor Changes
+
+- 0915dd8: Add managed downloads, portable traces and truthful click results.
+
+  `downloads` is now accepted by `launchBrowser()`, `connectBrowser()` and
+  `launchRealBrowser()`, and by `commander.configureDownloads()` on a browser you
+  already have. The manager owns the file rather than the page: `capture()` starts
+  listening before the action runs so a fast download cannot be missed, a caller
+  can choose the saved name and have a bare UUID given the extension its content
+  proves, and the file is still there after the context and the browser are gone.
+  Failed and cancelled downloads report the failure instead of a path, and
+  `browser-commander/tests` keeps captured files in the run's artifact directory.
+
+  `startTrace()` records a session into a schema-versioned bundle - an ordered
+  NDJSON timeline, named checkpoints with full HTML, live control state and frame
+  metadata, and the DOM mutation batches between them - which `readTrace()`,
+  `diffControlState()` and the offline `writeTraceViewer()` read back with scripts
+  and network disabled. Redaction runs before anything is written, a truncated or
+  interrupted run still produces a readable partial trace, and
+  `browser-commander/tests` supports `trace: 'retain-on-failure'` in place of its
+  own artifact mechanism.
+
+  `clickElement()` now reports what was observed: `status` is `succeeded`,
+  `failed`, `timed_out`, `interrupted` or `unverified`, `effect` is `confirmed`,
+  `not-observed` or `contradicted`, and `evidence` carries the reason for both.
+  The `clicked` and `verified` booleans remain and are derived conservatively, so
+  a click that changed nothing is no longer reported as verified. `waitForReady()`
+  composes URL, network, DOM, image and custom checks under one deadline and
+  returns the same per-check evidence. `noAutoScroll` is deprecated in favour of
+  the `scroll` axis; `scroll: 'none'` now fails with a `ScrollConstraintError` on
+  engines that cannot click without scrolling instead of scrolling anyway.
+
 ## 0.17.2
 
 ### Patch Changes

package/README.md

@@ -599,6 +599,138 @@ await keyDown({ page, engine: 'playwright', key: 'Control' });
 await keyUp({ page, engine: 'playwright', key: 'Control' });
 ```
 
+### Managed Downloads
+
+A download that only exists while the browser is open is not a download. Ask for
+`downloads` at any entry point - `launchBrowser()`, `connectBrowser()`,
+`launchRealBrowser()` or `commander.configureDownloads()` - and the manager owns
+the file from then on:
+
+```javascript
+const { commander, downloads } = await launchBrowser({
+  downloads: { directory: '/tmp/reports', conflict: 'rename' },
+});
+
+// capture() starts listening before the action runs, so a download that
+// finishes in 5ms cannot slip past the registration.
+const artifact = await downloads.capture({
+  action: () => commander.clickButton({ selector: '#export' }),
+  filename: 'q3-report.pdf', // the page's UUID name gets the caller's name
+  timeout: 30000,
+});
+
+console.log(artifact.path, artifact.bytes, artifact.checksum);
+
+await commander.destroy();
+// The file is still there: it outlives the page, the context and the browser.
+```
+
+`downloads.on(DOWNLOAD_EVENT.COMPLETED, ...)` observes every download in the
+session, including one a person started by hand in a visible browser, and each
+download is reported exactly once whether it was captured or merely observed. A
+failed or cancelled download raises the failure rather than returning a path.
+
+### Portable Traces
+
+`startTrace()` records a session into a schema-versioned bundle any of the three
+languages can read - the manifest, an ordered NDJSON timeline, per-checkpoint
+DOM snapshots and the mutation batches between them:
+
+```javascript
+import { startTrace, readTrace, writeTraceViewer } from 'browser-commander';
+
+const trace = await startTrace({
+  commander,
+  output: '/tmp/traces/checkout',
+  mode: 'continuous', // keeps DOM mutations between checkpoints
+  privacy: { redact: [/password/i, /token/i] },
+});
+
+await commander.goto({ url: 'https://example.com/checkout' });
+await trace.checkpoint('cart');
+await commander.clickButton({ selector: '#pay' });
+await trace.checkpoint('paid');
+
+const { path } = await trace.stop();
+const bundle = await readTrace(path);
+await writeTraceViewer(bundle, '/tmp/traces/checkout/viewer.html');
+```
+
+Redaction runs before anything reaches disk, and a run cut short by a closed
+page or a size limit still leaves a readable partial trace. In `continuous`
+mode the observers are reinstalled from an init script before the page's own
+code runs, so a trace keeps recording across navigations, SPA route changes and
+same-document updates, and it records what a person cannot see in the DOM -
+typing, checking, selecting, focus and scroll - as semantic live-state records
+(issue #93). `initialCheckpoint` (on by default) captures the page as it was
+before the first action, so the first interval has a base to replay onto. The
+viewer seeks, diffs and replays the captured DOM with scripts and network
+disabled; it is a diagnostic replay of what was recorded, not a pixel-accurate
+re-execution of the session.
+
+#### Links Notation Export
+
+The bundle stays authoritative, and `writeTraceLinks()` writes a second,
+portable view of it for tools that keep semantic, actor-aware histories - audit
+graphs, agent memory, cross-run diffing (issue #94):
+
+```javascript
+import { readTrace, writeTraceLinks } from 'browser-commander';
+
+const trace = await readTrace('./run.bc-trace');
+await writeTraceLinks(trace, './run.lino', {
+  include: ['timeline', 'checkpoints', 'control-diffs'],
+});
+```
+
+A long-lived agent can have the same export written as the run happens, so a
+process that is killed still leaves everything it had recorded:
+
+```javascript
+const trace = await commander.startTrace({
+  output: './run.bc-trace',
+  links: { output: './run.lino' },
+});
+// trace.links === './run.lino'
+```
+
+One link per line: one `(timeline: ...)` link per ordered event carrying its
+sequence, time, kind, owner ids, actor, action, target and outcome; one
+`(checkpoint: ...)` link naming its HTML, state and screenshot members by their
+path inside the bundle; one `(control-diff: ...)` link per control that changed
+between two checkpoints, with `path`, `before`, `after` and who changed it.
+Dropped and partial records are written as such rather than left out, no binary
+content is ever copied into the export, and redaction is whatever the bundle
+already decided - the export only reads what was written there. The
+representation is pinned by a golden test against
+[`links-notation`](https://www.npmjs.com/package/links-notation) 0.20, whose
+Python and Rust implementations read the same file;
+`experiments/trace-links-export.mjs` records a real run and parses its export
+from Python to prove it.
+
+### Truthful Click Results
+
+`clickElement()` reports what was observed, not what was attempted:
+
+```javascript
+const result = await clickElement({
+  page,
+  engine,
+  locatorOrElement: '#submit',
+});
+
+result.status; // 'succeeded' | 'failed' | 'timed_out' | 'interrupted' | 'unverified'
+result.effect; // 'confirmed' | 'not-observed' | 'contradicted'
+result.evidence; // why status and effect say what they say
+result.clicked; // still here: whether the click reached the element
+result.verified; // still here, now derived from effect === 'confirmed'
+```
+
+The `scroll` axis (`auto`, `preserve`, `none`) replaces the deprecated
+`noAutoScroll` flag. `scroll: 'none'` never scrolls: on an engine that cannot
+deliver a click without scrolling it throws `ScrollConstraintError` naming the
+alternatives, rather than scrolling the page and reporting success.
+
 ### commander.destroy()
 
 ```javascript

package/eslint.config.js

@@ -22,6 +22,7 @@ export default [
         __filename: 'readonly',
         // Node.js 18+ globals
         fetch: 'readonly',
+        performance: 'readonly',
         // Web/Node.js shared globals
         setTimeout: 'readonly',
         clearTimeout: 'readonly',
@@ -50,6 +51,10 @@ export default [
         // Chrome verbatim rather than executed by Node).
         document: 'readonly',
         window: 'readonly',
+        location: 'readonly',
+        MutationObserver: 'readonly',
+        DOMParser: 'readonly',
+        Node: 'readonly',
         navigator: 'readonly',
         Navigator: 'readonly',
         screen: 'readonly',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-commander",
-  "version": "0.17.2",
+  "version": "0.19.0",
   "description": "Universal browser automation library that supports both Playwright and Puppeteer with a unified API",
   "main": "src/index.js",
   "type": "module",
@@ -16,6 +16,9 @@
     "test:e2e:playwright": "node scripts/run-tests.mjs --env RUN_E2E=true tests/e2e/playwright.e2e.test.js",
     "test:e2e:puppeteer": "node scripts/run-tests.mjs --env RUN_E2E=true tests/e2e/puppeteer.e2e.test.js",
     "test:e2e:parity": "node scripts/run-tests.mjs --env RUN_E2E=true tests/e2e/fingerprint-parity.e2e.test.js",
+    "test:e2e:click-readiness": "node scripts/run-tests.mjs --env RUN_E2E=true tests/e2e/click-readiness.e2e.test.js",
+    "test:e2e:downloads": "node scripts/run-tests.mjs --env RUN_E2E=true tests/e2e/downloads.e2e.test.js",
+    "test:e2e:traces": "node scripts/run-tests.mjs --env RUN_E2E=true tests/e2e/traces.e2e.test.js",
     "test:all": "npm run test:unit && npm run test:e2e",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
@@ -65,6 +68,7 @@
   },
   "dependencies": {
     "better-sqlite3": "^12.11.1",
+    "links-notation": "^0.20.0",
     "log-lazy": "^1.0.4",
     "test-anywhere": "^0.9.1"
   },

package/src/bindings.js

@@ -11,6 +11,7 @@ import {
   setContent,
   waitForNavigation,
   waitForPageReady,
+  waitForReady,
   waitAfterAction,
 } from './browser/navigation.js';
 import { emulateMedia } from './browser/media.js';
@@ -137,6 +138,15 @@ export function createBoundFunctions(options = {}) {
       log,
       wait: waitBound,
     });
+  const waitForReadyBound = (opts) =>
+    waitForReady({
+      ...opts,
+      page,
+      engine,
+      navigationManager,
+      networkTracker,
+      log,
+    });
   const waitAfterActionBound = (opts) =>
     waitAfterAction({
       ...opts,
@@ -199,7 +209,8 @@ export function createBoundFunctions(options = {}) {
     scrollIntoViewIfNeeded({ ...opts, page, engine, wait: waitBound, log });
 
   // Bound click - now navigation-aware
-  const clickElementBound = (opts) => clickElement({ ...opts, engine, log });
+  const clickElementBound = (opts) =>
+    clickElement({ ...opts, page, engine, log });
   const clickButtonBound = (opts) =>
     clickButton({
       ...opts,
@@ -323,6 +334,7 @@ export function createBoundFunctions(options = {}) {
     getUrl: getUrlBound,
     waitForNavigation: waitForNavigationBound,
     waitForPageReady: waitForPageReadyBound,
+    waitForReady: waitForReadyBound,
     waitAfterAction: waitAfterActionBound,
     getAttribute: getAttributeWrapped,
     isVisible: isVisibleWrapped,

package/src/browser/connector.js

@@ -1,3 +1,4 @@
+import { attachDownloads } from '../downloads/attach.js';
 import {
   loadStorageState,
   restorePlaywrightStorageState,
@@ -109,7 +110,8 @@ async function connectPuppeteer({ options, loadPuppeteer, storageState }) {
  * @param {Object[]|string|Object} [options.storageState] - Playwright-compatible state path or object
  * @param {Object[]} [options.seedCookies] - Cookies to seed after connecting
  * @param {boolean} [options.verbose=false] - Enable connection logging
- * @returns {Promise<{browser: Object, page: Object}>} Raw browser and page handles
+ * @param {boolean|Object} [options.downloads] - Manage downloads: true for defaults, or {directory, persist, conflict}
+ * @returns {Promise<{browser: Object, page: Object, downloads: Object|null}>} Raw handles and the download manager when one was requested
  */
 export async function connectBrowser(options = {}) {
   return await connectBrowserWithDependencies(options);
@@ -120,7 +122,7 @@ export async function connectBrowser(options = {}) {
  *
  * @param {Object} options - See {@link connectBrowser}
  * @param {Object} dependencies - Optional engine module loaders
- * @returns {Promise<{browser: Object, page: Object}>} Raw browser and page handles
+ * @returns {Promise<{browser: Object, page: Object, downloads: Object|null}>} Raw handles and the download manager when one was requested
  */
 export async function connectBrowserWithDependencies(
   options = {},
@@ -157,7 +159,17 @@ export async function connectBrowserWithDependencies(
   if (verbose) {
     console.log(`Connected to browser with ${engine} engine`);
   }
-  return result;
+
+  // An attached browser gets the same managed lifecycle as a launched one:
+  // the manager is built from the browser and page, not from how we got them.
+  const downloads = await attachDownloads({
+    engine,
+    browser: result.browser,
+    page: result.page,
+    downloads: normalizedOptions.downloads,
+  });
+
+  return { ...result, downloads };
 }
 
 export { buildPlaywrightConnectOptions, buildPuppeteerConnectOptions };

package/src/browser/launcher.js

@@ -8,6 +8,7 @@ import {
   resolveChromeArgs,
 } from './launch-options.js';
 import { applyFingerprint } from '../fingerprint/apply.js';
+import { attachDownloads } from '../downloads/attach.js';
 import {
   loadStorageState,
   restorePlaywrightStorageState,
@@ -31,7 +32,8 @@ import {
  * @param {string|Object} [options.storageState] - Playwright-compatible storage state path or object
  * @param {Object} [options.fingerprint] - Environment fields to present to pages, such as userAgent, timezone, locale, hardwareConcurrency or screen. Applied over CDP after launch; see src/fingerprint/profile.js for the full field list and presets.js for ready-made profiles.
  * @param {boolean} [options.automationParity=true] - Keep the command line indistinguishable from a hand-started Chrome. Turning this off restores the pre-parity switches and makes navigator.webdriver true.
- * @returns {Promise<Object>} - Object with browser and page
+ * @param {boolean|Object} [options.downloads] - Manage downloads: true for defaults, or {directory, persist, conflict}. The directory may be an absolute path, 'user-downloads' or 'temporary'.
+ * @returns {Promise<{browser: Object, page: Object, downloads: Object|null}>} - Browser, page and the download manager when one was requested
  */
 export async function launchBrowser(options = {}) {
   const {
@@ -49,6 +51,7 @@ export async function launchBrowser(options = {}) {
     storageState,
     fingerprint,
     automationParity = true,
+    downloads,
   } = options;
 
   const resolvedChromeArgs = resolveChromeArgs({
@@ -169,5 +172,14 @@ export async function launchBrowser(options = {}) {
     }
   }
 
-  return { browser, page };
+  // Downloads are armed before the caller can navigate: a download triggered
+  // by the first page load still lands in the managed directory.
+  const downloadManager = await attachDownloads({
+    engine,
+    browser,
+    page,
+    downloads,
+  });
+
+  return { browser, page, downloads: downloadManager };
 }

package/src/browser/navigation.js

@@ -8,6 +8,13 @@
 import { TIMING } from '../core/constants.js';
 import { isNavigationError } from '../core/navigation-safety.js';
 import { isActionStoppedError } from '../core/page-trigger-manager.js';
+import {
+  READINESS_STATUS,
+  createDeadline,
+  networkIdleFor,
+  runReadinessChecks,
+  urlStableFor,
+} from '../core/readiness.js';
 
 /**
  * Default verification function for navigation operations.
@@ -492,6 +499,62 @@ export async function waitForPageReady(options = {}) {
   return true;
 }
 
+/**
+ * Wait for the page to be ready and return structured evidence.
+ *
+ * Unlike {@link waitForPageReady}, which answers with a single boolean, this
+ * reports which checks passed, which failed, which were skipped and which never
+ * got to run before the shared deadline expired.
+ *
+ * @param {Object} options - Configuration options
+ * @param {Object} options.page - Browser page object
+ * @param {string} [options.engine] - Engine type
+ * @param {Object} [options.navigationManager] - NavigationManager instance
+ * @param {Object} [options.networkTracker] - NetworkTracker instance
+ * @param {Function} [options.log] - Logger instance
+ * @param {number} [options.timeout=30000] - Total budget in milliseconds
+ * @param {string} [options.reason='page ready'] - Reason for waiting
+ * @param {Array} [options.checks] - Composable readiness checks
+ * @returns {Promise<Object>} Structured readiness result
+ */
+export async function waitForReady(options = {}) {
+  const {
+    page,
+    engine,
+    navigationManager,
+    networkTracker,
+    log = { debug: () => {} },
+    timeout = 30000,
+    reason = 'page ready',
+    checks,
+  } = options;
+
+  if (navigationManager?.waitForReady) {
+    return navigationManager.waitForReady({ timeout, reason, checks });
+  }
+
+  const deadline = createDeadline({ timeout });
+  const result = await runReadinessChecks({
+    checks: checks ?? [urlStableFor(), networkIdleFor()],
+    deadline,
+    context: {
+      page,
+      engine,
+      log,
+      networkTracker,
+      getAdapter: async () => {
+        const { createEngineAdapter } =
+          await import('../core/engine-adapter.js');
+        return createEngineAdapter(page, engine);
+      },
+    },
+  });
+
+  return { ...result, reason, url: page?.url?.() ?? null };
+}
+
+export { READINESS_STATUS };
+
 /**
  * Wait for any ongoing navigation and network requests to complete.
  * Use this after actions that might trigger navigation (like clicks).