agent-device-lab 0.0.0-stage → 0.3.1

package/dist/core/feed.js

@@ -0,0 +1,493 @@
+import { formatChanges, formatClose, formatControlChange, formatHuman, formatSettle } from './format.js';
+import { basename } from 'node:path';
+const DEFAULT_LIMITS = { buffer: 1000, timeline: 200, serverLog: 200, countsIntervalMs: 250 };
+const SECRET = /\b([A-Za-z0-9_.-]*(?:secret|token|passw(?:or)?d|api[_-]?key|auth(?:orization)?|cookie|session[_-]?id|private[_-]?key)[A-Za-z0-9_.-]*)(\s*[=:]\s*|\s+)("[^"]*"|'[^']*'|[^\s,;&]+)/gi;
+const BEARER = /\b(bearer|basic)\s+[A-Za-z0-9._~+/=-]{8,}/gi;
+const URL_CREDENTIALS = /(\b[a-z][a-z0-9+.-]*:\/\/)[^\s/@:]+:[^\s/@]+@/gi;
+/** What an action was asked to do beyond its target. Secret keys arrive already masked; files show names only. */
+function actionDetail(r) {
+    switch (r.action) {
+        case 'press': return `key ${r.key}`;
+        case 'select': return `→ ${(r.values ?? []).map((v) => JSON.stringify(v.slice(0, 40))).join(', ')}`;
+        case 'scroll': return r.direction ? `${r.direction}${r.amount ? ` ${r.amount}px` : ''}` : 'into view';
+        case 'swipe': return `${r.direction}${r.amount ? ` ${r.amount}px` : ''}`;
+        case 'upload': return `files ${(r.files ?? []).map((f) => basename(f)).join(', ')}`;
+        case 'drag': return r.toRef ? `onto ${r.toRef}` : `by (${r.dx ?? 0}, ${r.dy ?? 0})`;
+        case 'open_tab': return `at ${r.path}`;
+        case 'switch_tab':
+        case 'close_tab': return r.tab ? `tab ${r.tab}` : '';
+        default: return '';
+    }
+}
+/** Mask things that look like credentials in free text (server output, commands). */
+export function redactSecrets(text) {
+    return text
+        .replace(URL_CREDENTIALS, '$1‹redacted›@')
+        .replace(BEARER, '$1 ‹redacted›')
+        .replace(SECRET, (_m, key, sep) => `${key}${sep}‹redacted›`);
+}
+/** origin + path: query strings and fragments are dropped because they often carry tokens. */
+export function displayUrl(url) {
+    try {
+        const u = new URL(url);
+        return u.origin + u.pathname;
+    }
+    catch {
+        return url.split(/[?#]/)[0] ?? url;
+    }
+}
+function errorText(e) {
+    return redactSecrets(`${e.code}: ${e.message}${e.hint ? ` Hint: ${e.hint}` : ''}`);
+}
+function stateView(s) {
+    const { frame, error, ...rest } = s;
+    return structuredClone({ ...rest, ...(error ? { error: errorText(error) } : {}), hasFrame: !!frame });
+}
+function redactError(e) {
+    const details = e.details ? { ...e.details } : undefined;
+    if (details && Array.isArray(details.logTail))
+        details.logTail = details.logTail.map((l) => redactSecrets(String(l)));
+    return { ...e, message: redactSecrets(e.message), ...(e.hint ? { hint: redactSecrets(e.hint) } : {}), ...(details ? { details } : {}) };
+}
+/**
+ * Show a typed value only when the page itself displays it back in the control (so it is already on
+ * screen); password fields read back as a mask. Otherwise report only its length.
+ */
+function fillValue(result, value) {
+    const shown = result.observation?.controls.find((c) => c.ref === result.ref)?.value;
+    if (shown !== undefined && shown === value)
+        return value.length > 60 ? `${value.slice(0, 57)}…` : value;
+    if (shown === '••••')
+        return '••••';
+    return `‹${value.length} chars›`;
+}
+export class SessionFeed {
+    limits;
+    seq = 0;
+    buffer = [];
+    status = SessionFeed.idle();
+    timeline = [];
+    findings = new Map();
+    frames = new Map();
+    serverLog = [];
+    sweeps = [];
+    sweepFrames = new Map();
+    scans = [];
+    scanFrames = new Map();
+    extraFrames = new Map();
+    listeners = new Set();
+    startingAt = 0;
+    countsTimer;
+    lastCountsAt = 0;
+    constructor(limits = {}) {
+        this.limits = { ...DEFAULT_LIMITS, ...limits };
+    }
+    static idle() {
+        return { state: 'idle', gen: 0, consoleErrors: 0, failedRequests: 0, findings: 0 };
+    }
+    /** Subscribe to live messages. Returns an unsubscribe function. */
+    subscribe(fn) {
+        this.listeners.add(fn);
+        return () => { this.listeners.delete(fn); };
+    }
+    get state() {
+        return this.status.state;
+    }
+    get lastSeq() {
+        return this.seq;
+    }
+    snapshot() {
+        return {
+            seq: this.seq,
+            status: structuredClone(this.status),
+            timeline: this.timeline.slice(-this.limits.timeline),
+            findings: [...this.findings.values()],
+            serverLog: [...this.serverLog],
+            sweeps: structuredClone(this.sweeps),
+            scans: structuredClone(this.scans),
+        };
+    }
+    /** Messages after `seq`, or undefined when they are no longer buffered (the client needs a snapshot). */
+    since(seq) {
+        if (seq === this.seq)
+            return [];
+        if (seq > this.seq)
+            return undefined;
+        const first = this.buffer[0];
+        if (!first || first.seq > seq + 1)
+            return undefined;
+        return this.buffer.filter((m) => m.seq > seq);
+    }
+    /** Viewport frame captured for one width of a sweep. */
+    sweepFrameFile(sweepId, device) {
+        return this.sweepFrames.get(`${sweepId}/${device}`);
+    }
+    /** State frame of a scan run (`runIndex` is the run's position in the plan). */
+    scanFrameFile(scanId, runIndex, stateId) {
+        return this.scanFrames.get(`${scanId}/${runIndex}/${stateId}`);
+    }
+    /** The i-th extra evidence frame of a finding (the other width, or before/after a shift). */
+    extraFrameFile(id, index) {
+        return this.extraFrames.get(`${id}-${index}`);
+    }
+    /** Evidence frame file for a finding id, if one was captured. */
+    frameFile(id) {
+        return this.frames.get(id);
+    }
+    apply(e) {
+        switch (e.kind) {
+            case 'starting': {
+                if (this.status.state !== 'idle')
+                    this.reset();
+                this.startingAt = Date.now();
+                this.status = {
+                    ...SessionFeed.idle(), state: 'starting', project: e.project, device: e.device, headed: e.headed,
+                    url: displayUrl(e.url), startedAt: new Date().toISOString(),
+                };
+                this.emitStatus();
+                break;
+            }
+            case 'service': {
+                const i = e.info;
+                const services = (this.status.services ??= []).filter((s) => s.name !== i.name);
+                services.push({ name: i.name, ...(i.url ? { url: i.url } : {}), owned: i.owned, ...(i.pid !== undefined ? { pid: i.pid } : {}), readyMs: i.readyMs, readiness: i.readiness });
+                this.status.services = services;
+                this.emitStatus();
+                break;
+            }
+            case 'auth': {
+                if (e.action === 'saved') {
+                    this.entry({ kind: 'auth', outcome: 'success', summary: `saved sign-in state (${e.cookies} cookies, ${e.origins} origins with storage)`, changes: [], notes: [], findings: [] });
+                }
+                else if (e.action === 'invalidated') {
+                    this.entry({ kind: 'auth', outcome: 'error', summary: 'saved sign-in state was unusable and has been removed', changes: [], notes: [], findings: [] });
+                }
+                break;
+            }
+            case 'start': {
+                const { session, server, observation: o } = e.result;
+                Object.assign(this.status, {
+                    state: 'active', sessionId: session.id, device: session.device, headed: session.browser.headed,
+                    browser: `Chromium ${session.browser.version}`, environment: session.environment, auth: session.auth ?? 'fresh',
+                    server: {
+                        url: server.url, owned: server.owned, readyMs: server.readyMs,
+                        ...(server.pid !== undefined ? { pid: server.pid } : {}),
+                        ...(server.command ? { command: redactSecrets(server.command) } : {}),
+                    },
+                });
+                this.observed(o);
+                this.emitStatus();
+                this.entry({
+                    kind: 'start', outcome: 'success', durationMs: this.startingAt ? Date.now() - this.startingAt : undefined,
+                    summary: `session ${session.id} on ${o.route}; server ${server.owned ? `started (pid ${server.pid}, ready in ${server.readyMs}ms)` : 'reused (not owned)'}`,
+                    changes: [], notes: [], findings: this.firstSeenIn(o.gen), route: o.route,
+                });
+                break;
+            }
+            case 'start-failed': {
+                const error = redactError(e.error);
+                if (this.status.state === 'idle')
+                    this.status = { ...SessionFeed.idle(), startedAt: new Date().toISOString() };
+                this.entry({
+                    kind: 'start-failed', outcome: 'error', durationMs: this.startingAt ? Date.now() - this.startingAt : undefined,
+                    summary: `start failed: ${error.code}`, changes: [], notes: [], findings: [],
+                    error: { code: error.code, message: error.message, ...(error.hint ? { hint: error.hint } : {}) },
+                });
+                Object.assign(this.status, { state: 'failed', startError: error, endedReason: 'start failed' });
+                this.emitStatus();
+                break;
+            }
+            case 'server-log': {
+                const line = redactSecrets(e.line).slice(0, 500);
+                this.serverLog.push(line);
+                if (this.serverLog.length > this.limits.serverLog)
+                    this.serverLog.splice(0, this.serverLog.length - this.limits.serverLog);
+                this.publish({ type: 'server-log', line });
+                break;
+            }
+            case 'observe': {
+                this.observed(e.observation);
+                this.emitStatus();
+                const o = e.observation;
+                this.entry({
+                    kind: 'observe', outcome: 'success', summary: `observe gen ${o.gen}: ${o.controls.length} controls${o.omitted ? ` (+${o.omitted} omitted)` : ''}, ${o.layout.length} layout flags`,
+                    changes: [], notes: [], findings: this.firstSeenIn(o.gen), route: o.route,
+                });
+                break;
+            }
+            case 'act': {
+                const r = e.result;
+                if (r.observation)
+                    this.observed(r.observation);
+                this.emitStatus();
+                const target = r.target ?? (r.ref ? { ref: r.ref } : undefined);
+                const detail = actionDetail(e.request);
+                const what = [r.target ? `${r.target.role} "${r.target.name}"` : r.ref, detail].filter(Boolean).join(' ');
+                if (r.observation)
+                    this.status.tab = r.observation.tab;
+                const changes = !r.changes ? []
+                    : r.changes.reset ? [`${r.changes.route ? `route ${r.changes.route.from} → ${r.changes.route.to}; ` : ''}new document, baseline reset`]
+                        : r.changes.none ? ['no visible change'] : formatChanges(r.changes).map((l) => l.replace(' (use --json for all)', ''));
+                this.entry({
+                    kind: r.action, ...(target ? { target } : {}), ...(detail ? { detail } : {}), outcome: r.outcome, durationMs: r.elapsedMs,
+                    ...(r.action === 'fill' && e.request.value !== undefined ? { value: fillValue(r, e.request.value) } : {}),
+                    summary: `${r.action}${r.ref ? ` ${r.ref}` : ''}${what ? ` ${what}` : ''}`, ...(r.method ? { method: r.method } : {}),
+                    ...(r.settle ? { settle: r.settle, ...(r.settle.reason === 'timeout' ? { settleText: formatSettle(r.settle) } : {}) } : {}),
+                    changes, notes: r.notes, findings: r.newFindings.map((f) => f.id),
+                    ...(r.error ? { error: { code: r.error.code, message: r.error.message, ...(r.error.hint ? { hint: r.error.hint } : {}) } } : {}),
+                    ...(r.observation ? { route: r.observation.route } : {}), navigated: r.navigated,
+                    newConsoleErrors: r.newConsoleErrors.length, newFailedRequests: r.newFailedRequests.length,
+                });
+                break;
+            }
+            case 'control': {
+                this.status.control = structuredClone(e.change.state);
+                this.emitStatus();
+                this.entry({ kind: 'control', outcome: 'success', summary: formatControlChange(e.change), changes: [], notes: [], findings: [] });
+                break;
+            }
+            case 'human': {
+                const a = e.action;
+                this.entry({
+                    kind: 'human', outcome: 'success', summary: a.type === 'input-dropped' ? `person: ${formatHuman(a)}` : `person ${formatHuman(a)}`,
+                    ...(a.target ? { target: { role: a.target.role, name: a.target.name } } : {}), changes: [], notes: [], findings: [],
+                });
+                break;
+            }
+            case 'refused': {
+                const error = redactError(e.error);
+                this.entry({
+                    kind: 'refused', outcome: 'error', summary: `agent's ${e.command} refused (${error.code}); nothing ran`, changes: [], notes: [], findings: [],
+                    error: { code: error.code, message: error.message, ...(error.hint ? { hint: error.hint } : {}) },
+                });
+                break;
+            }
+            case 'findings': {
+                for (const f of e.findings) {
+                    const main = e.frame ?? f.frame;
+                    if (main)
+                        this.frames.set(f.id, main);
+                    (f.frames ?? []).forEach((x, i) => this.extraFrames.set(`${f.id}-${i}`, x.path));
+                    const { frame: _frame, frames, ...rest } = structuredClone(f);
+                    const view = { ...rest, hasFrame: !!main, frames: (frames ?? []).map((x) => ({ label: x.label, ...(x.device ? { device: x.device } : {}) })) };
+                    this.findings.set(f.id, view);
+                    this.publish({ type: 'finding', finding: view });
+                }
+                this.status.findings = this.findings.size;
+                this.emitStatus();
+                break;
+            }
+            case 'page': {
+                this.status.url = displayUrl(e.url);
+                try {
+                    this.status.route = new URL(e.url).pathname;
+                }
+                catch { /* keep the last route */ }
+                this.emitStatus();
+                break;
+            }
+            case 'counts': {
+                this.status.consoleErrors = e.consoleErrors;
+                this.status.failedRequests = e.failedRequests;
+                this.emitCounts();
+                break;
+            }
+            case 'sweep': {
+                if (e.phase === 'start') {
+                    this.sweeps.push({ id: e.id, route: e.route, state: 'running', devices: e.devices.map((d) => ({ ...d, state: 'pending', findings: [], confirmed: 0, hasFrame: false })) });
+                    if (this.sweeps.length > 10)
+                        this.sweeps.shift();
+                }
+                const sweep = this.sweeps.find((s) => s.id === e.id);
+                if (!sweep)
+                    break;
+                if (e.phase === 'device-start') {
+                    const d = sweep.devices.find((x) => x.id === e.device);
+                    if (d)
+                        d.state = 'running';
+                }
+                else if (e.phase === 'device-done') {
+                    const r = e.result;
+                    const d = sweep.devices.find((x) => x.id === r.device);
+                    if (d) {
+                        Object.assign(d, {
+                            state: r.status === 'ok' ? 'done' : 'error', ms: r.ms, findings: r.findings, hasFrame: !!r.frame,
+                            confirmed: r.findings.filter((id) => this.findings.get(id)?.confidence === 'confirmed').length,
+                            ...(r.error ? { error: redactSecrets(r.error.message) } : {}),
+                        });
+                    }
+                    if (r.frame)
+                        this.sweepFrames.set(`${e.id}/${r.device}`, r.frame);
+                }
+                else if (e.phase === 'done') {
+                    sweep.state = 'done';
+                    sweep.ms = e.result.ms;
+                    const ids = e.result.findings.map((f) => f.id);
+                    const confirmed = e.result.findings.filter((f) => f.confidence === 'confirmed').length;
+                    this.entry({
+                        kind: 'sweep', outcome: e.result.devices.some((d) => d.status === 'error') ? 'error' : 'success', durationMs: e.result.ms,
+                        summary: `sweep ${e.id} of ${e.result.route} at ${e.result.devices.map((d) => d.width).join(', ')} px`,
+                        changes: e.result.devices.map((d) => `${d.device}: ${d.status === 'error' ? `error ${d.error?.code ?? ''}` : d.findings.length ? `${d.findings.length} finding(s)` : 'clean'}`),
+                        notes: ids.length ? [`${confirmed} confirmed, ${ids.length - confirmed} heuristic`] : [], findings: ids, route: e.result.route,
+                    });
+                }
+                this.publish({ type: 'sweep', sweep: structuredClone(sweep) });
+                break;
+            }
+            case 'scan': {
+                this.applyScan(e);
+                break;
+            }
+            case 'closed': {
+                if (this.status.state === 'failed')
+                    break; // start failure already reported, with its cause
+                // The entry goes first: viewers stop listening once they see the final status.
+                this.entry({ kind: 'stop', outcome: 'success', summary: formatClose(e.result), changes: [], notes: [], findings: [] });
+                if (this.status.state === 'starting')
+                    break; // cleanup after a failed start; start-failed follows with the cause
+                Object.assign(this.status, { state: 'ended', endedReason: e.result.reason });
+                this.emitStatus();
+                break;
+            }
+        }
+    }
+    applyScan(e) {
+        if (e.phase === 'start') {
+            this.scans.push({
+                id: e.id, state: 'running', explore: e.explore,
+                runs: e.runs.map((r, index) => ({ index, ...r, state: 'pending', states: [], decisions: [], decisionsOmitted: 0, limits: [], findings: [] })),
+            });
+            while (this.scans.length > 5) {
+                const old = this.scans.shift();
+                for (const key of [...this.scanFrames.keys()])
+                    if (key.startsWith(`${old.id}/`))
+                        this.scanFrames.delete(key);
+            }
+        }
+        const scan = this.scans.find((s) => s.id === e.id);
+        if (!scan)
+            return;
+        const find = (scenario, device, state) => scan.runs.find((r) => r.scenario === scenario && r.device === device && r.state === state)
+            ?? scan.runs.find((r) => r.scenario === scenario && r.device === device);
+        if (e.phase === 'run-start') {
+            const run = find(e.scenario, e.device, 'pending');
+            if (run)
+                run.state = 'running';
+            scan.current = { scenario: e.scenario, device: e.device };
+        }
+        else if (e.phase === 'state') {
+            const run = find(e.scenario, e.device, 'running');
+            if (run) {
+                const view = stateView(e.state);
+                const i = run.states.findIndex((s) => s.id === view.id);
+                if (i >= 0)
+                    run.states[i] = view;
+                else
+                    run.states.push(view);
+                if (e.state.frame)
+                    this.scanFrames.set(`${scan.id}/${run.index}/${e.state.id}`, e.state.frame);
+            }
+            scan.current = { scenario: e.scenario, device: e.device, state: e.state.label };
+        }
+        else if (e.phase === 'run-done') {
+            const r = e.run;
+            const run = find(r.scenario, r.device, 'running');
+            if (run) {
+                Object.assign(run, {
+                    state: r.status === 'ok' ? 'ok' : 'failed', ms: r.ms, states: r.states.map(stateView), decisions: structuredClone(r.decisions),
+                    decisionsOmitted: r.decisionsOmitted, limits: [...r.limits], findings: [...r.findings],
+                    ...(r.failedAt ? { failedAt: r.failedAt } : {}), ...(r.error ? { error: errorText(r.error) } : {}),
+                });
+                for (const s of r.states)
+                    if (s.frame)
+                        this.scanFrames.set(`${scan.id}/${run.index}/${s.id}`, s.frame);
+            }
+            if (scan.current?.scenario === r.scenario && scan.current.device === r.device)
+                delete scan.current;
+        }
+        else if (e.phase === 'done') {
+            const r = e.result;
+            Object.assign(scan, { state: 'done', groups: structuredClone(r.groups), verdict: structuredClone(r.verdict), suppressions: structuredClone(r.suppressions), ms: r.ms });
+            delete scan.current;
+            // Suppression is decided when the scan finishes: tell viewers about findings that changed.
+            for (const f of r.findings) {
+                const known = this.findings.get(f.id);
+                if (!known || JSON.stringify(known.suppressed) === JSON.stringify(f.suppressed))
+                    continue;
+                const { suppressed: _old, ...rest } = known;
+                const view = { ...rest, ...(f.suppressed ? { suppressed: structuredClone(f.suppressed) } : {}) };
+                this.findings.set(f.id, view);
+                this.publish({ type: 'finding', finding: view });
+            }
+            const failed = r.runs.filter((x) => x.status === 'failed');
+            this.entry({
+                kind: 'scan', outcome: r.verdict.result === 'pass' ? 'success' : 'error', durationMs: r.ms,
+                summary: `scan ${e.id}: ${r.verdict.result.toUpperCase()} · ${r.runs.length} runs (${failed.length} failed) · ${r.groups.length} problems`,
+                changes: failed.map((x) => `${x.scenario} @ ${x.device}: failed at ${x.failedAt ?? 'unknown'}`),
+                notes: [], findings: r.findings.map((f) => f.id),
+            });
+        }
+        this.publish({ type: 'scan', scan: structuredClone(scan) });
+    }
+    observed(o) {
+        Object.assign(this.status, {
+            gen: o.gen, url: displayUrl(o.url), route: o.route, title: o.title.slice(0, 120),
+            consoleErrors: o.console.errors, failedRequests: o.network.failed,
+        });
+    }
+    firstSeenIn(gen) {
+        return [...this.findings.values()].filter((f) => f.firstSeen.gen === gen).map((f) => f.id);
+    }
+    reset() {
+        this.buffer = [];
+        this.timeline = [];
+        this.findings.clear();
+        this.frames.clear();
+        this.serverLog = [];
+        this.sweeps = [];
+        this.sweepFrames.clear();
+        this.scans = [];
+        this.scanFrames.clear();
+        this.extraFrames.clear();
+        if (this.countsTimer)
+            clearTimeout(this.countsTimer);
+        this.countsTimer = undefined;
+        this.publish({ type: 'reset' });
+    }
+    entry(e) {
+        const entry = { seq: this.seq + 1, at: new Date().toISOString(), ...e };
+        this.timeline.push(entry);
+        if (this.timeline.length > this.limits.timeline)
+            this.timeline.splice(0, this.timeline.length - this.limits.timeline);
+        this.publish({ type: 'timeline', entry });
+    }
+    emitStatus() {
+        if (this.countsTimer) {
+            clearTimeout(this.countsTimer);
+            this.countsTimer = undefined;
+        }
+        this.lastCountsAt = Date.now();
+        this.publish({ type: 'status', status: structuredClone(this.status) });
+    }
+    /** Counters can change many times a second on a noisy page; publish at most once per interval. */
+    emitCounts() {
+        const wait = this.limits.countsIntervalMs - (Date.now() - this.lastCountsAt);
+        if (wait <= 0)
+            return this.emitStatus();
+        this.countsTimer ??= setTimeout(() => { this.countsTimer = undefined; this.emitStatus(); }, wait);
+        this.countsTimer.unref?.();
+    }
+    publish(event) {
+        const message = { seq: ++this.seq, at: new Date().toISOString(), event };
+        this.buffer.push(message);
+        if (this.buffer.length > this.limits.buffer)
+            this.buffer.splice(0, this.buffer.length - this.limits.buffer);
+        for (const fn of this.listeners) {
+            try {
+                fn(message);
+            }
+            catch { /* a viewer must never break the session */ }
+        }
+    }
+}
+//# sourceMappingURL=feed.js.map

package/dist/core/findings.js

@@ -0,0 +1,179 @@
+import { createHash } from 'node:crypto';
+import { DETECTORS } from './detectors.js';
+/** Basis that counts as a deterministic measurement: only these may make a heuristic high severity. */
+const DETERMINISTIC = new Set(['clipping', 'hit-test', 'interaction', 'standard', 'browser-metric']);
+/**
+ * The same underlying problem, stable across runs: the detector family (so a control covered at its
+ * centre is one problem whether the reach check or the fixed-bar check found it), the route without
+ * its fragment, and the element's identity. Device, scenario and state are left out so a problem seen
+ * at several widths or in several scenarios groups together.
+ */
+export function fingerprintOf(kind, route, target) {
+    const family = DETECTORS[kind].family;
+    const identity = target ? [target.role, target.name, target.context ?? ''].join('\u0000') : kind;
+    return createHash('sha1').update([family, route.split('#')[0], identity].join('\u0001')).digest('hex').slice(0, 12);
+}
+/** A session keeps at most this many distinct findings; later new ones are counted in `omitted`. */
+export const MAX_FINDINGS = 2000;
+/** Session-scoped finding store. Pure: no browser, so it is unit-tested directly. */
+export class FindingStore {
+    device;
+    max;
+    byKey = new Map();
+    next = 1;
+    omittedCount = 0;
+    constructor(device, max = MAX_FINDINGS) {
+        this.device = device;
+        this.max = max;
+    }
+    /** New findings that arrived after the cap and were counted, not kept. Findings already kept are never dropped. */
+    get omitted() {
+        return this.omittedCount;
+    }
+    list() {
+        return [...this.byKey.values()];
+    }
+    get(id) {
+        return this.list().find((f) => f.id === id);
+    }
+    get size() {
+        return this.byKey.size;
+    }
+    /** Record every layout flag in an observation (heuristic). Returns findings seen for the first time. */
+    recordObservation(o, reproduction, ctx = {}) {
+        return this.observationResults(o, reproduction, ctx).filter((r) => r.fresh).map((r) => r.finding);
+    }
+    /** Like recordObservation, but returns every finding the observation shows, new or already known. */
+    observationResults(o, reproduction, ctx = {}) {
+        const out = [];
+        for (const flag of o.layout) {
+            const control = flag.ref ? o.controls.find((c) => c.ref === flag.ref) : undefined;
+            const f = this.upsert({
+                kind: flag.kind, severity: flag.severity, source: 'measured-layout', confidence: 'heuristic',
+                confidenceScore: 0.6, basis: flag.kind === 'control-clipped' ? ['clipping'] : ['geometry'],
+                route: o.route, viewportWidth: o.viewport.width, target: control ? controlTarget(control) : undefined,
+                message: `${flag.message} on ${o.route}`, evidence: flag.evidence, gen: o.gen, reproduction,
+            }, ctx);
+            out.push(f);
+        }
+        return out;
+    }
+    /**
+     * Reaching a control needed the view to pan sideways (confirmed by measuring the pan). An automated
+     * click still succeeds, but a person would first have to discover the hidden horizontal pan.
+     */
+    recordHorizontalPan(o, control, target, panPx, reproduction, ctx = {}) {
+        const r = this.panResult(o, control, target, panPx, reproduction, ctx);
+        return r.fresh ? r.finding : undefined;
+    }
+    panResult(o, control, target, panPx, reproduction, ctx = {}) {
+        const width = control?.rect.w ?? 0;
+        const outsidePx = control?.clip?.px ?? panPx;
+        const entirelyOutside = width > 0 && outsidePx >= width;
+        return this.upsert({
+            kind: 'horizontal-pan-required', severity: entirelyOutside ? 'high' : 'medium', source: ctx.source ?? 'interaction', confidence: 'confirmed',
+            confidenceScore: 0.95, basis: ['interaction'],
+            route: o.route, viewportWidth: o.viewport.width, target: control ? controlTarget(control) : { ...target },
+            message: `${target.role} "${target.name}" on ${o.route} could only be reached after panning ${panPx}px sideways; ` +
+                `on a ${o.viewport.width}px-wide screen a person must first discover the horizontal pan`,
+            evidence: {
+                panPx, viewportWidth: o.viewport.width, documentWidth: o.documentWidth,
+                ...(control ? { targetLeft: control.rect.x, targetRight: control.rect.x + control.rect.w, targetWidth: control.rect.w } : {}),
+            },
+            gen: o.gen, reproduction,
+        }, ctx);
+    }
+    /**
+     * After scrolling a control into view, a pointer at its centre lands on another element (confirmed
+     * by hit-testing, the same check a click makes before tapping).
+     */
+    recordObstruction(o, control, hit, reproduction, ctx = {}) {
+        const r = this.obstructionResult(o, control, hit, reproduction, ctx);
+        return r.fresh ? r.finding : undefined;
+    }
+    obstructionResult(o, control, hit, reproduction, ctx = {}) {
+        return this.upsert({
+            kind: 'control-obstructed', severity: 'high', source: ctx.source ?? 'sweep-reachability', confidence: 'confirmed',
+            confidenceScore: 0.95, basis: ['hit-test'],
+            route: o.route, viewportWidth: o.viewport.width, target: controlTarget(control),
+            message: `${control.role} "${control.name}" on ${o.route} is covered at its centre by ${hit} even after scrolling it into view`,
+            evidence: { coveredBy: hit.slice(0, 80), viewportWidth: o.viewport.width, targetLeft: control.rect.x, targetTop: control.rect.y, targetWidth: control.rect.w, targetHeight: control.rect.h },
+            gen: o.gen, reproduction,
+        }, ctx);
+    }
+    /** A scan detector's result. Returns the finding (new or the existing one it merged into) and whether it is new. */
+    recordHit(hit, where, reproduction, ctx = {}) {
+        return this.upsert({
+            kind: hit.kind, severity: hit.severity, source: ctx.source ?? 'scan', confidence: hit.confidence, confidenceScore: hit.confidenceScore,
+            basis: hit.basis, route: where.route, viewportWidth: where.viewport.width, target: hit.target,
+            message: `${hit.message} on ${where.route}`, evidence: hit.evidence, gen: where.gen, reproduction, frames: hit.frames,
+        }, ctx);
+    }
+    /**
+     * Copy a finding recorded elsewhere (a scenario's own context, e.g. a sideways pan during a setup
+     * step) into this store under the given context.
+     */
+    adopt(f, reproduction, ctx) {
+        return this.upsert({
+            kind: f.kind, severity: f.severity, source: f.source, confidence: f.confidence, confidenceScore: f.confidenceScore, basis: f.basis,
+            route: f.route, viewportWidth: f.viewportWidth, target: f.target, message: f.message, evidence: f.evidence, gen: f.firstSeen.gen,
+            reproduction, frames: f.frames,
+        }, ctx);
+    }
+    /** Mark or clear a scan suppression on a finding (the finding itself is always kept and reported). */
+    suppress(id, s) {
+        const f = this.get(id);
+        if (!f)
+            return;
+        if (s)
+            f.suppressed = s;
+        else
+            delete f.suppressed;
+    }
+    upsert(input, ctx) {
+        const device = ctx.device ?? this.device;
+        const keepRef = ctx.keepRefs ?? !ctx.device;
+        // Refs change across documents, so identity is device + scenario + kind + route + the element's
+        // role, name and context. The UI state is not part of it: the same problem seen in several states
+        // of one scenario is one finding, which lists every state.
+        const key = [device, ctx.scenario ?? '', input.kind, input.route, input.target?.role ?? '', input.target?.name ?? '', input.target?.context ?? ''].join('\u0000');
+        const { ref, ...rest } = input.target ?? { role: '', name: '' };
+        const target = input.target ? { ...rest, ...(keepRef && ref ? { ref } : {}) } : undefined;
+        const existing = this.byKey.get(key);
+        if (existing) {
+            existing.lastSeenGen = input.gen;
+            existing.occurrences++;
+            if (target)
+                existing.target = target;
+            if (ctx.state && !existing.states?.includes(ctx.state))
+                (existing.states ??= []).push(ctx.state);
+            return { finding: existing, fresh: false };
+        }
+        // A heuristic stays below high severity unless a deterministic measurement backs it.
+        const severity = input.confidence === 'heuristic' && input.severity === 'high' && !input.basis.some((b) => DETERMINISTIC.has(b)) ? 'medium' : input.severity;
+        const finding = {
+            id: `F${this.next++}`, kind: input.kind, detector: { name: input.kind, version: DETECTORS[input.kind].version },
+            severity, source: input.source, confidence: input.confidence, confidenceScore: input.confidenceScore, basis: [...input.basis],
+            route: input.route, device, viewportWidth: input.viewportWidth,
+            ...(ctx.scenario ? { scenario: ctx.scenario } : {}),
+            ...(ctx.state ? { state: ctx.state, states: [ctx.state] } : {}),
+            ...(target ? { target } : {}),
+            message: input.message, evidence: { ...input.evidence },
+            fingerprint: fingerprintOf(input.kind, input.route, target),
+            ...(ctx.frame ? { frame: ctx.frame } : {}),
+            ...(input.frames?.length ? { frames: input.frames.map((f) => ({ ...f })) } : {}),
+            firstSeen: { gen: input.gen, at: new Date().toISOString() }, lastSeenGen: input.gen, occurrences: 1,
+            reproduction: [...input.reproduction],
+        };
+        if (this.byKey.size >= this.max) {
+            this.omittedCount++;
+            return { finding, fresh: false };
+        }
+        this.byKey.set(key, finding);
+        return { finding, fresh: true };
+    }
+}
+function controlTarget(c) {
+    return { role: c.role, name: c.name, ...(c.ref ? { ref: c.ref } : {}), ...(c.context ? { context: c.context } : {}) };
+}
+//# sourceMappingURL=findings.js.map