moonbridge-ts 0.1.0

package/.eslintignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+build/
+coverage/
+*.min.js

package/.eslintrc.cjs

@@ -0,0 +1,27 @@
+/** @type { import('eslint').Linter.Config } */
+module.exports = {
+  root: true,
+  env: { browser: true, es2022: true },
+  parser: '@typescript-eslint/parser',
+  parserOptions: { ecmaVersion: 'latest', sourceType: 'module', project: './tsconfig.json' },
+  plugins: ['@typescript-eslint'],
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended',
+    'prettier',
+  ],
+  rules: {
+    'no-magic-numbers': ['warn', { ignore: [0, 1, -1], ignoreArrayIndexes: true }],
+    'no-restricted-syntax': [
+      'warn',
+      {
+        selector: "Literal[value=/^[a-z_][a-z0-9_]*$/]",
+        message: 'Use named constants instead of string literals for protocol/type names.',
+      },
+    ],
+  },
+  overrides: [
+    { files: ['src/**/*.ts'], rules: { '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }] } },
+  ],
+  ignorePatterns: ['node_modules/', 'dist/', 'coverage/', '*.min.js'],
+};

package/.prettierignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+build/
+coverage/
+package-lock.json

package/.prettierrc

@@ -0,0 +1,7 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "es5",
+  "printWidth": 100
+}

package/DEPENDENCIES.md

