@reticlehq/electron 2.3.0

package/LICENSE

@@ -0,0 +1,33 @@
+Reticle — License overview
+Copyright (c) 2026 Reticle Labs
+
+Reticle uses a per-package license model so the SDK is safe to embed in your own
+application while the server and enterprise features remain protected. The
+license that applies depends on the package. Each package contains its own
+LICENSE file, which is authoritative.
+
+1. Apache License, Version 2.0 — the wire contract + the embeddable SDK
+   Packages: @reticlehq/core, @reticlehq/browser, @reticlehq/react,
+   @reticlehq/babel-plugin, @reticlehq/next, @reticlehq/vite-plugin,
+   @reticlehq/eslint-plugin
+   @reticlehq/core is the bottom-of-graph wire contract (constants + zod schemas,
+   zod its only dependency); every embeddable SDK package above depends on it, so
+   it is Apache-2.0 too — that is what makes the SDK genuinely safe to embed. These
+   run inside / compile into your application. Use them anywhere, including in apps
+   you ship to your own customers. See the LICENSE and NOTICE files in each package.
+   (@reticlehq/protocol is a deprecated, unpublished Apache-2.0 alias of core.)
+
+2. Functional Source License, Version 1.1, Apache 2.0 future (FSL-1.1-ALv2)
+   Packages: @reticlehq/server, @reticlehq/test
+   Free for any Permitted Purpose (internal use, development, evaluation,
+   non-commercial research/education, professional services). The one
+   restriction is a Competing Use — offering Reticle itself as a competing
+   product or service. Each version converts to Apache-2.0 two years after
+   its release. See the LICENSE file in each package.
+
+3. The Reticle Enterprise License — enterprise features
+   Path: packages/server/src/ee/ (source-available)
+   Free for development and evaluation; production use requires a valid Reticle
+   Enterprise subscription license key. See packages/server/src/ee/LICENSE.
+
+For OEM / embedding / commercial licensing questions: hey@reticle.sh

package/NOTICE

@@ -0,0 +1,5 @@
+Reticle
+Copyright 2026 Reticle Labs
+
+This product includes software developed at Reticle Labs.
+Licensed under the Apache License, Version 2.0.

package/README.md

@@ -0,0 +1,49 @@
+# @reticlehq/electron
+
+Reticle's Electron adapter — the two places a renderer cannot reach.
+
+Everything else Reticle does inside an Electron app is the ordinary browser SDK (`@reticlehq/browser`). This package exists for the two things the renderer physically cannot do: observe IPC (a `contextBridge` object is deeply frozen and non-configurable) and screenshot the window (the renderer has no access to its own pixels).
+
+Both are **dev-only**. Gate each `require` behind your own dev check so neither ships.
+
+## IPC observation — one line at the top of your preload
+
+```js
+require('@reticlehq/electron/preload');
+```
+
+It must come **first**, before your own `require('electron')` and before `contextBridge.exposeInMainWorld`. It wraps `ipcRenderer.invoke` while that function is still ordinary and writable, so every channel your preload goes on to expose is covered.
+
+Each call then reaches the agent as an ordinary network record — `ipc://<channel>`, with `initiator: "ipc"`, the duration, and the error the main process actually threw:
+
+```
+reticle_network { ok: false }  →  ipc://todos:archive  ok:false  "archive is not implemented"
+```
+
+Without it, a desktop app's whole backend is invisible: `reticle_network` reports nothing, which reads as "this app makes no backend calls" rather than "you are blind to all of them". The SDK declares that as a `coverage: partial` blind spot rather than letting the silence pass, and `reticle doctor` names the missing line.
+
+> A **sandboxed** preload cannot resolve `node_modules`. Either bundle the preload (electron-vite and Electron Forge do this by default, and the `require` is inlined at build time, so sandboxing stays on) or set `sandbox: false` for an unbundled dev preload.
+
+## Screenshots — one line in the main process
+
+```js
+const { installReticleCapture } = require('@reticlehq/electron/main');
+
+const win = new BrowserWindow({ ... });
+installReticleCapture(win);
+```
+
+`reticle_screenshot` and `reticle_visual_diff` now work. It uses `webContents.capturePage()`, which reads the window's own backing store — correct while the window is behind your editor, correct while backgrounded, and needing no screen-recording permission. Capturing a screen region was deliberately not used: it photographs whatever is on top, which would bank a picture of your editor as a visual baseline.
+
+Safe to call for several windows; the handler registers once and answers for whichever window asked.
+
+`{ fullPage: true }` is **refused**, not silently downgraded — `capturePage()` composites the viewport, and handing back a viewport image for a full-page request would bank a baseline that says nothing about the content below the fold.
+
+## Requirements
+
+- Electron >= 22 (peer dependency)
+- A renderer running `@reticlehq/browser` — see [Desktop apps: Electron & Tauri][docs].
+
+[docs]: https://github.com/reticlehq/reticle/blob/main/docs/desktop-apps.md
+
+Apache-2.0

