@reticlehq/server 2.0.0

package/dist/update/update-checker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-checker.js","sourceRoot":"","sources":["../../src/update/update-checker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,KAAK,MAAM,YAAY,CAAC;AACpC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAEhC,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,UAAU,CAAC,CAAC;AACjD,MAAM,aAAa,GAAG,IAAI,CAAC,YAAY,EAAE,sBAAsB,CAAC,CAAC;AACjE,MAAM,YAAY,GAAG,mDAAmD,CAAC;AAqBzE,MAAM,UAAU,YAAY;IAC1B,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,aAAa,CAAC;QAAE,OAAO,IAAI,CAAC;IAC/C,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;QACnD,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAmB,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,QAAwB;IACnD,EAAE,CAAC,SAAS,CAAC,YAAY,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAChD,EAAE,CAAC,aAAa,CAAC,aAAa,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;AAC7E,CAAC;AAED,SAAS,YAAY,CAAC,QAAwB,EAAE,GAAiB;IAC/D,MAAM,OAAO,GAAG,IAAI,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,OAAO,EAAE,CAAC;IACzD,OAAO,GAAG,EAAE,GAAG,OAAO,GAAG,qBAAqB,CAAC;AACjD,CAAC;AAED,SAAS,YAAY;IACnB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,YAAY,EAAE,CAAC,GAAG,EAAE,EAAE;YAC1C,IAAI,IAAI,GAAG,EAAE,CAAC;YACd,GAAG,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;YACxB,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE;gBAC/B,IAAI,IAAI,KAAK,CAAC;YAChB,CAAC,CAAC,CAAC;YACH,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE;gBACjB,IAAI,CAAC;oBACH,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAmB,CAAC,CAAC;gBAC9C,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,MAAM,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;gBAC9D,CAAC;YACH,CAAC,CAAC,CAAC;YACH,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC1B,CAAC,CAAC,CAAC;QACH,GAAG,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,EAAE;YACxB,GAAG,CAAC,OAAO,EAAE,CAAC;YACd,MAAM,CAAC,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC,CAAC;QACtD,CAAC,CAAC,CAAC;QACH,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC1B,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,cAAsB,EACtB,GAAiB;IAEjB,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,CAAC,cAAc,KAAK,cAAc,IAAI,YAAY,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;QAC7F,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,YAAY,EAAE,CAAC;QAClC,MAAM,eAAe,GAAG,IAAI,CAAC,OAAO,KAAK,cAAc,CAAC;QACxD,MAAM,QAAQ,GAAmB;YAC/B,cAAc;YACd,aAAa,EAAE,IAAI,CAAC,OAAO;YAC3B,eAAe;YACf,WAAW,EAAE,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,WAAW,EAAE;YAC1C,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACvF,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,eAAe,KAAK,SAAS;gBAC7C,CAAC,CAAC,EAAE,eAAe,EAAE,IAAI,CAAC,OAAO,CAAC,eAAe,EAAE;gBACnD,CAAC,CAAC,EAAE,CAAC;YACP,GAAG,CAAC,MAAM,EAAE,eAAe,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,MAAM,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC9F,CAAC;QACF,YAAY,CAAC,QAAQ,CAAC,CAAC;QACvB,OAAO,QAAQ,CAAC;IAClB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,GAAG,CAAC,6BAA6B,EAAE;YACjC,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;SACxD,CAAC,CAAC;QACH,IAAI,MAAM,KAAK,IAAI;YAAE,OAAO,EAAE,GAAG,MAAM,EAAE,cAAc,EAAE,CAAC;QAC1D,OAAO;YACL,cAAc;YACd,eAAe,EAAE,KAAK;YACtB,WAAW,EAAE,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,WAAW,EAAE;SAC3C,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/update/update-tools.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDef } from '../tools/tools.js';
+export declare const UPDATE_TOOLS: ToolDef[];
+//# sourceMappingURL=update-tools.d.ts.map

package/dist/update/update-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-tools.d.ts","sourceRoot":"","sources":["../../src/update/update-tools.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAY,MAAM,mBAAmB,CAAC;AAK3D,eAAO,MAAM,YAAY,EAAE,OAAO,EAgGjC,CAAC"}

package/dist/update/update-tools.js

