@descryy/mcp 0.11.3 → 0.11.5

package/dist/browser/playwright-driver.js

@@ -1,1479 +0,0 @@
-/**
- * The real `BrowserDriver`, over `@descryy/runtime-browser`. Import stays
- * dynamic — `loadRuntimeModule` is a test injection seam (fake module, no
- * browser needed). Adds only element refs over the runtime; stack-trace parsing is caller-supplied (rule 1: no language named here).
- */
-var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
-    if (typeof path === "string" && /^\.\.?\//.test(path)) {
-        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
-            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
-        });
-    }
-    return path;
-};
-import { BrowserSessionCrashedError, NoSuchOptionError, NotOperableError, NotSelectableError, NotSubmittableError, UnknownElementRefError, } from "./driver.js";
-import { clampWaitTimeout, describeWaitTarget, isEmptyWaitTarget, matchesWaitTarget, WAIT_POLL_INTERVAL_MS, } from "./wait-target.js";
-import { PROBE_CONSTANTS, probeInPage } from "./page-probe.js";
-/** The module the driver composes. Named once, imported at call time. */
-const RUNTIME_BROWSER_MODULE = "@descryy/runtime-browser";
-const defaultRuntimeModuleLoader = () => import(__rewriteRelativeImportExtension(RUNTIME_BROWSER_MODULE));
-/** Same seam, for the optional identity-grounding module — imported dynamically and only
- *  when `groundIdentity` is set, so a build or a session that never asks for it pays nothing. */
-const IDENTITY_GROUNDING_MODULE = "@descryy/runtime-identity-grounding";
-const defaultIdentityGroundingModuleLoader = () => import(__rewriteRelativeImportExtension(IDENTITY_GROUNDING_MODULE));
-/** Ceiling on waiting for network activity to *start* — no signal proves "never will". Kept at the old fixed 300ms so a no-op action observes the same as before. */
-const ACTIVITY_GRACE_MS = 300;
-/** How long after the last request event counts as settled; fires only once activity is seen, so it measures a gap, not a guess about more coming. */
-const NETWORK_QUIET_MS = 120;
-/** Ceiling on the whole wait; reaching it is recorded on the observation and disclosed, never swallowed. */
-const SETTLE_TIMEOUT_MS = 5_000;
-/** How often the settle loop re-checks. Small enough not to add latency of its own. */
-const POLL_INTERVAL_MS = 10;
-/** Elements an agent can act on — deliberately narrow; a full-page snapshot would blow the reply budget. `[role]` included for custom controls. */
-const INTERACTIVE = "a, button, input, select, textarea, [role], [onclick], summary";
-/** How many scroll-and-re-check rounds a reveal pass runs before it stops and says it stopped. */
-const REVEAL_MAX_PASSES = 12;
-/** How long after a scroll before re-checking. A lazily-rendered row needs a frame or two to exist. */
-const REVEAL_SETTLE_MS = 150;
-/** `RawElementIdentity` -> the port's own `ElementComponentIdentity` — the one place the two
- *  vocabularies are joined, so a change to either shows up as one diff here. */
-function mapIdentity(raw) {
-    switch (raw.outcome) {
-        case "grounded":
-            return {
-                outcome: "grounded",
-                component: raw.component.name,
-                file: raw.sourceLocation.file,
-                line: raw.sourceLocation.line,
-                authoredSource: raw.authoredSource,
-                reason: null,
-            };
-        case "component-only":
-            return {
-                outcome: "component-only",
-                component: raw.component.name,
-                file: null,
-                line: null,
-                authoredSource: false,
-                reason: raw.reason,
-            };
-        case "refused":
-            return {
-                outcome: "refused",
-                component: null,
-                file: null,
-                line: null,
-                authoredSource: false,
-                reason: raw.reason,
-            };
-    }
-}
-/** Folds the session's install-time identity warnings into a drained observation, once —
- *  same drain-not-peek discipline `drainEvidence` and `close` already hold every other field
- *  to, so a warning surfaces on the first read after it happened and never again. */
-function withIdentityWarnings(observation, warnings) {
-    if (warnings.length === 0)
-        return observation;
-    const drained = [...warnings];
-    warnings.length = 0;
-    return { ...observation, evidenceWarnings: [...observation.evidenceWarnings, ...drained] };
-}
-/** Grounds one selector, never throwing — a probe failure is reported as a named refusal
- *  (rule 2: no guess), the same as every other outcome the grounder itself can name. */
-async function groundOne(grounder, page, selector) {
-    try {
-        const raw = await grounder.ground(page, selector);
-        return mapIdentity(raw);
-    }
-    catch (error) {
-        return {
-            outcome: "refused",
-            component: null,
-            file: null,
-            line: null,
-            authoredSource: false,
-            reason: `the identity probe failed: ${error instanceof Error ? error.message : String(error)}`,
-        };
-    }
-}
-/** What one element looks like from inside the page. Serialized and run there, so it closes over
- *  nothing in this module — every helper it needs is declared inside it.
- *
- *  Exported for `browser-element-describe.test.ts`: role, name and renderedness are pure
- *  functions of one element, and pinning their decision table should not need a browser. */
-export function describeElement(el) {
-    const tag = el.tagName.toLowerCase();
-    const explicit = el.getAttribute("role");
-    const type = el.getAttribute("type")?.toLowerCase() ?? null;
-    /** The HTML→ARIA role of this element. The old chain ended `: tag`, which reported
-     *  `input[type="number"]` as role `"input"` — a role no agent filters on and no verb
-     *  validates against, so a real control went silently missing from every role-filtered
-     *  read. The mapping below is HTML's own, and it names no framework (rule 1).
-     *
-     *  It still ends at the tag for a tag this does not know, deliberately: `[role]` and
-     *  `[onclick]` put arbitrary elements into the query, and inventing a role for one of
-     *  them would be this same defect pointed the other way. */
-    function derivedRole() {
-        if (tag === "a")
-            return "link";
-        if (tag === "button")
-            return "button";
-        if (tag === "textarea")
-            return "textbox";
-        // `summary` is the control that opens a `<details>`; a click is what it takes.
-        if (tag === "summary")
-            return "button";
-        if (tag === "select") {
-            const multiple = el.getAttribute("multiple") !== null;
-            const size = Number(el.getAttribute("size") ?? "1");
-            return multiple || size > 1 ? "listbox" : "combobox";
-        }
-        if (tag !== "input")
-            return tag;
-        switch (type) {
-            case "button":
-            case "submit":
-            case "reset":
-            case "image":
-                return "button";
-            case "checkbox":
-                return "checkbox";
-            case "radio":
-                return "radio";
-            case "range":
-                return "slider";
-            case "number":
-                return "spinbutton";
-            case "search":
-                return "searchbox";
-            // `password` has no ARIA role of its own; `textbox` is both the useful answer and the
-            // true one about how it is operated. The rest are HTML's textbox-mapped types.
-            case null:
-            case "text":
-            case "email":
-            case "tel":
-            case "url":
-            case "password":
-                return "textbox";
-            default:
-                // `file`, `color`, `date`, `hidden`, and anything a later HTML adds. Reporting the
-                // tag here is a disclosed gap; reporting `textbox` would be a wrong fact.
-                return tag;
-        }
-    }
-    const role = explicit ?? derivedRole();
-    /** A pragmatic accessible-name approximation, not a full AccName implementation.
-     *
-     *  One case is carved out rather than approximated: a **chooser's own contents are its
-     *  options**, so `innerText` on a `<select>` returns the list of things it can be set to,
-     *  and a period picker came back named `"This month\nLast month"`. That is not a rough
-     *  name, it is a false one — no person calls the control that, and the `select` verb
-     *  matches on name. A chooser therefore skips the text tiers entirely and is left unnamed
-     *  when nothing else names it. Unnamed is a gap; named after its options is a lie. */
-    function derivedName() {
-        const aria = el.getAttribute("aria-label");
-        if (aria !== null && aria.trim() !== "")
-            return aria;
-        if (tag !== "select") {
-            const inner = el.innerText?.trim();
-            if (inner !== undefined && inner !== "")
-                return inner;
-            const text = el.textContent?.trim();
-            if (text !== undefined && text !== null && text !== "")
-                return text;
-        }
-        // A push-button input carries its label in `value`, where no text tier would find it.
-        if (tag === "input" && (type === "button" || type === "submit" || type === "reset")) {
-            const value = el.getAttribute("value");
-            if (value !== null && value.trim() !== "")
-                return value.trim();
-        }
-        return el.getAttribute("placeholder") ?? el.getAttribute("title") ?? el.getAttribute("name") ?? "";
-    }
-    const name = derivedName();
-    /** Whether the page is laying this element out and painting it — true, false, or `null`
-     *  when nothing available could answer.
-     *
-     *  **Deliberately not a viewport test.** An element below the fold is on the page and the
-     *  reveal pass depends on finding it; treating off-screen as hidden would trade this
-     *  precision defect for a recall one. What it does reject is an element the page renders
-     *  nowhere at all: `display:none`, the `hidden` attribute, a closed `<dialog>`,
-     *  `content-visibility: hidden`, `visibility: hidden`, and `<canvas>` fallback content.
-     *
-     *  Opacity is **not** rejected: a zero-opacity element still occupies space and still
-     *  takes a click, and a fade-in caught mid-animation would vanish from the snapshot. */
-    function renderedState() {
-        if (typeof el.checkVisibility === "function") {
-            try {
-                return el.checkVisibility({ visibilityProperty: true });
-            }
-            catch {
-                return null;
-            }
-        }
-        if (typeof el.getClientRects !== "function")
-            return null;
-        try {
-            if (el.getClientRects().length === 0)
-                return false;
-        }
-        catch {
-            return null;
-        }
-        const view = globalThis.getComputedStyle;
-        if (typeof view !== "function")
-            return null;
-        try {
-            const visibility = view.call(globalThis, el)?.visibility;
-            if (visibility === undefined)
-                return null;
-            return visibility !== "hidden" && visibility !== "collapse";
-        }
-        catch {
-            return null;
-        }
-    }
-    // The node's own root: the document for a light-DOM element, the shadow root for one inside
-    // an open shadow root. Only a shadow root has a `host`, which is what tells them apart, and
-    // it is also the scope a uniqueness check has to run in — `ownerDocument.querySelectorAll`
-    // matches nothing at all for a shadow child, so every such element used to come back with a
-    // null selector for a reason that read like "no stable hook".
-    const root = typeof el.getRootNode === "function" ? el.getRootNode() : el.ownerDocument;
-    const inShadowRoot = root !== el.ownerDocument && root.host !== undefined && root.host !== null;
-    // Computed in this same round trip so role/name/selector read off one live DOM state.
-    // Rejects ids that look generated (hex run, React's `:r0:` useId
-    // style, or blank) — "stable across reload" is what a generated id lacks.
-    const GENERATED_ID = /[0-9a-f]{8}|:r[0-9a-z]+:|^\s*$/i;
-    const FORM_CONTROLS = ["input", "select", "textarea", "button"];
-    function escapeAttrValue(value) {
-        return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
-    }
-    function isUnique(candidate) {
-        try {
-            return root.querySelectorAll(candidate).length === 1;
-        }
-        catch {
-            // Invalid selector (rare) is treated as "no candidate", not thrown.
-            return false;
-        }
-    }
-    /** The element's own stable-hook selector, or null. Used both on the target itself and while climbing for a structural path's anchor. */
-    function stableHookSelector(node) {
-        const testId = node.getAttribute("data-testid");
-        if (testId !== null && testId.trim() !== "")
-            return `[data-testid="${escapeAttrValue(testId)}"]`;
-        const testAttr = node.getAttribute("data-test");
-        if (testAttr !== null && testAttr.trim() !== "")
-            return `[data-test="${escapeAttrValue(testAttr)}"]`;
-        const id = node.getAttribute("id");
-        if (id !== null && !GENERATED_ID.test(id))
-            return `[id="${escapeAttrValue(id)}"]`;
-        return null;
-    }
-    function nthOfTypeSegment(node, parent) {
-        const nodeTag = node.tagName.toLowerCase();
-        const siblings = parent.querySelectorAll(`:scope > ${nodeTag}`);
-        if (siblings.length <= 1)
-            return nodeTag;
-        for (let i = 0; i < siblings.length; i += 1) {
-            if (siblings.item(i) === node)
-                return `${nodeTag}:nth-of-type(${i + 1})`;
-        }
-        return nodeTag;
-    }
-    /** A bounded path from the nearest ancestor carrying a stable hook, capped at 6 segments. Null
-     *  when none is found in range — including when the climb reaches a shadow boundary, where
-     *  `parentElement` is null and there is genuinely no further ancestor inside this root. */
-    function structuralPath(target) {
-        const segments = [];
-        let node = target;
-        for (let depth = 0; depth < 6; depth += 1) {
-            const parent = node.parentElement;
-            if (parent === null)
-                return null;
-            segments.unshift(nthOfTypeSegment(node, parent));
-            const hook = stableHookSelector(parent);
-            if (hook !== null) {
-                const candidate = `${hook} > ${segments.join(" > ")}`;
-                return isUnique(candidate) ? candidate : null;
-            }
-            node = parent;
-        }
-        return null;
-    }
-    function computeSelector(target) {
-        // Priority order: first unique candidate wins. Each tier is checked
-        // independently — a shared data-testid isn't addressable either,
-        // so the next tier gets a turn instead of stopping there.
-        const testId = target.getAttribute("data-testid");
-        if (testId !== null && testId.trim() !== "") {
-            const candidate = `[data-testid="${escapeAttrValue(testId)}"]`;
-            if (isUnique(candidate))
-                return candidate;
-        }
-        const testAttr = target.getAttribute("data-test");
-        if (testAttr !== null && testAttr.trim() !== "") {
-            const candidate = `[data-test="${escapeAttrValue(testAttr)}"]`;
-            if (isUnique(candidate))
-                return candidate;
-        }
-        const id = target.getAttribute("id");
-        if (id !== null && !GENERATED_ID.test(id)) {
-            const candidate = `[id="${escapeAttrValue(id)}"]`;
-            if (isUnique(candidate))
-                return candidate;
-        }
-        const controlTag = target.tagName.toLowerCase();
-        const controlName = target.getAttribute("name");
-        if (controlName !== null && controlName.trim() !== "" && FORM_CONTROLS.includes(controlTag)) {
-            const candidate = `${controlTag}[name="${escapeAttrValue(controlName)}"]`;
-            if (isUnique(candidate))
-                return candidate;
-        }
-        const explicitRole = target.getAttribute("role");
-        const ariaLabel = target.getAttribute("aria-label");
-        if (explicitRole !== null && ariaLabel !== null && ariaLabel.trim() !== "") {
-            const candidate = `[role="${escapeAttrValue(explicitRole)}"][aria-label="${escapeAttrValue(ariaLabel)}"]`;
-            if (isUnique(candidate))
-                return candidate;
-        }
-        return structuralPath(target);
-    }
-    return { role, name: name.slice(0, 200), selector: computeSelector(el), inShadowRoot, rendered: renderedState() };
-}
-/** Said once, so the cap and the sentence describing it cannot drift apart. */
-const CONTAINER_SCAN_NOTE = "this page holds more elements than the reveal pass scans for scrollable containers, so a list " +
-    "inside one past that point was not scrolled and anything only it holds is not above";
-/**
- * One reveal step, run inside the page: scrolls the document **and every scrollable container
- * in it** by just under their own height.
- *
- * The container half is the point. `window.scrollBy` does nothing to a list inside
- * `overflow: auto` — a shape common enough that a window-only reveal reports "nothing below
- * the fold" about a page whose entire content is below one. The step stays under a full
- * viewport so a row sitting on the seam is never scrolled past between two enumerations.
- *
- * Serialized and run in the page, so it closes over nothing in this module — the scan cap is
- * declared inside it for that reason and mirrored in `CONTAINER_SCAN_NOTE` above.
- */
-function revealStep() {
-    const win = globalThis;
-    const doc = win.document;
-    const SCAN_CAP = 5000;
-    let scrolled = false;
-    if (win.scrollY + win.innerHeight < doc.documentElement.scrollHeight - 1) {
-        win.scrollBy(0, Math.round(win.innerHeight * 0.9));
-        scrolled = true;
-    }
-    const all = doc.querySelectorAll("*");
-    const limit = all.length > SCAN_CAP ? SCAN_CAP : all.length;
-    let containers = 0;
-    for (let i = 0; i < limit; i += 1) {
-        const node = all.item(i);
-        if (node === null)
-            continue;
-        // Geometry first, style second: the overflow read is the expensive one, and an element
-        // whose content fits inside it can never be a scroller whatever its overflow says.
-        if (typeof node.scrollHeight !== "number" || typeof node.clientHeight !== "number")
-            continue;
-        if (node.clientHeight === 0 || node.scrollHeight <= node.clientHeight + 1)
-            continue;
-        const overflow = typeof win.getComputedStyle === "function" ? win.getComputedStyle(node)?.overflowY : undefined;
-        if (overflow !== "auto" && overflow !== "scroll" && overflow !== "overlay")
-            continue;
-        containers += 1;
-        if (node.scrollTop + node.clientHeight < node.scrollHeight - 1) {
-            node.scrollBy(0, Math.round(node.clientHeight * 0.9));
-            scrolled = true;
-        }
-    }
-    return { y: win.scrollY, scrolled, containers, scanCapped: all.length > SCAN_CAP };
-}
-/** A frame's URL, or "" — a frame detaching mid-snapshot throws from `url()`. */
-function safeUrl(frame) {
-    try {
-        return typeof frame.url === "function" ? frame.url() : "";
-    }
-    catch {
-        return "";
-    }
-}
-/** Something a person can read back: the frame's name, else the iframe element's id or title.
- *  Null when it carries none — the reply then falls back to the frame's URL. */
-async function frameLabel(frame) {
-    try {
-        const declared = typeof frame.name === "function" ? frame.name() : "";
-        if (declared !== "")
-            return declared;
-        if (typeof frame.frameElement !== "function")
-            return null;
-        const element = await frame.frameElement();
-        try {
-            if (typeof element.getAttribute !== "function")
-                return null;
-            const id = await element.getAttribute("id");
-            if (id !== null && id.trim() !== "")
-                return id;
-            const title = await element.getAttribute("title");
-            if (title !== null && title.trim() !== "")
-                return title;
-            return null;
-        }
-        finally {
-            await element.dispose().catch(() => { });
-        }
-    }
-    catch {
-        return null;
-    }
-}
-/** Identity for reveal accounting. Elements are compared as a multiset, not by ref: a ref is
- *  issued per snapshot and two enumerations of the same row never share one. */
-function countKeys(elements) {
-    const counts = new Map();
-    for (const element of elements) {
-        const key = `${element.frame?.id ?? ""}\u0000${element.role}\u0000${element.name}\u0000${element.selector ?? ""}`;
-        counts.set(key, (counts.get(key) ?? 0) + 1);
-    }
-    return counts;
-}
-/** How many of `a` have no counterpart in `b`. */
-function surplus(a, b) {
-    let total = 0;
-    for (const [key, count] of a)
-        total += Math.max(0, count - (b.get(key) ?? 0));
-    return total;
-}
-export class BrowserBackendMissingError extends Error {
-    constructor(cause) {
-        super(`Could not load ${RUNTIME_BROWSER_MODULE}: ${cause instanceof Error ? cause.message : String(cause)}. ` +
-            "This build of @descryy/mcp does not have the browser backend installed.");
-        this.name = "BrowserBackendMissingError";
-    }
-}
-export async function createPlaywrightBrowserDriver(options = {}) {
-    let runtime;
-    try {
-        runtime = (await (options.loadRuntimeModule ?? defaultRuntimeModuleLoader)());
-    }
-    catch (error) {
-        throw new BrowserBackendMissingError(error);
-    }
-    return {
-        async launch(launchOptions) {
-            const auth = runtimeAuthFor(launchOptions);
-            const launch = await runtime.launchBrowserSessionOrRefuse({
-                headless: launchOptions.headless ?? true,
-                // B1. This used to be `{ headless }` and nothing else, while the port
-                // above already carried `storageState` and a reply note already said
-                // it had been seeded. The option reached the fake driver and stopped;
-                // against a real browser nothing was ever applied and the note was
-                // false. Building the seed here, from the target URL, is also what
-                // makes the origin a fact the runtime is *told* rather than one it
-                // has to work out.
-                ...(auth === null ? {} : { auth }),
-            });
-            if (!launch.launched) {
-                const { launched: _launched, ...refusal } = launch;
-                return { launched: false, ...refusal };
-            }
-            const session = await openSession(runtime, launch.session, launchOptions, options);
-            return { launched: true, session };
-        },
-    };
-}
-async function openSession(runtime, session, launchOptions, options) {
-    const emitted = [];
-    const actions = [];
-    const unsettled = [];
-    // Never cleared, unlike `actions` — the session's whole-lifetime provenance record for
-    // `browser_save_scenario`, not per-drain evidence. Goes out of reach the moment this closure
-    // does (session closed/reaped) — there is no other path back to it.
-    const performed = [];
-    // inFlight/lastEventAt track request activity: counted, not slept through.
-    let inFlight = 0;
-    let lastEventAt = 0;
-    session.page.on("request", () => {
-        inFlight += 1;
-        lastEventAt = Date.now();
-    });
-    const settleOne = () => {
-        inFlight = Math.max(0, inFlight - 1);
-        lastEventAt = Date.now();
-    };
-    session.page.on("requestfinished", settleOne);
-    session.page.on("requestfailed", settleOne);
-    let refs = new Map();
-    let generation = 0;
-    let closed = false;
-    let finalObservation = null;
-    /** Set when a `saveStorageStateTo` write failed. Read by `storageStateSaveFailure()`. */
-    let storageStateSaveError = null;
-    /** Set when `groundIdentity` was asked for and installed successfully. Every snapshot
-     *  element with a selector is grounded through it; one with none is never attempted
-     *  (§B1's `identity: null` distinction — see `driver.ts`). */
-    let grounder = null;
-    const identityWarnings = [];
-    const context = {
-        executionId: `mcp-browser-${session.sessionId}`,
-        configuration: { environmentTier: "tier-2-container", fidelityLevel: 2, timeoutMs: 30_000, services: {} },
-        emit: (evidence) => {
-            emitted.push(evidence);
-        },
-        ...(options.resolveSourceRoot === undefined ? {} : { resolveSourceRoot: options.resolveSourceRoot }),
-    };
-    const actionCollector = runtime.createBrowserActionCollector({
-        session,
-        ...(options.service === undefined ? {} : { service: options.service }),
-    });
-    const consoleCollector = runtime.createBrowserConsoleCollector({
-        session,
-        ...(options.service === undefined ? {} : { service: options.service }),
-        ...(options.stackParser === undefined ? {} : { stackTraceParser: options.stackParser }),
-    });
-    const networkCollector = runtime.createBrowserNetworkCollector({
-        session,
-        ...(options.service === undefined ? {} : { service: options.service }),
-        ...(options.stackParser === undefined ? {} : { stackTraceParser: options.stackParser }),
-    });
-    // Started before first navigation: Playwright's init-script contract means
-    // a collector started later misses instrumentation, reporting an
-    // honest-looking but empty stack.
-    await actionCollector.start(context);
-    await consoleCollector.start(context);
-    await networkCollector.start(context);
-    // Same contract as the collectors above, and for the same reason: the identity probe is
-    // an init script too, so it must install before the first navigation or it reports
-    // `probe-not-installed` for the document's whole lifetime. Off by default (B1) — a session
-    // that never asks for it pays no page.evaluate and loads no module.
-    if (options.groundIdentity === true) {
-        try {
-            const identityModule = (await (options.loadIdentityGroundingModule ?? defaultIdentityGroundingModuleLoader)());
-            grounder = identityModule.createFrameworkAwareGrounder(options.resolveSourceRoot === undefined ? {} : { resolveSourceRoot: options.resolveSourceRoot });
-            await grounder.install(session.page);
-        }
-        catch (error) {
-            // Honest degradation (rule 7): identity grounding could not be installed, so every
-            // element on this session reports `identity: null` — never a guess — and the reason
-            // travels on the observation rather than being swallowed.
-            grounder = null;
-            identityWarnings.push(`identity grounding was requested (groundIdentity) but could not be installed: ` +
-                `${error instanceof Error ? error.message : String(error)}. Every element on this session ` +
-                "reports identity: null rather than a guess.");
-        }
-    }
-    await actionCollector.navigate(launchOptions.targetUrl);
-    function assertUsable() {
-        if (closed || !session.isUsable())
-            throw new BrowserSessionCrashedError(session.sessionId);
-    }
-    function resolve(ref) {
-        const found = refs.get(ref);
-        if (found === undefined)
-            throw new UnknownElementRefError(ref);
-        return found;
-    }
-    function recordAction(action, ref, mode) {
-        actions.push({ action, ref, mode, url: session.page.url(), at: new Date().toISOString() });
-    }
-    function recordPerformed(action, target, url, text) {
-        performed.push({ action, target, url, text, at: new Date().toISOString() });
-    }
-    /** Waits for the action's network effect (started within `ACTIVITY_GRACE_MS`, then quiet for `NETWORK_QUIET_MS`), capped at `SETTLE_TIMEOUT_MS` — reaching the cap is recorded, never swallowed. */
-    async function settleAfterAction(action, ref) {
-        const startedAt = Date.now();
-        lastEventAt = startedAt;
-        let sawActivity = inFlight > 0;
-        for (;;) {
-            const now = Date.now();
-            const waitedMs = now - startedAt;
-            if (inFlight > 0)
-                sawActivity = true;
-            if (waitedMs >= SETTLE_TIMEOUT_MS) {
-                unsettled.push({ action, ref, waitedMs });
-                return;
-            }
-            if (sawActivity) {
-                if (inFlight === 0 && now - lastEventAt >= NETWORK_QUIET_MS)
-                    return;
-            }
-            else if (waitedMs >= ACTIVITY_GRACE_MS) {
-                return;
-            }
-            await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
-        }
-    }
-    async function dropRefs() {
-        const handles = [...refs.values()].map((r) => r.handle);
-        refs = new Map();
-        await Promise.all(handles.map((h) => h.dispose().catch(() => { })));
-    }
-    /** Every document to read, main first. When the backend exposes no frame list the page
-     *  itself is the only one, and that limitation is reported as an unread frame rather than
-     *  passed off as "this page has no iframes". */
-    function documentsToRead() {
-        if (typeof session.page.frames !== "function")
-            return { frames: [{ frame: session.page, ref: null }], frameListUnavailable: true };
-        const all = session.page.frames();
-        const main = typeof session.page.mainFrame === "function" ? session.page.mainFrame() : all[0];
-        const out = [];
-        let index = 0;
-        for (const frame of all) {
-            if (frame === main) {
-                out.unshift({ frame, ref: null });
-                continue;
-            }
-            index += 1;
-            out.push({ frame, ref: { id: `frame-${index}`, url: safeUrl(frame), name: null } });
-        }
-        if (out.length === 0 || out[0]?.ref !== null)
-            out.unshift({ frame: session.page, ref: null });
-        return { frames: out, frameListUnavailable: false };
-    }
-    /** Reads the elements of one document, describing each in a single round trip. */
-    async function enumerateFrame(frame, frameRef) {
-        const handles = await frame.$$(INTERACTIVE);
-        const elements = [];
-        let ambiguousInDocument = 0;
-        let hidden = 0;
-        let untested = 0;
-        for (const handle of handles) {
-            const described = await handle.evaluate(describeElement).catch(() => null);
-            if (described === null) {
-                await handle.dispose().catch(() => { });
-                continue;
-            }
-            // The CSS query matches what is in the document; this is what is on the page. A
-            // `display:none` menu, a closed modal and an inactive tab panel all match the query,
-            // and reporting them as usable controls is Descry stating something false about the
-            // user's screen. Withheld and counted, never dropped in silence (rule 7).
-            if (described.rendered === false) {
-                hidden += 1;
-                await handle.dispose().catch(() => { });
-                continue;
-            }
-            // `null` is "nothing could answer". The element is kept — omitting on an unanswered
-            // question would hide real controls behind a test that did not run — and the fact that
-            // the question went unanswered travels with the snapshot.
-            if (described.rendered === null)
-                untested += 1;
-            let selector = described.selector;
-            // A hook unique inside its own shadow root is not necessarily unique in the document:
-            // two instances of the same component each carry `[data-testid="submit"]`. Playwright's
-            // own CSS resolution pierces, so asking it is the same question a replay would ask.
-            if (selector !== null && described.inShadowRoot === true) {
-                const matches = await frame.$$(selector).catch(() => null);
-                if (matches !== null)
-                    await Promise.all(matches.map((m) => m.dispose().catch(() => { })));
-                if (matches === null || matches.length !== 1) {
-                    selector = null;
-                    ambiguousInDocument += 1;
-                }
-            }
-            elements.push({
-                handle,
-                role: described.role,
-                name: described.name,
-                // An element inside a frame has no saveable selector: the scenario format carries no
-                // field to name the frame, so a stored selector would replay against the main document.
-                selector: frameRef === null ? selector : null,
-                inShadowRoot: described.inShadowRoot === true,
-                frame: frameRef,
-            });
-        }
-        return { elements, ambiguousInDocument, hidden, untested };
-    }
-    /** Counts custom elements that look like closed shadow hosts. Returns null when the probe could not run. */
-    async function probeClosedHosts(frame) {
-        if (typeof frame.evaluate !== "function")
-            return null;
-        return frame
-            .evaluate(() => {
-            const page = globalThis;
-            const all = page.document.querySelectorAll("*");
-            let suspected = 0;
-            for (let i = 0; i < all.length; i += 1) {
-                const element = all.item(i);
-                if (element === null)
-                    continue;
-                // A dash in the tag name is what the custom-element spec requires of every one of
-                // them; it names no language or framework (rule 1), only the HTML naming rule.
-                if (!element.tagName.toLowerCase().includes("-"))
-                    continue;
-                if (element.shadowRoot !== null && element.shadowRoot !== undefined)
-                    continue;
-                if ((element.childElementCount ?? 0) > 0)
-                    continue;
-                suspected += 1;
-            }
-            return suspected;
-        })
-            .catch(() => null);
-    }
-    /** Reads every document, and reports each one it could not read with the reason. */
-    async function enumerateAll() {
-        const { frames: documents, frameListUnavailable } = documentsToRead();
-        const elements = [];
-        const reach = [];
-        let ambiguousInDocument = 0;
-        let suspectedClosedHosts = 0;
-        let probed = false;
-        let hidden = 0;
-        let untested = 0;
-        for (const { frame, ref } of documents) {
-            let frameRef = ref;
-            if (frameRef !== null)
-                frameRef = { ...frameRef, name: await frameLabel(frame) };
-            try {
-                const read = await enumerateFrame(frame, frameRef);
-                elements.push(...read.elements);
-                ambiguousInDocument += read.ambiguousInDocument;
-                hidden += read.hidden;
-                untested += read.untested;
-                reach.push({ frame: frameRef, enumerated: true, elements: read.elements.length, reason: null });
-            }
-            catch (error) {
-                reach.push({
-                    frame: frameRef,
-                    enumerated: false,
-                    elements: 0,
-                    reason: `this frame could not be read: ${error instanceof Error ? error.message : String(error)}`,
-                });
-                continue;
-            }
-            const closed = await probeClosedHosts(frame);
-            if (closed !== null) {
-                probed = true;
-                suspectedClosedHosts += closed;
-            }
-        }
-        if (frameListUnavailable) {
-            reach.push({
-                frame: { id: "frames-unavailable", url: "", name: null },
-                enumerated: false,
-                elements: 0,
-                reason: "this browser backend exposes no frame list, so any iframe on this page was not read. " +
-                    "Nothing here claims the page has none.",
-            });
-        }
-        return {
-            elements,
-            frames: reach,
-            shadow: {
-                piercedElements: elements.filter((e) => e.inShadowRoot).length,
-                ambiguousInDocument,
-                suspectedClosedHosts,
-                probed,
-            },
-            hidden: { withheld: hidden, untested },
-        };
-    }
-    /** Scrolls the document **and every scrollable container in it** a viewport at a time until
-     *  nothing can move further, or the pass cap stops it. Containers are the half a window-only
-     *  scroll never reached: a list inside `overflow: auto` does not move when the page does. */
-    async function scrollToReveal() {
-        const page = session.page;
-        if (typeof page.evaluate !== "function") {
-            return {
-                passes: 0,
-                stoppedAtCap: false,
-                finalScrollY: 0,
-                containersScrolled: 0,
-                reason: "this browser backend exposes no page evaluation, so nothing below the fold could be revealed",
-            };
-        }
-        const evaluate = page.evaluate.bind(page);
-        let passes = 0;
-        let containers = 0;
-        let lastY = 0;
-        let scanCapped = false;
-        for (;;) {
-            const step = await evaluate(revealStep).catch(() => null);
-            if (step === null) {
-                return {
-                    passes,
-                    stoppedAtCap: false,
-                    finalScrollY: lastY,
-                    containersScrolled: containers,
-                    reason: "the page stopped answering mid-reveal",
-                };
-            }
-            lastY = step.y;
-            containers = Math.max(containers, step.containers);
-            scanCapped = scanCapped || step.scanCapped;
-            // Nothing left to move: the page and every container it holds are at their end, or
-            // none of them can scroll at all. Either way there is nothing further to reveal.
-            if (!step.scrolled) {
-                return {
-                    passes,
-                    stoppedAtCap: false,
-                    finalScrollY: step.y,
-                    containersScrolled: containers,
-                    reason: scanCapped ? CONTAINER_SCAN_NOTE : null,
-                };
-            }
-            passes += 1;
-            if (passes >= REVEAL_MAX_PASSES) {
-                return {
-                    passes,
-                    stoppedAtCap: true,
-                    finalScrollY: step.y,
-                    containersScrolled: containers,
-                    reason: scanCapped ? CONTAINER_SCAN_NOTE : null,
-                };
-            }
-            await new Promise((done) => setTimeout(done, REVEAL_SETTLE_MS));
-        }
-    }
-    /**
-   * Refuses a control the page has put out of reach.
-   *
-   * `click` never calls this: Playwright's own actionability checks already
-   * cover it, and duplicating them here would mean two rules that can
-   * disagree. `select` and `submit` do, because neither of their underlying
-   * operations hit-tests — see `NotOperableError`.
-   *
-   * A browser that cannot answer is treated as operable rather than refused.
-   * Refusing on an unanswered question would turn a missing capability into a
-   * false negative on every element, which is the same trade rule 2 rejects
-   * pointed the other way.
-   */
-    async function assertOperable(ref, handle) {
-        const state = await handle
-            .evaluate((el) => ({
-            // `inert` applies to a whole subtree and `HTMLElement.inert` reflects only the
-            // attribute on the node it is read from, so this has to walk ancestors.
-            inert: el.closest === undefined ? null : el.closest("[inert]") !== null,
-            disabled: el.disabled === true,
-        }))
-            .catch(() => null);
-        if (state === null)
-            return;
-        if (state.inert === true)
-            throw new NotOperableError(ref, "inert");
-        if (state.disabled)
-            throw new NotOperableError(ref, "disabled");
-    }
-    // Named rather than returned inline: `waitFor` re-enumerates the page each poll and does it
-    // by calling this same `snapshot()`, so the refs it hands back come from the one enumeration
-    // path instead of a second copy that could drift from it.
-    const api = {
-        sessionId: session.sessionId,
-        startedAt: session.startedAt,
-        isUsable: () => !closed && session.isUsable(),
-        currentUrl: () => session.page.url(),
-        async navigate(url) {
-            assertUsable();
-            await dropRefs();
-            await actionCollector.navigate(url);
-            recordAction("navigate", null, null);
-            recordPerformed("navigate", null, url, null);
-        },
-        async snapshot(options) {
-            assertUsable();
-            await dropRefs();
-            generation += 1;
-            let read = await enumerateAll();
-            let reveal = null;
-            if (options?.reveal === true) {
-                const before = countKeys(read.elements);
-                const scrolled = await scrollToReveal();
-                if (scrolled.passes > 0) {
-                    // Handles taken before the scroll may point at rows the list has since destroyed;
-                    // the page is re-read rather than merged, so every ref handed back is one that
-                    // exists now. What the scroll cost is reported, not hidden.
-                    await Promise.all(read.elements.map((e) => e.handle.dispose().catch(() => { })));
-                    read = await enumerateAll();
-                }
-                const after = countKeys(read.elements);
-                reveal = {
-                    passes: scrolled.passes,
-                    containersScrolled: scrolled.containersScrolled,
-                    revealedElements: surplus(after, before),
-                    recycledElements: surplus(before, after),
-                    stoppedAtCap: scrolled.stoppedAtCap,
-                    finalScrollY: scrolled.finalScrollY,
-                    framesNotScrolled: read.frames
-                        .filter((f) => f.frame !== null)
-                        .map((f) => f.frame?.name ?? f.frame?.url ?? f.frame?.id ?? ""),
-                    reason: scrolled.reason,
-                };
-            }
-            const elements = [];
-            for (const [index, found] of read.elements.entries()) {
-                const ref = `ref-${generation}-${index}`;
-                const element = {
-                    ref,
-                    role: found.role,
-                    name: found.name,
-                    selector: found.selector,
-                    frame: found.frame,
-                    inShadowRoot: found.inShadowRoot,
-                    // Grounding resolves a *document* selector, so a framed or hookless element
-                    // (selector === null) is never attempted — `identity` stays null rather than
-                    // guessed at, same reasoning `driver.ts` documents on the field itself.
-                    identity: grounder === null || found.selector === null
-                        ? null
-                        : await groundOne(grounder, session.page, found.selector),
-                };
-                refs.set(ref, { element, handle: found.handle });
-                elements.push(element);
-            }
-            return {
-                url: session.page.url(),
-                title: await session.page.title().catch(() => ""),
-                elements,
-                totalElements: elements.length,
-                frames: read.frames,
-                shadow: read.shadow,
-                hidden: read.hidden,
-                reveal,
-            };
-        },
-        async click(ref) {
-            assertUsable();
-            const { element, handle } = resolve(ref);
-            await handle.click();
-            recordAction("click", ref, null);
-            recordPerformed("click", { role: element.role, name: element.name, selector: element.selector }, null, null);
-            // requestfinished fires after the page's handler resolves; draining immediately would miss the very request being watched for.
-            await settleAfterAction("click", ref);
-        },
-        async type(ref, text) {
-            assertUsable();
-            const { element, handle } = resolve(ref);
-            if (handle.pressSequentially !== undefined)
-                await handle.pressSequentially(text);
-            else if (handle.type !== undefined)
-                await handle.type(text);
-            else
-                throw new Error("this Playwright build exposes no keystroke-level typing method");
-            recordAction("type", ref, "append");
-            recordPerformed("type", { role: element.role, name: element.name, selector: element.selector }, null, text);
-            await settleAfterAction("type", ref);
-        },
-        async fill(ref, text) {
-            assertUsable();
-            const { element, handle } = resolve(ref);
-            await handle.fill(text);
-            recordAction("fill", ref, "replace");
-            recordPerformed("fill", { role: element.role, name: element.name, selector: element.selector }, null, text);
-            await settleAfterAction("fill", ref);
-        },
-        async select(ref, value) {
-            assertUsable();
-            const { element, handle } = resolve(ref);
-            await assertOperable(ref, handle);
-            // Read what the element actually offers before touching it. Playwright's own
-            // selectOption would time out on a non-match and say nothing useful about why; the
-            // refusal a caller can act on has to carry the real option list, and that means one
-            // round trip to read it.
-            const offered = await handle.evaluate((el) => {
-                if (el.options === undefined)
-                    return null;
-                const out = [];
-                for (let i = 0; i < el.options.length; i += 1) {
-                    const option = el.options[i];
-                    out.push({ value: option.value, label: option.label === "" ? option.text : option.label });
-                }
-                return out;
-            });
-            if (offered === null)
-                throw new NotSelectableError(ref, element.role);
-            // By stored value first, then by the label a person reads — both exact. A caller
-            // reading a snapshot sees labels and a caller reading the page's source sees values;
-            // neither should have to know which one this element uses.
-            const matched = offered.find((o) => o.value === value) ?? offered.find((o) => o.label.trim() === value.trim());
-            if (matched === undefined) {
-                throw new NoSuchOptionError(ref, value, offered.map((o) => (o.label.trim() === "" ? o.value : o.label)));
-            }
-            if (handle.selectOption === undefined)
-                throw new Error("this Playwright build exposes no option-selecting method");
-            await handle.selectOption(matched.value);
-            recordAction("select", ref, "replace");
-            recordPerformed("select", { role: element.role, name: element.name, selector: element.selector }, null, matched.value);
-            await settleAfterAction("select", ref);
-        },
-        async submit(ref) {
-            assertUsable();
-            const { element, handle } = resolve(ref);
-            await assertOperable(ref, handle);
-            // Submitted through the form's own submit control rather than by synthesising a bare
-            // submit event: that is what a person's click does, it names the submitter the page's
-            // handler reads, and it runs the form's validation. A form with no such control is
-            // submitted by script on some other control — refused, not guessed at.
-            const outcome = await handle.evaluate((el) => {
-                const form = el.closest === undefined ? null : el.closest("form");
-                if (form === null)
-                    return "noForm";
-                const control = form.querySelector('button[type="submit"], input[type="submit"], button:not([type])');
-                if (control === null)
-                    return "noSubmitControl";
-                form.requestSubmit(control);
-                return "submitted";
-            });
-            if (outcome !== "submitted")
-                throw new NotSubmittableError(ref, outcome);
-            recordAction("submit", ref, null);
-            recordPerformed("submit", { role: element.role, name: element.name, selector: element.selector }, null, null);
-            await settleAfterAction("submit", ref);
-        },
-        async waitFor(target, waitOptions = {}) {
-            assertUsable();
-            if (isEmptyWaitTarget(target)) {
-                throw new Error("browser_wait_for needs a target: give a role, a name, or both. Waiting for nothing in particular " +
-                    `would return the first element on the page, which is not what any caller means. Got: ${describeWaitTarget(target)}.`);
-            }
-            const timeoutMs = clampWaitTimeout(waitOptions.timeoutMs);
-            const startedAt = Date.now();
-            for (;;) {
-                assertUsable();
-                // Re-enumerates each poll rather than watching one selector: the port has no
-                // selector to watch, and a fresh snapshot is what makes the matched element
-                // actionable at all. That cost is real, and is why the interval is not tighter.
-                const snapshot = await api.snapshot();
-                const matches = snapshot.elements.filter((e) => matchesWaitTarget(e, target));
-                const waitedMs = Date.now() - startedAt;
-                if (matches.length > 0) {
-                    return { appeared: true, waitedMs, timeoutMs, matched: matches[0], matchCount: matches.length, snapshot };
-                }
-                if (waitedMs >= timeoutMs) {
-                    return { appeared: false, waitedMs, timeoutMs, matched: null, matchCount: 0, snapshot };
-                }
-                await new Promise((done) => setTimeout(done, WAIT_POLL_INTERVAL_MS));
-            }
-        },
-        async injectStorageState(origin, state) {
-            assertUsable();
-            if (typeof session.injectStorageState !== "function") {
-                // Honest degradation (rule 7), same shape the groundIdentity install
-                // failure above uses: an older runtime-browser build predates this
-                // primitive, so nothing was injected and the reason travels on the
-                // result rather than a silent no-op or a thrown TypeError.
-                return {
-                    cookiesInjected: 0,
-                    localStorageInjected: 0,
-                    localStorageSkipped: "this build of @descryy/runtime-browser does not export injectStorageState -- nothing was injected. " +
-                        "Republish runtime-browser at a version that includes BrowserSession.injectStorageState.",
-                };
-            }
-            return session.injectStorageState({
-                origin,
-                ...(state.cookies === undefined ? {} : { cookies: state.cookies }),
-                ...(state.localStorage === undefined ? {} : { localStorage: state.localStorage }),
-            });
-        },
-        async drainEvidence() {
-            const observation = collect(emitted, actions, unsettled);
-            emitted.length = 0;
-            actions.length = 0;
-            unsettled.length = 0;
-            return withIdentityWarnings(observation, identityWarnings);
-        },
-        performedSteps() {
-            return [...performed];
-        },
-        storageStateSaveFailure: () => storageStateSaveError,
-        /**
-         * §4.2's probe. Reads the page and counts; decides nothing — `estimateReach`
-         * is the only thing that turns these counts into a claim, so a change of
-         * policy never touches a driver.
-         *
-         * The body lives in `page-probe.ts` rather than here: this file belongs to
-         * another lane, and a six-line delegation is mergeable where two hundred
-         * lines of DOM walking would not be.
-         */
-        async fingerprint() {
-            assertUsable();
-            const [root] = await session.page.$$("html");
-            if (root === undefined) {
-                // No document element at all. Refusing is right: a fingerprint of
-                // zeroes would read as a page with nothing on it.
-                throw new Error("the page exposed no document element to probe");
-            }
-            try {
-                return await root.evaluate(probeInPage, PROBE_CONSTANTS);
-            }
-            finally {
-                await root.dispose();
-            }
-        },
-        async close() {
-            if (finalObservation !== null)
-                return finalObservation;
-            closed = true;
-            // Stopped before observing: a stop flushes what each collector was
-            // still holding, which observing first would drop.
-            await actionCollector.stop().catch(() => { });
-            await consoleCollector.stop().catch(() => { });
-            await networkCollector.stop().catch(() => { });
-            const observation = withIdentityWarnings(collect(emitted, actions, unsettled), identityWarnings);
-            emitted.length = 0;
-            actions.length = 0;
-            unsettled.length = 0;
-            await dropRefs();
-            // Before `session.close()`, not after: a closed context holds no
-            // cookies to read, and a save that ran afterwards would write a file
-            // that looks like a session with nothing in it — which is worse than no
-            // file, because the next run would seed from it and silently drive the
-            // logged-out surface. A failure here is reported as a note by the
-            // caller rather than swallowed, but it never fails the close: evidence
-            // already collected must not be lost to a write that did not work.
-            if (launchOptions.saveStorageStateTo !== undefined && session.saveStorageState !== undefined) {
-                try {
-                    await session.saveStorageState(launchOptions.saveStorageStateTo);
-                }
-                catch (error) {
-                    storageStateSaveError = error instanceof Error ? error.message : String(error);
-                }
-            }
-            await session.close().catch(() => { });
-            finalObservation = observation;
-            return observation;
-        },
-    };
-    return api;
-}
-/** Turns collector evidence into the port's vocabulary. Joins request/response on `requestId`, keeping `status: null` (not guessed) when unanswered. Exported for `browser-request-outcome-mapping.test.ts`. */
-export function collect(emitted, actions, unsettled) {
-    // `requestId` is a correlation header the app must itself propagate, not a
-    // transport id — an id-only join silently reported `status: null` for
-    // every request without one, i.e. most of them, hence the URL fallback
-    // below. `status` and `outcome` are read from the *same* terminal event and
-    // stored together: two independent last-write-wins maps let a later
-    // terminal event for a *different* request overwrite one field but not the
-    // other (e.g. an id-less "unanswered" HTTP_ERROR with no numeric status
-    // updates only `outcome`), so a third, genuinely-still-pending id-less
-    // request sharing that URL could read back `status: 200` from one sibling
-    // and `outcome: "unanswered"` from another — a self-contradictory pair
-    // that is a real, reported defect (P6-D5), not a hypothetical one.
-    //
-    // **B4: that pairing was necessary and was not sufficient.** Three routes to
-    // a false fact survived it, each verified here rather than reasoned about,
-    // and each fixed at the line it occurs on below: the pair itself was never
-    // checked for self-consistency across a boundary that versions separately;
-    // "paired" was a set-membership test on the URL rather than a record of what
-    // this request consumed, so an in-flight sibling read as failed; and the
-    // HTTP_ERROR `descry-runtime` emits *alongside* a >= 400 NETWORK_RESPONSE
-    // took a second queue slot, handing one exchange's 500 to two requests.
-    const byRequestId = new Map();
-    // C3. A **transport-level** identity, when the collector carries one: an id
-    // the browser's own request object owns, not a header an application chose
-    // to propagate. It outranks `requestId` because it cannot be absent for
-    // application reasons, and where it is present the whole out-of-order
-    // question below simply does not arise. `descry-runtime`'s network
-    // collector already holds this identity — its pending map is keyed by the
-    // Playwright `Request` object itself, "not a URL or an id, which could
-    // collide across concurrent requests to the same endpoint" — and does not
-    // yet emit it. Read here the same way `outcome` was read before its
-    // producer shipped: validated, optional, and absent degrades to the join
-    // below rather than to a guess. See
-    // `DEC-NEXT-transport-level-exchange-id-for-browser-requests`.
-    const byExchangeId = new Map();
-    // FIFO per URL, fed only by unidentified terminal events. A URL is not
-    // unique the way an id is — a page can issue the same URL more than once —
-    // so a shared cache must hand each terminal event's (status, outcome) pair
-    // to at most one request, in arrival order, rather than broadcasting the
-    // most recent one to every request sharing that URL. An id-bearing terminal
-    // event is deliberately excluded from this pool: it is already claimed
-    // evidence for one specific request, and folding it into the shared pool
-    // would just relocate the same contamination.
-    //
-    // **C3: arrival order is not an answer, so it is no longer used as one.**
-    // Two unidentified requests to one URL whose responses arrive out of order
-    // swap records, and nothing at this layer can tell an in-order pair from a
-    // swapped one. A FIFO is therefore right about half the time and silent
-    // when it is wrong — the exact shape rule 2 forbids, because the failure
-    // leaves no trace in the reply. Where the assignment is genuinely
-    // undetermined the queue is not consulted at all and every request in that
-    // bucket is reported `unattributed` with the terminal events disclosed by
-    // URL instead. Where it is determined — one unidentified request, or
-    // several whose records are indistinguishable from one another, so that
-    // every possible assignment yields the same answer — it still pairs, since
-    // refusing there would trade a silent wrong answer for a loud missing one
-    // that nothing required.
-    const queueByUrl = new Map();
-    const warnings = new Set();
-    // URLs that produced an id-less NETWORK_RESPONSE, so the duplicate-HTTP_ERROR
-    // exclusion below can require its sibling rather than assume it. A build that
-    // ever emitted a numeric-status HTTP_ERROR *alone* would otherwise have it
-    // silently dropped, turning a real 4xx into "pending".
-    const respondedUrls = new Set();
-    for (const evidence of emitted) {
-        if (evidence.eventType !== "NETWORK_RESPONSE" || evidence.requestId !== null)
-            continue;
-        if (exchangeIdOf(evidence.payload) !== null)
-            continue;
-        const url = evidence.payload["url"];
-        if (typeof url === "string")
-            respondedUrls.add(url);
-    }
-    for (const evidence of emitted) {
-        if (evidence.eventType !== "NETWORK_RESPONSE" && evidence.eventType !== "HTTP_ERROR")
-            continue;
-        const url = evidence.payload["url"];
-        const rawStatus = evidence.payload["status"];
-        const status = typeof rawStatus === "number" ? rawStatus : null;
-        // B4. The pair is validated, not just each field: this payload crosses a
-        // package boundary that versions separately, which is the same reason
-        // `requestOutcomeOf` validates instead of casting. A numeric status means
-        // a response arrived; "unanswered" means none ever did. Both cannot be
-        // true of one request, and forwarding the pair verbatim is what produced
-        // the `status: 200` + `outcome: "unanswered"` record the cal.com pass
-        // reported. Neither field can be trusted to correct the other, so the
-        // directly-observed status is kept and the outcome degrades to the same
-        // "not reported" state an older collector build produces — and it is
-        // named in the reply rather than dropped quietly (rule 7).
-        const outcome = reconcile(status, requestOutcomeOf(evidence.payload), url, warnings);
-        const record = { status, outcome };
-        const exchangeId = exchangeIdOf(evidence.payload);
-        if (exchangeId !== null) {
-            byExchangeId.set(exchangeId, record);
-            continue;
-        }
-        if (evidence.requestId !== null) {
-            byRequestId.set(evidence.requestId, record);
-            continue;
-        }
-        if (typeof url !== "string")
-            continue;
-        // B4. One exchange, one slot. `descry-runtime`'s collector emits
-        // NETWORK_RESPONSE *and* a payload-sharing HTTP_ERROR for a single
-        // response with status >= 400, and a numeric status is the only shape in
-        // which it ever emits HTTP_ERROR — every other HTTP_ERROR it produces
-        // (requestfailed, its own timeout, a websocket socketerror, a session
-        // closing mid-flight) carries `status: null` and has no NETWORK_RESPONSE
-        // beside it. Keyed by requestId that duplicate is harmless (same content,
-        // one map entry); in this queue it took a second slot, so one 500
-        // exchange handed a 500 to a second request that never got a response at
-        // all. Excluded here only — an id-keyed one still records, in case a
-        // build ever emits it without its sibling.
-        if (evidence.eventType === "HTTP_ERROR" && status !== null && respondedUrls.has(url))
-            continue;
-        const queue = queueByUrl.get(url);
-        if (queue === undefined)
-            queueByUrl.set(url, [record]);
-        else
-            queue.push(record);
-    }
-    /** The record this evidence owns outright, or undefined when it must draw from the shared
-     *  URL queue. Exchange id first: it identifies the transport exchange, where `requestId`
-     *  identifies whatever the application decided to label. */
-    const keyedRecordFor = (evidence) => {
-        const exchangeId = exchangeIdOf(evidence.payload);
-        if (exchangeId !== null) {
-            const byExchange = byExchangeId.get(exchangeId);
-            if (byExchange !== undefined)
-                return byExchange;
-        }
-        return evidence.requestId === null ? undefined : byRequestId.get(evidence.requestId);
-    };
-    // C3. How many requests to each URL have no record of their own — exactly the set that
-    // draws from the shared queue, and therefore exactly the set the queue can be wrong about.
-    // Counted after the maps are built, not from the presence of an id: a request carrying an
-    // id that never came back on a terminal event falls through to the queue like any other,
-    // and counting it as identified would leave the queue one short of the requests using it.
-    const unkeyedByUrl = new Map();
-    for (const evidence of emitted) {
-        if (evidence.eventType !== "NETWORK_REQUEST")
-            continue;
-        const url = evidence.payload["url"];
-        if (typeof url !== "string")
-            continue;
-        if (keyedRecordFor(evidence) !== undefined)
-            continue;
-        unkeyedByUrl.set(url, (unkeyedByUrl.get(url) ?? 0) + 1);
-    }
-    // C3. The URLs whose assignment is undetermined. Not "has duplicates" — having two requests
-    // to one URL is ordinary and usually harmless. It is undetermined only when two different
-    // assignments would produce two different replies.
-    const undeterminedUrls = new Set();
-    for (const [url, records] of queueByUrl) {
-        const unkeyed = unkeyedByUrl.get(url) ?? 0;
-        if (unkeyed <= 1)
-            continue;
-        const first = records[0];
-        if (first === undefined)
-            continue;
-        const alike = records.every((record) => record.status === first.status && record.outcome === first.outcome);
-        // Enough alike records to go round means every request gets the same one, so which is
-        // which never comes up. One short means at least one request is still in flight and
-        // nothing can say which — and "pending" on the wrong one is a false fact about a healthy
-        // request, which is the defect B4 fixed in its first costume.
-        if (alike && records.length >= unkeyed)
-            continue;
-        undeterminedUrls.add(url);
-        warnings.add(undeterminedJoinWarning(url, unkeyed, records));
-    }
-    const requests = [];
-    const consoleErrors = [];
-    for (const evidence of emitted) {
-        if (evidence.eventType === "NETWORK_REQUEST") {
-            const method = evidence.payload["method"];
-            const url = evidence.payload["url"];
-            if (typeof method !== "string" || typeof url !== "string")
-                continue;
-            // The keyed match wins when it exists; only a request with no record of its own draws
-            // from the shared URL queue, and it draws once. C3: on an undetermined URL the queue is
-            // not consulted at all — consuming from it is what produced the swap.
-            const keyed = keyedRecordFor(evidence);
-            const undetermined = keyed === undefined && undeterminedUrls.has(url);
-            const matched = keyed ?? (undetermined ? undefined : queueByUrl.get(url)?.shift());
-            // B4. Paired is what this request *consumed*, not what its URL was seen
-            // in. It used to be a set-membership test on the URL, so a second,
-            // genuinely in-flight request to an already-answered URL came out with
-            // no outcome at all — which `isFailedRequest`'s older-build fallback
-            // reads as a failure, because its status is null. A healthy in-flight
-            // request reported as a failed one. No record consumed means no terminal
-            // event was ever attributable to this request, and "pending" is exactly
-            // that fact. An unrecognised outcome on a record that *was* consumed
-            // still leaves the field undefined, which is the older-build case the
-            // fallback exists for.
-            // C3. `unattributed` before `pending`: a terminal event for this URL exists, so claiming
-            // the request is still in flight would be as wrong as handing it a sibling's status —
-            // and wrong in the direction that reads as healthy.
-            const outcome = undetermined
-                ? "unattributed"
-                : matched === undefined
-                    ? "pending"
-                    : matched.outcome;
-            requests.push({
-                method,
-                url,
-                status: undetermined ? null : (matched?.status ?? null),
-                ...(outcome === undefined ? {} : { outcome }),
-                stackText: renderStack(evidence.stackTrace),
-                stackTrace: evidence.stackTrace,
-                scriptUrlMapping: scriptUrlOutcomesOf(evidence.payload),
-                at: evidence.timestamp,
-            });
-            continue;
-        }
-        // Uncaught page error and console error both mean "something went wrong"; callers don't need to know which listener fired.
-        if (evidence.eventType === "EXCEPTION" || evidence.eventType === "CONSOLE_MESSAGE") {
-            const level = evidence.payload["level"] ?? evidence.payload["type"];
-            if (evidence.eventType === "CONSOLE_MESSAGE" && level !== "error")
-                continue;
-            const text = evidence.payload["text"] ?? evidence.payload["message"];
-            consoleErrors.push({
-                text: typeof text === "string" ? text : JSON.stringify(evidence.payload),
-                stackText: renderStack(evidence.stackTrace),
-                scriptUrlMapping: scriptUrlOutcomesOf(evidence.payload),
-                at: evidence.timestamp,
-            });
-        }
-    }
-    return { actions: [...actions], consoleErrors, requests, unsettled: [...unsettled], evidenceWarnings: [...warnings] };
-}
-/** B4's pair check. Returns the outcome that may be published alongside `status`, dropping it —
- *  and naming the drop in `warnings` — when the two cannot both be true. Deliberately one-sided:
- *  a status is a number the collector read off a real response object, an outcome is a label it
- *  derived, so when they disagree the derived half is the one that goes. `url` only names the
- *  request in the warning; a missing one degrades the text, never the check. */
-function reconcile(status, outcome, url, warnings) {
-    const impossible = (outcome === "unanswered" && status !== null) || (outcome === "answered" && status === null);
-    if (!impossible)
-        return outcome;
-    const where = typeof url === "string" ? ` for ${url}` : "";
-    warnings.add(`Descry's browser collector reported a request${where} as both "${outcome}" and ` +
-        `status ${status === null ? "null" : String(status)}, which cannot both be true. The status is ` +
-        "what was read off the response, so it is kept and the outcome is dropped — this request is " +
-        "reported without one rather than with a contradiction. Usually a version mismatch between " +
-        "@descryy/mcp and @descryy/runtime-browser.");
-    return undefined;
-}
-/** Reads `outcome` off an untyped cross-package payload; validated not cast, since this build doesn't depend on `@descryy/runtime-browser`'s types — unrecognised values degrade to undefined, never a guessed literal. `"unattributed"` is deliberately not accepted here: it is this package's verdict about a join it could not make, and a collector is in no position to assert it. */
-function requestOutcomeOf(payload) {
-    const raw = payload["outcome"];
-    if (raw === "answered" || raw === "unanswered" || raw === "pending")
-        return raw;
-    return undefined;
-}
-/** Reads the collector's transport-level exchange id, when it carries one. Validated not cast,
- *  and an empty string is treated as absent — an id that identifies nothing would put every
- *  request into one bucket, which is worse than having none. */
-function exchangeIdOf(payload) {
-    const raw = payload["exchangeId"];
-    return typeof raw === "string" && raw !== "" ? raw : null;
-}
-/** C3's disclosure. Says what was observed and refuses to say whose it was — the terminal
- *  events are named in full so a real 500 is never lost, only left unassigned. */
-function undeterminedJoinWarning(url, unkeyed, records) {
-    const describe = (record) => `${record.status === null ? "no status" : `status ${record.status}`}${record.outcome === undefined ? "" : ` (${record.outcome})`}`;
-    const shortfall = records.length < unkeyed
-        ? ` Fewer terminal events arrived than requests were issued, so at least one of them was still in flight, and which one is the same unanswerable question.`
-        : "";
-    return (`Descry saw ${unkeyed} requests to ${url} carrying no id of their own, and ${records.length} terminal ` +
-        `event(s) for that URL that do not all say the same thing: ${records.map(describe).join("; ")}.${shortfall} ` +
-        "Pairing them by arrival order would be right roughly half the time and silent when it was wrong, so none " +
-        "of these requests is reported with a status or an outcome. The events just listed did happen — Descry " +
-        "cannot say which request each one belongs to. A transport-level exchange id from the browser collector " +
-        "would remove this; the collector in this build does not emit one.");
-}
-/** Reads `scriptUrlMapping` off an untyped cross-package payload; validated not cast, so a malformed/absent field degrades to "no mapping reported" rather than a half-populated result. */
-function scriptUrlOutcomesOf(payload) {
-    const raw = payload["scriptUrlMapping"];
-    if (!Array.isArray(raw))
-        return [];
-    const outcomes = [];
-    for (const entry of raw) {
-        if (typeof entry !== "object" || entry === null)
-            continue;
-        const record = entry;
-        const url = record["url"];
-        if (typeof url !== "string")
-            continue;
-        const mapped = record["mapped"];
-        const reason = record["reason"];
-        outcomes.push({
-            url,
-            mapped: typeof mapped === "string" ? mapped : null,
-            reason: typeof reason === "string" ? reason : null,
-        });
-    }
-    return outcomes;
-}
-/** Human-readable rendering of parsed stack frames, for the reply; the R4 write uses `stackTrace` itself, never this. Primary frame marked since it isn't always the innermost. */
-function renderStack(stack) {
-    if (stack === null || stack.frames.length === 0)
-        return null;
-    return stack.frames
-        .slice(0, 5)
-        .map((frame, index) => {
-        const where = `${frame.location.file}:${frame.location.line}`;
-        const name = frame.location.functionName ?? "(anonymous)";
-        return `${index === stack.primaryFrameIndex ? "> " : "  "}at ${name} (${where})`;
-    })
-        .join("\n");
-}
-/**
- * The runtime's auth seed for this launch, or null when the caller named none.
- *
- * The origin comes from `targetUrl` and from nowhere else — it is the same
- * value the registry records as the session's consented origin, so "the seed
- * is scoped to what was consented" is a property of one derivation rather
- * than of two that have to agree.
- */
-function runtimeAuthFor(launchOptions) {
-    const state = launchOptions.storageState;
-    const headers = launchOptions.extraHttpHeaders;
-    if (state === undefined && headers === undefined)
-        return null;
-    let origin;
-    try {
-        origin = new URL(launchOptions.targetUrl).origin;
-    }
-    catch {
-        // Unparseable targets are refused far above this — the tool cannot mint
-        // consent for a URL it could not read an origin from. Carrying the raw
-        // string keeps this total rather than throwing from inside a launch.
-        origin = launchOptions.targetUrl;
-    }
-    return {
-        origin,
-        ...(state?.cookies === undefined ? {} : { cookies: state.cookies }),
-        ...(state?.localStorage === undefined ? {} : { localStorage: state.localStorage }),
-        ...(headers === undefined ? {} : { extraHttpHeaders: headers }),
-    };
-}
-//# sourceMappingURL=playwright-driver.js.map