# Eigen Desktop

An Electron wrapper for the web applications in this monorepo. Powered by **electron-vite** for development and **electron-builder** for production packaging.

---

## Quick Start

```bash
# From the monorepo root

# Install dependencies
pnpm install

# Development (starts both the web dev server and Electron)
pnpm dev:desktop

# Build for production
pnpm build:desktop

# Package for distribution
pnpm package:desktop
```

---

## How It Works

| Environment | Behavior |
|---|---|
| **Development** | Electron loads the Vite dev server (`http://localhost:5173`). Hot reload works normally. |
| **Production** | Electron registers a custom `app://` protocol that serves the static build output of the target web app. SPA client-side routing is fully supported via an `index.html` fallback. |

---

## Project Structure

```
apps/desktop/
├── docs/                    # Documentation
│   ├── CONFIGURATION.md     # Target app, routing, HashRouter fallback
│   ├── AUTO_UPDATER.md      # Release process, CI/CD, code signing
│   └── IPC_ARCHITECTURE.md  # Security model, adding new features
├── scripts/
│   └── copy-web-dist.ts     # Prebuild: copies web app build → web-dist/
├── src/
│   ├── main/
│   │   └── index.ts         # Main process: protocol, CORS, IPC, updater
│   ├── preload/
│   │   └── index.ts         # Secure contextBridge API
│   └── renderer/
│       └── index.html       # Renderer shell (CSP reference)
├── .env                     # Target app configuration
├── electron-builder.yml     # Packaging & auto-update config
├── electron-vite.config.ts  # Build config (main, preload, renderer)
├── package.json
├── tsconfig.json
├── tsconfig.main.json
├── tsconfig.preload.json
└── tsconfig.renderer.json
```

---

## Scripts

| Script | Description |
|---|---|
| `pnpm dev` | Start electron-vite dev server |
| `pnpm build` | Compile TypeScript → `out/` |
| `pnpm prebuild` | Copy target web app's `dist/` → `web-dist/` |
| `pnpm package` | Build + package for current platform |
| `pnpm package:win` | Package for Windows (NSIS) |
| `pnpm package:mac` | Package for macOS (DMG + ZIP) |
| `pnpm package:linux` | Package for Linux (AppImage) |

---

## Configuration

The target web app is configured via `.env`:

```env
DESKTOP_TARGET_APP=web
DESKTOP_DEV_SERVER_URL=http://localhost:5173
```

See [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for details on switching target apps and routing fallbacks.

---

## Features

### Custom `app://` Protocol
Serves the web app's static build with SPA routing support. Includes path traversal protection and CSP header injection.

### Hardware Printing
The React app can list printers and trigger print jobs via `window.electronAPI.getPrinters()` and `window.electronAPI.print()`.

### Auto-Update
Background update checks via GitHub Releases with download progress forwarding to the React UI. See [docs/AUTO_UPDATER.md](docs/AUTO_UPDATER.md).

### CORS Bypass
API requests from the `app://` origin are transparently handled by stripping non-standard Origin headers and injecting CORS response headers.

---

## Security

- `contextIsolation: true` — preload runs in an isolated context
- `nodeIntegration: false` — no Node.js APIs in the renderer
- `sandbox: true` — Chromium sandbox enabled
- `webSecurity: true` — same-origin policy enforced
- Path traversal protection in the custom protocol handler
- CSP headers injected on all HTML responses

See [docs/IPC_ARCHITECTURE.md](docs/IPC_ARCHITECTURE.md) for the full security model and how to safely extend the app.

---

## Documentation

| Document | Contents |
|---|---|
| [CONFIGURATION.md](docs/CONFIGURATION.md) | Target app switching, `app://` protocol internals, HashRouter fallback procedure |
| [AUTO_UPDATER.md](docs/AUTO_UPDATER.md) | Release workflow, CI/CD variables, S3/generic provider switching, code signing |
| [IPC_ARCHITECTURE.md](docs/IPC_ARCHITECTURE.md) | Security model, Three-Step Bridge pattern, existing IPC channels, extension guide |