@@ -0,0 +1,94 @@
+import { z } from 'zod';
+import { ReticleTool } from '../tools/tool-names.js';
+import { checkForUpdate } from './update-checker.js';
+import { applyUpdate, rollback, detectExecutionKind } from './updater.js';
+import { SERVER_VERSION } from '../server-version.js';
+export const UPDATE_TOOLS = [
+    {
+        name: ReticleTool.VERSION_INFO,
+        description: 'Returns the running Reticle version, latest available version, release changelog, and any breaking changes. Call this at the start of a session or when unexpected tool behavior suggests a version mismatch.',
+        inputSchema: {},
+        outputSchema: {
+            currentVersion: z.string().describe('The Reticle server version currently running.'),
+            latestVersion: z.string().optional().describe('Latest published version on npm.'),
+            updateAvailable: z.boolean().describe('True when a newer version is available to install.'),
+            executionKind: z
+                .string()
+                .describe('How reticle was launched: "npx" (no install needed — restart applies update), "global" (npm install -g), or "local" (project node_modules).'),
+            changelog: z.string().optional().describe('Release notes for the latest version.'),
+            breakingChanges: z
+                .array(z.string())
+                .optional()
+                .describe('Breaking changes in the latest version that may affect your scripts.'),
+            rollbackAvailable: z
+                .boolean()
+                .describe('True when a previous version is stored and can be restored.'),
+            previousVersion: z
+                .string()
+                .optional()
+                .describe('The version that would be restored on rollback.'),
+        },
+        handler: async (deps) => {
+            const manifest = await checkForUpdate(SERVER_VERSION, deps.now);
+            return {
+                currentVersion: manifest.currentVersion,
+                ...(manifest.latestVersion !== undefined ? { latestVersion: manifest.latestVersion } : {}),
+                updateAvailable: manifest.updateAvailable,
+                executionKind: detectExecutionKind(),
+                ...(manifest.changelog !== undefined ? { changelog: manifest.changelog } : {}),
+                ...(manifest.breakingChanges !== undefined
+                    ? { breakingChanges: manifest.breakingChanges }
+                    : {}),
+                rollbackAvailable: manifest.previousVersion !== undefined,
+                ...(manifest.previousVersion !== undefined
+                    ? { previousVersion: manifest.previousVersion }
+                    : {}),
+            };
+        },
+    },
+    {
+        name: ReticleTool.APPLY_UPDATE,
+        description: 'Install the latest Reticle server version and restart. Strategy depends on how reticle was launched (check executionKind from reticle_version_info): "global" and "local" installs run npm install then exit; "npx" just exits — Claude Code restarts and npx re-resolves the latest version from npm automatically. The MCP connection briefly drops during restart.',
+        inputSchema: {
+            confirm: z
+                .boolean()
+                .describe('Set to true to confirm the update should be applied. Required to prevent accidental upgrades.'),
+        },
+        outputSchema: {
+            ok: z.boolean(),
+            message: z.string().optional(),
+        },
+        handler: async (deps, args) => {
+            if (args['confirm'] !== true) {
+                return { ok: false, message: 'Set confirm:true to apply the update' };
+            }
+            const manifest = await checkForUpdate(SERVER_VERSION, deps.now);
+            if (!manifest.updateAvailable || manifest.latestVersion === undefined) {
+                return { ok: false, message: 'No update available — already on the latest version' };
+            }
+            await applyUpdate(manifest.latestVersion);
+            return { ok: true }; // unreachable — applyUpdate calls process.exit()
+        },
+    },
+    {
+        name: ReticleTool.ROLLBACK,
+        description: 'Restore the previous Reticle server version and restart. Use when an update introduced a regression. The MCP connection will briefly drop — Claude Code restarts the process automatically with the restored binary.',
+        inputSchema: {
+            confirm: z
+                .boolean()
+                .describe('Set to true to confirm the rollback. Required to prevent accidental downgrades.'),
+        },
+        outputSchema: {
+            ok: z.boolean(),
+            message: z.string().optional(),
+        },
+        handler: async (_deps, args) => {
+            if (args['confirm'] !== true) {
+                return { ok: false, message: 'Set confirm:true to apply the rollback' };
+            }
+            await rollback();
+            return { ok: true }; // unreachable — rollback() calls process.exit()
+        },
+    },
+];
+//# sourceMappingURL=update-tools.js.map

package/dist/update/update-tools.js.map

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

package/dist/update/updater.d.ts

