@jevitate/cli 0.1.0 → 0.3.0

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[];

package/dist/ux-evidence.js

@@ -0,0 +1,197 @@
+export 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;
+}
+/**
+ * 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 function extractTypedValues(recording) {
+    const values = [];
+    for (const page of recording.pages) {
+        for (const rs of page.steps) {
+            const step = rs.step;
+            if ((step.kind === "fill" || step.kind === "select") && !("var" in step.value) && !step.value.redacted) {
+                values.push(step.value.value);
+            }
+        }
+    }
+    return [...new Set(values)];
+}
+/**
+ * #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 function captureFromTranscript(transcript) {
+    const steps = transcript.map((t, i) => ({
+        step: t.step ?? i + 1,
+        op: t.op ?? null,
+        target: t.target ?? null,
+        actOk: t.actOk,
+        url: t.url,
+        ...(t.descriptor === undefined ? {} : { descriptor: t.descriptor }),
+        ...(t.reason === undefined ? {} : { reason: t.reason }),
+        ...(t.value === undefined ? {} : { value: t.value }),
+        ...(t.message === undefined ? {} : { message: t.message }),
+        ...(t.reply?.text === undefined || t.reply.received === false ? {} : { reply: t.reply.text }),
+    }));
+    const screens = transcript.map((t, i) => ({
+        index: i,
+        step: t.step ?? i + 1,
+        at: 0,
+        url: t.url,
+        signature: t.signature ?? `step:${t.step ?? i + 1}`,
+        visibleText: "",
+        busy: false,
+        ...(t.screenshot === undefined ? {} : { screenshot: t.screenshot }),
+    }));
+    return { steps, requests: [], screens, endedAt: 0 };
+}
+const ACTIONABLE_OPS = new Set(["click", "type", "select"]);
+/**
+ * Blocked/disabled-target controls derived from a mission transcript (#85 item 2), grouped by the
+ * page url they were observed on. A failed action is never recorded as a Recording step (see #81:
+ * `RunRecorder` records only successful actions), so this is the only source that gives offline
+ * `jevitate ux` the same evidence a LIVE usability run sees for free via `Control.enabled` on its
+ * snapshot — e.g. a "Pay" button that stayed disabled.
+ */
+function blockedControlsByUrl(transcript, startIndex) {
+    const byUrl = new Map();
+    const seen = new Set();
+    let idx = startIndex;
+    for (const t of transcript) {
+        if (t.actOk || t.descriptor === undefined || !t.op || !ACTIONABLE_OPS.has(t.op))
+            continue;
+        const key = `${t.url}|${JSON.stringify(t.descriptor)}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const d = t.descriptor;
+        const list = byUrl.get(t.url) ?? [];
+        list.push({
+            index: idx++,
+            role: d.role ?? "",
+            name: d.name ?? d.testId ?? d.text ?? "",
+            tag: "",
+            inputType: null,
+            enabled: false,
+            summary: `${descriptorSummary(d)} (blocked: ${t.reason ?? "action did not succeed"})`,
+            descriptor: d,
+        });
+        byUrl.set(t.url, list);
+    }
+    return byUrl;
+}
+/**
+ * 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 function recordingToEvidence(recording, appContext, job, missionTranscript) {
+    const screens = [];
+    const history = [];
+    const typedValues = extractTypedValues(recording);
+    const blockedByUrl = blockedControlsByUrl(missionTranscript ?? [], recording.pages.reduce((n, p) => n + p.steps.length, 0) + 1000);
+    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,
+            });
+        }
+        for (const blocked of blockedByUrl.get(page.url) ?? [])
+            controls.push(blocked);
+        const screenId = `${page.url}#${i}`;
+        screens.push({
+            screenId,
+            url: page.url,
+            controls,
+            visibleText: "",
+            appContext,
+            ...(job !== undefined ? { job } : {}),
+            history: [...history],
+            behavior: emptyBehavior(),
+            a11yFacts: { controls: [] },
+            ...(typedValues.length > 0 ? { typedValues } : {}),
+        });
+        history.push({ screenId, url: page.url });
+    }
+    return screens;
+}
+//# sourceMappingURL=ux-evidence.js.map