@@ -0,0 +1,8 @@
+# Dependency direction (IC-003)
+
+- **core/** – Protocol types, constants, handshake, request encode. No dependency on transport or client.
+- **transport/** – ITransportClient interface and WebSocketClient. Depends only on (nothing above).
+- **utils/** – Logger and helpers. No dependency on client or transport.
+- **client/** – ConnectionManager, MoonbridgeClient, types, retry_policy. May depend on core, transport, utils.
+
+**Rule**: Only `client/` may depend on `core/`, `transport/`, and `utils/`. No reverse or circular dependencies.

package/README.md

@@ -0,0 +1,303 @@
+# moonbridge-ts
+
+基于 MoonBridge 通信协议的 TypeScript IPC 库，面向**仅支持 WebSocket 的环境**（如 WPS 加载项任务窗格、浏览器页面），与 moonbridge-ipc 服务端互通（不限制技术栈），实现稳定、统一 IPC 通信。
+
+---
+
+## 完全一致原则（与 Flutter 端对齐）
+
+本库以 **moonbridge-ipc-flutter** 的 `lib/` 为**唯一参考**，在以下维度与 Flutter 端保持**完全一致**，便于跨端维护与同一套心智模型：
+
+- **命名**：类名、方法名、枚举名、文件名、目录名与 Flutter 端一致（仅因语言规范导致的拼写风格可微调）。
+- **设计模式**：Flutter 使用的设计模式在 TS 端以相同方式体现；Flutter 用 class 则 TS 用 class，Flutter 用 enum 则 TS 用 enum。
+- **公开 API**：对外方法签名、参数语义、返回值约定与 Flutter 端对应抽象一致，使两端调用方式可互换理解。
+- **目录与层级**：目录结构、模块划分与 Flutter `lib/` 一致（如 `client/`、`general/encode`、`general/message`、`general/transport`），便于按相同路径在两端定位。
+- **平台封装例外**：仅在**平台能力差异**（如 WebSocket 的运行时 API 不同）时，底层实现可不同，但**对外暴露的 API（方法名、参数与语义）须与 Flutter 端抽象完全一致**（如 `TransportClient.connectWithServer()`、`sendData()`、`isClientConnected`、`onErrorAndClose()`）。
+- **实施顺序**：先**第一步**完全还原 `lib/general/`（encode、message、transport、config、error、lock、statistics、utils、app_launch），再**第二步**对齐 client/、extension/ 及根入口 index.ts。
+
+详见仓库内 `specs/001-moonbridge-js-full-1to1/` 下的规格与契约。
+
+---
+
+## 1. 是什么？
+
+**适用场景**：moonbridge-ts 面向**仅支持 WebSocket 的环境**（WPS 加载项任务窗格、浏览器页面），无法使用 Node Socket。与 Flutter 端差异：JS 无 Dart 反射、无 build_runner，模块通过 `@MoonBridgeModule` / `@MoonBridgeMethod` 装饰器在**运行时**注册到 MoonBridgeRegistry。
+
+moonbridge-ts 是 **MoonBridge IPC 在 TypeScript 侧的客户端与服务端实现**，与 Flutter 端「客户端 / 服务端」角色模型一致：
+
+- **客户端**：负责消息的发送与接收（本库实现**客户端**角色）。
+- **服务端**：由 NPC 侧 moonbridge-ipc-flutter 承担，负责消息的中转与分发（本库同时提供 **MoonBridgeIpcServer** 用于服务端场景）。
+
+可以类比为：每个"微信用户"是客户端，既能发消息也能收消息；微信服务器负责中转。本库相当于在 WPS 或浏览器里运行的"微信客户端"，通过 WebSocket 连接 NPC 的 MoonBridge IPC 服务端；同时也提供"微信服务器"能力供 NPC 端使用。
+
+---
+
+## 2. 当前提供的能力
+
+### 2.1 客户端能力（MoonBridgeIpcClient）
+
+- 基于 **WebSocket（ws）** 的传输层，与 Flutter 端 WebSocket 接入语义一致；wss 预留。
+- **握手与协议**：连接建立后发送 Handshake，校验对端为 MoonBridge IPC 服务后再进入会话。
+- **连接管理**：连接状态机（disconnected / connecting / connected / disconnecting）、有限次数重试与固定间隔（与 Flutter IpcConnectionManager 对齐）。
+- **发送请求并接收响应**：`messenger.postMessage(target, { args: [..., callback] })`，将回调作为 args 末位传入，服务端响应时调用 callback。
+- **接收对端请求**：`registerHandler(moduleName, methodName, handler)` 注册本地方法；对端发送 TYPE_NAME_REQUEST 时派发到 handler，参数中 callbackId 替换为 ResultCallback，业务调用 `callback.invoke(result)` 回写 TYPE_NAME_RESPONSE；未注册则回写 TYPE_NAME_ERROR。协议与 [contracts](../specs/001-moonbridge-js-receive-extensions/contracts/message-formats.md) 一致（仓库内路径）。
+- **心跳保活**：连接建立后按 `heartbeatIntervalMs`（默认 30s）发送 TYPE_NAME_PING；可配置 `heartbeatEnabled`、`heartbeatIntervalMs`。
+- **EventBus**：`client.getEventBus().register(eventName, callback)` 订阅，`client.postEvent(type, source?, data?)` 发布；收到 TYPE_NAME_EVENT 时按事件名派发。
+- **可配置**：serverAddress、serverPort、path、clientName、heartbeatIntervalMs、heartbeatEnabled 等，与 Flutter 端配置概念一致。
+
+### 2.2 服务端能力（MoonBridgeIpcServer）
+
+- 基于 **WebSocket（ws）** 的服务端接收与分发。
+- **客户端身份管理**：支持客户端身份认证（ClientIdentity），记录连接客户端信息。
+- **消息派发**：根据 clientName、moduleName、methodName 派发到注册的 handler。
+- **响应回写**：支持同步响应和异步响应（通过 ResultCallback）。
+- **EventBus 事件分发**：收到 TYPE_NAME_EVENT 时向订阅者广播。
+
+### 2.3 模块化能力（@MoonBridgeModule / @MoonBridgeMethod）
+
+- 通过装饰器注册模块和方法，运行时自动注册到 MoonBridgeRegistry。
+- 支持 `BridgeModule` 基类，提供与 Flutter 端一致的模块抽象。
+- 支持方法拦截、日志等横切关注点。
+
+### 2.4 WPS 应用启动能力（WpsAppLauncher）
+
+- 支持通过 AppLaunchIdentifier 启动 WPS 应用。
+- 支持应用安装路径查询和类型转换。
+
+---
+
+## 3. 架构与分层（与 Flutter lib/ 一一对应）
+
+与 moonbridge-ipc-flutter 保持**一致的分层与目录**，便于按相同路径在两端定位：
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│  moonbridge/              核心模块层                                        │
+│  ├── kernel/              Bridge、BridgeModule 核心抽象                    │
+│  ├── annotation/          @MoonBridgeModule、@MoonBridgeMethod 装饰器      │
+│  └── logger/              日志抽象                                         │
+├──────────────────────────────────────────────────────────────────────────┤
+│  moonbridge-ipc/          IPC 通信层                                       │
+│  ├── client/              IPC 客户端（MoonBridgeIpcClient）                │
+│  │   ├── internal/        内部实现（连接管理、桥接、执行器等）               │
+│  │   └── types/           客户端类型定义                                    │
+│  ├── server/              IPC 服务端（MoonBridgeIpcServer）                │
+│  │   └── credential/      客户端身份认证                                   │
+│  ├── general/             通用层（与 Flutter lib/general 对应）            │
+│  │   ├── encode/          IpcMessageEncoder 消息编码                      │
+│  │   ├── message/         消息类型常量、负载类型                           │
+│  │   └── error/           IpcError 与错误码                               │
+│  └── extension/           扩展能力                                         │
+├──────────────────────────────────────────────────────────────────────────┤
+│  wps-launcher/            WPS 应用启动层                                   │
+│  └── launcher/            WpsAppLauncher 实现                             │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+- **moonbridge/**：对应 Flutter 端核心抽象，提供 Bridge、BridgeModule、装饰器等。
+- **moonbridge-ipc/client**：对应 Flutter `lib/client/`，对外暴露 `MoonBridgeIpcClient`。
+- **moonbridge-ipc/server**：对应 Flutter 服务端实现，对外暴露 `MoonBridgeIpcServer`。
+- **moonbridge-ipc/general**：对应 Flutter `lib/general/`，协议常量与编解码。
+- **wps-launcher/**：对应 Flutter `lib/app_launch/`，WPS 应用启动能力。
+
+---
+
+## 4. 目录结构
+
+```text
+moonbridge-ts/
+├── src/
+│   ├── moonbridge/              # 核心模块层
+│   │   ├── kernel/
+│   │   │   ├── bridge.ts       # Bridge 抽象
+│   │   │   ├── bridge_module.ts # BridgeModule 基类
+│   │   │   ├── result_callback.ts # 结果回调
+│   │   │   └── executor.ts     # 执行器
+│   │   ├── annotation/
+│   │   │   ├── decorators.ts  # @MoonBridgeModule、@MoonBridgeMethod
+│   │   │   └── registry.ts     # MoonBridgeRegistry
+│   │   ├── message/            # 消息解析
+│   │   ├── module/             # 模块创建与方法调用
+│   │   ├── logger/
+│   │   │   └── logger.ts       # 日志抽象
+│   │   └── index.ts            # 对外导出
+│   ├── moonbridge-ipc/         # IPC 通信层
+│   │   ├── client/
+│   │   │   ├── moonbridge_ipc_client.ts  # 客户端入口
+│   │   │   ├── internal/       # 内部实现
+│   │   │   │   ├── bridge/     # 桥接与执行
+│   │   │   │   ├── ipc/        # IPC 核心
+│   │   │   │   └── settings/   # 配置
+│   │   │   └── types/          # 类型定义
+│   │   ├── server/
+│   │   │   ├── moonbridge_ipc_server.ts  # 服务端入口
+│   │   │   ├── credential/     # 客户端身份
+│   │   │   └── internal/       # 内部实现
+│   │   ├── general/
+│   │   │   ├── encode/         # 消息编码
+│   │   │   ├── message/        # 消息类型
+│   │   │   └── error/          # 错误定义
+│   │   ├── extension/         # 扩展
+│   │   └── index.ts            # 对外导出
+│   ├── wps-launcher/           # WPS 应用启动
+│   │   ├── launcher/
+│   │   │   └── wps_app_launcher.ts
+│   │   └── index.ts            # 对外导出
+│   └── index.ts                # 根入口
+├── tests/
+│   ├── unit/
+│   └── integration/
+├── docs/
+│   ├── ROADMAP.md
+│   ├── REFACTOR_SCOPE.md
+│   └── STRUCTURE.md
+├── DEPENDENCIES.md
+├── package.json
+└── README.md
+```
+
+---
+
+## 5. 使用示例
+
+### 5.1 安装
+
+```bash
+npm install moonbridge-ts
+# 或本地引用
+# "moonbridge-ts": "path:../moonbridge-ts"
+```
+
+### 5.2 客户端初始化与连接
+
+```typescript
+import {
+  MoonBridgeIpcClientBuilder,
+  WebSocketServerEndpoint,
+} from 'moonbridge-ts';
+
+const client = MoonBridgeIpcClientBuilder.builder()
+  .clientName('client_a')
+  .useWebSocketChannel(new WebSocketServerEndpoint('127.0.0.1', 9100, '/ws'))
+  .build(true);
+
+client.connect((success, error) => {
+  if (success) console.log('连接成功');
+  else console.error('连接失败', error);
+});
+```
+
+### 5.3 发送消息
+
+```typescript
+// 极简调用：仅传核心定位 + 参数
+client.messenger.postMessage(
+  { clientName: 'client_b', moduleName: 'Printer', methodName: 'print' },
+  ['hello']
+);
+
+// 完整调用：传定位 + 全量配置（含 args、strategy、onError）
+client.messenger.postMessage(
+  { clientName: 'npc', moduleName: 'explainPage', methodName: 'call' },
+  {
+    args: [{ slide: 1, docPath: '/path/to.pptx' }, (res) => console.log(res)],
+    onError: (err) => console.error(err),
+  }
+);
+```
+
+### 5.4 模块实现（宿主侧）
+
+```typescript
+import { BridgeModule } from 'moonbridge-ts';
+import { Bridge } from 'moonbridge-ts';
+import { MoonBridgeModule, MoonBridgeMethod } from 'moonbridge-ts';
+
+@MoonBridgeModule('Printer')
+class PrintModule extends BridgeModule {
+  constructor(bridge: Bridge) { super(bridge); }
+  @MoonBridgeMethod('print')
+  printMessage(msg: string) { console.log('[MoonBridge] print', msg); }
+}
+```
+
+**装饰器配置**（tsconfig.json）：`"experimentalDecorators": true`，必要时 `"useDefineForClassFields": false`。
+
+### 5.5 服务端示例
+
+```typescript
+import { MoonBridgeIpcServerBuilder, WebSocketServerEndpoint } from 'moonbridge-ts';
+
+const server = MoonBridgeIpcServerBuilder.builder()
+  .serverName('moonbridge_server')
+  .useWebSocketChannel(new WebSocketServerEndpoint('0.0.0.0', 9100, '/ws'))
+  .build();
+
+server.start((success, error) => {
+  if (success) console.log('服务端启动成功');
+  else console.error('服务端启动失败', error);
+});
+```
+
+### 5.6 在 WPS 加载项中集成
+
+1. 构建本库：`npm install && npm run build`，得到 `dist/`（含 CJS、ESM、IIFE）。
+2. 在任务窗格页面中引入 IIFE：`<script src="path/to/index.global.js"></script>`，会暴露 `window.MoonbridgeJS`（含 `MoonBridgeIpcClientBuilder`、`WebSocketServerEndpoint` 等）。
+3. 使用仓库内 `wps-addin/src/ipc/moonbridge/client.js` 提供的 `createNpcClient()`，内部会读取 `getConfig()` 的 npcWsUrl/npcWsPort 并组装 WebSocket 通道。
+4. 端口与地址需按环境配置（见 `window.getConfig()` 或 `__NPC_LINK_CONFIG__`），避免误用固定配置。
+5. 为「连接」「讲解当前页」「发送消息」等按钮绑定 `createNpcClient().connect()`、`client.messenger.postMessage(...)` 即可。
+
+详见仓库根目录下 `specs/005-moonbridge-js-ipc/quickstart.md`。
+
+---
+
+## 6. 与 moonbridge-ipc-flutter 的对应关系
+
+| Flutter 端                        | moonbridge-ts                      |
+| --------------------------------- | ---------------------------------- |
+| MoonBridgeIpcClient               | MoonBridgeIpcClient                |
+| MoonBridgeIpcServer               | MoonBridgeIpcServer                |
+| IpcConnectionManager              | IpcConnectionManager               |
+| TransportClient / WebSocketClient | ITransportClient / WebSocketClient |
+| Handshake、Request/Response 协议  | general/encode、general/message    |
+| 连接重试、握手超时                | connection_manager + retry_policy  |
+| ClientIdentity                    | ClientIdentity                     |
+| ResultCallback                    | ResultCallback                     |
+
+报文格式与 Flutter 端对齐，详见 **docs/ROADMAP.md** 与特性契约 `specs/001-moonbridge-js-receive-extensions/contracts/message-formats.md`。客户端身份与动态端口为可选扩展，见 ROADMAP。
+
+---
+
+## 7. 开发与测试
+
+```bash
+npm install
+npm run build      # 产出 dist/
+npm run test       # 单元测试（Vitest）
+npm run lint       # ESLint
+npm run format     # Prettier
+```
+
+---
+
+## 8. 注意事项
+
+- 仅使用 **ws**，未实现 wss；与当前 Flutter 端保持一致。
+- 客户端身份与鉴权与 Flutter 端一致：基于 clientName 及可选的 ClientIdentity，无 Token/Cookie。
+- 本库**实现客户端和服务端**，客户端连接 NPC（moonbridge-ipc-flutter），服务端可供 NPC 或其他客户端连接。
+
+---
+
+## 9. 规范与约定（贡献与维护）
+
+**本项目不做向后兼容，只保留最新方案。** 方案升级或更新时，不保留废弃实现、无需考虑向后兼容，仅保留最新实现，以避免历史兼容逻辑堆积、降低维护成本。
+
+moonbridge-ts 与 moonbridge-ipc-flutter 采用**一比一翻译**原则：命名、目录层级、对外 API 语义尽量一致；仅在平台能力差异（如 WebSocket 底层 API）时内部实现可不同，**对外暴露的 API 须与 Flutter 端抽象一致**。
+
+- **与 Flutter 的详细对应**：见 [docs/STRUCTURE.md](docs/STRUCTURE.md)。
+- **单文件结构约定**（分区、`// IMPORTS`、`// CLASS: Xxx` 等）：见 [specs/001-moonbridge-js-refactor/contracts/file-structure.md](../specs/001-moonbridge-js-refactor/contracts/file-structure.md)。
+- **注释约定**（文件头、JSDoc、与 Flutter 对应注明）：见 [specs/001-moonbridge-js-refactor/contracts/comment-convention.md](../specs/001-moonbridge-js-refactor/contracts/comment-convention.md)。
+- **Flutter–JS 一比一对应约定**：见 [specs/001-moonbridge-js-refactor/contracts/flutter-js-1-to-1.md](../specs/001-moonbridge-js-refactor/contracts/flutter-js-1-to-1.md)。
+- **禁止顶层业务函数**：业务逻辑应封装在 class/interface 中；client/ 与 transport/ 不新增无归属的顶层函数（工厂等使用类静态方法，如 `ClientConfig.create`、`ResultCallback.create`、`RpcProxy.createService`）。协议层编解码过渡期可保留顶层函数，须在注释中标明与 Flutter 对应。
+- **查阅 specs 与 contracts**：仓库内 `specs/001-moonbridge-js-refactor/` 含本改造的 spec、plan、tasks、contracts；`contracts/` 下为单文件结构、注释、Flutter–JS 一比一约定。
+- **规范豁免**：自动生成代码（如未来 RPC 生成器产物）、对第三方 API 的极薄 wrapper 可豁免完整注释与分区规范，仅需文件头与对外入口简短说明；见 research.md 与 spec Edge Cases。

package/dist/bridge_module-2N398tJq.d.ts

@@ -0,0 +1,126 @@
+import { MessageParserManager } from './moonbridge/message/message_parser_manager.js';
+
+/**
+ * 消息执行器抽象接口，对应 Flutter lib/kernel/executor.dart Executor。
+ *
+ * Executor 绑定一个 Bridge 实例，并根据元数据执行指定模块中的方法。
+ */
+
+declare abstract class Executor {
+    /** 绑定的 bridge 引用（WeakReference 在 JS 中用普通引用表达）。 */
+    private readonly _bridge;
+    /**
+     * 指定构造方法，并在这里传递绑定的 bridge 实例。
+     */
+    protected constructor(bridge: Bridge);
+    /**
+     * 获取绑定的 bridge 对象。
+     */
+    get bridge(): Bridge;
+    /**
+     * 根据原数据 metaData 执行指定类中的指定方法，需要在子类中实现，
+     * 并返回最终执行结果：true 为执行成功，false 为执行失败。
+     */
+    abstract invokeMethod(metaData: unknown): boolean;
+}
+
+/**
+ * module 实例构造器，对应 Flutter lib/module/module_creator.dart。
+ *
+ * JS 端：通过 MoonBridgeRegistry 中已注册的模块构造函数创建实例，
+ * 不再依赖 ModuleFactory 列表。
+ */
+declare class ModuleCreator {
+    private readonly cacheMap;
+    /** JS 中没有 WeakReference 的通用实现，这里直接持有强引用。 */
+    private readonly _bridge;
+    constructor(bridge: Bridge);
+    /**
+     * 获取绑定的 bridge 对象。
+     */
+    get bridge(): Bridge;
+    /**
+     * 获取名为 name 的 module 实例。
+     *
+     * 创建流程：
+     * - 优先从本地缓存中读取；
+     * - 若无缓存，则从 MoonBridgeRegistry 中获取构造函数并创建实例；
+     * - 创建成功后写入缓存并返回。
+     */
+    getModule(name: string): BridgeModule | undefined;
+}
+
+/**
+ * 桥接接口抽象，对应 Flutter lib/kernel/bridge.dart Bridge。
+ *
+ * Bridge 负责提供：
+ * - 方法执行器 Executor；
+ * - module 实例构造器 ModuleCreator；
+ * - 消息解析器管理器 MessageParserManager。
+ *
+ * 具体实现由上层在 JS 端根据运行环境提供。
+ */
+
+interface Bridge {
+    /** 获取方法执行器 */
+    readonly executor: Executor;
+    /** 获取 module 实例构造器 */
+    readonly moduleCreator: ModuleCreator;
+    /** 获取消息解析器实例 */
+    readonly parserManager: MessageParserManager;
+}
+
+/**
+ * 自定义 module 基础类，对应 Flutter lib/kernel/bridge_module.dart BridgeModule。
+ *
+ * JS 端职责：
+ * - 绑定一个 Bridge 实例（构造函数 BridgeModule(bridge: Bridge)）；
+ * - 暴露只读的 bridge getter。
+ *
+ * 方法暴露信息完全由装饰器 + MoonBridgeRegistry 负责，
+ * BridgeModule 本身不再提供 methodsToExport 等注册表接口。
+ *
+ * 使用方式：
+ * 1. 此类作为所有 MoonBridge 模块的基类
+ * 2. 使用 @MoonBridgeModule 装饰器来注册模块
+ * 3. 构造函数必须接收一个 Bridge 实例
+ *
+ * @example
+ * ```typescript
+ * @MoonBridgeModule('MyModule')
+ * class MyModule extends BridgeModule {
+ *   constructor(bridge: Bridge) {
+ *     super(bridge);
+ *   }
+ *
+ *   @MoonBridgeMethod('hello')
+ *   sayHello(): string {
+ *     return 'Hello!';
+ *   }
+ * }
+ * ```
+ */
+
+/**
+ * 自定义 module 基础类。
+ *
+ * @remarks
+ * 此类作为所有 MoonBridge 模块的基类，使用时需要：
+ * 1. 继承此类并实现具体模块逻辑
+ * 2. 使用 @MoonBridgeModule 装饰器注册模块
+ * 3. 构造函数必须调用 super(bridge) 传递 Bridge 实例
+ */
+declare class BridgeModule {
+    /** 绑定的 bridge 引用（WeakReference 在 JS 中用普通引用表达）。 */
+    private readonly _bridge;
+    /**
+     * 指定构造方法，并在这里传递绑定的 bridge 实例。
+     */
+    constructor(bridge: Bridge);
+    /**
+     * 获取绑定的 bridge 对象。
+     */
+    get bridge(): Bridge;
+}
+
+export { type Bridge as B, Executor as E, ModuleCreator as M, BridgeModule as a };

