@neonwatty/limner 0.1.0

package/README.md

@@ -0,0 +1,161 @@
+# Limner
+
+Limner is an agent-guided visual fidelity workbench. It helps a coding agent turn an input image into a structured HTML reference, then compare that approved reference against a real app implementation.
+
+Limner is model-agnostic. It does not call a vision model and it does not produce hard pass/fail scores. It produces artifacts an agent and human can inspect: screenshots, side-by-sides, DOM metrics, reports, contracts, and local JSONL run logs.
+
+The optional visual spec workflow is agent-required. Limner can prepare the prompt pack and validate structured agent output, but it does not extract that spec on its own.
+
+## Install Locally
+
+```bash
+npm install
+npm run build
+```
+
+Run from source during development:
+
+```bash
+npm run dev -- --help
+```
+
+After build:
+
+```bash
+node dist/cli.js --help
+```
+
+Run the full local gate before PRs:
+
+```bash
+npm run check
+```
+
+`npm run check` runs ESLint, TypeScript, Vitest, build, Knip, and a tracked-file line-count guard.
+
+## Basic Workflow
+
+```bash
+limn init ./ideal.png --target replay-boundaries
+limn preview --target replay-boundaries
+limn capture reference --target replay-boundaries
+limn compare image-reference --target replay-boundaries
+limn compare image-app --target replay-boundaries --url http://localhost:3152/internal/optimization-lab/wedding-envelope#replay-boundaries --storage-state ./e2e/.auth/user.json
+limn compare reference-app --target replay-boundaries --url http://localhost:3152/internal/optimization-lab/wedding-envelope#replay-boundaries --storage-state ./e2e/.auth/user.json
+limn report --target replay-boundaries
+limn runs list
+```
+
+## Workspace Shape
+
+```text
+limner-workspace/
+  limner.config.ts
+  targets/
+    replay-boundaries/
+      source/ideal.png
+      contract/regions.json
+      contract/tokens.json
+      contract/acceptance.md
+      reference/index.html
+      reference/styles.css
+      captures/
+      reports/
+      AGENT_GUIDE.md
+  .limner/runs/
+```
+
+## Modes
+
+### Image To Reference
+
+Use this while recreating the input image in standalone HTML/CSS.
+
+```bash
+limn compare image-reference --target replay-boundaries
+limn compare image-reference --target replay-boundaries --spec
+limn compare image-reference --target replay-boundaries --spec --spec-instructions ./visual-spec-policy.md
+```
+
+Outputs:
+
+- `captures/image-reference/reference.png`
+- `captures/image-reference/side-by-side.png`
+- `reports/image-reference.md`
+
+With `--spec`, Limner also writes an agent handoff pack under `captures/image-reference/spec/`:
+
+- `agent-prompt.md`
+- `agent-prompt.codex.md`
+- `agent-prompt.claude.md`
+- `reference-dom-facts.json`
+- `agent-response.schema.json`
+- `agent-response.example.json`
+- expected agent output path: `agent-response.json`
+
+Limner also creates `contract/visual-spec-instructions.md` if it does not exist. Edit that file to customize the generated Codex and Claude prompts for a target, or pass `--spec-instructions <path>` to use a shared prompt policy file.
+
+After an agent writes a valid `agent-response.json`, rerun the same command and Limner will validate it and split out:
+
+- `captures/image-reference/ideal-visual-spec.json`
+- `captures/image-reference/reference-visual-spec.json`
+- `captures/image-reference/visual-spec-diff.json`
+
+The prompt pack is tuned for two common flows:
+
+- `agent-prompt.codex.md`: for Codex reading local files and writing `agent-response.json` directly in the repo.
+- `agent-prompt.claude.md`: for Claude with attached images and strict structured output, then copying the JSON into `agent-response.json`.
+
+Agents should inspect the ideal image and reference screenshot separately. The side-by-side image is comparison context, not the source image to parse.
+
+### Image To App
+
+Use this for quick grounding checks against a real app before or during reconstruction.
+It compares the source image directly to a captured app viewport.
+
+```bash
+limn compare image-app --target replay-boundaries --url http://localhost:3152/... --storage-state ./e2e/.auth/user.json
+```
+
+Outputs:
+
+- `captures/image-app/app.png`
+- `captures/image-app/side-by-side.png`
+- `reports/image-app.md`
+
+### Reference To App
+
+Use this after the reference HTML is approved and the real app needs to match it.
+
+```bash
+limn compare reference-app --target replay-boundaries --url http://localhost:3152/... --storage-state ./e2e/.auth/user.json
+```
+
+Outputs:
+
+- `captures/reference-app/reference.png`
+- `captures/reference-app/app.png`
+- `captures/reference-app/side-by-side.png`
+- `captures/reference-app/dom-metrics.json`
+- `reports/reference-app.md`
+
+Capture commands default to viewport-only screenshots. Add `--full-page` when the full scrollable page is the comparison target.
+
+## Local Logs
+
+Limner writes local structured logs only. There is no remote telemetry.
+
+```text
+.limner/runs/<run-id>/
+  manifest.json
+  events.jsonl
+  agent-notes.md
+```
+
+Use:
+
+```bash
+limn runs list
+limn runs show <run-id>
+limn runs summarize
+```

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { registerCaptureCommand } from './commands/capture.js';
+import { registerCompareCommand } from './commands/compare.js';
+import { registerInitCommand } from './commands/init.js';
+import { registerPreviewCommand } from './commands/preview.js';
+import { registerReportCommand } from './commands/report.js';
+import { registerRunsCommand } from './commands/runs.js';
+const program = new Command();
+program
+    .name('limn')
+    .description('Agent-guided visual fidelity workbench')
+    .version('0.1.0')
+    .option('-w, --workspace <path>', 'Limner workspace root', process.cwd());
+registerInitCommand(program);
+registerPreviewCommand(program);
+registerCaptureCommand(program);
+registerCompareCommand(program);
+registerReportCommand(program);
+registerRunsCommand(program);
+program.parseAsync(process.argv).catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`limn: ${message}`);
+    process.exitCode = 1;
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAEzD,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,MAAM,CAAC;KACZ,WAAW,CAAC,wCAAwC,CAAC;KACrD,OAAO,CAAC,OAAO,CAAC;KAChB,MAAM,CAAC,wBAAwB,EAAE,uBAAuB,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;AAE5E,mBAAmB,CAAC,OAAO,CAAC,CAAC;AAC7B,sBAAsB,CAAC,OAAO,CAAC,CAAC;AAChC,sBAAsB,CAAC,OAAO,CAAC,CAAC;AAChC,sBAAsB,CAAC,OAAO,CAAC,CAAC;AAChC,qBAAqB,CAAC,OAAO,CAAC,CAAC;AAC/B,mBAAmB,CAAC,OAAO,CAAC,CAAC;AAE7B,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IACxD,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,OAAO,CAAC,KAAK,CAAC,SAAS,OAAO,EAAE,CAAC,CAAC;IAClC,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CAAC,CAAC"}

