@descryy/mcp 0.9.1 → 0.11.0

package/dist/browser/playwright-driver.js

@@ -11,10 +11,16 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
-import { BrowserSessionCrashedError, UnknownElementRefError } from "./driver.js";
+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. */
@@ -25,6 +31,419 @@ const SETTLE_TIMEOUT_MS = 5_000;
 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)}. ` +
@@ -42,7 +461,18 @@ export async function createPlaywrightBrowserDriver(options = {}) {
     }
     return {
         async launch(launchOptions) {
-            const launch = await runtime.launchBrowserSessionOrRefuse({ headless: launchOptions.headless ?? true });
+            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 };
@@ -77,6 +507,13 @@ async function openSession(runtime, session, launchOptions, options) {
     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: {} },
@@ -105,6 +542,26 @@ async function openSession(runtime, session, launchOptions, options) {
     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())
@@ -151,7 +608,256 @@ async function openSession(runtime, session, launchOptions, options) {
         refs = new Map();
         await Promise.all(handles.map((h) => h.dispose().catch(() => { })));
     }
-    return {
+    /** 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(),
@@ -163,154 +869,66 @@ async function openSession(runtime, session, launchOptions, options) {
             recordAction("navigate", null, null);
             recordPerformed("navigate", null, url, null);
         },
-        async snapshot() {
+        async snapshot(options) {
             assertUsable();
             await dropRefs();
             generation += 1;
-            const handles = await session.page.$$(INTERACTIVE);
-            const elements = [];
-            for (const [index, handle] of handles.entries()) {
-                const described = await handle
-                    .evaluate((el) => {
-                    const tag = el.tagName.toLowerCase();
-                    const explicit = el.getAttribute("role");
-                    const type = el.getAttribute("type");
-                    const role = explicit ??
-                        (tag === "a"
-                            ? "link"
-                            : tag === "button" || (tag === "input" && (type === "button" || type === "submit"))
-                                ? "button"
-                                : tag === "select"
-                                    ? "combobox"
-                                    : tag === "textarea" || (tag === "input" && (type === null || type === "text" || type === "search"))
-                                        ? "textbox"
-                                        : tag === "input" && type === "checkbox"
-                                            ? "checkbox"
-                                            : tag);
-                    // A pragmatic accessible-name approximation, not a full AccName implementation.
-                    const name = el.getAttribute("aria-label") ??
-                        el.innerText?.trim() ??
-                        el.textContent?.trim() ??
-                        el.getAttribute("placeholder") ??
-                        el.getAttribute("name") ??
-                        "";
-                    // Computed in this same round trip so role/name/selector read off
-                    // one live DOM state; runs inside the page (serialized by
-                    // Playwright), so it must not close over the outer module.
-                    // 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 el.ownerDocument.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 tag = node.tagName.toLowerCase();
-                        const siblings = parent.querySelectorAll(`:scope > ${tag}`);
-                        if (siblings.length <= 1)
-                            return tag;
-                        for (let i = 0; i < siblings.length; i += 1) {
-                            if (siblings.item(i) === node)
-                                return `${tag}:nth-of-type(${i + 1})`;
-                        }
-                        return tag;
-                    }
-                    /** A bounded path from the nearest ancestor carrying a stable hook, capped at 6 segments. Null when none is found in range. */
-                    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 name = target.getAttribute("name");
-                        if (name !== null && name.trim() !== "" && FORM_CONTROLS.includes(controlTag)) {
-                            const candidate = `${controlTag}[name="${escapeAttrValue(name)}"]`;
-                            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) };
-                })
-                    .catch(() => null);
-                if (described === null) {
-                    await handle.dispose().catch(() => { });
-                    continue;
+            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: described.role,
-                    name: described.name,
-                    selector: described.selector,
+                    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 });
+                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 };
+            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();
@@ -342,16 +960,144 @@ async function openSession(runtime, session, launchOptions, options) {
             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 observation;
+            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;
@@ -361,16 +1107,32 @@ async function openSession(runtime, session, launchOptions, options) {
             await actionCollector.stop().catch(() => { });
             await consoleCollector.stop().catch(() => { });
             await networkCollector.stop().catch(() => { });
-            const observation = collect(emitted, actions, unsettled);
+            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) {
@@ -385,51 +1147,164 @@ export function collect(emitted, actions, unsettled) {
     // 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();
-    // FIFO per URL, fed only by id-less terminal events. A URL is not unique
-    // the way a requestId is — a page can issue the same id-less 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 id-less pool would just relocate the same contamination.
+    // 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 pairedRequestIds = new Set();
-    // Populated only from id-less terminal events, to match `queueByUrl`'s own
-    // restriction: an id-bearing event answers `pairedRequestIds`, not this —
-    // otherwise an id-less request sharing a URL with an id-claimed response
-    // would read `wasPaired: true` from an event it was never eligible to
-    // consume, and report "undefined" (read by `isFailedRequest` as a failure)
-    // instead of the "pending" it actually is.
-    const pairedUrls = new Set();
+    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"];
-        if (evidence.requestId !== null)
-            pairedRequestIds.add(evidence.requestId);
-        else if (typeof url === "string")
-            pairedUrls.add(url);
         const rawStatus = evidence.payload["status"];
-        const record = {
-            status: typeof rawStatus === "number" ? rawStatus : null,
-            outcome: requestOutcomeOf(evidence.payload),
-        };
-        if (record.status === null && record.outcome === undefined)
+        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) {
@@ -438,19 +1313,34 @@ export function collect(emitted, actions, unsettled) {
             const url = evidence.payload["url"];
             if (typeof method !== "string" || typeof url !== "string")
                 continue;
-            const requestId = evidence.requestId;
-            const wasPaired = (requestId !== null && pairedRequestIds.has(requestId)) || pairedUrls.has(url);
-            // The id match wins when it exists; only a request with no id record of
-            // its own draws from the shared URL queue, and it draws once.
-            const matched = (requestId === null ? undefined : byRequestId.get(requestId)) ?? queueByUrl.get(url)?.shift();
-            // Paired outcome wins; no terminal event means still in-flight
-            // ("pending"); an unrecognised outcome (older runtime build) leaves the
-            // field undefined — `isFailedRequest`'s fallback handles that, not this.
-            const outcome = matched?.outcome ?? (wasPaired ? undefined : "pending");
+            // 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: matched?.status ?? null,
+                status: undetermined ? null : (matched?.status ?? null),
                 ...(outcome === undefined ? {} : { outcome }),
                 stackText: renderStack(evidence.stackTrace),
                 stackTrace: evidence.stackTrace,
@@ -473,15 +1363,53 @@ export function collect(emitted, actions, unsettled) {
             });
         }
     }
-    return { actions: [...actions], consoleErrors, requests, unsettled: [...unsettled] };
+    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. */
+/** 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"];
@@ -518,4 +1446,34 @@ function renderStack(stack) {
     })
         .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