@jevitate/cli 0.1.0 → 0.2.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-cli.d.ts

@@ -0,0 +1,4 @@
+import { Command } from "commander";
+import { type CliDeps } from "./cli-shared.js";
+/** Registers `jevitate ux <recording>`. */
+export declare function registerUxCommands(program: Command, deps: CliDeps): void;

package/dist/ux-cli.js

@@ -0,0 +1,102 @@
+import { readFile } from "node:fs/promises";
+import { RecordingSchema } from "@jevitate/recording";
+import { MissingCredentialError } from "@jevitate/ai-core";
+import { ok, fail } from "./envelope.js";
+import { withEngine } from "./engine.js";
+import { discoverRecordingSidecars, loadRecordingSidecars, runUxReview, UxAnalysisFailedError } from "./ux-api.js";
+import { UxConfigError } from "./ux-config.js";
+import { MinConfidenceError, QualityPolicyError, MaxFindingsPerRouteError } from "@jevitate/ux";
+import { emitJson, GatewaySelectionError, buildExploreGateways } from "./cli-shared.js";
+/** Registers `jevitate ux <recording>`. */
+export function registerUxCommands(program, deps) {
+    // Additive: `jevitate ux <recording>` (issue #30) — offline UX review of a
+    // saved Recording. Findings are advisory; a `failed` analysis is a non-zero
+    // fail envelope (never a fabricated clean report).
+    program
+        .command("ux <recording>")
+        .description("offline UX review of a saved Recording — ranked, cited usability findings")
+        .option("--app-class <class>", "app class for calibration (required), e.g. consumer|admin|internal")
+        .option("--show <labels>", "opt-in filter on the quality grade (comma list of actionable,relevant-minor,generic,wrong); others are suppressed and counted; default JEVITATE_UX_SHOW, then ~/.jevitate/config.json ux.show, then ALL grades — the grader is uncalibrated (#133), so by default every finding is shown with its grade")
+        .option("--min-confidence <n>", "findings below this FINDING confidence (0..1, a finding's own violation/applicability/grounding score — NOT its quality-grade confidence, a separate independent-grader number shown as finding.quality.confidence) are suppressed and counted in report.suppressed; default JEVITATE_UX_MIN_CONFIDENCE, then ~/.jevitate/config.json ux.minConfidence, then 0.3")
+        .option("--max-findings-per-page <n>", "cap on UX findings per route/page, highest-confidence first; the rest are counted in report.suppressed as per-page-cap, never dropped silently; default JEVITATE_UX_MAX_FINDINGS_PER_PAGE, then ~/.jevitate/config.json ux.maxFindingsPerPage, then 5")
+        .option("--persona <p>", "optional persona for calibration")
+        .option("--job <text>", "the job the flow pursues (improves relevance)")
+        .option("--out <dir>", "directory to write the UX report")
+        .option("--result <file>", "mission result JSON (as written alongside the Recording by `jevitate explore`) — supplies blocked/disabled-target evidence the Recording alone cannot carry; default: <stem>.result.json, else <stem>.transcript.json, next to the Recording")
+        .option("--evidence <file>", "a live usability run's evidence sidecar (screens as analyzed + run signals); default: <stem>.evidence.json next to the Recording — with it, offline review reproduces the live run's findings")
+        .option("--real", "use live Jev gateways (requires keys)", false)
+        .option("--fake-ai", "use deterministic fake gateways", false)
+        .option("--json", "emit a JSON envelope")
+        .action(async function (recordingPath) {
+        const o = this.opts();
+        if (!o.appClass) {
+            emitJson(program, fail("E_UX_ARGS", "--app-class is required"));
+            return;
+        }
+        let recording;
+        try {
+            recording = RecordingSchema.parse(JSON.parse(await readFile(recordingPath, "utf8")));
+        }
+        catch (err) {
+            // #218: an unreadable or invalid Recording is unusable input — a usage error (64).
+            emitJson(program, fail("E_UX_INPUT", String(err instanceof Error ? err.message : err)));
+            return;
+        }
+        // #85 item 2 / #134: the artifacts next to the Recording — the live usability run's evidence
+        // sidecar, the mission result or transcript — are discovered automatically (explicit flags
+        // win). Absent or unreadable, the report says so (`report.evidenceCaveats`) rather than
+        // silently seeing less.
+        const found = discoverRecordingSidecars(recordingPath);
+        const sidecars = await loadRecordingSidecars({
+            ...((o.evidence ?? found.evidencePath) === undefined ? {} : { evidencePath: o.evidence ?? found.evidencePath }),
+            ...((o.result ?? found.resultPath) === undefined ? {} : { resultPath: o.result ?? found.resultPath }),
+            ...(o.result === undefined && found.transcriptPath !== undefined ? { transcriptPath: found.transcriptPath } : {}),
+        });
+        let uxJudge;
+        let uxGen;
+        let uxUsage;
+        try {
+            ({ judge: uxJudge, gen: uxGen, usage: uxUsage } = await buildExploreGateways(deps, { real: o.real ?? false, fakeAi: o.fakeAi ?? false }));
+        }
+        catch (err) {
+            if (err instanceof MissingCredentialError || err instanceof GatewaySelectionError) {
+                emitJson(program, fail("E_AI_SETUP_REQUIRED", err.message));
+            }
+            else {
+                emitJson(program, fail("E_UX_SETUP", String(err instanceof Error ? err.message : err)));
+            }
+            return;
+        }
+        try {
+            const result = await runUxReview({
+                recording,
+                appContext: {
+                    appClass: o.appClass,
+                    ...(o.persona ? { persona: o.persona } : {}),
+                    ...(o.job ? { job: o.job } : {}),
+                },
+                judge: uxJudge,
+                gen: uxGen,
+                usage: uxUsage,
+                ...(o.minConfidence !== undefined ? { minConfidence: o.minConfidence } : {}),
+                ...(o.show !== undefined ? { show: o.show } : {}),
+                ...(o.maxFindingsPerPage !== undefined ? { maxFindingsPerRoute: o.maxFindingsPerPage } : {}),
+                outDir: o.out,
+                ...sidecars,
+            });
+            emitJson(program, ok(withEngine({ ...result, sidecars: found })));
+        }
+        catch (err) {
+            if (err instanceof UxAnalysisFailedError) {
+                emitJson(program, fail("E_UX_ANALYSIS", err.message));
+            }
+            else if (err instanceof MinConfidenceError || err instanceof QualityPolicyError || err instanceof MaxFindingsPerRouteError || err instanceof UxConfigError) {
+                emitJson(program, fail("E_UX_ARGS", err.message));
+            }
+            else {
+                emitJson(program, fail("E_UX_RUN", String(err instanceof Error ? err.message : err)));
+            }
+        }
+    });
+}
+//# sourceMappingURL=ux-cli.js.map

