agent-device-lab 0.0.0-stage → 0.3.1

package/dist/core/bundle.js

@@ -0,0 +1,432 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { arch, platform, release } from 'node:os';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+import { redactSecrets, displayUrl } from './feed.js';
+import { routePath } from './action-log.js';
+import { SECRET_FIELD } from './steps.js';
+import { readZip } from './zip.js';
+import { LabError, } from './schema.js';
+import { CONTRACT_VERSIONS, productVersion } from './versions.js';
+// Failure bundles: a folder holding bundle.json (what happened, how to replay it), the evidence frames and,
+// when recorded and provably clean, a sanitized Playwright trace. The bundle is meant to leave the machine as a
+// CI artifact or a bug report, so it never holds commands' environment, request bodies, headers, typed
+// passwords or saved sign-in state, and a final pass over everything written refuses to proceed if a secret
+// value known to the process is still in it.
+export const BUNDLE_KIND = 'agentlab-failure-bundle';
+export const BUNDLE_FILE = 'bundle.json';
+const REDACTED = '‹redacted›';
+const SET = '‹set›';
+const DEFAULT_KEEP = 20;
+const DEFAULT_DAYS = 14;
+const MAX_FRAMES = 60;
+const MIN_ENV_SECRET = 6;
+/** A declared service env value this long is treated as a secret whatever its name (a token, a URL with credentials). */
+const LONG_ENV_VALUE = 16;
+const SECRET_ENV_NAME = /secret|token|passw|api[_-]?key|auth|cookie|private|credential|signature|csrf/i;
+/** Scenario steps aimed at a field with one of these words in its name or role keep no `value`. */
+const SECRETISH = SECRET_FIELD;
+const ID = /^b-\d{8}T\d{6}-[0-9a-f]{4}$/;
+export const sha256 = (data) => createHash('sha256').update(data).digest('hex');
+export function bundleId(now = new Date()) {
+    return `b-${now.toISOString().slice(0, 19).replace(/[-:]/g, '')}-${randomBytes(2).toString('hex')}`;
+}
+// ---------- what must never be written ----------
+/** Values in the process environment that must not appear in a bundle: required and secret-named variables, and long declared service values. */
+export function envSecrets(profile, env = process.env) {
+    const out = new Set();
+    const add = (v, min) => { if (v && v.length >= min)
+        out.add(v); };
+    for (const svc of profile.services) {
+        for (const name of svc.requiredEnv)
+            add(env[name], MIN_ENV_SECRET);
+        for (const value of Object.values(svc.env))
+            add(value, LONG_ENV_VALUE);
+    }
+    for (const [name, value] of Object.entries(env))
+        if (SECRET_ENV_NAME.test(name))
+            add(value, MIN_ENV_SECRET);
+    return [...out];
+}
+const variants = (secret) => [...new Set([secret, encodeURIComponent(secret)])].filter((v) => v.length > 0);
+const escapedVariants = (secret) => [...new Set([...variants(secret), JSON.stringify(secret).slice(1, -1)])];
+function replaceAll(text, secrets) {
+    let out = text;
+    for (const s of secrets)
+        for (const v of variants(s))
+            if (out.includes(v))
+                out = out.split(v).join(REDACTED);
+    return out;
+}
+/** A copy of a JSON value with every secret replaced inside its strings. */
+export function redactTree(value, secrets) {
+    if (typeof value === 'string')
+        return replaceAll(value, secrets);
+    if (Array.isArray(value))
+        return value.map((v) => redactTree(v, secrets));
+    if (value && typeof value === 'object')
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, redactTree(v, secrets)]));
+    return value;
+}
+/** Names of the secrets still in `text`, as a count only: the values are never reported. */
+export function leakedSecrets(text, secrets) {
+    return secrets.filter((s) => escapedVariants(s).some((v) => text.includes(v))).length;
+}
+// ---------- the profile, sanitized ----------
+const isRec = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/**
+ * agentlab.json as it can leave the machine: every service env value becomes ‹set› (names kept), requiredEnv
+ * names stay, strings pass through `redactSecrets` (commands, URLs, everything), and the auth section keeps
+ * only `use`, `loginPath` and the state file relative to the project root. Scenario steps aimed at a
+ * secret-looking field keep no `value`.
+ */
+export function sanitizeProfile(raw, root) {
+    if (!isRec(raw))
+        return {};
+    const copy = structuredClone(raw);
+    const mask = (svc) => {
+        if (isRec(svc) && isRec(svc.env))
+            svc.env = Object.fromEntries(Object.keys(svc.env).map((k) => [k, SET]));
+    };
+    mask(copy.web);
+    if (isRec(copy.services))
+        for (const svc of Object.values(copy.services))
+            mask(svc);
+    if (isRec(copy.auth)) {
+        const { use, loginPath, file } = copy.auth;
+        const rel = typeof file === 'string' ? relative(root, resolve(root, file)) : undefined;
+        copy.auth = { ...(use !== undefined ? { use } : {}), ...(loginPath !== undefined ? { loginPath } : {}), ...(rel !== undefined ? { file: rel } : {}) };
+    }
+    // Sign-in steps in declared scenarios carry test credentials: same rule as the bundle's scenario section.
+    const scenarios = isRec(copy.scan) && Array.isArray(copy.scan.scenarios) ? copy.scan.scenarios : [];
+    for (const sc of scenarios) {
+        if (!isRec(sc))
+            continue;
+        for (const key of ['steps', 'cleanup'])
+            if (Array.isArray(sc[key]))
+                sc[key] = sanitizeScenarioSteps(sc[key].filter(isRec));
+    }
+    const walk = (v) => {
+        if (typeof v === 'string')
+            return redactSecrets(v);
+        if (Array.isArray(v))
+            return v.map(walk);
+        if (isRec(v))
+            return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, walk(x)]));
+        return v;
+    };
+    return walk(copy);
+}
+/** A declared scenario for the bundle: the `value` of a step aimed at a secret-looking field is masked. */
+export function sanitizeScenarioSteps(steps) {
+    return steps.map((step) => {
+        const s = { ...step };
+        if (s.value !== undefined && SECRETISH.test(`${s.name ?? ''} ${s.nameContains ?? ''} ${s.role ?? ''}`))
+            s.value = '‹secret›';
+        return s;
+    });
+}
+export function summariseConsole(entries, limit = 50) {
+    const seen = new Map();
+    for (const e of entries) {
+        const text = redactSecrets(e.text).slice(0, 300);
+        const key = `${e.type}\u0001${text}`;
+        const prev = seen.get(key);
+        seen.delete(key); // re-inserted last: order is by most recent occurrence
+        seen.set(key, { type: e.type, text, count: (prev?.count ?? 0) + 1 });
+    }
+    return [...seen.values()].slice(-limit);
+}
+export function summariseRequests(entries, limit = 50) {
+    return entries.slice(-limit).map((r) => ({
+        method: r.method, url: displayUrl(r.url), ...(r.status !== undefined ? { status: r.status } : {}),
+        ...(r.failure !== undefined ? { failure: redactSecrets(r.failure).slice(0, 200) } : {}),
+    }));
+}
+// ---------- frames ----------
+/** Frames inside the run directory that belong in the bundle, by the name they get there. Nothing outside the run directory is copied. */
+function planFrames(runDir, findings) {
+    const copies = new Map(); // absolute source → name in frames/
+    const taken = new Set();
+    let omitted = 0;
+    let root;
+    try {
+        root = realpathSync(runDir);
+    }
+    catch {
+        return { copies, omitted };
+    }
+    const add = (src) => {
+        let real;
+        try {
+            real = realpathSync(src);
+        }
+        catch {
+            return undefined;
+        }
+        if (!real.startsWith(root + sep) || !statSync(real).isFile())
+            return undefined;
+        const known = copies.get(real);
+        if (known)
+            return known;
+        if (copies.size >= MAX_FRAMES) {
+            omitted++;
+            return undefined;
+        }
+        let name = basename(real);
+        for (let n = 2; taken.has(name); n++)
+            name = `${n}-${basename(real)}`;
+        taken.add(name);
+        copies.set(real, name);
+        return name;
+    };
+    const direct = join(runDir, 'frames');
+    if (existsSync(direct))
+        for (const f of readdirSync(direct).sort())
+            if (/\.jpe?g$/i.test(f))
+                add(join(direct, f));
+    for (const f of findings) {
+        if (f.frame)
+            add(f.frame);
+        for (const x of f.frames ?? [])
+            add(x.path);
+    }
+    return { copies, omitted };
+}
+function withFramePaths(findings, copies) {
+    const nameOf = (p) => {
+        try {
+            const n = copies.get(realpathSync(p));
+            return n ? `frames/${n}` : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    return findings.map((f) => {
+        const { frame, frames, ...rest } = structuredClone(f);
+        const inBundle = frame ? nameOf(frame) : undefined;
+        const extra = (frames ?? []).flatMap((x) => { const p = nameOf(x.path); return p ? [{ ...x, path: p }] : []; });
+        return { ...rest, ...(inBundle ? { frame: inBundle } : {}), ...(extra.length ? { frames: extra } : {}) };
+    });
+}
+// ---------- assembling and writing ----------
+function playwrightVersion() {
+    try {
+        return createRequire(import.meta.url)('playwright/package.json').version;
+    }
+    catch {
+        return 'unknown';
+    }
+}
+const envInt = (name, env) => {
+    const n = Number(env[name]);
+    return env[name] !== undefined && env[name] !== '' && Number.isFinite(n) && n >= 0 ? n : undefined;
+};
+/** The retention limits: AGENTLAB_KEEP_BUNDLES and AGENTLAB_BUNDLE_DAYS override the defaults. */
+export function retentionLimits(env = process.env) {
+    return { keep: envInt('AGENTLAB_KEEP_BUNDLES', env) ?? DEFAULT_KEEP, maxAgeDays: envInt('AGENTLAB_BUNDLE_DAYS', env) ?? DEFAULT_DAYS };
+}
+function ensureDir(dir) {
+    const fresh = !existsSync(dir);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    if (fresh)
+        chmodSync(dir, 0o700);
+}
+/**
+ * Write `<dir>/<id>/bundle.json`, `frames/*.jpg` and `trace.zip` (owner-only: files 0600, directories 0700),
+ * after a final pass that replaces, then verifies the absence of, every secret value known to the process.
+ * Throws `bundle_unsafe` (writing nothing) when one is still present. Prunes old bundles afterwards.
+ */
+export function writeBundle(input, dir) {
+    const env = input.env ?? process.env;
+    const now = input.now ?? new Date();
+    const { profile, session } = input;
+    const limits = retentionLimits(env);
+    const id = bundleId(now);
+    // Longest first, so a secret that contains another is replaced whole.
+    const secrets = [...new Set([...input.secrets, ...envSecrets(profile, env)])].filter((s) => s.length >= 4).sort((a, b) => b.length - a.length);
+    const profileBytes = readFileSync(profile.profilePath);
+    let rawProfile = {};
+    try {
+        rawProfile = JSON.parse(profileBytes.toString('utf8'));
+    }
+    catch { /* the sanitized copy is then empty */ }
+    const declared = profile.scan.scenarios.find((s) => s.name === input.scenario?.name);
+    const frames = planFrames(input.runDir, input.findings);
+    const trace = input.trace && 'file' in input.trace ? checkTrace(input.trace.file, secrets) : undefined;
+    const traceDropped = input.trace && 'dropped' in input.trace ? input.trace.dropped : trace && 'dropped' in trace ? trace.dropped : undefined;
+    const bundle = {
+        kind: BUNDLE_KIND,
+        bundleVersion: CONTRACT_VERSIONS.bundle,
+        id,
+        product: { version: productVersion(), contracts: { ...CONTRACT_VERSIONS } },
+        environment: {
+            node: process.version, platform: platform(), arch: arch(), osRelease: release(), playwright: playwrightVersion(),
+            chromium: session.browser.version, headed: session.browser.headed, ci: Boolean(process.env.CI),
+        },
+        reason: redactSecrets(input.reason).slice(0, 500),
+        failure: input.failure,
+        project: { name: profile.name, profileSha256: sha256(profileBytes), profile: sanitizeProfile(rawProfile, profile.root) },
+        session: { id: session.id, device: session.device.id, auth: session.auth ?? 'fresh', startRoute: routePath(input.startRoute) ?? '/' },
+        ...(declared && input.scenario ? { scenario: { name: declared.name, device: input.scenario.device, route: declared.route, steps: sanitizeScenarioSteps(declared.steps) } } : {}),
+        route: routePath(input.route) ?? '/',
+        actions: input.actions,
+        actionsOmitted: input.actionsOmitted,
+        observations: input.observations,
+        findings: withFramePaths(input.findings, frames.copies),
+        consoleErrors: summariseConsole(input.consoleErrors),
+        failedRequests: summariseRequests(input.failedRequests),
+        frames: [...frames.copies.values()].map((n) => `frames/${n}`),
+        framesOmitted: frames.omitted,
+        ...(trace && 'file' in trace ? { trace: 'trace.zip' } : {}),
+        ...(traceDropped ? { traceDropped } : {}),
+        retention: {
+            createdAt: now.toISOString(),
+            expiresAt: new Date(now.getTime() + limits.maxAgeDays * 86_400_000).toISOString(),
+            policy: `Kept locally for ${limits.maxAgeDays} days, and only the newest ${limits.keep} bundles are kept; agentlab never uploads a bundle.`,
+        },
+    };
+    const safe = redactTree(bundle, secrets);
+    const text = JSON.stringify(safe, null, 2) + '\n';
+    const leaked = leakedSecrets(text, secrets);
+    if (leaked)
+        throw new LabError('bundle_unsafe', `The bundle still contained ${leaked} secret value(s) after redaction; nothing was written`, { hint: 'This is a bug in agentlab: report it without attaching the run.' });
+    const bundleDir = join(resolve(dir), id);
+    ensureDir(resolve(dir));
+    ensureDir(bundleDir);
+    const files = [];
+    const put = (rel, write) => {
+        const to = join(bundleDir, rel);
+        ensureDir(dirname(to));
+        write(to);
+        chmodSync(to, 0o600);
+        files.push(rel);
+    };
+    try {
+        put(BUNDLE_FILE, (to) => writeFileSync(to, text, { mode: 0o600 }));
+        for (const [src, name] of frames.copies)
+            put(`frames/${name}`, (to) => copyFileSync(src, to));
+        if (trace && 'file' in trace)
+            put('trace.zip', (to) => copyFileSync(trace.file, to));
+    }
+    catch (err) {
+        rmSync(bundleDir, { recursive: true, force: true });
+        throw err;
+    }
+    const pruned = pruneBundles(dir, { ...limits, now });
+    return {
+        id, dir: bundleDir, files,
+        counts: {
+            actions: bundle.actions.length, observations: bundle.observations.length, findings: bundle.findings.length,
+            consoleErrors: bundle.consoleErrors.length, failedRequests: bundle.failedRequests.length, frames: bundle.frames.length,
+        },
+        trace: trace && 'file' in trace ? 'included' : traceDropped ? { dropped: traceDropped } : 'not-recorded',
+        pruned,
+    };
+}
+/** A last look at a sanitized trace: a secret still in any entry means it is left out (the sanitizer should have made this impossible). */
+function checkTrace(file, secrets) {
+    try {
+        for (const entry of readZip(readFileSync(file))) {
+            const text = entry.data.toString('latin1');
+            if (leakedSecrets(text, secrets))
+                return { dropped: 'a secret value was still present in the trace after sanitizing' };
+        }
+        return { file };
+    }
+    catch {
+        return { dropped: 'the trace could not be verified' };
+    }
+}
+// ---------- reading, listing, pruning ----------
+/** `<bundle dir>` or `bundle.json`: the path of the file. */
+export function resolveBundleFile(path) {
+    const p = resolve(path);
+    const file = existsSync(p) && statSync(p).isDirectory() ? join(p, BUNDLE_FILE) : p;
+    if (!existsSync(file))
+        throw new LabError('bundle_invalid', `No bundle at ${path}`, { hint: `Pass a bundle directory or its ${BUNDLE_FILE}.` });
+    return file;
+}
+/** Parse and validate a bundle. Its content is untrusted: the shape is checked before anything uses it. */
+export function parseBundle(raw) {
+    const bad = (why) => { throw new LabError('bundle_invalid', `Not a usable failure bundle: ${why}`); };
+    if (!isRec(raw) || raw.kind !== BUNDLE_KIND)
+        return bad('missing kind "agentlab-failure-bundle"');
+    if (typeof raw.bundleVersion !== 'number' || !Number.isInteger(raw.bundleVersion) || raw.bundleVersion < 1)
+        return bad('bundleVersion must be a positive integer');
+    if (raw.bundleVersion > CONTRACT_VERSIONS.bundle) {
+        throw new LabError('bundle_too_new', `This bundle is version ${raw.bundleVersion}; this agentlab reads up to ${CONTRACT_VERSIONS.bundle}`, { hint: 'Upgrade agentlab to replay it.' });
+    }
+    for (const k of ['actions', 'observations', 'findings', 'frames'])
+        if (!Array.isArray(raw[k]))
+            bad(`"${k}" must be a list`);
+    if (!isRec(raw.failure) || typeof raw.failure.kind !== 'string')
+        bad('"failure" is missing');
+    if (!isRec(raw.session) || typeof raw.session.device !== 'string')
+        bad('"session.device" is missing');
+    if (!isRec(raw.project) || typeof raw.project.profileSha256 !== 'string')
+        bad('"project.profileSha256" is missing');
+    if (typeof raw.id !== 'string' || !ID.test(raw.id))
+        bad('"id" is malformed');
+    return raw;
+}
+export function loadBundle(path) {
+    const file = resolveBundleFile(path);
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        throw new LabError('bundle_invalid', `${file} is not valid JSON`);
+    }
+    return parseBundle(raw);
+}
+/** Bundles under `dir`, newest first. Only directories holding a valid bundle.json count; nothing else is ever touched. */
+export function listBundles(dir) {
+    const root = resolve(dir);
+    if (!existsSync(root))
+        return [];
+    const out = [];
+    for (const name of readdirSync(root)) {
+        if (!ID.test(name))
+            continue;
+        try {
+            const b = parseBundle(JSON.parse(readFileSync(join(root, name, BUNDLE_FILE), 'utf8')));
+            out.push({
+                id: b.id, dir: join(root, name), createdAt: b.retention?.createdAt ?? statSync(join(root, name)).mtime.toISOString(), reason: b.reason,
+                failure: b.failure.kind, actions: b.actions.length, findings: b.findings.length, trace: existsSync(join(root, name, 'trace.zip')),
+            });
+        }
+        catch { /* not ours, or unreadable: left alone */ }
+    }
+    return out.sort((a, b) => b.createdAt.localeCompare(a.createdAt) || b.id.localeCompare(a.id));
+}
+export function removeBundle(dir, id) {
+    if (!ID.test(id))
+        throw new LabError('invalid_request', `"${id.slice(0, 40)}" is not a bundle id`, { hint: 'List them with `agentlab bundles`.' });
+    const target = join(resolve(dir), id);
+    if (!existsSync(join(target, BUNDLE_FILE)))
+        throw new LabError('not_found', `No bundle ${id} in ${resolve(dir)}`);
+    rmSync(target, { recursive: true, force: true });
+}
+/** Remove bundles beyond the newest `keep` and older than `maxAgeDays`. Returns the ids removed. */
+export function pruneBundles(dir, opts = {}) {
+    const limits = retentionLimits();
+    const keep = opts.keep ?? limits.keep;
+    const maxAgeDays = opts.maxAgeDays ?? limits.maxAgeDays;
+    const cutoff = (opts.now ?? new Date()).getTime() - maxAgeDays * 86_400_000;
+    const removed = [];
+    listBundles(dir).forEach((b, i) => {
+        if (i >= keep || Date.parse(b.createdAt) < cutoff) {
+            try {
+                removeBundle(dir, b.id);
+                removed.push(b.id);
+            }
+            catch { /* already gone */ }
+        }
+    });
+    return removed;
+}
+//# sourceMappingURL=bundle.js.map

package/dist/core/checks.js

@@ -0,0 +1,137 @@
+import { writeFileSync } from 'node:fs';
+import { coveredHits, detectLayout, labelKey, modalHits, shiftHits } from './detectors.js';
+import { centreInView, coveredAtExtremes, extractPage, lookupRef, measureLayout, panIntoView, scrollToOrigin, takeLayoutShifts, targetPoint, } from './extract.js';
+import { buildObservation } from './observation.js';
+const OBSERVE_LIMIT = 60;
+export async function measureState(page, m) {
+    const on = m.detectors.enabled;
+    const seen = new Set();
+    await page.evaluate(scrollToOrigin);
+    let o = m.observation;
+    if (!o) {
+        const raw = await page.evaluate(extractPage, { nextRef: 1, limit: OBSERVE_LIMIT });
+        o = buildObservation(raw, { sessionId: m.sessionId, gen: m.gen, consoleErrors: 0, failedRequests: 0 });
+    }
+    const frame = await shot(page, m.frameFile('state'));
+    const ctx = { ...m.ctx, keepRefs: false, ...(frame ? { frame } : {}) };
+    const where = { route: o.route, viewport: o.viewport, gen: o.gen };
+    const fresh = [];
+    const note = (f, isNew, evidence = frame) => {
+        seen.add(f.id);
+        if (isNew)
+            fresh.push({ findings: [f], ...(evidence ? { frame: evidence } : {}) });
+    };
+    const record = (hit, extra = {}) => {
+        const r = m.store.recordHit(hit, where, m.reproduction, { ...ctx, ...extra });
+        note(r.finding, r.fresh, extra.frame ?? frame);
+        return r.finding;
+    };
+    // 1. The observation's layout flags (document overflow, controls past the viewport edge).
+    const flags = { ...o, layout: o.layout.filter((f) => on(f.kind)) };
+    for (const r of m.store.observationResults(flags, m.reproduction, ctx))
+        note(r.finding, r.fresh);
+    // 2. Layout detectors over one measurement of the state.
+    const raw = await page.evaluate(measureLayout, { maxElements: 2500, maxItems: 40 });
+    const hits = detectLayout(raw, m.detectors);
+    const hiddenLabels = new Set();
+    // A control a fixed layer covers is explained by fixed-collision; the reach check would repeat it.
+    const collided = new Set(hits.filter((h) => h.kind === 'fixed-collision' && h.confidence === 'confirmed' && h.target).map((h) => labelKey(h.target)));
+    for (const h of hits) {
+        record(h);
+        if (h.target && h.confidence === 'confirmed' && (h.kind === 'text-clipped' || h.kind === 'text-truncated' || h.kind === 'container-clipped'))
+            hiddenLabels.add(labelKey(h.target));
+    }
+    // 3. Layout shifts while the state settled (before any scrolling here, which the API ignores anyway).
+    if (m.shift && on('layout-shift')) {
+        const entries = await page.evaluate(takeLayoutShifts).catch(() => []);
+        for (const h of shiftHits(entries, m.detectors.layoutShiftMin, m.shift.when)) {
+            const frames = [
+                ...(m.shift.before ? [{ label: 'before it settled', path: m.shift.before }] : []),
+                ...(frame ? [{ label: 'after it settled', path: frame }] : []),
+            ];
+            record({ ...h, frames });
+        }
+    }
+    // 4. The reach check, as the click path does it: scroll the control into view, then on past a fixed
+    //    bar, and hit-test its centre. In an open dialog, a control whose centre never comes into view
+    //    cannot be reached at all.
+    let reachChecked = 0;
+    const unreachable = [];
+    const obstructed = new Set();
+    const frameTick = () => page.evaluate(() => new Promise((r) => requestAnimationFrame(() => r(null))));
+    for (const c of o.controls.slice(0, m.reachLimit)) {
+        if (c.disabled || c.rect.w < 4 || c.rect.h < 4)
+            continue;
+        const handle = (await page.evaluateHandle(lookupRef, c.ref)).asElement();
+        if (!handle)
+            continue;
+        try {
+            await page.evaluate(scrollToOrigin);
+            let { dx } = await handle.evaluate(panIntoView);
+            await frameTick();
+            let point = await handle.evaluate(targetPoint);
+            if ((!point.hitOk && point.hitFixed) || (!point.inView && o.dialog)) {
+                dx += (await handle.evaluate(centreInView)).dx;
+                await frameTick();
+                point = await handle.evaluate(targetPoint);
+            }
+            reachChecked++;
+            const steps = [...m.reproduction, `scroll ${c.role} "${c.name}" into view`];
+            if (dx && on('horizontal-pan-required')) {
+                const r = m.store.panResult(o, c, { role: c.role, name: c.name, ref: c.ref }, Math.abs(dx), steps, { ...ctx, source: 'sweep-reachability' });
+                note(r.finding, r.fresh);
+            }
+            if (point.inView && !point.hitOk && point.hit && on('control-obstructed') && !collided.has(labelKey(c))) {
+                obstructed.add(labelKey(c));
+                const r = m.store.obstructionResult(o, c, point.hit, steps, { ...ctx, source: 'sweep-reachability' });
+                // The moment of obstruction is the evidence: the control scrolled into view, still covered.
+                const evidence = r.fresh ? await shot(page, m.frameFile(r.finding.id)) : undefined;
+                if (evidence)
+                    r.finding.frame = evidence;
+                note(r.finding, r.fresh, evidence ?? frame);
+            }
+            if (!point.inView && o.dialog)
+                unreachable.push({ el: { role: c.role, name: c.name, selector: '', control: true }, box: { x: c.rect.x, y: c.rect.y, w: c.rect.w, h: c.rect.h } });
+        }
+        finally {
+            await handle.dispose().catch(() => undefined);
+        }
+    }
+    await page.evaluate(scrollToOrigin);
+    if (on('modal-overflow'))
+        for (const h of modalHits(raw.modal, unreachable, raw.viewport))
+            record(h);
+    // 5. Content that stays under a fixed bar at the top or bottom of the page (skipped while a modal
+    //    locks scrolling). A control the reach check already found covered is the same problem.
+    if (on('content-under-fixed') && !raw.modal) {
+        const covered = await page.evaluate(coveredAtExtremes, { maxItems: 20 });
+        const hitsUnder = coveredHits(covered).filter((h) => !(h.target && obstructed.has(labelKey(h.target))));
+        if (hitsUnder.length) {
+            await page.evaluate(() => window.scrollTo({ left: 0, top: (document.scrollingElement ?? document.documentElement).scrollHeight, behavior: 'instant' }));
+            const bottom = hitsUnder.some((h) => h.evidence.edge === 'bottom') ? await shot(page, m.frameFile('bottom')) : undefined;
+            await page.evaluate(scrollToOrigin);
+            for (const h of hitsUnder)
+                record(h, h.evidence.edge === 'bottom' && bottom ? { frame: bottom } : {});
+        }
+    }
+    for (const f of fresh)
+        m.onFindings?.(f.findings, f.frame);
+    return {
+        observation: o, ...(frame ? { frame } : {}), findings: [...seen], reachChecked,
+        labels: raw.labels, hiddenLabels, examined: raw.examined, omitted: raw.omitted,
+    };
+}
+/** Which checks run: `enable` limits them to those kinds, `disable` removes kinds. */
+export function checkFilter(...configs) {
+    return (kind) => configs.every((c) => !c || ((!c.enable?.length || c.enable.includes(kind)) && !(c.disable ?? []).includes(kind)));
+}
+export async function shot(page, file) {
+    try {
+        writeFileSync(file, await page.screenshot({ type: 'jpeg', quality: 70, scale: 'css', caret: 'initial', animations: 'allow', timeout: 5000 }));
+        return file;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=checks.js.map