gazesight 0.3.5

package/dist/worker/visual-diff.js

@@ -0,0 +1,642 @@
+// apps/mcp-server/src/tools/diff-worker.ts
+import { parentPort, workerData } from "node:worker_threads";
+
+// apps/mcp-server/src/tools/diff-engine.ts
+import pixelmatch from "pixelmatch";
+import { PNG } from "pngjs";
+
+// packages/protocol/src/schemas.ts
+import { z } from "zod";
+var targetSchema = z.strictObject({
+  tabId: z.number().int().nonnegative().optional()
+});
+var stabilityDiagnosticsSchema = z.strictObject({
+  stable: z.boolean(),
+  stabilityWaitMs: z.number().finite().nonnegative(),
+  lastMutationAgoMs: z.number().finite().nonnegative(),
+  fontsReady: z.boolean(),
+  pendingImages: z.number().int().nonnegative().max(1e6),
+  timeoutReached: z.boolean()
+});
+var diagnosticsQuerySchema = targetSchema.extend({
+  maxEntries: z.number().int().min(1).max(100).default(50),
+  reset: z.boolean().default(true)
+});
+var highlightSchema = targetSchema.extend({
+  selector: z.string().min(1).max(2048),
+  durationMs: z.number().int().min(500).max(3e4).default(3e3)
+});
+var highlightResultSchema = z.strictObject({
+  tabId: z.number().int().nonnegative(),
+  url: z.url(),
+  highlighted: z.boolean()
+});
+var consoleEntrySchema = z.strictObject({
+  level: z.enum(["warn", "error"]),
+  message: z.string().max(512),
+  timestamp: z.number().finite().nonnegative()
+});
+var networkEntrySchema = z.strictObject({
+  url: z.url().max(1024),
+  method: z.string().max(16),
+  resourceType: z.string().max(32),
+  status: z.number().int().min(100).max(599).optional(),
+  error: z.string().max(128).optional(),
+  timestamp: z.number().finite().nonnegative()
+});
+var consoleResultSchema = z.strictObject({
+  tabId: z.number().int().nonnegative(),
+  entries: z.array(consoleEntrySchema).max(100),
+  dropped: z.number().int().nonnegative(),
+  forwardingDropped: z.number().int().nonnegative()
+});
+var networkResultSchema = z.strictObject({
+  tabId: z.number().int().nonnegative(),
+  entries: z.array(networkEntrySchema).max(100),
+  dropped: z.number().int().nonnegative()
+});
+var pageStatusContentSchema = z.strictObject({
+  url: z.url(),
+  title: z.string().max(160),
+  readyState: z.enum(["loading", "interactive", "complete"]),
+  viewport: z.strictObject({
+    width: z.number().int().positive(),
+    height: z.number().int().positive(),
+    devicePixelRatio: z.number().finite().positive()
+  }),
+  scroll: z.strictObject({ x: z.number().finite(), y: z.number().finite() }),
+  stabilityPending: z.boolean(),
+  consoleInstrumentationActive: z.boolean(),
+  consoleForwardingDropped: z.number().int().nonnegative()
+});
+var pageStatusResultSchema = pageStatusContentSchema.extend({
+  tabId: z.number().int().nonnegative(),
+  targetState: z.enum(["authorized", "reauthorization_required", "none"]),
+  runtimeErrorCount: z.number().int().nonnegative(),
+  consoleEntryCount: z.number().int().nonnegative(),
+  networkFailureCount: z.number().int().nonnegative()
+});
+var interactionTypeSchema = z.enum([
+  "click",
+  "type",
+  "press_key",
+  "hover",
+  "scroll",
+  "select",
+  "focus"
+]);
+var interactionTargetSchema = targetSchema.extend({
+  selector: z.string().min(1).max(2048)
+});
+var typeSchema = interactionTargetSchema.extend({
+  text: z.string().max(4096),
+  clear: z.boolean().default(true)
+});
+var pressKeySchema = targetSchema.extend({
+  selector: z.string().min(1).max(2048).optional(),
+  key: z.string().max(12).refine(
+    (key) => key.length === 1 || [
+      "Enter",
+      "Escape",
+      "Tab",
+      "Backspace",
+      "Delete",
+      "ArrowUp",
+      "ArrowDown",
+      "ArrowLeft",
+      "ArrowRight",
+      "Home",
+      "End"
+    ].includes(key)
+  ),
+  shift: z.boolean().default(false)
+});
+var scrollSchema = targetSchema.extend({
+  selector: z.string().min(1).max(2048).optional(),
+  x: z.number().finite().min(-1e6).max(1e6).default(0),
+  y: z.number().finite().min(-1e6).max(1e6).default(0),
+  mode: z.enum(["by", "to"]).default("by")
+});
+var selectSchema = interactionTargetSchema.extend({
+  value: z.string().max(4096)
+});
+var interactionResultSchema = z.strictObject({
+  tabId: z.number().int().nonnegative(),
+  url: z.url(),
+  action: interactionTypeSchema,
+  inputSource: z.literal("dom"),
+  completed: z.literal(true),
+  scroll: z.strictObject({ x: z.number().finite(), y: z.number().finite() }).optional()
+});
+var captureSchema = targetSchema.extend({
+  url: z.url().optional(),
+  format: z.enum(["png", "jpeg"]).default("jpeg"),
+  quality: z.number().int().min(0).max(100).default(85),
+  waitForStable: z.boolean().default(false),
+  includeOverlay: z.boolean().optional(),
+  stableWindowMs: z.number().int().min(20).max(1e3).default(100),
+  maxWaitMs: z.number().int().min(50).max(5e3).default(2e3)
+});
+var reloadSchema = targetSchema.extend({
+  bypassCache: z.boolean().default(false)
+});
+var regionCaptureSchema = captureSchema.extend({
+  x: z.number().finite().nonnegative(),
+  y: z.number().finite().nonnegative(),
+  width: z.number().finite().positive().max(32768),
+  height: z.number().finite().positive().max(32768)
+});
+var elementCaptureSchema = captureSchema.extend({
+  selector: z.string().min(1).max(2048),
+  padding: z.number().finite().min(0).max(1e3).default(0)
+});
+var fullPageCaptureSchema = captureSchema.extend({
+  maxPixels: z.number().int().min(1).max(32e6).default(16e6),
+  maxSegments: z.number().int().min(1).max(64).default(32),
+  timeoutMs: z.number().int().min(500).max(8e3).default(7e3)
+});
+var navigateSchema = targetSchema.extend({ url: z.url() });
+var diffSchema = z.strictObject({
+  baseline: z.uuid(),
+  current: z.uuid().optional(),
+  threshold: z.number().finite().min(0).max(1).default(0.1)
+});
+var viewportProfileSchema = z.enum([
+  "mobile-small",
+  "mobile",
+  "tablet",
+  "desktop",
+  "desktop-wide"
+]);
+var setViewportSchema = targetSchema.extend({
+  profile: viewportProfileSchema.optional(),
+  width: z.number().int().min(200).max(8192).optional(),
+  height: z.number().int().min(200).max(8192).optional(),
+  dedicatedPreview: z.boolean().default(true)
+});
+var viewportResultSchema = z.strictObject({
+  tabId: z.number().int().nonnegative(),
+  url: z.url(),
+  windowId: z.number().int().nonnegative(),
+  width: z.number().int().positive(),
+  height: z.number().int().positive(),
+  devicePixelRatio: z.number().finite().positive(),
+  zoom: z.number().finite().positive(),
+  outerWidth: z.number().int().positive(),
+  outerHeight: z.number().int().positive(),
+  dedicatedPreview: z.boolean(),
+  sourceTabId: z.number().int().nonnegative().optional(),
+  requested: z.strictObject({
+    width: z.number().int().positive(),
+    height: z.number().int().positive(),
+    profile: viewportProfileSchema.optional()
+  }).optional(),
+  exact: z.boolean().optional(),
+  attempts: z.number().int().min(0).max(3).optional(),
+  requiresTargetSelection: z.boolean().optional(),
+  sourceWindowUnchanged: z.boolean().optional()
+});
+var domSchema = targetSchema.extend({
+  selector: z.string().min(1).max(2048).optional(),
+  depth: z.number().int().min(0).max(8).default(3),
+  maxNodes: z.number().int().min(1).max(300).default(100),
+  textLength: z.number().int().min(0).max(300).default(160),
+  maxBytes: z.number().int().min(2048).max(65536).default(32768)
+});
+var getElementSchema = domSchema.extend({
+  selector: z.string().min(1).max(2048)
+});
+var changedRegionsSchema = targetSchema.extend({
+  maxRegions: z.number().int().min(1).max(100).default(50),
+  reset: z.boolean().default(true)
+});
+var capabilitySchema = z.enum([
+  "highlight",
+  "clear_highlight",
+  "capture_region",
+  "capture_element",
+  "capture_full_page",
+  "get_dom",
+  "get_element",
+  "get_changed_regions",
+  "get_viewport",
+  "set_viewport",
+  ...interactionTypeSchema.options,
+  "get_console",
+  "get_network_failures",
+  "get_page_status"
+]);
+var boundsSchema = z.strictObject({
+  x: z.number().finite(),
+  y: z.number().finite(),
+  width: z.number().finite().nonnegative(),
+  height: z.number().finite().nonnegative()
+});
+var domNodeSchema = z.strictObject({
+  index: z.number().int().nonnegative(),
+  parent: z.number().int().nonnegative().optional(),
+  depth: z.number().int().min(0).max(8),
+  tag: z.string().max(80),
+  id: z.string().max(160).optional(),
+  classes: z.array(z.string().max(80)).max(6).optional(),
+  role: z.string().max(80).optional(),
+  text: z.string().max(300).optional(),
+  ariaLabel: z.string().max(300).optional(),
+  name: z.string().max(160).optional(),
+  type: z.string().max(80).optional(),
+  href: z.string().max(1024).optional(),
+  bounds: boundsSchema,
+  visible: z.boolean(),
+  redacted: z.boolean().optional(),
+  disabled: z.boolean().optional(),
+  checked: z.boolean().optional(),
+  selected: z.boolean().optional()
+});
+var domResultSchema = z.strictObject({
+  tabId: z.number().int().nonnegative(),
+  url: z.url(),
+  nodes: z.array(domNodeSchema).max(300),
+  truncated: z.boolean(),
+  payloadBytes: z.number().int().max(65536)
+});
+var changedRegionsResultSchema = z.strictObject({
+  tabId: z.number().int().nonnegative(),
+  url: z.url(),
+  regions: z.array(
+    boundsSchema.extend({
+      reason: z.enum(["mutation", "resize", "attribute", "text"]),
+      selector: z.string().max(240).optional()
+    })
+  ).max(100),
+  trackingStarted: z.boolean(),
+  dropped: z.number().int().nonnegative(),
+  coverage: z.literal("potential-dom-and-layout-changes")
+});
+var errorSchema = z.strictObject({
+  type: z.enum(["error", "unhandledrejection", "console-error"]),
+  message: z.string().max(4096),
+  source: z.string().max(2048).optional(),
+  line: z.number().int().nonnegative().optional(),
+  column: z.number().int().nonnegative().optional(),
+  timestamp: z.number().nonnegative()
+});
+var stateSchema = z.strictObject({
+  extensionVersion: z.string().max(80).optional(),
+  extensionId: z.string().min(1).max(256).optional(),
+  capabilities: z.array(capabilitySchema).max(20).optional(),
+  selectedTab: z.number().int().nonnegative().nullable(),
+  url: z.string().max(2048).nullable(),
+  targetState: z.enum(["none", "authorized", "reauthorization_required"]).optional(),
+  browser: z.strictObject({
+    name: z.enum(["firefox", "chrome"]),
+    version: z.string().max(80)
+  }).optional(),
+  backgroundCapture: z.strictObject({
+    enabled: z.boolean(),
+    permissionGranted: z.boolean()
+  }).optional()
+});
+var requestSchema = z.discriminatedUnion("type", [
+  z.strictObject({
+    id: z.uuid(),
+    version: z.literal(1),
+    type: z.literal("highlight"),
+    payload: highlightSchema
+  }),
+  z.strictObject({
+    id: z.uuid(),
+    version: z.literal(1),
+    type: z.literal("clear_highlight"),
+    payload: targetSchema
+  }),
+  z.strictObject({
+    id: z.uuid(),
+    version: z.literal(1),
+    type: z.literal("get_console"),
+    payload: diagnosticsQuerySchema
+  }),
+  z.strictObject({
+    id: z.uuid(),
+    version: z.literal(1),
+    type: z.literal("get_network_failures"),
+    payload: diagnosticsQuerySchema
+  }),
+  z.strictObject({
+    id: z.uuid(),
+    version: z.literal(1),
+    type: z.literal("get_page_status"),
+    payload: targetSchema
+  }),
+  z.strictObject({
+    id: z.uuid(),
+    version: z.literal(1),
+    type: z.literal("click"),
+    payload: interactionTargetSchema
+  }),
+  z.strictObject({
+    id: z.uuid(),
+    version: z.literal(1),
+    type: z.literal("type"),
+    payload: typeSchema
+  }),
+  z.strictObject({
+    id: z.uuid(),
+    version: z.literal(1),
+    type: z.literal("press_key"),
+    payload: pressKeySchema
+  }),
+  z.strictObject({
+    id: z.uuid(),
+    version: z.literal(1),
+    type: z.literal("hover"),
+    payload: interactionTargetSchema
+  }),
+  z.strictObject({
+    id: z.uuid(),
+    version: z.literal(1),
+    type: z.literal("scroll"),
+    payload: scrollSchema
+  }),
+  z.strictObject({
+    id: z.uuid(),
+    version: z.literal(1),
+    type: z.literal("select"),
+    payload: selectSchema
+  }),
+  z.strictObject({
+    id: z.uuid(),
+    version: z.literal(1),
+    type: z.literal("focus"),
+    payload: interactionTargetSchema
+  }),
+  z.strictObject({
+    id: z.uuid(),
+    version: z.literal(1),
+    type: z.literal("get_viewport"),
+    payload: targetSchema
+  }),
+  z.strictObject({
+    id: z.uuid(),
+    version: z.literal(1),
+    type: z.literal("set_viewport"),
+    payload: setViewportSchema
+  }),
+  z.strictObject({
+    id: z.uuid(),
+    version: z.literal(1),
+    type: z.literal("get_dom"),
+    payload: domSchema
+  }),
+  z.strictObject({
+    id: z.uuid(),
+    version: z.literal(1),
+    type: z.literal("get_element"),
+    payload: getElementSchema
+  }),
+  z.strictObject({
+    id: z.uuid(),
+    version: z.literal(1),
+    type: z.literal("get_changed_regions"),
+    payload: changedRegionsSchema
+  }),
+  z.strictObject({
+    id: z.uuid(),
+    version: z.literal(1),
+    type: z.literal("capture_region"),
+    payload: regionCaptureSchema
+  }),
+  z.strictObject({
+    id: z.uuid(),
+    version: z.literal(1),
+    type: z.literal("capture_element"),
+    payload: elementCaptureSchema
+  }),
+  z.strictObject({
+    id: z.uuid(),
+    version: z.literal(1),
+    type: z.literal("capture_full_page"),
+    payload: fullPageCaptureSchema
+  }),
+  z.strictObject({
+    id: z.uuid(),
+    version: z.literal(1),
+    type: z.literal("capture"),
+    payload: captureSchema
+  }),
+  z.strictObject({
+    id: z.uuid(),
+    version: z.literal(1),
+    type: z.literal("reload"),
+    payload: reloadSchema
+  }),
+  z.strictObject({
+    id: z.uuid(),
+    version: z.literal(1),
+    type: z.literal("navigate"),
+    payload: navigateSchema
+  }),
+  z.strictObject({
+    id: z.uuid(),
+    version: z.literal(1),
+    type: z.literal("get_errors"),
+    payload: targetSchema
+  })
+]);
+var responseSchema = z.discriminatedUnion("ok", [
+  z.strictObject({
+    id: z.uuid(),
+    version: z.literal(1),
+    ok: z.literal(true),
+    result: z.unknown()
+  }),
+  z.strictObject({
+    id: z.uuid(),
+    version: z.literal(1),
+    ok: z.literal(false),
+    error: z.strictObject({
+      code: z.string().max(80),
+      message: z.string().max(4096),
+      stability: stabilityDiagnosticsSchema.optional()
+    })
+  })
+]);
+var helloSchema = z.strictObject({
+  version: z.literal(1),
+  type: z.literal("hello"),
+  token: z.string().regex(/^[a-f0-9]{64}$/),
+  state: stateSchema
+});
+var stateMessageSchema = z.strictObject({
+  version: z.literal(1),
+  type: z.literal("state"),
+  state: stateSchema
+});
+var captureResultSchema = z.strictObject({
+  tabId: z.number().int().nonnegative(),
+  url: z.url(),
+  width: z.number().int().positive(),
+  height: z.number().int().positive(),
+  format: z.enum(["png", "jpeg"]),
+  captureMs: z.number().nonnegative(),
+  processingMs: z.number().nonnegative().optional(),
+  totalMs: z.number().nonnegative().optional(),
+  segments: z.number().int().positive().max(64).optional(),
+  scrollRestored: z.boolean().optional(),
+  stabilityWaitMs: z.number().nonnegative().optional(),
+  extensionTotalMs: z.number().nonnegative().optional(),
+  renderAppearsStable: z.boolean().optional(),
+  stable: z.boolean().optional(),
+  lastMutationAgoMs: z.number().finite().nonnegative().optional(),
+  fontsReady: z.boolean().optional(),
+  pendingImages: z.number().int().nonnegative().optional(),
+  timeoutReached: z.boolean().optional(),
+  dataUrl: z.string().max(16 * 1024 * 1024)
+});
+var tabResultSchema = z.strictObject({
+  tabId: z.number().int().nonnegative(),
+  url: z.url()
+});
+var errorsResultSchema = z.strictObject({
+  tabId: z.number().int().nonnegative(),
+  errors: z.array(errorSchema).max(200)
+});
+var GSError = class extends Error {
+  constructor(code, message, stability) {
+    super(message);
+    this.code = code;
+    this.stability = stability;
+  }
+};
+
+// apps/mcp-server/src/tools/diff-engine.ts
+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/diff-worker.ts
+try {
+  parentPort?.postMessage({
+    ok: true,
+    value: diffPixels(
+      workerData.baseline,
+      workerData.current,
+      workerData.threshold
+    )
+  });
+} catch (error) {
+  parentPort?.postMessage({
+    ok: false,
+    code: error instanceof GSError ? error.code : "GS_DIFF_FAILED"
+  });
+}

package/docs/preview-matrix.csv

@@ -0,0 +1,6 @@
+Tester,OS,Firefox version,Coding agent,Install success,Setup success,Doctor result,TTFC seconds,FAST capture,STABLE capture,HMR verification,Reauthorization understood,Problems encountered
+Tester 1,,,,,,,,,,,,
+Tester 2,,,,,,,,,,,,
+Tester 3,,,,,,,,,,,,
+Tester 4,,,,,,,,,,,,
+Tester 5,,,,,,,,,,,,