package/dist/ux-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ux-cli.js","sourceRoot":"","sources":["../src/ux-cli.ts"],"names":[],"mappings":"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"}

package/dist/ux-config.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The UX-review slice of `~/.jevitate/config.json`:
+ *
+ * ```json
+ * { "ux": { "minConfidence": 0.75, "show": ["actionable", "relevant-minor"] } }
+ * ```
+ *
+ * A missing file (or missing key) is "not configured"; a malformed file or a non-numeric value
+ * fails closed — it is never silently replaced by the default.
+ */
+export declare class UxConfigError extends Error {
+    readonly code: "E_UX_CONFIG";
+}
+export declare function loadUxMinConfidence(path?: string): number | undefined;
+/**
+ * `ux.minConfidenceByAppClass` — per-`--app-class` cutoff defaults (issue #97), e.g.:
+ * `{ "ux": { "minConfidenceByAppClass": { "consumer": 0.3, "admin": 0.5 } } }`. Looked up
+ * case-insensitively by `appClass`; falls through to `resolveMinConfidence`'s next precedence
+ * level (`DEFAULT_MIN_CONFIDENCE`) when `appClass` has no entry — today's behavior is unchanged
+ * where no app-class-specific data exists.
+ */
+export declare function loadUxMinConfidenceByAppClass(path?: string, appClass?: string): number | undefined;
+/** `ux.show` — the quality grades a UX report shows (validated by `resolveQualityPolicy`). */
+export declare function loadUxShow(path?: string): string[] | undefined;
+/**
+ * `ux.maxFindingsPerPage` — the per-route finding cap (issue #198 interim, 0.2.0; validated by
+ * `resolveMaxFindingsPerRoute`).
+ */
+export declare function loadUxMaxFindingsPerPage(path?: string): number | undefined;

