yam-flow 0.1.1 → 0.1.2

package/COMMANDS.md

@@ -39,6 +39,14 @@ $ueye
 yam template ueye-comparison
 ```
 
+Opt-in visual evidence helpers:
+
+```bash
+yam ueye capture --url http://localhost:3000 --out .yam/screens/home.png
+yam ueye compare --reference ./reference.png --actual .yam/screens/home.png
+yam proof --route ueye --truth partial --visual "browser/local screenshot comparison executed" --require-visual
+```
+
 ## Review-Only
 
 ```text
@@ -136,6 +144,8 @@ yam proof /path/to/project
 yam proof --route deep --truth verified --command "npm run build: pass"
 yam proof --route ueye --truth verified --visual "reference image only"
 yam proof --route ueye --truth partial --visual-provenance '{"source_kind":"reference","source_hash":"unknown","comparison_result":"not-verified","truth_status":"partial"}'
+yam ueye capture --url http://localhost:3000 --out .yam/screens/home.png
+yam ueye compare --reference ./reference.png --actual .yam/screens/home.png --json
 yam proof --route mission --mission-envelope '{"agent_id":"implementer","assigned_scope":"target component","changed_files":["src/file.ts"],"verification_hint":"npm run typecheck","truth_status":"partial"}'
 yam proof --route deep --truth proven --require-runtime --runtime "mock server fixture"
 yam proof write /path/to/project --route deep --truth partial --command "npm run build: pass"

package/README.md

@@ -127,6 +127,8 @@ yam proof /path/to/project
 yam proof write /path/to/project --route quick --truth verified --command "npm run verify:self: pass"
 yam proof --route ueye --truth verified --visual "reference image only"
 yam proof --route ueye --truth partial --visual-provenance '{"source_kind":"reference","source_hash":"unknown","comparison_result":"not-verified","truth_status":"partial"}'
+yam ueye capture --url http://localhost:3000 --out .yam/screens/home.png
+yam ueye compare --reference ./reference.png --actual .yam/screens/home.png
 yam proof --route mission --mission-envelope '{"agent_id":"implementer","assigned_scope":"target component","changed_files":["src/file.ts"],"verification_hint":"npm run typecheck","truth_status":"partial"}'
 yam release report --json
 yam safety "supabase db reset"
@@ -175,3 +177,18 @@ Publishing still requires confirming the final npm package name and account acce
 - DB/Supabase safety signals
 
 It is implemented locally in `src/lib/trust-kernel.ts` and kept route-scoped. It is not an always-on release gate.
+
+## Ueye Capture And Compare
+
+`$ueye` stays one skill. It starts fast by default, then uses capture/compare only when a visual claim needs real evidence.
+
+```bash
+yam ueye capture --url http://localhost:3000 --out .yam/screens/home.png
+yam ueye compare --reference ./reference.png --actual .yam/screens/home.png --json
+```
+
+`capture` uses a Playwright install from the current project when present, then falls back to the package context. It does not install browsers or add runtime dependencies by itself. If capture is unavailable, the visual claim stays `partial` or `blocked` until a real screenshot is supplied.
+
+`compare` is local-only and dependency-free. It records file hashes, dimensions, comparison result, and proof-ready visual provenance. Exact image matches can be `verified`; different screenshots stay `partial` so visual parity is not overclaimed.
+
+For agent-driven visual QA, prefer the Codex in-app Browser plugin. Use the user's Chrome browser only when explicitly requested or when Chrome-only session/profile state is required.

package/dist/bin/yam.js

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 import { spawnSync } from 'node:child_process';
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import fsp from 'node:fs/promises';
+import { createRequire } from 'node:module';
 import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
@@ -118,6 +120,8 @@ Usage:
   yam tools doctor [dir]
   yam proof [dir|--from file] [--route route] [--truth status] [--command text] [--evidence text]
   yam proof write [dir] [--format json|md] [--out file] [--route route] [--truth status] [--command text]
