@jevitate/cli 0.1.0 → 0.3.0

package/dist/ux-api.js

@@ -8,224 +8,7 @@
 // This is the ONLY place @jevitate/ux meets @jevitate/explore — the dep
 // direction stays ux ⟂ explore (both are consumed here, neither imports the
 // other). Findings are advisory; a UX finding never gates a run.
-import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { PlaywrightBrowserPort } from "@jevitate/playwright";
-import { CastActor, BrowseTheWeb } from "@jevitate/screenplay";
-import { explore, assertAuthorizedExploreTarget, } from "@jevitate/explore";
-import { UxAnalyzer, a11yChecks, buildReport, loadV1Rubric, } from "@jevitate/ux";
-import { resolveDataDir } from "./data-dir.js";
-const DEFAULT_JUDGMENT_BUDGET = 40;
-function emptyBehavior() {
-    return { noProgress: false, backtracks: 0, formReentry: 0, dwellMs: 0, errors: 0 };
-}
-/** explore's live `Control` → ux `Control` (same shape by design; drop `stability`). */
-function toUxControl(c) {
-    return {
-        index: c.index,
-        role: c.role,
-        name: c.name,
-        tag: c.tag,
-        inputType: c.inputType,
-        enabled: c.enabled,
-        summary: c.summary,
-        descriptor: c.descriptor,
-    };
-}
-/** a11y facts computable from a live snapshot's controls (honest subset). */
-function a11yFactsFromControls(controls) {
-    return {
-        controls: controls.map((c) => ({
-            controlRef: `control:${c.index}`,
-            accessibleName: c.name.trim().length > 0 ? c.name : null,
-            focusOrder: c.index,
-            targetSize: null,
-            contrastRatio: null,
-        })),
-    };
-}
-/** A live Snapshot (+ extracted page text) → one screen's UxEvidence. */
-export function snapshotToEvidence(snap, visibleText, appContext, job, history) {
-    const controls = snap.controls.map(toUxControl);
-    return {
-        screenId: snap.signature,
-        url: snap.url,
-        controls,
-        visibleText,
-        appContext,
-        ...(job !== undefined ? { job } : {}),
-        history,
-        behavior: emptyBehavior(),
-        a11yFacts: a11yFactsFromControls(controls),
-    };
-}
-function descriptorSummary(d) {
-    const parts = [d.role, d.name ?? d.testId ?? d.text].filter((s) => !!s);
-    return parts.join(" ") || "control";
-}
-function stepTarget(step) {
-    if ("target" in step && step.target)
-        return step.target;
-    return undefined;
-}
-/**
- * A saved Recording → per-page UxEvidence. A Recording is deterministic and
- * thin: it carries the CONTROLS the user touched (via each step's descriptor)
- * and the page url, but NOT the full visible text or a11y geometry. So offline
- * analysis is honestly partial — items needing `visibleText`/`a11yFacts` Skip,
- * and coverage reports it. (The live mode carries the rich per-screen snapshot.)
- */
-export function recordingToEvidence(recording, appContext, job) {
-    const screens = [];
-    const history = [];
-    for (let i = 0; i < recording.pages.length; i++) {
-        const page = recording.pages[i];
-        const controls = [];
-        let idx = 0;
-        const seen = new Set();
-        for (const rs of page.steps) {
-            const d = stepTarget(rs.step);
-            if (!d)
-                continue;
-            const key = JSON.stringify(d);
-            if (seen.has(key))
-                continue;
-            seen.add(key);
-            controls.push({
-                index: idx++,
-                role: d.role ?? "",
-                name: d.name ?? d.testId ?? d.text ?? "",
-                tag: "",
-                inputType: null,
-                enabled: true,
-                summary: descriptorSummary(d),
-                descriptor: d,
-            });
-        }
-        const screenId = `${page.url}#${i}`;
-        screens.push({
-            screenId,
-            url: page.url,
-            controls,
-            visibleText: "",
-            appContext,
-            ...(job !== undefined ? { job } : {}),
-            history: [...history],
-            behavior: emptyBehavior(),
-            a11yFacts: { controls: [] },
-        });
-        history.push({ screenId, url: page.url });
-    }
-    return screens;
-}
-/**
- * Offline UX review. FAIL-FAST: an analyzer `failed` outcome throws
- * `UxAnalysisFailedError` (the CLI maps it to a non-zero fail envelope) — never
- * a fabricated "clean" report.
- */
-export async function runUxReview(opts) {
-    const analyzer = new UxAnalyzer({ judge: opts.judge, a11yChecker: a11yChecks });
-    const screens = recordingToEvidence(opts.recording, opts.appContext, opts.appContext.job);
-    const outcome = await analyzer.analyze({
-        screens,
-        rubric: loadV1Rubric(),
-        appContext: opts.appContext,
-        secrets: opts.secrets,
-        judgmentBudget: opts.judgmentBudget ?? DEFAULT_JUDGMENT_BUDGET,
-    });
-    if (outcome.kind === "failed") {
-        throw new UxAnalysisFailedError(outcome.reason, outcome.screenId, outcome.rubricItemId);
-    }
-    const report = buildReport(outcome);
-    const outDir = opts.outDir ?? resolveDataDir(["ux-reports"]);
-    await mkdir(outDir, { recursive: true });
-    const iso = (opts.nowIso ?? (() => new Date().toISOString()))();
-    const reportPath = join(outDir, `ux-${iso.replace(/[:.]/g, "-")}.json`);
-    await writeFile(reportPath, `${JSON.stringify(report, null, 2)}\n`, "utf8");
-    return { report, reportPath };
-}
-export class UxAnalysisFailedError extends Error {
-    screenId;
-    rubricItemId;
-    code = "E_UX_ANALYSIS";
-    constructor(reason, screenId, rubricItemId) {
-        super(`UX analysis failed: ${reason}${screenId ? ` (screen ${screenId})` : ""}`);
-        this.screenId = screenId;
-        this.rubricItemId = rubricItemId;
-        this.name = "UxAnalysisFailedError";
-    }
-}
-/**
- * Live usability mission. Guardrail #1 authorizes BEFORE opening a browser.
- * Reuses explore()'s loop (goal = the job) and, via the additive onSnapshot
- * hook, collects one screen's evidence per observation — then analyzes ONCE
- * after the run. A UX finding NEVER gates the loop (the hook's result is
- * ignored by explore). The temp profile dir is always removed.
- */
-export async function runUsabilityMission(opts) {
-    const origin = assertAuthorizedExploreTarget(opts.url, opts.allowlist);
-    const portFactory = opts.browserPortFactory ?? (() => new PlaywrightBrowserPort());
-    const port = portFactory();
-    const profileDir = await mkdtemp(join(tmpdir(), "jevitate-usability-"));
-    const session = await port.open({
-        profileDir,
-        headless: true,
-        allowedOrigins: [...opts.allowlist],
-        baseUrl: origin,
-    });
-    const collected = [];
-    const history = [];
-    const extract = opts.extractText ??
-        (async (s) => s.page.evaluate(() => (typeof document !== "undefined" && document.body ? document.body.innerText : "")));
-    try {
-        const actor = CastActor.named("usability-mission").whoCan(new BrowseTheWeb(session, [...opts.allowlist]));
-        const run = await explore({
-            actor,
-            judge: opts.judge,
-            gen: opts.gen,
-            goal: opts.job,
-            allowlist: opts.allowlist,
-            startUrl: opts.url,
-            bounds: opts.bounds,
-            secrets: opts.secrets,
-            site: origin,
-            missionContext: "usability review: pursue the stated job as a plausible first-time user, using only what is on screen",
-            onSnapshot: async (snap) => {
-                let visibleText = "";
-                try {
-                    visibleText = await extract(session);
-                }
-                catch {
-                    visibleText = ""; // best-effort; the analyzer Skips visibleText items honestly
-                }
-                const ev = snapshotToEvidence(snap, visibleText, opts.appContext, opts.job, [...history]);
-                collected.push(ev);
-                history.push({ screenId: ev.screenId, url: ev.url });
-            },
-        });
-        const analyzer = new UxAnalyzer({ judge: opts.judge, a11yChecker: a11yChecks });
-        const outcome = await analyzer.analyze({
-            screens: collected,
-            rubric: loadV1Rubric(),
-            appContext: opts.appContext,
-            secrets: opts.secrets,
-            judgmentBudget: opts.judgmentBudget ?? DEFAULT_JUDGMENT_BUDGET,
-        });
-        if (outcome.kind === "failed") {
-            throw new UxAnalysisFailedError(outcome.reason, outcome.screenId, outcome.rubricItemId);
-        }
-        const report = buildReport(outcome);
-        const outDir = opts.outDir ?? resolveDataDir(["ux-reports"]);
-        await mkdir(outDir, { recursive: true });
-        const iso = (opts.nowIso ?? (() => new Date().toISOString()))();
-        const reportPath = join(outDir, `usability-${iso.replace(/[:.]/g, "-")}.json`);
-        await writeFile(reportPath, `${JSON.stringify(report, null, 2)}\n`, "utf8");
-        return { report, reportPath, stop: run.stop, screensObserved: collected.length };
-    }
-    finally {
-        await session.close();
-        await rm(profileDir, { recursive: true, force: true });
-    }
-}
+export { UsabilityInvariantsUnsupportedError, runUsabilityMission } from "./ux-usability.js";
+export { UxAnalysisFailedError, discoverRecordingSidecars, loadRecordingSidecars, runUxReview } from "./ux-review.js";
+export { captureFromTranscript, extractTypedValues, recordingToEvidence, snapshotToEvidence } from "./ux-evidence.js";
 //# sourceMappingURL=ux-api.js.map

