@vforsh/argus-watcher 0.5.3 → 0.5.5

package/dist/cdp/ffmpeg.d.ts

@@ -4,16 +4,19 @@ import type { RecordFormat } from '@vforsh/argus-core';
 import type { VisualCaptureClip, VisualCaptureViewport } from './visualCapture.js';
 /**
  * The ffmpeg side of screen recording: spawning the encoder, building its arguments, and reading
- * the PNG frame headers that size its filter graph.
+ * the frame headers that size its filter graph.
  *
  * Split out of `recording.ts` because none of it touches CDP — the recorder pipes frames into a
  * child process, and that process's argument construction, stderr ring, and ENOENT phrasing are a
  * separate concern from screencast frame pacing.
  */
-/** Dimensions read from a PNG screencast frame. */
-export type PngSize = {
+/** Wire format of the screencast frames piped into ffmpeg. */
+export type FrameCodec = 'png' | 'jpeg';
+/** Dimensions and encoding read from a screencast frame. */
+export type FrameInfo = {
     width: number;
     height: number;
+    codec: FrameCodec;
 };
 type FfmpegChild = ChildProcessByStdio<Writable, null, Readable>;
 /** A running ffmpeg encoder and a promise for its exit. */
@@ -22,16 +25,29 @@ export type FfmpegProcess = {
     /** Resolves on a clean exit; rejects with the tail of stderr otherwise. */
     completion: Promise<void>;
 };
-/** Spawn ffmpeg to encode a PNG frame stream, resolving once the child has actually spawned. */
+/** Spawn ffmpeg to encode a screencast frame stream, resolving once the child has actually spawned. */
 export declare const startFfmpeg: (options: {
     absolutePath: string;
     fps: number;
     format: RecordFormat;
     clip: VisualCaptureClip | undefined;
     viewport: VisualCaptureViewport | undefined;
-    frameSize: PngSize;
+    frame: FrameInfo;
 }) => Promise<FfmpegProcess>;
-export declare const readPngSize: (buffer: Buffer) => PngSize;
+/**
+ * Read the encoding and pixel dimensions of a screencast frame.
+ *
+ * The codec is *detected*, never assumed from the `Page.startScreencast` request: ffmpeg is told
+ * up front which decoder sits on the pipe, and if that disagrees with the bytes it gets, every
+ * frame fails to decode and the encode dies with an empty file. Chrome is not the only producer
+ * here — test fakes and future capture paths feed this too — so the frames are the authority.
+ *
+ * The size matters because a CSS-pixel crop rectangle has to be translated into encoder
+ * coordinates, and the screencast reports no device pixel ratio worth trusting across DPR changes.
+ *
+ * @throws {Error} When the buffer is not a recognizable PNG or JPEG.
+ */
+export declare const readFrameInfo: (buffer: Buffer) => FrameInfo;
 export declare const formatFfmpegError: (error: unknown) => Error;
 export {};
 //# sourceMappingURL=ffmpeg.d.ts.map

package/dist/cdp/ffmpeg.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ffmpeg.d.ts","sourceRoot":"","sources":["../../src/cdp/ffmpeg.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AACpE,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,KAAK,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AAElF;;;;;;;GAOG;AAEH,mDAAmD;AACnD,MAAM,MAAM,OAAO,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAEvD,KAAK,WAAW,GAAG,mBAAmB,CAAC,QAAQ,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAA;AAEhE,2DAA2D;AAC3D,MAAM,MAAM,aAAa,GAAG;IAC3B,KAAK,EAAE,WAAW,CAAA;IAClB,2EAA2E;IAC3E,UAAU,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;CACzB,CAAA;AAED,gGAAgG;AAChG,eAAO,MAAM,WAAW,GAAU,SAAS;IAC1C,YAAY,EAAE,MAAM,CAAA;IACpB,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,YAAY,CAAA;IACpB,IAAI,EAAE,iBAAiB,GAAG,SAAS,CAAA;IACnC,QAAQ,EAAE,qBAAqB,GAAG,SAAS,CAAA;IAC3C,SAAS,EAAE,OAAO,CAAA;CAClB,KAAG,OAAO,CAAC,aAAa,CA+CxB,CAAA;AAgCD,eAAO,MAAM,WAAW,GAAI,QAAQ,MAAM,KAAG,OAmB5C,CAAA;AAOD,eAAO,MAAM,iBAAiB,GAAI,OAAO,OAAO,KAAG,KAMlD,CAAA"}
+{"version":3,"file":"ffmpeg.d.ts","sourceRoot":"","sources":["../../src/cdp/ffmpeg.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AACpE,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,KAAK,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AAElF;;;;;;;GAOG;AAEH,8DAA8D;AAC9D,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,CAAA;AAEvC,4DAA4D;AAC5D,MAAM,MAAM,SAAS,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAE,CAAA;AAE5E,KAAK,WAAW,GAAG,mBAAmB,CAAC,QAAQ,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAA;AAEhE,2DAA2D;AAC3D,MAAM,MAAM,aAAa,GAAG;IAC3B,KAAK,EAAE,WAAW,CAAA;IAClB,2EAA2E;IAC3E,UAAU,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;CACzB,CAAA;AAED,uGAAuG;AACvG,eAAO,MAAM,WAAW,GAAU,SAAS;IAC1C,YAAY,EAAE,MAAM,CAAA;IACpB,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,YAAY,CAAA;IACpB,IAAI,EAAE,iBAAiB,GAAG,SAAS,CAAA;IACnC,QAAQ,EAAE,qBAAqB,GAAG,SAAS,CAAA;IAC3C,KAAK,EAAE,SAAS,CAAA;CAChB,KAAG,OAAO,CAAC,aAAa,CA8CxB,CAAA;AAqDD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,aAAa,GAAI,QAAQ,MAAM,KAAG,SAW9C,CAAA;AAsDD,eAAO,MAAM,iBAAiB,GAAI,OAAO,OAAO,KAAG,KAMlD,CAAA"}

package/dist/cdp/ffmpeg.js

@@ -1,8 +1,7 @@
 import { spawn } from 'node:child_process';
-/** Spawn ffmpeg to encode a PNG frame stream, resolving once the child has actually spawned. */
+/** Spawn ffmpeg to encode a screencast frame stream, resolving once the child has actually spawned. */
 export const startFfmpeg = async (options) => {
     const ffmpeg = process.env.ARGUS_FFMPEG?.trim() || 'ffmpeg';
-    const filter = buildVideoFilter(options);
     const args = [
         '-hide_banner',
         '-loglevel',
@@ -12,12 +11,12 @@ export const startFfmpeg = async (options) => {
         '-framerate',
         String(options.fps),
         '-vcodec',
-        'png',
+        options.frame.codec === 'jpeg' ? 'mjpeg' : 'png',
         '-i',
         'pipe:0',
         '-an',
         '-vf',
-        filter,
+        buildVideoFilter(options),
         ...buildEncoderArgs(options.format),
         '-y',
         options.absolutePath,
@@ -46,43 +45,104 @@ export const startFfmpeg = async (options) => {
     return { child, completion };
 };
 const buildVideoFilter = (options) => {
-    if (!options.clip) {
-        return 'scale=trunc(iw/2)*2:trunc(ih/2)*2,format=yuv420p';
+    const geometry = options.clip ? buildCropFilter(options.clip, options.viewport, options.frame) : 'scale=trunc(iw/2)*2:trunc(ih/2)*2';
+    if (options.format !== 'gif') {
+        return `${geometry},format=yuv420p`;
     }
-    if (!options.viewport) {
+    /**
+     * One-pass palette generation, because the frames arrive on a pipe.
+     *
+     * The usual high-quality GIF recipe runs `palettegen` over the whole file and only then
+     * `paletteuse`, which needs two passes over a seekable input. A live screencast has neither,
+     * so this builds a palette per frame (`stats_mode=single`) and tells `paletteuse` to expect a
+     * new one each time (`new=1`). Slightly larger files than a global palette, no second pass,
+     * and no banding on the gradients that make up most app UI.
+     */
+    return `${geometry},split[gifsrc][gifpal];[gifpal]palettegen=stats_mode=single[pal];[gifsrc][pal]paletteuse=new=1:dither=sierra2_4a`;
+};
+const buildCropFilter = (clip, viewport, frameSize) => {
+    if (!viewport) {
         throw new Error('Unable to compute viewport size for recording crop');
     }
-    const ratioX = options.frameSize.width / options.viewport.width;
-    const ratioY = options.frameSize.height / options.viewport.height;
-    const x = clampEven(options.clip.x * ratioX, 0, options.frameSize.width - 2);
-    const y = clampEven(options.clip.y * ratioY, 0, options.frameSize.height - 2);
-    const width = clampEven(options.clip.width * ratioX, 2, options.frameSize.width - x);
-    const height = clampEven(options.clip.height * ratioY, 2, options.frameSize.height - y);
-    return `crop=${width}:${height}:${x}:${y},format=yuv420p`;
+    const ratioX = frameSize.width / viewport.width;
+    const ratioY = frameSize.height / viewport.height;
+    const x = clampEven(clip.x * ratioX, 0, frameSize.width - 2);
+    const y = clampEven(clip.y * ratioY, 0, frameSize.height - 2);
+    const width = clampEven(clip.width * ratioX, 2, frameSize.width - x);
+    const height = clampEven(clip.height * ratioY, 2, frameSize.height - y);
+    return `crop=${width}:${height}:${x}:${y}`;
 };
 const buildEncoderArgs = (format) => {
+    if (format === 'gif') {
+        return ['-loop', '0', '-f', 'gif'];
+    }
     if (format === 'webm') {
-        return ['-c:v', 'libvpx', '-deadline', 'realtime', '-cpu-used', '5', '-b:v', '1M', '-f', 'webm'];
+        // VP9 at constant quality: the old flat 1M VP8 bitrate smeared any 2x-DPR canvas.
+        return ['-c:v', 'libvpx-vp9', '-deadline', 'realtime', '-cpu-used', '5', '-crf', '32', '-b:v', '0', '-row-mt', '1', '-f', 'webm'];
     }
     // yuv420p + H.264 keeps files playable in Finder, QuickTime, iOS Photos, Slack, and browsers.
     return ['-c:v', 'libx264', '-preset', 'veryfast', '-crf', '23', '-movflags', '+faststart', '-f', 'mp4'];
 };
-export const readPngSize = (buffer) => {
-    if (buffer.length < 24 ||
-        buffer[0] !== 0x89 ||
-        buffer[1] !== 0x50 ||
-        buffer[2] !== 0x4e ||
-        buffer[3] !== 0x47 ||
-        buffer[4] !== 0x0d ||
-        buffer[5] !== 0x0a ||
-        buffer[6] !== 0x1a ||
-        buffer[7] !== 0x0a) {
-        throw new Error('Expected PNG screencast frame');
+/**
+ * Read the encoding and pixel dimensions of a screencast frame.
+ *
+ * The codec is *detected*, never assumed from the `Page.startScreencast` request: ffmpeg is told
+ * up front which decoder sits on the pipe, and if that disagrees with the bytes it gets, every
+ * frame fails to decode and the encode dies with an empty file. Chrome is not the only producer
+ * here — test fakes and future capture paths feed this too — so the frames are the authority.
+ *
+ * The size matters because a CSS-pixel crop rectangle has to be translated into encoder
+ * coordinates, and the screencast reports no device pixel ratio worth trusting across DPR changes.
+ *
+ * @throws {Error} When the buffer is not a recognizable PNG or JPEG.
+ */
+export const readFrameInfo = (buffer) => {
+    if (isPng(buffer)) {
+        return { width: buffer.readUInt32BE(16), height: buffer.readUInt32BE(20), codec: 'png' };
+    }
+    const jpegSize = readJpegSize(buffer);
+    if (jpegSize) {
+        return { ...jpegSize, codec: 'jpeg' };
+    }
+    throw new Error('Expected a PNG or JPEG screencast frame');
+};
+const isPng = (buffer) => buffer.length >= 24 &&
+    buffer[0] === 0x89 &&
+    buffer[1] === 0x50 &&
+    buffer[2] === 0x4e &&
+    buffer[3] === 0x47 &&
+    buffer[4] === 0x0d &&
+    buffer[5] === 0x0a &&
+    buffer[6] === 0x1a &&
+    buffer[7] === 0x0a;
+/** Frame-header markers (SOF0-SOF15) that carry dimensions, minus the four that are not frame headers. */
+const JPEG_NON_SOF_MARKERS = new Set([0xc4, 0xc8, 0xcc]);
+const readJpegSize = (buffer) => {
+    if (buffer.length < 4 || buffer[0] !== 0xff || buffer[1] !== 0xd8) {
+        return null;
+    }
+    let offset = 2;
+    while (offset + 3 < buffer.length) {
+        if (buffer[offset] !== 0xff) {
+            offset += 1;
+            continue;
+        }
+        const marker = buffer[offset + 1];
+        // Padding fill bytes and the standalone markers carry no length field.
+        if (marker === 0xff || marker === 0x01 || (marker >= 0xd0 && marker <= 0xd9)) {
+            offset += 2;
+            continue;
+        }
+        const segmentLength = buffer.readUInt16BE(offset + 2);
+        if (marker >= 0xc0 && marker <= 0xcf && !JPEG_NON_SOF_MARKERS.has(marker)) {
+            if (offset + 9 > buffer.length) {
+                return null;
+            }
+            return { width: buffer.readUInt16BE(offset + 7), height: buffer.readUInt16BE(offset + 5) };
+        }
+        offset += 2 + segmentLength;
     }
-    return {
-        width: buffer.readUInt32BE(16),
-        height: buffer.readUInt32BE(20),
-    };
+    return null;
 };
 const clampEven = (value, min, max) => {
     const clamped = Math.min(max, Math.max(min, Math.floor(value)));

package/dist/cdp/ffmpeg.js.map

@@ -1 +1 @@
-{"version":3,"file":"ffmpeg.js","sourceRoot":"","sources":["../../src/cdp/ffmpeg.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ffmpeg.js","sourceRoot":"","sources":["../../src/cdp/ffmpeg.ts"],"names":[],"mappings":"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"}

package/dist/cdp/navigation.d.ts

@@ -0,0 +1,82 @@
+import { type LogEpoch, type NavigationDirection, type NavigationSummary, type NavigationWait, type NavigationWaitOptions } from '@vforsh/argus-core';
+import type { CdpSessionHandle } from './connection.js';
+/**
+ * Waiting for a navigation to finish, for every command that causes one.
+ *
+ * The hard part is not sending `Page.navigate` — it is knowing when the answer is safe to
+ * send back. A load event on its own proves nothing: it may belong to the document that was
+ * already there when the command was issued. So a wait only counts a `domContentEventFired`
+ * or `loadEventFired` that arrives *after* the top-frame `Page.frameNavigated`, and — when
+ * Chrome told us which loader it started — for that loader.
+ *
+ * Handlers are attached before the navigating command is sent, never after, so a fast
+ * same-origin load cannot slip through the gap between the send and the subscribe.
+ */
+/** A primed navigation wait. Always `dispose()` it, including on the failure path. */
+export type NavigationWaiter = {
+    /**
+     * Wait for the requested phase, resolving to the URL navigated to, or `null` when nothing
+     * navigated (which is what `wait: 'none'` always reports).
+     *
+     * @param expectedLoaderId Loader id from the navigating command, when it reported one. A load
+     *   event for a different loader (a redirect chain's earlier hop, a concurrent reload) is ignored.
+     * @throws A `navigation_timeout` coded error when the phase does not arrive in time.
+     */
+    settle: (expectedLoaderId?: string | null) => Promise<string | null>;
+    dispose: () => void;
+};
+/** Subscribe to the navigation lifecycle before issuing the command that triggers it. */
+export declare const armNavigationWaiter: (session: CdpSessionHandle, options: {
+    wait: NavigationWait;
+    timeoutMs: number;
+}) => NavigationWaiter;
+/** Result of a completed `Page.navigate`. */
+export type NavigatePageResult = {
+    url: string;
+    loaderId: string | null;
+};
+/**
+ * Navigate the page and wait for the requested phase.
+ *
+ * @throws A `navigation_failed` coded error when Chrome refuses the URL (bad host, blocked
+ *   scheme); `navigation_timeout` when the load does not complete in time. Both are the
+ *   request's fault or the network's, so they are reported as such rather than as CDP errors.
+ */
+export declare const navigatePage: (session: CdpSessionHandle, options: {
+    url: string;
+    wait: NavigationWait;
+    timeoutMs: number;
+}) => Promise<NavigatePageResult>;
+/** Result of a completed history navigation. */
+export type NavigateHistoryResult = {
+    url: string;
+    index: number;
+    length: number;
+};
+/**
+ * Move through the session history and wait for the requested phase.
+ *
+ * @throws A `no_history` coded error when the requested step falls outside the history, which
+ *   is what "already at the first entry" looks like — not a transport failure.
+ */
+export declare const navigateHistory: (session: CdpSessionHandle, options: {
+    direction: NavigationDirection;
+    steps: number;
+    wait: NavigationWait;
+    timeoutMs: number;
+}) => Promise<NavigateHistoryResult>;
+/**
+ * Run an interaction that may navigate, and report whether it did.
+ *
+ * A click on a plain button navigates nowhere, and that is the common case — so a timeout here
+ * is a `navigated: false` summary, not an error. Only a **top-frame** navigation counts: an
+ * iframe that navigates internally reports `navigated: false`.
+ *
+ * @param beginEpoch Opens a log epoch just before the interaction, so the caller can read the
+ *   new page's console output without racing it. Only called when a wait was requested.
+ */
+export declare const withNavigationWait: <T>(session: CdpSessionHandle, options: NavigationWaitOptions, beginEpoch: () => LogEpoch, act: () => Promise<T>) => Promise<{
+    result: T;
+    navigation?: NavigationSummary;
+}>;
+//# sourceMappingURL=navigation.d.ts.map

package/dist/cdp/navigation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../src/cdp/navigation.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,KAAK,QAAQ,EACb,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,MAAM,oBAAoB,CAAA;AAC3B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAGvD;;;;;;;;;;;GAWG;AAEH,sFAAsF;AACtF,MAAM,MAAM,gBAAgB,GAAG;IAC9B;;;;;;;OAOG;IACH,MAAM,EAAE,CAAC,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IACpE,OAAO,EAAE,MAAM,IAAI,CAAA;CACnB,CAAA;AAED,yFAAyF;AACzF,eAAO,MAAM,mBAAmB,GAAI,SAAS,gBAAgB,EAAE,SAAS;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,KAAG,gBA2FrH,CAAA;AAED,6CAA6C;AAC7C,MAAM,MAAM,kBAAkB,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAA;AAEzE;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,GACxB,SAAS,gBAAgB,EACzB,SAAS;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,cAAc,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,KAC/D,OAAO,CAAC,kBAAkB,CAc5B,CAAA;AAED,gDAAgD;AAChD,MAAM,MAAM,qBAAqB,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAElF;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAC3B,SAAS,gBAAgB,EACzB,SAAS;IAAE,SAAS,EAAE,mBAAmB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,cAAc,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,KACjG,OAAO,CAAC,qBAAqB,CAuB/B,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,GAAU,CAAC,EACzC,SAAS,gBAAgB,EACzB,SAAS,qBAAqB,EAC9B,YAAY,MAAM,QAAQ,EAC1B,KAAK,MAAM,OAAO,CAAC,CAAC,CAAC,KACnB,OAAO,CAAC;IAAE,MAAM,EAAE,CAAC,CAAC;IAAC,UAAU,CAAC,EAAE,iBAAiB,CAAA;CAAE,CAiBvD,CAAA"}

package/dist/cdp/navigation.js

@@ -0,0 +1,186 @@
+import { DEFAULT_INTERACTION_NAV_TIMEOUT_MS, } from '@vforsh/argus-core';
+import { codedError, hasErrorCode } from '../errors.js';
+/** Subscribe to the navigation lifecycle before issuing the command that triggers it. */
+export const armNavigationWaiter = (session, options) => {
+    let topFrameId = null;
+    let navigatedUrl = null;
+    let navigatedLoaderId = null;
+    let domFired = false;
+    let loadFired = false;
+    // Set when the navigation completed but no dom/load event will ever follow it: a hash change
+    // or pushState (same document), and a back/forward-cache restore (the document is resumed,
+    // not parsed). Waiting for `load` in either case would burn the whole timeout on a page that
+    // is already there.
+    let settledWithoutLoadUrl = null;
+    let notify = null;
+    // The top frame's id, so a same-document navigation inside an iframe cannot settle the wait.
+    // Fire-and-forget: a detached session fails the navigating command with its own error.
+    void session
+        .sendAndWait('Page.getFrameTree')
+        .then((result) => {
+        topFrameId = result.frameTree?.frame.id ?? null;
+    })
+        .catch(() => { });
+    const isSettled = (expectedLoaderId) => {
+        if (settledWithoutLoadUrl != null)
+            return true;
+        if (navigatedUrl == null)
+            return false;
+        if (expectedLoaderId != null && navigatedLoaderId != null && navigatedLoaderId !== expectedLoaderId)
+            return false;
+        return options.wait === 'domcontentloaded' ? domFired || loadFired : loadFired;
+    };
+    const removers = [
+        // A child target's events carry a sessionId; only the top frame's do not.
+        session.onEvent('Page.frameNavigated', (params, meta) => {
+            const frame = params.frame;
+            if (meta.sessionId || !frame || frame.parentId)
+                return;
+            topFrameId = frame.id;
+            navigatedUrl = frame.url ?? '';
+            navigatedLoaderId = frame.loaderId ?? null;
+            domFired = false;
+            loadFired = false;
+            settledWithoutLoadUrl = params.type === 'BackForwardCacheRestore' ? navigatedUrl : null;
+            notify?.();
+        }),
+        session.onEvent('Page.domContentEventFired', (_params, meta) => {
+            if (meta.sessionId)
+                return;
+            domFired = true;
+            notify?.();
+        }),
+        session.onEvent('Page.loadEventFired', (_params, meta) => {
+            if (meta.sessionId)
+                return;
+            loadFired = true;
+            notify?.();
+        }),
+        session.onEvent('Page.navigatedWithinDocument', (params, meta) => {
+            if (meta.sessionId || !params.url)
+                return;
+            if (topFrameId != null && params.frameId !== topFrameId)
+                return;
+            settledWithoutLoadUrl = params.url;
+            notify?.();
+        }),
+    ];
+    let timer = null;
+    const dispose = () => {
+        for (const remove of removers)
+            remove();
+        if (timer)
+            clearTimeout(timer);
+        timer = null;
+        notify = null;
+    };
+    const settle = async (expectedLoaderId = null) => {
+        if (options.wait === 'none') {
+            return null;
+        }
+        if (!isSettled(expectedLoaderId)) {
+            await new Promise((resolve, reject) => {
+                notify = () => {
+                    if (!isSettled(expectedLoaderId))
+                        return;
+                    notify = null;
+                    resolve();
+                };
+                timer = setTimeout(() => {
+                    notify = null;
+                    reject(codedError('navigation_timeout', `Navigation did not reach "${options.wait}" within ${options.timeoutMs}ms.`));
+                }, options.timeoutMs);
+            });
+        }
+        return settledWithoutLoadUrl ?? navigatedUrl;
+    };
+    return { settle, dispose };
+};
+/**
+ * Navigate the page and wait for the requested phase.
+ *
+ * @throws A `navigation_failed` coded error when Chrome refuses the URL (bad host, blocked
+ *   scheme); `navigation_timeout` when the load does not complete in time. Both are the
+ *   request's fault or the network's, so they are reported as such rather than as CDP errors.
+ */
+export const navigatePage = async (session, options) => {
+    const waiter = armNavigationWaiter(session, options);
+    try {
+        const result = await session.sendAndWait('Page.navigate', { url: options.url });
+        if (result.errorText) {
+            throw codedError('navigation_failed', `Navigation to ${options.url} failed: ${result.errorText}`);
+        }
+        const loaderId = result.loaderId ?? null;
+        const settledUrl = await waiter.settle(loaderId);
+        return { url: settledUrl ?? options.url, loaderId };
+    }
+    finally {
+        waiter.dispose();
+    }
+};
+/**
+ * Move through the session history and wait for the requested phase.
+ *
+ * @throws A `no_history` coded error when the requested step falls outside the history, which
+ *   is what "already at the first entry" looks like — not a transport failure.
+ */
+export const navigateHistory = async (session, options) => {
+    const history = await session.sendAndWait('Page.getNavigationHistory');
+    const entries = history.entries ?? [];
+    const currentIndex = history.currentIndex ?? 0;
+    const targetIndex = currentIndex + (options.direction === 'back' ? -options.steps : options.steps);
+    const entry = entries[targetIndex];
+    if (!entry) {
+        const step = options.steps === 1 ? '' : ` ${options.steps} entries`;
+        throw codedError('no_history', `Cannot go ${options.direction}${step}: at entry ${currentIndex + 1} of ${entries.length} in the session history.`);
+    }
+    const waiter = armNavigationWaiter(session, options);
+    try {
+        await session.sendAndWait('Page.navigateToHistoryEntry', { entryId: entry.id });
+        const settledUrl = await waiter.settle();
+        return { url: settledUrl ?? entry.url, index: targetIndex, length: entries.length };
+    }
+    finally {
+        waiter.dispose();
+    }
+};
+/**
+ * Run an interaction that may navigate, and report whether it did.
+ *
+ * A click on a plain button navigates nowhere, and that is the common case — so a timeout here
+ * is a `navigated: false` summary, not an error. Only a **top-frame** navigation counts: an
+ * iframe that navigates internally reports `navigated: false`.
+ *
+ * @param beginEpoch Opens a log epoch just before the interaction, so the caller can read the
+ *   new page's console output without racing it. Only called when a wait was requested.
+ */
+export const withNavigationWait = async (session, options, beginEpoch, act) => {
+    if (!options.waitNav) {
+        return { result: await act() };
+    }
+    const epoch = beginEpoch();
+    const waiter = armNavigationWaiter(session, {
+        wait: options.waitNav,
+        timeoutMs: options.navTimeoutMs ?? DEFAULT_INTERACTION_NAV_TIMEOUT_MS,
+    });
+    try {
+        const result = await act();
+        return { result, navigation: await summarizeNavigation(waiter, epoch) };
+    }
+    finally {
+        waiter.dispose();
+    }
+};
+/** Settle a `--wait-nav` waiter, turning its timeout into a "nothing navigated" summary. */
+const summarizeNavigation = async (waiter, epoch) => {
+    try {
+        const url = await waiter.settle();
+        return { navigated: url != null, url, epoch };
+    }
+    catch (error) {
+        if (!hasErrorCode(error, 'navigation_timeout'))
+            throw error;
+        return { navigated: false, url: null, epoch };
+    }
+};
+//# sourceMappingURL=navigation.js.map

package/dist/cdp/navigation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation.js","sourceRoot":"","sources":["../../src/cdp/navigation.ts"],"names":[],"mappings":"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"}

package/dist/cdp/protocol.d.ts

@@ -64,6 +64,15 @@ export type CdpFrame = {
     parentId?: string;
     url?: string;
     name?: string;
+    /** Identifies the navigation that produced this frame state. Used to match load events to a navigation. */
+    loaderId?: string;
+};
+/** One entry in the `Page.getNavigationHistory` response. */
+export type CdpNavigationHistoryEntry = {
+    id: number;
+    url: string;
+    title: string;
+    transitionType?: string;
 };
 /** A node in the `Page.getFrameTree` response. */
 export type CdpFrameTreeNode = {
@@ -369,6 +378,10 @@ export type CdpCommandMap = {
         cssVisualViewport?: CdpVisualViewport;
         visualViewport?: CdpVisualViewport;
     }>;
+    'Page.getNavigationHistory': Command<NoParams, {
+        currentIndex?: number;
+        entries?: CdpNavigationHistoryEntry[];
+    }>;
     'Page.handleJavaScriptDialog': Command<{
         accept: boolean;
         promptText?: string;
@@ -381,6 +394,9 @@ export type CdpCommandMap = {
         loaderId?: string;
         errorText?: string;
     }>;
+    'Page.navigateToHistoryEntry': Command<{
+        entryId: number;
+    }, unknown>;
     'Page.reload': Command<{
         ignoreCache?: boolean;
         scriptToEvaluateOnLoad?: string;
@@ -547,11 +563,19 @@ export type CdpEventMap = {
     };
     'Page.frameNavigated': {
         frame?: CdpFrame;
+        type?: 'Navigation' | 'BackForwardCacheRestore';
     };
     'Page.javascriptDialogClosed': {
         result?: boolean;
         userInput?: string;
     };
+    'Page.loadEventFired': {
+        timestamp?: number;
+    };
+    'Page.navigatedWithinDocument': {
+        frameId?: string;
+        url?: string;
+    };
     'Page.javascriptDialogOpening': {
         url?: string;
         message?: string;