package/dist/commands/capture.d.ts

@@ -0,0 +1,12 @@
+import type { Command } from 'commander';
+export declare function captureReference(options: {
+    workspaceRoot: string;
+    target: string;
+    headed?: boolean;
+    fullPage?: boolean;
+    modeDir?: string;
+}): Promise<{
+    screenshotPath: string;
+    metricsPath: string;
+}>;
+export declare function registerCaptureCommand(program: Command): void;

package/dist/commands/capture.js

@@ -0,0 +1,66 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { capturePage } from '../core/playwright-capture.js';
+import { createRunLogger } from '../core/run-logger.js';
+import { startStaticServer } from '../core/static-server.js';
+import { loadRegionContract } from '../core/dom-metrics.js';
+import { resolveTarget, resolveWorkspace } from '../core/workspace.js';
+export async function captureReference(options) {
+    const workspace = resolveWorkspace(options.workspaceRoot);
+    const target = resolveTarget(options.workspaceRoot, options.target);
+    const logger = await createRunLogger(workspace, { command: 'capture', target: options.target, mode: 'reference' });
+    const captureDir = path.join(target.capturesDir, options.modeDir ?? 'reference');
+    const screenshotPath = path.join(captureDir, 'reference.png');
+    const metricsPath = path.join(captureDir, 'dom-metrics.json');
+    try {
+        await logger.event({ type: 'command.started' });
+        const contract = await loadRegionContract(target.regionsPath);
+        await mkdir(captureDir, { recursive: true });
+        const server = await startStaticServer(target.referenceDir);
+        try {
+            const result = await capturePage({
+                url: server.url,
+                outputPath: screenshotPath,
+                contract,
+                side: 'reference',
+                headed: options.headed,
+                fullPage: options.fullPage,
+            });
+            await writeFile(metricsPath, JSON.stringify({ reference: result.metrics }, null, 2) + '\n');
+            await logger.artifact(screenshotPath, 'screenshot');
+            await logger.artifact(metricsPath, 'dom-metrics');
+            await logger.complete('ok');
+            return { screenshotPath, metricsPath };
+        }
+        finally {
+            await server.close();
+        }
+    }
+    catch (error) {
+        await logger.event({ type: 'command.failed', status: 'failed', message: error instanceof Error ? error.message : String(error) });
+        await logger.complete('failed');
+        throw error;
+    }
+}
+export function registerCaptureCommand(program) {
+    const capture = program.command('capture').description('Capture Limner artifacts');
+    capture
+        .command('reference')
+        .description('Capture the target reference HTML')
+        .requiredOption('-t, --target <name>', 'target name')
+        .option('--headed', 'show the browser while capturing')
+        .option('--full-page', 'capture the full scrollable page')
+        .option('--viewport-only', 'capture only the viewport (default)')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        const result = await captureReference({
+            workspaceRoot: globals.workspace,
+            target: options.target,
+            headed: options.headed,
+            fullPage: options.fullPage,
+        });
+        console.log(`Reference screenshot: ${result.screenshotPath}`);
+        console.log(`DOM metrics: ${result.metricsPath}`);
+    });
+}
+//# sourceMappingURL=capture.js.map

