gazesight 0.4.0 → 0.5.0

package/dist/mcp/index.js

@@ -95,7 +95,7 @@ function loadConfig(env = process.env) {
 }
 
 // packages/protocol/src/release.ts
-var VERSION = "0.4.0";
+var VERSION = "0.5.0";
 
 // apps/mcp-server/src/bridge/websocket-server.ts
 import { WebSocketServer, WebSocket } from "ws";
@@ -252,9 +252,20 @@ var fullPageCaptureSchema = captureSchema.extend({
 });
 var navigateSchema = targetSchema.extend({ url: z3.url() });
 var diffSchema = z3.strictObject({
-  baseline: z3.uuid(),
+  baseline: z3.uuid().optional().describe(
+    "A prior PNG imageReference from this session. Omit and use referenceImagePath instead to diff against an external design reference."
+  ),
+  referenceImagePath: z3.string().min(1).max(4096).optional().describe(
+    "Path (relative to the MCP server's working directory, or absolute) to a local PNG design reference to diff the live capture against. Exactly one of baseline/referenceImagePath is required."
+  ),
   current: z3.uuid().optional(),
-  threshold: z3.number().finite().min(0).max(1).default(0.1)
+  tabId: z3.number().int().nonnegative().optional().describe(
+    "Only used with referenceImagePath when current is omitted, to select which tab to capture. Ignored otherwise (baseline's own tab is used)."
+  ),
+  threshold: z3.number().finite().min(0).max(1).default(0.1),
+  checkpoint: z3.string().min(1).max(200).regex(/^[A-Za-z0-9_-]+$/).optional().describe(
+    "Visual Convergence best-so-far tracking id (e.g. 'hero-desktop'). Only meaningful together with referenceImagePath: persists the best-known result locally and objectively reports isBest/regressed on every call, independent of the agent's own assessment."
+  )
 });
 var viewportProfileSchema = z3.enum([
   "mobile-small",
@@ -267,7 +278,10 @@ var setViewportSchema = targetSchema.extend({
   profile: viewportProfileSchema.optional(),
   width: z3.number().int().min(200).max(8192).optional(),
   height: z3.number().int().min(200).max(8192).optional(),
-  dedicatedPreview: z3.boolean().default(true)
+  dedicatedPreview: z3.boolean().default(true),
+  close: z3.boolean().optional().describe(
+    "Close the current dedicated preview window instead of creating or resizing one. Width/height/profile are ignored when true. Idempotent: has no effect if no preview is open."
+  )
 });
 var viewportResultSchema = z3.strictObject({
   tabId: z3.number().int().nonnegative(),
@@ -289,7 +303,10 @@ var viewportResultSchema = z3.strictObject({
   exact: z3.boolean().optional(),
   attempts: z3.number().int().min(0).max(3).optional(),
   requiresTargetSelection: z3.boolean().optional(),
-  sourceWindowUnchanged: z3.boolean().optional()
+  sourceWindowUnchanged: z3.boolean().optional(),
+  previewClosed: z3.boolean().optional().describe(
+    "Present when close:true was requested. True if a dedicated preview window was actually open and closed; false if there was none to close."
+  )
 });
 var domSchema = targetSchema.extend({
   selector: z3.string().min(1).max(2048).optional(),
@@ -1026,6 +1043,7 @@ var PairingService = class {
 
 // apps/mcp-server/src/bridge/websocket-server.ts
 var EMPTY_STATE = { selectedTab: null, url: null };
+var DEFAULT_HEARTBEAT_INTERVAL_MS = 2e4;
 function browserFromOrigin(origin) {
   if (origin === void 0) return void 0;
   if (/^moz-extension:\/\/[a-f0-9-]+\/?$/i.test(origin)) return "firefox";
@@ -1055,6 +1073,12 @@ var Bridge = class {
       response.setHeader("Content-Type", "application/json");
       response.end(JSON.stringify(this.status()));
     });
+    this.http.once("error", (error) => {
+      this.listenError = error.code === "EADDRINUSE" ? new GSError(
+        "GS_PORT_IN_USE",
+        `Port ${config.port} is already in use by another GazeSight MCP server. Only one can run at a time -- close the other session first.`
+      ) : error;
+    });
     this.server = new WebSocketServer({
       server: this.http,
       maxPayload: 17 * 1024 * 1024,
@@ -1077,6 +1101,11 @@ var Bridge = class {
         this.wiring.delete(connection.connectionId);
         this.registry.remove(connection.connectionId);
       };
+      this.alive.set(socket, { pongReceived: true });
+      socket.on("pong", () => {
+        const state = this.alive.get(socket);
+        if (state) state.pongReceived = true;
+      });
       socket.on("error", () => {
       });
       socket.on("message", (bytes, binary) => {
@@ -1131,12 +1160,28 @@ var Bridge = class {
       });
       socket.on("close", teardown);
     });
+    this.heartbeat = setInterval(() => {
+      for (const socket of this.server.clients) {
+        const state = this.alive.get(socket);
+        if (!state) continue;
+        if (!state.pongReceived) {
+          socket.terminate();
+          continue;
+        }
+        state.pongReceived = false;
+        socket.ping();
+      }
+    }, config.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS);
+    this.heartbeat.unref?.();
   }
   registry = new BrowserConnectionRegistry();
   activeTargetRouter = new ActiveTargetRouter();
   wiring = /* @__PURE__ */ new Map();
+  alive = /* @__PURE__ */ new WeakMap();
+  heartbeat;
   server;
   http;
+  listenError;
   pairing;
   // Resolves the connection currently backing the global active target, or
   // undefined if no browser is active (nothing selected yet, or the
@@ -1212,13 +1257,17 @@ var Bridge = class {
     };
   }
   async ready() {
+    if (this.listenError) throw this.listenError;
     if (this.server.address()) return;
     await new Promise((resolve, reject) => {
       this.server.once("listening", resolve);
-      this.server.once("error", reject);
+      const onError = () => reject(this.listenError);
+      this.server.once("error", onError);
+      this.http.once("error", onError);
     });
   }
   async close() {
+    clearInterval(this.heartbeat);
     for (const wiring of this.wiring.values()) wiring.router.disconnect();
     for (const client of this.server.clients) client.terminate();
     await new Promise((resolve) => this.server.close(() => resolve()));
@@ -1228,8 +1277,8 @@ var Bridge = class {
 
 // apps/mcp-server/src/server.ts
 import { McpServer } from "@modelcontextprotocol/server";
-import { writeFile, mkdir } from "node:fs/promises";
-import { join as join2 } from "node:path";
+import { writeFile as writeFile2, mkdir as mkdir2 } from "node:fs/promises";
+import { join as join3 } from "node:path";
 
 // apps/mcp-server/src/tools/capture.ts
 function toImage(value) {
@@ -1349,9 +1398,316 @@ async function runDiff(baseline, current, threshold) {
   }
 }
 
+// apps/mcp-server/src/tools/convergence.ts
+import { lstat, readFile, writeFile, mkdir } from "node:fs/promises";
+import { extname, join as join2 } from "node:path";
+import { homedir } from "node:os";
+
+// apps/mcp-server/src/tools/diff-engine.ts
+import pixelmatch from "pixelmatch";
+import { PNG } from "pngjs";
+var signature = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+function decodeBoundedPng(data) {
+  if (data.length > 16 * 1024 * 1024)
+    throw new GSError("GS_DIFF_LIMIT", "Encoded PNG exceeds 16 MiB.");
+  const bytes = Buffer.from(data, "base64");
+  if (bytes.length < 33 || !bytes.subarray(0, 8).equals(signature) || bytes.readUInt32BE(8) !== 13 || bytes.toString("ascii", 12, 16) !== "IHDR")
+    throw new GSError("GS_DIFF_FORMAT", "Use a PNG capture reference.");
+  const width = bytes.readUInt32BE(16), height = bytes.readUInt32BE(20);
+  if (!width || !height || width > 8192 || height > 8192 || width * height > 4e6)
+    throw new GSError(
+      "GS_DIFF_LIMIT",
+      "Diff is limited to 4 million pixels and 8192 pixels per side."
+    );
+  if (bytes[24] !== 8 || ![2, 6].includes(bytes[25]) || bytes[26] || bytes[27] || bytes[28])
+    throw new GSError(
+      "GS_DIFF_FORMAT",
+      "Use a non-interlaced 8-bit RGB/RGBA PNG capture."
+    );
+  try {
+    return PNG.sync.read(bytes, { checkCRC: true });
+  } catch {
+    throw new GSError("GS_DIFF_FORMAT", "PNG decoding failed.");
+  }
+}
+function diffPixels(baseline, current, threshold) {
+  const start = performance.now(), a = decodeBoundedPng(baseline), b = decodeBoundedPng(current);
+  if (a.width !== b.width || a.height !== b.height)
+    throw new GSError(
+      "GS_DIFF_DIMENSIONS",
+      "Capture both images at the same pixel dimensions."
+    );
+  const output = Buffer.alloc(a.data.length);
+  const changedPixelCount = pixelmatch(
+    a.data,
+    b.data,
+    output,
+    a.width,
+    a.height,
+    { threshold, includeAA: true, diffMask: true }
+  );
+  const columns = Math.ceil(a.width / 32), rows = Math.ceil(a.height / 32);
+  const tiles = /* @__PURE__ */ new Map();
+  for (let y = 0; y < a.height; y++)
+    for (let x = 0; x < a.width; x++)
+      if (output[(y * a.width + x) * 4 + 3]) {
+        const index = Math.floor(y / 32) * columns + Math.floor(x / 32), box = tiles.get(index);
+        if (box) {
+          box.left = Math.min(box.left, x);
+          box.top = Math.min(box.top, y);
+          box.right = Math.max(box.right, x + 1);
+          box.bottom = Math.max(box.bottom, y + 1);
+        } else
+          tiles.set(index, { left: x, top: y, right: x + 1, bottom: y + 1 });
+      }
+  const visited = /* @__PURE__ */ new Set(), boundingBoxes = [];
+  for (const [index, first] of tiles) {
+    if (visited.has(index)) continue;
+    const queue = [index], box = { ...first };
+    visited.add(index);
+    for (let i = 0; i < queue.length; i++) {
+      const key = queue[i], tile = tiles.get(key);
+      box.left = Math.min(box.left, tile.left);
+      box.top = Math.min(box.top, tile.top);
+      box.right = Math.max(box.right, tile.right);
+      box.bottom = Math.max(box.bottom, tile.bottom);
+      const col = key % columns, row = Math.floor(key / columns);
+      for (let dy = -1; dy <= 1; dy++)
+        for (let dx = -1; dx <= 1; dx++) {
+          const nx = col + dx, ny = row + dy, next = ny * columns + nx;
+          if (nx >= 0 && ny >= 0 && nx < columns && ny < rows && tiles.has(next) && !visited.has(next)) {
+            visited.add(next);
+            queue.push(next);
+          }
+        }
+    }
+    boundingBoxes.push({
+      x: box.left,
+      y: box.top,
+      width: box.right - box.left,
+      height: box.bottom - box.top
+    });
+  }
+  const boundingBoxesCoalesced = boundingBoxes.length > 100;
+  if (boundingBoxesCoalesced) {
+    const x = Math.min(...boundingBoxes.map((r) => r.x)), y = Math.min(...boundingBoxes.map((r) => r.y));
+    const right = Math.max(...boundingBoxes.map((r) => r.x + r.width)), bottom = Math.max(...boundingBoxes.map((r) => r.y + r.height));
+    boundingBoxes.splice(0, boundingBoxes.length, {
+      x,
+      y,
+      width: right - x,
+      height: bottom - y
+    });
+  }
+  const image = PNG.sync.write(
+    Object.assign(new PNG(), {
+      width: a.width,
+      height: a.height,
+      data: output
+    })
+  );
+  if (image.length * 4 / 3 > 16 * 1024 * 1024)
+    throw new GSError("GS_DIFF_LIMIT", "Encoded diff image exceeds 16 MiB.");
+  return {
+    changed: changedPixelCount > 0,
+    changedPixelCount,
+    differencePercent: changedPixelCount / (a.width * a.height) * 100,
+    boundingBoxes,
+    boundingBoxesCoalesced,
+    width: a.width,
+    height: a.height,
+    data: image.toString("base64"),
+    processingMs: performance.now() - start
+  };
+}
+
+// apps/mcp-server/src/tools/convergence.ts
+var MEANINGFUL_REGRESSION_PERCENT = 0.5;
+function checkpointRoot(platform = process.platform, home = homedir(), env = process.env) {
+  if (platform === "win32")
+    return join2(
+      env.APPDATA ?? join2(home, "AppData", "Roaming"),
+      "GazeSight",
+      "convergence"
+    );
+  if (platform === "darwin")
+    return join2(
+      home,
+      "Library",
+      "Application Support",
+      "GazeSight",
+      "convergence"
+    );
+  return join2(env.XDG_CONFIG_HOME ?? join2(home, ".config"), "gazesight", "convergence");
+}
+function checkpointDir(id, root) {
+  return join2(root, id);
+}
+async function loadCheckpoint(id, root) {
+  try {
+    const raw = await readFile(join2(checkpointDir(id, root), "best.json"), "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return void 0;
+  }
+}
+async function saveCheckpoint(id, root, state, pngBase64) {
+  const dir = checkpointDir(id, root);
+  await mkdir(dir, { recursive: true });
+  await writeFile(join2(dir, "best.json"), JSON.stringify(state, null, 2), "utf8");
+  await writeFile(join2(dir, "best.png"), Buffer.from(pngBase64, "base64"));
+}
+var RELIABILITY_THRESHOLD_PERCENT = MEANINGFUL_REGRESSION_PERCENT;
+async function observeCheckpoint(id, root, input, currentPngBase64) {
+  const dir = checkpointDir(id, root);
+  const bestImagePath = join2(dir, "best.png");
+  const prior = await loadCheckpoint(id, root);
+  const stabilityChecked = input.stabilityDifferencePercent !== void 0;
+  const stabilityFields = {
+    ...stabilityChecked ? { reliable: true } : {},
+    ...input.stabilityDifferencePercent !== void 0 ? { stabilityDifferencePercent: input.stabilityDifferencePercent } : {},
+    ...input.unstableBoundingBoxes ? { unstableBoundingBoxes: input.unstableBoundingBoxes } : {}
+  };
+  if (stabilityChecked && input.stabilityDifferencePercent >= RELIABILITY_THRESHOLD_PERCENT) {
+    const iteration2 = (prior?.totalIterations ?? 0) + 1;
+    if (prior)
+      await writeFile(
+        join2(dir, "best.json"),
+        JSON.stringify({ ...prior, totalIterations: iteration2 }, null, 2),
+        "utf8"
+      );
+    return {
+      isBest: false,
+      regressed: false,
+      shouldWarn: false,
+      iteration: iteration2,
+      bestDifferencePercent: prior?.bestDifferencePercent ?? input.differencePercent,
+      currentDifferencePercent: input.differencePercent,
+      bestImagePath,
+      ...stabilityFields,
+      reliable: false
+    };
+  }
+  const iteration = (prior?.totalIterations ?? 0) + 1;
+  if (!prior || input.differencePercent < prior.bestDifferencePercent) {
+    await saveCheckpoint(
+      id,
+      root,
+      {
+        bestDifferencePercent: input.differencePercent,
+        bestChangedPixelCount: input.changedPixelCount,
+        bestWidth: input.width,
+        bestHeight: input.height,
+        bestIteration: iteration,
+        totalIterations: iteration,
+        lastWarnedIteration: null,
+        referenceImagePath: input.referenceImagePath,
+        updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+      },
+      currentPngBase64
+    );
+    return {
+      isBest: true,
+      regressed: false,
+      shouldWarn: false,
+      iteration,
+      bestDifferencePercent: input.differencePercent,
+      currentDifferencePercent: input.differencePercent,
+      bestImagePath,
+      ...stabilityFields
+    };
+  }
+  const degradation = input.differencePercent - prior.bestDifferencePercent;
+  if (degradation < MEANINGFUL_REGRESSION_PERCENT) {
+    await writeFile(
+      join2(dir, "best.json"),
+      JSON.stringify({ ...prior, totalIterations: iteration }, null, 2),
+      "utf8"
+    );
+    return {
+      isBest: false,
+      regressed: false,
+      shouldWarn: false,
+      iteration,
+      bestDifferencePercent: prior.bestDifferencePercent,
+      currentDifferencePercent: input.differencePercent,
+      bestImagePath,
+      ...stabilityFields
+    };
+  }
+  const shouldWarn = prior.lastWarnedIteration === null;
+  await writeFile(
+    join2(dir, "best.json"),
+    JSON.stringify(
+      {
+        ...prior,
+        totalIterations: iteration,
+        lastWarnedIteration: shouldWarn ? iteration : prior.lastWarnedIteration
+      },
+      null,
+      2
+    ),
+    "utf8"
+  );
+  let regressionBoundingBoxes;
+  try {
+    const bestPng = await readFile(bestImagePath);
+    const { boundingBoxes } = diffPixels(
+      bestPng.toString("base64"),
+      currentPngBase64,
+      input.threshold
+    );
+    regressionBoundingBoxes = boundingBoxes;
+  } catch {
+  }
+  return {
+    isBest: false,
+    regressed: true,
+    shouldWarn,
+    iteration,
+    bestDifferencePercent: prior.bestDifferencePercent,
+    currentDifferencePercent: input.differencePercent,
+    bestImagePath,
+    ...regressionBoundingBoxes ? { regressionBoundingBoxes } : {},
+    ...stabilityFields
+  };
+}
+async function readReferenceImage(path) {
+  if (extname(path).toLowerCase() !== ".png" || path.includes("\0"))
+    throw new GSError(
+      "GS_REFERENCE_INVALID",
+      "referenceImagePath must identify a local PNG file."
+    );
+  let bytes;
+  try {
+    const entry = await lstat(path);
+    if (!entry.isFile() || entry.isSymbolicLink())
+      throw new Error("Reference is not a regular file");
+    bytes = await readFile(path);
+  } catch {
+    throw new GSError(
+      "GS_REFERENCE_NOT_FOUND",
+      "referenceImagePath could not be read. Use a path relative to the MCP server's working directory, or an absolute path."
+    );
+  }
+  if (bytes.length > 16 * 1024 * 1024)
+    throw new GSError(
+      "GS_DIFF_LIMIT",
+      "The reference PNG exceeds the 16 MiB local diff budget."
+    );
+  if (!bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])))
+    throw new GSError(
+      "GS_REFERENCE_INVALID",
+      "referenceImagePath must identify a valid local PNG file."
+    );
+  return bytes.toString("base64");
+}
+
 // packages/protocol/src/agent-guidance.ts
 var coreGuidance = `GazeSight gives you visual access to the developer's explicitly authorized browser tab \u2014 nothing else, and only when they selected it.
 
+If a separate, general-purpose browser automation tool is also available for the same check, prefer GazeSight's authorized tab over spinning up a new automated browser instance: it's the developer's real, already-running session (their actual logged-in state and environment), not a fresh, unauthenticated instance that may not even reproduce the page correctly, and needs no separate browser install. Fall back to a general-purpose browser tool only when no GazeSight tab is authorized for what you need to check.
+
 When visual accuracy matters: inspect the rendered page before assuming how it looks; verify frontend changes after implementing them; preserve existing application state unless the task requires changing it; prefer the project's existing assets, icons, fonts and design-system components over invented ones; use DOM inspection (visual_get_dom / visual_get_element) when a screenshot alone is ambiguous; use visual_diff when comparing two controlled captures; fix meaningful visible discrepancies before calling a visual task done; don't redesign an interface when the user asked for a faithful reproduction.
 
 Typical loop: inspect -> implement -> capture -> compare -> correct -> verify. Don't capture after every line of code, and prefer visual_capture_element or visual_capture_region over a full-page capture when only part of the page matters; use FAST for quick feedback and STABLE after changes that may still be settling. Avoid unnecessary reloads, navigation or viewport changes: most CSS/JS edits already hot-reload, and a reload can still reset in-page state even when GazeSight stays connected, so only reload when you have a specific reason to believe the page is stale. If a call ever returns GS_REAUTHORIZE_TARGET, wait briefly and retry once before assuming anything is wrong: GazeSight often reconnects automatically after a same-origin reload or navigation. Only tell the developer to click the extension again if that error persists.
@@ -1368,11 +1724,36 @@ Match as closely as practical: layout, spacing, alignment, component dimensions,
 After implementing: capture the result, compare it against the reference (visual_diff when a comparable baseline exists), and diagnose before editing \u2014 localize the problem with visual_diff or visual_get_changed_regions, or DOM/computed-style inspection, rather than guessing CSS values repeatedly. Correct in priority order: overall structure and layout, then element size and position, then typography, then spacing, then colors/borders/radius/shadows, then decorative details \u2014 don't polish a detail while the layout underneath is still wrong.
 
 Leave a region alone once it matches the reference unless the current fix depends on it. If a change makes the result visibly worse, revise or revert it before touching anything else, rather than layering more edits on top of a regression. Repeat diagnose -> correct -> verify until no meaningful visible difference remains, further edits stop producing visible improvement, a fix requires an asset or information you don't have, or the developer's stated acceptance criteria are met. Don't chase indefinite sub-pixel differences, and don't capture again without a specific reason to expect something changed.`;
+var visualConvergenceGuidance = `VISUAL CONVERGENCE (part of Visual Fidelity Mode) applies when a local PNG reference file is available and the task is to iteratively make the live page match it. Use visual_diff's referenceImagePath (not baseline) to compare the live capture directly against that file, and pass the same stable checkpoint id (e.g. "hero-desktop") on every call for that reference/viewport pair \u2014 this persists an objective, server-computed best-so-far result outside your own assessment.
+
+After every correction, call visual_diff again with the same referenceImagePath, checkpoint and viewport. Read isBest and regressed directly from the result rather than relying on your own visual impression of whether a change helped, and don't report a fix as successful without first confirming isBest:true or a lower currentDifferencePercent in that next call \u2014 a self-reported "reverted successfully" that the next measurement contradicts is a known failure mode. If regressed:true, the result's regressionBoundingBoxes and bestImagePath show exactly what changed since the best-known state and where to find it; use them as concrete recovery context and revise toward that best state rather than layering further edits on top of a regression. shouldWarn:true only marks the first call to observe a given regression episode; it will not repeat on every call while still regressed, so keep checking regressed on later calls rather than assuming an earlier warning is the only one that matters.
+
+If the developer or project supplies a convergence config (for example a local JSON file listing checkpoints with their referenceImagePath, viewport and tolerance/max-iteration limits), read and honor it: set the matching viewport with visual_set_viewport before each capture, and stop once currentDifferencePercent is within the stated tolerance.
+
+When checkpoint is used, visual_diff also runs an immediate self-vs-self recapture of the same tab and reports reliable, stabilityDifferencePercent and unstableBoundingBoxes alongside isBest/regressed on every call. reliable:false means this specific reading was too noisy (animation, video, a live clock, anything moving on its own) to trust: isBest/regressed in that same result reflect the untouched previous best-so-far state, not this reading \u2014 don't treat an unreliable call as either progress or a regression, and don't let it interrupt a correct-diagnose-verify sequence otherwise going well.
+
+Stop the convergence loop, and report honestly rather than as success, on any of these. Never continue indefinitely past them:
+- acceptable fidelity: currentDifferencePercent is within the stated tolerance (or, absent a stated tolerance, no meaningful visible difference remains per Visual Fidelity Mode above).
+- stagnation: two consecutive reliable calls show no improvement in currentDifferencePercent.
+- max iterations: the stated max-iteration count is reached, or, absent a stated limit, after at most 5 correction attempts for a single reference.
+- unrecoverable regression: regressed:true persists across repeated attempts to recover toward bestImagePath/regressionBoundingBoxes rather than clearing.
+- environmental instability: reliable:false persists across repeated attempts \u2014 the page itself is too noisy to measure (e.g. autoplaying media), not a fidelity problem you can fix by editing code; report which region is unstable (unstableBoundingBoxes) rather than continuing to chase it.`;
+var visualConvergenceAutoTriggerGuidance = `AUTOMATIC VISUAL CONVERGENCE TRIGGER: enter Visual Convergence (above) on your own, without the developer needing to mention GazeSight, whenever their request combines (a) genuine visual reproduction intent \u2014 asking you to build, reproduce, clone, match, replicate, or closely follow the look of something \u2014 with (b) an accessible visual reference: an attached/pasted image, a local design file path, or an existing page/URL to match. Detect this from meaning, not fixed phrases: the request can be in any language the connected coding agent supports (French, English, Spanish, Portuguese, German, and others), can mix languages, and may not use any of this guidance's own English words at all. Judge intent the way you would if a colleague said it to you in that language, not by scanning for keywords.
+
+Do not trigger on a visual reference alone: a screenshot attached to a bug report, an error message, a design discussion, or a "what does this look like" question is not a reproduction request even though an image is present. Both genuine reproduction intent AND an accessible reference are required together.
+
+If reproduction intent is clear but no reference is actually accessible yet (described verbally only, or an image mentioned but not attached/reachable), ask the developer for the reference in their own language rather than proceeding without one or silently skipping Visual Convergence.
+
+Once triggered, save any attached/pasted image to a local file first (Visual Convergence's referenceImagePath needs a path, not inline image data), then follow Visual Convergence and Visual Fidelity Mode above exactly as if the developer had asked for them by name. Give the developer status updates and the final verification report in the same language they used to make the request \u2014 translate none of it to English on their behalf. This applies per request: a developer switching languages between requests changes only that request's response language, not a standing preference.`;
 function buildInstructions(config) {
   if (!config.enabled) return void 0;
   return config.visualFidelity ? `${coreGuidance}
 
-${visualFidelityGuidance}` : coreGuidance;
+${visualFidelityGuidance}
+
+${visualConvergenceGuidance}
+
+${visualConvergenceAutoTriggerGuidance}` : coreGuidance;
 }
 
 // apps/mcp-server/src/server.ts
@@ -1438,12 +1819,12 @@ function createServer2(bridge, config) {
           ))
             throw new GSError(
               "GS_EXTENSION_OUTDATED",
-              "This tool requires a matching GazeSight 0.3.x Firefox extension. The 0.2 core remains available."
+              `This tool requires a matching GazeSight ${VERSION} browser extension. The core capture tools remain available regardless of extension version.`
             );
           if (type.startsWith("capture") && bridge.connected && bridge.state.targetState === void 0)
             throw new GSError(
               "GS_EXTENSION_OUTDATED",
-              "Load the GazeSight 0.2.0 dist/firefox/manifest.json in about:debugging, then click its icon in the target tab."
+              "Open the GazeSight browser extension (Firefox: install the signed version from https://addons.mozilla.org/addon/6a2319d4fa544731884d/ if not already installed) and click its icon in the target tab."
             );
           if ("url" in input && typeof input.url === "string")
             assertAllowedUrl(input.url, config.allowedOrigins);
@@ -1458,9 +1839,9 @@ function createServer2(bridge, config) {
               data: image.data
             }) : void 0;
             if (config.debugDir) {
-              await mkdir(config.debugDir, { recursive: true });
-              await writeFile(
-                join2(config.debugDir, `last-capture.${metadata.format}`),
+              await mkdir2(config.debugDir, { recursive: true });
+              await writeFile2(
+                join3(config.debugDir, `last-capture.${metadata.format}`),
                 Buffer.from(image.data, "base64")
               );
             }
@@ -1515,7 +1896,7 @@ function createServer2(bridge, config) {
   server.registerTool(
     "visual_diff",
     {
-      description: "Compare local PNG capture references from this MCP session. If current is omitted, capture the authorized baseline tab as PNG STABLE. Threshold is perceptual sensitivity, not allowed percent difference. No remote service; maximum 4 million pixels.",
+      description: "Compare local PNG capture references from this MCP session, or a live capture against an external PNG design reference (referenceImagePath) for Visual Convergence. If current is omitted, capture PNG STABLE (the baseline's tab, or tabId with referenceImagePath). Threshold is perceptual sensitivity, not allowed percent difference. Pass checkpoint with referenceImagePath to persist an objective, server-computed best-so-far result and get isBest/regressed on every call. No remote service; maximum 4 million pixels; both images must have identical pixel dimensions.",
       inputSchema: diffSchema,
       annotations: {
         readOnlyHint: true,
@@ -1536,57 +1917,123 @@ function createServer2(bridge, config) {
         };
       diffBusy = true;
       try {
-        if (!images)
+        if (!input.baseline && !input.referenceImagePath)
+          throw new GSError(
+            "GS_DIFF_TARGET",
+            "Provide either baseline (a prior imageReference) or referenceImagePath (an external PNG)."
+          );
+        if (input.baseline && input.referenceImagePath)
           throw new GSError(
-            "GS_IMAGE_NOT_FOUND",
-            "First request a PNG capture and use its imageReference."
+            "GS_DIFF_TARGET",
+            "Provide only one of baseline or referenceImagePath, not both."
           );
-        const baseline = images.get(input.baseline);
-        assertAllowedUrl(baseline.url, config.allowedOrigins);
+        let baselineData;
+        let baselineTabId;
+        let baselineUrl;
+        let baselineForDiffImage;
+        if (input.referenceImagePath) {
+          baselineData = await readReferenceImage(input.referenceImagePath);
+        } else {
+          if (!images)
+            throw new GSError(
+              "GS_IMAGE_NOT_FOUND",
+              "First request a PNG capture and use its imageReference."
+            );
+          const baseline = images.get(input.baseline);
+          assertAllowedUrl(baseline.url, config.allowedOrigins);
+          baselineData = baseline.data;
+          baselineTabId = baseline.tabId;
+          baselineUrl = baseline.url;
+          baselineForDiffImage = baseline;
+        }
+        const store = images ??= new ImageStore();
         let currentReference = input.current;
         if (!currentReference) {
           const capture = toImage(
             await bridge.router.request(
               "capture",
               captureSchema.parse({
-                tabId: baseline.tabId,
+                tabId: input.referenceImagePath ? input.tabId : baselineTabId,
                 format: "png",
                 waitForStable: true
               })
             )
           );
           assertAllowedUrl(capture.metadata.url, config.allowedOrigins);
-          currentReference = images.put({
+          currentReference = store.put({
             ...capture.metadata,
             format: "png",
             data: capture.image.data
           });
         }
-        const current = images.get(currentReference);
+        const current = store.get(currentReference);
         assertAllowedUrl(current.url, config.allowedOrigins);
-        if (baseline.tabId !== current.tabId || baseline.url !== current.url)
+        if (!input.referenceImagePath && (baselineTabId !== current.tabId || baselineUrl !== current.url))
           throw new GSError(
             "GS_DIFF_TARGET",
             "Both references must belong to the same tab and URL."
           );
         const { data, ...metadata } = await runDiff(
-          baseline.data,
+          baselineData,
           current.data,
           input.threshold
         );
-        const diffImage = images.put({
-          ...baseline,
+        const diffImage = store.put({
+          ...baselineForDiffImage ?? current,
           width: metadata.width,
           height: metadata.height,
           data
         });
         const result = {
           ...metadata,
-          baseline: input.baseline,
+          ...input.baseline ? { baseline: input.baseline } : {},
+          ...input.referenceImagePath ? { referenceImagePath: input.referenceImagePath } : {},
           current: currentReference,
           diffImage,
           threshold: input.threshold
         };
+        if (input.checkpoint && input.referenceImagePath) {
+          let stabilityDifferencePercent;
+          let unstableBoundingBoxes;
+          if (!input.current) {
+            try {
+              const recapture = toImage(
+                await bridge.router.request(
+                  "capture",
+                  captureSchema.parse({
+                    tabId: input.tabId,
+                    format: "png",
+                    waitForStable: false
+                  })
+                )
+              );
+              const stability = await runDiff(
+                current.data,
+                recapture.image.data,
+                input.threshold
+              );
+              stabilityDifferencePercent = stability.differencePercent;
+              unstableBoundingBoxes = stability.boundingBoxes;
+            } catch {
+            }
+          }
+          const observed = await observeCheckpoint(
+            input.checkpoint,
+            checkpointRoot(),
+            {
+              differencePercent: metadata.differencePercent,
+              changedPixelCount: metadata.changedPixelCount,
+              width: metadata.width,
+              height: metadata.height,
+              referenceImagePath: input.referenceImagePath,
+              threshold: input.threshold,
+              stabilityDifferencePercent,
+              unstableBoundingBoxes
+            },
+            current.data
+          );
+          Object.assign(result, { checkpoint: input.checkpoint, ...observed });
+        }
         return {
           content: [
             { type: "image", mimeType: "image/png", data },
@@ -1654,9 +2101,9 @@ try {
   process.once("SIGINT", () => void close());
   process.once("SIGTERM", () => void close());
   process.stdin.once("end", () => void close());
-} catch {
+} catch (error) {
   console.error(
-    "ERROR GazeSight startup failed. Check GAZESIGHT_PAIR_TOKEN (64 hex characters), port availability and configuration."
+    error instanceof Error && error.message ? `ERROR GazeSight startup failed: ${error.message}` : "ERROR GazeSight startup failed. Check GAZESIGHT_PAIR_TOKEN (64 hex characters), port availability and configuration."
   );
   process.exitCode = 1;
 }