package/main.cjs

@@ -0,0 +1,134 @@
+'use strict';
+/**
+ * Reticle's Electron MAIN-process helper — the screenshot half of desktop support.
+ *
+ *     const { installReticleCapture } = require('@reticlehq/electron/main');
+ *     const win = new BrowserWindow({ ... });
+ *     installReticleCapture(win);
+ *
+ * ...and `reticle_screenshot` / `reticle_visual_diff` work on your app.
+ *
+ * Why the main process: `webContents.capturePage()` reads the window's own BACKING STORE. That makes
+ * it correct while the window is behind your editor, correct while it is backgrounded, and free of
+ * any screen-recording permission. Capturing a screen region instead was tried and rejected — it
+ * photographs whatever is on top, which would quietly save a picture of your editor as a visual
+ * baseline. Renderer-side capture is not an option either: the renderer has no access to the pixels.
+ *
+ * Dev-only, like the rest of Reticle. Gate the require behind your dev check so it never ships.
+ */
+const { ipcMain } = require('electron');
+const { writeFile, readdir, stat, unlink } = require('node:fs/promises');
+const { tmpdir } = require('node:os');
+const { join } = require('node:path');
+// Generated from @reticlehq/core's TypeScript source, so the main process, the preload and the
+// daemon agree by construction rather than by three people copying the same string.
+const {
+  RETICLE_CAPTURE_CHANNEL,
+  RETICLE_CAPTURE_FILE_PREFIX,
+  RETICLE_FULL_PAGE_UNSUPPORTED,
+} = require('@reticlehq/core/desktop-contract');
+
+let captureSeq = 0;
+/** One ipcMain handler serves every window — the channel is global, so registration is once-only. */
+let registered = false;
+/** Windows this app registered, so a capture survives its requester being destroyed. */
+const windows = new Set();
+
+/**
+ * The webContents to photograph: the requester if it is alive, else the ONE remaining window.
+ *
+ * The fallback exists for a window that closed mid-command — answering "no image" there reports a
+ * capture failure with no cause. But it only applies when exactly one window is left, because with
+ * two the choice is a guess: picking "any" window silently returns a picture of a DIFFERENT window
+ * and reports it as a successful capture of the one that was asked for, which is the same
+ * photographed-the-wrong-thing failure that ruled out capturing a screen region in the first place.
+ * Ambiguous means no image, and no image is a result the caller can act on.
+ */
+function usableContents(sender) {
+  if (sender !== null && sender !== undefined && !sender.isDestroyed()) return sender;
+  const alive = [...windows]
+    .map((win) => win?.webContents)
+    .filter((contents) => contents !== undefined && contents !== null && !contents.isDestroyed());
+  return alive.length === 1 ? alive[0] : null;
+}
+
+/**
+ * Delete this process's earlier captures before writing a new one.
+ *
+ * The daemon unlinks a capture after reading it, but only if it ever reads: a session that died, a
+ * command that timed out, or a path the daemon rejected all leave a ~300KB PNG in the temp directory
+ * forever. Sweeping our own prefix on each capture bounds that to one file at a time, with no timer
+ * to leak and no cleanup handler to forget. Best-effort — a failed sweep must never fail a capture.
+ *
+ * Only files older than STALE_CAPTURE_MS are swept. Deleting every sibling unconditionally raced
+ * with CONCURRENT captures: with two screenshots in flight, the second one's sweep unlinked the
+ * first one's PNG before the daemon had read it, and the daemon then answered `no-visual-provider`
+ * — which reads as "this app installed no capture helper" when the helper is installed and working.
+ */
+const STALE_CAPTURE_MS = 60_000;
+
+async function sweepOldCaptures(dir, keepFile) {
+  const mine = `${RETICLE_CAPTURE_FILE_PREFIX}${String(process.pid)}-`;
+  const cutoff = Date.now() - STALE_CAPTURE_MS;
+  try {
+    const entries = await readdir(dir);
+    await Promise.all(
+      entries
+        .filter((name) => name.startsWith(mine) && join(dir, name) !== keepFile)
+        .map(async (name) => {
+          const file = join(dir, name);
+          const info = await stat(file).catch(() => undefined);
+          if (info !== undefined && info.mtimeMs < cutoff)
+            await unlink(file).catch(() => undefined);
+        }),
+    );
+  } catch {
+    /* the temp dir is unreadable; a capture is still worth attempting */
+  }
+}
+
+/**
+ * Let Reticle screenshot this window. Safe to call for several windows; the handler is registered
+ * once and answers for whichever window asked, so a multi-window app needs no extra wiring.
+ */
+function installReticleCapture(win) {
+  if (win === null || win === undefined) return;
+  // Remembered so a capture can still resolve if the requesting webContents has gone (a window
+  // closing mid-command), rather than returning null and reporting an unexplained capture failure.
+  windows.add(win);
+  win.on?.('closed', () => windows.delete(win));
+
+  if (!registered) {
+    ipcMain.handle(RETICLE_CAPTURE_CHANNEL, async (event, options) => {
+      // `capturePage()` reads the composited window, so there is no full-document render to ask for.
+      // Saying so beats handing back a viewport the caller thinks covers the whole scroll height.
+      if (options && options.fullPage === true) throw new Error(RETICLE_FULL_PAGE_UNSUPPORTED);
+      const contents = usableContents(event.sender);
+      if (contents === null) return null;
+      try {
+        const image = await contents.capturePage();
+        // An empty image means the window had nothing to compose yet; report it as no-image rather
+        // than handing back a 0-byte PNG that a diff would treat as a real, blank baseline.
+        if (image.isEmpty()) return null;
+        // Write to a temp FILE and return its path, rather than base64 over the bridge. The SDK's
+        // transport sanitizer caps every string at 64KB, so a real screenshot came back silently
+        // truncated — an invalid PNG that still reported `saved: true`. The daemon and the app are
+        // always on the same machine here (the bridge is loopback), so a path is the honest channel:
+        // no size cap, no chunking, and nothing large on the event wire.
+        captureSeq += 1;
+        const file = join(
+          tmpdir(),
+          `${RETICLE_CAPTURE_FILE_PREFIX}${String(process.pid)}-${String(captureSeq)}.png`,
+        );
+        await writeFile(file, image.toPNG());
+        await sweepOldCaptures(tmpdir(), file);
+        return file;
+      } catch {
+        return null;
+      }
+    });
+    registered = true;
+  }
+}
+
+module.exports = { installReticleCapture };

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@reticlehq/electron",
+  "version": "2.3.0",
+  "description": "Reticle adapter for Electron: makes main-process IPC observable and the window screenshottable, from the two places the renderer cannot reach.",
+  "type": "module",
+  "exports": {
+    "./preload": "./preload.cjs",
+    "./main": "./main.cjs"
+  },
+  "dependencies": {
+    "@reticlehq/core": "2.3.0"
+  },
+  "peerDependencies": {
+    "electron": ">=22"
+  },
+  "license": "Apache-2.0",
+  "author": "Reticle contributors",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reticlehq/reticle.git",
+    "directory": "packages/electron"
+  },
+  "homepage": "https://github.com/reticlehq/reticle#readme",
+  "bugs": "https://github.com/reticlehq/reticle/issues",
+  "files": [
+    "preload.cjs",
+    "main.cjs",
+    "README.md",
+    "NOTICE"
+  ],
+  "keywords": [
+    "electron",
+    "reticle",
+    "ai-agents",
+    "testing",
+    "instrumentation"
+  ]
+}