package/dist/ux-api.js.map

@@ -1 +1 @@
-{"version":3,"file":"ux-api.js","sourceRoot":"","sources":["../src/ux-api.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAC7D,8EAA8E;AAC9E,iEAAiE;AACjE,yEAAyE;AACzE,2EAA2E;AAC3E,+EAA+E;AAC/E,EAAE;AACF,wEAAwE;AACxE,4EAA4E;AAC5E,iEAAiE;AACjE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACjE,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,qBAAqB,EAAoB,MAAM,sBAAsB,CAAC;AAC/E,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAE/D,OAAO,EACL,OAAO,EACP,6BAA6B,GAI9B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,UAAU,EACV,UAAU,EACV,WAAW,EACX,YAAY,GAMb,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C,MAAM,uBAAuB,GAAG,EAAE,CAAC;AAEnC,SAAS,aAAa;IACpB,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAW,CAAC;AAC9F,CAAC;AAED,wFAAwF;AACxF,SAAS,WAAW,CAAC,CAAiB;IACpC,OAAO;QACL,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,GAAG,EAAE,CAAC,CAAC,GAAG;QACV,SAAS,EAAE,CAAC,CAAC,SAAS;QACtB,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,UAAU,EAAE,CAAC,CAAC,UAAU;KACzB,CAAC;AACJ,CAAC;AAED,6EAA6E;AAC7E,SAAS,qBAAqB,CAAC,QAA8B;IAC3D,OAAO;QACL,QAAQ,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAC7B,UAAU,EAAE,WAAW,CAAC,CAAC,KAAK,EAAE;YAChC,cAAc,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI;YACxD,UAAU,EAAE,CAAC,CAAC,KAAK;YACnB,UAAU,EAAE,IAAI;YAChB,aAAa,EAAE,IAAI;SACpB,CAAC,CAAC;KACJ,CAAC;AACJ,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,kBAAkB,CAChC,IAAc,EACd,WAAmB,EACnB,UAAsB,EACtB,GAAuB,EACvB,OAA6B;IAE7B,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAChD,OAAO;QACL,QAAQ,EAAE,IAAI,CAAC,SAAS;QACxB,GAAG,EAAE,IAAI,CAAC,GAAG;QACb,QAAQ;QACR,WAAW;QACX,UAAU;QACV,GAAG,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrC,OAAO;QACP,QAAQ,EAAE,aAAa,EAAE;QACzB,SAAS,EAAE,qBAAqB,CAAC,QAAQ,CAAC;KAC3C,CAAC;AACJ,CAAC;AAED,SAAS,iBAAiB,CAAC,CAAmB;IAC5C,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACrF,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,SAAS,CAAC;AACtC,CAAC;AAED,SAAS,UAAU,CAAC,IAAyD;IAC3E,IAAI,QAAQ,IAAI,IAAI,IAAI,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC,MAAM,CAAC;IACxD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,SAAoB,EAAE,UAAsB,EAAE,GAAY;IAC5F,MAAM,OAAO,GAAiB,EAAE,CAAC;IACjC,MAAM,OAAO,GAAgB,EAAE,CAAC;IAChC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAChD,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAChC,MAAM,QAAQ,GAAgB,EAAE,CAAC;QACjC,IAAI,GAAG,GAAG,CAAC,CAAC;QACZ,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;QAC/B,KAAK,MAAM,EAAE,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YAC5B,MAAM,CAAC,GAAG,UAAU,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;YAC9B,IAAI,CAAC,CAAC;gBAAE,SAAS;YACjB,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;YAC9B,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,SAAS;YAC5B,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACd,QAAQ,CAAC,IAAI,CAAC;gBACZ,KAAK,EAAE,GAAG,EAAE;gBACZ,IAAI,EAAE,CAAC,CAAC,IAAI,IAAI,EAAE;gBAClB,IAAI,EAAE,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,IAAI,IAAI,EAAE;gBACxC,GAAG,EAAE,EAAE;gBACP,SAAS,EAAE,IAAI;gBACf,OAAO,EAAE,IAAI;gBACb,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC;gBAC7B,UAAU,EAAE,CAAC;aACd,CAAC,CAAC;QACL,CAAC;QACD,MAAM,QAAQ,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC;QACpC,OAAO,CAAC,IAAI,CAAC;YACX,QAAQ;YACR,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,QAAQ;YACR,WAAW,EAAE,EAAE;YACf,UAAU;YACV,GAAG,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACrC,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC;YACrB,QAAQ,EAAE,aAAa,EAAE;YACzB,SAAS,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE;SAC5B,CAAC,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAoBD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAwB;IACxD,MAAM,QAAQ,GAAG,IAAI,UAAU,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,CAAC,CAAC;IAChF,MAAM,OAAO,GAAG,mBAAmB,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IAC1F,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC;QACrC,OAAO;QACP,MAAM,EAAE,YAAY,EAAE;QACtB,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,cAAc,EAAE,IAAI,CAAC,cAAc,IAAI,uBAAuB;KAC/D,CAAC,CAAC;IACH,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,IAAI,qBAAqB,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;IAC1F,CAAC;IACD,MAAM,MAAM,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;IACpC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,cAAc,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC;IAC7D,MAAM,KAAK,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACzC,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC,EAAE,CAAC;IAChE,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;IACxE,MAAM,SAAS,CAAC,UAAU,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC5E,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;AAChC,CAAC;AAED,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAET;IAA4B;IADxD,IAAI,GAAG,eAAwB,CAAC;IACzC,YAAY,MAAc,EAAW,QAAiB,EAAW,YAAqB;QACpF,KAAK,CAAC,uBAAuB,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,YAAY,QAAQ,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAD9C,aAAQ,GAAR,QAAQ,CAAS;QAAW,iBAAY,GAAZ,YAAY,CAAS;QAEpF,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AA4BD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,IAAgC;IACxE,MAAM,MAAM,GAAG,6BAA6B,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IACvE,MAAM,WAAW,GAAG,IAAI,CAAC,kBAAkB,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,qBAAqB,EAAE,CAAC,CAAC;IACnF,MAAM,IAAI,GAAG,WAAW,EAAE,CAAC;IAC3B,MAAM,UAAU,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,qBAAqB,CAAC,CAAC,CAAC;IACxE,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC;QAC9B,UAAU;QACV,QAAQ,EAAE,IAAI;QACd,cAAc,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC;QACnC,OAAO,EAAE,MAAM;KAChB,CAAC,CAAC;IACH,MAAM,SAAS,GAAiB,EAAE,CAAC;IACnC,MAAM,OAAO,GAAgB,EAAE,CAAC;IAChC,MAAM,OAAO,GACX,IAAI,CAAC,WAAW;QAChB,CAAC,KAAK,EAAE,CAAgE,EAAE,EAAE,CAC1E,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC,OAAO,QAAQ,KAAK,WAAW,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC9G,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC,MAAM,CAAC,IAAI,YAAY,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;QAC1G,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC;YACxB,KAAK;YACL,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,IAAI,EAAE,IAAI,CAAC,GAAG;YACd,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,QAAQ,EAAE,IAAI,CAAC,GAAG;YAClB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,IAAI,EAAE,MAAM;YACZ,cAAc,EACZ,sGAAsG;YACxG,UAAU,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;gBACzB,IAAI,WAAW,GAAG,EAAE,CAAC;gBACrB,IAAI,CAAC;oBACH,WAAW,GAAG,MAAM,OAAO,CAAC,OAAgB,CAAC,CAAC;gBAChD,CAAC;gBAAC,MAAM,CAAC;oBACP,WAAW,GAAG,EAAE,CAAC,CAAC,6DAA6D;gBACjF,CAAC;gBACD,MAAM,EAAE,GAAG,kBAAkB,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;gBAC1F,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;gBACnB,OAAO,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;YACvD,CAAC;SACF,CAAC,CAAC;QAEH,MAAM,QAAQ,GAAG,IAAI,UAAU,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,CAAC,CAAC;QAChF,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC;YACrC,OAAO,EAAE,SAAS;YAClB,MAAM,EAAE,YAAY,EAAE;YACtB,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,cAAc,EAAE,IAAI,CAAC,cAAc,IAAI,uBAAuB;SAC/D,CAAC,CAAC;QACH,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC9B,MAAM,IAAI,qBAAqB,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;QAC1F,CAAC;QACD,MAAM,MAAM,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;QACpC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,cAAc,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC;QAC7D,MAAM,KAAK,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACzC,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC,EAAE,CAAC;QAChE,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,EAAE,aAAa,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;QAC/E,MAAM,SAAS,CAAC,UAAU,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC5E,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,eAAe,EAAE,SAAS,CAAC,MAAM,EAAE,CAAC;IACnF,CAAC;YAAS,CAAC;QACT,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC;QACtB,MAAM,EAAE,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACzD,CAAC;AACH,CAAC"}
+{"version":3,"file":"ux-api.js","sourceRoot":"","sources":["../src/ux-api.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAC7D,8EAA8E;AAC9E,iEAAiE;AACjE,yEAAyE;AACzE,2EAA2E;AAC3E,+EAA+E;AAC/E,EAAE;AACF,wEAAwE;AACxE,4EAA4E;AAC5E,iEAAiE;AACjE,OAAO,EAAmE,mCAAmC,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC9J,OAAO,EAAgG,qBAAqB,EAAE,yBAAyB,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AACpN,OAAO,EAAmC,qBAAqB,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/ux-claim-probe.d.ts

@@ -0,0 +1,45 @@
+import type { Page } from "playwright";
+import { type SafetyConfig } from "@jevitate/explore";
+import { type Control, type GuardProbe, type UxEvidence, type UxFinding } from "@jevitate/ux";
+/** At most this many controls are probed per run; the rest are recorded as not probed (unverifiable). */
+export declare const MAX_GUARD_PROBES = 25;
+/** Why nothing was clicked without the opt-in. */
+export declare const PROBE_OPT_IN_REASON = "not probed: clicking destructive controls is opt-in (--probe-guards)";
+/** The fail-safe destructive-request classifier, shared with the find-out guard (#270): one vocabulary. */
+export declare function looksDestructive(url: string, body?: string | null, method?: string): boolean;
+export interface ProbeTarget {
+    readonly screen: UxEvidence;
+    readonly control: Control;
+    /** Redacted `role "name"`. */
+    readonly label: string;
+    /** controlKey over the REDACTED role/name (what the claim pipeline matches on). */
+    readonly key: string;
+    readonly route: string;
+}
+/** The destructive controls to probe (one per route × control) and the ones a `--deny` pattern refuses. */
+export declare function planGuardProbes(screens: readonly UxEvidence[], secrets: readonly string[], safety?: SafetyConfig): {
+    readonly targets: ProbeTarget[];
+    readonly refused: GuardProbe[];
+};
+/** The opt-out record: every planned target is `skipped` (its guard claim: unverifiable). */
+export declare function skippedProbes(targets: readonly ProbeTarget[]): GuardProbe[];
+/**
+ * Probes each target, each on a fresh page in `runPage`'s context (call only with the opt-in).
+ * Never throws per target; a target that cannot be probed safely is `refused`/`failed`.
+ */
+export declare function runGuardProbes(runPage: Page, targets: readonly ProbeTarget[], opts: {
+    readonly allowlist: readonly string[];
+    readonly secrets: readonly string[];
+}): Promise<GuardProbe[]>;
+/**
+ * Cropped, masked, boxed screenshots for the verified claim findings (`finding.screenshot`). Best
+ * effort per finding: one that cannot be located or masked has none. Fails CLOSED on masking: if
+ * the pixel mask cannot be installed or proven, no screenshot is written.
+ */
+export declare function captureFindingShots(page: Page, findings: readonly UxFinding[], screens: ReadonlyMap<string, UxEvidence>, opts: {
+    readonly dir: string;
+    readonly allowlist: readonly string[];
+    readonly secrets: readonly string[];
+}): Promise<UxFinding[]>;
+/** Opens the dedicated probe page in the run's context; closing it deletes its video, if any. */
+export declare function withProbePage<T>(runPage: Page, fn: (page: Page) => Promise<T>): Promise<T>;