@glubean/browser 0.8.1 → 0.9.0

package/dist/page.js

@@ -11,10 +11,21 @@
  *
  * @module page
  */
-import { attachNetworkTracer } from "./network.js";
+import { EvidenceSession, } from "./evidence.js";
 import { collectNavigationMetrics } from "./metrics.js";
 import { createWrappedLocator } from "./locator.js";
+import { createFrame } from "./frame.js";
 import { getRuntime } from "@glubean/sdk/internal";
+// ── Module-level helpers (used by the shoot callback in _create) ──────
+/** Sanitize a string into a safe filename segment. */
+function _sanitizeFilename(s) {
+    return s.replace(/[^a-z0-9_-]/gi, "_").slice(0, 60);
+}
+/** Create a directory (and any parents) if it does not already exist. */
+async function _ensureDir(dir) {
+    const { mkdir } = await import("node:fs/promises");
+    await mkdir(dir, { recursive: true });
+}
 /**
  * Connected browser instance returned by the plugin.
  *
@@ -50,7 +61,6 @@ export class GlubeanBrowser {
             clearTimeout(this._closeTimer);
             this._closeTimer = null;
         }
-        this._openPages++;
         const browser = await this._getBrowser();
         // Reuse the default about:blank tab instead of opening a new one.
         // When Chrome launches it always creates one blank page — reusing it
@@ -61,16 +71,31 @@ export class GlubeanBrowser {
             return url === "about:blank" || url === "chrome://new-tab-page/";
         });
         const rawPage = blank ?? await browser.newPage();
+        this._track(rawPage);
+        // Read testId lazily from the runtime carrier — the harness updates it
+        // before each test runs, so reading at newPage() time is always fresh.
+        const runtimeTestId = getRuntime()?.test?.id;
+        return GlubeanPage._create(rawPage, this._baseUrl, ctx, this._options, runtimeTestId, this);
+    }
+    /**
+     * @internal Register a raw page in the open-page accounting so the browser
+     * isn't auto-closed while it's alive. Cancels any pending close, increments
+     * the counter, and decrements (rescheduling close at zero) on page close.
+     * Used by both `newPage()` and `GlubeanPage.waitForPopup()` (popups are
+     * real pages that must keep the browser open too).
+     */
+    _track(rawPage) {
+        if (this._closeTimer) {
+            clearTimeout(this._closeTimer);
+            this._closeTimer = null;
+        }
+        this._openPages++;
         rawPage.once("close", () => {
             this._openPages--;
             if (this._openPages <= 0) {
                 this._scheduleClose();
             }
         });
-        // Read testId lazily from the runtime carrier — the harness updates it
-        // before each test runs, so reading at newPage() time is always fresh.
-        const runtimeTestId = getRuntime()?.test?.id;
-        return GlubeanPage._create(rawPage, this._baseUrl, ctx, this._options, runtimeTestId);
     }
     _scheduleClose() {
         this._closeTimer = setTimeout(async () => {
@@ -116,32 +141,78 @@ export class GlubeanPage {
     _baseUrl;
     _ctx;
     _metricsEnabled;
-    _screenshotMode;
-    _screenshotDir;
-    _testId;
     _actionTimeout;
-    _stepCounter = 0;
-    _networkCleanup = null;
-    constructor(page, baseUrl, ctx, metricsEnabled, screenshotMode, screenshotDir, testId, actionTimeout) {
+    _options;
+    _testId;
+    /** Owning browser — used to register popups in its open-page accounting. */
+    _owner;
+    _evidence = null;
+    _dialogHandler = null;
+    constructor(page, baseUrl, ctx, metricsEnabled, actionTimeout, options, testId, owner) {
         this.raw = page;
         this._baseUrl = baseUrl;
         this._ctx = ctx;
         this._metricsEnabled = metricsEnabled;
-        this._screenshotMode = screenshotMode;
-        this._screenshotDir = screenshotDir;
-        this._testId = testId;
         this._actionTimeout = actionTimeout;
+        this._options = options;
+        this._testId = testId;
+        this._owner = owner;
     }
     /** @internal */
-    static async _create(page, baseUrl, ctx, options, runtimeTestId) {
+    static async _create(page, baseUrl, ctx, options, runtimeTestId, owner) {
         const consoleForward = options.consoleForward ?? true;
         const networkTraceOpt = options.networkTrace ?? true;
         const metricsEnabled = options.metrics ?? true;
         const screenshotMode = options.screenshot ?? "on-failure";
         const screenshotDir = options.screenshotDir ?? ".glubean/screenshots";
         const testId = runtimeTestId ?? ctx.testId ?? "unknown";
+        // ONE download dir for the whole browser — NOT per-test. `Browser.setDownloadBehavior`
+        // is browser-context-global (last call wins the path), so two concurrent instrumented
+        // pages sharing one Chrome (e.g. concurrent tests off one `browser()` fixture) must
+        // agree on the directory or one would silently repoint the other's downloads. The
+        // per-download `browser:download` evidence carries the testId for attribution instead.
+        const downloadDir = options.downloadDir ?? ".glubean/downloads";
         const actionTimeout = options.actionTimeout ?? 30_000;
-        const gp = new GlubeanPage(page, baseUrl, ctx, metricsEnabled, screenshotMode, screenshotDir, testId, actionTimeout);
+        const dialogMode = options.dialogMode ?? "dismiss";
+        const gp = new GlubeanPage(page, baseUrl, ctx, metricsEnabled, actionTimeout, options, testId, owner);
+        // Native dialogs (alert/confirm/prompt/beforeunload) always emit evidence.
+        // Puppeteer auto-dismisses unhandled dialogs UNLESS a 'dialog' listener is
+        // registered — once we register one, WE are responsible for resolving
+        // every dialog (custom handler via onDialog(), else `dialogMode`).
+        page.on("dialog", (dialog) => {
+            ctx.event({
+                type: "browser:dialog",
+                data: {
+                    dialogType: dialog.type(),
+                    message: dialog.message(),
+                    defaultValue: dialog.defaultValue(),
+                },
+            });
+            const handle = async () => {
+                if (gp._dialogHandler) {
+                    await gp._dialogHandler(dialog);
+                    return;
+                }
+                if (dialogMode === "accept")
+                    await dialog.accept();
+                else
+                    await dialog.dismiss();
+            };
+            handle().catch((err) => {
+                ctx.warn(false, `[browser:dialog] failed to resolve dialog: ${String(err)}`);
+            });
+        });
+        // Popups (window.open / target=_blank) always emit evidence. Use
+        // page.waitForPopup() to also get a fully-instrumented handle to the
+        // popup itself (own evidence session: network/console/screenshots).
+        page.on("popup", (popup) => {
+            if (!popup)
+                return;
+            ctx.event({
+                type: "browser:popup",
+                data: { url: popup.url() },
+            });
+        });
         if (consoleForward) {
             page.on("console", (msg) => {
                 const type = msg.type();
@@ -167,15 +238,83 @@ export class GlubeanPage {
                 ctx.warn(false, `[browser:uncaught] ${msg}`);
             });
         }
-        if (networkTraceOpt !== false) {
-            const filterOpts = typeof networkTraceOpt === "object" ? networkTraceOpt : undefined;
-            gp._networkCleanup = await attachNetworkTracer(page, {
-                trace: (t) => ctx.trace(t),
-                include: filterOpts?.include,
-                excludePaths: filterOpts?.excludePaths,
-                filter: filterOpts?.filter,
-            });
-        }
+        // One shared evidence CDP session hosts Network trace + Fetch mock +
+        // Emulation + Screenshot capture. Each capability is only wired when its
+        // config is present.
+        const filterOpts = typeof networkTraceOpt === "object" ? networkTraceOpt : undefined;
+        // Build the screenshot shoot delegate. It performs I/O (take screenshot,
+        // save artifact, emit ctx.event) and is called by EvidenceSession.captureShot
+        // when mode+trigger policy allows. Defined here so it closes over `page`,
+        // `ctx`, `screenshotDir`, and `testId` without leaking them into EvidenceSession.
+        // Always install the shoot delegate so captureScreenshot() (manual, trigger="manual")
+        // works even when screenshotMode is "off". The mode only gates automatic triggers
+        // (step / failure); manual captures bypass the mode filter inside EvidenceSession.
+        const screenshotsOpt = {
+            mode: screenshotMode,
+            shoot: async (filename, label, trigger) => {
+                if (ctx.saveArtifact) {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    const buffer = (await page.screenshot({
+                        fullPage: true,
+                        encoding: "binary",
+                    }));
+                    const artifactId = await ctx.saveArtifact(filename, buffer, {
+                        type: "screenshot",
+                        mimeType: "image/png",
+                    });
+                    ctx.event({
+                        type: "browser:screenshot",
+                        data: { artifactId, label, trigger, fullPage: true },
+                    });
+                    return { artifactId };
+                }
+                // Legacy fallback: direct file write when saveArtifact is not available.
+                const subdir = `${screenshotDir}/${_sanitizeFilename(testId)}`;
+                await _ensureDir(subdir);
+                const filePath = `${subdir}/${filename}`;
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                await page.screenshot({ path: filePath, fullPage: true });
+                ctx.event({
+                    type: "browser:screenshot",
+                    data: { path: filePath, label, trigger, fullPage: true },
+                });
+                return { path: filePath };
+            },
+        };
+        // Downloads are always captured as evidence (like dialog/popup) — the
+        // save directory must exist before Chrome is told to use it.
+        await _ensureDir(downloadDir);
+        gp._evidence = await EvidenceSession.attach(page, {
+            trace: networkTraceOpt !== false ? (t) => ctx.trace(t) : undefined,
+            network: filterOpts && {
+                include: filterOpts.include,
+                excludePaths: filterOpts.excludePaths,
+                filter: filterOpts.filter,
+            },
+            mocks: options.mock,
+            emulate: options.emulate,
+            storageState: options.storageState,
+            screenshots: screenshotsOpt,
+            downloads: {
+                dir: downloadDir,
+                onDownload: (entry, state) => {
+                    // Only terminal states are evidence — "inProgress" fires repeatedly
+                    // per download and would flood the timeline with no new information.
+                    if (state === "inProgress")
+                        return;
+                    ctx.event({
+                        type: "browser:download",
+                        data: {
+                            guid: entry.guid,
+                            url: entry.url,
+                            filename: entry.suggestedFilename,
+                            path: entry.path,
+                            state,
+                        },
+                    });
+                },
+            },
+        });
         // Proxy: GlubeanPage methods take priority; everything else falls through
         // to the raw Puppeteer Page so users can call page.waitForNavigation(),
         // page.setViewport(), page.keyboard.press(), etc. directly.
@@ -198,81 +337,267 @@ export class GlubeanPage {
         });
     }
     // ── Screenshot helpers ──────────────────────────────────────────────
-    _formatTimestamp() {
-        return new Date().toISOString().replace(/[:.]/g, "").slice(0, 15);
+    /**
+     * Capture a screenshot for a test-level failure (e.g. assertion error).
+     *
+     * Call this in the fixture's catch block to get a final-state screenshot
+     * when the test body throws. Delegates to the shared {@link EvidenceSession}
+     * so the capture obeys the configured {@link ScreenshotMode} and the
+     * screenshot is recorded in the unified evidence timeline.
+     */
+    async screenshotOnFailure() {
+        await this._evidence?.captureShot("final", "failure");
+    }
+    /**
+     * Manually capture a screenshot into the evidence stream.
+     *
+     * Unlike the raw `screenshot()` method (which returns bytes and skips the
+     * evidence flow), this always records the capture in the timeline regardless
+     * of the configured auto-screenshot mode. Use it for explicit checkpoints
+     * inside the test body.
+     *
+     * @param label — human label for this checkpoint (default: `"manual"`)
+     *
+     * @example
+     * ```ts
+     * await page.goto("/checkout");
+     * await page.captureScreenshot("cart-loaded");
+     * ```
+     */
+    async captureScreenshot(label = "manual") {
+        await this._evidence?.captureShot(label, "manual");
     }
-    _sanitizeLabel(label) {
-        return label.replace(/[^a-z0-9_-]/gi, "_").slice(0, 60);
+    // ── Storage state (cookies + localStorage) ──────────────────────────
+    /**
+     * Capture the current page's cookies + localStorage — a thin "login once,
+     * reuse the session" primitive. Pass the result to `browser({ storageState })`
+     * on a fresh page to skip a UI login flow.
+     *
+     * @example
+     * ```ts
+     * await page.fill('[data-testid="username"]', "ada");
+     * await page.click('[data-testid="login-btn"]');
+     * const state = await page.getStorageState();
+     * ```
+     */
+    async getStorageState() {
+        if (!this._evidence)
+            return {};
+        return await this._evidence.captureStorageState(this.raw);
     }
-    async _ensureDir(dir) {
-        const { mkdir } = await import("node:fs/promises");
-        await mkdir(dir, { recursive: true });
+    // ── Dialog & popup ───────────────────────────────────────────────────
+    /**
+     * Register a handler for the next native dialogs (`alert`/`confirm`/`prompt`/
+     * `beforeunload`) on this page, overriding the plugin's `dialogMode` default.
+     * The handler MUST resolve the dialog itself (`dialog.accept()` /
+     * `dialog.dismiss()`) — Glubean will not also auto-resolve it.
+     *
+     * A `browser:dialog` evidence event is emitted for every dialog regardless
+     * of whether a handler is registered.
+     *
+     * @example
+     * ```ts
+     * page.onDialog((dialog) => dialog.accept());
+     * await page.click('[data-testid="clear-cart-btn"]'); // triggers confirm()
+     * ```
+     */
+    onDialog(handler) {
+        this._dialogHandler = handler;
     }
-    async _saveScreenshot(filename, label) {
-        if (this._ctx.saveArtifact) {
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            const buffer = (await this.raw.screenshot({
-                fullPage: true,
-                encoding: "binary",
-            }));
-            const id = await this._ctx.saveArtifact(filename, buffer, {
-                type: "screenshot",
-                mimeType: "image/png",
+    /**
+     * Run `action`, wait for it to open a popup (`window.open()` / `target="_blank"`),
+     * and return the popup as a fully-instrumented page (its own evidence session —
+     * network trace, console forwarding, screenshots — just like the parent).
+     *
+     * A `browser:popup` evidence event is emitted for every popup regardless of
+     * whether `waitForPopup()` is used to capture it.
+     *
+     * @example
+     * ```ts
+     * const popup = await page.waitForPopup(() => page.click('[data-testid="policy-link"]'));
+     * await popup.expectText("body", "Return Policy");
+     * await popup.close();
+     * ```
+     */
+    async waitForPopup(action, options) {
+        const timeout = options?.timeout ?? this._actionTimeout;
+        const start = Date.now();
+        // Named listener + timer so BOTH are always cleaned up — a failed wait
+        // must not leave a stale `popup` listener behind (it would swallow a later
+        // popup and accumulate across repeated failed waits).
+        let timer;
+        let onPopup;
+        const popupPromise = new Promise((resolve, reject) => {
+            timer = setTimeout(() => {
+                reject(new Error(`waitForPopup: no popup opened after ${timeout}ms`));
+            }, timeout);
+            onPopup = (popup) => {
+                if (popup) {
+                    // Register the popup in the owning browser's open-page accounting
+                    // SYNCHRONOUSLY on the open event — before awaiting `action()` to
+                    // settle. Otherwise a popup that opens and closes within `action()`
+                    // would fire its `close` before `_track()` wired the decrementing
+                    // listener, permanently pinning `_openPages` above zero and
+                    // suppressing browser auto-close.
+                    this._owner?._track(popup);
+                    resolve(popup);
+                }
+                else {
+                    reject(new Error("waitForPopup: popup event fired with no page"));
+                }
+            };
+            this.raw.once("popup", onPopup);
+        });
+        const cleanup = () => {
+            if (timer)
+                clearTimeout(timer);
+            if (onPopup)
+                this.raw.off("popup", onPopup);
+        };
+        try {
+            const [rawPopup] = await Promise.all([popupPromise, action()]);
+            cleanup();
+            this._ctx.action({
+                category: "browser:waitForPopup",
+                target: rawPopup.url(),
+                duration: Date.now() - start,
+                status: "ok",
             });
-            this._ctx.event({
-                type: "browser:screenshot",
-                data: { artifactId: id, label, fullPage: true },
+            return await GlubeanPage._create(rawPopup, this._baseUrl, this._ctx, this._options, this._testId, this._owner);
+        }
+        catch (err) {
+            cleanup();
+            this._ctx.action({
+                category: "browser:waitForPopup",
+                target: "(popup)",
+                duration: Date.now() - start,
+                status: "timeout",
+                detail: { error: String(err) },
             });
-            return id;
+            throw err;
         }
-        // Legacy fallback: direct file write when saveArtifact is not available
-        const dir = `${this._screenshotDir}/${this._sanitizeLabel(this._testId)}`;
-        await this._ensureDir(dir);
-        const path = `${dir}/${filename}`;
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        await this.raw.screenshot({ path, fullPage: true });
-        this._ctx.event({
-            type: "browser:screenshot",
-            data: { path, label, fullPage: true },
-        });
-        return path;
-    }
-    async _captureStep(action) {
-        if (this._screenshotMode !== "every-step")
-            return;
-        this._stepCounter++;
-        const num = String(this._stepCounter).padStart(3, "0");
-        const ts = this._formatTimestamp();
-        await this._saveScreenshot(`${num}-${this._sanitizeLabel(action)}-${ts}.png`, action);
     }
-    async _captureFailure(action) {
-        if (this._screenshotMode === "off")
-            return;
-        this._stepCounter++;
-        const num = String(this._stepCounter).padStart(3, "0");
-        const ts = this._formatTimestamp();
+    // ── Downloads ────────────────────────────────────────────────────────
+    /**
+     * Run `action`, wait for it to produce a completed download, and return
+     * the download's metadata. A `browser:download` evidence event is emitted
+     * for every download (`completed` or `canceled`) regardless of whether
+     * `waitForDownload()` is used to capture it — like `waitForPopup()`.
+     *
+     * @example
+     * ```ts
+     * const dl = await page.waitForDownload(() => page.click('[data-testid="download-receipt"]'));
+     * ctx.assert(dl.suggestedFilename.endsWith(".txt"), "expected a .txt receipt");
+     * ```
+     */
+    async waitForDownload(action, options) {
+        const timeout = options?.timeout ?? this._actionTimeout;
+        const start = Date.now();
+        if (!this._evidence) {
+            throw new Error("waitForDownload: evidence session not attached");
+        }
+        // Register the wait BEFORE the action so a fast download can't slip past,
+        // and scope it to THIS action: if `action()` throws, abort the wait so it
+        // neither leaks a waiter nor gets satisfied by a later, unrelated download.
+        const ac = new AbortController();
+        const waitPromise = this._evidence.waitForDownload(timeout, ac.signal);
         try {
-            await this._saveScreenshot(`FAIL-${num}-${this._sanitizeLabel(action)}-${ts}.png`, `FAIL:${action}`);
+            await action();
         }
-        catch {
-            // best-effort — page may be in a broken state
+        catch (err) {
+            ac.abort();
+            await waitPromise.catch(() => { }); // settle the aborted wait; swallow its rejection
+            this._ctx.action({
+                category: "browser:waitForDownload",
+                target: "(download)",
+                duration: Date.now() - start,
+                status: "timeout",
+                detail: { error: String(err) },
+            });
+            throw err;
+        }
+        try {
+            const entry = await waitPromise;
+            this._ctx.action({
+                category: "browser:waitForDownload",
+                target: entry.suggestedFilename,
+                duration: Date.now() - start,
+                status: "ok",
+                detail: { url: entry.url, path: entry.path },
+            });
+            return entry;
+        }
+        catch (err) {
+            this._ctx.action({
+                category: "browser:waitForDownload",
+                target: "(download)",
+                duration: Date.now() - start,
+                status: "timeout",
+                detail: { error: String(err) },
+            });
+            throw err;
         }
     }
+    // ── iframe ───────────────────────────────────────────────────────────
     /**
-     * Capture a screenshot for a test-level failure (e.g. assertion error).
+     * Locate an `<iframe>` matching `selector` and return its content frame,
+     * wrapped with the same locator API as `GlubeanPage` (`byTestId`/`byText`/
+     * `byRole`/`byLabel`, `click`/`fill`/`type`/`hover`, `expectVisible`/
+     * `expectText`/`expectHidden`).
      *
-     * Call this in the fixture's catch block to get a final-state screenshot
-     * when the test body throws.
+     * CDP already handles the execution-context switch into the frame (that's
+     * Puppeteer's own `Frame` machinery) — this method is purely the
+     * encapsulation-layer half: locator ergonomics scoped to the frame instead
+     * of the top-level page.
+     *
+     * @example
+     * ```ts
+     * const policy = await page.frame('[data-testid="policy-frame"]');
+     * await policy.expectText("body", "Return Policy");
+     * ```
      */
-    async screenshotOnFailure() {
-        if (this._screenshotMode === "off")
-            return;
-        const ts = this._formatTimestamp();
+    async frame(selector, options) {
+        const timeout = options?.timeout ?? this._actionTimeout;
+        const start = Date.now();
         try {
-            await this._saveScreenshot(`FAIL-final-${ts}.png`, "FAIL:final");
+            const handle = await this.raw.waitForSelector(selector, { timeout });
+            if (!handle) {
+                throw new Error(`frame("${selector}"): element not found`);
+            }
+            // try/finally so the handle is disposed even if contentFrame() throws.
+            let contentFrame;
+            try {
+                contentFrame = await handle.contentFrame();
+            }
+            finally {
+                await handle.dispose();
+            }
+            if (!contentFrame) {
+                throw new Error(`frame("${selector}"): element matched but is not an <iframe> (no content frame)`);
+            }
+            this._ctx.action({
+                category: "browser:frame",
+                target: selector,
+                duration: Date.now() - start,
+                status: "ok",
+                detail: { url: contentFrame.url() },
+            });
+            return createFrame(contentFrame, {
+                action: (e) => this._ctx.action(e),
+                captureStep: (label) => this._evidence?.captureShot(label, "step") ?? Promise.resolve(),
+                captureFailure: (label) => this._evidence?.captureShot(label, "failure") ?? Promise.resolve(),
+            }, this._actionTimeout);
         }
-        catch {
-            // best-effort
+        catch (err) {
+            this._ctx.action({
+                category: "browser:frame",
+                target: selector,
+                duration: Date.now() - start,
+                status: "timeout",
+                detail: { error: String(err) },
+            });
+            await this._evidence?.captureShot(`frame-${selector}`, "failure");
+            throw err;
         }
     }
     // ── Navigation & interaction ────────────────────────────────────────
@@ -300,7 +625,7 @@ export class GlubeanPage {
                 status: "error",
                 detail: { url: resolvedUrl, error: String(err) },
             });
-            await this._captureFailure(`goto-${url}`);
+            await this._evidence?.captureShot(`goto-${url}`, "failure");
             throw err;
         }
         const duration = Date.now() - start;
@@ -315,7 +640,7 @@ export class GlubeanPage {
         if (this._metricsEnabled) {
             await collectNavigationMetrics(this.raw, (name, value, opts) => this._ctx.metric(name, value, opts), resolvedUrl);
         }
-        await this._captureStep(`goto-${url}`);
+        await this._evidence?.captureShot(`goto-${url}`, "step");
     }
     /**
      * Create a WrappedLocator for the given selector.
@@ -337,9 +662,9 @@ export class GlubeanPage {
         const inner = this.raw.locator(selector);
         return createWrappedLocator(inner, {
             action: (e) => this._ctx.action(e),
-            captureStep: (label) => this._captureStep(label),
-            captureFailure: (label) => this._captureFailure(label),
-        }, selector);
+            captureStep: (label) => this._evidence?.captureShot(label, "step") ?? Promise.resolve(),
+            captureFailure: (label) => this._evidence?.captureShot(label, "failure") ?? Promise.resolve(),
+        }, selector, this.raw);
     }
     /**
      * Locate an element by its `data-testid` attribute.
@@ -451,10 +776,10 @@ export class GlubeanPage {
                 status: "error",
                 detail: { error: String(err) },
             });
-            await this._captureFailure(`clickAndNavigate-${selector}`);
+            await this._evidence?.captureShot(`clickAndNavigate-${selector}`, "failure");
             throw err;
         }
-        await this._captureStep(`clickAndNavigate-${selector}`);
+        await this._evidence?.captureShot(`clickAndNavigate-${selector}`, "step");
     }
     /**
      * Type text into an element matching the selector (appends — does not clear).
@@ -530,7 +855,7 @@ export class GlubeanPage {
                 status: "timeout",
                 detail: { values, error: String(err) },
             });
-            await this._captureFailure(`select-${selector}`);
+            await this._evidence?.captureShot(`select-${selector}`, "failure");
             throw err;
         }
     }
@@ -602,10 +927,10 @@ export class GlubeanPage {
                 status: "timeout",
                 detail: { fileCount: filePaths.length, error: String(err) },
             });
-            await this._captureFailure(`upload-${selector}`);
+            await this._evidence?.captureShot(`upload-${selector}`, "failure");
             throw err;
         }
-        await this._captureStep(`upload-${selector}`);
+        await this._evidence?.captureShot(`upload-${selector}`, "step");
     }
     /**
      * Click a button/element that triggers a file chooser dialog, then accept
@@ -645,10 +970,10 @@ export class GlubeanPage {
                 status: "timeout",
                 detail: { fileCount: filePaths.length, error: String(err) },
             });
-            await this._captureFailure(`chooseFile-${triggerSelector}`);
+            await this._evidence?.captureShot(`chooseFile-${triggerSelector}`, "failure");
             throw err;
         }
-        await this._captureStep(`chooseFile-${triggerSelector}`);
+        await this._evidence?.captureShot(`chooseFile-${triggerSelector}`, "step");
     }
     /** Query a single element by selector. */
     async $(selector) {
@@ -930,7 +1255,7 @@ export class GlubeanPage {
             });
         }
         catch (err) {
-            await this._captureFailure(`expectURL-${String(pattern)}`);
+            await this._evidence?.captureShot(`expectURL-${String(pattern)}`, "failure");
             this._ctx.action({
                 category: "browser:assert",
                 target: `expectURL(${JSON.stringify(String(pattern))})`,
@@ -983,7 +1308,7 @@ export class GlubeanPage {
             });
         }
         catch (err) {
-            await this._captureFailure(`expectText-${selector}`);
+            await this._evidence?.captureShot(`expectText-${selector}`, "failure");
             this._ctx.action({
                 category: "browser:assert",
                 target: `expectText("${selector}")`,
@@ -1014,7 +1339,7 @@ export class GlubeanPage {
             });
         }
         catch (err) {
-            await this._captureFailure(`expectVisible-${selector}`);
+            await this._evidence?.captureShot(`expectVisible-${selector}`, "failure");
             this._ctx.action({
                 category: "browser:assert",
                 target: `expectVisible("${selector}")`,
@@ -1041,7 +1366,7 @@ export class GlubeanPage {
             });
         }
         catch (err) {
-            await this._captureFailure(`expectHidden-${selector}`);
+            await this._evidence?.captureShot(`expectHidden-${selector}`, "failure");
             this._ctx.action({
                 category: "browser:assert",
                 target: `expectHidden("${selector}")`,
@@ -1079,7 +1404,7 @@ export class GlubeanPage {
             });
         }
         catch (err) {
-            await this._captureFailure(`expectAttribute-${selector}-${attr}`);
+            await this._evidence?.captureShot(`expectAttribute-${selector}-${attr}`, "failure");
             this._ctx.action({
                 category: "browser:assert",
                 target: `expectAttribute("${selector}", "${attr}")`,
@@ -1112,7 +1437,7 @@ export class GlubeanPage {
             });
         }
         catch (err) {
-            await this._captureFailure(`expectCount-${selector}`);
+            await this._evidence?.captureShot(`expectCount-${selector}`, "failure");
             this._ctx.action({
                 category: "browser:assert",
                 target: `expectCount("${selector}")`,
@@ -1123,6 +1448,82 @@ export class GlubeanPage {
             throw err;
         }
     }
+    /**
+     * Assert that a checkbox/radio's `.checked` state matches `expected`.
+     * Retries until match or timeout.
+     *
+     * @param expected — desired `.checked` value. @default true
+     */
+    async expectChecked(selector, expected = true, options) {
+        const start = Date.now();
+        let lastVal = null;
+        try {
+            lastVal = await this._retryUntil(() => this.raw.$eval(selector, 
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            (el) => Boolean(el.checked)).catch(() => null), (val) => val === expected, (lv) => `expectChecked("${selector}"): expected checked=${expected} ` +
+                `but received checked=${JSON.stringify(lv)} after ${options?.timeout ?? 5_000}ms`, options);
+            this._ctx.action({
+                category: "browser:assert",
+                target: `expectChecked("${selector}")`,
+                duration: Date.now() - start,
+                status: "ok",
+                detail: { expected, actual: lastVal },
+            });
+        }
+        catch (err) {
+            await this._evidence?.captureShot(`expectChecked-${selector}`, "failure");
+            this._ctx.action({
+                category: "browser:assert",
+                target: `expectChecked("${selector}")`,
+                duration: Date.now() - start,
+                status: "timeout",
+                detail: { expected, actual: lastVal, error: String(err) },
+            });
+            throw err;
+        }
+    }
+    /**
+     * Assert that an input/textarea/select's `.value` matches `expected`.
+     * Retries until match or timeout. For text content of non-form elements,
+     * use `expectText()` instead.
+     */
+    async expectValue(selector, expected, options) {
+        const matches = (val) => {
+            if (val === null)
+                return false;
+            return expected instanceof RegExp ? expected.test(val) : val === expected;
+        };
+        const start = Date.now();
+        let lastVal = null;
+        try {
+            lastVal = await this._retryUntil(() => this.raw.$eval(selector, 
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            (el) => (el.value ?? "")).catch(() => null), matches, (lv) => `expectValue("${selector}"): expected ${JSON.stringify(expected)} ` +
+                `but received ${JSON.stringify(lv)} after ${options?.timeout ?? 5_000}ms`, options);
+            this._ctx.action({
+                category: "browser:assert",
+                target: `expectValue("${selector}")`,
+                duration: Date.now() - start,
+                status: "ok",
+                detail: { expected: String(expected), actual: lastVal },
+            });
+        }
+        catch (err) {
+            await this._evidence?.captureShot(`expectValue-${selector}`, "failure");
+            this._ctx.action({
+                category: "browser:assert",
+                target: `expectValue("${selector}")`,
+                duration: Date.now() - start,
+                status: "timeout",
+                detail: {
+                    expected: String(expected),
+                    actual: lastVal,
+                    error: String(err),
+                },
+            });
+            throw err;
+        }
+    }
     // ── Phase 8: Network Interception & Assertions ────────────────────
     /**
      * Wait for a network request matching `pattern`.
@@ -1276,11 +1677,11 @@ export class GlubeanPage {
             throw err;
         }
     }
-    /** Clean up: remove CDP listeners and close the page. */
+    /** Clean up: detach the shared evidence CDP session and close the page. */
     async close() {
-        if (this._networkCleanup) {
-            await this._networkCleanup();
-            this._networkCleanup = null;
+        if (this._evidence) {
+            await this._evidence.detach();
+            this._evidence = null;
         }
         try {
             await this.raw.close();