@@ -0,0 +1,31 @@
+/** How this reticle process was launched — determines which npm strategy to use for updates. */
+declare const ExecutionKind: {
+    /** Launched via `npx @reticlehq/core` — npm re-resolves the package on restart. */
+    readonly NPX: "npx";
+    /** Installed globally via `npm install -g`. */
+    readonly GLOBAL: "global";
+    /** Installed as a local project dependency. */
+    readonly LOCAL: "local";
+};
+type ExecutionKind = (typeof ExecutionKind)[keyof typeof ExecutionKind];
+/**
+ * Infer how reticle was launched from process.argv[1].
+ *
+ * npm's npx cache stores packages under a path containing `_npx`, which is the
+ * most reliable cross-platform signal. Local installs always live inside a
+ * `node_modules` directory. Everything else is treated as a global install.
+ */
+export declare function detectExecutionKind(): ExecutionKind;
+/**
+ * Install targetVersion using the appropriate strategy for the detected execution kind,
+ * then exit so Claude Code restarts with the new binary. Saves the current version
+ * first so rollback() can restore it.
+ */
+export declare function applyUpdate(targetVersion: string): Promise<void>;
+/**
+ * Reinstall the previousVersion saved in the update manifest using the appropriate
+ * strategy, then exit so Claude Code restarts with the restored binary.
+ */
+export declare function rollback(): Promise<void>;
+export {};
+//# sourceMappingURL=updater.d.ts.map

package/dist/update/updater.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"updater.d.ts","sourceRoot":"","sources":["../../src/update/updater.ts"],"names":[],"mappings":"AAUA,gGAAgG;AAChG,QAAA,MAAM,aAAa;IACjB,mFAAmF;;IAEnF,+CAA+C;;IAE/C,+CAA+C;;CAEvC,CAAC;AACX,KAAK,aAAa,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,OAAO,aAAa,CAAC,CAAC;AAExE;;;;;;GAMG;AACH,wBAAgB,mBAAmB,IAAI,aAAa,CAOnD;AAoED;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAWtE;AAED;;;GAGG;AACH,wBAAsB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAW9C"}

package/dist/update/updater.js

