[feat] Full Electron Support with Transparent Relay & Secure IPC Bridge (#19)

* init: electron demo

* feat(kkrpc): add Electron support with transparent relay

Add complete Electron integration for kkrpc with:

- Electron IPC adapters (main ↔ renderer) via kkrpc/electron-ipc
- Utility process adapters (main ↔ worker) via kkrpc/electron
- Event-driven createRelay() for transparent message forwarding
- Full electron-demo with 3 communication patterns

Key changes:
- New adapters: ElectronIpcMainIO, ElectronIpcRendererIO, ElectronUtilityProcessIO, ElectronUtilityProcessChildIO
- Extended IoInterface with optional onMessage callback for event-driven adapters
- Rewrote relay.ts to use event callbacks instead of blocking while loops
- Added 47 new files including documentation, examples, and implementation plans

The relay architecture enables main process to act as transparent byte pipe
without parsing JSON or knowing API details. Renderer can now call external
Node.js processes directly through createRelay(ipcIO, nodeIO).

* feat(electron)!: refactor to dependency injection pattern for version-agnostic Electron support

Refactored `createSecureIpcBridge` to use dependency injection instead of direct Electron imports. This removes Electron as a peer dependency, making kkrpc compatible with any Electron version without version conflicts.

BREAKING CHANGE: `createSecureIpcBridge` API changed to require `ipcRenderer` parameter

Before:
createSecureIpcBridge({ channelPrefix: "kkrpc-" })

After:
import { ipcRenderer } from "electron"
createSecureIpcBridge({ ipcRenderer, channelPrefix: "kkrpc-" })

- Added `IpcRendererInterface` type for minimal Electron API surface
- Updated all documentation and examples with new usage pattern
- Exported `createSecureIpcBridge` from `kkrpc/electron-ipc` entry point
- Fixed TypeScript errors in http.test.ts and nats.ts adapter

* ci: optimize test execution to run only kkrpc package tests

Filter test execution to run only kkrpc package tests instead of all packages,
reducing CI build time and avoiding unnecessary test runs for unaffected packages.

* fix(node-io): resolve pending read on stream error to prevent hanging RPC channel

Author: HuakunShen

.github/workflows/ci.yml

@@ -38,7 +38,7 @@ jobs:
           # pnpm --filter kkrpc exec playwright install
           pnpx playwright install --with-deps
           pnpm build
-          pnpm test
+          pnpm test -F kkrpc
       - name: Stop test services
         if: always()
         run: |

.journal/2026-02-02.md

@@ -0,0 +1,111 @@
+# Journal Entry - 2026-02-02
+
+## 11:20 - Secure IPC Bridge Architecture Decision
+
+### Core Decision/Topic
+
+Refactored `createSecureIpcBridge` to use dependency injection pattern instead of directly importing from "electron" package. This eliminates the need for kkrpc to depend on Electron as a peer dependency.
+
+### Options Considered
+
+1. **Option A: Keep Electron as peerDependency (>=20.0.0)**
+
+   - Pros: Simple, works out of the box
+   - Cons: Forces non-Electron users to install Electron; version conflicts with newer/older Electron versions
+
+2. **Option B: Use optional peerDependency**
+
+   - Pros: Non-Electron users won't be forced to install
+   - Cons: Still version-locked; future Electron API changes could break kkrpc
+
+3. **Option C: Dependency Injection Pattern (Chosen)**
+   - Pros: Version agnostic, works with any Electron version, zero dependency overhead
+   - Cons: Slightly more verbose API (user must import electron themselves)
+
+### Final Decision & Rationale
+
+**Chosen: Option C - Dependency Injection**
+
+The key insight is that kkrpc only needs a minimal interface from Electron's `ipcRenderer`:
+
+```ts
+interface IpcRendererInterface {
+	send(channel: string, ...args: unknown[]): void
+	on(channel: string, listener: (event: unknown, ...args: unknown[]) => void): void
+	off(channel: string, listener: (event: unknown, ...args: unknown[]) => void): void
+}
+```
+
+By accepting `ipcRenderer` as a parameter instead of importing it:
+
+- Users control their own Electron version
+- No peer dependency warnings for non-Electron users
+- Future-proof against Electron API changes
+- Follows the principle of "composition over inheritance"
+
+### Key Changes Made
+
+| File                                         | Change                                                                             |
+| -------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `src/adapters/electron-ipc-preload.ts`       | Refactored to accept `ipcRenderer` as parameter; added `IpcRendererInterface` type |
+| `package.json`                               | Removed `electron` from `peerDependencies` entirely                                |
+| `examples/electron-demo/electron/preload.ts` | Updated to new API: `createSecureIpcBridge({ ipcRenderer, channelPrefix })`        |
+| `docs/examples/electron.md`                  | Updated documentation with new usage pattern                                       |
+| `README.md`                                  | Updated Electron preload examples                                                  |
+
+### API Change
+
+**Before:**
+
+```ts
+import { createSecureIpcBridge } from "kkrpc/electron-ipc"
+
+createSecureIpcBridge({ channelPrefix: "kkrpc-" })
+```
+
+**After:**
+
+```ts
+import { contextBridge, ipcRenderer } from "electron"
+import { createSecureIpcBridge } from "kkrpc/electron-ipc"
+
+const securedIpcRenderer = createSecureIpcBridge({
+	ipcRenderer,
+	channelPrefix: "kkrpc-"
+})
+
+contextBridge.exposeInMainWorld("electron", {
+	ipcRenderer: securedIpcRenderer
+})
+```
+
+### Future Considerations
+
+- The `IpcRendererInterface` should remain stable even if Electron changes their API
+- If Electron makes breaking changes to ipcRenderer, users can adapt without waiting for kkrpc updates
+- Consider documenting this pattern for other framework integrations (e.g., if we add Tauri-specific helpers)
+
+---
+
+## 11:45 - TypeScript Error Fixes
+
+### Core Decision/Topic
+
+Fixed 3 TypeScript errors that appeared during `bun tsc --noEmit`:
+
+1. `__tests__/http.test.ts:8` - `Server` generic requires type argument
+2. `src/adapters/nats.ts:67` - Invalid option `rewait` (should be `reconnectTimeWait`)
+3. `src/adapters/electron-ipc-preload.ts:1` - Cannot find module 'electron'
+
+### Key Changes
+
+| File                                   | Fix                                                           |
+| -------------------------------------- | ------------------------------------------------------------- |
+| `__tests__/http.test.ts`               | Changed `let server: Server` to `let server: Server<unknown>` |
+| `src/adapters/nats.ts`                 | Fixed typo: `rewait: 1000` → `reconnectTimeWait: 1000`        |
+| `src/adapters/electron-ipc-preload.ts` | Resolved by removing electron import (see above refactor)     |
+
+### Verification
+
+- ✅ `bun tsc --noEmit` passes
+- ✅ 119 tests pass

.mcp.json

@@ -0,0 +1,9 @@
+{
+	"active_plan": "/Users/hk/Dev/kkrpc/.sisyphus/plans/implement-event-driven-relay.md",
+	"started_at": "2026-02-02T02:09:46.201Z",
+	"session_ids": ["ses_3eda811e5ffecNE7cB2t1fexby"],
+	"plan_name": "implement-event-driven-relay",
+	"status": "in_progress",
+	"tasks_completed": 3,
+	"tasks_total": 6
+}

.sisyphus/boulder.json

@@ -0,0 +1,220 @@
+# Better Relay Design - Event-Driven Approach
+
+## Problems with Current Implementation
+
+### 1. Proxy is Too Ugly
+
+```typescript
+// Current - user has to write this:
+stdio: new Proxy({} as StdioWorkerAPI, {
+	get: (_, method: string) => {
+		return (...args: any[]) => {
+			return (stdioAPI as any)[method](...args)
+		}
+	}
+})
+```
+
+**Bad**: Users shouldn't write this complexity.
+
+### 2. While Loop is Blocking
+
+```typescript
+// Current relay - brute force polling
+while (!destroyed) {
+	const msg = await a.read() // Blocks forever
+	await b.write(msg)
+}
+```
+
+**Bad**: Wastes CPU, not event-driven.
+
+---
+
+## Better Solution: Event-Driven IoInterface
+
+### Core Insight
+
+The essence of relay is: **connect two adapters' read/write streams**.
+
+When adapter A receives a message → write to adapter B
+When adapter B receives a message → write to adapter A
+
+### Design: Add onMessage Hook to IoInterface
+
+```typescript
+// Extend IoInterface with optional callback
+export interface IoInterface {
+	name: string
+	read(): Promise<string | IoMessage | null>
+	write(message: string | IoMessage): Promise<void>
+
+	// NEW: Event-driven message handling
+	onMessage?: (message: string | IoMessage) => void | Promise<void>
+
+	capabilities?: IoCapabilities
+	destroy?(): void
+	signalDestroy?(): void
+}
+```
+
+### Relay Implementation (Clean!)
+
+```typescript
+// packages/kkrpc/src/relay.ts
+export function createRelay(a: IoInterface, b: IoInterface): Relay {
+	// When A receives message → forward to B
+	a.onMessage = async (msg) => {
+		await b.write(msg)
+	}
+
+	// When B receives message → forward to A
+	b.onMessage = async (msg) => {
+		await a.write(msg)
+	}
+
+	return {
+		destroy: () => {
+			a.onMessage = undefined
+			b.onMessage = undefined
+			a.destroy?.()
+			b.destroy?.()
+		}
+	}
+}
+```
+
+### User API (Super Clean!)
+
+```typescript
+// main.ts - no Proxy, no method enumeration!
+import { createRelay } from "kkrpc"
+
+// Just pipe the adapters together
+const relay = createRelay(
+	new ElectronIpcMainIO(ipcMain, win.webContents), // From Renderer
+	new NodeIo(stdioProcess.stdout!, stdioProcess.stdin!) // To Worker
+)
+
+// That's it! Main doesn't know any API methods.
+// Messages flow transparently: Renderer ↔ Worker
+```
+
+---
+
+## Adapter Modifications Needed
+
+Each adapter needs to call `onMessage` when data arrives:
+
+### Example: NodeIo
+
+```typescript
+export class NodeIo implements IoInterface {
+	onMessage?: (msg: string) => void | Promise<void>
+
+	constructor(stdout: ReadableStream, stdin: WritableStream) {
+		// ... existing setup ...
+
+		// NEW: Use event-driven approach instead of blocking read()
+		this.stdout.on("data", (chunk: Buffer) => {
+			// Buffer and process lines (existing logic)
+			const messages = this.bufferString(chunk.toString())
+			for (const msg of messages) {
+				// If onMessage is set, use it (event-driven)
+				// Otherwise fall back to queue for read() compatibility
+				if (this.onMessage) {
+					this.onMessage(msg)
+				} else {
+					this.messageQueue.push(msg)
+					this.resolveRead?.(msg)
+				}
+			}
+		})
+	}
+
+	// read() now returns queued messages or waits
+	async read(): Promise<string | null> {
+		if (this.messageQueue.length > 0) {
+			return this.messageQueue.shift()!
+		}
+		// If onMessage is set, read() shouldn't be called
+		// But we keep it for backward compatibility
+		return new Promise((resolve) => {
+			this.resolveRead = resolve
+		})
+	}
+}
+```
+
+### Example: ElectronIpcMainIO
+
+```typescript
+export class ElectronIpcMainIO implements IoInterface {
+	onMessage?: (msg: string | IoMessage) => void | Promise<void>
+
+	constructor(ipcMain: IpcMain, webContents: WebContents) {
+		// ... existing setup ...
+
+		ipcMain.on(this.channelName, (_event, message) => {
+			if (this.onMessage) {
+				// Event-driven mode
+				this.onMessage(message)
+			} else {
+				// Traditional queue mode
+				this.messageQueue.push(message)
+				this.resolveRead?.(message)
+			}
+		})
+	}
+}
+```
+
+---
+
+## Benefits
+
+| Aspect              | Before (Proxy)           | After (Event-Driven Relay)   |
+| ------------------- | ------------------------ | ---------------------------- |
+| **User Code**       | 8 lines of ugly Proxy    | 1 line: `createRelay(a, b)`  |
+| **Performance**     | While loop polling       | Event-driven, zero CPU waste |
+| **API Knowledge**   | Main still knows methods | Main knows **nothing**       |
+| **Maintainability** | Add method → update Main | Add method → no change       |
+| **Type Safety**     | Any types                | Fully typed via endpoints    |
+
+---
+
+## Migration Strategy
+
+1. **Add `onMessage` to IoInterface** (backward compatible - optional)
+2. **Update adapters** to support event-driven mode
+3. **Implement new relay** using `onMessage`
+4. **Deprecate old approaches**
+
+---
+
+## Advanced: Router Pattern
+
+With this design, we can also build routers easily:
+
+```typescript
+// Route messages based on path prefix
+const router = createRouter({
+	"math.": mathWorkerIO,
+	"db.": dbWorkerIO,
+	"fs.": fsWorkerIO
+})
+
+// "math.add" → math worker
+// "db.query" → db worker
+```
+
+---
+
+## Summary
+
+**The key insight**: Instead of Main creating RPCChannel and proxying methods, just **pipe the raw adapters together**.
+
+- **Before**: Renderer → Main RPC → Main proxies → Worker RPC → Worker
+- **After**: Renderer → Relay → Worker (Main just passes bytes!)
+
+This is the true "transparent relay" you envisioned!