package/dist/bridge_module-Dd27cxv9.d.mts

@@ -0,0 +1,126 @@
+import { MessageParserManager } from './moonbridge/message/message_parser_manager.mjs';
+
+/**
+ * 消息执行器抽象接口，对应 Flutter lib/kernel/executor.dart Executor。
+ *
+ * Executor 绑定一个 Bridge 实例，并根据元数据执行指定模块中的方法。
+ */
+
+declare abstract class Executor {
+    /** 绑定的 bridge 引用（WeakReference 在 JS 中用普通引用表达）。 */
+    private readonly _bridge;
+    /**
+     * 指定构造方法，并在这里传递绑定的 bridge 实例。
+     */
+    protected constructor(bridge: Bridge);
+    /**
+     * 获取绑定的 bridge 对象。
+     */
+    get bridge(): Bridge;
+    /**
+     * 根据原数据 metaData 执行指定类中的指定方法，需要在子类中实现，
+     * 并返回最终执行结果：true 为执行成功，false 为执行失败。
+     */
+    abstract invokeMethod(metaData: unknown): boolean;
+}
+
+/**
+ * module 实例构造器，对应 Flutter lib/module/module_creator.dart。
+ *
+ * JS 端：通过 MoonBridgeRegistry 中已注册的模块构造函数创建实例，
+ * 不再依赖 ModuleFactory 列表。
+ */
+declare class ModuleCreator {
+    private readonly cacheMap;
+    /** JS 中没有 WeakReference 的通用实现，这里直接持有强引用。 */
+    private readonly _bridge;
+    constructor(bridge: Bridge);
+    /**
+     * 获取绑定的 bridge 对象。
+     */
+    get bridge(): Bridge;
+    /**
+     * 获取名为 name 的 module 实例。
+     *
+     * 创建流程：
+     * - 优先从本地缓存中读取；
+     * - 若无缓存，则从 MoonBridgeRegistry 中获取构造函数并创建实例；
+     * - 创建成功后写入缓存并返回。
+     */
+    getModule(name: string): BridgeModule | undefined;
+}
+
+/**
+ * 桥接接口抽象，对应 Flutter lib/kernel/bridge.dart Bridge。
+ *
+ * Bridge 负责提供：
+ * - 方法执行器 Executor；
+ * - module 实例构造器 ModuleCreator；
+ * - 消息解析器管理器 MessageParserManager。
+ *
+ * 具体实现由上层在 JS 端根据运行环境提供。
+ */
+
+interface Bridge {
+    /** 获取方法执行器 */
+    readonly executor: Executor;
+    /** 获取 module 实例构造器 */
+    readonly moduleCreator: ModuleCreator;
+    /** 获取消息解析器实例 */
+    readonly parserManager: MessageParserManager;
+}
+
+/**
+ * 自定义 module 基础类，对应 Flutter lib/kernel/bridge_module.dart BridgeModule。
+ *
+ * JS 端职责：
+ * - 绑定一个 Bridge 实例（构造函数 BridgeModule(bridge: Bridge)）；
+ * - 暴露只读的 bridge getter。
+ *
+ * 方法暴露信息完全由装饰器 + MoonBridgeRegistry 负责，
+ * BridgeModule 本身不再提供 methodsToExport 等注册表接口。
+ *
+ * 使用方式：
+ * 1. 此类作为所有 MoonBridge 模块的基类
+ * 2. 使用 @MoonBridgeModule 装饰器来注册模块
+ * 3. 构造函数必须接收一个 Bridge 实例
+ *
+ * @example
+ * ```typescript
+ * @MoonBridgeModule('MyModule')
+ * class MyModule extends BridgeModule {
+ *   constructor(bridge: Bridge) {
+ *     super(bridge);
+ *   }
+ *
+ *   @MoonBridgeMethod('hello')
+ *   sayHello(): string {
+ *     return 'Hello!';
+ *   }
+ * }
+ * ```
+ */
+
+/**
+ * 自定义 module 基础类。
+ *
+ * @remarks
+ * 此类作为所有 MoonBridge 模块的基类，使用时需要：
+ * 1. 继承此类并实现具体模块逻辑
+ * 2. 使用 @MoonBridgeModule 装饰器注册模块
+ * 3. 构造函数必须调用 super(bridge) 传递 Bridge 实例
+ */
+declare class BridgeModule {
+    /** 绑定的 bridge 引用（WeakReference 在 JS 中用普通引用表达）。 */
+    private readonly _bridge;
+    /**
+     * 指定构造方法，并在这里传递绑定的 bridge 实例。
+     */
+    constructor(bridge: Bridge);
+    /**
+     * 获取绑定的 bridge 对象。
+     */
+    get bridge(): Bridge;
+}
+
+export { type Bridge as B, Executor as E, ModuleCreator as M, BridgeModule as a };