package/dist/ux-config.js

@@ -0,0 +1,103 @@
+import { readFileSync } from "node:fs";
+import { resolveDataDir } from "./data-dir.js";
+/**
+ * The UX-review slice of `~/.jevitate/config.json`:
+ *
+ * ```json
+ * { "ux": { "minConfidence": 0.75, "show": ["actionable", "relevant-minor"] } }
+ * ```
+ *
+ * A missing file (or missing key) is "not configured"; a malformed file or a non-numeric value
+ * fails closed — it is never silently replaced by the default.
+ */
+export class UxConfigError extends Error {
+    code = "E_UX_CONFIG";
+}
+/** The parsed `ux` object of the config file (undefined when the file or key is absent). */
+function loadUxSection(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (e) {
+        if (typeof e === "object" && e !== null && "code" in e && e.code === "ENOENT")
+            return undefined;
+        throw new UxConfigError(`cannot read ${path}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new UxConfigError(`${path} is not valid JSON`);
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new UxConfigError(`${path} must be a JSON object`);
+    }
+    const ux = parsed.ux;
+    if (ux === undefined)
+        return undefined;
+    if (ux === null || typeof ux !== "object" || Array.isArray(ux))
+        throw new UxConfigError(`${path}: "ux" must be an object`);
+    return ux;
+}
+export function loadUxMinConfidence(path = resolveDataDir(["config.json"])) {
+    const v = loadUxSection(path)?.minConfidence;
+    if (v === undefined)
+        return undefined;
+    if (typeof v !== "number" || !Number.isFinite(v) || v < 0 || v > 1) {
+        throw new UxConfigError(`${path}: ux.minConfidence must be a number in [0,1]`);
+    }
+    return v;
+}
+/**
+ * `ux.minConfidenceByAppClass` — per-`--app-class` cutoff defaults (issue #97), e.g.:
+ * `{ "ux": { "minConfidenceByAppClass": { "consumer": 0.3, "admin": 0.5 } } }`. Looked up
+ * case-insensitively by `appClass`; falls through to `resolveMinConfidence`'s next precedence
+ * level (`DEFAULT_MIN_CONFIDENCE`) when `appClass` has no entry — today's behavior is unchanged
+ * where no app-class-specific data exists.
+ */
+export function loadUxMinConfidenceByAppClass(path = resolveDataDir(["config.json"]), appClass) {
+    if (!appClass)
+        return undefined;
+    const v = loadUxSection(path)?.minConfidenceByAppClass;
+    if (v === undefined)
+        return undefined;
+    if (v === null || typeof v !== "object" || Array.isArray(v)) {
+        throw new UxConfigError(`${path}: ux.minConfidenceByAppClass must be an object keyed by app class`);
+    }
+    const rec = v;
+    const wanted = appClass.trim().toLowerCase();
+    const key = Object.keys(rec).find((k) => k.trim().toLowerCase() === wanted);
+    if (key === undefined)
+        return undefined;
+    const n = rec[key];
+    if (typeof n !== "number" || !Number.isFinite(n) || n < 0 || n > 1) {
+        throw new UxConfigError(`${path}: ux.minConfidenceByAppClass.${key} must be a number in [0,1]`);
+    }
+    return n;
+}
+/** `ux.show` — the quality grades a UX report shows (validated by `resolveQualityPolicy`). */
+export function loadUxShow(path = resolveDataDir(["config.json"])) {
+    const v = loadUxSection(path)?.show;
+    if (v === undefined)
+        return undefined;
+    if (!Array.isArray(v) || !v.every((x) => typeof x === "string")) {
+        throw new UxConfigError(`${path}: ux.show must be an array of quality labels`);
+    }
+    return v;
+}
+/**
+ * `ux.maxFindingsPerPage` — the per-route finding cap (issue #198 interim, 0.2.0; validated by
+ * `resolveMaxFindingsPerRoute`).
+ */
+export function loadUxMaxFindingsPerPage(path = resolveDataDir(["config.json"])) {
+    const v = loadUxSection(path)?.maxFindingsPerPage;
+    if (v === undefined)
+        return undefined;
+    if (typeof v !== "number" || !Number.isInteger(v) || v < 1) {
+        throw new UxConfigError(`${path}: ux.maxFindingsPerPage must be a positive integer`);
+    }
+    return v;
+}
+//# sourceMappingURL=ux-config.js.map

package/dist/ux-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ux-config.js","sourceRoot":"","sources":["../src/ux-config.ts"],"names":[],"mappings":"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"}

package/dist/ux-evidence.d.ts

@@ -0,0 +1,54 @@
+import type { Recording, TargetDescriptor } from "@jevitate/recording";
+import { type Snapshot } from "@jevitate/explore";
+import { type AppContext, type RunSignalCapture, type ScreenRef, type UxEvidence } from "@jevitate/ux";
+export declare const DEFAULT_JUDGMENT_BUDGET = 40;
+/** A live Snapshot (+ extracted page text) → one screen's UxEvidence. */
+export declare function snapshotToEvidence(snap: Snapshot, visibleText: string, appContext: AppContext, job: string | undefined, history: readonly ScreenRef[]): UxEvidence;
+/**
+ * Values the run itself typed or selected — a Recording's own `fill`/`select` steps whose value
+ * was NOT redacted (a secret field's value is always `{redacted:true}` and never surfaces here).
+ * #85 item 1: feeds the vocabulary/jargon tier (nielsen-2) so a quote/label that is really the
+ * user's own content (e.g. a piece title echoed back onto a card) is not mistaken for app copy.
+ */
+export declare function extractTypedValues(recording: Recording): string[];
+/**
+ * The minimal shape of a mission transcript entry `recordingToEvidence` needs — duck-typed against
+ * `@jevitate/explore`'s `TranscriptEntry` (this file already imports plenty from there; kept
+ * separate so `recordingToEvidence` itself stays decoupled from the live explore-control shape).
+ */
+export interface MissionTranscriptEntryLike {
+    readonly step?: number;
+    readonly op?: string | null;
+    readonly target?: string | null;
+    readonly actOk: boolean;
+    readonly reason?: string;
+    readonly url: string;
+    readonly signature?: string;
+    readonly descriptor?: TargetDescriptor;
+    readonly value?: string;
+    readonly message?: string;
+    readonly reply?: {
+        readonly received?: boolean;
+        readonly text?: string;
+    };
+    readonly screenshot?: string;
+}
+/**
+ * #134: the run-signal capture a transcript ALONE supports (no visible text, no requests) — enough
+ * for the journey friction (retries, dead ends, waits, backtracks, abandoned fields) and repeated
+ * replies, NOT for the oracles that need requests or page text (they would misfire on the blanks).
+ */
+export declare function captureFromTranscript(transcript: readonly MissionTranscriptEntryLike[]): RunSignalCapture;
+/**
+ * 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.)
+ *
+ * `missionTranscript` (#85 item 2, optional) adds blocked/disabled-target controls the Recording
+ * itself cannot carry, on whichever screen(s) share the blocked action's url — the same evidence a
+ * live usability run gets from its snapshot. `typedValues` (every screen's own #85 item 1 input)
+ * is always derived from the Recording, with or without a transcript.
+ */
+export declare function recordingToEvidence(recording: Recording, appContext: AppContext, job?: string, missionTranscript?: readonly MissionTranscriptEntryLike[]): UxEvidence[];