package/dist/ux-evidence.js.map

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

package/dist/ux-product.d.ts

@@ -0,0 +1,14 @@
+import { type ProductFacts } from "@jevitate/ux";
+import { type LayoutDeps } from "./project-dir.js";
+export declare const PRODUCT_FACTS_FILE = "product.json";
+export interface LoadedProductFacts {
+    readonly facts?: ProductFacts;
+    /** The file read, when one was. */
+    readonly path?: string;
+}
+/** The facts file to read: the flag, else `<project>/.jevitate/product.json` when present. */
+export declare function productFactsPath(flag: string | undefined, deps?: LayoutDeps): string | undefined;
+/** Reads and validates the product facts. Throws `ProductFactsError` for a missing/invalid file. */
+export declare function loadProductFacts(flag: string | undefined, deps?: LayoutDeps): Promise<LoadedProductFacts>;
+/** The report caveat when no facts were available (prices and intended next steps went unchecked). */
+export declare const NO_PRODUCT_FACTS_CAVEAT = "no product facts (.jevitate/product.json or --product): prices, trial lengths and each page's intended next step were not checked against the product's own facts (docs/ux-findings.md).";

package/dist/ux-product.js

@@ -0,0 +1,39 @@
+// ux-product.ts — finding and loading the product facts file for the UX review (#198).
+//
+// `--product <file>` wins; otherwise the project's `.jevitate/product.json` (found by walking up
+// from the working directory, like every other in-repo `.jevitate/` file) is used when it exists.
+// An unreadable or invalid file is a typed refusal (`E_UX_PRODUCT_INPUT`, usage error) BEFORE any
+// browser opens — never a silently ignored file.
+import { existsSync, statSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { ProductFactsError, parseProductFactsText } from "@jevitate/ux";
+import { findProjectDir } from "./project-dir.js";
+export const PRODUCT_FACTS_FILE = "product.json";
+/** The facts file to read: the flag, else `<project>/.jevitate/product.json` when present. */
+export function productFactsPath(flag, deps = {}) {
+    if (flag !== undefined)
+        return flag;
+    const dir = findProjectDir(deps);
+    if (dir === null)
+        return undefined;
+    const p = join(dir, PRODUCT_FACTS_FILE);
+    return existsSync(p) && statSync(p).isFile() ? p : undefined;
+}
+/** Reads and validates the product facts. Throws `ProductFactsError` for a missing/invalid file. */
+export async function loadProductFacts(flag, deps = {}) {
+    const path = productFactsPath(flag, deps);
+    if (path === undefined)
+        return {};
+    let text;
+    try {
+        text = await readFile(path, "utf8");
+    }
+    catch (err) {
+        throw new ProductFactsError(path, [`cannot read the file: ${err instanceof Error ? err.message : String(err)}`]);
+    }
+    return { facts: parseProductFactsText(text, path), path };
+}
+/** The report caveat when no facts were available (prices and intended next steps went unchecked). */
+export const NO_PRODUCT_FACTS_CAVEAT = "no product facts (.jevitate/product.json or --product): prices, trial lengths and each page's intended next step were not checked against the product's own facts (docs/ux-findings.md).";
+//# sourceMappingURL=ux-product.js.map

package/dist/ux-product.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ux-product.js","sourceRoot":"","sources":["../src/ux-product.ts"],"names":[],"mappings":"AAAA,uFAAuF;AACvF,EAAE;AACF,iGAAiG;AACjG,kGAAkG;AAClG,kGAAkG;AAClG,iDAAiD;AACjD,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAqB,MAAM,cAAc,CAAC;AAC3F,OAAO,EAAE,cAAc,EAAmB,MAAM,kBAAkB,CAAC;AAEnE,MAAM,CAAC,MAAM,kBAAkB,GAAG,cAAc,CAAC;AAQjD,8FAA8F;AAC9F,MAAM,UAAU,gBAAgB,CAAC,IAAwB,EAAE,OAAmB,EAAE;IAC9E,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACpC,MAAM,GAAG,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IACjC,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IACnC,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,kBAAkB,CAAC,CAAC;IACxC,OAAO,UAAU,CAAC,CAAC,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC/D,CAAC;AAED,oGAAoG;AACpG,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAAwB,EAAE,OAAmB,EAAE;IACpF,MAAM,IAAI,GAAG,gBAAgB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC1C,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IAClC,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACtC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,iBAAiB,CAAC,IAAI,EAAE,CAAC,yBAAyB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IACnH,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,qBAAqB,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC;AAC5D,CAAC;AAED,sGAAsG;AACtG,MAAM,CAAC,MAAM,uBAAuB,GAClC,0LAA0L,CAAC"}

package/dist/ux-review.d.ts

@@ -0,0 +1,116 @@
+import type { JudgmentPort, GenerationPort, UsageTracker, UsageCounts } from "@jevitate/ai-core";
+import type { Recording } from "@jevitate/recording";
+import { type AppContext, type JourneyOutcome, type SignalOptions, type UxEvidenceFile, type UxReport } from "@jevitate/ux";
+import { type MissionTranscriptEntryLike } from "./ux-evidence.js";
+export interface RunUxReviewOptions {
+    readonly recording: Recording;
+    readonly appContext: AppContext;
+    readonly judge: JudgmentPort;
+    /** Structured-output specifics (observation / implicated controls / fix) for flagged items. */
+    readonly gen: GenerationPort;
+    /**
+     * Usage accounting (#100): when supplied, its snapshot (judgments/generations/tokens/`usd`) lands
+     * in the result as `usage`. The CLI builds one per invocation and hands it to `judge`/`gen`.
+     */
+    readonly usage?: UsageTracker;
+    /**
+     * Report cutoff; findings below it are suppressed (counted in `report.suppressed`). Precedence:
+     * this (CLI `--min-confidence`) > `JEVITATE_UX_MIN_CONFIDENCE` > config `ux.minConfidence`
+     * (`~/.jevitate/config.json`) > `DEFAULT_MIN_CONFIDENCE`.
+     */
+    readonly minConfidence?: number | string;
+    /**
+     * Quality grades to show, e.g. "actionable,relevant-minor". Precedence: this (CLI `--show`) >
+     * `JEVITATE_UX_SHOW` > config `ux.show` > every grade (#133: the uncalibrated grader labels, it does not filter).
+     */
+    readonly show?: string;
+    /**
+     * Cap on findings per route (issue #198 interim, 0.2.0). Precedence: this (CLI
+     * `--max-findings-per-page`) > `JEVITATE_UX_MAX_FINDINGS_PER_PAGE` > config
+     * `ux.maxFindingsPerPage` > `DEFAULT_MAX_FINDINGS_PER_ROUTE` (5).
+     */
+    readonly maxFindingsPerRoute?: number | string;
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    /** Path of the config file holding `ux.minConfidence`. Default `~/.jevitate/config.json`. */
+    readonly configPath?: string;
+    readonly secrets?: readonly string[];
+    /** Local file the `upload` op attaches (CLI `--fixture`); validated before any browser opens. */
+    readonly fixture?: string;
+    readonly judgmentBudget?: number;
+    /** Where to write the report. Default `.jevitate/logs/<date>` (project, else `~/.jevitate`). */
+    readonly outDir?: string;
+    readonly nowIso?: () => string;
+    /**
+     * The source run's mission transcript (#85 item 2) — from `--result`'s `<recording>.result.json`
+     * (`result.transcript`), or the sibling `<recording>.transcript.json` directly. Gives offline
+     * analysis the same blocked/disabled-target evidence a live usability run sees. Absent, the
+     * report says so (`report.evidenceCaveats`) rather than silently seeing less.
+     */
+    readonly missionTranscript?: readonly MissionTranscriptEntryLike[];
+    /** Why `missionTranscript` is absent (e.g. no `--result` given, or the file could not be read) — becomes a report caveat. */
+    readonly missionTranscriptUnavailable?: string;
+    /** The source run's end state (a mission result's `outcome`), for the goal-not-reached friction (#132). */
+    readonly missionOutcome?: JourneyOutcome;
+    /**
+     * #134: the live usability run's evidence sidecar (`<stamp>.evidence.json`): every screen as the
+     * live analyzer saw it (redacted) and the run-signal capture. With it, offline review reproduces
+     * the live run's rubric AND signal findings; without it, the report says what it could not see.
+     */
+    readonly evidenceFile?: UxEvidenceFile;
+    /** Why no evidence sidecar was used (not found next to the Recording, or unreadable) — a report caveat. */
+    readonly evidenceUnavailable?: string;
+    /** Tuning of the run-signal oracles (#96/#131). */
+    readonly signals?: SignalOptions;
+    /** #198 `--product <file>`: product facts (default `.jevitate/product.json` in the project). */
+    readonly product?: string;
+    /** #198 `--polish`: polish each verified finding's recommendation with one generation call (opt-in). */
+    readonly polish?: boolean;
+}
+export interface RunUxReviewResult {
+    readonly report: UxReport;
+    readonly reportPath: string;
+    /** Judgment/generation call counts and tokens for this run (#100); present only when `opts.usage` was supplied. */
+    readonly usage?: UsageCounts;
+}
+/**
+ * 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 declare function runUxReview(opts: RunUxReviewOptions): Promise<RunUxReviewResult>;
+/** #134: the artifacts a run writes next to its Recording (`<stem>.recording.json`). */
+export interface RecordingSidecars {
+    /** `<stem>.evidence.json` — the live usability run's evidence sidecar. */
+    readonly evidencePath?: string;
+    /** `<stem>.transcript.json` — the decision transcript (each step's screenshot). */
+    readonly transcriptPath?: string;
+    /** `<stem>.result.json` — a mission result (explore/adversarial), carrying transcript + outcome. */
+    readonly resultPath?: string;
+    /** `<stem>.screens/` — the per-step screenshots. */
+    readonly screenshotDir?: string;
+}
+/** Finds the sidecars that exist next to `recordingPath` (only `<stem>.recording.json` has a stem). */
+export declare function discoverRecordingSidecars(recordingPath: string): RecordingSidecars;
+/** What the discovered (or given) sidecars supply to `runUxReview`, and why anything is missing. */
+export interface LoadedSidecars {
+    readonly evidenceFile?: UxEvidenceFile;
+    readonly evidenceUnavailable?: string;
+    readonly missionTranscript?: MissionTranscriptEntryLike[];
+    readonly missionTranscriptUnavailable?: string;
+    readonly missionOutcome?: JourneyOutcome;
+}
+/**
+ * Reads the evidence sidecar and the transcript/result (explicit paths win over discovered ones).
+ * Never throws: an unreadable file becomes the matching `…Unavailable` caveat.
+ */
+export declare function loadRecordingSidecars(paths: {
+    readonly evidencePath?: string;
+    readonly resultPath?: string;
+    readonly transcriptPath?: string;
+}): Promise<LoadedSidecars>;
+export declare class UxAnalysisFailedError extends Error {
+    readonly screenId?: string | undefined;
+    readonly rubricItemId?: string | undefined;
+    readonly code: "E_UX_ANALYSIS";
+    constructor(reason: string, screenId?: string | undefined, rubricItemId?: string | undefined);
+}