@@ -0,0 +1,120 @@
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { platform } from 'node:os';
+import { dirname, join } from 'node:path';
+import { loadManifest, saveManifest } from './update-checker.js';
+import { log } from '../log.js';
+const NPM_BIN = platform() === 'win32' ? 'npm.cmd' : 'npm';
+const NPM_TIMEOUT_MS = 120_000;
+/** How this reticle process was launched — determines which npm strategy to use for updates. */
+const ExecutionKind = {
+    /** Launched via `npx @reticlehq/core` — npm re-resolves the package on restart. */
+    NPX: 'npx',
+    /** Installed globally via `npm install -g`. */
+    GLOBAL: 'global',
+    /** Installed as a local project dependency. */
+    LOCAL: 'local',
+};
+/**
+ * Infer how reticle was launched from process.argv[1].
+ *
+ * npm's npx cache stores packages under a path containing `_npx`, which is the
+ * most reliable cross-platform signal. Local installs always live inside a
+ * `node_modules` directory. Everything else is treated as a global install.
+ */
+export function detectExecutionKind() {
+    const script = process.argv[1] ?? '';
+    if (script.includes('/_npx/') || script.includes('\\_npx\\'))
+        return ExecutionKind.NPX;
+    if (script.includes('/node_modules/') || script.includes('\\node_modules\\')) {
+        return ExecutionKind.LOCAL;
+    }
+    return ExecutionKind.GLOBAL;
+}
+/** Walk up from cwd until a directory containing package.json is found. */
+function findLocalProjectRoot() {
+    let dir = process.cwd();
+    for (;;) {
+        if (existsSync(join(dir, 'package.json')))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null; // reached filesystem root
+        dir = parent;
+    }
+}
+function runNpm(args, opts = {}) {
+    return new Promise((resolve, reject) => {
+        execFile(NPM_BIN, args, { timeout: NPM_TIMEOUT_MS, ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}) }, (err, _stdout, stderr) => {
+            if (err !== null) {
+                reject(new Error(`npm ${args.join(' ')} failed: ${stderr !== '' ? stderr : err.message}`));
+            }
+            else {
+                resolve();
+            }
+        });
+    });
+}
+async function installVersion(version, kind) {
+    const pkg = `@reticlehq/core@${version}`;
+    if (kind === ExecutionKind.NPX) {
+        // npx re-resolves the package from npm on the next Claude Code restart — no npm
+        // install needed. The restart itself is what triggers the update.
+        log('reticle_update_npx_strategy', {
+            note: 'Running via npx — exiting so Claude Code restarts and npx fetches the new version',
+        });
+        return;
+    }
+    if (kind === ExecutionKind.LOCAL) {
+        const root = findLocalProjectRoot();
+        if (root !== null) {
+            await runNpm(['install', pkg], { cwd: root });
+            return;
+        }
+        // Could not find a project root — fall through to global install as a safe default
+        log('reticle_update_local_no_root', { fallback: 'global' });
+    }
+    await runNpm(['install', '-g', pkg]);
+}
+async function installVersionRollback(version, kind) {
+    if (kind === ExecutionKind.NPX) {
+        log('reticle_rollback_npx_strategy', {
+            note: 'Running via npx — update your .mcp.json args to pin the version you want to restore',
+        });
+        return;
+    }
+    await installVersion(version, kind);
+}
+/**
+ * Install targetVersion using the appropriate strategy for the detected execution kind,
+ * then exit so Claude Code restarts with the new binary. Saves the current version
+ * first so rollback() can restore it.
+ */
+export async function applyUpdate(targetVersion) {
+    const manifest = loadManifest();
+    if (manifest !== null) {
+        saveManifest({ ...manifest, previousVersion: manifest.currentVersion });
+    }
+    const kind = detectExecutionKind();
+    log('reticle_update_applying', { version: targetVersion, executionKind: kind });
+    await installVersion(targetVersion, kind);
+    log('reticle_update_applied', { version: targetVersion, executionKind: kind });
+    process.exit(0);
+}
+/**
+ * Reinstall the previousVersion saved in the update manifest using the appropriate
+ * strategy, then exit so Claude Code restarts with the restored binary.
+ */
+export async function rollback() {
+    const manifest = loadManifest();
+    if (manifest === null || manifest.previousVersion === undefined) {
+        throw new Error('No previous version available for rollback');
+    }
+    const prev = manifest.previousVersion;
+    const kind = detectExecutionKind();
+    log('reticle_rollback_applying', { version: prev, executionKind: kind });
+    await installVersionRollback(prev, kind);
+    log('reticle_rollback_applied', { version: prev, executionKind: kind });
+    process.exit(0);
+}
+//# sourceMappingURL=updater.js.map

package/dist/update/updater.js.map

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

package/dist/visual/visual-diff.d.ts

@@ -0,0 +1,46 @@
+/** A rectangle in image pixel space — a mask to ignore, or the bounding box of what changed. */
+export interface VisualRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Knobs for a perceptual diff. masks zero out volatile regions (clocks, avatars) before comparing. */
+export interface DiffOptions {
+    /** pixelmatch per-pixel color threshold (0..1; higher = more lenient). */
+    threshold?: number;
+    /** A run passes when changed/total ≤ maxRatio. Default 0 (any change fails). */
+    maxRatio?: number;
+    /** Regions to neutralize in BOTH images before diffing, so dynamic content never trips the diff. */
+    masks?: VisualRect[];
+}
+/** The verdict of a perceptual diff (also the reticle_visual_diff result body). */
+export interface VisualDiffResult {
+    matched: boolean;
+    changedPixels: number;
+    totalPixels: number;
+    /** changedPixels / totalPixels (0 on a dimension mismatch). */
+    ratio: number;
+    width: number;
+    height: number;
+    /** True when baseline and current differ in size — a pixel diff is impossible, so it's a fail. */
+    dimensionMismatch: boolean;
+    baseline: {
+        width: number;
+        height: number;
+    };
+    current: {
+        width: number;
+        height: number;
+    };
+    /** Bounding box of the changed pixels (omitted when nothing changed / dimension mismatch). */
+    region?: VisualRect;
+    /** Encoded overlay diff PNG (omitted on a dimension mismatch). */
+    diffPng?: Uint8Array;
+}
+/**
+ * Perceptually diff two PNGs. Pure (deps injected by lazy import), no IO. A size
+ * mismatch is a hard fail (can't pixel-diff) reported as `dimensionMismatch`, never a throw.
+ */
+export declare function diffPng(baselineBytes: Uint8Array, currentBytes: Uint8Array, opts?: DiffOptions): Promise<VisualDiffResult>;
+//# sourceMappingURL=visual-diff.d.ts.map

