@jevitate/cli 0.1.0 → 0.2.0

package/dist/usability-capture.js

@@ -0,0 +1,326 @@
+// usability-capture.ts — what a live usability run measures besides the rubric evidence (#96/#98):
+//
+//   - a per-step SCREENSHOT of every screen the run decides on, with every secret-bearing element
+//     MASKED by Playwright before the pixels are captured (password/OTP inputs, bound secret
+//     fields, and any element whose text or value holds a registered secret) — fail-closed: when
+//     the secret scan cannot run, no screenshot is written at all;
+//   - the REQUESTS the page made (fetch/xhr/document: method, endpoint, status, start/end), each
+//     attributed to the step whose action it followed;
+//   - per-screen facts the signal oracles need (url, signature, visible text, a busy indicator,
+//     the page heading — #131);
+//   - per write request, a one-way PAYLOAD DIGEST (#131 duplicate create): volatile keys dropped,
+//     never for a body holding a secret or a credential-named field, and never the body itself.
+//
+// Everything stored here is redacted (redactUrl + the run's secrets) before it is kept; nothing
+// here ever reaches a model. The capture is advisory: a failure to screenshot or to read the page
+// never affects the run.
+import { createHash } from "node:crypto";
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { DEMO_OVERLAY_HIDE_STYLE, endpointOf, redactText, redactUrl } from "@jevitate/explore";
+/** Secret-bearing inputs — the same predicate as `@jevitate/recorder`'s `isSecretField`, in CSS. */
+export const SECRET_INPUT_SELECTOR = [
+    'input[type="password" i]',
+    '[autocomplete~="current-password" i]',
+    '[autocomplete~="new-password" i]',
+    '[autocomplete~="one-time-code" i]',
+    '[autocomplete~="otp" i]',
+].join(", ");
+/** The attribute the in-page secret scan marks an element with (removed after the screenshot). */
+const MASK_ATTR = "data-jevitate-mask";
+/** The opaque box drawn over every masked element (Playwright's own default, pinned). */
+export const MASK_COLOR = "#FF00FF";
+const KEPT_TYPES = new Set(["fetch", "xhr", "document"]);
+const SCREENSHOT_TIMEOUT_MS = 5_000;
+function withTimeout(p, ms) {
+    let timer;
+    return Promise.race([
+        p,
+        new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`timed out after ${ms}ms`)), ms);
+        }),
+    ]).finally(() => clearTimeout(timer));
+}
+/** A bound secret field's matcher → a locator for every element it could match. */
+function boundFieldLocator(page, f) {
+    const v = JSON.stringify(f.matcher.value);
+    switch (f.matcher.key) {
+        case "label":
+            return page.getByLabel(f.matcher.value, { exact: true });
+        case "testId":
+            return page.getByTestId(f.matcher.value);
+        case "type":
+            return page.locator(`input[type=${v} i]`);
+        case "id":
+            return page.locator(`[id=${v}]`);
+        case "name":
+            return page.locator(`[name=${v}]`);
+    }
+}
+/**
+ * BROWSER CODE — marks every element whose text or form value holds a registered secret, and
+ * reports whether a busy/progress/status indicator is on screen. The secrets are handed to the
+ * browser that already holds them (it rendered or was typed them); they never leave it.
+ */
+function scanPage(args) {
+    let marked = 0;
+    if (args.secrets.length > 0) {
+        const holds = (s) => !!s && args.secrets.some((x) => s.includes(x));
+        for (const el of Array.from(document.querySelectorAll("input, textarea, select"))) {
+            if (holds(el.value)) {
+                el.setAttribute(args.attr, "");
+                marked++;
+            }
+        }
+        const walker = document.createTreeWalker(document.body ?? document.documentElement, NodeFilter.SHOW_TEXT);
+        for (let n = walker.nextNode(); n !== null; n = walker.nextNode()) {
+            if (holds(n.nodeValue) && n.parentElement !== null) {
+                n.parentElement.setAttribute(args.attr, "");
+                marked++;
+            }
+        }
+    }
+    const busy = document.querySelector('[aria-busy="true"], [role="progressbar"], progress, .spinner, [class*="spinner" i], [class*="loading" i]') !== null ||
+        Array.from(document.querySelectorAll('[role="status"], [aria-live]')).some((el) => (el.textContent ?? "").trim().length > 0);
+    const h1 = document.querySelector('h1, [role="heading"][aria-level="1"]');
+    const heading = ((h1?.innerText ?? h1?.textContent ?? "").trim() || document.title || "").replace(/\s+/g, " ").slice(0, 200);
+    return { marked, busy, heading };
+}
+/** Body keys that change between two submissions of the same thing (ids, timestamps, nonces). */
+const VOLATILE_KEY = /^(id|_id|uuid|guid|key|nonce|timestamp|ts|time|date|created_?at|updated_?at|client_?id|request_?id|idempotency_?key|trace_?id|csrf.*|xsrf.*)$/i;
+/** A body with a field named like a credential is never digested. */
+const CREDENTIAL_KEY = /pass|secret|token|otp|totp|pin|cvc|cvv|card|auth|session|cookie/i;
+const MAX_DIGEST_BODY = 64_000;
+class CredentialBody extends Error {
+}
+function canonical(v) {
+    if (Array.isArray(v))
+        return v.map(canonical);
+    if (v !== null && typeof v === "object") {
+        const out = {};
+        for (const k of Object.keys(v).sort()) {
+            if (CREDENTIAL_KEY.test(k))
+                throw new CredentialBody();
+            if (VOLATILE_KEY.test(k))
+                continue;
+            out[k] = canonical(v[k]);
+        }
+        return out;
+    }
+    return v;
+}
+/**
+ * A one-way digest of a write request's body (#131): two creates with the same digest sent the
+ * same payload. `undefined` — no digest — for a body that is absent, too large, not JSON or form
+ * data, or holds a secret or a credential-named field. The body itself is never kept.
+ */
+export function payloadDigest(method, endpoint, body, secrets) {
+    if (body === null || body.length === 0 || body.length > MAX_DIGEST_BODY)
+        return undefined;
+    if (secrets.some((x) => x.length > 0 && body.includes(x)))
+        return undefined;
+    let value;
+    try {
+        value = JSON.parse(body);
+    }
+    catch {
+        if (!/^[^=&\s]+=[^&]*(&[^=&\s]+=[^&]*)*$/.test(body))
+            return undefined;
+        value = Object.fromEntries(new URLSearchParams(body));
+    }
+    try {
+        const canon = JSON.stringify(canonical(value));
+        return createHash("sha256").update(`${method.toUpperCase()} ${endpoint}\n${canon}`).digest("hex").slice(0, 32);
+    }
+    catch {
+        return undefined; // a credential-named field: never digested
+    }
+}
+function unmark(attr) {
+    for (const el of Array.from(document.querySelectorAll(`[${attr}]`)))
+        el.removeAttribute(attr);
+}
+/** A request's own `content-type` header (#110: tells a gRPC-web/Connect read from a write). */
+function requestContentType(r) {
+    try {
+        const v = r.headers()["content-type"];
+        return typeof v === "string" && v !== "" ? v : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+const WRITE_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+function postDataOf(r) {
+    try {
+        return r.postData();
+    }
+    catch {
+        return null;
+    }
+}
+export class UsabilityCapture {
+    #opts;
+    #now;
+    #requests = [];
+    #live = new Map();
+    #screens = [];
+    /** Step number → the screenshot of the screen that step was decided on. */
+    #shotByStep = new Map();
+    /** Status reads still in flight (awaited before the capture is handed out). */
+    #statusReads = [];
+    #entries = 0;
+    #step = 0;
+    #detached = false;
+    constructor(opts) {
+        this.#opts = opts;
+        this.#now = opts.now ?? Date.now;
+        opts.page.on("request", this.#onRequest);
+        opts.page.on("requestfinished", this.#onFinished);
+        opts.page.on("requestfailed", this.#onFailed);
+    }
+    #redact(s) {
+        return redactText(s, this.#opts.secrets);
+    }
+    #onRequest = (r) => {
+        if (!KEPT_TYPES.has(r.resourceType()))
+            return;
+        const endpoint = this.#redact(endpointOf(r.method(), r.url()));
+        const payloadKey = WRITE_METHODS.has(r.method().toUpperCase()) ? payloadDigest(r.method(), endpoint, postDataOf(r), this.#opts.secrets) : undefined;
+        const rec = {
+            id: this.#requests.length,
+            method: r.method(),
+            endpoint,
+            url: this.#redact(redactUrl(r.url())),
+            resourceType: r.resourceType(),
+            startedAt: this.#now(),
+            endedAt: null,
+            status: null,
+            step: this.#step,
+            ...(payloadKey === undefined ? {} : { payloadKey }),
+        };
+        const contentType = requestContentType(r);
+        if (contentType !== undefined)
+            rec.contentType = contentType;
+        this.#requests.push(rec);
+        this.#live.set(r, rec);
+    };
+    #onFinished = (r) => {
+        const rec = this.#live.get(r);
+        if (rec === undefined)
+            return;
+        this.#live.delete(r);
+        rec.endedAt = this.#now();
+        this.#statusReads.push(r.response().then((res) => {
+            rec.status = res?.status() ?? null;
+        }, () => undefined));
+    };
+    #onFailed = (r) => {
+        const rec = this.#live.get(r);
+        if (rec === undefined)
+            return;
+        this.#live.delete(r);
+        rec.endedAt = this.#now();
+        rec.failed = true;
+    };
+    /** TranscriptLog listener: counts the steps recorded so far (a snapshot belongs to the next one). */
+    noteEntry(_entry, all) {
+        this.#entries = all.length;
+    }
+    /** The transcript with each step's screenshot path added (what the journal persists). */
+    withScreenshots(entries) {
+        return entries.map((e) => {
+            const shot = this.#shotByStep.get(e.step);
+            return shot === undefined ? e : { ...e, screenshot: shot };
+        });
+    }
+    /**
+     * One observed screen: its (masked) screenshot and its facts. Returns the screenshot path, or
+     * `null` when none was written (fail-closed secret scan, or the page did not answer in time).
+     */
+    async observe(snap, visibleText) {
+        const step = this.#entries + 1;
+        this.#step = step;
+        const index = this.#screens.length;
+        const { page, secrets } = this.#opts;
+        let busy = false;
+        let heading = "";
+        let shot = null;
+        let scanned = false;
+        try {
+            ({ busy, heading } = await withTimeout(page.evaluate(scanPage, { secrets: [...secrets], attr: MASK_ATTR }), SCREENSHOT_TIMEOUT_MS));
+            scanned = true;
+        }
+        catch {
+            scanned = false; // cannot prove where a secret is ⇒ no screenshot (fail-closed)
+        }
+        if (scanned) {
+            const path = join(this.#opts.screenshotDir, `screen-${index + 1}-step-${step}.png`);
+            const mask = [
+                page.locator(SECRET_INPUT_SELECTOR),
+                page.locator(`[${MASK_ATTR}]`),
+                ...(this.#opts.secretFields ?? []).map((f) => boundFieldLocator(page, f)),
+            ];
+            try {
+                mkdirSync(this.#opts.screenshotDir, { recursive: true });
+                // #245: the demo overlay (when shown) is hidden for the capture — evidence never contains it.
+                await page.screenshot({ path, mask, maskColor: MASK_COLOR, fullPage: true, style: DEMO_OVERLAY_HIDE_STYLE, timeout: SCREENSHOT_TIMEOUT_MS });
+                shot = path;
+            }
+            catch {
+                shot = null;
+            }
+            await withTimeout(page.evaluate(unmark, MASK_ATTR), SCREENSHOT_TIMEOUT_MS).catch(() => undefined);
+        }
+        if (shot !== null)
+            this.#shotByStep.set(step, shot);
+        this.#screens.push({
+            index,
+            step,
+            at: this.#now(),
+            url: this.#redact(redactUrl(snap.url)),
+            signature: snap.signature,
+            visibleText: this.#redact(visibleText),
+            busy,
+            ...(shot === null ? {} : { screenshot: shot }),
+            ...(heading.length === 0 ? {} : { heading: this.#redact(heading) }),
+        });
+        return shot;
+    }
+    /** Every screenshot written, in order. */
+    screenshots() {
+        return this.#screens.flatMap((s) => (s.screenshot === undefined ? [] : [s.screenshot]));
+    }
+    /** Stops listening; the capture is frozen from here. */
+    detach() {
+        if (this.#detached)
+            return;
+        this.#detached = true;
+        this.#opts.page.off("request", this.#onRequest);
+        this.#opts.page.off("requestfinished", this.#onFinished);
+        this.#opts.page.off("requestfailed", this.#onFailed);
+    }
+    /** The run's signal capture (steps from the final transcript). */
+    async signalCapture(transcript, typedValues) {
+        this.detach();
+        await Promise.allSettled(this.#statusReads);
+        const steps = transcript.map((e) => ({
+            step: e.step,
+            op: e.op,
+            target: e.target,
+            actOk: e.actOk,
+            url: e.url,
+            ...(e.descriptor === undefined ? {} : { descriptor: e.descriptor }),
+            ...(e.reason === undefined ? {} : { reason: e.reason }),
+            ...(e.href === undefined ? {} : { href: e.href }),
+            ...(e.ariaCurrent === undefined ? {} : { ariaCurrent: e.ariaCurrent }),
+            // #131: the transcript's own (already redacted) value/message/reply — redacted again here.
+            ...(e.value === undefined ? {} : { value: this.#redact(e.value) }),
+            ...(e.message === undefined ? {} : { message: this.#redact(e.message) }),
+            ...(e.reply === undefined || !e.reply.received ? {} : { reply: this.#redact(e.reply.text) }),
+        }));
+        const requests = this.#requests.map((r) => ({ ...r }));
+        return { steps, requests, screens: [...this.#screens], endedAt: this.#now(), typedValues };
+    }
+}
+//# sourceMappingURL=usability-capture.js.map

package/dist/usability-capture.js.map

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

package/dist/usage-config.d.ts

@@ -0,0 +1,36 @@
+import type { ConfiguredModelPrices, JevPricing, UsagePricing } from "@jevitate/ai-core";
+/**
+ * The usage-pricing slice of `~/.jevitate/config.json` (#136):
+ *
+ * ```json
+ * { "usage": {
+ *     "jevUnitPriceUsd": 0.006,
+ *     "modelPrices": { "openai/gpt-4o": { "inputUsdPerMtok": 2.5, "outputUsdPerMtok": 10 } } } }
+ * ```
+ *
+ * `jevUnitPriceUsd` prices each Jev judgment call when the provider itself reports no cost (it
+ * overrides the built-in Jev price table). `modelPrices` (#163) prices any model per million tokens
+ * — Jev or generation — overriding the built-in tables (and pricing a model they don't list). A
+ * missing file (or key) is "not configured"; a malformed file or a non-numeric/negative value fails
+ * closed rather than being silently ignored.
+ */
+export declare class UsageConfigError extends Error {
+    readonly code: "E_USAGE_CONFIG";
+}
+/** `usage.jevUnitPriceUsd` from the config file. Undefined when the file or key is absent. */
+export declare function loadJevUnitPriceUsd(path?: string): number | undefined;
+/**
+ * Resolves the Jev per-judgment unit price (#136): `JEVITATE_JEV_UNIT_PRICE_USD` (env) beats
+ * `usage.jevUnitPriceUsd` (config); undefined when neither is set — `jevUsd` then stays unpriced,
+ * exactly as it did before #136. The result's `source` is what `UsageCounts.jevPriceSource` echoes,
+ * so a priced run's number is never unexplained. A malformed value fails closed (never silently
+ * ignored, never silently mispriced): the CLI surfaces it as a setup error before any run starts.
+ */
+export declare function resolveJevUnitPrice(env?: Readonly<Record<string, string | undefined>>, configPath?: string): JevPricing | undefined;
+/** `usage.modelPrices` from the config file (#163). Undefined when the file or key is absent. */
+export declare function loadModelPrices(path?: string): ConfiguredModelPrices | undefined;
+/**
+ * Every configured price (#163): the Jev unit price (`resolveJevUnitPrice`) and `usage.modelPrices`.
+ * Whatever is not configured is priced from the built-in tables in `@jevitate/ai-core`'s usage.ts.
+ */
+export declare function resolveUsagePricing(env?: Readonly<Record<string, string | undefined>>, configPath?: string): UsagePricing;

package/dist/usage-config.js

@@ -0,0 +1,114 @@
+import { readFileSync } from "node:fs";
+import { resolveDataDir } from "./data-dir.js";
+/**
+ * The usage-pricing slice of `~/.jevitate/config.json` (#136):
+ *
+ * ```json
+ * { "usage": {
+ *     "jevUnitPriceUsd": 0.006,
+ *     "modelPrices": { "openai/gpt-4o": { "inputUsdPerMtok": 2.5, "outputUsdPerMtok": 10 } } } }
+ * ```
+ *
+ * `jevUnitPriceUsd` prices each Jev judgment call when the provider itself reports no cost (it
+ * overrides the built-in Jev price table). `modelPrices` (#163) prices any model per million tokens
+ * — Jev or generation — overriding the built-in tables (and pricing a model they don't list). A
+ * missing file (or key) is "not configured"; a malformed file or a non-numeric/negative value fails
+ * closed rather than being silently ignored.
+ */
+export class UsageConfigError extends Error {
+    code = "E_USAGE_CONFIG";
+}
+const ENV_VAR = "JEVITATE_JEV_UNIT_PRICE_USD";
+function loadUsageSection(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 UsageConfigError(`cannot read ${path}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new UsageConfigError(`${path} is not valid JSON`);
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new UsageConfigError(`${path} must be a JSON object`);
+    }
+    const usage = parsed.usage;
+    if (usage === undefined)
+        return undefined;
+    if (usage === null || typeof usage !== "object" || Array.isArray(usage)) {
+        throw new UsageConfigError(`${path}: "usage" must be an object`);
+    }
+    return usage;
+}
+function positiveNumber(v, at) {
+    if (typeof v !== "number" || !Number.isFinite(v) || v < 0) {
+        throw new UsageConfigError(`${at} must be a non-negative number, got ${JSON.stringify(v)}`);
+    }
+    return v;
+}
+/** `usage.jevUnitPriceUsd` from the config file. Undefined when the file or key is absent. */
+export function loadJevUnitPriceUsd(path = resolveDataDir(["config.json"])) {
+    const v = loadUsageSection(path)?.jevUnitPriceUsd;
+    if (v === undefined)
+        return undefined;
+    return positiveNumber(v, `${path}: usage.jevUnitPriceUsd`);
+}
+/**
+ * Resolves the Jev per-judgment unit price (#136): `JEVITATE_JEV_UNIT_PRICE_USD` (env) beats
+ * `usage.jevUnitPriceUsd` (config); undefined when neither is set — `jevUsd` then stays unpriced,
+ * exactly as it did before #136. The result's `source` is what `UsageCounts.jevPriceSource` echoes,
+ * so a priced run's number is never unexplained. A malformed value fails closed (never silently
+ * ignored, never silently mispriced): the CLI surfaces it as a setup error before any run starts.
+ */
+export function resolveJevUnitPrice(env = process.env, configPath = resolveDataDir(["config.json"])) {
+    const raw = env[ENV_VAR];
+    if (raw !== undefined && raw !== "") {
+        const n = Number(raw);
+        if (!Number.isFinite(n) || n < 0) {
+            throw new UsageConfigError(`${ENV_VAR} must be a non-negative number, got ${JSON.stringify(raw)}`);
+        }
+        return { unitPriceUsd: n, source: `env:${ENV_VAR}` };
+    }
+    const fromConfig = loadJevUnitPriceUsd(configPath);
+    if (fromConfig === undefined)
+        return undefined;
+    return { unitPriceUsd: fromConfig, source: `config:${configPath} usage.jevUnitPriceUsd` };
+}
+/** `usage.modelPrices` from the config file (#163). Undefined when the file or key is absent. */
+export function loadModelPrices(path = resolveDataDir(["config.json"])) {
+    const v = loadUsageSection(path)?.modelPrices;
+    if (v === undefined)
+        return undefined;
+    if (v === null || typeof v !== "object" || Array.isArray(v)) {
+        throw new UsageConfigError(`${path}: usage.modelPrices must be an object of { "<model>": { inputUsdPerMtok, outputUsdPerMtok } }`);
+    }
+    const prices = {};
+    for (const [model, p] of Object.entries(v)) {
+        if (p === null || typeof p !== "object" || Array.isArray(p)) {
+            throw new UsageConfigError(`${path}: usage.modelPrices.${model} must be { inputUsdPerMtok, outputUsdPerMtok }`);
+        }
+        const o = p;
+        prices[model] = {
+            inputUsdPerMtok: positiveNumber(o.inputUsdPerMtok, `${path}: usage.modelPrices.${model}.inputUsdPerMtok`),
+            outputUsdPerMtok: positiveNumber(o.outputUsdPerMtok, `${path}: usage.modelPrices.${model}.outputUsdPerMtok`),
+        };
+    }
+    return { prices, source: `config:${path} usage.modelPrices` };
+}
+/**
+ * Every configured price (#163): the Jev unit price (`resolveJevUnitPrice`) and `usage.modelPrices`.
+ * Whatever is not configured is priced from the built-in tables in `@jevitate/ai-core`'s usage.ts.
+ */
+export function resolveUsagePricing(env = process.env, configPath = resolveDataDir(["config.json"])) {
+    const jevUnitPrice = resolveJevUnitPrice(env, configPath);
+    const modelPrices = loadModelPrices(configPath);
+    return { ...(jevUnitPrice === undefined ? {} : { jevUnitPrice }), ...(modelPrices === undefined ? {} : { modelPrices }) };
+}
+//# sourceMappingURL=usage-config.js.map

package/dist/usage-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-config.js","sourceRoot":"","sources":["../src/usage-config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAChC,IAAI,GAAG,gBAAyB,CAAC;CAC3C;AAED,MAAM,OAAO,GAAG,6BAA6B,CAAC;AAE9C,SAAS,gBAAgB,CAAC,IAAY;IACpC,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACnC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QAChG,MAAM,IAAI,gBAAgB,CAAC,eAAe,IAAI,KAAK,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACnG,CAAC;IACD,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,gBAAgB,CAAC,GAAG,IAAI,oBAAoB,CAAC,CAAC;IAC1D,CAAC;IACD,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3E,MAAM,IAAI,gBAAgB,CAAC,GAAG,IAAI,wBAAwB,CAAC,CAAC;IAC9D,CAAC;IACD,MAAM,KAAK,GAAI,MAAkC,CAAC,KAAK,CAAC;IACxD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC1C,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACxE,MAAM,IAAI,gBAAgB,CAAC,GAAG,IAAI,6BAA6B,CAAC,CAAC;IACnE,CAAC;IACD,OAAO,KAAgC,CAAC;AAC1C,CAAC;AAED,SAAS,cAAc,CAAC,CAAU,EAAE,EAAU;IAC5C,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1D,MAAM,IAAI,gBAAgB,CAAC,GAAG,EAAE,uCAAuC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC9F,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,mBAAmB,CAAC,IAAI,GAAG,cAAc,CAAC,CAAC,aAAa,CAAC,CAAC;IACxE,MAAM,CAAC,GAAG,gBAAgB,CAAC,IAAI,CAAC,EAAE,eAAe,CAAC;IAClD,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACtC,OAAO,cAAc,CAAC,CAAC,EAAE,GAAG,IAAI,yBAAyB,CAAC,CAAC;AAC7D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAAoD,OAAO,CAAC,GAAG,EAC/D,UAAU,GAAG,cAAc,CAAC,CAAC,aAAa,CAAC,CAAC;IAE5C,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC;IACzB,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,EAAE,EAAE,CAAC;QACpC,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QACtB,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YACjC,MAAM,IAAI,gBAAgB,CAAC,GAAG,OAAO,uCAAuC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACrG,CAAC;QACD,OAAO,EAAE,YAAY,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,OAAO,EAAE,EAAE,CAAC;IACvD,CAAC;IACD,MAAM,UAAU,GAAG,mBAAmB,CAAC,UAAU,CAAC,CAAC;IACnD,IAAI,UAAU,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC/C,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,UAAU,wBAAwB,EAAE,CAAC;AAC5F,CAAC;AAED,iGAAiG;AACjG,MAAM,UAAU,eAAe,CAAC,IAAI,GAAG,cAAc,CAAC,CAAC,aAAa,CAAC,CAAC;IACpE,MAAM,CAAC,GAAG,gBAAgB,CAAC,IAAI,CAAC,EAAE,WAAW,CAAC;IAC9C,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACtC,IAAI,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5D,MAAM,IAAI,gBAAgB,CAAC,GAAG,IAAI,+FAA+F,CAAC,CAAC;IACrI,CAAC;IACD,MAAM,MAAM,GAA+B,EAAE,CAAC;IAC9C,KAAK,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAA4B,CAAC,EAAE,CAAC;QACtE,IAAI,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;YAC5D,MAAM,IAAI,gBAAgB,CAAC,GAAG,IAAI,uBAAuB,KAAK,gDAAgD,CAAC,CAAC;QAClH,CAAC;QACD,MAAM,CAAC,GAAG,CAA4B,CAAC;QACvC,MAAM,CAAC,KAAK,CAAC,GAAG;YACd,eAAe,EAAE,cAAc,CAAC,CAAC,CAAC,eAAe,EAAE,GAAG,IAAI,uBAAuB,KAAK,kBAAkB,CAAC;YACzG,gBAAgB,EAAE,cAAc,CAAC,CAAC,CAAC,gBAAgB,EAAE,GAAG,IAAI,uBAAuB,KAAK,mBAAmB,CAAC;SAC7G,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,IAAI,oBAAoB,EAAE,CAAC;AAChE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAAoD,OAAO,CAAC,GAAG,EAC/D,UAAU,GAAG,cAAc,CAAC,CAAC,aAAa,CAAC,CAAC;IAE5C,MAAM,YAAY,GAAG,mBAAmB,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;IAC1D,MAAM,WAAW,GAAG,eAAe,CAAC,UAAU,CAAC,CAAC;IAChD,OAAO,EAAE,GAAG,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,GAAG,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC;AAC5H,CAAC"}

package/dist/ux-api.d.ts

@@ -1,75 +1,3 @@
-import type { JudgmentPort, GenerationPort } from "@jevitate/ai-core";
-import { type BrowserPort } from "@jevitate/playwright";
-import type { Recording } from "@jevitate/recording";
-import { type Snapshot, type Bounds } from "@jevitate/explore";
-import { type AppContext, type ScreenRef, type UxEvidence, type UxReport } from "@jevitate/ux";
-/** 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;
-/**
- * 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 declare function recordingToEvidence(recording: Recording, appContext: AppContext, job?: string): UxEvidence[];
-export interface RunUxReviewOptions {
-    readonly recording: Recording;
-    readonly appContext: AppContext;
-    readonly judge: JudgmentPort;
-    readonly secrets?: readonly string[];
-    readonly judgmentBudget?: number;
-    /** Where to write the report. Default `~/.jevitate/ux-reports`. */
-    readonly outDir?: string;
-    readonly nowIso?: () => string;
-}
-export interface RunUxReviewResult {
-    readonly report: UxReport;
-    readonly reportPath: string;
-}
-/**
- * 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>;
-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);
-}
-export interface RunUsabilityMissionOptions {
-    readonly url: string;
-    readonly job: string;
-    readonly allowlist: readonly string[];
-    readonly appContext: AppContext;
-    readonly judge: JudgmentPort;
-    readonly gen: GenerationPort;
-    readonly bounds?: Partial<Bounds>;
-    readonly secrets?: readonly string[];
-    readonly judgmentBudget?: number;
-    readonly outDir?: string;
-    readonly browserPortFactory?: () => BrowserPort;
-    readonly nowIso?: () => string;
-    /** Test seam: extract a page's visible text. Default reads the live page. */
-    readonly extractText?: (session: {
-        page: {
-            evaluate: (fn: () => string) => Promise<string>;
-        };
-    }) => Promise<string>;
-}
-export interface RunUsabilityMissionResult {
-    readonly report: UxReport;
-    readonly reportPath: string;
-    readonly stop: string;
-    readonly screensObserved: number;
-}
-/**
- * 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 declare function runUsabilityMission(opts: RunUsabilityMissionOptions): Promise<RunUsabilityMissionResult>;
+export { type RunUsabilityMissionOptions, type RunUsabilityMissionResult, UsabilityInvariantsUnsupportedError, runUsabilityMission } from "./ux-usability.js";
+export { type LoadedSidecars, type RecordingSidecars, type RunUxReviewOptions, type RunUxReviewResult, UxAnalysisFailedError, discoverRecordingSidecars, loadRecordingSidecars, runUxReview } from "./ux-review.js";
+export { type MissionTranscriptEntryLike, captureFromTranscript, extractTypedValues, recordingToEvidence, snapshotToEvidence } from "./ux-evidence.js";