electron-state-sync 1.1.0

package/CLAUDE.md

@@ -0,0 +1,254 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a lightweight Electron state synchronization library that enables seamless data sharing between main and renderer processes. It supports React, Vue, Svelte, and SolidJS with automatic multi-window sync.
+
+**Key characteristics:**
+- Main process bundle: ~6.3KB, renderer bundles: 1.5-2.2KB per framework
+- Three-tier architecture: main process → preload script → renderer layer
+- IPC-based communication using typed channels
+- Write permission control and validation from main process
+- Automatic multi-window synchronization
+
+## Development Commands
+
+```bash
+# Build all artifacts (main + preload + renderer integrations)
+bun run build
+
+# Build individual parts
+bun run build:main      # Main process (src/main.ts)
+bun run build:preload   # Preload script (src/preload.ts)
+bun run build:renderer  # All framework integrations
+
+# Linting and formatting
+bun run lint           # Check code with oxlint
+bun run lint:fix       # Auto-fix linting issues
+bun run format         # Format code with oxfmt
+bun run format:check   # Check formatting
+bun run check          # Run both lint and format checks
+
+# Testing
+bun run test           # Run unit tests (test/ directory)
+bun run coverage       # Run unit tests with coverage
+bun run test:e2e       # Run E2E tests (requires build first)
+
+# Development
+bun run dev            # Run src/index.ts directly
+```
+
+**Important:** E2E tests require the library to be built first (`bun run build`). Git hooks enforce this via lefthook (pre-push hook runs tests and build).
+
+## Architecture
+
+### Three-Tier Structure
+
+**1. Main Process (`src/main.ts`)**
+- Central state management hub with IPC handlers
+- Controls write permissions via `allowRendererSet` flag
+- Validates renderer writes via `resolveRendererValue` function
+- Broadcasts updates to all subscribed windows
+- Uses `WebContents` tracking for multi-window sync
+
+**2. Preload Script (`src/preload.ts`)**
+- Security bridge using `contextBridge.exposeInMainWorld`
+- Exposes `SyncStateBridge` interface to renderer
+- Handles IPC communication with type safety
+- Entry point for `electron-state-sync/preload` export
+
+**3. Renderer Layer (`src/renderer/`)**
+- **Core**: `bridge.ts` resolves bridge instances, `index.ts` provides global config
+- **Framework integrations**: Each framework has its own adapter
+  - `react.ts` - React hook with tuple return `[value, setter, isSynced]`
+  - `vue.ts` - Vue composable returning Ref with `isSynced` property
+  - `svelte.ts` - Svelte store with `isSynced` readable store
+  - `solid.ts` - Solid hook with tuple return similar to React
+
+### IPC Channel System (`src/channels.ts`)
+
+Channel naming pattern: `${baseChannel}:${name}:action`
+
+Five channels per state:
+- `get` - Renderer fetches current value
+- `set` - Renderer updates value (if allowed)
+- `subscribe` - Window subscribes to updates
+- `unsubscribe` - Window unsubscribes
+- `update` - Main broadcasts changes to subscribers
+
+**Example:** For `baseChannel="state"` and `name="counter"`:
+- `state:counter:get`
+- `state:counter:set`
+- `state:counter:subscribe`
+- `state:counter:unsubscribe`
+- `state:counter:update`
+
+### Data Flow
+
+1. **Initialization**: Main creates state with `state({ name, initialValue })`
+2. **Subscription**: Renderer calls `bridge.subscribe()` via IPC
+3. **Initial Sync**: Renderer fetches current value via `bridge.get()`
+4. **Updates**:
+   - Main process calls `handle.set()` → broadcasts to all subscribers
+   - Renderer calls `bridge.set()` → validated by main → broadcast if valid
+5. **Multi-window**: All subscribed windows receive updates automatically
+
+### State Management Pattern
+
+Each framework integration follows this pattern:
+1. Create local reactive state with `initialValue` (placeholder)
+2. Subscribe to main process updates in effect/hook
+3. Fetch initial value from main process on mount
+4. Local changes sync to main (if allowed)
+5. Remote updates from main override local state
+6. Track sync completion via `isSynced` flag
+
+**Critical detail:** To prevent infinite loops when renderer writes are allowed:
+- Frameworks track when applying remote updates
+- Skip syncing back to main during remote update application
+- React/Solid: Use refs/flags to track update source
+- Vue: Compare resolved values before syncing
+- Svelte: Track update state in callback closure
+
+## Build System
+
+**Tool:** `tsdown` (TypeScript-to-JavaScript compiler)
+
+Three separate build configurations:
+- `tsdown.main.config.ts` - Builds main process entry
+- `tsdown.preload.config.ts` - Builds preload script
+- `tsdown.config.ts` - Builds all renderer framework integrations
+
+**Output format:** Dual ESM + CJS with TypeScript definitions
+
+**Package exports:** Each layer has its own export path:
+- `electron-state-sync/main` → `dist/main.{js,cjs,d.ts}`
+- `electron-state-sync/preload` → `dist/preload.{js,cjs,d.ts}`
+- `electron-state-sync/renderer` → `dist/renderer/index.{js,cjs,d.ts}`
+- `electron-state-sync/react` → `dist/react.{js,cjs,d.ts}`
+- `electron-state-sync/vue` → `dist/vue.{js,cjs,d.ts}`
+- `electron-state-sync/svelte` → `dist/svelte.{js,cjs,d.ts}`
+- `electron-state-sync/solid` → `dist/solid.{js,cjs,d.ts}`
+
+## Testing
+
+**Unit Tests (`test/`):**
+- `channels.test.ts` - IPC channel generation logic
+- `validation.test.ts` - Serialization validation
+- `index.test.ts` - SyncStateError class
+- `setup.ts` - Mocks Electron modules for unit tests
+- `mocks.ts` - Test utilities
+
+**E2E Tests (`e2e/`):**
+- Uses Playwright with real Electron app
+- `sync-state.spec.ts` - Tests all frameworks (React, Vue, Svelte, Solid)
+- `main.mjs` - Electron main process for testing
+- `renderer-*.js` - Framework-specific test renderers
+- `preload.{cjs,mjs}` - Preload scripts for testing
+
+**Key test utilities:**
+- Unit tests mock Electron IPC to avoid needing real Electron
+- E2E tests use `@playwright/test` with `electron` launcher
+- Test framework selection via `--framework=` CLI argument
+- Multi-window testing via `--windows=` argument
+
+## Code Conventions
+
+### Error Handling
+
+Use `SyncStateError` for all library errors:
+```typescript
+throw new SyncStateError("RENDERER_READONLY", message, {
+  stateName: options.name,
+  baseChannel: options.baseChannel ?? "state",
+});
+```
+
+Error codes:
+- `RENDERER_READONLY` - Renderer write blocked by `allowRendererSet: false`
+- `RENDERER_INVALID_VALUE` - Renderer write rejected by `resolveRendererValue`
+
+### Serialization Safety
+
+All state values must be JSON-serializable. The library validates:
+- No functions, Symbols, or BigInt
+- No circular references
+- Arrays and objects are recursively checked
+
+**Validation function** (`src/main.ts`): Used to warn about invalid initial values but doesn't block them (renderer's initialValue is just a placeholder).
+
+### Framework-Specific Notes
+
+**Vue only:**
+- Supports `deep` option for object watching
+- Converts Vue Proxies to raw values before IPC via `toRaw()`
+- Watch flush mode set to `'sync'` for immediate updates
+
+**React/Solid:**
+- Return tuple `[value, setter, isSynced]` from hooks
+- Use `useCallback`/`useMemo` to optimize bridge operations
+
+**Svelte:**
+- Returns custom store with `isSynced` as separate readable store
+- Store cleanup handles unsubscribe automatically
+
+### Global Configuration
+
+Both main and renderer support global config:
+```typescript
+// Main process
+import { initSyncStateMain } from "electron-state-sync/main";
+initSyncStateMain({ baseChannel: "myapp", allowRendererSet: false });
+
+// Renderer process
+import { initSyncState } from "electron-state-sync/react";
+initSyncState({ baseChannel: "myapp" });
+```
+
+Global config is merged with per-state options, where per-state options take precedence.
+
+### Working with Bridges
+
+The `SyncStateBridge` interface enables custom integrations:
+```typescript
+interface SyncStateBridge {
+  get: <StateValue>(options: SyncStateChannelOptions) => Promise<StateValue>;
+  set: <StateValue>(options: SyncStateChannelOptions, value: StateValue) => Promise<void>;
+  subscribe: <StateValue>(options: SyncStateChannelOptions, listener: SyncStateListener<StateValue>) => () => void;
+}
+```
+
+Framework hooks accept optional `bridge` parameter for custom implementations or testing.
+
+## Important Files
+
+- `src/main.ts` - Main process state management and IPC handlers
+- `src/preload.ts` - Preload bridge exposure
+- `src/channels.ts` - IPC channel naming
+- `src/types.ts` - Core type definitions and SyncStateError
+- `src/renderer/bridge.ts` - Bridge resolution logic
+- `src/renderer/index.ts` - Global config for renderer
+- `src/renderer/react.ts` - React integration
+- `src/renderer/vue.ts` - Vue integration
+- `src/renderer/svelte.ts` - Svelte integration
+- `src/renderer/solid.ts` - SolidJS integration
+
+## Linting and Formatting
+
+**Tools:**
+- `oxlint` - Fast linting (used in CI and pre-commit hooks)
+- `oxfmt` - Code formatting
+
+**Common warnings that should be fixed:**
+- `arrow-body-style` - Use concise arrow function bodies when possible
+- `init-declarations` - Initialize variables on declaration
+- `curly` - Use braces for all if statements
+- `prefer-destructuring` - Use object destructuring
+
+**Warnings to ignore (by convention):**
+- `max-statements` - Complex functions are acceptable
+- `max-lines-per-function` - Long functions are acceptable
+
+Pre-commit hooks run `lint` and `format:check` in parallel. Pre-push hooks run `test` and `build`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.