package/dist/visual/visual-diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visual-diff.d.ts","sourceRoot":"","sources":["../../src/visual/visual-diff.ts"],"names":[],"mappings":"AAEA,gGAAgG;AAChG,MAAM,WAAW,UAAU;IACzB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,uGAAuG;AACvG,MAAM,WAAW,WAAW;IAC1B,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oGAAoG;IACpG,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;CACtB;AAED,mFAAmF;AACnF,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,kGAAkG;IAClG,iBAAiB,EAAE,OAAO,CAAC;IAC3B,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3C,8FAA8F;IAC9F,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,kEAAkE;IAClE,OAAO,CAAC,EAAE,UAAU,CAAC;CACtB;AAyED;;;GAGG;AACH,wBAAsB,OAAO,CAC3B,aAAa,EAAE,UAAU,EACzB,YAAY,EAAE,UAAU,EACxB,IAAI,GAAE,WAAgB,GACrB,OAAO,CAAC,gBAAgB,CAAC,CAgD3B"}

package/dist/visual/visual-diff.js

@@ -0,0 +1,100 @@
+import { VISUAL_PIXEL_THRESHOLD } from '@reticlehq/core';
+/** Lazy load — pngjs/pixelmatch are optional deps, so the always-on path never imports them. */
+async function loadDeps() {
+    const png = (await import('pngjs'));
+    const pm = (await import('pixelmatch'));
+    return { PNG: png.PNG, pixelmatch: pm.default };
+}
+const RGBA = 4;
+/** Zero a rectangle (clamped to bounds) in an RGBA buffer so masked regions compare equal. */
+function applyMask(data, width, height, rect) {
+    const x0 = Math.max(0, Math.floor(rect.x));
+    const y0 = Math.max(0, Math.floor(rect.y));
+    const x1 = Math.min(width, Math.floor(rect.x + rect.width));
+    const y1 = Math.min(height, Math.floor(rect.y + rect.height));
+    for (let y = y0; y < y1; y += 1) {
+        for (let x = x0; x < x1; x += 1) {
+            const i = (y * width + x) * RGBA;
+            data[i] = 0;
+            data[i + 1] = 0;
+            data[i + 2] = 0;
+            data[i + 3] = 0;
+        }
+    }
+}
+/** Bounding box of pixelmatch's red diff pixels in the overlay output (undefined if none). */
+function changedRegion(out, width, height) {
+    let minX = width;
+    let minY = height;
+    let maxX = -1;
+    let maxY = -1;
+    for (let y = 0; y < height; y += 1) {
+        for (let x = 0; x < width; x += 1) {
+            const i = (y * width + x) * RGBA;
+            // pixelmatch marks a changed pixel solid red (default diffColor) at full alpha.
+            if (out[i] === 255 && out[i + 1] === 0 && out[i + 2] === 0 && out[i + 3] === 255) {
+                if (x < minX)
+                    minX = x;
+                if (y < minY)
+                    minY = y;
+                if (x > maxX)
+                    maxX = x;
+                if (y > maxY)
+                    maxY = y;
+            }
+        }
+    }
+    if (maxX < 0)
+        return undefined;
+    return { x: minX, y: minY, width: maxX - minX + 1, height: maxY - minY + 1 };
+}
+/**
+ * Perceptually diff two PNGs. Pure (deps injected by lazy import), no IO. A size
+ * mismatch is a hard fail (can't pixel-diff) reported as `dimensionMismatch`, never a throw.
+ */
+export async function diffPng(baselineBytes, currentBytes, opts = {}) {
+    const { PNG, pixelmatch } = await loadDeps();
+    const a = PNG.sync.read(Buffer.from(baselineBytes));
+    const b = PNG.sync.read(Buffer.from(currentBytes));
+    const baseDims = { width: a.width, height: a.height };
+    const curDims = { width: b.width, height: b.height };
+    if (a.width !== b.width || a.height !== b.height) {
+        return {
+            matched: false,
+            changedPixels: 0,
+            totalPixels: a.width * a.height,
+            ratio: 0,
+            width: a.width,
+            height: a.height,
+            dimensionMismatch: true,
+            baseline: baseDims,
+            current: curDims,
+        };
+    }
+    const { width, height } = a;
+    for (const rect of opts.masks ?? []) {
+        applyMask(a.data, width, height, rect);
+        applyMask(b.data, width, height, rect);
+    }
+    const out = new PNG({ width, height });
+    const threshold = opts.threshold ?? VISUAL_PIXEL_THRESHOLD;
+    const changedPixels = pixelmatch(a.data, b.data, out.data, width, height, { threshold });
+    const totalPixels = width * height;
+    const ratio = totalPixels === 0 ? 0 : changedPixels / totalPixels;
+    const maxRatio = opts.maxRatio ?? 0;
+    const region = changedPixels > 0 ? changedRegion(out.data, width, height) : undefined;
+    const result = {
+        matched: ratio <= maxRatio,
+        changedPixels,
+        totalPixels,
+        ratio,
+        width,
+        height,
+        dimensionMismatch: false,
+        baseline: baseDims,
+        current: curDims,
+        diffPng: new Uint8Array(PNG.sync.write(out)),
+    };
+    return region === undefined ? result : { ...result, region };
+}
+//# sourceMappingURL=visual-diff.js.map

