@slowcook-ai/cli 0.19.5 → 0.20.0

package/dist/commands/brew/fidelity-loop.js

@@ -0,0 +1,108 @@
+/**
+ * design #8 — eye-driven brew convergence loop.
+ *
+ * Bounded fidelity-correction controller: the "brain" that drives a front-end
+ * brew toward a mock by repeatedly measuring fidelity violations (the eye) and
+ * applying fixes (the brew agent), relying on a hot-reload stack to re-render
+ * between iterations so each pass is cheap.
+ *
+ * Generic + dependency-free. Parameterised over a violation type `V` so it
+ * never couples to the eye's concrete types (no import from
+ * @slowcook-ai/gates or any sibling package).
+ *
+ * MUST be bounded and detect non-progress. slowcook's brew agent has a
+ * documented "analysis-paralysis" failure mode (see
+ * `project_brew_agent_improvements`) where it loops without converging — so
+ * the controller escalates rather than spinning:
+ *   - converged: zero violations measured.
+ *   - stalled:   violation COUNT failed to strictly decrease for `stallLimit`
+ *                consecutive iterations (default 2). The stalling applyFix is
+ *                NOT re-run — we bail before burning another fix.
+ *   - exhausted: `maxIters` (default 5) measure() calls made while violations
+ *                remain.
+ *
+ * Progress is measured by strictly-decreasing violation COUNT. `keyOf` is
+ * required in deps (and is the stable per-violation identity used by callers
+ * for logging/diffing `remaining`) but the convergence decision itself is
+ * count-based and documented as such for simplicity.
+ */
+/**
+ * Drive a bounded measure → fix → re-measure loop until the front-end matches
+ * the mock (zero violations) or the controller escalates.
+ *
+ * Escalation semantics (return without calling applyFix again on bail):
+ *   - First iteration always proceeds to applyFix if violations exist (there is
+ *     no "previous" count to stall against).
+ *   - After each measure: if `iterations >= maxIters` and violations remain →
+ *     `exhausted`.
+ *   - Stall: if this iteration's count did NOT strictly decrease vs the prior
+ *     count (>= previous), increment the stall counter; otherwise reset it to
+ *     0. When the stall counter reaches `stallLimit` → `stalled` (applyFix is
+ *     NOT invoked for this iteration).
+ *   - `escalated === !converged`.
+ */
+export async function runFidelityLoop(deps) {
+    const maxIters = deps.maxIters ?? 5;
+    const stallLimit = deps.stallLimit ?? 2;
+    const history = [];
+    let iterations = 0;
+    let stallCount = 0;
+    let prevCount = null;
+    let remaining = [];
+    // Loop guard: maxIters caps measure() calls, so this can never run forever.
+    for (;;) {
+        remaining = await deps.measure();
+        iterations += 1;
+        const count = remaining.length;
+        history.push(count);
+        const converged = count === 0;
+        deps.onIteration?.({ iteration: iterations, count, converged });
+        if (converged) {
+            return {
+                converged: true,
+                escalated: false,
+                iterations,
+                remaining,
+                history,
+                reason: 'converged',
+            };
+        }
+        // Out of budget: violations remain and we've used our measure() quota.
+        if (iterations >= maxIters) {
+            return {
+                converged: false,
+                escalated: true,
+                iterations,
+                remaining,
+                history,
+                reason: 'exhausted',
+            };
+        }
+        // Progress check (count-based). Skipped on the first iteration since there
+        // is no previous count to compare against.
+        if (prevCount !== null) {
+            if (count >= prevCount) {
+                stallCount += 1;
+            }
+            else {
+                stallCount = 0;
+            }
+            if (stallCount >= stallLimit) {
+                // Bail BEFORE applying another fix — the agent is spinning.
+                return {
+                    converged: false,
+                    escalated: true,
+                    iterations,
+                    remaining,
+                    history,
+                    reason: 'stalled',
+                };
+            }
+        }
+        prevCount = count;
+        // Hand the current violations to the brew agent; the caller's HMR stack
+        // re-renders before the next measure().
+        await deps.applyFix(remaining, iterations);
+    }
+}
+//# sourceMappingURL=fidelity-loop.js.map

