@unified-desktop/bridge 0.0.0-stage → 0.2.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Unified Desktop Starter contributors
+
+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,3 +1,70 @@
-# Temporary Holding Version
+# @unified-desktop/bridge
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+供 React、Vue 等前端使用的统一 TypeScript Bridge。同一份业务代码可在浏览器、Electron 和 Tauri 中运行，`getBridge()` 自动选择对应适配器。
+
+## 安装与使用
+
+```bash
+npm install --save-exact @unified-desktop/bridge@0.2.4
+```
+
+生成项目已安装匹配版本，并在 `frontend/src/platform.ts` 中配置 Bridge。业务页面从该入口导入，保持项目的安全策略生效。手动集成时，在首次 `getBridge()` 前配置：
+
+```ts
+import { configureBridge, getBridge } from '@unified-desktop/bridge';
+
+configureBridge({
+  apiBaseUrl: 'https://api.example.com',
+  externalProtocols: ['https:', 'mailto:'],
+});
+
+const bridge = await getBridge();
+console.log(bridge.runtime); // web | electron | tauri
+await bridge.store.set('theme', 'dark');
+const theme = await bridge.store.get<string>('theme');
+```
+
+`getBridge()` 在页面生命周期内复用同一个实例；首次解析后配置会锁定。包采用 ESM，并包含 TypeScript 类型声明。原生能力需要匹配版本的 shell、preload 和权限配置，单独安装本包不会自动添加这些文件。
+
+## 能力与平台边界
+
+| 命名空间 | 用途 |
+| --- | --- |
+| `http`、`upload`、`websocket` | HTTP 请求、上传、WebSocket 连接 |
+| `fileSystem` | 文件/目录选择、句柄读取与写入、释放句柄 |
+| `clipboard`、`dialog`、`notification` | 剪贴板、对话框、通知 |
+| `store`、`secureStorage` | JSON 数据持久化、原生安全存储 |
+| `permissions` | 查询与请求权限 |
+| `shell`、`process`、`windowState` | 外部链接、进程、窗口状态 |
+| `deepLink`、`updater`、`logger` | 深链、更新、日志 |
+
+浏览器能力取决于浏览器授权和 API 支持。浏览器没有原生安全存储或应用更新能力；安全存储等不支持的操作返回 `UNSUPPORTED`，更新检查返回空结果。Electron/Tauri 在原生端继续执行权限校验，前端配置不能绕过原生限制。更新器默认关闭。
+
+## 文件选择示例
+
+以下函数应在用户点击按钮时调用；文件句柄属于当前进程，使用后释放，不应保存到数据库或下一次会话中。
+
+```ts
+async function readSelectedText() {
+  const bridge = await getBridge();
+  const [handle] = await bridge.fileSystem.pickFiles();
+  if (!handle) return; // 用户取消选择
+  try {
+    return new TextDecoder().decode(await bridge.fileSystem.readFile(handle));
+  } finally {
+    await bridge.fileSystem.releaseFileHandle(handle);
+  }
+}
+```
+
+业务代码可捕获 `BridgeError`，按 `code` 区分 `PERMISSION_DENIED`、`CANCELLED`、`NOT_FOUND`、`INVALID_INPUT`、`UNSUPPORTED`、`NETWORK_ERROR` 和 `UNKNOWN`。保留的兼容方法包括 `readTextFile`、`saveTextFile`、`openExternal` 和 `checkUpdate`；文件访问优先采用选择器和句柄。
+
+测试或自定义适配器可使用 `createCommonBridge` 和 `BridgeOverrides`。新增能力时同时实现所需平台适配器。
+
+## 相关包
+
+- [create-unified-desktop](https://www.npmjs.com/package/create-unified-desktop)：创建完整项目。
+- [@unified-desktop/cli](https://www.npmjs.com/package/@unified-desktop/cli)：检查、升级、回滚。
+- [@unified-desktop/electron-runtime](https://www.npmjs.com/package/@unified-desktop/electron-runtime)：Electron 主进程。
+
+许可证：MIT。