package/dist/visual/visual-diff.js.map

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

package/dist/visual/visual-store.d.ts

@@ -0,0 +1,22 @@
+import type { FileSystemPort } from '../project/fs-port.js';
+/**
+ * On-disk PNG baselines + diffs under .reticle/visual/. Binary sibling of FlowStore — same
+ * name guard (rejects path traversal before any join) and injected FileSystemPort, but bytes not text.
+ */
+export declare class VisualStore {
+    #private;
+    constructor(fs: FileSystemPort, root: string);
+    /** The absolute baseline path for `name` (for echoing back to the agent). */
+    baselinePath(name: string): string;
+    /** The absolute overlay-diff path for `name`. */
+    diffPath(name: string): string;
+    /** True iff a valid name and a baseline PNG exists on disk. */
+    hasBaseline(name: string): Promise<boolean>;
+    /** Write a PNG baseline (auto-creating .reticle/visual/). Returns its path; throws on a bad name. */
+    saveBaseline(name: string, png: Uint8Array): Promise<string>;
+    /** Read a PNG baseline, or undefined if absent / invalid name (never throws on missing). */
+    readBaseline(name: string): Promise<Uint8Array | undefined>;
+    /** Write the overlay diff PNG for `name` (auto-creating .reticle/visual/). Returns its path. */
+    saveDiff(name: string, png: Uint8Array): Promise<string>;
+}
+//# sourceMappingURL=visual-store.d.ts.map

package/dist/visual/visual-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visual-store.d.ts","sourceRoot":"","sources":["../../src/visual/visual-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAQ5D;;;GAGG;AACH,qBAAa,WAAW;;gBAIV,EAAE,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM;IAK5C,6EAA6E;IAC7E,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAIlC,iDAAiD;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAI9B,+DAA+D;IACzD,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKjD,qGAAqG;IAC/F,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IAQlE,4FAA4F;IACtF,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAYjE,gGAAgG;IAC1F,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;CAO/D"}

package/dist/visual/visual-store.js