package/dist/commands/brew/fidelity-loop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fidelity-loop.js","sourceRoot":"","sources":["../../../src/commands/brew/fidelity-loop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AA0BH;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,IAAyB;IAEzB,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC;IACpC,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,CAAC,CAAC;IAExC,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,IAAI,SAAS,GAAkB,IAAI,CAAC;IACpC,IAAI,SAAS,GAAQ,EAAE,CAAC;IAExB,4EAA4E;IAC5E,SAAS,CAAC;QACR,SAAS,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QACjC,UAAU,IAAI,CAAC,CAAC;QAChB,MAAM,KAAK,GAAG,SAAS,CAAC,MAAM,CAAC;QAC/B,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAEpB,MAAM,SAAS,GAAG,KAAK,KAAK,CAAC,CAAC;QAC9B,IAAI,CAAC,WAAW,EAAE,CAAC,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;QAEhE,IAAI,SAAS,EAAE,CAAC;YACd,OAAO;gBACL,SAAS,EAAE,IAAI;gBACf,SAAS,EAAE,KAAK;gBAChB,UAAU;gBACV,SAAS;gBACT,OAAO;gBACP,MAAM,EAAE,WAAW;aACpB,CAAC;QACJ,CAAC;QAED,uEAAuE;QACvE,IAAI,UAAU,IAAI,QAAQ,EAAE,CAAC;YAC3B,OAAO;gBACL,SAAS,EAAE,KAAK;gBAChB,SAAS,EAAE,IAAI;gBACf,UAAU;gBACV,SAAS;gBACT,OAAO;gBACP,MAAM,EAAE,WAAW;aACpB,CAAC;QACJ,CAAC;QAED,2EAA2E;QAC3E,2CAA2C;QAC3C,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;YACvB,IAAI,KAAK,IAAI,SAAS,EAAE,CAAC;gBACvB,UAAU,IAAI,CAAC,CAAC;YAClB,CAAC;iBAAM,CAAC;gBACN,UAAU,GAAG,CAAC,CAAC;YACjB,CAAC;YAED,IAAI,UAAU,IAAI,UAAU,EAAE,CAAC;gBAC7B,4DAA4D;gBAC5D,OAAO;oBACL,SAAS,EAAE,KAAK;oBAChB,SAAS,EAAE,IAAI;oBACf,UAAU;oBACV,SAAS;oBACT,OAAO;oBACP,MAAM,EAAE,SAAS;iBAClB,CAAC;YACJ,CAAC;QACH,CAAC;QAED,SAAS,GAAG,KAAK,CAAC;QAElB,wEAAwE;QACxE,wCAAwC;QACxC,MAAM,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;IAC7C,CAAC;AACH,CAAC"}

package/dist/commands/brew/fidelity-phase.d.ts

@@ -0,0 +1,49 @@
+/**
+ * design #8 — the post-green fidelity phase. After brew's behavioural/structural
+ * tests pass, render the brewed app vs the mock across the spec-declared modes
+ * and either (a) gate: drift → escalate to the #9 designer/QA gate, or (b) drive:
+ * feed the hard per-element violations back to the brew agent over a hot-reload
+ * candidate, bounded, until convergence or escalation.
+ *
+ * The eye measurement + the brew-fix application are INJECTED — the orchestration
+ * (matrix from spec, loop, escalation mapping) is pure-flow + unit-tested; the
+ * Playwright render (../eye/run.ts) and the live brew-agent fix supply the seams.
+ */
+import type { FidelityViolation } from "@slowcook-ai/gates";
+import { type EyeContext } from "../eye/plan.js";
+/**
+ * Render violations into a concise, mock-faithful fix instruction for the brew
+ * agent. Grouped by viewport/scheme; scoped to presentation-only edits. Pure.
+ */
+export declare function formatViolationsForBrew(violations: FidelityViolation[]): string;
+export interface FidelityPhaseDeps {
+    /** Story id — used to resolve the spec's fidelity.modes. */
+    story?: string;
+    /** Repo root for the spec lookup. */
+    cwd: string;
+    /** Render + grade the matrix → violations (real: a runEyeMatrix wrapper). */
+    measure: (matrix: EyeContext[]) => Promise<FidelityViolation[]>;
+    /**
+     * Apply fixes via the brew agent against a hot-reload candidate, then the
+     * caller's HMR re-renders. OMIT for gate-only mode (drift → escalate, no fix).
+     */
+    applyFix?: (violations: FidelityViolation[], iteration: number) => Promise<void>;
+    maxIters?: number;
+    log?: (msg: string) => void;
+}
+export interface FidelityPhaseResult {
+    converged: boolean;
+    escalated: boolean;
+    iterations: number;
+    remaining: FidelityViolation[];
+    reason: string;
+    /** The #9 gate action: pass advances; blocked-on-designer halts for review. */
+    gateAction: "pass" | "blocked-on-designer";
+    matrixCells: number;
+}
+/**
+ * Run the fidelity phase. Matrix comes from the spec's fidelity.modes (the
+ * contract) or the full default. Gate-only when `applyFix` is omitted.
+ */
+export declare function runFidelityPhase(deps: FidelityPhaseDeps): Promise<FidelityPhaseResult>;
+//# sourceMappingURL=fidelity-phase.d.ts.map

