remote-state-sync 1.0.0 → 1.0.2

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 ButterCookies
-
-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.
+MIT License
+
+Copyright (c) 2026 ButterCookies
+
+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.

package/README.md

@@ -1,182 +1,182 @@
-# Remote State Sync
-
-A lightweight, fully type-safe unidirectional remote state synchronization library. Effortlessly sync complex states with fine-grained precision from a Provider (e.g., Server or Electron Main) to a Receiver (e.g., Web Client or Electron Renderer).
-
-English | [中文](./README.zh-CN.md)
-
-## Features
-
-- **Unidirectional Sync**: Safely sync state from A to B with an efficient patch-based diffing system.
-- **Deep Reactivity & Proxies**: Built-in, automatic support for intercepting deep changes across `Object`, `Map`, and `Set` structures.
-- **Batch Patching**: Automatically queues and batches rapid state mutations into singular, optimized events for high performance.
-- **Framework Agnostic Transport**: Bring your own transport layer (WebSocket, Socket.io, Electron IPC, HTTP, etc).
-- **Vue Integration**: Seamlessly connects to Vue's Reactivity system out of the box (`toValue()`, `toRef()`, `toShallowRef()`).
-
-## Installation
-
-```bash
-npm install remote-state-sync
-```
-
-## Examples
-
-### 1. Hono + Socket.IO (Server & Client Web)
-
-**Server (Provider)**
-
-```typescript
-import { SyncProvider } from 'remote-state-sync';
-import { Hono } from 'hono';
-import { Server } from 'socket.io';
-
-const app = new Hono();
-const io = new Server(3000);
-
-const provider = new SyncProvider();
-const usersNs = provider.register('users_space');
-
-// Define a state
-type UserState = {
-  connected: number;
-  history: string[];
-};
-
-// Initialize the state
-const userState = usersNs.sync<UserState>('data', {
-  connected: 0,
-  history: [],
-});
-
-// 1. snapshotGetter implementation via HTTP endpoint
-app.get('/snapshot/:namespace', (c) => {
-  const ns = c.req.param('namespace');
-  return c.json(provider.getStateSnapshot(ns));
-});
-
-io.on('connection', (socket) => {
-  // Mutating deeply tracks changes and queues patches automatically
-  userState.set((state) => void state.connected++);
-
-  socket.on('disconnect', () => {
-    userState.set((state) => void state.connected--);
-  });
-});
-
-// 2. Broadcast patches triggered by deeper modifications over WebSocket
-provider.bus.on('update', (namespace, patches) => {
-  io.emit('state-update', namespace, patches);
-});
-```
-
-**Client (Receiver)**
-
-```typescript
-import { SyncReceiver } from 'remote-state-sync';
-import { io } from 'socket.io-client';
-
-const socket = io('ws://localhost:3000');
-
-const receiver = new SyncReceiver({
-  // 1. Fetch the initial snapshot over HTTP
-  snapshotGetter: async (namespace) => {
-    const res = await fetch(`http://localhost:3000/snapshot/${namespace}`);
-    return res.json();
-  },
-});
-
-// 2. Receive and apply patches incrementally
-socket.on('state-update', (namespace, patches) => {
-  receiver.applyPatches(namespace, patches);
-});
-
-async function main() {
-  const usersNs = await receiver.register('users_space');
-
-  type UserState = { connected: number; history: string[] };
-  const userState = usersNs.sync<UserState>('data');
-
-  // Output: { connected: 1, history: [] }
-  console.log(userState.toValue());
-
-  // Listen to specific item changes!
-  userState.on('update', (newVal, oldVal, patches) => {
-    console.log('State updated!', newVal.connected);
-  });
-}
-main();
-```
-
-### 2. Electron (`ipcMain` + `ipcRenderer`)
-
-**Main Process (Provider)**
-
-```typescript
-import { SyncProvider } from 'remote-state-sync';
-import { ipcMain, BrowserWindow } from 'electron';
-
-const provider = new SyncProvider();
-const appNs = provider.register('app_ns');
-
-type SettingsState = {
-  theme: 'dark' | 'light';
-  version: string;
-};
-
-// Initialize the state
-const settings = appNs.sync<SettingsState>('settings', {
-  theme: 'dark',
-  version: '1.0.0',
-});
-
-// 1. snapshotGetter via ipcMain.handle
-ipcMain.handle('get-sync-snapshot', (_, namespace) => {
-  return provider.getStateSnapshot(namespace);
-});
-
-// 2. Broadcast patches to all renderer windows
-provider.bus.on('update', (namespace, patches) => {
-  BrowserWindow.getAllWindows().forEach((win) => {
-    win.webContents.send('sync-update', namespace, patches);
-  });
-});
-
-// Example modification later down the line
-setTimeout(() => {
-  settings.set((state) => void (state.theme = 'light'));
-}, 5000);
-```
-
-**Renderer Process (Receiver with Vue)**
-
-```typescript
-import { SyncReceiver } from 'remote-state-sync';
-import { ipcRenderer } from 'electron';
-import { watch } from 'vue';
-
-const receiver = new SyncReceiver({
-  // 1. Fetch the snapshot via ipcRenderer.invoke
-  snapshotGetter: (namespace) => ipcRenderer.invoke('get-sync-snapshot', namespace),
-});
-
-// 2. Listen for patches from Main process
-ipcRenderer.on('sync-update', (_, namespace, patches) => {
-  receiver.applyPatches(namespace, patches);
-});
-
-async function setup() {
-  const appNs = await receiver.register('app_ns');
-  const settings = appNs.sync<SettingsState>('settings');
-
-  // Vue Reactivity directly tied to the remote state!
-  const settingsRef = settings.toRef();
-
-  watch(
-    settingsRef,
-    (newSettings) => {
-      console.log('Renderer theme changed to:', newSettings.theme);
-    },
-    { deep: true },
-  );
-}
-setup();
-```
+# Remote State Sync
+
+A lightweight, fully type-safe unidirectional remote state synchronization library. Effortlessly sync complex states with fine-grained precision from a Provider (e.g., Server or Electron Main) to a Receiver (e.g., Web Client or Electron Renderer).
+
+English | [中文](./README.zh-CN.md)
+
+## Features
+
+- **Unidirectional Sync**: Safely sync state from A to B with an efficient patch-based diffing system.
+- **Deep Reactivity & Proxies**: Built-in, automatic support for intercepting deep changes across `Object`, `Map`, and `Set` structures.
+- **Batch Patching**: Automatically queues and batches rapid state mutations into singular, optimized events for high performance.
+- **Framework Agnostic Transport**: Bring your own transport layer (WebSocket, Socket.io, Electron IPC, HTTP, etc).
+- **Vue Integration**: Seamlessly connects to Vue's Reactivity system out of the box (`toValue()`, `toRef()`, `toShallowRef()`).
+
+## Installation
+
+```bash
+npm install remote-state-sync
+```
+
+## Examples
+
+### 1. Hono + Socket.IO (Server & Client Web)
+
+**Server (Provider)**
+
+```typescript
+import { SyncProvider } from 'remote-state-sync';
+import { Hono } from 'hono';
+import { Server } from 'socket.io';
+
+const app = new Hono();
+const io = new Server(3000);
+
+const provider = new SyncProvider();
+const usersNs = provider.register('users_space');
+
+// Define a state
+type UserState = {
+  connected: number;
+  history: string[];
+};
+
+// Initialize the state
+const userState = usersNs.sync<UserState>('data', {
+  connected: 0,
+  history: [],
+});
+
+// 1. snapshotGetter implementation via HTTP endpoint
+app.get('/snapshot/:namespace', (c) => {
+  const ns = c.req.param('namespace');
+  return c.json(provider.getStateSnapshot(ns));
+});
+
+io.on('connection', (socket) => {
+  // Mutating deeply tracks changes and queues patches automatically
+  userState.set((state) => void state.connected++);
+
+  socket.on('disconnect', () => {
+    userState.set((state) => void state.connected--);
+  });
+});
+
+// 2. Broadcast patches triggered by deeper modifications over WebSocket
+provider.bus.on('update', (namespace, patches) => {
+  io.emit('state-update', namespace, patches);
+});
+```
+
+**Client (Receiver)**
+
+```typescript
+import { SyncReceiver } from 'remote-state-sync';
+import { io } from 'socket.io-client';
+
+const socket = io('ws://localhost:3000');
+
+const receiver = new SyncReceiver({
+  // 1. Fetch the initial snapshot over HTTP
+  snapshotGetter: async (namespace) => {
+    const res = await fetch(`http://localhost:3000/snapshot/${namespace}`);
+    return res.json();
+  },
+});
+
+// 2. Receive and apply patches incrementally
+socket.on('state-update', (namespace, patches) => {
+  receiver.applyPatches(namespace, patches);
+});
+
+async function main() {
+  const usersNs = await receiver.register('users_space');
+
+  type UserState = { connected: number; history: string[] };
+  const userState = usersNs.sync<UserState>('data');
+
+  // Output: { connected: 1, history: [] }
+  console.log(userState.toValue());
+
+  // Listen to specific item changes!
+  userState.on('update', (newVal, oldVal, patches) => {
+    console.log('State updated!', newVal.connected);
+  });
+}
+main();
+```
+
+### 2. Electron (`ipcMain` + `ipcRenderer`)
+
+**Main Process (Provider)**
+
+```typescript
+import { SyncProvider } from 'remote-state-sync';
+import { ipcMain, BrowserWindow } from 'electron';
+
+const provider = new SyncProvider();
+const appNs = provider.register('app_ns');
+
+type SettingsState = {
+  theme: 'dark' | 'light';
+  version: string;
+};
+
+// Initialize the state
+const settings = appNs.sync<SettingsState>('settings', {
+  theme: 'dark',
+  version: '1.0.0',
+});
+
+// 1. snapshotGetter via ipcMain.handle
+ipcMain.handle('get-sync-snapshot', (_, namespace) => {
+  return provider.getStateSnapshot(namespace);
+});
+
+// 2. Broadcast patches to all renderer windows
+provider.bus.on('update', (namespace, patches) => {
+  BrowserWindow.getAllWindows().forEach((win) => {
+    win.webContents.send('sync-update', namespace, patches);
+  });
+});
+
+// Example modification later down the line
+setTimeout(() => {
+  settings.set((state) => void (state.theme = 'light'));
+}, 5000);
+```
+
+**Renderer Process (Receiver with Vue)**
+
+```typescript
+import { SyncReceiver } from 'remote-state-sync';
+import { ipcRenderer } from 'electron';
+import { watch } from 'vue';
+
+const receiver = new SyncReceiver({
+  // 1. Fetch the snapshot via ipcRenderer.invoke
+  snapshotGetter: (namespace) => ipcRenderer.invoke('get-sync-snapshot', namespace),
+});
+
+// 2. Listen for patches from Main process
+ipcRenderer.on('sync-update', (_, namespace, patches) => {
+  receiver.applyPatches(namespace, patches);
+});
+
+async function setup() {
+  const appNs = await receiver.register('app_ns');
+  const settings = appNs.sync<SettingsState>('settings');
+
+  // Vue Reactivity directly tied to the remote state!
+  const settingsRef = settings.toRef();
+
+  watch(
+    settingsRef,
+    (newSettings) => {
+      console.log('Renderer theme changed to:', newSettings.theme);
+    },
+    { deep: true },
+  );
+}
+setup();
+```

package/README.zh-CN.md

@@ -1,179 +1,179 @@
-# Remote State Sync
-
-轻量级、完全类型安全的单向远程状态同步库。轻松将复杂状态以细小粒度从 Provider（如：服务端 Server 或 Electron 主进程）同步到 Receiver（如：Web 客户端 Client 或 Electron 渲染进程）。
-
-[English](./README.md) | 中文
-
-## 特性
-
-- **单向同步**：通过高效的增量 Patch (补丁) 算法，将状态从 A 端安全地同步到 B 端。
-- **深度响应与代理拦截**：内建支持对 `Object`、`Map` 和 `Set` 数据类型结构进行深层侦听、拦截与同步同步。
-- **补丁按需批处理**：高频次、连续的状态变更会在底层自动批量打包合并为单次事件分发，最大化性能。
-- **多端传输解耦**：不强绑定任何传输协议。可以灵活适配 WebSocket、Socket.io、Electron IPC、HTTP 等任意传输层网络！
-- **完美兼容 Vue**：提供无缝的 `@vue/reactivity` 支持能力，开箱即用（支持 `.toValue()`、`.toRef()` 和 `.toShallowRef()`）。
-
-## 安装
-
-```bash
-npm install remote-state-sync
-```
-
-## 场景示例
-
-### 1. 组合：Hono + Socket.IO (Server端与Web端通信)
-
-**服务端 Server (提供方 Provider)**
-
-```typescript
-import { SyncProvider } from 'remote-state-sync';
-import { Hono } from 'hono';
-import { Server } from 'socket.io';
-
-const app = new Hono();
-const io = new Server(3000);
-
-const provider = new SyncProvider();
-const usersNs = provider.register('users_space');
-
-// 定义一个状态
-type UserState = {
-  connected: number;
-  history: string[];
-};
-
-// 初始化这个状态
-const userState = usersNs.sync<UserState>('data', {
-  connected: 0,
-  history: [],
-});
-
-// 第一步：利用 Hono 提供 HTTP 接口
-// 向客户端暴露 Snapshot
-app.get('/snapshot/:namespace', (c) => {
-  const ns = c.req.param('namespace');
-  return c.json(provider.getStateSnapshot(ns));
-});
-
-io.on('connection', (socket) => {
-  // 修改复杂对象会自动生成补丁（得益于内部 Proxy）
-  userState.set((state) => void state.connected++);
-
-  socket.on('disconnect', () => {
-    userState.set((state) => void state.connected--);
-  });
-});
-
-// 第二步：通过 WebSocket 向外部广播由于变更生成的批量 Patches
-provider.bus.on('update', (namespace, patches) => {
-  io.emit('state-update', namespace, patches);
-});
-```
-
-**Web客户端 Client (接收方 Receiver)**
-
-```typescript
-import { SyncReceiver } from 'remote-state-sync';
-import { io } from 'socket.io-client';
-
-const socket = io('ws://localhost:3000');
-
-// 第一步：通过 HTTP 拉取远端快照，作为初始化状态
-snapshotGetter: (async (namespace) => {
-  const res = await fetch(`http://localhost:3000/snapshot/${namespace}`);
-  return res.json();
-},
-  // 第二步：接管增量 Patches，增量更新本地状态树
-  socket.on('state-update', (namespace, patches) => {
-    receiver.applyPatches(namespace, patches);
-  }));
-
-async function main() {
-  const usersNs = await receiver.register('users_space');
-
-  type UserState = { connected: number; history: string[] };
-  const userState = usersNs.sync<UserState>('data');
-
-  // Output: { connected: 1, history: [] }
-  console.log(userState.toValue());
-
-  userState.on('update', (newVal, oldVal, patches) => {
-    console.log('状态更新', newVal.connected);
-  });
-}
-main();
-```
-
-### 2.组合：Electron (`ipcMain` + `ipcRenderer`)
-
-**主进程 Main Process (提供方 Provider)**
-
-```typescript
-import { SyncProvider } from 'remote-state-sync';
-import { ipcMain, BrowserWindow } from 'electron';
-
-const provider = new SyncProvider();
-const appNs = provider.register('app_ns');
-
-type SettingsState = {
-  theme: 'dark' | 'light';
-  version: string;
-};
-
-// 初始化状态
-const settings = appNs.sync<SettingsState>('settings', {
-  theme: 'dark',
-  version: '1.0.0',
-});
-
-// 第一步：通过 ipcMain.handle 暴露 snapshot 获取能力
-ipcMain.handle('get-sync-snapshot', (_, namespace) => {
-  return provider.getStateSnapshot(namespace);
-});
-
-// 第二步：将状态补丁通过 ipcEvent 主动投递给所有渲染进程
-provider.bus.on('update', (namespace, patches) => {
-  BrowserWindow.getAllWindows().forEach((win) => {
-    win.webContents.send('sync-update', namespace, patches);
-  });
-});
-
-// 修改示例
-setTimeout(() => {
-  settings.set((state) => void (state.theme = 'light'));
-}, 5000);
-```
-
-**渲染进程 Renderer Process (结合Vue使用的 Receiver)**
-
-```typescript
-import { SyncReceiver } from 'remote-state-sync';
-import { ipcRenderer } from 'electron';
-import { watch } from 'vue';
-
-const receiver = new SyncReceiver({
-  // 第一步：利用 ipcRenderer.invoke 异步请求 Snapshot
-  snapshotGetter: (namespace) => ipcRenderer.invoke('get-sync-snapshot', namespace),
-});
-
-// 第二步：监听来自主进程投递的 Patches
-ipcRenderer.on('sync-update', (_, namespace, patches) => {
-  receiver.applyPatches(namespace, patches);
-});
-
-async function setup() {
-  const appNs = await receiver.register('app_ns');
-  const settings = appNs.sync<SettingsState>('settings');
-
-  // 第三步：将远端状态一键接入 Vue 的响应式生态内！
-  const settingsRef = settings.toRef(); // 或 toShallowRef()
-
-  watch(
-    settingsRef,
-    (newSettings) => {
-      console.log('Renderer theme changed to:', newSettings.theme);
-    },
-    { deep: true },
-  );
-}
-setup();
-```
+# Remote State Sync
+
+轻量级、完全类型安全的单向远程状态同步库。轻松将复杂状态以细小粒度从 Provider（如：服务端 Server 或 Electron 主进程）同步到 Receiver（如：Web 客户端 Client 或 Electron 渲染进程）。
+
+[English](./README.md) | 中文
+
+## 特性
+
+- **单向同步**：通过高效的增量 Patch (补丁) 算法，将状态从 A 端安全地同步到 B 端。
+- **深度响应与代理拦截**：内建支持对 `Object`、`Map` 和 `Set` 数据类型结构进行深层侦听、拦截与同步同步。
+- **补丁按需批处理**：高频次、连续的状态变更会在底层自动批量打包合并为单次事件分发，最大化性能。
+- **多端传输解耦**：不强绑定任何传输协议。可以灵活适配 WebSocket、Socket.io、Electron IPC、HTTP 等任意传输层网络！
+- **完美兼容 Vue**：提供无缝的 `@vue/reactivity` 支持能力，开箱即用（支持 `.toValue()`、`.toRef()` 和 `.toShallowRef()`）。
+
+## 安装
+
+```bash
+npm install remote-state-sync
+```
+
+## 场景示例
+
+### 1. 组合：Hono + Socket.IO (Server端与Web端通信)
+
+**服务端 Server (提供方 Provider)**
+
+```typescript
+import { SyncProvider } from 'remote-state-sync';
+import { Hono } from 'hono';
+import { Server } from 'socket.io';
+
+const app = new Hono();
+const io = new Server(3000);
+
+const provider = new SyncProvider();
+const usersNs = provider.register('users_space');
+
+// 定义一个状态
+type UserState = {
+  connected: number;
+  history: string[];
+};
+
+// 初始化这个状态
+const userState = usersNs.sync<UserState>('data', {
+  connected: 0,
+  history: [],
+});
+
+// 第一步：利用 Hono 提供 HTTP 接口
+// 向客户端暴露 Snapshot
+app.get('/snapshot/:namespace', (c) => {
+  const ns = c.req.param('namespace');
+  return c.json(provider.getStateSnapshot(ns));
+});
+
+io.on('connection', (socket) => {
+  // 修改复杂对象会自动生成补丁（得益于内部 Proxy）
+  userState.set((state) => void state.connected++);
+
+  socket.on('disconnect', () => {
+    userState.set((state) => void state.connected--);
+  });
+});
+
+// 第二步：通过 WebSocket 向外部广播由于变更生成的批量 Patches
+provider.bus.on('update', (namespace, patches) => {
+  io.emit('state-update', namespace, patches);
+});
+```
+
+**Web客户端 Client (接收方 Receiver)**
+
+```typescript
+import { SyncReceiver } from 'remote-state-sync';
+import { io } from 'socket.io-client';
+
+const socket = io('ws://localhost:3000');
+
+// 第一步：通过 HTTP 拉取远端快照，作为初始化状态
+snapshotGetter: (async (namespace) => {
+  const res = await fetch(`http://localhost:3000/snapshot/${namespace}`);
+  return res.json();
+},
+  // 第二步：接管增量 Patches，增量更新本地状态树
+  socket.on('state-update', (namespace, patches) => {
+    receiver.applyPatches(namespace, patches);
+  }));
+
+async function main() {
+  const usersNs = await receiver.register('users_space');
+
+  type UserState = { connected: number; history: string[] };
+  const userState = usersNs.sync<UserState>('data');
+
+  // Output: { connected: 1, history: [] }
+  console.log(userState.toValue());
+
+  userState.on('update', (newVal, oldVal, patches) => {
+    console.log('状态更新', newVal.connected);
+  });
+}
+main();
+```
+
+### 2.组合：Electron (`ipcMain` + `ipcRenderer`)
+
+**主进程 Main Process (提供方 Provider)**
+
+```typescript
+import { SyncProvider } from 'remote-state-sync';
+import { ipcMain, BrowserWindow } from 'electron';
+
+const provider = new SyncProvider();
+const appNs = provider.register('app_ns');
+
+type SettingsState = {
+  theme: 'dark' | 'light';
+  version: string;
+};
+
+// 初始化状态
+const settings = appNs.sync<SettingsState>('settings', {
+  theme: 'dark',
+  version: '1.0.0',
+});
+
+// 第一步：通过 ipcMain.handle 暴露 snapshot 获取能力
+ipcMain.handle('get-sync-snapshot', (_, namespace) => {
+  return provider.getStateSnapshot(namespace);
+});
+
+// 第二步：将状态补丁通过 ipcEvent 主动投递给所有渲染进程
+provider.bus.on('update', (namespace, patches) => {
+  BrowserWindow.getAllWindows().forEach((win) => {
+    win.webContents.send('sync-update', namespace, patches);
+  });
+});
+
+// 修改示例
+setTimeout(() => {
+  settings.set((state) => void (state.theme = 'light'));
+}, 5000);
+```
+
+**渲染进程 Renderer Process (结合Vue使用的 Receiver)**
+
+```typescript
+import { SyncReceiver } from 'remote-state-sync';
+import { ipcRenderer } from 'electron';
+import { watch } from 'vue';
+
+const receiver = new SyncReceiver({
+  // 第一步：利用 ipcRenderer.invoke 异步请求 Snapshot
+  snapshotGetter: (namespace) => ipcRenderer.invoke('get-sync-snapshot', namespace),
+});
+
+// 第二步：监听来自主进程投递的 Patches
+ipcRenderer.on('sync-update', (_, namespace, patches) => {
+  receiver.applyPatches(namespace, patches);
+});
+
+async function setup() {
+  const appNs = await receiver.register('app_ns');
+  const settings = appNs.sync<SettingsState>('settings');
+
+  // 第三步：将远端状态一键接入 Vue 的响应式生态内！
+  const settingsRef = settings.toRef(); // 或 toShallowRef()
+
+  watch(
+    settingsRef,
+    (newSettings) => {
+      console.log('Renderer theme changed to:', newSettings.theme);
+    },
+    { deep: true },
+  );
+}
+setup();
+```

package/dist/index.d.ts

@@ -4,6 +4,7 @@ import { Ref, ShallowRef } from '@vue/reactivity';
 type PatchOperation = 'set' | 'delete' | 'clear' | 'add';
 interface Patch {
     op: PatchOperation;
+    key: string;
     path: (string | number)[];
     value?: unknown;
 }
@@ -13,6 +14,7 @@ interface SyncOptions {
 type SyncUpdater<T> = (state: T) => T | void;
 type SyncBusDefinition = {
     update: (namespace: string, patches: Patch[]) => void;
+    register: (namespace: string) => void;
 };
 type ReceiverItemBusDefinition<T> = {
     update: (newValue: T, oldValue: T, patches: Patch[]) => void;
@@ -20,7 +22,7 @@ type ReceiverItemBusDefinition<T> = {
 
 declare class SyncProvider {
     private namespaces;
-    bus: Nanobus<SyncBusDefinition>;
+    readonly bus: Nanobus<SyncBusDefinition>;
     constructor();
     register(namespace: string): SyncNamespaceProvider;
     getStateSnapshot(namespace: string): Promise<Record<string, unknown>>;
@@ -68,7 +70,7 @@ declare class SyncItemReceiver<T> {
     private value;
     private _ref;
     private _shallowRef;
-    bus: Nanobus<ReceiverItemBusDefinition<T>>;
+    readonly bus: Nanobus<ReceiverItemBusDefinition<T>>;
     constructor(key: string, initialValue: T);
     on(event: 'update', cb: (newValue: T, oldValue: T, patches: Patch[]) => void): void;
     toValue(): T;

package/dist/index.js

@@ -53,19 +53,19 @@ function clearValue(current) {
 }
 
 // src/proxy.ts
-function createDeepProxy(target, path, onPatch) {
+function createDeepProxy(target, rootKey, path, onPatch) {
   if (!shouldProxy(target)) {
     return target;
   }
   if (target instanceof Map) {
-    return createMapProxy(target, path, onPatch);
+    return createMapProxy(target, rootKey, path, onPatch);
   }
   if (target instanceof Set) {
-    return createSetProxy(target, path, onPatch);
+    return createSetProxy(target, rootKey, path, onPatch);
   }
-  return createObjectProxy(target, path, onPatch);
+  return createObjectProxy(target, rootKey, path, onPatch);
 }
-function createObjectProxy(target, path, onPatch) {
+function createObjectProxy(target, rootKey, path, onPatch) {
   const handler = {
     get(obj, prop, receiver) {
       const value = Reflect.get(obj, prop, receiver);
@@ -73,7 +73,7 @@ function createObjectProxy(target, path, onPatch) {
         return value;
       }
       if (shouldProxy(value)) {
-        return createDeepProxy(value, [...path, prop], onPatch);
+        return createDeepProxy(value, rootKey, [...path, prop], onPatch);
       }
       return value;
     },
@@ -85,6 +85,7 @@ function createObjectProxy(target, path, onPatch) {
       if (success) {
         onPatch({
           op: "set",
+          key: rootKey,
           path: [...path, prop],
           value
         });
@@ -99,6 +100,7 @@ function createObjectProxy(target, path, onPatch) {
       if (success) {
         onPatch({
           op: "delete",
+          key: rootKey,
           path: [...path, prop]
         });
       }
@@ -107,7 +109,7 @@ function createObjectProxy(target, path, onPatch) {
   };
   return new Proxy(target, handler);
 }
-function createMapProxy(target, path, onPatch) {
+function createMapProxy(target, rootKey, path, onPatch) {
   const handler = {
     get(obj, prop) {
       const value = Reflect.get(obj, prop);
@@ -120,6 +122,7 @@ function createMapProxy(target, path, onPatch) {
             const result = obj.set(key, val);
             onPatch({
               op: "set",
+              key: rootKey,
               path: [...path, key],
               value: val
             });
@@ -133,6 +136,7 @@ function createMapProxy(target, path, onPatch) {
             if (hasKey) {
               onPatch({
                 op: "delete",
+                key: rootKey,
                 path: [...path, key]
               });
             }
@@ -145,6 +149,7 @@ function createMapProxy(target, path, onPatch) {
               const result = obj.clear();
               onPatch({
                 op: "clear",
+                key: rootKey,
                 path
               });
               return result;
@@ -155,7 +160,7 @@ function createMapProxy(target, path, onPatch) {
           return function(key) {
             const getVal = obj.get(key);
             if (shouldProxy(getVal)) {
-              return createDeepProxy(getVal, [...path, key], onPatch);
+              return createDeepProxy(getVal, rootKey, [...path, key], onPatch);
             }
             return getVal;
           };
@@ -167,7 +172,7 @@ function createMapProxy(target, path, onPatch) {
   };
   return new Proxy(target, handler);
 }
-function createSetProxy(target, path, onPatch) {
+function createSetProxy(target, rootKey, path, onPatch) {
   const handler = {
     get(obj, prop) {
       const value = Reflect.get(obj, prop);
@@ -182,6 +187,7 @@ function createSetProxy(target, path, onPatch) {
             if (!hasVal) {
               onPatch({
                 op: "add",
+                key: rootKey,
                 // For set, we don't have a key to navigate, but we can pass the value
                 // In a true Sync scenario, Set diffing is tricky. Path is just the Set itself.
                 path,
@@ -198,6 +204,7 @@ function createSetProxy(target, path, onPatch) {
             if (hasVal) {
               onPatch({
                 op: "delete",
+                key: rootKey,
                 path,
                 // Similarly, deleting from set happens at Set boundary
                 value: val
@@ -213,6 +220,7 @@ function createSetProxy(target, path, onPatch) {
               const result = obj.clear();
               onPatch({
                 op: "clear",
+                key: rootKey,
                 path
               });
               return result;
@@ -239,6 +247,7 @@ var SyncProvider = class {
     }
     const ns = new SyncNamespaceProvider(namespace, this.bus);
     this.namespaces.set(namespace, ns);
+    this.bus.emit("register", namespace);
     return ns;
   }
   async getStateSnapshot(namespace) {
@@ -316,10 +325,11 @@ var SyncItemProvider = class {
   setValue(newVal) {
     this.onPatch({
       op: "set",
-      path: [this.key],
+      key: this.key,
+      path: [],
       value: newVal
     });
-    this.value = createDeepProxy(newVal, [this.key], this.onPatch);
+    this.value = createDeepProxy(newVal, this.key, [], this.onPatch);
   }
 };
 
@@ -365,8 +375,7 @@ var SyncNamespaceReceiver = class {
   applyPatches(patches) {
     const affectedItems = /* @__PURE__ */ new Map();
     for (const patch of patches) {
-      if (patch.path.length === 0) continue;
-      const key = patch.path[0];
+      const key = patch.key;
       const item = this.items.get(key);
       if (item) {
         if (!affectedItems.has(item)) {
@@ -384,9 +393,9 @@ var SyncNamespaceReceiver = class {
     }
   }
   applyPatchToObject(obj, patch) {
-    if (patch.path.length === 0) return;
+    const fullPath = [patch.key, ...patch.path];
     if (patch.op === "clear" || patch.op === "add") {
-      const target = navigatePath(obj, patch.path, 0, patch.path.length);
+      const target = navigatePath(obj, fullPath, 0, fullPath.length);
       if (patch.op === "clear") {
         clearValue(target);
       } else {
@@ -394,8 +403,8 @@ var SyncNamespaceReceiver = class {
       }
       return;
     }
-    const current = navigatePath(obj, patch.path, 0, patch.path.length - 1);
-    const lastKey = patch.path[patch.path.length - 1];
+    const current = navigatePath(obj, fullPath, 0, fullPath.length - 1);
+    const lastKey = fullPath[fullPath.length - 1];
     if (patch.op === "set") {
       setValueAtPath(current, lastKey, patch.value);
     } else if (patch.op === "delete") {
@@ -431,7 +440,7 @@ var SyncItemReceiver = class {
     return this._shallowRef;
   }
   applyPatch(patch) {
-    if (patch.path.length === 1) {
+    if (patch.path.length === 0) {
       if (patch.op === "set") {
         this.value = patch.value;
         if (this._ref) this._ref.value = patch.value;
@@ -441,41 +450,41 @@ var SyncItemReceiver = class {
     }
     const lastKey = patch.path[patch.path.length - 1];
     if (patch.op === "set") {
-      const current = navigatePath(this.value, patch.path, 1, patch.path.length - 1);
+      const current = navigatePath(this.value, patch.path, 0, patch.path.length - 1);
       const refCurrent = navigatePath(
         this._ref ? this._ref.value : null,
         patch.path,
-        1,
+        0,
         patch.path.length - 1
       );
       setValueAtPath(current, lastKey, patch.value);
       setValueAtPath(refCurrent, lastKey, patch.value);
     } else if (patch.op === "delete") {
-      const current = navigatePath(this.value, patch.path, 1, patch.path.length - 1);
+      const current = navigatePath(this.value, patch.path, 0, patch.path.length - 1);
       const refCurrent = navigatePath(
         this._ref ? this._ref.value : null,
         patch.path,
-        1,
+        0,
         patch.path.length - 1
       );
       deleteValueAtPath(current, lastKey);
       deleteValueAtPath(refCurrent, lastKey);
     } else if (patch.op === "add") {
-      const target = navigatePath(this.value, patch.path, 1, patch.path.length);
+      const target = navigatePath(this.value, patch.path, 0, patch.path.length);
       const refTarget = navigatePath(
         this._ref ? this._ref.value : null,
         patch.path,
-        1,
+        0,
         patch.path.length
       );
       addValueToSet(target, patch.value);
       addValueToSet(refTarget, patch.value);
     } else if (patch.op === "clear") {
-      const target = navigatePath(this.value, patch.path, 1, patch.path.length);
+      const target = navigatePath(this.value, patch.path, 0, patch.path.length);
       const refTarget = navigatePath(
         this._ref ? this._ref.value : null,
         patch.path,
-        1,
+        0,
         patch.path.length
       );
       clearValue(target);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "remote-state-sync",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "A lightweight, fully type-safe unidirectional remote state synchronization library.",
   "type": "module",
   "repository": {
@@ -12,6 +12,15 @@
     "name": "Coooookies",
     "email": "admin@mitay.net"
   },
+  "keywords": [
+    "remote",
+    "state",
+    "sync",
+    "typescript",
+    "electron",
+    "state-management",
+    "ipc"
+  ],
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -27,9 +36,11 @@
   "engines": {
     "node": ">=18.0.0"
   },
+  "provenance": true,
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
-    "access": "public"
+    "access": "public",
+    "provenance": true
   },
   "scripts": {
     "dev": "tsup src/index.ts --watch",
@@ -57,4 +68,4 @@
     "@vue/reactivity": "^3.5.28",
     "nanobus": "^4.5.0"
   }
-}
+}