add-npm-dependency

# Adding an npm Library This is an Electron app with **three separate build targets** (main, preload, renderer) and a few non-obvious bundling rules. Adding a dependency the wrong way silently breaks CSS, native modules, or the renderer bundle. Follow this guide every time. ## Golden Rule: install the latest, caret-pinned **Always install the newest published version. Never hand-edit `package.json` to set or downgrade a version.** ```bash npm install <pkg>@latest # runtime dependency npm install -D <pkg>@latest # dev / build-only tool (types, bundlers, test libs) ``` - This records a caret range `^x.y.z` — the repo convention (every dep in `package.json` uses `^`). Leave it as a caret range. - `package-lock.json` is committed and gets updated by the install. **Both `package.json` and `package-lock.json` are part of your change** — stage both. - Use **npm only** (the lockfile is `package-lock.json` — not yarn, not pnpm). - Node **v24** is pinned in `.nvmrc`; `engines.node` is `>=18`. Run `nvm use` first if needed. ## Step 1 — Decide which build target consumes the package This determines every gotcha that follows. | Target | Source dirs | How it's built | What's allowed | |--------|-------------|----------------|----------------| | **Renderer** | `src/renderer/**` | Bundled by **esbuild** into one IIFE (`build:renderer`) | Plain JS/TS deps only. **No Node built-ins, no native modules.** | | **Main** | `src/main/**`, `src/shared/**` | `tsc` → CommonJS (`d...