@@ -0,0 +1,60 @@
+import { reticleDirPaths, isValidFlowName, visualDiffPath, visualPath, } from '../project/reticle-dir.js';
+/**
+ * On-disk PNG baselines + diffs under .reticle/visual/. Binary sibling of FlowStore — same
+ * name guard (rejects path traversal before any join) and injected FileSystemPort, but bytes not text.
+ */
+export class VisualStore {
+    #fs;
+    #root;
+    constructor(fs, root) {
+        this.#fs = fs;
+        this.#root = root;
+    }
+    /** The absolute baseline path for `name` (for echoing back to the agent). */
+    baselinePath(name) {
+        return visualPath(this.#root, name);
+    }
+    /** The absolute overlay-diff path for `name`. */
+    diffPath(name) {
+        return visualDiffPath(this.#root, name);
+    }
+    /** True iff a valid name and a baseline PNG exists on disk. */
+    async hasBaseline(name) {
+        if (!isValidFlowName(name))
+            return false;
+        return this.#fs.exists(visualPath(this.#root, name));
+    }
+    /** Write a PNG baseline (auto-creating .reticle/visual/). Returns its path; throws on a bad name. */
+    async saveBaseline(name, png) {
+        if (!isValidFlowName(name))
+            throw new Error(`invalid visual baseline name: ${name}`);
+        await this.#fs.mkdir(reticleDirPaths(this.#root).visual);
+        const path = visualPath(this.#root, name);
+        await this.#fs.writeFileBytes(path, png);
+        return path;
+    }
+    /** Read a PNG baseline, or undefined if absent / invalid name (never throws on missing). */
+    async readBaseline(name) {
+        if (!isValidFlowName(name) || !(await this.#fs.exists(visualPath(this.#root, name)))) {
+            return undefined;
+        }
+        try {
+            return await this.#fs.readFileBytes(visualPath(this.#root, name));
+        }
+        catch (error) {
+            if (this.#fs.isNotFound(error))
+                return undefined; // exists/read TOCTOU race
+            throw error;
+        }
+    }
+    /** Write the overlay diff PNG for `name` (auto-creating .reticle/visual/). Returns its path. */
+    async saveDiff(name, png) {
+        if (!isValidFlowName(name))
+            throw new Error(`invalid visual baseline name: ${name}`);
+        await this.#fs.mkdir(reticleDirPaths(this.#root).visual);
+        const path = visualDiffPath(this.#root, name);
+        await this.#fs.writeFileBytes(path, png);
+        return path;
+    }
+}
+//# sourceMappingURL=visual-store.js.map

package/dist/visual/visual-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"visual-store.js","sourceRoot":"","sources":["../../src/visual/visual-store.ts"],"names":[],"mappings":"AACA,OAAO,EACL,eAAe,EACf,eAAe,EACf,cAAc,EACd,UAAU,GACX,MAAM,2BAA2B,CAAC;AAEnC;;;GAGG;AACH,MAAM,OAAO,WAAW;IACb,GAAG,CAAiB;IACpB,KAAK,CAAS;IAEvB,YAAY,EAAkB,EAAE,IAAY;QAC1C,IAAI,CAAC,GAAG,GAAG,EAAE,CAAC;QACd,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;IAED,6EAA6E;IAC7E,YAAY,CAAC,IAAY;QACvB,OAAO,UAAU,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACtC,CAAC;IAED,iDAAiD;IACjD,QAAQ,CAAC,IAAY;QACnB,OAAO,cAAc,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAC1C,CAAC;IAED,+DAA+D;IAC/D,KAAK,CAAC,WAAW,CAAC,IAAY;QAC5B,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC;YAAE,OAAO,KAAK,CAAC;QACzC,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;IACvD,CAAC;IAED,qGAAqG;IACrG,KAAK,CAAC,YAAY,CAAC,IAAY,EAAE,GAAe;QAC9C,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,iCAAiC,IAAI,EAAE,CAAC,CAAC;QACrF,MAAM,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC;QACzD,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QAC1C,MAAM,IAAI,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QACzC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,4FAA4F;IAC5F,KAAK,CAAC,YAAY,CAAC,IAAY;QAC7B,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YACrF,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;QACpE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC;gBAAE,OAAO,SAAS,CAAC,CAAC,0BAA0B;YAC5E,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED,gGAAgG;IAChG,KAAK,CAAC,QAAQ,CAAC,IAAY,EAAE,GAAe;QAC1C,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,iCAAiC,IAAI,EAAE,CAAC,CAAC;QACrF,MAAM,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC;QACzD,MAAM,IAAI,GAAG,cAAc,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QAC9C,MAAM,IAAI,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QACzC,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/dist/visual/visual-tools.d.ts

@@ -0,0 +1,9 @@
+import type { ToolDef } from '../tools/tools.js';
+/**
+ * The opt-in pixel layer. Both tools require a DRIVEN browser (reticle drive /
+ * RETICLE_CDP_URL) — the always-on SDK ships no screenshotter — and return a structured NO_PROVIDER
+ * envelope (with a recommendation) instead of throwing when none is attached. Behavioral checks
+ * stay the default; this is the complementary "does it look right" surface, never bundled in.
+ */
+export declare const VISUAL_TOOLS: ToolDef[];
+//# sourceMappingURL=visual-tools.d.ts.map

package/dist/visual/visual-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visual-tools.d.ts","sourceRoot":"","sources":["../../src/visual/visual-tools.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,OAAO,EAAY,MAAM,mBAAmB,CAAC;AA+E3D;;;;;GAKG;AACH,eAAO,MAAM,YAAY,EAAE,OAAO,EA+GjC,CAAC"}