package/preload.cjs

@@ -0,0 +1,238 @@
+'use strict';
+/**
+ * Reticle's Electron preload shim. Add ONE line at the top of your preload, before you expose
+ * anything:
+ *
+ *     require('@reticlehq/electron/preload');
+ *
+ * ...and every `ipcRenderer.invoke`, `sendSync` and `send` your app makes becomes a Reticle-visible
+ * request (`ipc://<channel>`), so net assertions and settle-waiting cover the main-process hop.
+ * A one-way `send` is recorded as DISPATCHED with no outcome, because that is all the renderer knows.
+ *
+ * Why a preload shim and not renderer-side patching, like every other Reticle observer:
+ * `contextBridge.exposeInMainWorld` hands the renderer a DEEPLY FROZEN object, installed on `window`
+ * as non-writable AND non-configurable. Neither assignment nor defineProperty can replace a method on
+ * it — verified, not assumed. The renderer physically cannot instrument an app's IPC surface. The
+ * preload is the last point where the functions are still ordinary and writable.
+ *
+ * This file is hand-written CommonJS on purpose: a sandboxed Electron preload is CJS-only and cannot
+ * load the ESM SDK build.
+ *
+ * Dev-only, like the rest of Reticle. Gate the require behind your dev check so it never ships.
+ */
+const { contextBridge, ipcRenderer } = require('electron');
+// The ONE definition of these strings, generated from @reticlehq/core's TypeScript source so a CJS
+// preload and the ESM renderer cannot drift apart. Previously hand-copied into six files.
+const {
+  RETICLE_IPC_GLOBAL,
+  RETICLE_CAPTURE_CHANNEL,
+  RETICLE_FULL_PAGE_UNSUPPORTED,
+} = require('@reticlehq/core/desktop-contract');
+
+/**
+ * Renderer-side subscribers, keyed by a token.
+ *
+ * A Map rather than one slot, and a token rather than the callback itself, for two reasons. A single
+ * slot meant a second `connect()` in the same renderer silently STOLE the first one's subscription —
+ * and "unsubscribing" was really "overwrite with a no-op", so an SDK teardown left the app in a
+ * different state than it found it. Tokens rather than function identity because a callback crosses
+ * `contextBridge` as a proxy, so the reference the preload holds is not the one the renderer passes
+ * back and `delete(callback)` would never match.
+ *
+ * Empty until a renderer subscribes, so records before `connect()` are dropped rather than queued —
+ * the SDK only wants activity from the moment it is watching.
+ */
+const sinks = new Map();
+let sinkToken = 0;
+let seq = 0;
+
+function report(record) {
+  for (const sink of sinks.values()) {
+    try {
+      sink(record);
+    } catch {
+      /* a renderer sink is best-effort; it must never break the app's IPC call */
+    }
+  }
+}
+
+/**
+ * Longest payload reported per IPC call, matching the HTTP body cap.
+ *
+ * A desktop app's ENTIRE API surface is IPC. The web side has recorded request/response bodies for a
+ * long time — which is what lets Reticle catch a batch whose 200 hides per-item failures, or a refund
+ * posting a major-unit number into a minor-unit field. On Electron none of that could ever fire,
+ * because this shim reported only channel, ok and duration and dropped the payloads it was already
+ * holding. Every payload-based check was silently web-only on the platform this release is about.
+ */
+const IPC_BODY_MAX = 8192;
+
+/**
+ * Serialize an IPC payload, or report why it could not be.
+ *
+ * Size is computed even when the body is not forwarded, because "a write returned ok and its payload
+ * went unread" is a caveat the verdict layer needs and it cannot infer it from an absent field.
+ */
+function payload(value) {
+  if (value === undefined) return undefined;
+  try {
+    const text = JSON.stringify(value);
+    if (typeof text !== 'string') return undefined;
+    return text.length > IPC_BODY_MAX
+      ? { text: text.slice(0, IPC_BODY_MAX), size: text.length, truncated: true }
+      : { text, size: text.length };
+  } catch {
+    // Circular, or carrying something structured-cloneable but not JSON-able. Not an error — the
+    // call is still reported, just without a readable payload.
+    return undefined;
+  }
+}
+
+/** Wrap one invoke-style function so each call reports a start and an end. */
+function observe(original, channelFromArg, name) {
+  return function reticleObservedIpc(...args) {
+    const id = `i${String(++seq)}`;
+    const channel = channelFromArg && typeof args[0] === 'string' ? args[0] : name;
+    const startedAt = Date.now();
+    report({ phase: 'start', id, channel });
+    // The arguments after the channel name ARE the request payload.
+    const request = payload(channelFromArg ? args.slice(1) : args);
+    const finish = (ok, error, value) => {
+      const response = payload(value);
+      report({
+        phase: 'end',
+        id,
+        channel,
+        ok,
+        durationMs: Date.now() - startedAt,
+        ...(error === undefined ? {} : { error }),
+        ...(request === undefined ? {} : { requestBody: request.text, requestSize: request.size }),
+        ...(response === undefined
+          ? {}
+          : {
+              responseBody: response.text,
+              responseSize: response.size,
+              ...(response.truncated === true ? { responseBodyTruncated: true } : {}),
+            }),
+      });
+    };
+    let result;
+    try {
+      result = original.apply(this, args);
+    } catch (err) {
+      finish(false, String(err && err.message ? err.message : err));
+      throw err;
+    }
+    if (result === null || typeof result !== 'object' || typeof result.then !== 'function') {
+      finish(true, undefined, result);
+      return result;
+    }
+    return result.then(
+      (value) => {
+        finish(true, undefined, value);
+        return value;
+      },
+      (err) => {
+        finish(false, String(err && err.message ? err.message : err));
+        throw err;
+      },
+    );
+  };
+}
+
+/**
+ * Wrap a ONE-WAY send. It has no verdict to wait for, so it is recorded as DISPATCHED and never as
+ * succeeded: `ok` and `status` are omitted entirely rather than defaulted to true/200.
+ *
+ * That distinction is the whole point. `ipcRenderer.send` hands the message to the main process and
+ * returns; whether the handler ran, threw, or does not exist is information the renderer never gets.
+ * Recording it as a 200 would manufacture a verdict nobody produced — so `reticle_network { ok }`
+ * matches it in NEITHER direction, and the record carries `oneWay: true` so a reader can see why
+ * there is no outcome rather than assume one.
+ *
+ * Only a throw at the call site (a closed port, a serialization failure) is a real failure the
+ * renderer can observe, and that one IS reported as `ok: false`.
+ */
+function observeOneWay(original, name) {
+  return function reticleObservedOneWayIpc(...args) {
+    const id = `i${String(++seq)}`;
+    const channel = typeof args[0] === 'string' ? args[0] : name;
+    try {
+      const result = original.apply(this, args);
+      report({ phase: 'end', id, channel, oneWay: true, durationMs: 0 });
+      return result;
+    } catch (err) {
+      report({
+        phase: 'end',
+        id,
+        channel,
+        oneWay: true,
+        ok: false,
+        durationMs: 0,
+        error: String(err && err.message ? err.message : err),
+      });
+      throw err;
+    }
+  };
+}
+
+// Patch the three entry points an app's IPC actually leaves through, before its own
+// `exposeInMainWorld` captures the references.
+//
+// `invoke` alone is NOT the whole surface — that claim used to be in this comment and it was wrong.
+// A `send` + `on('reply')` pair is a mainstream Electron pattern, and an app built that way had
+// EVERY backend call invisible while `coverage` still read full. `sendSync` genuinely returns its
+// result, so it is observed like an invoke; `send` cannot be, so it is recorded as one-way.
+//
+// `postMessage` (MessagePort transfer) is deliberately not wrapped: the ports outlive the call, so a
+// single record could not describe it honestly. An app using it should say so in its own signals.
+const originalInvoke = ipcRenderer.invoke.bind(ipcRenderer);
+ipcRenderer.invoke = observe(originalInvoke, true, 'invoke');
+if (typeof ipcRenderer.sendSync === 'function') {
+  ipcRenderer.sendSync = observe(ipcRenderer.sendSync.bind(ipcRenderer), true, 'sendSync');
+}
+if (typeof ipcRenderer.send === 'function') {
+  ipcRenderer.send = observeOneWay(ipcRenderer.send.bind(ipcRenderer), 'send');
+}
+
+contextBridge.exposeInMainWorld(RETICLE_IPC_GLOBAL, {
+  /** Start receiving records. Returns a token to hand back to `unsubscribe`. */
+  subscribe(callback) {
+    if (typeof callback !== 'function') return -1;
+    sinkToken += 1;
+    sinks.set(sinkToken, callback);
+    return sinkToken;
+  },
+  /**
+   * Stop receiving records. A real removal, so an SDK teardown leaves the app as it found it.
+   *
+   * The `ipcRenderer.invoke` patch itself is deliberately NOT reverted: it is a pass-through with no
+   * observable effect once no sinks remain, and un-patching it mid-flight would strand any call that
+   * had already started inside the wrapper.
+   */
+  unsubscribe(token) {
+    sinks.delete(token);
+  },
+  /**
+   * Screenshot this window. Resolves to a base64 PNG, or null when the app did not install the
+   * main-process helper (`@reticlehq/electron/main`) — there is no handler to answer, and a
+   * missing screenshot must read as missing, never as a blank image.
+   *
+   * Uses the ORIGINAL invoke: this is Reticle's own plumbing, and recording it as an app IPC call
+   * would put `ipc://__reticle:capture` in the agent's own network evidence.
+   */
+  capture(fullPage) {
+    return originalInvoke(RETICLE_CAPTURE_CHANNEL, { fullPage: fullPage === true }).catch(
+      (error) => {
+        // A missing handler must stay `null` ("this app installed no capture helper"). An explicit
+        // refusal is different information and has to reach the tool, or `fullPage` would silently
+        // come back as a viewport image the caller believes is the whole page.
+        const message = String((error && error.message) || error);
+        if (message.includes(RETICLE_FULL_PAGE_UNSUPPORTED)) {
+          throw new Error(RETICLE_FULL_PAGE_UNSUPPORTED);
+        }
+        return null;
+      },
+    );
+  },
+});