+  yam ueye capture --url URL --out screenshot.png [--viewport 1440x900] [--full-page] [--json]
+  yam ueye compare --reference ref.png --actual screenshot.png [--json]
   yam release report [--json]
   yam safety [text...]
   yam memory <init|add|list|summary|resolve> [dir] [options]
@@ -1017,6 +1021,271 @@ async function readStdinTextIfAvailable() {
         chunks.push(Buffer.from(chunk));
     return Buffer.concat(chunks).toString('utf8').trim();
 }
+async function ueye(args = []) {
+    const subcommand = args[0] || 'help';
+    if (subcommand === 'help' || subcommand === '--help' || subcommand === '-h')
+        return ueyeUsage();
+    if (subcommand === 'capture')
+        return ueyeCapture(args.slice(1));
+    if (subcommand === 'compare')
+        return ueyeCompare(args.slice(1));
+    console.error(`unknown ueye command: ${subcommand}`);
+    return ueyeUsage();
+}
+function ueyeUsage() {
+    console.log(`yam ueye
+
+Opt-in visual evidence helpers. Ueye stays one skill: fast by default, capture/compare only when verified visual claims need real evidence.
+
+Usage:
+  yam ueye capture --url URL --out screenshot.png [--viewport 1440x900] [--full-page] [--json]
+  yam ueye compare --reference ref.png --actual screenshot.png [--json]
+
+Notes:
+  capture uses a locally available Playwright install when present. It does not download browsers or install dependencies.
+  compare uses local files only and reports sha256, dimensions, comparison_result, and proof-ready visual provenance.
+`);
+}
+async function ueyeCapture(args = []) {
+    if (args[0] === 'help' || args[0] === '--help' || args[0] === '-h')
+        return ueyeUsage();
+    const flags = parseSimpleFlags(args, new Set(['url', 'out', 'viewport', 'wait-until', 'timeout', 'full-page', 'json']));
+    const url = String(flags.url || '');
+    const out = String(flags.out || '');
+    if (!url || !out) {
+        console.error('usage: yam ueye capture --url URL --out screenshot.png [--viewport 1440x900] [--full-page] [--json]');
+        process.exitCode = 1;
+        return;
+    }
+    const target = path.resolve(expandHome(out));
+    const viewport = parseViewport(String(flags.viewport || '1440x900'));
+    const timeout = Number(flags.timeout || 30000);
+    const waitUntil = String(flags.wait_until || 'networkidle');
+    let browser;
+    try {
+        const playwright = await loadOptionalPlaywright();
+        const chromium = playwright?.chromium;
+        if (!chromium)
+            throw new Error('Playwright chromium launcher was not found');
+        await fsp.mkdir(path.dirname(target), { recursive: true });
+        browser = await chromium.launch({ headless: true });
+        const page = await browser.newPage({ viewport });
+        await page.goto(url, { waitUntil, timeout });
+        await page.screenshot({ path: target, fullPage: Boolean(flags.full_page) });
+        const info = await imageFileInfo(target);
+        const result = {
+            schema: 'yam.ueye-capture.v1',
+            status: 'verified',
+            url,
+            out: target,
+            viewport: `${viewport.width}x${viewport.height}`,
+            full_page: Boolean(flags.full_page),
+            sha256: info.sha256,
+            dimensions: info.dimensions,
+            visual_evidence: `browser screenshot captured: ${target} (${info.dimensions}, sha256:${info.sha256})`
+        };
+        printJsonOrHuman(result, Boolean(flags.json), 'Ueye capture');
+    }
+    catch (error) {
+        const result = {
+            schema: 'yam.ueye-capture.v1',
+            status: 'blocked',
+            url,
+            out: target,
+            reason: errorMessage(error),
+            next_action: 'Install Playwright in the current project or provide a user/browser screenshot, then use `yam ueye compare`.',
+            visual_cap: 'blocked'
+        };
+        printJsonOrHuman(result, Boolean(flags.json), 'Ueye capture');
+        process.exitCode = 1;
+    }
+    finally {
+        if (browser)
+            await browser.close().catch(() => { });
+    }
+}
+async function ueyeCompare(args = []) {
+    if (args[0] === 'help' || args[0] === '--help' || args[0] === '-h')
+        return ueyeUsage();
+    const flags = parseSimpleFlags(args, new Set(['reference', 'ref', 'actual', 'screenshot', 'json', 'reference-id', 'screenshot-id']));
+    const reference = String(flags.reference || flags.ref || '');
+    const actual = String(flags.actual || flags.screenshot || '');
+    if (!reference || !actual) {
+        console.error('usage: yam ueye compare --reference ref.png --actual screenshot.png [--json]');
+        process.exitCode = 1;
+        return;
+    }
+    const referencePath = path.resolve(expandHome(reference));
+    const actualPath = path.resolve(expandHome(actual));
+    try {
+        const referenceInfo = await imageFileInfo(referencePath);
+        const actualInfo = await imageFileInfo(actualPath);
+        if (referenceInfo.dimensions === 'unknown' || actualInfo.dimensions === 'unknown') {
+            throw new Error('compare requires image files with readable PNG, JPEG, or GIF dimensions');
+        }
+        const exactMatch = referenceInfo.sha256 === actualInfo.sha256;
+        const sameDimensions = referenceInfo.dimensions === actualInfo.dimensions;
+        const comparisonResult = exactMatch ? 'matched' : 'different';
+        const truthStatus = exactMatch ? 'verified' : 'partial';
+        const provenance = buildUeyeVisualProvenance({
+            source_kind: 'implementation_screenshot',
+            source_path: actualPath,
+            source_hash: actualInfo.sha256,
+            reference_id: String(flags.reference_id || path.basename(referencePath)),
+            screenshot_id: String(flags.screenshot_id || path.basename(actualPath)),
+            local_only: true,
+            redacted: false,
+            operator_provided: false,
+            comparison_result: comparisonResult,
+            truth_status: truthStatus
+        });
+        const result = {
+            schema: 'yam.ueye-compare.v1',
+            status: truthStatus,
+            comparison_result: comparisonResult,
+            exact_match: exactMatch,
+            same_dimensions: sameDimensions,
+            reference: referenceInfo,
+            actual: actualInfo,
+            visual_evidence: `browser/local screenshot comparison executed: reference=${referencePath}, actual=${actualPath}, result=${comparisonResult}`,
+            visual_provenance: provenance,
+            proof_hint: `yam proof --route ueye --truth ${truthStatus} --visual "browser/local screenshot comparison executed: ${comparisonResult}" --visual-provenance '${JSON.stringify(provenance)}' --require-visual`
+        };
+        printJsonOrHuman(result, Boolean(flags.json), 'Ueye compare');
+    }
+    catch (error) {
+        const result = {
+            schema: 'yam.ueye-compare.v1',
+            status: 'blocked',
+            comparison_result: 'not-verified',
+            reason: errorMessage(error),
+            visual_cap: 'blocked'
+        };
+        printJsonOrHuman(result, Boolean(flags.json), 'Ueye compare');
+        process.exitCode = 1;
+    }
+}
+function parseSimpleFlags(args = [], allowed = new Set()) {
+    const flags = {};
+    const positionals = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = String(args[index] || '');
+        if (!arg.startsWith('--')) {
+            positionals.push(arg);
+            continue;
+        }
+        const [rawKey, inlineValue] = arg.includes('=') ? arg.split(/=(.*)/s, 2) : [arg, undefined];
+        const key = rawKey.slice(2);
+        if (allowed.size && !allowed.has(key))
+            continue;
+        const normalizedKey = key.replace(/-/g, '_');
+        if (['json', 'full-page'].includes(key)) {
+            flags[normalizedKey] = true;
+            continue;
+        }
+        const value = inlineValue ?? args[index + 1] ?? '';
+        if (inlineValue === undefined)
+            index += 1;
+        flags[normalizedKey] = value;
+    }
+    flags._ = positionals;
+    return flags;
+}
+function parseViewport(value = '1440x900') {
+    const match = String(value || '').match(/^(\d{2,5})x(\d{2,5})$/i);
+    if (!match)
+        return { width: 1440, height: 900 };
+    return { width: Number(match[1]), height: Number(match[2]) };
+}
+async function loadOptionalPlaywright() {
+    let projectError = '';
+    try {
+        const projectRequire = createRequire(path.join(process.cwd(), 'package.json'));
+        return projectRequire('playwright');
+    }
+    catch (error) {
+        projectError = errorMessage(error);
+        // Fall through to the yam package context for local development or bundled installs.
+    }
+    const dynamicImport = new Function('specifier', 'return import(specifier)');
+    try {
+        return await dynamicImport('playwright');
+    }
+    catch (error) {
+        throw new Error(`Playwright not found from current project or yam package context. Current project: ${projectError}; package context: ${errorMessage(error)}`);
+    }
+}
+async function imageFileInfo(file) {
+    const absolute = path.resolve(expandHome(file));
+    const buffer = await fsp.readFile(absolute);
+    const stat = await fsp.stat(absolute);
+    return {
+        path: absolute,
+        sha256: crypto.createHash('sha256').update(buffer).digest('hex'),
+        bytes: stat.size,
+        dimensions: imageDimensions(buffer)
+    };
+}
+function imageDimensions(buffer) {
+    const png = pngDimensions(buffer);
+    if (png)
+        return png;
+    const jpeg = jpegDimensions(buffer);
+    if (jpeg)
+        return jpeg;
+    const gif = gifDimensions(buffer);
+    if (gif)
+        return gif;
+    return 'unknown';
+}
+function pngDimensions(buffer) {
+    if (buffer.length < 24)
+        return '';
+    if (buffer.readUInt32BE(0) !== 0x89504e47 || buffer.readUInt32BE(4) !== 0x0d0a1a0a)
+        return '';
+    return `${buffer.readUInt32BE(16)}x${buffer.readUInt32BE(20)}`;
+}
+function gifDimensions(buffer) {
+    if (buffer.length < 10)
+        return '';
+    const signature = buffer.toString('ascii', 0, 6);
+    if (signature !== 'GIF87a' && signature !== 'GIF89a')
+        return '';
+    return `${buffer.readUInt16LE(6)}x${buffer.readUInt16LE(8)}`;
+}
+function jpegDimensions(buffer) {
+    if (buffer.length < 4 || buffer[0] !== 0xff || buffer[1] !== 0xd8)
+        return '';
+    let offset = 2;
+    while (offset < buffer.length) {
+        if (buffer[offset] !== 0xff)
+            return '';
+        const marker = buffer[offset + 1];
+        const length = buffer.readUInt16BE(offset + 2);
+        if (marker >= 0xc0 && marker <= 0xc3 && offset + 8 < buffer.length) {
+            return `${buffer.readUInt16BE(offset + 7)}x${buffer.readUInt16BE(offset + 5)}`;
+        }
+        offset += 2 + length;
+    }
+    return '';
+}
+function printJsonOrHuman(result, json = false, label = 'yam') {
+    if (json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    console.log(label);
+    for (const [key, value] of Object.entries(result)) {
+        if (key === 'schema')
+            continue;
+        if (typeof value === 'object' && value !== null) {
+            console.log(`- ${key}: ${JSON.stringify(value)}`);
+        }
+        else {
+            console.log(`- ${key}: ${value}`);
+        }
+    }
+}
 function detectDbSafetyText(text = '') {
     return detectTrustDbSafetyText(text);
 }
@@ -2112,6 +2381,8 @@ async function main() {
         return tools(process.argv.slice(3));
     if (command === 'proof')
         return proof(process.argv.slice(3));
+    if (command === 'ueye')
+        return ueye(process.argv.slice(3));
     if (command === 'release')
         return release(process.argv.slice(3));
     if (command === 'safety')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yam-flow",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Progressive proof-first agent flow: start fast, deepen deliberately, stay honest by design.",
   "type": "module",
   "author": "0kim0bos",
@@ -96,6 +96,7 @@
   "license": "MIT",
   "devDependencies": {
     "@types/node": "^25.9.1",
+    "playwright": "^1.60.0",
     "typescript": "^6.0.3"
   }
 }

package/references/ueye-proof.md

@@ -19,6 +19,26 @@ Skip or compress them when:
 
 ## Artifact Set
 
+### Opt-In CLI Helpers
+
+Ueye is one route. It should not split into separate lite/deep skills. Use these helpers only when the current visual claim needs real evidence:
+
+```bash
+yam ueye capture --url http://localhost:3000 --out .yam/screens/home.png
+yam ueye compare --reference ./reference.png --actual .yam/screens/home.png --json
+```
+
+- `capture` uses a Playwright install from the current project when present, then reports `blocked` instead of installing dependencies or pretending a screenshot exists.
+- `compare` is local-only and dependency-free. It records hashes, dimensions, comparison result, and visual provenance. Different screenshots stay `partial`; exact file matches can be `verified`.
+- Without capture or user-provided screenshots, report implementation/source review separately from visual verification and cap the visual claim.
+
+### Browser Preference
+
+- Prefer the Codex in-app Browser plugin for local pages, localhost, file URLs, and ordinary visual QA.
+- Do not silently switch to the user's Chrome browser when the in-app Browser cannot capture or inspect.
+- Use Chrome only when the user explicitly asks for it, or when the task requires existing Chrome cookies, sessions, extensions, or profile state.
+- If the in-app Browser is unavailable and Chrome was not explicitly requested or required, cap the visual claim at `partial` or `blocked`.
+
 ### Visual Evidence Inventory
 
 Purpose: identify what visual sources were inspected.

package/skills/ueye/SKILL.md

@@ -35,6 +35,8 @@ Do not use for:
 - Generated annotated images are optional, not a default gate.
 - Image evidence should stay bounded: inspect the primary screen first, then only the states/images needed to support the claim.
 - Design quality judgment belongs after implementation/review: compare to the reference first, then judge whether the result is good design.
+- Keep Ueye as one route: start fast, then opt into `yam ueye capture` and `yam ueye compare` only when a `verified` visual claim needs real screen evidence.
+- Prefer the Codex in-app Browser plugin for interactive visual checks. Do not switch to the user's Chrome browser unless the user explicitly asks for Chrome or the task requires existing Chrome cookies, sessions, extensions, or profile state.
 
 ## Workflow
 
@@ -52,6 +54,10 @@ Do not use for:
 6. Implement the smallest coherent design improvement when implementation is requested.
 7. Check default, loading, error, empty, disabled, hover/focus, and mobile states when relevant.
 8. Run browser/screenshot verification when feasible.
+   - Prefer the Codex in-app Browser plugin for local pages, localhost, file URLs, and ordinary visual QA.
+   - Do not silently use Chrome as a fallback. If the in-app Browser cannot capture or inspect, report the visual cap as `partial` or `blocked`.
+   - Use `yam ueye capture --url URL --out path.png` when a local Playwright install is available and the claim needs real browser evidence.
+   - Use `yam ueye compare --reference ref.png --actual shot.png` when reference fidelity needs a proof-ready local comparison record.
 9. Compare reference and implementation when reference fidelity was requested:
    - matched, similar, different, not-applicable, or not-verified.
    - Separate "faithful to reference" from "good design."

package/src/bin/yam.ts

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 import { spawnSync } from 'node:child_process';
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import fsp from 'node:fs/promises';
+import { createRequire } from 'node:module';
 import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
@@ -132,6 +134,8 @@ Usage:
   yam tools doctor [dir]
   yam proof [dir|--from file] [--route route] [--truth status] [--command text] [--evidence text]
   yam proof write [dir] [--format json|md] [--out file] [--route route] [--truth status] [--command text]
+  yam ueye capture --url URL --out screenshot.png [--viewport 1440x900] [--full-page] [--json]
+  yam ueye compare --reference ref.png --actual screenshot.png [--json]
   yam release report [--json]
   yam safety [text...]
   yam memory <init|add|list|summary|resolve> [dir] [options]
@@ -1010,6 +1014,261 @@ async function readStdinTextIfAvailable() {
   return Buffer.concat(chunks).toString('utf8').trim();
 }
 
+async function ueye(args = []) {
+  const subcommand = args[0] || 'help';
+  if (subcommand === 'help' || subcommand === '--help' || subcommand === '-h') return ueyeUsage();
+  if (subcommand === 'capture') return ueyeCapture(args.slice(1));
+  if (subcommand === 'compare') return ueyeCompare(args.slice(1));
+  console.error(`unknown ueye command: ${subcommand}`);
+  return ueyeUsage();
+}
+
+function ueyeUsage() {
+  console.log(`yam ueye
+
+Opt-in visual evidence helpers. Ueye stays one skill: fast by default, capture/compare only when verified visual claims need real evidence.
+
+Usage:
+  yam ueye capture --url URL --out screenshot.png [--viewport 1440x900] [--full-page] [--json]
+  yam ueye compare --reference ref.png --actual screenshot.png [--json]
+
+Notes:
+  capture uses a locally available Playwright install when present. It does not download browsers or install dependencies.
+  compare uses local files only and reports sha256, dimensions, comparison_result, and proof-ready visual provenance.
+`);
+}
+
+async function ueyeCapture(args = []) {
+  if (args[0] === 'help' || args[0] === '--help' || args[0] === '-h') return ueyeUsage();
+  const flags = parseSimpleFlags(args, new Set(['url', 'out', 'viewport', 'wait-until', 'timeout', 'full-page', 'json']));
+  const url = String(flags.url || '');
+  const out = String(flags.out || '');
+  if (!url || !out) {
+    console.error('usage: yam ueye capture --url URL --out screenshot.png [--viewport 1440x900] [--full-page] [--json]');
+    process.exitCode = 1;
+    return;
+  }
+
+  const target = path.resolve(expandHome(out));
+  const viewport = parseViewport(String(flags.viewport || '1440x900'));
+  const timeout = Number(flags.timeout || 30000);
+  const waitUntil = String(flags.wait_until || 'networkidle');
+  let browser;
+
+  try {
+    const playwright = await loadOptionalPlaywright();
+    const chromium = playwright?.chromium;
+    if (!chromium) throw new Error('Playwright chromium launcher was not found');
+    await fsp.mkdir(path.dirname(target), { recursive: true });
+    browser = await chromium.launch({ headless: true });
+    const page = await browser.newPage({ viewport });
+    await page.goto(url, { waitUntil, timeout });
+    await page.screenshot({ path: target, fullPage: Boolean(flags.full_page) });
+    const info = await imageFileInfo(target);
+    const result = {
+      schema: 'yam.ueye-capture.v1',
+      status: 'verified',
+      url,
+      out: target,
+      viewport: `${viewport.width}x${viewport.height}`,
+      full_page: Boolean(flags.full_page),
+      sha256: info.sha256,
+      dimensions: info.dimensions,
+      visual_evidence: `browser screenshot captured: ${target} (${info.dimensions}, sha256:${info.sha256})`
+    };
+    printJsonOrHuman(result, Boolean(flags.json), 'Ueye capture');
+  } catch (error) {
+    const result = {
+      schema: 'yam.ueye-capture.v1',
+      status: 'blocked',
+      url,
+      out: target,
+      reason: errorMessage(error),
+      next_action: 'Install Playwright in the current project or provide a user/browser screenshot, then use `yam ueye compare`.',
+      visual_cap: 'blocked'
+    };
+    printJsonOrHuman(result, Boolean(flags.json), 'Ueye capture');
+    process.exitCode = 1;
+  } finally {
+    if (browser) await browser.close().catch(() => {});
+  }
+}
+
+async function ueyeCompare(args = []) {
+  if (args[0] === 'help' || args[0] === '--help' || args[0] === '-h') return ueyeUsage();
+  const flags = parseSimpleFlags(args, new Set(['reference', 'ref', 'actual', 'screenshot', 'json', 'reference-id', 'screenshot-id']));
+  const reference = String(flags.reference || flags.ref || '');
+  const actual = String(flags.actual || flags.screenshot || '');
+  if (!reference || !actual) {
+    console.error('usage: yam ueye compare --reference ref.png --actual screenshot.png [--json]');
+    process.exitCode = 1;
+    return;
+  }
+
+  const referencePath = path.resolve(expandHome(reference));
+  const actualPath = path.resolve(expandHome(actual));
+  try {
+    const referenceInfo = await imageFileInfo(referencePath);
+    const actualInfo = await imageFileInfo(actualPath);
+    if (referenceInfo.dimensions === 'unknown' || actualInfo.dimensions === 'unknown') {
+      throw new Error('compare requires image files with readable PNG, JPEG, or GIF dimensions');
+    }
+    const exactMatch = referenceInfo.sha256 === actualInfo.sha256;
+    const sameDimensions = referenceInfo.dimensions === actualInfo.dimensions;
+    const comparisonResult = exactMatch ? 'matched' : 'different';
+    const truthStatus = exactMatch ? 'verified' : 'partial';
+    const provenance = buildUeyeVisualProvenance({
+      source_kind: 'implementation_screenshot',
+      source_path: actualPath,
+      source_hash: actualInfo.sha256,
+      reference_id: String(flags.reference_id || path.basename(referencePath)),
+      screenshot_id: String(flags.screenshot_id || path.basename(actualPath)),
+      local_only: true,
+      redacted: false,
+      operator_provided: false,
+      comparison_result: comparisonResult,
+      truth_status: truthStatus
+    });
+    const result = {
+      schema: 'yam.ueye-compare.v1',
+      status: truthStatus,
+      comparison_result: comparisonResult,
+      exact_match: exactMatch,
+      same_dimensions: sameDimensions,
+      reference: referenceInfo,
+      actual: actualInfo,
+      visual_evidence: `browser/local screenshot comparison executed: reference=${referencePath}, actual=${actualPath}, result=${comparisonResult}`,
+      visual_provenance: provenance,
+      proof_hint: `yam proof --route ueye --truth ${truthStatus} --visual "browser/local screenshot comparison executed: ${comparisonResult}" --visual-provenance '${JSON.stringify(provenance)}' --require-visual`
+    };
+    printJsonOrHuman(result, Boolean(flags.json), 'Ueye compare');
+  } catch (error) {
+    const result = {
+      schema: 'yam.ueye-compare.v1',
+      status: 'blocked',
+      comparison_result: 'not-verified',
+      reason: errorMessage(error),
+      visual_cap: 'blocked'
+    };
+    printJsonOrHuman(result, Boolean(flags.json), 'Ueye compare');
+    process.exitCode = 1;
+  }
+}
+
+function parseSimpleFlags(args = [], allowed = new Set<string>()) {
+  const flags: AnyRecord = {};
+  const positionals: string[] = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = String(args[index] || '');
+    if (!arg.startsWith('--')) {
+      positionals.push(arg);
+      continue;
+    }
+    const [rawKey, inlineValue] = arg.includes('=') ? arg.split(/=(.*)/s, 2) : [arg, undefined];
+    const key = rawKey.slice(2);
+    if (allowed.size && !allowed.has(key)) continue;
+    const normalizedKey = key.replace(/-/g, '_');
+    if (['json', 'full-page'].includes(key)) {
+      flags[normalizedKey] = true;
+      continue;
+    }
+    const value = inlineValue ?? args[index + 1] ?? '';
+    if (inlineValue === undefined) index += 1;
+    flags[normalizedKey] = value;
+  }
+  flags._ = positionals;
+  return flags;
+}
+
+function parseViewport(value = '1440x900') {
+  const match = String(value || '').match(/^(\d{2,5})x(\d{2,5})$/i);
+  if (!match) return { width: 1440, height: 900 };
+  return { width: Number(match[1]), height: Number(match[2]) };
+}
+
+async function loadOptionalPlaywright() {
+  let projectError = '';
+  try {
+    const projectRequire = createRequire(path.join(process.cwd(), 'package.json'));
+    return projectRequire('playwright');
+  } catch (error) {
+    projectError = errorMessage(error);
+    // Fall through to the yam package context for local development or bundled installs.
+  }
+  const dynamicImport = new Function('specifier', 'return import(specifier)') as (specifier: string) => Promise<any>;
+  try {
+    return await dynamicImport('playwright');
+  } catch (error) {
+    throw new Error(`Playwright not found from current project or yam package context. Current project: ${projectError}; package context: ${errorMessage(error)}`);
+  }
+}
+
+async function imageFileInfo(file) {
+  const absolute = path.resolve(expandHome(file));
+  const buffer = await fsp.readFile(absolute);
+  const stat = await fsp.stat(absolute);
+  return {
+    path: absolute,
+    sha256: crypto.createHash('sha256').update(buffer).digest('hex'),
+    bytes: stat.size,
+    dimensions: imageDimensions(buffer)
+  };
+}
+
+function imageDimensions(buffer) {
+  const png = pngDimensions(buffer);
+  if (png) return png;
+  const jpeg = jpegDimensions(buffer);
+  if (jpeg) return jpeg;
+  const gif = gifDimensions(buffer);
+  if (gif) return gif;
+  return 'unknown';
+}
+
+function pngDimensions(buffer) {
+  if (buffer.length < 24) return '';
+  if (buffer.readUInt32BE(0) !== 0x89504e47 || buffer.readUInt32BE(4) !== 0x0d0a1a0a) return '';
+  return `${buffer.readUInt32BE(16)}x${buffer.readUInt32BE(20)}`;
+}
+
+function gifDimensions(buffer) {
+  if (buffer.length < 10) return '';
+  const signature = buffer.toString('ascii', 0, 6);
+  if (signature !== 'GIF87a' && signature !== 'GIF89a') return '';
+  return `${buffer.readUInt16LE(6)}x${buffer.readUInt16LE(8)}`;
+}
+
+function jpegDimensions(buffer) {
+  if (buffer.length < 4 || buffer[0] !== 0xff || buffer[1] !== 0xd8) return '';
+  let offset = 2;
+  while (offset < buffer.length) {
+    if (buffer[offset] !== 0xff) return '';
+    const marker = buffer[offset + 1];
+    const length = buffer.readUInt16BE(offset + 2);
+    if (marker >= 0xc0 && marker <= 0xc3 && offset + 8 < buffer.length) {
+      return `${buffer.readUInt16BE(offset + 7)}x${buffer.readUInt16BE(offset + 5)}`;
+    }
+    offset += 2 + length;
+  }
+  return '';
+}
+
+function printJsonOrHuman(result, json = false, label = 'yam') {
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.log(label);
+  for (const [key, value] of Object.entries(result)) {
+    if (key === 'schema') continue;
+    if (typeof value === 'object' && value !== null) {
+      console.log(`- ${key}: ${JSON.stringify(value)}`);
+    } else {
+      console.log(`- ${key}: ${value}`);
+    }
+  }
+}
+
 function detectDbSafetyText(text = '') {
   return detectTrustDbSafetyText(text);
 }
@@ -2105,6 +2364,7 @@ async function main() {
   if (command === 'measure') return measure(process.argv[3], process.argv.slice(4));
   if (command === 'tools') return tools(process.argv.slice(3));
   if (command === 'proof') return proof(process.argv.slice(3));
+  if (command === 'ueye') return ueye(process.argv.slice(3));
   if (command === 'release') return release(process.argv.slice(3));
   if (command === 'safety') return safety(process.argv.slice(3));
   if (command === 'memory') return memory(process.argv.slice(3));