@appliqation/visual-regression 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Appliqation Pty Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,87 @@
+# Appliqation Visual-Regression
+
+**Checks one route for a real visual regression by diffing it against its own live production counterpart — no stored baseline files, no manual baseline-approval workflow.**
+
+Point it at a route and a test case — it navigates to that route on production and a target environment, masks any known dynamic regions, full-page screenshots both, pixel-diffs them for real, and has a model judge the result from the actual evidence: a genuine regression, an expected divergence, or a route that simply doesn't exist on production yet (declines rather than substituting any other baseline).
+
+## Why this exists
+
+A Playwright `getByRole` assertion can pass while the page looks broken — an overlapping modal, a button pushed off-screen by a CSS regression, invisible text from a contrast bug. Nothing else in this agent family checks appearance, only behaviour. Traditional visual-regression tooling solves this with a stored baseline image that a human has to keep re-approving every time a legitimate UI change ships — in practice, that maintenance burden is what kills most setups. This agent sidesteps it entirely by using **production itself as the baseline, fetched live at comparison time**. Production always represents current truth by definition; there's nothing to store or re-approve.
+
+## The one rule that matters more than anything else here
+
+**If the route doesn't exist on production, that's not a failure — it's not applicable.** This agent never falls back to comparing against a design file or mock (a live render vs. a Figma file is a different, unreliable problem — design fidelity, not regression detection). No production equivalent means no comparison, reported plainly, nothing forced.
+
+The mechanical work — navigating both environments, masking, screenshotting, pixel-diffing — is entirely code-owned, never something the model claims: it happens inside one atomic `capture_and_diff` call, and the real diff statistics it returns are what the model is required to cite, never a number it asserts on its own. The model's only real job is judgment, reported back through a structured `submit_verdict` call rather than free-text prose — the same discipline `appq:autotest-validator` already uses for its own verdicts.
+
+## Quick start
+
+```bash
+npm install -g @appliqation/visual-regression
+npx playwright install chromium
+```
+
+Create a `.env` file (in whatever directory you'll run it from) with:
+
+```
+APPQ_API_KEY=your-appliqation-api-key   # read-only is enough
+ANTHROPIC_API_KEY=your-anthropic-key    # or OPENAI_API_KEY — pick one
+```
+
+```bash
+appliqation-visual-regression check \
+  --test-case-uuid 1350-2732cd99-81d6-44ce-a053-1aa2e2efc42c \
+  --route /subscribe \
+  --baseline-environment Prod \
+  --target-environment Stage \
+  --mask ".reader-count" \
+  --mask "[data-testid=timestamp]"
+```
+
+Add `--json`/`--ci` for a structured summary. The exit code is 0 for `expected-divergence`/`not-applicable`, 1 for `regression`/`inconclusive` (fail-closed on ambiguity) — the JSON summary's `verdict` field is what actually distinguishes the outcomes, not the exit code alone.
+
+## What this agent does not do (on purpose)
+
+- **No route enumeration or inference.** `--route` is always explicit — there's no structured route data on a scenario/test case to derive it from (confirmed: routes only ever exist inside free-text step descriptions). A real caller with a just-completed run derives it from real observed navigation data (`get_execution_evidence`), never by guessing at step text.
+- **No auto-detection of dynamic regions.** `--mask` is caller-supplied CSS selectors only. The model already has to reason about "is this difference data-driven or a real break" regardless, so masking is an optimization, not a prerequisite.
+- **No write capability.** This agent never calls an Appliqation write tool and never files a defect — it reports a verdict, nothing else. What happens to a confirmed regression (or a secondary observation) is entirely the caller's decision.
+- **No ID/slug-based dynamic-content routes.** `/blog/123` on staging has no reliable way to be matched to its "equivalent" content on production (`/blog/345`) without this agent guessing at content equivalence — a single `--route` assumes path identity means content identity. Static, stable routes only.
+- **No multi-step workflow replay.** This agent navigates directly to a URL — it doesn't replay a login flow or rebuild cart state. Auth-gated pages are covered via `--storage-state`; deeper application state built up through a workflow is not.
+
+## Primary finding vs. secondary observations
+
+A full-page diff can surface something real that's unrelated to what the check was actually for. The verdict carries one **primary finding** (what drove the classification) and a separate list of **secondary observations** — other real differences noticed elsewhere on the page. Secondary observations are always reported, never silently dropped, and never affect the verdict or exit code.
+
+## Configuration
+
+Copy `.env.example` to `.env`. Requires `APPQ_API_KEY` (read-only access is sufficient — this agent never calls an appq write tool) and one of `ANTHROPIC_API_KEY`/`OPENAI_API_KEY`.
+
+## Running this safely
+
+This agent has a real browser and navigates to whatever URLs `--baseline-environment`/`--target-environment` resolve to — it has no filesystem write access and no shell surface at all (unlike `heal-selector`/`scriptgen`, it never patches anything).
+
+**Run this inside a container with an egress allowlist**, same as every agent in this family. This process only ever legitimately needs to reach:
+
+- your LLM provider (`api.anthropic.com` or `api.openai.com`)
+- your configured `APPQ_ORIGIN` (`appq.appliqation.io` by default)
+- the two sites under test — whatever `--baseline-environment`/`--target-environment` resolve to
+
+Anything else this process tries to reach is unexpected and worth investigating.
+
+## Development
+
+```bash
+git clone https://github.com/appliqation/visual-regression.git
+cd visual-regression
+npm install
+cp .env.example .env   # fill in APPQ_API_KEY (read-only) and an LLM key
+npm run dev -- check --test-case-uuid <uuid> --route </path> --baseline-environment <name> --target-environment <name>
+npm run typecheck
+npm test
+```
+
+See `CLAUDE.md` for a map of this repo if you're working in it with an AI coding assistant.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/cli/audit.js

@@ -0,0 +1,37 @@
+// Extracted out of cli/index.ts so this is testable without triggering that
+// file's top-level program.parseAsync(process.argv) side effect — same
+// reasoning as every sibling agent's audit module.
+import { safeRecord, safeClose } from '@appliqation/agent-core';
+import { exitCodeFor } from './output.js';
+export async function recordVisualRegressionRun(args) {
+    const { sink, startedAt, endedAt, model, usage, route, baselineUrl, targetUrl, testCaseUuid, result } = args;
+    const summary = result
+        ? {
+            route,
+            baselineUrl,
+            targetUrl,
+            diffRan: result.diffRan,
+            diffPixelCount: result.diffPixelCount,
+            diffPercentage: result.diffPercentage,
+            verdict: (result.verdict ?? 'inconclusive'),
+            primaryFinding: result.primaryFinding,
+            secondaryFindings: result.secondaryFindings,
+            report: result.report,
+        }
+        : undefined;
+    await safeRecord(sink, {
+        agent: 'appliqation-visual-regression',
+        subcommand: 'check',
+        startedAt,
+        endedAt,
+        durationMillis: endedAt - startedAt,
+        model,
+        usage,
+        turns: result?.turns,
+        budgetExceeded: result?.budgetExceeded,
+        exitCode: summary ? exitCodeFor(summary) : 1,
+        outcome: summary ? { ...summary, testCaseUuid } : { route, baselineUrl, targetUrl, testCaseUuid, error: true },
+    });
+    await safeClose(sink);
+}
+//# sourceMappingURL=audit.js.map

package/dist/cli/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../src/cli/audit.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,uEAAuE;AACvE,mDAAmD;AAEnD,OAAO,EAAE,UAAU,EAAE,SAAS,EAAoC,MAAM,yBAAyB,CAAC;AAElG,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAiB1C,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAAC,IAAmC;IACjF,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAC7G,MAAM,OAAO,GAAwC,MAAM;QACzD,CAAC,CAAC;YACE,KAAK;YACL,WAAW;YACX,SAAS;YACT,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,cAAc,EAAE,MAAM,CAAC,cAAc;YACrC,cAAc,EAAE,MAAM,CAAC,cAAc;YACrC,OAAO,EAAE,CAAC,MAAM,CAAC,OAAO,IAAI,cAAc,CAAY;YACtD,cAAc,EAAE,MAAM,CAAC,cAAc;YACrC,iBAAiB,EAAE,MAAM,CAAC,iBAAiB;YAC3C,MAAM,EAAE,MAAM,CAAC,MAAM;SACtB;QACH,CAAC,CAAC,SAAS,CAAC;IAEd,MAAM,UAAU,CAAC,IAAI,EAAE;QACrB,KAAK,EAAE,+BAA+B;QACtC,UAAU,EAAE,OAAO;QACnB,SAAS;QACT,OAAO;QACP,cAAc,EAAE,OAAO,GAAG,SAAS;QACnC,KAAK;QACL,KAAK;QACL,KAAK,EAAE,MAAM,EAAE,KAAK;QACpB,cAAc,EAAE,MAAM,EAAE,cAAc;QACtC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5C,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,OAAO,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,YAAY,EAAE,KAAK,EAAE,IAAI,EAAE;KAC/G,CAAC,CAAC;IACH,MAAM,SAAS,CAAC,IAAI,CAAC,CAAC;AACxB,CAAC"}

package/dist/cli/index.js

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+// `check`: compare one route between production and a target environment for
+// a real visual regression. See src/orchestrator/visualRegression.ts for the
+// mechanism and src/policy/visualRegressionPrompt.ts for the actual
+// methodology (no appq-served prompt exists for this yet — the policy is
+// local, bundled here).
+//
+// Generic, caller-agnostic inputs — not designed around any one caller.
+// project_id is always derived from --test-case-uuid, never accepted as a
+// separate input, same reasoning as every sibling agent. --route stays a
+// single, caller-supplied string — no route enumeration/inference (no
+// structured route data exists on scenarios/test cases to derive it from).
+import { Command } from 'commander';
+import { createMcpClient, createAnthropicAdapter, createOpenAiAdapter, createUsageAccumulator, resolveScenarioId, fetchScenarioInfo, resolveUrl, } from '@appliqation/agent-core';
+import { config, resolveProvider, resolveModel } from '../config/env.js';
+import { checkVisualRegression } from '../orchestrator/visualRegression.js';
+import { recordVisualRegressionRun } from './audit.js';
+import { printJsonSummary, printHumanSummary, exitCodeFor } from './output.js';
+const client = createMcpClient({ origin: config.appqOrigin, apiKey: config.appqApiKey() });
+function buildAdapter() {
+    const provider = resolveProvider();
+    const model = resolveModel();
+    return provider === 'anthropic'
+        ? createAnthropicAdapter(config.anthropicApiKey, model, config.anthropicMaxTokens)
+        : createOpenAiAdapter(config.openaiApiKey, model, config.openaiMaxOutputTokens);
+}
+function logEvent(prefix) {
+    return (e) => {
+        if (e.type === 'assistant') {
+            const text = (e.detail ?? '').trim();
+            if (text)
+                console.error(`${prefix}[thinking] ${text}`);
+        }
+        else if (e.type === 'tool') {
+            const d = e.detail;
+            console.error(`${prefix}[tool] ${d.name} -> ${d.result.slice(0, 300)}`);
+        }
+        else if (e.type === 'log') {
+            console.error(`${prefix}[log] ${e.detail}`);
+        }
+        else if (e.type === 'usage') {
+            const u = e.detail;
+            const cacheNote = u.cacheReadTokens
+                ? ` (${u.cacheReadTokens} from cache)`
+                : u.cacheWriteTokens
+                    ? ` (${u.cacheWriteTokens} written to cache)`
+                    : '';
+            console.error(`${prefix}[usage] in=${u.inputTokens} out=${u.outputTokens}${cacheNote}`);
+        }
+    };
+}
+function collect(value, previous) {
+    return [...previous, value];
+}
+/** Joins a base environment URL with a route path — an absolute route (leading "/") replaces the base's own path, same as any URL resolution. */
+function joinRoute(baseUrl, route) {
+    return new URL(route, baseUrl).toString();
+}
+const program = new Command();
+program
+    .name('appliqation-visual-regression')
+    .description('Check one route for a real visual regression by diffing it against its own live production ' +
+    'counterpart — no stored baseline files, no manual baseline-approval workflow. Declines rather than ' +
+    'compares when the route does not exist on production. See README.md for the full story.');
+program
+    .command('check')
+    .description('Navigate to the same route on a baseline (production) and target environment, mask configured ' +
+    'dynamic regions, full-page screenshot both, pixel-diff them for real, and have the model judge ' +
+    "regression vs. expected divergence vs. inconclusive — never the model's own claim about the pixels, " +
+    'always the real diff it was actually shown.')
+    .requiredOption('--test-case-uuid <uuid>', 'test case this route belongs to — derives project_id, supplies expected_result context')
+    .requiredOption('--route </path>', 'the route to check, e.g. /subscribe — same route is checked on both environments')
+    .requiredOption('--baseline-environment <name>', 'environment name treated as the source of truth (commonly, but not necessarily, "Prod")')
+    .requiredOption('--target-environment <name>', 'environment name being checked against the baseline')
+    .option('--mask <selector>', 'CSS selector to mask before capturing (repeatable) — reduces noise on known dynamic regions', collect, [])
+    .option('--storage-state <path>', 'Playwright storageState file, for auth-gated routes')
+    .option('--max-turns <n>', 'override BUDGET_MAX_TURNS for this run')
+    .option('--json', 'print a single structured JSON summary on stdout instead of a human-readable report')
+    .option('--ci', 'shorthand for --json; exit code already reflects the real verdict either way')
+    .action(async (opts) => {
+    const json = (opts.json ?? false) || (opts.ci ?? false);
+    const adapter = buildAdapter();
+    const scenarioId = resolveScenarioId({ testCaseUuid: opts.testCaseUuid });
+    const { projectId } = await fetchScenarioInfo(client, scenarioId);
+    const [baselineBaseUrl, targetBaseUrl] = await Promise.all([
+        resolveUrl(client, opts.baselineEnvironment, projectId),
+        resolveUrl(client, opts.targetEnvironment, projectId),
+    ]);
+    const baselineUrl = joinRoute(baselineBaseUrl, opts.route);
+    const targetUrl = joinRoute(targetBaseUrl, opts.route);
+    const budget = { ...config.budget, ...(opts.maxTurns ? { maxTurns: Number(opts.maxTurns) } : {}) };
+    const startedAt = Date.now();
+    const usage = createUsageAccumulator();
+    const baseLog = logEvent('');
+    let result;
+    try {
+        result = await checkVisualRegression({
+            client,
+            adapter,
+            testCaseUuid: opts.testCaseUuid,
+            route: opts.route,
+            baselineUrl,
+            targetUrl,
+            maskSelectors: opts.mask,
+            storageStatePath: opts.storageState,
+            budget,
+            onEvent: (e) => {
+                baseLog(e);
+                if (e.type === 'usage')
+                    usage.onUsage(e.detail);
+            },
+        });
+    }
+    finally {
+        // Audit write happens whether the run succeeded or threw — see
+        // @appliqation/agent-core's audit/sink.ts: safeRecord() (used inside
+        // recordVisualRegressionRun) never lets a failed/unreachable audit
+        // sink affect this process's real outcome.
+        await recordVisualRegressionRun({
+            sink: config.auditSink,
+            startedAt,
+            endedAt: Date.now(),
+            model: resolveModel(),
+            usage: usage.totals(),
+            route: opts.route,
+            baselineUrl,
+            targetUrl,
+            testCaseUuid: opts.testCaseUuid,
+            result,
+        });
+    }
+    if (!json) {
+        console.log('\n=== Report ===\n');
+        console.log(result.report);
+        console.error(`\n(${result.turns} turns, budget exceeded: ${result.budgetExceeded})`);
+    }
+    const summary = {
+        route: opts.route,
+        baselineUrl,
+        targetUrl,
+        diffRan: result.diffRan,
+        diffPixelCount: result.diffPixelCount,
+        diffPercentage: result.diffPercentage,
+        verdict: (result.verdict ?? 'inconclusive'),
+        primaryFinding: result.primaryFinding,
+        secondaryFindings: result.secondaryFindings,
+        report: result.report,
+    };
+    if (json)
+        printJsonSummary(summary);
+    else
+        printHumanSummary(summary);
+    process.exitCode = exitCodeFor(summary);
+});
+program.parseAsync(process.argv).catch((err) => {
+    console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+    process.exitCode = 1;
+});
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

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

package/dist/cli/output.js

@@ -0,0 +1,32 @@
+// --json/--ci's renderer, matching the family's shape (heal-selector/
+// scriptgen/defect-fix output.ts). exitCodeFor() is driven only by
+// `verdict` (the primary finding) — `secondaryFindings` never affects it,
+// same reasoning the policy prompt gives the model: secondary observations
+// are reported, never merged into the primary judgment.
+export function printJsonSummary(summary) {
+    console.log(JSON.stringify(summary, null, 2));
+}
+export function printHumanSummary(summary) {
+    console.log(`\n=== ${summary.route} ===\n`);
+    console.log(`  Baseline: ${summary.baselineUrl}`);
+    console.log(`  Target:   ${summary.targetUrl}`);
+    if (!summary.diffRan) {
+        console.log('\n  capture_and_diff never actually ran — no verdict was computed.');
+        return;
+    }
+    if (summary.diffPercentage !== null) {
+        console.log(`  Diff: ${summary.diffPixelCount} pixels (${summary.diffPercentage.toFixed(2)}%)`);
+    }
+    console.log(`\n  Verdict: ${summary.verdict.toUpperCase()}`);
+    console.log(`  Primary finding: ${summary.primaryFinding || '(none stated)'}`);
+    if (summary.secondaryFindings.length > 0) {
+        console.log('  Secondary observations (out of scope for this check):');
+        for (const s of summary.secondaryFindings)
+            console.log(`    - ${s}`);
+    }
+}
+/** 0 for expected-divergence/not-applicable — nothing wrong, or nothing to check. 1 for regression/inconclusive — fail-closed on ambiguity, matching family convention. */
+export function exitCodeFor(summary) {
+    return summary.verdict === 'expected-divergence' || summary.verdict === 'not-applicable' ? 0 : 1;
+}
+//# sourceMappingURL=output.js.map

package/dist/cli/output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../../src/cli/output.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,mEAAmE;AACnE,0EAA0E;AAC1E,2EAA2E;AAC3E,wDAAwD;AAiBxD,MAAM,UAAU,gBAAgB,CAAC,OAAgC;IAC/D,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,OAAgC;IAChE,OAAO,CAAC,GAAG,CAAC,SAAS,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC;IAC5C,OAAO,CAAC,GAAG,CAAC,eAAe,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAClD,OAAO,CAAC,GAAG,CAAC,eAAe,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;IAChD,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;QACrB,OAAO,CAAC,GAAG,CAAC,oEAAoE,CAAC,CAAC;QAClF,OAAO;IACT,CAAC;IACD,IAAI,OAAO,CAAC,cAAc,KAAK,IAAI,EAAE,CAAC;QACpC,OAAO,CAAC,GAAG,CAAC,WAAW,OAAO,CAAC,cAAc,YAAY,OAAO,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAClG,CAAC;IACD,OAAO,CAAC,GAAG,CAAC,gBAAgB,OAAO,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IAC7D,OAAO,CAAC,GAAG,CAAC,sBAAsB,OAAO,CAAC,cAAc,IAAI,eAAe,EAAE,CAAC,CAAC;IAC/E,IAAI,OAAO,CAAC,iBAAiB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzC,OAAO,CAAC,GAAG,CAAC,yDAAyD,CAAC,CAAC;QACvE,KAAK,MAAM,CAAC,IAAI,OAAO,CAAC,iBAAiB;YAAE,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IACvE,CAAC;AACH,CAAC;AAED,2KAA2K;AAC3K,MAAM,UAAU,WAAW,CAAC,OAAgC;IAC1D,OAAO,OAAO,CAAC,OAAO,KAAK,qBAAqB,IAAI,OAAO,CAAC,OAAO,KAAK,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACnG,CAAC"}

package/dist/config/env.js

@@ -0,0 +1,55 @@
+import 'dotenv/config';
+import { DEFAULT_ANTHROPIC_MODEL, DEFAULT_OPENAI_MODEL } from '@appliqation/agent-core/providers';
+import { required, optional } from '@appliqation/agent-core/config';
+import { resolveAuditSink } from '@appliqation/agent-core/audit';
+export const config = {
+    appqOrigin: optional('APPQ_ORIGIN') ?? 'https://appq.appliqation.io',
+    appqApiKey: () => required('APPQ_API_KEY'),
+    anthropicApiKey: optional('ANTHROPIC_API_KEY'),
+    openaiApiKey: optional('OPENAI_API_KEY'),
+    anthropicModel: optional('ANTHROPIC_MODEL'),
+    openaiModel: optional('OPENAI_MODEL'),
+    anthropicMaxTokens: Number(optional('ANTHROPIC_MAX_TOKENS') ?? 8192),
+    openaiMaxOutputTokens: Number(optional('OPENAI_MAX_OUTPUT_TOKENS') ?? 8192),
+    // One capture-then-judge pass — the mechanical work (two navigations, one
+    // diff) is fixed cost; the model's only real work is a single judgment
+    // call, so this budget is deliberately tight compared to heal-selector's.
+    budget: {
+        maxCalls: Number(optional('BUDGET_MAX_CALLS') ?? 15),
+        // Two real navigations (baseline + target) happen inside the one
+        // capture_and_diff tool call, not as separate browser_navigate calls —
+        // this cap is a backstop, not something the model spends turn-by-turn.
+        maxPages: Number(optional('BUDGET_MAX_PAGES') ?? 10),
+        maxMillis: Number(optional('BUDGET_MAX_MILLIS') ?? 5 * 60 * 1000),
+        maxTurns: Number(optional('BUDGET_MAX_TURNS') ?? 10),
+        // A broad backstop against runaway spend, not a tuned budget. Includes
+        // cache tokens — and matters more here than most siblings, since every
+        // turn after capture_and_diff carries three real images in context.
+        maxTotalTokens: Number(optional('BUDGET_MAX_TOTAL_TOKENS') ?? 1_000_000),
+    },
+    // Playwright browser tools' evidence ring-buffer cap — see
+    // @appliqation/agent-core's evidence/capture.ts. Unused in practice: this
+    // agent never exposes BROWSER_TOOL_DEFS to the model, capture_and_diff
+    // drives its own browser directly. Kept for config-shape consistency with
+    // every sibling agent.
+    ringBufferCap: Number(optional('RING_BUFFER_CAP') ?? 10),
+    // Observability, entirely opt-in — see @appliqation/agent-core's audit/sink.ts.
+    auditSink: resolveAuditSink({
+        auditMongoUri: optional('AUDIT_MONGO_URI'),
+        auditMongoDb: optional('AUDIT_MONGO_DB'),
+        auditMongoCollection: optional('AUDIT_MONGO_COLLECTION'),
+        auditJsonlPath: optional('AUDIT_JSONL_PATH'),
+    }),
+};
+export function resolveProvider() {
+    if (config.anthropicApiKey)
+        return 'anthropic';
+    if (config.openaiApiKey)
+        return 'openai';
+    throw new Error('Set ANTHROPIC_API_KEY or OPENAI_API_KEY');
+}
+export function resolveModel() {
+    const provider = resolveProvider();
+    return provider === 'anthropic' ? (config.anthropicModel ?? DEFAULT_ANTHROPIC_MODEL) : (config.openaiModel ?? DEFAULT_OPENAI_MODEL);
+}
+//# sourceMappingURL=env.js.map

package/dist/config/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/config/env.ts"],"names":[],"mappings":"AAAA,OAAO,eAAe,CAAC;AACvB,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAClG,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAEjE,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,UAAU,EAAE,QAAQ,CAAC,aAAa,CAAC,IAAI,6BAA6B;IACpE,UAAU,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,cAAc,CAAC;IAC1C,eAAe,EAAE,QAAQ,CAAC,mBAAmB,CAAC;IAC9C,YAAY,EAAE,QAAQ,CAAC,gBAAgB,CAAC;IACxC,cAAc,EAAE,QAAQ,CAAC,iBAAiB,CAAC;IAC3C,WAAW,EAAE,QAAQ,CAAC,cAAc,CAAC;IACrC,kBAAkB,EAAE,MAAM,CAAC,QAAQ,CAAC,sBAAsB,CAAC,IAAI,IAAI,CAAC;IACpE,qBAAqB,EAAE,MAAM,CAAC,QAAQ,CAAC,0BAA0B,CAAC,IAAI,IAAI,CAAC;IAC3E,0EAA0E;IAC1E,uEAAuE;IACvE,0EAA0E;IAC1E,MAAM,EAAE;QACN,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAAC,IAAI,EAAE,CAAC;QACpD,iEAAiE;QACjE,uEAAuE;QACvE,uEAAuE;QACvE,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAAC,IAAI,EAAE,CAAC;QACpD,SAAS,EAAE,MAAM,CAAC,QAAQ,CAAC,mBAAmB,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;QACjE,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAAC,IAAI,EAAE,CAAC;QACpD,uEAAuE;QACvE,uEAAuE;QACvE,oEAAoE;QACpE,cAAc,EAAE,MAAM,CAAC,QAAQ,CAAC,yBAAyB,CAAC,IAAI,SAAS,CAAC;KACzE;IACD,2DAA2D;IAC3D,0EAA0E;IAC1E,uEAAuE;IACvE,0EAA0E;IAC1E,uBAAuB;IACvB,aAAa,EAAE,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAAC,IAAI,EAAE,CAAC;IAExD,gFAAgF;IAChF,SAAS,EAAE,gBAAgB,CAAC;QAC1B,aAAa,EAAE,QAAQ,CAAC,iBAAiB,CAAC;QAC1C,YAAY,EAAE,QAAQ,CAAC,gBAAgB,CAAC;QACxC,oBAAoB,EAAE,QAAQ,CAAC,wBAAwB,CAAC;QACxD,cAAc,EAAE,QAAQ,CAAC,kBAAkB,CAAC;KAC7C,CAAC;CACH,CAAC;AAEF,MAAM,UAAU,eAAe;IAC7B,IAAI,MAAM,CAAC,eAAe;QAAE,OAAO,WAAW,CAAC;IAC/C,IAAI,MAAM,CAAC,YAAY;QAAE,OAAO,QAAQ,CAAC;IACzC,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;AAC7D,CAAC;AAED,MAAM,UAAU,YAAY;IAC1B,MAAM,QAAQ,GAAG,eAAe,EAAE,CAAC;IACnC,OAAO,QAAQ,KAAK,WAAW,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,cAAc,IAAI,uBAAuB,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,IAAI,oBAAoB,CAAC,CAAC;AACtI,CAAC"}

package/dist/orchestrator/visualRegression.js

@@ -0,0 +1,79 @@
+// Drives the visual-regression methodology (src/policy/visualRegressionPrompt.ts
+// — no appq-served prompt exists for this, so runLoop() is used directly,
+// same pattern appliqation-heal-selector/appliqation-autopilot use for their
+// own local policies). Deliberately NOT the browser+coding-tools composition
+// heal-selector uses — this agent never exposes BROWSER_TOOL_DEFS to the
+// model at all; the entire mechanical pipeline is one atomic, code-owned
+// tool (capture_and_diff). The model's only real work is judgment, captured
+// through a second tool (submit_verdict) as structured data, never parsed
+// out of free-text report prose.
+import { runLoop, fetchAppqToolDefs, createGatedAppqDispatcher, } from '@appliqation/agent-core';
+import { READONLY_CONTEXT_TOOLS } from '../tools/safety.js';
+import { CAPTURE_TOOL_DEFS, CaptureAndDiffTool } from '../tools/captureAndDiff.js';
+import { SUBMIT_VERDICT_TOOL_DEF, VerdictCapture } from '../tools/verdictTool.js';
+import { buildVisualRegressionPrompt } from '../policy/visualRegressionPrompt.js';
+function seedMessage(opts) {
+    const lines = [
+        `Route being checked: ${opts.route}`,
+        `Baseline (production) URL: ${opts.baselineUrl}`,
+        `Target URL: ${opts.targetUrl}`,
+        `Masked selectors: ${opts.maskSelectors.length > 0 ? opts.maskSelectors.join(', ') : '(none configured)'}`,
+    ];
+    if (opts.testCaseUuid) {
+        lines.push(`Test case UUID (for context via get_scenario): ${opts.testCaseUuid}`);
+    }
+    else {
+        lines.push('No test case given — no expected_result context available; judge from the screenshots alone.');
+    }
+    lines.push('Begin now — call capture_and_diff.');
+    return lines.join('\n');
+}
+export async function checkVisualRegression(opts) {
+    const appqToolDefs = opts.testCaseUuid ? await fetchAppqToolDefs(opts.client, READONLY_CONTEXT_TOOLS) : [];
+    const gatedAppq = createGatedAppqDispatcher(opts.client, READONLY_CONTEXT_TOOLS);
+    const capture = new CaptureAndDiffTool({
+        baselineUrl: opts.baselineUrl,
+        targetUrl: opts.targetUrl,
+        maskSelectors: opts.maskSelectors,
+        storageStatePath: opts.storageStatePath,
+    });
+    const verdictCapture = new VerdictCapture();
+    let diffRan = false;
+    const diffState = { data: null };
+    const dispatch = async (name, args) => {
+        if (name === 'capture_and_diff') {
+            const result = await capture.dispatch(name, args);
+            diffRan = true;
+            const data = result.data;
+            if (data && typeof data.diffPixelCount === 'number' && typeof data.diffPercentage === 'number') {
+                diffState.data = { diffPixelCount: data.diffPixelCount, diffPercentage: data.diffPercentage };
+            }
+            return result;
+        }
+        if (name === 'submit_verdict')
+            return verdictCapture.dispatch(name, args);
+        return gatedAppq(name, args);
+    };
+    const loopResult = await runLoop({
+        adapter: opts.adapter,
+        system: buildVisualRegressionPrompt(),
+        seedMessage: seedMessage(opts),
+        tools: [...appqToolDefs, ...CAPTURE_TOOL_DEFS, SUBMIT_VERDICT_TOOL_DEF],
+        dispatch,
+        budget: opts.budget,
+        onEvent: opts.onEvent,
+    });
+    const verdict = verdictCapture.get();
+    return {
+        report: loopResult.report,
+        turns: loopResult.turns,
+        budgetExceeded: loopResult.budgetExceeded,
+        diffRan,
+        diffPixelCount: diffState.data?.diffPixelCount ?? null,
+        diffPercentage: diffState.data?.diffPercentage ?? null,
+        verdict: verdict?.verdict,
+        primaryFinding: verdict?.primaryFinding ?? '',
+        secondaryFindings: verdict?.secondaryFindings ?? [],
+    };
+}
+//# sourceMappingURL=visualRegression.js.map

package/dist/orchestrator/visualRegression.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"visualRegression.js","sourceRoot":"","sources":["../../src/orchestrator/visualRegression.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,0EAA0E;AAC1E,6EAA6E;AAC7E,6EAA6E;AAC7E,yEAAyE;AACzE,yEAAyE;AACzE,4EAA4E;AAC5E,0EAA0E;AAC1E,iCAAiC;AAEjC,OAAO,EACL,OAAO,EACP,iBAAiB,EACjB,yBAAyB,GAM1B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AACnF,OAAO,EAAE,uBAAuB,EAAE,cAAc,EAAgB,MAAM,yBAAyB,CAAC;AAChG,OAAO,EAAE,2BAA2B,EAAE,MAAM,qCAAqC,CAAC;AAkClF,SAAS,WAAW,CAAC,IAA6B;IAChD,MAAM,KAAK,GAAG;QACZ,wBAAwB,IAAI,CAAC,KAAK,EAAE;QACpC,8BAA8B,IAAI,CAAC,WAAW,EAAE;QAChD,eAAe,IAAI,CAAC,SAAS,EAAE;QAC/B,qBAAqB,IAAI,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,mBAAmB,EAAE;KAC3G,CAAC;IACF,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;QACtB,KAAK,CAAC,IAAI,CAAC,kDAAkD,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC;IACpF,CAAC;SAAM,CAAC;QACN,KAAK,CAAC,IAAI,CAAC,8FAA8F,CAAC,CAAC;IAC7G,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,oCAAoC,CAAC,CAAC;IACjD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,IAA6B;IACvE,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,MAAM,iBAAiB,CAAC,IAAI,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3G,MAAM,SAAS,GAAG,yBAAyB,CAAC,IAAI,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;IAEjF,MAAM,OAAO,GAAG,IAAI,kBAAkB,CAAC;QACrC,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,aAAa,EAAE,IAAI,CAAC,aAAa;QACjC,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;KACxC,CAAC,CAAC;IACH,MAAM,cAAc,GAAG,IAAI,cAAc,EAAE,CAAC;IAE5C,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,MAAM,SAAS,GAAwE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAEtG,MAAM,QAAQ,GAAmB,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;QACpD,IAAI,IAAI,KAAK,kBAAkB,EAAE,CAAC;YAChC,MAAM,MAAM,GAAe,MAAM,OAAO,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YAC9D,OAAO,GAAG,IAAI,CAAC;YACf,MAAM,IAAI,GAAG,MAAM,CAAC,IAAwE,CAAC;YAC7F,IAAI,IAAI,IAAI,OAAO,IAAI,CAAC,cAAc,KAAK,QAAQ,IAAI,OAAO,IAAI,CAAC,cAAc,KAAK,QAAQ,EAAE,CAAC;gBAC/F,SAAS,CAAC,IAAI,GAAG,EAAE,cAAc,EAAE,IAAI,CAAC,cAAc,EAAE,cAAc,EAAE,IAAI,CAAC,cAAc,EAAE,CAAC;YAChG,CAAC;YACD,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,IAAI,IAAI,KAAK,gBAAgB;YAAE,OAAO,cAAc,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC1E,OAAO,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC/B,CAAC,CAAC;IAEF,MAAM,UAAU,GAAG,MAAM,OAAO,CAAC;QAC/B,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,MAAM,EAAE,2BAA2B,EAAE;QACrC,WAAW,EAAE,WAAW,CAAC,IAAI,CAAC;QAC9B,KAAK,EAAE,CAAC,GAAG,YAAY,EAAE,GAAG,iBAAiB,EAAE,uBAAuB,CAAC;QACvE,QAAQ;QACR,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,OAAO,EAAE,IAAI,CAAC,OAAO;KACtB,CAAC,CAAC;IAEH,MAAM,OAAO,GAAG,cAAc,CAAC,GAAG,EAAE,CAAC;IAErC,OAAO;QACL,MAAM,EAAE,UAAU,CAAC,MAAM;QACzB,KAAK,EAAE,UAAU,CAAC,KAAK;QACvB,cAAc,EAAE,UAAU,CAAC,cAAc;QACzC,OAAO;QACP,cAAc,EAAE,SAAS,CAAC,IAAI,EAAE,cAAc,IAAI,IAAI;QACtD,cAAc,EAAE,SAAS,CAAC,IAAI,EAAE,cAAc,IAAI,IAAI;QACtD,OAAO,EAAE,OAAO,EAAE,OAAO;QACzB,cAAc,EAAE,OAAO,EAAE,cAAc,IAAI,EAAE;QAC7C,iBAAiB,EAAE,OAAO,EAAE,iBAAiB,IAAI,EAAE;KACpD,CAAC;AACJ,CAAC"}

package/dist/policy/visualRegressionPrompt.js

@@ -0,0 +1,75 @@
+// The actual decision-making methodology. There is no appq-served prompt for
+// this — genuinely new methodology, no server-side equivalent exists yet —
+// so this is a local, bundled prompt, driven through @appliqation/agent-core's
+// runLoop() directly, same pattern appliqation-heal-selector and
+// appliqation-autopilot already use for their own local policies.
+export function buildVisualRegressionPrompt() {
+    return `You are a narrow specialist: you check ONE route for a real visual regression by comparing it \
+against its own live production counterpart. You never compare against a design file or mock — production \
+IS the source of truth here, fetched live, not a stored baseline. You never touch application code, never \
+file a defect, never take any write action of any kind. Your entire output is a verdict and a report.
+
+## Phase 0 — Prerequisites
+
+You have two tool surfaces: read-only Appliqation context (\`get_scenario\`, if a test case was given — \
+its \`expected_result\`/step text is context for what this page is supposed to show, never a substitute \
+for looking at the real screenshots) and exactly one action tool, \`capture_and_diff\`, which takes no \
+arguments — the baseline URL, target URL, and any mask selectors were already fixed before this run \
+started. Call it exactly once.
+
+## Phase 1 — Load context (only if a test case was given)
+
+If a test case UUID is present in the seed message, call \`get_scenario\` to load its \`expected_result\`/ \
+step text. This tells you what this page is supposed to show, so you can weigh a real difference against \
+actual intent rather than reasoning about pixels in a vacuum. If no test case was given, skip straight to \
+Phase 2 — this agent works fine with just the two URLs.
+
+## Phase 2 — Capture and diff
+
+Call \`capture_and_diff\`. Its result is authoritative: real screenshots, a real diff overlay image, and \
+real, code-computed diff statistics (pixel count, percentage). If it comes back with \
+\`VERDICT: not-applicable (predetermined...)\`, do not override that — that determination was made by the \
+tool itself (the route returned HTTP 404 on the baseline environment), not something for you to second-guess \
+or re-diff. Report \`not-applicable\` and stop; skip Phase 3 entirely.
+
+## Phase 3 — Judge
+
+Otherwise, look at all three images (baseline, target, diff overlay) plus the real diff percentage, and \
+classify:
+
+- **\`regression\`** — a real, visible break: a missing or overlapping element, a button pushed off-screen \
+or hidden, unreadable/invisible text, a broken layout. This is what a real user would notice as "this looks \
+broken," not just "these pixels differ."
+- **\`expected-divergence\`** — the pixels really do differ, but for a legitimate reason: different \
+data (an article title, a count, a timestamp — especially anything that looks like it should have been \
+masked but wasn't configured to be), a new feature present on the target that isn't live on production yet, \
+a staging banner, an environment label. Different is not automatically broken.
+- **\`inconclusive\`** — you genuinely cannot tell from the evidence. Fail closed here rather than guessing \
+either direction — same discipline \`appq:autotest-validator\`'s own reconciliation uses for ambiguous \
+evidence.
+- **\`not-applicable\`** — only ever set by Phase 2's short-circuit, never something you decide yourself in \
+this phase.
+
+**Primary finding vs. secondary observations.** A full-page diff can surface something real that has \
+nothing to do with what this check was actually for (if a test case's \`expected_result\` pointed at one \
+part of the page, or the check is just "does this route look right" broadly). Your **primary finding** is \
+whichever difference is most connected to the page's own stated purpose (or, with no test case given, the \
+single most significant difference you see) — this is what drives your verdict. Anything else real you \
+notice elsewhere on the page goes in **secondary observations** — reported, never silently dropped, but \
+never merged into or affecting the primary verdict. You take no action on either; reporting clearly is the \
+whole job.
+
+## Phase 4 — Report
+
+State your verdict plainly, then:
+- Cite the real diff percentage from \`capture_and_diff\`'s own output — never restate a different number, \
+never round away precision that changes the picture.
+- Describe *specifically* what changed and where (e.g. "the 'Subscribe' button in the hero, present on \
+production, is not rendered on target" — not "the hero section looks different").
+- List secondary observations separately and clearly labeled as outside the scope of this check.
+- If the verdict is \`inconclusive\`, say exactly what evidence was missing or ambiguous, not just "unclear."
+
+Never blur outcomes together — a human (or another agent) reading your report should immediately know \
+whether this route is fine, broken, or genuinely undecidable, and why.`;
+}
+//# sourceMappingURL=visualRegressionPrompt.js.map

package/dist/policy/visualRegressionPrompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"visualRegressionPrompt.js","sourceRoot":"","sources":["../../src/policy/visualRegressionPrompt.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,2EAA2E;AAC3E,+EAA+E;AAC/E,iEAAiE;AACjE,kEAAkE;AAElE,MAAM,UAAU,2BAA2B;IACzC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;uEAkE8D,CAAC;AACxE,CAAC"}

package/dist/tools/captureAndDiff.js

@@ -0,0 +1,140 @@
+// The one real piece of new mechanism in this repo. Deliberately NOT driven
+// by the model turn-by-turn (BROWSER_TOOL_DEFS is never offered) — the
+// entire mechanical pipeline (navigate baseline, navigate target, mask,
+// screenshot, pixel-diff) is one atomic, code-owned tool call. The model's
+// only job, in the turn after this returns, is judgment: given the two real
+// screenshots + a diff overlay + real diff stats, classify the result. This
+// keeps the objective measurement itself (pixel counts, dimensions, the
+// not-applicable determination) something the model can never quietly
+// override with its own claim — same "never trust the model's own report"
+// discipline every sibling agent applies to its own domain.
+import { chromium } from 'playwright';
+import { PNG } from 'pngjs';
+import pixelmatch from 'pixelmatch';
+export const CAPTURE_TOOL_DEFS = [
+    {
+        name: 'capture_and_diff',
+        description: 'Navigate to the same route on the baseline (production) and target environment, mask any ' +
+            'configured dynamic regions, take full-page screenshots of both, and pixel-diff them. Takes no ' +
+            'arguments — baseline URL, target URL, and mask selectors were already given when this run started. ' +
+            'Call this exactly once. Returns the two real screenshots, a diff overlay image, and real diff ' +
+            'statistics — or, if the route does not exist on the baseline environment, a pre-determined ' +
+            'not-applicable result with no diff attempted.',
+        inputSchema: { type: 'object', properties: {} },
+    },
+];
+function decodePng(buffer) {
+    const png = PNG.sync.read(buffer);
+    return { width: png.width, height: png.height, data: png.data };
+}
+/**
+ * pixelmatch requires both inputs to be the exact same dimensions. Real
+ * pages on two environments can legitimately differ in full-page height
+ * (different content length, not a bug) — rather than fail, pad both onto a
+ * shared canvas sized to the larger of the two, filling new area with a
+ * fixed, obviously-synthetic color. The padded region then genuinely shows
+ * up as 100% different in the diff, which is correct: a real dimension
+ * mismatch is real information for the model to reason about, not something
+ * to silently crop away.
+ */
+function padToMatch(a, b) {
+    const width = Math.max(a.width, b.width);
+    const height = Math.max(a.height, b.height);
+    if (width === a.width && height === a.height && width === b.width && height === b.height) {
+        return { a, b };
+    }
+    const pad = (img) => {
+        const out = new PNG({ width, height });
+        out.data.fill(0);
+        for (let y = 0; y < img.height; y++) {
+            img.data.copy(out.data, (y * width) * 4, y * img.width * 4, y * img.width * 4 + img.width * 4);
+        }
+        return { width, height, data: out.data };
+    };
+    return { a: pad(a), b: pad(b) };
+}
+function toLlmImage(buffer, label) {
+    return { data: buffer.toString('base64'), mimeType: 'image/png', label };
+}
+async function captureFullPage(page, url, maskSelectors) {
+    const response = await page.goto(url, { waitUntil: 'networkidle' }).catch(() => null);
+    const httpStatus = response?.status() ?? null;
+    if (httpStatus === 404) {
+        return { status: 'not-found', httpStatus, png: null };
+    }
+    // Best-effort: let CSS transitions/animations settle before capture, same
+    // reasoning every screenshot-diff tool needs — a mid-transition frame is
+    // noise, not a real difference.
+    await page.addStyleTag({ content: '*, *::before, *::after { animation-duration: 0s !important; animation-delay: 0s !important; transition-duration: 0s !important; }' }).catch(() => { });
+    const mask = maskSelectors.map((selector) => page.locator(selector));
+    const png = await page.screenshot({ fullPage: true, type: 'png', mask });
+    return { status: 'ok', httpStatus, png };
+}
+export class CaptureAndDiffTool {
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    async dispatch(name, _args) {
+        if (name !== 'capture_and_diff') {
+            return { ok: false, text: `Unknown tool: ${name}` };
+        }
+        const browser = await chromium.launch();
+        try {
+            const context = await browser.newContext(this.opts.storageStatePath ? { storageState: this.opts.storageStatePath } : {});
+            const page = await context.newPage();
+            const baseline = await captureFullPage(page, this.opts.baselineUrl, this.opts.maskSelectors);
+            if (baseline.status === 'not-found') {
+                return {
+                    ok: true,
+                    text: `VERDICT: not-applicable (predetermined by capture_and_diff, do not override this)\n` +
+                        `Reason: the baseline (production) URL ${this.opts.baselineUrl} returned HTTP 404 — this route ` +
+                        `does not exist on the baseline environment. No comparison is possible; the target environment ` +
+                        `was never navigated to.`,
+                };
+            }
+            const target = await captureFullPage(page, this.opts.targetUrl, this.opts.maskSelectors);
+            if (target.status === 'not-found') {
+                return {
+                    ok: true,
+                    text: `VERDICT: not-applicable (predetermined by capture_and_diff, do not override this)\n` +
+                        `Reason: the baseline exists (HTTP ${baseline.httpStatus}) but the target URL ${this.opts.targetUrl} ` +
+                        `returned HTTP 404. No comparison is possible.`,
+                };
+            }
+            const decodedBaseline = decodePng(baseline.png);
+            const decodedTarget = decodePng(target.png);
+            const { a: paddedBaseline, b: paddedTarget } = padToMatch(decodedBaseline, decodedTarget);
+            const diffPng = new PNG({ width: paddedBaseline.width, height: paddedBaseline.height });
+            const diffPixelCount = pixelmatch(paddedBaseline.data, paddedTarget.data, diffPng.data, paddedBaseline.width, paddedBaseline.height, { threshold: 0.1 });
+            const totalPixels = paddedBaseline.width * paddedBaseline.height;
+            const diffPercentage = totalPixels > 0 ? (diffPixelCount / totalPixels) * 100 : 0;
+            const diffOverlayBuffer = PNG.sync.write(diffPng);
+            const dimensionNote = decodedBaseline.width !== decodedTarget.width || decodedBaseline.height !== decodedTarget.height
+                ? ` Note: baseline is ${decodedBaseline.width}x${decodedBaseline.height}, target is ` +
+                    `${decodedTarget.width}x${decodedTarget.height} — different full-page dimensions, padded onto a ` +
+                    `shared ${paddedBaseline.width}x${paddedBaseline.height} canvas before diffing. The padded region ` +
+                    `shows up as fully different in the overlay; that may just reflect different content length, not a ` +
+                    `layout break — reason about it accordingly.`
+                : '';
+            return {
+                ok: true,
+                text: `Baseline (production): ${this.opts.baselineUrl} (HTTP ${baseline.httpStatus})\n` +
+                    `Target: ${this.opts.targetUrl} (HTTP ${target.httpStatus})\n` +
+                    `Masked selectors: ${this.opts.maskSelectors.length > 0 ? this.opts.maskSelectors.join(', ') : '(none)'}\n` +
+                    `Real diff: ${diffPixelCount} pixels differ out of ${totalPixels} (${diffPercentage.toFixed(2)}%).${dimensionNote}\n` +
+                    `These numbers are real and code-computed — never restate a different figure.`,
+                data: { diffPixelCount, diffPercentage, baselineHttpStatus: baseline.httpStatus, targetHttpStatus: target.httpStatus },
+                images: [
+                    toLlmImage(baseline.png, `Baseline (production) — ${this.opts.baselineUrl}`),
+                    toLlmImage(target.png, `Target — ${this.opts.targetUrl}`),
+                    toLlmImage(diffOverlayBuffer, 'Diff overlay (magenta/highlighted = differs)'),
+                ],
+            };
+        }
+        finally {
+            await browser.close();
+        }
+    }
+}
+//# sourceMappingURL=captureAndDiff.js.map

package/dist/tools/captureAndDiff.js.map

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

package/dist/tools/safety.js

@@ -0,0 +1,13 @@
+// This agent's own domain knowledge of which appq tools it may touch — the
+// enforcement mechanism (assertToolAllowed / the gated dispatcher) lives in
+// @appliqation/agent-core, shared with every sibling agent; only the
+// allowlist content is local. Zero write tools — genuinely absent, not
+// gated behind a flag. This agent never calls an appq write tool; it only
+// ever reports a verdict, never files a defect or persists anything.
+export const READONLY_CONTEXT_TOOLS = new Set([
+    // The test case's own expected_result/steps, when a --test-case-uuid was
+    // given — the ground truth a diff's "is this expected" judgment gets
+    // checked against. Optional context, not required to proceed.
+    'get_scenario',
+]);
+//# sourceMappingURL=safety.js.map

package/dist/tools/safety.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safety.js","sourceRoot":"","sources":["../../src/tools/safety.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,4EAA4E;AAC5E,qEAAqE;AACrE,uEAAuE;AACvE,0EAA0E;AAC1E,qEAAqE;AAErE,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,GAAG,CAAC;IAC5C,yEAAyE;IACzE,qEAAqE;IACrE,8DAA8D;IAC9D,cAAc;CACf,CAAC,CAAC"}

package/dist/tools/verdictTool.js

@@ -0,0 +1,54 @@
+// The verdict itself is inherently a judgment call — unlike heal-selector's
+// declined/verified (both derivable from real code signals: file writes, a
+// real command exit code), there's no objective code-computed equivalent
+// for "is this a regression." Rather than parse it out of free-text report
+// prose (fragile), the model reports it through a real tool call's
+// structured arguments — same discipline `appq:autotest-validator` already
+// uses (writing its verdict via `update_run_results`'s real enum argument,
+// not asserting it in prose). This tool never causes a side effect; it's
+// purely how the model's judgment reaches this process as structured data.
+export const SUBMIT_VERDICT_TOOL_DEF = {
+    name: 'submit_verdict',
+    description: 'Report your final judgment. Call this exactly once, after capture_and_diff (and get_scenario, if a ' +
+        'test case was given) — never before you have the real diff evidence. This is how your verdict reaches ' +
+        'the caller; a verdict only stated in your closing prose is not captured.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            verdict: {
+                type: 'string',
+                enum: ['regression', 'expected-divergence', 'not-applicable', 'inconclusive'],
+                description: 'regression = a real visible break. expected-divergence = pixels differ but for a legitimate ' +
+                    'reason (data, a new unreleased feature, a staging banner). inconclusive = you genuinely cannot ' +
+                    'tell — fail closed. not-applicable = only ever set because capture_and_diff itself pre-determined ' +
+                    'it (route missing on baseline) — never decide this yourself in any other case.',
+            },
+            primary_finding: {
+                type: 'string',
+                description: 'The one finding most connected to what this check was for — what drove the verdict above. Be specific about what and where.',
+            },
+            secondary_findings: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Other real differences noticed elsewhere on the page, unrelated to the primary finding. Empty array if none. Never affects the verdict above.',
+            },
+        },
+        required: ['verdict', 'primary_finding'],
+    },
+};
+export class VerdictCapture {
+    captured;
+    dispatch(name, args) {
+        if (name !== 'submit_verdict')
+            return { ok: false, text: `Unknown tool: ${name}` };
+        const verdict = args.verdict;
+        const primaryFinding = String(args.primary_finding ?? '');
+        const secondaryFindings = Array.isArray(args.secondary_findings) ? args.secondary_findings.map(String) : [];
+        this.captured = { verdict, primaryFinding, secondaryFindings };
+        return { ok: true, text: 'Verdict recorded.' };
+    }
+    get() {
+        return this.captured;
+    }
+}
+//# sourceMappingURL=verdictTool.js.map

