comber 0.1.0

package/dist/web/driver.js

@@ -0,0 +1,803 @@
+import { createHash } from "node:crypto";
+import { chromium, } from "playwright";
+import { attachBreakageListeners, attachInitScripts, auditDom, runAxe, sessionLivenessProbe } from "./breakage.js";
+import { classify, orderForExhaustion, synthFor, traversalIntentForKind } from "./elements.js";
+import { exerciseControl, isControl } from "./controls.js";
+import { FormTester } from "./forms.js";
+import { LinkChecker } from "./links.js";
+import { EgressGuard } from "../core/egress.js";
+import { restoreFingerprint } from "./fingerprint.js";
+/**
+ * Browser-side DOM extraction, as a STRING expression (tsx/esbuild keep-names injects
+ * a `__name` helper into serialized closures that doesn't exist in the browser). Widened
+ * selector set + classification fields + a structural domPath (stable across re-snapshots)
+ * + recursive OPEN-shadow-DOM piercing. Returns { els, blindSpots } where blindSpots counts
+ * likely-closed shadow roots this frame couldn't see into. Runs per-frame (snapshot() merges).
+ */
+const EXTRACT_INTERACTIVE = `(() => {
+  const SEL = [
+    "a[href]","area[href]","button","[role=button]","input","select","textarea","[onclick]",
+    "[role=tab]","[role=menuitem]","[role=menuitemcheckbox]","[role=menuitemradio]",
+    "[role=switch]","[role=checkbox]","[role=radio]","[role=option]","[role=link]",
+    "[role=combobox]","[role=slider]","[role=treeitem]","[role=gridcell]","summary",
+    "[aria-haspopup]","[aria-expanded]","[contenteditable='true']",
+    "[tabindex]:not([tabindex='-1'])"
+  ].join(",");
+  const isVisible = (el) => {
+    if (!el.getBoundingClientRect) return false;
+    const r = el.getBoundingClientRect();
+    const s = window.getComputedStyle(el);
+    return r.width > 0 && r.height > 0 && s.visibility !== "hidden" && s.display !== "none" && s.opacity !== "0";
+  };
+  const domPath = (el) => {
+    const segs = []; let node = el, hops = 0;
+    while (node && node.nodeType === 1 && hops < 6) {
+      const tag = node.tagName.toLowerCase();
+      let n = 1, sib = node;
+      while ((sib = sib.previousElementSibling)) { if (sib.tagName === node.tagName) n++; }
+      segs.unshift(tag + ":nth-of-type(" + n + ")");
+      node = node.parentElement; hops++;
+    }
+    return segs.join(">");
+  };
+  const out = []; let i = 0; let blindSpots = 0;
+  const ORIGIN = location.origin;
+  const linkClassOf = (el) => {
+    const raw = el.getAttribute("href"); if (raw == null) return undefined;
+    if (raw.startsWith("#")) return "hash";
+    if (/^(mailto:|tel:|javascript:)/i.test(raw)) return "nonhttp";
+    try { return new URL(el.href).origin === ORIGIN ? "internal" : "external"; } catch { return undefined; }
+  };
+  const process = (el) => {
+    if (!isVisible(el)) return;
+    const ref = "c" + (i++);
+    try { el.setAttribute("data-comber-ref", ref); } catch (e) {}
+    const tag = el.tagName.toLowerCase();
+    const aLabel = el.getAttribute("aria-label");
+    const txt = (el.innerText || el.textContent || "").trim().replace(/\\s+/g, " ");
+    const name = (aLabel || txt || el.getAttribute("placeholder") || el.value ||
+      el.getAttribute("title") || el.getAttribute("alt") || el.getAttribute("name") || "").slice(0, 120);
+    const aExpanded = el.getAttribute("aria-expanded");
+    const aPressed = el.getAttribute("aria-pressed");
+    // Action-effect inputs: for a submit-capable form control, capture the effective wire
+    // method + resolved action URL (the formaction/formmethod override wins over the form's).
+    const etype = el.type ? String(el.type).toLowerCase() : "";
+    const submitCapable = !!el.form && (etype === "submit" || etype === "image");
+    let formMethod, formAction;
+    if (submitCapable) {
+      formMethod = (el.getAttribute("formmethod") || el.form.getAttribute("method") || "get").toLowerCase();
+      const a = el.getAttribute("formaction") || el.form.getAttribute("action") || "";
+      try { formAction = a ? new URL(a, location.href).href : location.href; } catch (e) { formAction = location.href; }
+    }
+    const onclickAttr = (el.getAttribute("onclick") || "").slice(0, 200);
+    out.push({
+      ref, role: el.getAttribute("role") || tag, name: String(name), href: el.href || undefined,
+      tag, inputType: el.type ? String(el.type).toLowerCase() : undefined, domPath: domPath(el),
+      ariaExpanded: aExpanded == null ? undefined : aExpanded === "true",
+      ariaControls: el.getAttribute("aria-controls") || undefined,
+      ariaPressed: aPressed == null ? undefined : aPressed === "true",
+      ariaChecked: el.getAttribute("aria-checked") || undefined,
+      checkedState: el.checked != null ? String(el.checked) : el.getAttribute("aria-checked") || undefined,
+      ariaSelected: el.getAttribute("aria-selected") || undefined,
+      valueNow: el.value != null ? String(el.value) : el.getAttribute("aria-valuenow") || undefined,
+      optionCount: el.tagName === "SELECT" ? el.options.length : (el.getAttribute("role") === "listbox" || el.getAttribute("role") === "combobox") ? el.querySelectorAll("[role=option]").length : undefined,
+      ariaHasPopup: el.getAttribute("aria-haspopup") || undefined,
+      group: el.getAttribute("name") || el.getAttribute("aria-owns") || undefined,
+      disabled: !!(el.disabled || el.getAttribute("aria-disabled") === "true"),
+      contentEditable: el.isContentEditable === true,
+      hasOnClick: el.hasAttribute("onclick") || typeof el.onclick === "function",
+      tabbable: el.hasAttribute("tabindex") && el.getAttribute("tabindex") !== "-1",
+      linkClass: linkClassOf(el),
+      formMethod, formAction, onclickText: onclickAttr || undefined,
+    });
+  };
+  const collect = (root) => {
+    try { root.querySelectorAll(SEL).forEach(process); } catch (e) {}
+    try {
+      root.querySelectorAll("*").forEach((el) => {
+        if (el.shadowRoot) { collect(el.shadowRoot); }
+        else if (el.tagName && el.tagName.includes("-") && el.childElementCount === 0) { blindSpots++; }
+      });
+    } catch (e) {}
+  };
+  collect(document);
+  return { els: out, blindSpots };
+})()`;
+/** Browser-side link + anchor-id collection (string body — see EXTRACT note). */
+const COLLECT_LINKS = `(() => {
+  const links = [];
+  document.querySelectorAll("a[href], area[href]").forEach((el) => {
+    const rawHref = el.getAttribute("href");
+    if (rawHref == null) return;
+    links.push({
+      rawHref,
+      resolvedHref: el.href || rawHref,
+      text: (el.innerText || el.textContent || "").trim().replace(/\\s+/g, " ").slice(0, 80),
+      isDownload: el.hasAttribute("download"),
+      foundOnUrl: location.href,
+    });
+  });
+  const anchorIds = [];
+  document.querySelectorAll("[id]").forEach((el) => { if (el.id) anchorIds.push(el.id); });
+  document.querySelectorAll("[name]").forEach((el) => { const n = el.getAttribute("name"); if (n) anchorIds.push(n); });
+  return { links, anchorIds };
+})()`;
+/** Browser-side form discovery (string body — tags forms with data-comber-form-ref). */
+const DISCOVER_FORMS = `(() => {
+  const isVis = (el) => { const r = el.getBoundingClientRect(); const s = getComputedStyle(el); return r.width > 0 && r.height > 0 && s.display !== "none" && s.visibility !== "hidden"; };
+  const forms = []; let fi = 0;
+  document.querySelectorAll("form, [role=form]").forEach((f) => {
+    if (!isVis(f)) return;
+    const fref = "f" + (fi++);
+    try { f.setAttribute("data-comber-form-ref", fref); } catch (e) {}
+    const fields = [];
+    f.querySelectorAll("input,select,textarea").forEach((el) => {
+      const type = (el.type || el.tagName).toLowerCase();
+      if (["hidden","submit","button","reset","image"].includes(type)) return;
+      let label = "";
+      if (el.id) { const lab = document.querySelector("label[for='" + (window.CSS && CSS.escape ? CSS.escape(el.id) : el.id) + "']"); if (lab) label = lab.innerText || ""; }
+      label = label || el.getAttribute("aria-label") || el.getAttribute("placeholder") || el.getAttribute("name") || "";
+      fields.push({ name: el.getAttribute("name") || el.id || "", type, label: String(label).trim().slice(0, 60), required: !!(el.required || el.getAttribute("aria-required") === "true"), pattern: el.getAttribute("pattern") || undefined });
+    });
+    const submitEl = f.querySelector("[type=submit], button:not([type=button])");
+    forms.push({
+      formRef: fref, name: f.getAttribute("name") || f.getAttribute("aria-label") || "",
+      action: f.getAttribute("action") || undefined, method: (f.getAttribute("method") || "get").toLowerCase(),
+      submitText: ((submitEl && (submitEl.innerText || submitEl.value)) || "").trim().slice(0, 40),
+      fieldCount: fields.length, requiredCount: fields.filter((x) => x.required).length, fields,
+    });
+  });
+  return forms;
+})()`;
+const WEBACTION_PREFIX = "webaction:";
+const WEBACTION_BASE_SEP = "::";
+const WEBACTION_STEP_SEP = ">>";
+const NOOP_COVERAGE = { skip() { }, bumpExtra() { } };
+function normalizeUrl(url) {
+    try {
+        const u = new URL(url);
+        u.hash = "";
+        return u.toString();
+    }
+    catch {
+        return url;
+    }
+}
+function pathOf(url) {
+    try {
+        return new URL(url).pathname;
+    }
+    catch {
+        return url;
+    }
+}
+function egressSignalSignature(method, url) {
+    const key = (() => {
+        try {
+            const parsed = new URL(url);
+            parsed.hash = "";
+            parsed.search = "";
+            parsed.hostname = parsed.hostname.toLowerCase();
+            return `${parsed.protocol}//${parsed.host}${parsed.pathname}`;
+        }
+        catch {
+            return url;
+        }
+    })();
+    return `egress-${method}-${createHash("sha1").update(key).digest("hex").slice(0, 12)}`;
+}
+function sameOrigin(a, b) {
+    try {
+        return new URL(a).origin === new URL(b).origin;
+    }
+    catch {
+        return false;
+    }
+}
+/** scheme+host+port of a URL, or undefined if unparseable. (No shared util existed.) */
+function originOf(url) {
+    try {
+        return new URL(url).origin;
+    }
+    catch {
+        return undefined;
+    }
+}
+function encodeWebActionPath(baseUrl, domPaths) {
+    return `${WEBACTION_PREFIX}${encodeURIComponent(baseUrl)}${WEBACTION_BASE_SEP}${domPaths
+        .map((domPath) => encodeURIComponent(domPath))
+        .join(WEBACTION_STEP_SEP)}`;
+}
+function parseWebActionPath(id) {
+    const body = id.slice(WEBACTION_PREFIX.length);
+    const sep = body.indexOf(WEBACTION_BASE_SEP);
+    const rawBase = sep < 0 ? body : body.slice(0, sep);
+    const rawSteps = sep < 0 ? "" : body.slice(sep + WEBACTION_BASE_SEP.length);
+    const domPaths = rawSteps
+        ? rawSteps.split(WEBACTION_STEP_SEP).filter(Boolean).map((step) => decodeURIComponent(step))
+        : [];
+    return { baseUrl: decodeURIComponent(rawBase), domPaths };
+}
+/**
+ * The first Driver implementation — Playwright over Chromium. It keeps ALL web/DOM/ARIA
+ * semantics (the ElKind taxonomy, link/form subsystems, axe, the egress gates) behind the
+ * core contract: the core only ever sees an `Address`, a `Surface` of `SurfaceNode`s, and
+ * `BreakageSignal`s. Web-internal control/form/link drivers run via `exercise`/`probe`.
+ */
+export class WebDriver {
+    opts;
+    name = "web";
+    // Probes registered with their lifecycle slot. The order reproduces the pre-v2 hard-coded
+    // crawl ordering EXACTLY: after-goto → session; after-snapshot → axe, dom, links (in that
+    // order); after-exercise → forms. No `finalize`-slot probe (link validation is the
+    // separate DriverExtras.finalize). Byte-identical web findings + plan ordering.
+    capabilities = {
+        screenshot: true,
+        probes: [
+            { name: "session", slot: "after-goto" },
+            { name: "axe", slot: "after-snapshot" },
+            { name: "dom", slot: "after-snapshot" },
+            { name: "links", slot: "after-snapshot" },
+            { name: "forms", slot: "after-exercise" },
+        ],
+    };
+    browser;
+    ctx;
+    page;
+    signals = [];
+    egressGuard = new EgressGuard();
+    cov = NOOP_COVERAGE;
+    linkChecker;
+    formTester;
+    crawlReached = new Set();
+    lastSnapshot;
+    linkAudit = [];
+    axeRuns = 0;
+    actionBaseUrl = "";
+    actionPath = [];
+    constructor(opts) {
+        this.opts = opts;
+    }
+    // -- DriverExtras: core injects its coverage sink so web sub-metrics + form skips land
+    //    in the same honest ledger the orchestrator owns. --
+    attachCoverage(sink) {
+        this.cov = sink;
+    }
+    async start() {
+        try {
+            await this.startInner();
+        }
+        catch (err) {
+            // A failure AFTER launch (newContext/route/newPage can all throw) would otherwise
+            // orphan a headless Chromium process — one leaked browser per failed start, compounding
+            // in CI. Tear down what we opened before propagating.
+            await this.close();
+            throw err;
+        }
+    }
+    async startInner() {
+        this.browser = await chromium.launch({ headless: this.opts.headless });
+        this.ctx = await this.browser.newContext({
+            ...(this.opts.storageStatePath ? { storageState: this.opts.storageStatePath } : {}),
+            // Lets a synthetic-aware app reject the bot server-side too.
+            extraHTTPHeaders: { "X-Comber-Synthetic": "1" },
+        });
+        // EGRESS GATE — registered before any navigation. Aborts destructive-endpoint URLs
+        // always; aborts all mutating methods when --block-writes. Every block is observable.
+        const egress = this.opts.egressUrlDenylist;
+        const blockWrites = this.opts.blockWrites === true;
+        await this.ctx.route("**/*", async (route) => {
+            const req = route.request();
+            const method = req.method().toUpperCase();
+            const url = req.url();
+            const mutating = method === "POST" || method === "PUT" || method === "PATCH" || method === "DELETE";
+            // DELETE is an inherently destructive verb — there is no read-DELETE — so it is blocked
+            // ALWAYS, independent of --allow-writes, closing the RESTful `DELETE /api/items/5` bypass
+            // the accessible-name denylist can't see (an icon-only delete has no name to match).
+            const destructiveMethod = method === "DELETE";
+            const urlDenied = egress ? egress.test(url) : false;
+            const localFixtureAllowed = this.opts.allowPrivateNetworkForTesting === true && sameOrigin(url, this.opts.startUrl);
+            const networkDecision = localFixtureAllowed ? { allowed: true } : await this.egressGuard.check(url);
+            if (!networkDecision.allowed || urlDenied || destructiveMethod || (blockWrites && mutating)) {
+                const reason = !networkDecision.allowed
+                    ? networkDecision.reason ?? "blocked by network egress policy"
+                    : urlDenied
+                        ? "blocked by destructive URL policy"
+                        : destructiveMethod
+                            ? "blocked destructive DELETE method"
+                            : "blocked by write policy";
+                this.signals.push({
+                    kind: "egress-blocked",
+                    severity: "warn",
+                    message: `blocked ${method} ${url.slice(0, 140)} (${reason})`,
+                    url: this.page?.url() ?? url,
+                    signature: egressSignalSignature(method, url),
+                });
+                return route.abort("blockedbyclient");
+            }
+            return route.continue();
+        });
+        // WebSocket egress gate — ws:// / wss:// connections bypass the HTTP route
+        // above, so gate them separately with the same EgressGuard (private/metadata
+        // targets blocked). Held until we decide: connect-through if allowed, close if not.
+        await this.ctx.routeWebSocket("**/*", async (ws) => {
+            const wsUrl = ws.url();
+            const localFixtureAllowed = this.opts.allowPrivateNetworkForTesting === true && sameOrigin(wsUrl, this.opts.startUrl);
+            const decision = localFixtureAllowed ? { allowed: true } : await this.egressGuard.check(wsUrl);
+            if (!decision.allowed) {
+                this.signals.push({
+                    kind: "egress-blocked",
+                    severity: "warn",
+                    message: `blocked WS ${wsUrl.slice(0, 140)} (${decision.reason ?? "blocked by network egress policy"})`,
+                    url: this.page?.url() ?? wsUrl,
+                    signature: egressSignalSignature("WS", wsUrl),
+                });
+                ws.close();
+                return;
+            }
+            ws.connectToServer();
+        });
+        this.page = await this.ctx.newPage();
+        attachBreakageListeners(this.page, (s) => this.signals.push(s));
+        await attachInitScripts(this.page);
+        this.linkChecker = new LinkChecker({
+            startOrigin: (() => {
+                try {
+                    return new URL(this.opts.startUrl).origin;
+                }
+                catch {
+                    return this.opts.startUrl;
+                }
+            })(),
+            globalConcurrency: this.opts.linkConcurrency,
+            timeoutMs: this.opts.linkTimeoutMs,
+            externalEnabled: this.opts.checkExternalLinks,
+            maxExternalLinks: this.opts.maxExternalLinks,
+            crawlReachedUrls: this.crawlReached,
+        });
+    }
+    get p() {
+        if (!this.page)
+            throw new Error("WebDriver not started");
+        return this.page;
+    }
+    // -- addressing --------------------------------------------------------------
+    addressOf(url) {
+        return { id: normalizeUrl(url), scope: pathOf(url), label: url };
+    }
+    entryAddress() {
+        return this.addressOf(this.opts.startUrl);
+    }
+    currentAddress() {
+        if (this.actionPath.length > 0 && this.lastSnapshot) {
+            return this.actionAddressForSnapshot(this.lastSnapshot, this.actionPath);
+        }
+        return this.addressOf(this.currentUrl());
+    }
+    inScope(addr) {
+        if (addr.id.startsWith(WEBACTION_PREFIX)) {
+            return this.isAllowedOrigin(parseWebActionPath(addr.id).baseUrl);
+        }
+        return this.isAllowedOrigin(addr.id);
+    }
+    isAllowedOrigin(url) {
+        if (!this.opts.sameOriginOnly)
+            return true;
+        try {
+            return this.opts.allowedOrigins.includes(new URL(url).origin);
+        }
+        catch {
+            return sameOrigin(url, this.opts.startUrl);
+        }
+    }
+    /**
+     * Derive the core `ActionEffect` from a submit-capable control's form metadata, so the core
+     * action-floor gates on what the action DOES (wire method / destination), not its
+     * author/attacker-controlled label. Links are the follow-frontier (never exercised) → no
+     * effect. A non-form JS button carries no method → no effect here; its writes are still caught
+     * at the wire by the egress denylist / `--block-writes`. Returns undefined when nothing is
+     * known (so unknown-effect nodes stay allow, keeping this additive).
+     */
+    effectOf(el) {
+        if (el.kind === "link")
+            return undefined;
+        const effect = {};
+        const method = el.formMethod ? el.formMethod.toUpperCase() : undefined;
+        if (method) {
+            effect.method = method;
+            effect.mutates = /^(POST|PUT|PATCH|DELETE)$/.test(method);
+            if (method === "DELETE")
+                effect.irreversible = "delete";
+        }
+        if (el.formAction) {
+            const origin = originOf(el.formAction);
+            if (origin) {
+                effect.destinationOrigin = origin;
+                // offOrigin = outside the operator's allowed set (suppressed when --cross-origin is on).
+                if (!this.isAllowedOrigin(el.formAction))
+                    effect.offOrigin = true;
+                // crossOrigin = destination ≠ the CURRENT page origin, INDEPENDENT of the allowed set —
+                // so a cross-origin WRITE is hard-denied (action-gate rule 1) even when cross-origin
+                // crawling is enabled, closing the exfil-POST bypass.
+                if (origin !== originOf(this.currentUrl()))
+                    effect.crossOrigin = true;
+            }
+        }
+        if (el.onclickText && /\bconfirm\s*\(/i.test(el.onclickText))
+            effect.requiresConfirm = true;
+        return Object.keys(effect).length > 0 ? effect : undefined;
+    }
+    async goto(addr) {
+        if (addr.id.startsWith(WEBACTION_PREFIX)) {
+            const parsed = parseWebActionPath(addr.id);
+            await this.gotoUrl(parsed.baseUrl);
+            this.actionBaseUrl = parsed.baseUrl;
+            this.actionPath = [];
+            for (const domPath of parsed.domPaths) {
+                await this.clickDomPath(domPath);
+                this.actionPath.push(domPath);
+            }
+            return;
+        }
+        this.actionBaseUrl = addr.id;
+        this.actionPath = [];
+        await this.gotoUrl(addr.id);
+    }
+    async gotoUrl(url) {
+        await this.p.goto(url, { waitUntil: "domcontentloaded", timeout: 30_000 }).catch((e) => {
+            this.signals.push({
+                kind: "navigation-failed",
+                severity: "fail",
+                message: `goto ${url} failed: ${String(e).slice(0, 200)}`,
+                url,
+                signature: `nav-${url}`,
+            });
+        });
+        await this.settle();
+    }
+    /** Best-effort "page is done reacting": network-idle with a short ceiling. */
+    async settle() {
+        await this.p.waitForLoadState("networkidle", { timeout: 8_000 }).catch(() => { });
+    }
+    /** Web-internal DOM-first snapshot (full InteractiveEl). The core sees only the Surface
+     *  produced by `snapshot()`; control/form handlers use this richer view. */
+    async webSnapshot() {
+        const interactive = [];
+        let frameBlindSpots = 0;
+        const blindSpotDetails = [];
+        for (const frame of this.p.frames()) {
+            const isMain = frame === this.p.mainFrame();
+            try {
+                const res = (await frame.evaluate(EXTRACT_INTERACTIVE));
+                frameBlindSpots += res.blindSpots;
+                const scope = pathOf(frame.url() || this.p.url());
+                for (let i = 0; i < res.blindSpots; i++) {
+                    blindSpotDetails.push({
+                        kind: "closed-shadow-root",
+                        severity: "blocker-for-exhaustive",
+                        scope,
+                        message: "closed shadow root or opaque custom element could not be inspected",
+                    });
+                }
+                for (const raw of res.els) {
+                    interactive.push({
+                        ...raw,
+                        kind: classify(raw),
+                        selector: `[data-comber-ref="${raw.ref}"]`,
+                        framePath: isMain ? undefined : [frame.url()],
+                        inShadow: undefined,
+                    });
+                }
+            }
+            catch {
+                // cross-origin frame — can't evaluate into it. Honest blind spot.
+                if (!isMain) {
+                    frameBlindSpots += 1;
+                    blindSpotDetails.push({
+                        kind: "cross-origin-frame",
+                        severity: "blocker-for-exhaustive",
+                        scope: pathOf(frame.url() || this.p.url()),
+                        message: "cross-origin frame could not be inspected",
+                    });
+                }
+            }
+        }
+        return {
+            url: this.p.url(),
+            title: await this.p.title().catch(() => ""),
+            interactive,
+            frameBlindSpots,
+            blindSpotDetails,
+        };
+    }
+    /** DISCOVER — the contract surface. Wraps webSnapshot into target-agnostic nodes:
+     *  the full InteractiveEl rides in `handle`; file-inputs are surfaced as disabled
+     *  (never drive a native file picker); links are `navigates` (followed, not clicked). */
+    async snapshot() {
+        const snap = await this.webSnapshot();
+        this.lastSnapshot = snap;
+        const nodes = orderForExhaustion(snap.interactive).map((el) => ({
+            id: el.domPath,
+            kind: el.kind,
+            label: el.name,
+            handle: el,
+            group: el.group,
+            disabled: Boolean(el.disabled) || el.kind === "file-input",
+            intent: traversalIntentForKind(el.kind),
+            navigates: el.kind === "link",
+            effect: this.effectOf(el),
+        }));
+        return {
+            address: this.surfaceAddress(snap),
+            title: snap.title,
+            nodes,
+            blindSpots: snap.frameBlindSpots,
+            blindSpotDetails: snap.blindSpotDetails,
+        };
+    }
+    /** EXERCISE — type-correct dispatch over the ElKind in the node's handle. Stateful
+     *  controls go through the assert-changed handlers; control/dead-* signals ride the
+     *  ExerciseResult, listener signals drain via drainSignals(). */
+    async exercise(node) {
+        const el = node.handle;
+        const signals = [];
+        if (node.intent === "branch") {
+            return this.exerciseBranch(el);
+        }
+        if (isControl(el.kind)) {
+            const r = await exerciseControl(this, el);
+            signals.push(...r.signals);
+            this.cov.bumpExtra("controlsExercised");
+            if (r.modalOpened)
+                this.cov.bumpExtra("modalsOpened");
+            return { signals };
+        }
+        switch (el.kind) {
+            case "text-input":
+                await this.fill(el, synthFor(el));
+                break;
+            case "contenteditable":
+                await this.fill(el, "comber-probe");
+                break;
+            default:
+                // button / generic-clickable / other
+                await this.act(el);
+        }
+        return { signals };
+    }
+    async exerciseBranch(el) {
+        const before = this.lastSnapshot ?? (await this.webSnapshot());
+        const beforeUrl = before.url;
+        const beforeFp = restoreFingerprint(before);
+        await this.act(el);
+        const after = await this.webSnapshot();
+        this.lastSnapshot = after;
+        if (after.url !== beforeUrl) {
+            return { discovered: [this.addressOf(after.url)] };
+        }
+        if (restoreFingerprint(after) === beforeFp) {
+            return {};
+        }
+        const nextPath = [...this.actionPath, el.domPath];
+        return { discovered: [this.actionAddressForSnapshot(after, nextPath)] };
+    }
+    // -- web-internal action primitives (ControlActions) -------------------------
+    /** Resolve a Locator for an element, honoring iframe context, with a domPath fallback. */
+    async resolveLocator(el) {
+        let root = this.p;
+        if (el.framePath && el.framePath.length) {
+            const f = this.p.frames().find((fr) => fr.url() === el.framePath[0]);
+            if (f)
+                root = f;
+        }
+        const primary = root.locator(el.selector).first();
+        if ((await primary.count().catch(() => 0)) > 0)
+            return primary;
+        // Stale ref after a re-snapshot/restore: fall back to the structural domPath.
+        if (el.domPath) {
+            const byPath = root.locator(el.domPath).first();
+            if ((await byPath.count().catch(() => 0)) > 0)
+                return byPath;
+        }
+        return primary; // let the action surface the real failure
+    }
+    async clickDomPath(domPath) {
+        await this.p.locator(domPath).first().click({ timeout: 5_000 }).catch((e) => {
+            this.signals.push({
+                kind: "dead-end-click",
+                severity: "warn",
+                message: `replay click "${domPath}" had no effect or errored: ${String(e).slice(0, 120)}`,
+                url: this.p.url(),
+                signature: `dead-replay-${domPath}`.slice(0, 80),
+            });
+        });
+        await this.settle();
+    }
+    async act(el) {
+        const target = await this.resolveLocator(el);
+        await target.click({ timeout: 5_000 }).catch((e) => {
+            this.signals.push({
+                kind: "dead-end-click",
+                severity: "warn",
+                message: `click "${el.name}" (${el.kind}) had no effect or errored: ${String(e).slice(0, 120)}`,
+                url: this.p.url(),
+                signature: `dead-${el.kind}-${el.domPath}`.slice(0, 80),
+            });
+        });
+        await this.settle();
+    }
+    async fill(el, value) {
+        const target = await this.resolveLocator(el);
+        await target.fill(value, { timeout: 5_000 }).catch(() => { });
+        await this.settle();
+    }
+    async selectOption(el, value) {
+        const target = await this.resolveLocator(el);
+        await target.selectOption(value !== undefined ? value : { index: 1 }, { timeout: 5_000 }).catch(() => { });
+        await this.settle();
+    }
+    async pressKey(key) {
+        await this.p.keyboard.press(key).catch(() => { });
+        await this.settle();
+    }
+    async nudge(el) {
+        const target = await this.resolveLocator(el);
+        await target.press("ArrowRight", { timeout: 5_000 }).catch(() => { });
+        await this.settle();
+    }
+    /** DriverExtras.softReset — the cheap middle restore tier (dismiss a leftover popover). */
+    async softReset() {
+        await this.pressKey("Escape");
+    }
+    // -- web-internal link + form primitives -------------------------------------
+    async collectLinks() {
+        return (await this.p.evaluate(COLLECT_LINKS).catch(() => ({ links: [], anchorIds: [] })));
+    }
+    async discoverForms() {
+        return (await this.p.evaluate(DISCOVER_FORMS).catch(() => []));
+    }
+    // Refs are controlled "fN" tokens, so building eval strings via template literal is
+    // safe AND sidesteps the esbuild __name trap (string contents aren't transpiled).
+    async formEmptyProbe(ref) {
+        const js = `(() => {
+      const f = document.querySelector('[data-comber-form-ref="${ref}"]'); if (!f) return null;
+      const els = f.querySelectorAll("input,select,textarea");
+      const saved = []; els.forEach((el, i) => saved.push([i, el.value == null ? "" : el.value]));
+      els.forEach((el) => {
+        const t = (el.type || "").toLowerCase();
+        if (el.tagName === "TEXTAREA" || ["text","email","password","search","tel","url","number","date","","time","month"].includes(t)) {
+          el.value = ""; el.dispatchEvent(new Event("input", { bubbles: true }));
+        }
+      });
+      return { savedJson: JSON.stringify(saved), checkValidity: f.checkValidity ? f.checkValidity() : true, requiredCount: f.querySelectorAll("[required],[aria-required='true']").length };
+    })()`;
+        return (await this.p.evaluate(js).catch(() => null));
+    }
+    async submitForm(ref) {
+        const js = `(() => { const f = document.querySelector('[data-comber-form-ref="${ref}"]'); if (f) { if (f.requestSubmit) f.requestSubmit(); else if (f.submit) f.submit(); } })()`;
+        await this.p.evaluate(js).catch(() => { });
+        await this.settle();
+    }
+    async formFeedback() {
+        const js = `(() => !!document.querySelector('[aria-invalid="true"], [role=alert]:not(:empty), input:invalid, textarea:invalid, select:invalid'))()`;
+        return (await this.p.evaluate(js).catch(() => false));
+    }
+    async formExists(ref) {
+        const js = `(() => !!document.querySelector('[data-comber-form-ref="${ref}"]'))()`;
+        return (await this.p.evaluate(js).catch(() => false));
+    }
+    async restoreForm(ref, savedJson) {
+        const js = `(() => {
+      const f = document.querySelector('[data-comber-form-ref="${ref}"]'); if (!f) return;
+      const saved = ${savedJson}; const els = f.querySelectorAll("input,select,textarea");
+      saved.forEach((pair) => { const el = els[pair[0]]; if (el) { el.value = pair[1]; el.dispatchEvent(new Event("input", { bubbles: true })); } });
+    })()`;
+        await this.p.evaluate(js).catch(() => { });
+    }
+    /** DriverExtras.outboundAddresses — in-scope, non-denylisted link destinations from the
+     *  most recent surface, so the frontier expands by FOLLOWING links (never clicking them).
+     *  The web destructive-href + name denylists are enforced here (where the href lives). */
+    outboundAddresses() {
+        const snap = this.lastSnapshot;
+        if (!snap)
+            return [];
+        // domPath order matches the pre-split frontier (links sort last in orderForExhaustion,
+        // then by domPath), so traversal order under a tight --max-states cap is preserved.
+        const links = snap.interactive
+            .filter((el) => el.kind === "link")
+            .sort((a, b) => (a.domPath < b.domPath ? -1 : a.domPath > b.domPath ? 1 : 0));
+        const out = [];
+        for (const el of links) {
+            if (!el.href)
+                continue;
+            if (this.opts.denylist.test(el.name || ""))
+                continue;
+            if (this.opts.destructiveHrefDenylist.test(el.href))
+                continue;
+            if (el.linkClass === "internal" || (!el.linkClass && /^https?:/i.test(el.href))) {
+                const addr = this.addressOf(el.href);
+                if (this.isAllowedOrigin(addr.id))
+                    out.push(addr);
+            }
+        }
+        return out;
+    }
+    /** A named, capability-gated discovery pass. Collect-during for links; the validate-after
+     *  post-pass is DriverExtras.finalize. axe self-limits to the first 8 states (bounded cost). */
+    async probe(phase) {
+        switch (phase) {
+            case "session": {
+                const s = await sessionLivenessProbe(this.p);
+                return s ? [s] : [];
+            }
+            case "dom":
+                return auditDom(this.p);
+            case "axe": {
+                if (this.axeRuns >= 8)
+                    return [];
+                this.axeRuns++;
+                return runAxe(this.p);
+            }
+            case "links": {
+                // collect-during (every new state); validation happens in finalize().
+                this.crawlReached.add(normalizeUrl(this.currentUrl()));
+                if (this.linkChecker)
+                    this.linkChecker.ingest(await this.collectLinks(), this.currentUrl());
+                return [];
+            }
+            case "forms": {
+                this.formTester ??= new FormTester(this, this.cov);
+                const out = [];
+                await this.formTester.testState(this.currentUrl(), (s) => out.push(s));
+                return out;
+            }
+            default:
+                return [];
+        }
+    }
+    /** DriverExtras.finalize — validate EVERY collected link over the cookie-inheriting
+     *  request context (server-side, so CORS is a non-issue). Must run before close(). */
+    async finalize() {
+        if (!this.linkChecker || !this.ctx)
+            return [];
+        this.linkAudit = await this.linkChecker.validateAll(this.ctx.request).catch(() => []);
+        this.cov.bumpExtra("linksChecked", this.linkAudit.filter((r) => r.method !== "skip").length);
+        this.cov.bumpExtra("linksBroken", this.linkAudit.filter((r) => !r.ok).length);
+        return this.linkChecker.toFindings(this.linkAudit);
+    }
+    /** DriverExtras.auditExtra — structured per-driver data for the report/result.json. */
+    auditExtra() {
+        return { linkAudit: this.linkAudit };
+    }
+    async screenshot() {
+        return this.p.screenshot({ fullPage: false }).catch(() => Buffer.alloc(0));
+    }
+    currentUrl() {
+        return this.page?.url() ?? "";
+    }
+    surfaceAddress(snap) {
+        if (this.actionPath.length === 0)
+            return this.addressOf(snap.url);
+        return this.actionAddressForSnapshot(snap, this.actionPath);
+    }
+    actionAddressForSnapshot(snap, domPaths) {
+        const baseUrl = this.actionBaseUrl || snap.url;
+        const fingerprint = restoreFingerprint(snap);
+        const scope = `${pathOf(baseUrl)}#branch-${fingerprint.slice(0, 8)}`;
+        const label = `${snap.url} :: ${snap.title || "branch"}`;
+        return {
+            id: encodeWebActionPath(baseUrl, domPaths),
+            scope,
+            dedupeKey: `webbranch:${fingerprint}`,
+            label,
+        };
+    }
+    drainSignals() {
+        const out = this.signals;
+        this.signals = [];
+        return out;
+    }
+    async close() {
+        await this.browser?.close().catch(() => { });
+    }
+}