package/dist/commands/brew/fidelity-phase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fidelity-phase.d.ts","sourceRoot":"","sources":["../../../src/commands/brew/fidelity-phase.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAG5D,OAAO,EAAmC,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAElF;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,iBAAiB,EAAE,GAAG,MAAM,CAuB/E;AAED,MAAM,WAAW,iBAAiB;IAChC,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,6EAA6E;IAC7E,OAAO,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAC;IAChE;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,UAAU,EAAE,iBAAiB,EAAE,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACjF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,iBAAiB,EAAE,CAAC;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,UAAU,EAAE,MAAM,GAAG,qBAAqB,CAAC;IAC3C,WAAW,EAAE,MAAM,CAAC;CACrB;AAKD;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAuC5F"}

package/dist/commands/brew/fidelity-phase.js

@@ -0,0 +1,75 @@
+import { runFidelityLoop } from "./fidelity-loop.js";
+import { loadFidelityModes } from "../eye/spec-modes.js";
+import { matrixFromModes, DEFAULT_MATRIX } from "../eye/plan.js";
+/**
+ * Render violations into a concise, mock-faithful fix instruction for the brew
+ * agent. Grouped by viewport/scheme; scoped to presentation-only edits. Pure.
+ */
+export function formatViolationsForBrew(violations) {
+    if (violations.length === 0)
+        return "No fidelity violations.";
+    const byCtx = new Map();
+    for (const v of violations) {
+        const k = `${v.context.viewport}/${v.context.scheme}`;
+        const arr = byCtx.get(k) ?? [];
+        arr.push(v);
+        byCtx.set(k, arr);
+    }
+    const lines = [
+        "Visual fidelity drift vs the approved mock. Edit ONLY the presentation of the",
+        "affected @slowcook-port-from components to restore the mock's rendering — do not",
+        "change behaviour, data-wiring, or markup structure, only the diverged styling:",
+        "",
+    ];
+    for (const [ctx, vs] of byCtx) {
+        lines.push(`## ${ctx}`);
+        for (const v of vs) {
+            lines.push(`- \`${v.selector}\`: ${v.property} should be ${v.expected} (currently ${v.actual}) [${v.axis}]`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n").trimEnd() + "\n";
+}
+const keyOf = (v) => `${v.context.viewport}/${v.context.scheme}|${v.selector}|${v.property}`;
+/**
+ * Run the fidelity phase. Matrix comes from the spec's fidelity.modes (the
+ * contract) or the full default. Gate-only when `applyFix` is omitted.
+ */
+export async function runFidelityPhase(deps) {
+    const modes = deps.story ? loadFidelityModes(deps.cwd, deps.story) : null;
+    const matrix = modes && modes.length ? matrixFromModes(modes) : DEFAULT_MATRIX;
+    deps.log?.(`fidelity phase: ${matrix.length} cell(s)${deps.applyFix ? " (driving)" : " (gate-only)"}`);
+    const measure = () => deps.measure(matrix);
+    // Gate-only: one measurement; drift escalates to the designer/QA gate.
+    if (!deps.applyFix) {
+        const violations = await measure();
+        const converged = violations.length === 0;
+        return {
+            converged,
+            escalated: !converged,
+            iterations: 1,
+            remaining: violations,
+            reason: converged ? "converged" : "drift (gate-only — escalating)",
+            gateAction: converged ? "pass" : "blocked-on-designer",
+            matrixCells: matrix.length,
+        };
+    }
+    // Eye-driven correction loop (bounded; escalates on stall/exhaustion).
+    const loop = await runFidelityLoop({
+        measure,
+        applyFix: deps.applyFix,
+        keyOf,
+        maxIters: deps.maxIters,
+        onIteration: deps.log ? (i) => deps.log(`  iter ${i.iteration}: ${i.count} violation(s)`) : undefined,
+    });
+    return {
+        converged: loop.converged,
+        escalated: loop.escalated,
+        iterations: loop.iterations,
+        remaining: loop.remaining,
+        reason: loop.reason,
+        gateAction: loop.converged ? "pass" : "blocked-on-designer",
+        matrixCells: matrix.length,
+    };
+}
+//# sourceMappingURL=fidelity-phase.js.map

package/dist/commands/brew/fidelity-phase.js.map

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

package/dist/commands/eye/index.d.ts

@@ -0,0 +1,2 @@
+export declare function eye(args: string[], _version: string): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/commands/eye/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/eye/index.ts"],"names":[],"mappings":"AAmBA,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA4CzE"}

package/dist/commands/eye/index.js

@@ -0,0 +1,64 @@
+/**
+ * design #8 — `slowcook eye`. Renders a reference (mock) URL and a candidate
+ * (brewed) URL across the (viewport × scheme) matrix in headless Chromium,
+ * grades candidate-vs-reference with the gates fidelity engine, writes
+ * screenshots + a JSON report, and exits 1 when the gate fails. This is the
+ * runnable eye behind the brew-loop + the #9 designer/QA gate; it consumes
+ * `references.visual` as the reference URL and the spec's fidelity.modes for
+ * the matrix.
+ *
+ *   slowcook eye --reference http://localhost:33010 --candidate http://localhost:3001 \
+ *     [--story 020] [--cwd .] [--out .brewing/eye] [--viewport mobile|desktop] \
+ *     [--scheme light|dark] [--max-violations N] [--fail-on color,box,computed-style,missing]
+ */
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseEyeArgs, matrixFromModes, narrowMatrix } from "./plan.js";
+import { loadFidelityModes } from "./spec-modes.js";
+import { runEyeMatrix } from "./run.js";
+export async function eye(args, _version) {
+    if (args[0] === "--help" || args[0] === "-h") {
+        console.log("usage: slowcook eye --reference <url> --candidate <url> [--story <id>] [--cwd <dir>] [--out dir] [--viewport m] [--scheme s] [--max-violations N] [--fail-on a,b]");
+        return;
+    }
+    let opts;
+    try {
+        opts = parseEyeArgs(args);
+    }
+    catch (e) {
+        console.error(String(e instanceof Error ? e.message : e));
+        process.exit(64);
+    }
+    // Spec-declared modes (the contract) override the default matrix; explicit
+    // --viewport/--scheme flags still narrow on top.
+    if (opts.story) {
+        const modes = loadFidelityModes(opts.cwd, opts.story);
+        if (modes && modes.length) {
+            opts.matrix = narrowMatrix(matrixFromModes(modes), { viewport: opts.viewport, scheme: opts.scheme });
+            console.log(`eye: matrix from story-${opts.story} fidelity.modes [${modes.join(", ")}] → ${opts.matrix.length} cell(s)`);
+        }
+        else {
+            console.log(`eye: story-${opts.story} declares no fidelity.modes; using ${opts.matrix.length}-cell default matrix`);
+        }
+    }
+    const { result, screenshots } = await runEyeMatrix({
+        referenceUrl: opts.referenceUrl,
+        candidateUrl: opts.candidateUrl,
+        matrix: opts.matrix,
+        outDir: opts.outDir,
+        gate: opts.gate,
+    });
+    writeFileSync(join(opts.outDir, "eye-report.json"), JSON.stringify({ ...result, screenshots }, null, 2));
+    console.log(`\nslowcook eye — ${result.passed ? "PASS ✓" : "FAIL ✗"} (${result.violations.length} violation(s) across ${opts.matrix.length} render(s))`);
+    for (const ctx of result.byContext) {
+        if (ctx.violations.length === 0)
+            continue;
+        console.log(`  [${ctx.context.viewport}/${ctx.context.scheme}] ${ctx.violations.length}: ${JSON.stringify(ctx.summary.byAxis)}`);
+        for (const v of ctx.violations.slice(0, 5))
+            console.log(`     ${v.axis}: ${v.evidence}`);
+    }
+    console.log(`  screenshots + report → ${opts.outDir}/`);
+    if (!result.passed)
+        process.exit(1);
+}
+//# sourceMappingURL=index.js.map

package/dist/commands/eye/index.js.map

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

package/dist/commands/eye/plan.d.ts

@@ -0,0 +1,61 @@
+/**
+ * design #8 — `slowcook eye` planning (pure). Expands the CLI flags + the
+ * spec's declared fidelity modes into the (viewport × scheme) capture matrix +
+ * gate thresholds the runner executes. Kept pure + unit-tested; the Playwright
+ * execution + spec IO live in ./index.ts (matrix source) and ./spec-modes.ts.
+ *
+ * Which modes are in fidelity scope is a CONTRACT declared by refine in the
+ * spec (`fidelity.modes`), not chosen by brew. The eye reads + enforces it;
+ * brew is measured against it. CLI flags can only NARROW (never widen).
+ */
+import type { FidelityGateOptions } from "@slowcook-ai/gates";
+/** A capture context plus the pixel viewport to emulate. */
+export interface EyeContext {
+    viewport: string;
+    scheme: "light" | "dark";
+    width: number;
+    height: number;
+}
+export interface EyeOptions {
+    referenceUrl: string;
+    candidateUrl: string;
+    outDir: string;
+    matrix: EyeContext[];
+    gate: FidelityGateOptions;
+    /** When set, the runner derives the matrix from this story's `fidelity.modes`. */
+    story?: string;
+    /** Repo root for spec lookup (default "."). */
+    cwd: string;
+    /** Raw narrowing flags, re-applied after a spec-derived matrix is built. */
+    viewport?: string;
+    scheme?: string;
+}
+export declare const VIEWPORTS: Record<string, {
+    width: number;
+    height: number;
+}>;
+/** Full default matrix: {mobile,desktop} × {light,dark}. */
+export declare const DEFAULT_MATRIX: EyeContext[];
+/**
+ * Build the capture matrix from a spec's declared `fidelity.modes` (pure).
+ * Tokens are dimension VALUES (`light`/`dark`/`mobile`/`desktop`), expanded to
+ * the product: a dimension with no declared value defaults to its full set
+ * (so `[dark]` → dark × {mobile,desktop}; `[mobile]` → {light,dark} × mobile).
+ * Unrecognised tokens are ignored; if NONE are recognised, the full default
+ * matrix is returned (fail-open — a typo never silently checks nothing).
+ */
+export declare function matrixFromModes(modes: string[]): EyeContext[];
+/** Narrow a matrix by explicit --viewport / --scheme flags (pure). Validates. */
+export declare function narrowMatrix(base: EyeContext[], opts: {
+    viewport?: string;
+    scheme?: string;
+}): EyeContext[];
+/**
+ * Parse `slowcook eye` flags. Required: --reference <url>, --candidate <url>.
+ * Optional: --story <id> (derive the matrix from the spec's fidelity.modes),
+ * --cwd <dir>, --out <dir>, --viewport <name> + --scheme <light|dark> (narrow),
+ * --max-violations <n>, --fail-on <a,b>. The returned `matrix` is the flag-only
+ * default; when `story` is set the runner rebuilds it from the spec.
+ */
+export declare function parseEyeArgs(args: string[]): EyeOptions;
+//# sourceMappingURL=plan.d.ts.map

package/dist/commands/eye/plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../../src/commands/eye/plan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAgB,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE5E,4DAA4D;AAC5D,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,IAAI,EAAE,mBAAmB,CAAC;IAC1B,kFAAkF;IAClF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,GAAG,EAAE,MAAM,CAAC;IACZ,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAGvE,CAAC;AAIF,4DAA4D;AAC5D,eAAO,MAAM,cAAc,EAAE,UAAU,EAEtC,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,UAAU,EAAE,CAQ7D;AAED,iFAAiF;AACjF,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,IAAI,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,UAAU,EAAE,CAa3G;AAOD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CA4BvD"}

package/dist/commands/eye/plan.js

@@ -0,0 +1,81 @@
+export const VIEWPORTS = {
+    mobile: { width: 390, height: 844 },
+    desktop: { width: 1280, height: 800 },
+};
+const SCHEMES = ["light", "dark"];
+/** Full default matrix: {mobile,desktop} × {light,dark}. */
+export const DEFAULT_MATRIX = Object.entries(VIEWPORTS).flatMap(([viewport, dim]) => SCHEMES.map((scheme) => ({ viewport, scheme, ...dim })));
+/**
+ * Build the capture matrix from a spec's declared `fidelity.modes` (pure).
+ * Tokens are dimension VALUES (`light`/`dark`/`mobile`/`desktop`), expanded to
+ * the product: a dimension with no declared value defaults to its full set
+ * (so `[dark]` → dark × {mobile,desktop}; `[mobile]` → {light,dark} × mobile).
+ * Unrecognised tokens are ignored; if NONE are recognised, the full default
+ * matrix is returned (fail-open — a typo never silently checks nothing).
+ */
+export function matrixFromModes(modes) {
+    const wanted = new Set(modes.map((m) => String(m).toLowerCase().trim()));
+    const viewports = Object.keys(VIEWPORTS).filter((v) => wanted.has(v));
+    const schemes = SCHEMES.filter((s) => wanted.has(s));
+    if (!viewports.length && !schemes.length)
+        return DEFAULT_MATRIX;
+    const vps = viewports.length ? viewports : Object.keys(VIEWPORTS);
+    const schs = schemes.length ? schemes : SCHEMES;
+    return vps.flatMap((viewport) => schs.map((scheme) => ({ viewport, scheme, ...VIEWPORTS[viewport] })));
+}
+/** Narrow a matrix by explicit --viewport / --scheme flags (pure). Validates. */
+export function narrowMatrix(base, opts) {
+    let m = base;
+    if (opts.viewport) {
+        if (!VIEWPORTS[opts.viewport]) {
+            throw new Error(`eye: unknown --viewport '${opts.viewport}' (have: ${Object.keys(VIEWPORTS).join(", ")})`);
+        }
+        m = m.filter((c) => c.viewport === opts.viewport);
+    }
+    if (opts.scheme) {
+        if (opts.scheme !== "light" && opts.scheme !== "dark")
+            throw new Error("eye: --scheme must be light|dark");
+        m = m.filter((c) => c.scheme === opts.scheme);
+    }
+    return m;
+}
+function val(args, flag) {
+    const i = args.indexOf(flag);
+    return i >= 0 ? args[i + 1] : undefined;
+}
+/**
+ * Parse `slowcook eye` flags. Required: --reference <url>, --candidate <url>.
+ * Optional: --story <id> (derive the matrix from the spec's fidelity.modes),
+ * --cwd <dir>, --out <dir>, --viewport <name> + --scheme <light|dark> (narrow),
+ * --max-violations <n>, --fail-on <a,b>. The returned `matrix` is the flag-only
+ * default; when `story` is set the runner rebuilds it from the spec.
+ */
+export function parseEyeArgs(args) {
+    const referenceUrl = val(args, "--reference");
+    const candidateUrl = val(args, "--candidate");
+    if (!referenceUrl || !candidateUrl) {
+        throw new Error("eye: --reference <url> and --candidate <url> are both required");
+    }
+    const viewport = val(args, "--viewport");
+    const scheme = val(args, "--scheme");
+    const matrix = narrowMatrix(DEFAULT_MATRIX, { viewport, scheme });
+    const maxV = val(args, "--max-violations");
+    const failOn = val(args, "--fail-on");
+    const gate = {};
+    if (maxV !== undefined)
+        gate.maxViolations = Number.parseInt(maxV, 10);
+    if (failOn)
+        gate.failOnAxes = failOn.split(",").map((s) => s.trim());
+    return {
+        referenceUrl,
+        candidateUrl,
+        outDir: val(args, "--out") ?? ".brewing/eye",
+        matrix,
+        gate,
+        story: val(args, "--story"),
+        cwd: val(args, "--cwd") ?? ".",
+        viewport,
+        scheme,
+    };
+}
+//# sourceMappingURL=plan.js.map

package/dist/commands/eye/plan.js.map

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

package/dist/commands/eye/run.d.ts

@@ -0,0 +1,19 @@
+import { type FidelityGateOptions, type FidelityGateResult } from "@slowcook-ai/gates";
+import type { EyeContext } from "./plan.js";
+export interface RunEyeOptions {
+    referenceUrl: string;
+    candidateUrl: string;
+    matrix: EyeContext[];
+    /** Directory for screenshots. Files named `<label>-<viewport>-<scheme>.png`. */
+    outDir: string;
+    gate?: FidelityGateOptions;
+    /** Screenshot filename prefix (e.g. `eye-pr-123`); default none. */
+    shotPrefix?: string;
+}
+export interface RunEyeResult {
+    result: FidelityGateResult;
+    screenshots: string[];
+}
+/** Render + grade the full matrix. Launches one browser, a fresh context per cell. */
+export declare function runEyeMatrix(opts: RunEyeOptions): Promise<RunEyeResult>;
+//# sourceMappingURL=run.d.ts.map

package/dist/commands/eye/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../../src/commands/eye/run.ts"],"names":[],"mappings":"AAUA,OAAO,EAGL,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EAExB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE5C,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,mBAAmB,CAAC;IAC3B,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,kBAAkB,CAAC;IAC3B,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,sFAAsF;AACtF,wBAAsB,YAAY,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAmC7E"}

package/dist/commands/eye/run.js

@@ -0,0 +1,47 @@
+/**
+ * design #8 — reusable eye runner. Renders a reference (mock) URL + a candidate
+ * (brewed) URL across a capture matrix in headless Chromium, screenshots each
+ * cell, and grades candidate-vs-reference with the gates fidelity engine.
+ * Shared by the `slowcook eye` command (./index.ts) and the eye-driven brew
+ * fidelity phase (../brew/fidelity-phase.ts) so both measure identically.
+ */
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { chromium } from "@playwright/test";
+import { captureSnapshot, gradeFidelity, } from "@slowcook-ai/gates";
+/** Render + grade the full matrix. Launches one browser, a fresh context per cell. */
+export async function runEyeMatrix(opts) {
+    mkdirSync(opts.outDir, { recursive: true });
+    const prefix = opts.shotPrefix ? `${opts.shotPrefix}-` : "";
+    const browser = await chromium.launch();
+    const screenshots = [];
+    const captureUrl = async (url, label, ctx) => {
+        const c = await browser.newContext({
+            colorScheme: ctx.scheme,
+            viewport: { width: ctx.width, height: ctx.height },
+            deviceScaleFactor: 2,
+        });
+        const page = await c.newPage();
+        await page.goto(url, { waitUntil: "networkidle" });
+        await page.waitForTimeout(400); // let lazy / client styles settle
+        const shot = join(opts.outDir, `${prefix}${label}-${ctx.viewport}-${ctx.scheme}.png`);
+        await page.screenshot({ path: shot, fullPage: true });
+        screenshots.push(shot);
+        const snap = await captureSnapshot(page, { viewport: ctx.viewport, scheme: ctx.scheme });
+        await c.close();
+        return snap;
+    };
+    const pairs = [];
+    try {
+        for (const ctx of opts.matrix) {
+            const reference = await captureUrl(opts.referenceUrl, "reference", ctx);
+            const candidate = await captureUrl(opts.candidateUrl, "candidate", ctx);
+            pairs.push({ reference, candidate });
+        }
+    }
+    finally {
+        await browser.close();
+    }
+    return { result: gradeFidelity(pairs, opts.gate), screenshots };
+}
+//# sourceMappingURL=run.js.map

package/dist/commands/eye/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../../src/commands/eye/run.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EACL,eAAe,EACf,aAAa,GAId,MAAM,oBAAoB,CAAC;AAmB5B,sFAAsF;AACtF,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAmB;IACpD,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5C,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5D,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,MAAM,EAAE,CAAC;IACxC,MAAM,WAAW,GAAa,EAAE,CAAC;IAEjC,MAAM,UAAU,GAAG,KAAK,EAAE,GAAW,EAAE,KAAa,EAAE,GAAe,EAA0B,EAAE;QAC/F,MAAM,CAAC,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC;YACjC,WAAW,EAAE,GAAG,CAAC,MAAM;YACvB,QAAQ,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE;YAClD,iBAAiB,EAAE,CAAC;SACrB,CAAC,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,OAAO,EAAE,CAAC;QAC/B,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,aAAa,EAAE,CAAC,CAAC;QACnD,MAAM,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,kCAAkC;QAClE,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,MAAM,GAAG,KAAK,IAAI,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,MAAM,MAAM,CAAC,CAAC;QACtF,MAAM,IAAI,CAAC,UAAU,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;QACtD,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACvB,MAAM,IAAI,GAAG,MAAM,eAAe,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;QACzF,MAAM,CAAC,CAAC,KAAK,EAAE,CAAC;QAChB,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;IAEF,MAAM,KAAK,GAA6D,EAAE,CAAC;IAC3E,IAAI,CAAC;QACH,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAC9B,MAAM,SAAS,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC,YAAY,EAAE,WAAW,EAAE,GAAG,CAAC,CAAC;YACxE,MAAM,SAAS,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC,YAAY,EAAE,WAAW,EAAE,GAAG,CAAC,CAAC;YACxE,KAAK,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC,CAAC;QACvC,CAAC;IACH,CAAC;YAAS,CAAC;QACT,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC;IACxB,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,aAAa,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,WAAW,EAAE,CAAC;AAClE,CAAC"}

package/dist/commands/eye/spec-modes.d.ts

@@ -0,0 +1,5 @@
+/** Pure: extract `fidelity.modes` from a spec YAML string, or null if absent. */
+export declare function extractFidelityModes(specYaml: string): string[] | null;
+/** Load `fidelity.modes` for a story from `<repoRoot>/specs/story-<id>.yaml`. */
+export declare function loadFidelityModes(repoRoot: string, story: string): string[] | null;
+//# sourceMappingURL=spec-modes.d.ts.map

package/dist/commands/eye/spec-modes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-modes.d.ts","sourceRoot":"","sources":["../../../src/commands/eye/spec-modes.ts"],"names":[],"mappings":"AAeA,iFAAiF;AACjF,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAUtE;AAED,iFAAiF;AACjF,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAIlF"}

package/dist/commands/eye/spec-modes.js

@@ -0,0 +1,36 @@
+/**
+ * design #8 — read a story spec's declared fidelity modes. refine writes
+ * `fidelity.modes` on the spec (the contract for which viewport/scheme cells
+ * matter); the eye reads it here to build its matrix. Decoupled from the
+ * (not-yet-built) #7 `references` field — when that lands, `references.visual[].modes`
+ * becomes the per-source override and `fidelity.modes` the spec-level default.
+ *
+ *   # specs/story-020.yaml
+ *   fidelity:
+ *     modes: [light, dark, mobile, desktop]
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import YAML from "yaml";
+/** Pure: extract `fidelity.modes` from a spec YAML string, or null if absent. */
+export function extractFidelityModes(specYaml) {
+    let doc;
+    try {
+        doc = YAML.parse(specYaml);
+    }
+    catch {
+        return null;
+    }
+    const modes = doc?.fidelity?.modes;
+    if (Array.isArray(modes))
+        return modes.map((m) => String(m));
+    return null;
+}
+/** Load `fidelity.modes` for a story from `<repoRoot>/specs/story-<id>.yaml`. */
+export function loadFidelityModes(repoRoot, story) {
+    const p = join(repoRoot, "specs", `story-${story}.yaml`);
+    if (!existsSync(p))
+        return null;
+    return extractFidelityModes(readFileSync(p, "utf8"));
+}
+//# sourceMappingURL=spec-modes.js.map

package/dist/commands/eye/spec-modes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-modes.js","sourceRoot":"","sources":["../../../src/commands/eye/spec-modes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,IAAI,MAAM,MAAM,CAAC;AAExB,iFAAiF;AACjF,MAAM,UAAU,oBAAoB,CAAC,QAAgB;IACnD,IAAI,GAAY,CAAC;IACjB,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,KAAK,GAAI,GAAiD,EAAE,QAAQ,EAAE,KAAK,CAAC;IAClF,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7D,OAAO,IAAI,CAAC;AACd,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,iBAAiB,CAAC,QAAgB,EAAE,KAAa;IAC/D,MAAM,CAAC,GAAG,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE,SAAS,KAAK,OAAO,CAAC,CAAC;IACzD,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAChC,OAAO,oBAAoB,CAAC,YAAY,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;AACvD,CAAC"}