package/dist/index.d.mts

@@ -0,0 +1,30 @@
+export { B as Bridge, a as BridgeModule } from './bridge_module-Dd27cxv9.mjs';
+export { MoonBridgeMethod, MoonBridgeModule } from './moonbridge/annotation/decorators.mjs';
+export { MethodSpec, ModuleConstructor, MoonBridgeRegistry } from './moonbridge/annotation/registry.mjs';
+export { LogLevel, LogSubscriber, Logger } from './moonbridge/logger/logger.mjs';
+export { MoonBridgeIpcClient, MoonBridgeIpcClientBuilder, MoonBridgeIpcClientRegistry } from './moonbridge-ipc/client/moonbridge_ipc_client.mjs';
+export { AppInstallationPath, AppLaunchIdentifier } from './moonbridge-ipc/general/app_launch/model/app_info.mjs';
+export { AppLaunchArguments, AppLaunchResult, emptyAppLaunchArguments } from './moonbridge-ipc/general/app_launch/model/app_launch_models.mjs';
+export { APP_NOT_INSTALLED, LAUNCH_TIMEOUT, PERMISSION_DENIED, UNKNOWN } from './moonbridge-ipc/general/app_launch/model/app_launch_error_codes.mjs';
+export { PortCandidateRule, maxAttemptsCap } from './moonbridge-ipc/general/config/port_candidate_rule.mjs';
+export { WebSocketServerEndpoint } from './moonbridge-ipc/general/config/websocket_server_endpoint.mjs';
+export { ServerAddressInfo, SocketServer, WebSocketServer } from './moonbridge-ipc/general/transport/websocket/websocket_server.mjs';
+export { IpcError } from './moonbridge-ipc/general/error/ipc_error.mjs';
+export { MessageType } from './moonbridge-ipc/general/message/constants/message_types.mjs';
+export { Event } from './moonbridge-ipc/general/message/event.mjs';
+export { DisconnectedCallback, IpcMessageReply, MessagePreprocessor, MoonBridgeIpcServer, MoonBridgeIpcServerBuilder, MoonBridgeIpcServerRegistry, OnMessageReceived, WakeAppInterceptor } from './moonbridge-ipc/server/moonbridge_ipc_server.mjs';
+export { ClientIdentity, ClientIdentityProvider } from './moonbridge-ipc/server/credential/client_identity.mjs';
+export { MessageCallOptions, MessageEndpoint, Messenger } from './moonbridge-ipc/client/types/ipc_messenger.mjs';
+export { EventBus, Subscriber } from './moonbridge-ipc/client/types/ipc_event_bus.mjs';
+export { IpcMessageStrategy } from './moonbridge-ipc/client/types/ipc_message_strategy.mjs';
+export { ConnectionObserver, IpcConnectionCompletionHandler, IpcErrorCallback, IpcResponseCallback, MessageInterceptor } from './moonbridge-ipc/client/types/ipc_types.mjs';
+export { BridgeModuleUtils } from './moonbridge-ipc/extension/bridge_extension.mjs';
+export { FallbackMethod, WpsAppLauncher, WpsAppLauncherOptions } from './wps-launcher/launcher/wps_app_launcher.mjs';
+import './moonbridge/message/message_parser_manager.mjs';
+import './moonbridge/message/message.mjs';
+import './moonbridge/message/message_parser.mjs';
+import './moonbridge-ipc/general/app_launch/app_launcher.mjs';
+import './moonbridge-ipc/general/transport/interface/serial_message_channel.mjs';
+import './moonbridge-ipc/general/message/request.mjs';
+import './moonbridge-ipc/general/message/response.mjs';
+import './moonbridge-ipc/general/message/error.mjs';

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './moonbridge';
+export * from './moonbridge-ipc';
+export * from './wps-launcher';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC"}