@reticlehq/electron 2.13.1 → 3.1.0

package/LICENSE

@@ -1,33 +1,202 @@
-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
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Reticle Labs
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/main.cjs

@@ -10,9 +10,9 @@
  *
  * 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.
+ * any screen-recording permission. NOT a screen-region capture, which photographs whatever is on top
+ * and 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.
  */
@@ -58,7 +58,7 @@ function usableContents(sender) {
  *
  * 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, and the daemon
+ * forever. Sweeping Reticle's own prefix on each capture bounds that to one file at a time, and the daemon
  * removes this empty private directory in its existing shutdown path. Best-effort — a failed sweep
  * must never fail a capture.
  *
@@ -129,9 +129,8 @@ function installReticleCapture(win) {
       // 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);
-      // Named, not null. Every no-image answer used to be the same bare null, so a dead window, an
-      // uncomposited one and a thrown error were one silence — the tool reported `saved:false` with
-      // no bytes and no reason, which is unreadable in CI and useless to a user.
+      // Named, not null. A bare null makes a dead window, an uncomposited one and a thrown error one
+      // silence — `saved:false` with no bytes and no reason, unreadable in CI and useless to a user.
       if (contents === null) throw new Error('no usable webContents to capture');
       try {
         const image = await contents.capturePage();
@@ -156,7 +155,7 @@ function installReticleCapture(win) {
         // getting a symlink here, so this is the second lock on the same door — and the one that
         // still holds if a later change moves this write back out into the shared temp dir. The
         // sequence only ever climbs within a fresh per-process directory, so it never collides
-        // with a capture of our own.
+        // with a capture of Reticle's own.
         await writeFile(file, image.toPNG(), { flag: 'wx' });
         await sweepOldCaptures(dir, file);
         return file;

package/main.d.cts

@@ -0,0 +1,33 @@
+/**
+ * Types for the main-process entry, hand-written because the source is hand-written CJS.
+ *
+ * Without them every TypeScript Electron app — which is most of them — got `any` from
+ * `require('@reticlehq/electron/main')`, so a wrong argument to the one function this package
+ * exists for was a runtime surprise rather than a compile error.
+ */
+
+/**
+ * `object`, and deliberately not a structural shape.
+ *
+ * The obvious version declares the one member this adapter touches — `on?(event, listener)` — and a
+ * real `BrowserWindow` does not satisfy it: Electron types `on` as a long list of overloads keyed on
+ * literal event names, none of which is assignable to one general signature. The first draft of this
+ * file typed it that way and the electron-vite fixture in `apps/` refused to compile, which is what
+ * that fixture is for.
+ *
+ * Naming Electron's own type instead would make a type-only import a real dependency for a package
+ * that declares Electron as a PEER, so an app on a different Electron major would fail to compile
+ * against types it never asked for. `object` accepts every window and still rejects the argument
+ * mistakes worth catching — a string, a number, a forgotten `.webContents`.
+ */
+export type ReticleCapturableWindow = object;
+
+/**
+ * Make this window screenshottable from the daemon.
+ *
+ * Registers the capture IPC handler once per process and remembers the window, so a capture still
+ * resolves when the requesting webContents has gone away. A null or undefined window is ignored
+ * rather than throwing — a renderer that never opened is not an error worth crashing a main process
+ * over.
+ */
+export function installReticleCapture(win: ReticleCapturableWindow | null | undefined): void;

package/package.json

@@ -1,14 +1,24 @@
 {
   "name": "@reticlehq/electron",
-  "version": "2.13.1",
+  "version": "3.1.0",
   "description": "Reticle adapter for Electron: makes main-process IPC observable and the window screenshottable, from the two places the renderer cannot reach.",
+  "engines": {
+    "node": ">=20.0.0"
+  },
   "type": "module",
   "exports": {
-    "./preload": "./preload.cjs",
-    "./main": "./main.cjs"
+    "./preload": {
+      "types": "./preload.d.cts",
+      "default": "./preload.cjs"
+    },
+    "./main": {
+      "types": "./main.d.cts",
+      "default": "./main.cjs"
+    },
+    "./package.json": "./package.json"
   },
   "dependencies": {
-    "@reticlehq/core": "2.13.1"
+    "@reticlehq/core": "3.1.0"
   },
   "peerDependencies": {
     "electron": ">=22"
@@ -18,16 +28,21 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/reticlehq/reticle.git",
-    "directory": "packages/electron"
+    "directory": "adapters/realm/electron"
   },
   "homepage": "https://github.com/reticlehq/reticle#readme",
   "bugs": "https://github.com/reticlehq/reticle/issues",
   "files": [
     "preload.cjs",
+    "preload.d.cts",
     "main.cjs",
+    "main.d.cts",
     "README.md",
     "NOTICE"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
   "keywords": [
     "electron",
     "reticle",

package/preload.cjs

@@ -22,7 +22,7 @@
  */
 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.
+// preload and the ESM renderer cannot drift apart.
 const {
   RETICLE_IPC_GLOBAL,
   RETICLE_CAPTURE_CHANNEL,
@@ -32,12 +32,10 @@ const {
 /**
  * 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.
+ * A Map rather than one slot: a single slot lets a second `connect()` in the same renderer STEAL the
+ * first one's subscription, and "unsubscribe" becomes "overwrite with a no-op". 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)` never matches.
  *
  * Empty until a renderer subscribes. What happens to records made before that is `backlog`, below.
  */
@@ -48,13 +46,12 @@ let seq = 0;
 /**
  * IPC that happened before the SDK was watching, held for the first subscriber.
  *
- * This used to be dropped, on the reasoning that the SDK only wants activity from the moment it is
- * watching. That reasoning is a web reflex and it is wrong here. A desktop app loads its data over
- * IPC on mount, and `connect()` is injected and does asynchronous work, so the app's FIRST calls —
- * the ones that populate the entire screen — routinely land before any sink exists. Dropping them
- * does not produce a gap a reader can see: it produces a network view that is empty and looks clean,
- * which is the failure this project treats as the worst kind. An agent reads it as "the app made no
- * backend calls" and reports so.
+ * Held rather than dropped. "The SDK only wants activity from the moment it is watching" is a web
+ * reflex and wrong here: a desktop app loads its data over IPC on mount, and `connect()` is injected
+ * and does asynchronous work, so the app's FIRST calls — the ones that populate the entire screen —
+ * routinely land before any sink exists. Dropping them produces no gap a reader can see, just a
+ * network view that is empty and looks clean, which an agent reads as "the app made no backend
+ * calls".
  *
  * Bounded, because an app running for hours with no SDK attached must not grow a queue, and replayed
  * to the FIRST subscriber only: a second `connect()` in the same renderer is not entitled to history
@@ -81,11 +78,10 @@ function report(record) {
 /**
  * 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.
+ * A desktop app's ENTIRE API surface is IPC, so the payloads are what let Reticle catch a batch whose
+ * 200 hides per-item failures, or a write that posts the wrong units. Reporting only channel, ok and
+ * duration would drop payloads this shim is already holding, and make every payload-based check
+ * silently web-only.
  */
 const IPC_BODY_MAX = 8192;
 
@@ -201,10 +197,10 @@ function observeOneWay(original, name) {
 // 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.
+// `invoke` alone is NOT the whole surface. A `send` + `on('reply')` pair is a mainstream Electron
+// pattern, and an app built that way has EVERY backend call invisible while `coverage` reads 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.

package/preload.d.cts

@@ -0,0 +1,18 @@
+/**
+ * Types for the preload entry, which is a SIDE-EFFECT module and exports nothing.
+ *
+ * `arethetypeswrong` failed this package in CI with "Import resolved to JavaScript files, but no
+ * type declarations were found" on `@reticlehq/electron/preload`, across node16-CJS, node16-ESM and
+ * bundler. `./main` already had `main.d.cts`; this entry never did, so a TypeScript Electron app —
+ * which is most of them — got an untyped resolution for one of the package's two entries.
+ *
+ * The declaration is empty because the runtime surface is empty. `preload.cjs` runs
+ * `contextBridge.exposeInMainWorld` and returns nothing: it is named in a `webPreferences.preload`
+ * path, or required for its effect, and never destructured. Declaring a shape here would be
+ * inventing an API to satisfy a checker, which is worse than the untyped resolution it replaces.
+ *
+ * What the preload actually installs is on `window`, in the RENDERER, under the global the contract
+ * names. That is a different type surface and it belongs to whatever reads it, not here.
+ */
+
+export {};