# Electron Main, IPC, and Packaging Guide

## Main Files

- `electron/main.js`: Launch shim. Chooses bundled `dist-electron/main.cjs` in packaged mode when present, otherwise source.
- `electron/main-src.js`: Source of truth for main process behavior.
- `electron/preload.js`: Launch shim for preload.
- `electron/preload-src.js`: Source preload bridge.
- `scripts/build-electron.mjs`: Builds `dist-electron/main.cjs` and `dist-electron/preload.cjs`.

## Main Process Responsibilities

`electron/main-src.js` handles:

- App/window lifecycle.
- Application menu.
- Sentry main process setup.
- Auto-updater and update IPC.
- DevTools configuration.
- Third-party notice window.
- Single-instance locking.
- Tray behavior on minimize.
- Initializing `electron-store`.
- Loading IPC handlers.
- Dynamic ESM imports for ESM-only Electron packages.

## Store Initialization

`electron-store` v11 is ESM-only. The app uses `electron/electron-store.js`:

- `initializeStore()` dynamically imports and creates the store.
- `store` is a proxy that throws if accessed before initialization.

`main-src.js` must call:

```js
await initializeStore();
initializeIpcHandlers();
```

before modules such as analytics, watcher, scanner, audit, or decoder read `store`.

Store defaults include:

- `deviceId`
- `showChangeLog`
- `enableNotifications`
- `filePaths`
- `accepted_ins_co`
- `runWatcherOnStartup`
- `polling`
- `ins_rule_set`

## ESM-Only Package Notes

Current major upgrades made these ESM-only:

- `electron-context-menu`
- `electron-store`
- `electron-is-dev`

The app no longer uses `electron-is-dev`; it uses `!app.isPackaged` in main and `process.defaultApp`/`process.execPath` detection in preload.

Use dynamic import for `electron-context-menu`:

```js
const { default: contextMenu } = await import("electron-context-menu");
```

## Sentry Electron

Current dependency: `@sentry/electron@^7.13.0`.

Main process import:

```js
const Sentry = require("@sentry/electron/main");
```

Renderer import:

```js
import * as Sentry from "@sentry/electron/renderer";
```

Main setup uses:

```js
ipcMode: Sentry.IPCMode.Protocol
```

Keep protocol mode unless deliberately changing Sentry IPC behavior. It avoids the deprecated Electron preload path Sentry can otherwise use.

## DevTools

Current behavior:

- Dev mode: DevTools enabled and auto-open unless `ELECTRON_OPEN_DEVTOOLS=0`.
- Packaged mode: DevTools disabled unless `ELECTRON_ENABLE_DEVTOOLS=1`.
- Packaged auto-open: requires `ELECTRON_OPEN_DEVTOOLS=1`.
- React DevTools extension installation: opt-in with `ELECTRON_INSTALL_REACT_DEVTOOLS=1`.

Chrome DevTools can emit Electron backend console noise such as `Autofill.enable` and `Autofill.setAddresses` protocol errors. That noise is tied to DevTools/extension behavior, not app runtime failure.

## IPC Modules

Shared registration:

- `electron/ipc-main-handler.js`

Imported modules:

- `electron/file-watcher/file-watcher-ipc.js`
- `electron/file-scan/file-scan-ipc.js`
- `electron/audit/audit-ipc.js`

Avoid importing `mainWindow` from `main-src.js` in IPC modules. That caused circular dependency warnings. Use:

```js
const parentWindow = BrowserWindow.fromWebContents(event.sender);
```

for dialog parents, or `BrowserWindow.getAllWindows()[0]` for broadcast-style interactions when necessary.

## Packaging

`package.json` contains electron-builder config.

Important scripts:

- `npm run build:electron`: generates `dist-electron/`.
- `npm run pack`: local unpacked package check with `--publish never` and `electron-builder.pack-check.cjs`.
- `npm run dist`: full build/package using package config.
- `npm run distp`: publishes. Use only when explicitly requested.
- `npm run distnopublish`: full build/package with publishing disabled.

`electron-builder.pack-check.cjs` disables Azure Trusted Signing config for pack checks:

```js
azureSignOptions: null
```

The pack check may still locally sign the unpacked executable with signtool. That is not publishing.

Generated artifacts:

- `dist-electron/`: bundled main/preload, ignored.
- `build/`: renderer production build, ignored.
- `dist/`: electron-builder output, ignored.

Do not manually edit generated artifacts.