package/dist/tools/verdictTool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verdictTool.js","sourceRoot":"","sources":["../../src/tools/verdictTool.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,2EAA2E;AAC3E,yEAAyE;AACzE,2EAA2E;AAC3E,mEAAmE;AACnE,2EAA2E;AAC3E,2EAA2E;AAC3E,yEAAyE;AACzE,2EAA2E;AAM3E,MAAM,CAAC,MAAM,uBAAuB,GAAe;IACjD,IAAI,EAAE,gBAAgB;IACtB,WAAW,EACT,qGAAqG;QACrG,wGAAwG;QACxG,0EAA0E;IAC5E,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,OAAO,EAAE;gBACP,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,CAAC,YAAY,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,cAAc,CAAC;gBAC7E,WAAW,EACT,8FAA8F;oBAC9F,iGAAiG;oBACjG,oGAAoG;oBACpG,gFAAgF;aACnF;YACD,eAAe,EAAE;gBACf,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,6HAA6H;aAC3I;YACD,kBAAkB,EAAE;gBAClB,IAAI,EAAE,OAAO;gBACb,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBACzB,WAAW,EAAE,+IAA+I;aAC7J;SACF;QACD,QAAQ,EAAE,CAAC,SAAS,EAAE,iBAAiB,CAAC;KACzC;CACF,CAAC;AAQF,MAAM,OAAO,cAAc;IACjB,QAAQ,CAA8B;IAE9C,QAAQ,CAAC,IAAY,EAAE,IAA6B;QAClD,IAAI,IAAI,KAAK,gBAAgB;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,iBAAiB,IAAI,EAAE,EAAE,CAAC;QACnF,MAAM,OAAO,GAAG,IAAI,CAAC,OAAkB,CAAC;QACxC,MAAM,cAAc,GAAG,MAAM,CAAC,IAAI,CAAC,eAAe,IAAI,EAAE,CAAC,CAAC;QAC1D,MAAM,iBAAiB,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5G,IAAI,CAAC,QAAQ,GAAG,EAAE,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,CAAC;QAC/D,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,mBAAmB,EAAE,CAAC;IACjD,CAAC;IAED,GAAG;QACD,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;CACF"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@appliqation/visual-regression",
+  "version": "0.1.0",
+  "description": "Standalone agent that checks a page for real visual regressions by diffing it against its own live production counterpart — no stored baseline files, no manual baseline-approval workflow. Declines rather than compares when no production equivalent exists.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/appliqation/visual-regression.git"
+  },
+  "homepage": "https://github.com/appliqation/visual-regression#readme",
+  "bugs": {
+    "url": "https://github.com/appliqation/visual-regression/issues"
+  },
+  "type": "module",
+  "bin": {
+    "appliqation-visual-regression": "./dist/cli/index.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsx src/cli/index.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint src --ext .ts",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@appliqation/agent-core": "^0.1.5",
+    "commander": "^13.1.0",
+    "dotenv": "^16.4.7",
+    "pixelmatch": "^7.2.0",
+    "playwright": "^1.51.0",
+    "pngjs": "^7.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.5",
+    "@types/node": "^22.13.10",
+    "@types/pngjs": "^6.0.5",
+    "eslint": "^9.39.5",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2",
+    "typescript-eslint": "^8.67.0",
+    "vitest": "^3.2.7"
+  }
+}