package/dist/commands/capture.js.map

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

package/dist/commands/compare-image-app.d.ts

@@ -0,0 +1,12 @@
+export declare function compareImageApp(options: {
+    workspaceRoot: string;
+    target: string;
+    url: string;
+    headed?: boolean;
+    storageState?: string;
+    fullPage?: boolean;
+}): Promise<{
+    sideBySidePath: string;
+    reportPath: string;
+    appPath: string;
+}>;

package/dist/commands/compare-image-app.js

@@ -0,0 +1,45 @@
+import { mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { capturePage } from '../core/playwright-capture.js';
+import { writeImageAppReport } from '../core/report-writer.js';
+import { createRunLogger } from '../core/run-logger.js';
+import { createSideBySideImage } from '../core/side-by-side.js';
+import { resolveTarget, resolveWorkspace } from '../core/workspace.js';
+export async function compareImageApp(options) {
+    const workspace = resolveWorkspace(options.workspaceRoot);
+    const target = resolveTarget(options.workspaceRoot, options.target);
+    const logger = await createRunLogger(workspace, { command: 'compare', target: options.target, mode: 'image-app' });
+    const captureDir = path.join(target.capturesDir, 'image-app');
+    const appPath = path.join(captureDir, 'app.png');
+    const sideBySidePath = path.join(captureDir, 'side-by-side.png');
+    try {
+        await logger.event({ type: 'command.started' });
+        await mkdir(captureDir, { recursive: true });
+        await capturePage({
+            url: options.url,
+            outputPath: appPath,
+            headed: options.headed,
+            storageState: options.storageState,
+            fullPage: options.fullPage,
+        });
+        await createSideBySideImage({ leftPath: target.sourceImagePath, rightPath: appPath, outputPath: sideBySidePath });
+        const reportPath = await writeImageAppReport({
+            target,
+            idealPath: target.sourceImagePath,
+            appPath,
+            sideBySidePath,
+            appUrl: options.url,
+        });
+        await logger.artifact(appPath, 'screenshot');
+        await logger.artifact(sideBySidePath, 'side-by-side');
+        await logger.artifact(reportPath, 'report');
+        await logger.complete('ok');
+        return { sideBySidePath, reportPath, appPath };
+    }
+    catch (error) {
+        await logger.event({ type: 'command.failed', status: 'failed', message: error instanceof Error ? error.message : String(error) });
+        await logger.complete('failed');
+        throw error;
+    }
+}
+//# sourceMappingURL=compare-image-app.js.map

package/dist/commands/compare-image-app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare-image-app.js","sourceRoot":"","sources":["../../src/commands/compare-image-app.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAC5D,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAEvE,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,OAOrC;IACC,MAAM,SAAS,GAAG,gBAAgB,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;IAC1D,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC,aAAa,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACpE,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,SAAS,EAAE,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC;IACnH,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;IAC9D,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;IACjD,MAAM,cAAc,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,kBAAkB,CAAC,CAAC;IAEjE,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE,CAAC,CAAC;QAChD,MAAM,KAAK,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC7C,MAAM,WAAW,CAAC;YAChB,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,UAAU,EAAE,OAAO;YACnB,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,YAAY,EAAE,OAAO,CAAC,YAAY;YAClC,QAAQ,EAAE,OAAO,CAAC,QAAQ;SAC3B,CAAC,CAAC;QACH,MAAM,qBAAqB,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,eAAe,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,CAAC,CAAC;QAClH,MAAM,UAAU,GAAG,MAAM,mBAAmB,CAAC;YAC3C,MAAM;YACN,SAAS,EAAE,MAAM,CAAC,eAAe;YACjC,OAAO;YACP,cAAc;YACd,MAAM,EAAE,OAAO,CAAC,GAAG;SACpB,CAAC,CAAC;QACH,MAAM,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;QAC7C,MAAM,MAAM,CAAC,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC,CAAC;QACtD,MAAM,MAAM,CAAC,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;QAC5C,MAAM,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC5B,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC;IACjD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,MAAM,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAClI,MAAM,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QAChC,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/commands/compare-image-reference.d.ts

@@ -0,0 +1,28 @@
+export declare function compareImageReference(options: {
+    workspaceRoot: string;
+    target: string;
+    headed?: boolean;
+    fullPage?: boolean;
+    spec?: boolean;
+    specInstructions?: string;
+}): Promise<{
+    sideBySidePath: string;
+    reportPath: string;
+    specPaths?: {
+        idealSpecPath: string;
+        referenceSpecPath: string;
+        diffPath: string;
+    };
+    agentSpec?: {
+        promptPath: string;
+        codexPromptPath: string;
+        claudePromptPath: string;
+        factsPath: string;
+        examplePath: string;
+        schemaPath: string;
+        instructionsPath: string;
+        responsePath: string;
+        status: 'awaiting-agent' | 'validated' | 'invalid';
+        validationErrors?: string[];
+    };
+}>;

package/dist/commands/compare-image-reference.js

@@ -0,0 +1,82 @@
+import { mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { writeImageReferenceReport } from '../core/report-writer.js';
+import { createRunLogger } from '../core/run-logger.js';
+import { createSideBySideImage } from '../core/side-by-side.js';
+import { startStaticServer } from '../core/static-server.js';
+import { writeImageReferenceSpecPack } from '../core/visual-spec-agent-pack.js';
+import { resolveTarget, resolveWorkspace } from '../core/workspace.js';
+import { capturePage } from '../core/playwright-capture.js';
+export async function compareImageReference(options) {
+    const workspace = resolveWorkspace(options.workspaceRoot);
+    const target = resolveTarget(options.workspaceRoot, options.target);
+    const logger = await createRunLogger(workspace, { command: 'compare', target: options.target, mode: 'image-reference' });
+    const captureDir = path.join(target.capturesDir, 'image-reference');
+    const referencePath = path.join(captureDir, 'reference.png');
+    const sideBySidePath = path.join(captureDir, 'side-by-side.png');
+    let specPaths;
+    let agentSpec;
+    try {
+        await logger.event({ type: 'command.started' });
+        await mkdir(captureDir, { recursive: true });
+        const server = await startStaticServer(target.referenceDir);
+        try {
+            await capturePage({
+                url: server.url,
+                outputPath: referencePath,
+                headed: options.headed,
+                fullPage: options.fullPage,
+            });
+            await createSideBySideImage({ leftPath: target.sourceImagePath, rightPath: referencePath, outputPath: sideBySidePath });
+            if (options.spec) {
+                const specPack = await writeImageReferenceSpecPack({
+                    target,
+                    captureDir,
+                    referenceUrl: server.url,
+                    referencePath,
+                    sideBySidePath,
+                    headed: options.headed,
+                    instructionsPath: options.specInstructions ? path.resolve(options.workspaceRoot, options.specInstructions) : undefined,
+                });
+                specPaths = specPack.specPaths;
+                agentSpec = specPack;
+            }
+        }
+        finally {
+            await server.close();
+        }
+        const reportPath = await writeImageReferenceReport({
+            target,
+            idealPath: target.sourceImagePath,
+            referencePath,
+            sideBySidePath,
+            specPaths,
+            specHighlights: agentSpec?.status === 'validated' ? agentSpec.diffHighlights : undefined,
+            agentSpec,
+        });
+        await logger.artifact(referencePath, 'screenshot');
+        await logger.artifact(sideBySidePath, 'side-by-side');
+        if (agentSpec) {
+            await logger.artifact(agentSpec.promptPath, 'agent-prompt');
+            await logger.artifact(agentSpec.codexPromptPath, 'agent-prompt');
+            await logger.artifact(agentSpec.claudePromptPath, 'agent-prompt');
+            await logger.artifact(agentSpec.factsPath, 'dom-facts');
+            await logger.artifact(agentSpec.examplePath, 'spec-example');
+            await logger.artifact(agentSpec.schemaPath, 'spec-schema');
+        }
+        if (specPaths) {
+            await logger.artifact(specPaths.idealSpecPath, 'visual-spec');
+            await logger.artifact(specPaths.referenceSpecPath, 'visual-spec');
+            await logger.artifact(specPaths.diffPath, 'visual-spec-diff');
+        }
+        await logger.artifact(reportPath, 'report');
+        await logger.complete('ok');
+        return { sideBySidePath, reportPath, specPaths, agentSpec };
+    }
+    catch (error) {
+        await logger.event({ type: 'command.failed', status: 'failed', message: error instanceof Error ? error.message : String(error) });
+        await logger.complete('failed');
+        throw error;
+    }
+}
+//# sourceMappingURL=compare-image-reference.js.map

package/dist/commands/compare-image-reference.js.map

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

package/dist/commands/compare.d.ts

@@ -0,0 +1,15 @@
+import type { Command } from 'commander';
+export { compareImageReference } from './compare-image-reference.js';
+export declare function compareReferenceApp(options: {
+    workspaceRoot: string;
+    target: string;
+    url: string;
+    headed?: boolean;
+    storageState?: string;
+    fullPage?: boolean;
+}): Promise<{
+    sideBySidePath: string;
+    reportPath: string;
+    metricsPath: string;
+}>;
+export declare function registerCompareCommand(program: Command): void;

package/dist/commands/compare.js

@@ -0,0 +1,168 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { loadRegionContract } from '../core/dom-metrics.js';
+import { capturePage } from '../core/playwright-capture.js';
+import { writeReferenceAppReport } from '../core/report-writer.js';
+import { createRunLogger } from '../core/run-logger.js';
+import { createSideBySideImage } from '../core/side-by-side.js';
+import { startStaticServer } from '../core/static-server.js';
+import { resolveTarget, resolveWorkspace } from '../core/workspace.js';
+import { compareImageApp } from './compare-image-app.js';
+import { compareImageReference } from './compare-image-reference.js';
+export { compareImageReference } from './compare-image-reference.js';
+export async function compareReferenceApp(options) {
+    const workspace = resolveWorkspace(options.workspaceRoot);
+    const target = resolveTarget(options.workspaceRoot, options.target);
+    const logger = await createRunLogger(workspace, { command: 'compare', target: options.target, mode: 'reference-app' });
+    const captureDir = path.join(target.capturesDir, 'reference-app');
+    const referencePath = path.join(captureDir, 'reference.png');
+    const appPath = path.join(captureDir, 'app.png');
+    const sideBySidePath = path.join(captureDir, 'side-by-side.png');
+    const metricsPath = path.join(captureDir, 'dom-metrics.json');
+    try {
+        await logger.event({ type: 'command.started' });
+        await mkdir(captureDir, { recursive: true });
+        const contract = await loadRegionContract(target.regionsPath);
+        const server = await startStaticServer(target.referenceDir);
+        let referenceResult;
+        try {
+            referenceResult = await capturePage({
+                url: server.url,
+                outputPath: referencePath,
+                contract,
+                side: 'reference',
+                headed: options.headed,
+                fullPage: options.fullPage,
+            });
+        }
+        finally {
+            await server.close();
+        }
+        const appResult = await capturePage({
+            url: options.url,
+            outputPath: appPath,
+            contract,
+            side: 'app',
+            headed: options.headed,
+            storageState: options.storageState,
+            fullPage: options.fullPage,
+        });
+        await writeFile(metricsPath, JSON.stringify({
+            reference: referenceResult.metrics,
+            app: appResult.metrics,
+            appConsole: appResult.consoleMessages,
+            referenceConsole: referenceResult.consoleMessages,
+        }, null, 2) + '\n');
+        await createSideBySideImage({ leftPath: referencePath, rightPath: appPath, outputPath: sideBySidePath });
+        const reportPath = await writeReferenceAppReport({
+            target,
+            referencePath,
+            appPath,
+            sideBySidePath,
+            referenceMetrics: referenceResult.metrics,
+            appMetrics: appResult.metrics,
+            appUrl: options.url,
+        });
+        await logger.artifact(referencePath, 'screenshot');
+        await logger.artifact(appPath, 'screenshot');
+        await logger.artifact(sideBySidePath, 'side-by-side');
+        await logger.artifact(metricsPath, 'dom-metrics');
+        await logger.artifact(reportPath, 'report');
+        await logger.complete('ok');
+        return { sideBySidePath, reportPath, metricsPath };
+    }
+    catch (error) {
+        await logger.event({ type: 'command.failed', status: 'failed', message: error instanceof Error ? error.message : String(error) });
+        await logger.complete('failed');
+        throw error;
+    }
+}
+export function registerCompareCommand(program) {
+    const compare = program.command('compare').description('Compare Limner artifacts');
+    compare
+        .command('image-reference')
+        .description('Compare source image to reference HTML screenshot')
+        .requiredOption('-t, --target <name>', 'target name')
+        .option('--headed', 'show browser while capturing')
+        .option('--full-page', 'capture the full scrollable page')
+        .option('--spec', 'prepare or validate an agent-authored visual spec pack')
+        .option('--spec-instructions <path>', 'custom visual spec instructions markdown file')
+        .option('--viewport-only', 'capture only the viewport (default)')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        const result = await compareImageReference({
+            workspaceRoot: globals.workspace,
+            target: options.target,
+            headed: options.headed,
+            fullPage: options.fullPage,
+            spec: options.spec,
+            specInstructions: options.specInstructions,
+        });
+        console.log(`Side-by-side: ${result.sideBySidePath}`);
+        if (result.agentSpec) {
+            console.log(`Shared agent prompt: ${result.agentSpec.promptPath}`);
+            console.log(`Codex prompt: ${result.agentSpec.codexPromptPath}`);
+            console.log(`Claude prompt: ${result.agentSpec.claudePromptPath}`);
+            console.log(`Reference DOM facts: ${result.agentSpec.factsPath}`);
+            console.log(`Agent response schema: ${result.agentSpec.schemaPath}`);
+            console.log(`Custom instructions: ${result.agentSpec.instructionsPath}`);
+            console.log(`Agent response target: ${result.agentSpec.responsePath}`);
+        }
+        if (result.specPaths) {
+            console.log(`Ideal visual spec: ${result.specPaths.idealSpecPath}`);
+            console.log(`Reference visual spec: ${result.specPaths.referenceSpecPath}`);
+            console.log(`Visual spec diff: ${result.specPaths.diffPath}`);
+        }
+        else if (options.spec) {
+            console.log('Visual spec status: awaiting validated agent response');
+        }
+        console.log(`Report: ${result.reportPath}`);
+    });
+    compare
+        .command('reference-app')
+        .description('Compare reference HTML to an app URL')
+        .requiredOption('-t, --target <name>', 'target name')
+        .requiredOption('-u, --url <url>', 'app URL')
+        .option('--headed', 'show browser while capturing')
+        .option('--storage-state <path>', 'Playwright storageState JSON for authenticated app captures')
+        .option('--full-page', 'capture the full scrollable page')
+        .option('--viewport-only', 'capture only the viewport (default)')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        const result = await compareReferenceApp({
+            workspaceRoot: globals.workspace,
+            target: options.target,
+            url: options.url,
+            headed: options.headed,
+            storageState: options.storageState,
+            fullPage: options.fullPage,
+        });
+        console.log(`Side-by-side: ${result.sideBySidePath}`);
+        console.log(`Metrics: ${result.metricsPath}`);
+        console.log(`Report: ${result.reportPath}`);
+    });
+    compare
+        .command('image-app')
+        .description('Compare source image directly to an app URL screenshot')
+        .requiredOption('-t, --target <name>', 'target name')
+        .requiredOption('-u, --url <url>', 'app URL')
+        .option('--headed', 'show browser while capturing')
+        .option('--storage-state <path>', 'Playwright storageState JSON for authenticated app captures')
+        .option('--full-page', 'capture the full scrollable page')
+        .option('--viewport-only', 'capture only the viewport (default)')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        const result = await compareImageApp({
+            workspaceRoot: globals.workspace,
+            target: options.target,
+            url: options.url,
+            headed: options.headed,
+            storageState: options.storageState,
+            fullPage: options.fullPage,
+        });
+        console.log(`App screenshot: ${result.appPath}`);
+        console.log(`Side-by-side: ${result.sideBySidePath}`);
+        console.log(`Report: ${result.reportPath}`);
+    });
+}
+//# sourceMappingURL=compare.js.map