@motrix/mdxp 0.2.0 → 0.3.0

package/README.md

@@ -35,6 +35,9 @@ top of it.
 - **Platform RAL entry points.** `./node` and `./browser` install the matching
   `vscode-jsonrpc` runtime abstraction layer and re-export its transport classes,
   so you import everything — connection helper and reader/writer — from one place.
+- **One-call constructors.** `fromWebSocket`, `fromStdio`, and `fromWorker` build
+  a connection over a common transport in a single call; `createMdxpConnection`
+  stays the generic escape hatch.
 - **Agent-ready.** A built-in tool registry emits a JSON-Schema tool catalog you
   can feed straight into an LLM function-calling API.
 - **Forward-compatible.** Unknown methods and fields are ignored, not rejected.
@@ -75,16 +78,10 @@ including its reader/writer, from a single place.
 ### Node host (over stdio)
 
 ```ts
-import {
-  createMdxpConnection,
-  StreamMessageReader,
-  StreamMessageWriter,
-} from '@motrix/mdxp/node'
-
-const conn = createMdxpConnection(
-  new StreamMessageReader(process.stdin),
-  new StreamMessageWriter(process.stdout),
-)
+import { fromStdio } from '@motrix/mdxp/node'
+
+// Over process.stdin / process.stdout (the native-messaging / CLI case).
+const conn = fromStdio()
 
 // Register handlers BEFORE listen().
 conn.onNotification('$/task/progress', (p) => {
@@ -95,24 +92,31 @@ conn.onNotification('$/task/progress', (p) => {
 conn.listen()
 ```
 
-### Browser host
+### Browser host (over WebSocket)
 
 ```ts
-// Installs the browser RAL and re-exports the full API + transport classes.
-import {
-  createMdxpConnection,
-  BrowserMessageReader,
-  BrowserMessageWriter,
-} from '@motrix/mdxp/browser'
-
-// e.g. a MessagePort / Worker; adapt your WebSocket to reader/writer as needed.
-const conn = createMdxpConnection(
-  new BrowserMessageReader(worker),
-  new BrowserMessageWriter(worker),
-)
+import { fromWebSocket } from '@motrix/mdxp/browser'
+
+const conn = fromWebSocket(new WebSocket('ws://127.0.0.1:16650/v1'))
+conn.onNotification('$/task/progress', (p) => {})
 conn.listen()
 ```
 
+### Convenience constructors
+
+`createMdxpConnection(reader, writer)` is the generic entry point — bring any
+`vscode-jsonrpc` reader/writer. For the common transports, skip the boilerplate:
+
+| Constructor | Entry | Transport |
+| --- | --- | --- |
+| `fromWebSocket(ws)` | `./node` · `./browser` | A browser `WebSocket` or a Node `ws` socket |
+| `fromStdio(opts?)` | `./node` | `process.stdin` / `process.stdout`, or given streams |
+| `fromWorker(port)` | `./browser` | A `Worker` or `MessagePort` |
+
+Each returns a ready `MdxpConnection` — you still register handlers and call
+`listen()`. For any other transport, build the reader/writer and call
+`createMdxpConnection` directly.
+
 ## Core concepts
 
 **Server vs. client.** The Motrix desktop app is the **server** — it owns the
@@ -321,6 +325,7 @@ const tools = toAgentToolCatalog()
 | Export | Kind | Purpose |
 | --- | --- | --- |
 | `createMdxpConnection(reader, writer)` | function | Wrap a reader/writer pair in a typed `MdxpConnection`. |
+| `fromWebSocket` · `fromStdio` · `fromWorker` | function | One-call constructors over a WebSocket / stdio / Worker (from `./node` · `./browser`). |
 | `MdxpConnection` | type | The connection interface (`sendRequest`, `onRequest`, `sendNotification`, `onNotification`, `dispose`, `raw`). |
 | `MdxpRequestMap` / `MdxpNotificationMap` | type | Method/notification name → params/result type maps. |
 | `Methods` / `Notifications` | const | Wire-name constants (`Methods.DownloadAdd === 'download/add'`). |

package/README.zh-CN.md

@@ -30,6 +30,8 @@
 - **平台 RAL 入口**：`./node` 与 `./browser` 会替你装好对应的 `vscode-jsonrpc`
   runtime abstraction layer，并 re-export 它的 transport class —— 连接封装与
   reader/writer 都从同一处 import。
+- **一步构造**：`fromWebSocket`、`fromStdio`、`fromWorker` 一行即可在常见 transport
+  上建好连接；`createMdxpConnection` 仍是通用的底层入口。
 - **面向 agent**：内置的 tool registry 可产出一份 JSON-Schema tool catalog，
   能直接对接 LLM 的 function-calling API。
 - **forward-compatible**：遇到未知的 method 或字段选择忽略，而非 reject。
@@ -67,16 +69,10 @@ transport class**（Node 的 `StreamMessageReader`/`Writer`、浏览器的
 ### Node host（走 stdio）
 
 ```ts
-import {
-  createMdxpConnection,
-  StreamMessageReader,
-  StreamMessageWriter,
-} from '@motrix/mdxp/node'
-
-const conn = createMdxpConnection(
-  new StreamMessageReader(process.stdin),
-  new StreamMessageWriter(process.stdout),
-)
+import { fromStdio } from '@motrix/mdxp/node'
+
+// 走 process.stdin / process.stdout（native-messaging / CLI 场景）。
+const conn = fromStdio()
 
 // 务必在 listen() 之前注册 handler。
 conn.onNotification('$/task/progress', (p) => {
@@ -87,24 +83,30 @@ conn.onNotification('$/task/progress', (p) => {
 conn.listen()
 ```
 
-### 浏览器 host
+### 浏览器 host（走 WebSocket）
 
 ```ts
-// 装好 browser RAL，并 re-export 全量 API + transport class。
-import {
-  createMdxpConnection,
-  BrowserMessageReader,
-  BrowserMessageWriter,
-} from '@motrix/mdxp/browser'
-
-// 例如一个 MessagePort / Worker；若用 WebSocket，需自行适配成 reader/writer。
-const conn = createMdxpConnection(
-  new BrowserMessageReader(worker),
-  new BrowserMessageWriter(worker),
-)
+import { fromWebSocket } from '@motrix/mdxp/browser'
+
+const conn = fromWebSocket(new WebSocket('ws://127.0.0.1:16650/v1'))
+conn.onNotification('$/task/progress', (p) => {})
 conn.listen()
 ```
 
+### 便捷构造器
+
+`createMdxpConnection(reader, writer)` 是通用入口 —— 传入任意 `vscode-jsonrpc` 的
+reader/writer。常见 transport 则可直接省去样板：
+
+| 构造器 | 入口 | Transport |
+| --- | --- | --- |
+| `fromWebSocket(ws)` | `./node` · `./browser` | 浏览器 `WebSocket` 或 Node 的 `ws` socket |
+| `fromStdio(opts?)` | `./node` | `process.stdin` / `process.stdout`，或指定的流 |
+| `fromWorker(port)` | `./browser` | 一个 `Worker` 或 `MessagePort` |
+
+每个都返回开箱即用的 `MdxpConnection` —— 你仍需注册 handler 并调用 `listen()`。
+其它 transport 则自行构造 reader/writer，再直接调用 `createMdxpConnection`。
+
 ## 核心概念
 
 **server 与 client**：Motrix 桌面端是 **server** —— 下载引擎由它持有。**client**
@@ -305,6 +307,7 @@ const tools = toAgentToolCatalog()
 | 导出 | 类型 | 作用 |
 | --- | --- | --- |
 | `createMdxpConnection(reader, writer)` | function | 把一对 reader/writer 封装成类型化的 `MdxpConnection`。 |
+| `fromWebSocket` · `fromStdio` · `fromWorker` | function | 在 WebSocket / stdio / Worker 上的一步构造器（来自 `./node` · `./browser`）。 |
 | `MdxpConnection` | type | 连接接口（`sendRequest`、`onRequest`、`sendNotification`、`onNotification`、`dispose`、`raw`）。 |
 | `MdxpRequestMap` / `MdxpNotificationMap` | type | method / notification 名 → params/result 类型的映射表。 |
 | `Methods` / `Notifications` | const | wire 名常量（`Methods.DownloadAdd === 'download/add'`）。 |

package/dist/browser.d.ts

@@ -1,4 +1,8 @@
 import 'vscode-jsonrpc/browser';
 export { BrowserMessageReader, BrowserMessageWriter, } from 'vscode-jsonrpc/browser';
 export * from './index.js';
+export type { WorkerLike } from './transports/worker.js';
+export { fromWorker } from './transports/worker.js';
+export type { WebSocketLike } from './transports/ws.js';
+export { fromWebSocket } from './transports/ws.js';
 //# sourceMappingURL=browser.d.ts.map

package/dist/browser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAWA,OAAO,wBAAwB,CAAA;AAM/B,OAAO,EACL,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,wBAAwB,CAAA;AAC/B,cAAc,YAAY,CAAA"}
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAWA,OAAO,wBAAwB,CAAA;AAM/B,OAAO,EACL,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,wBAAwB,CAAA;AAC/B,cAAc,YAAY,CAAA;AAC1B,YAAY,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AACnD,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAEvD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA"}

package/dist/browser.js

@@ -16,4 +16,7 @@ import 'vscode-jsonrpc/browser';
 // installed the RAL into.
 export { BrowserMessageReader, BrowserMessageWriter, } from 'vscode-jsonrpc/browser';
 export * from './index.js';
+export { fromWorker } from './transports/worker.js';
+// High-level convenience constructors for browser transports.
+export { fromWebSocket } from './transports/ws.js';
 //# sourceMappingURL=browser.js.map

package/dist/browser.js.map

@@ -1 +1 @@
-{"version":3,"file":"browser.js","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA,0BAA0B;AAC1B,EAAE;AACF,8EAA8E;AAC9E,0EAA0E;AAC1E,gFAAgF;AAChF,8EAA8E;AAC9E,mCAAmC;AACnC,EAAE;AACF,uEAAuE;AACvE,iFAAiF;AACjF,4EAA4E;AAC5E,OAAO,wBAAwB,CAAA;AAE/B,uEAAuE;AACvE,4EAA4E;AAC5E,0EAA0E;AAC1E,0BAA0B;AAC1B,OAAO,EACL,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,wBAAwB,CAAA;AAC/B,cAAc,YAAY,CAAA"}
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA,0BAA0B;AAC1B,EAAE;AACF,8EAA8E;AAC9E,0EAA0E;AAC1E,gFAAgF;AAChF,8EAA8E;AAC9E,mCAAmC;AACnC,EAAE;AACF,uEAAuE;AACvE,iFAAiF;AACjF,4EAA4E;AAC5E,OAAO,wBAAwB,CAAA;AAE/B,uEAAuE;AACvE,4EAA4E;AAC5E,0EAA0E;AAC1E,0BAA0B;AAC1B,OAAO,EACL,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,wBAAwB,CAAA;AAC/B,cAAc,YAAY,CAAA;AAE1B,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AAEnD,8DAA8D;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA"}

package/dist/node.d.ts

@@ -1,4 +1,8 @@
 import 'vscode-jsonrpc/node';
 export { IPCMessageReader, IPCMessageWriter, PortMessageReader, PortMessageWriter, SocketMessageReader, SocketMessageWriter, StreamMessageReader, StreamMessageWriter, } from 'vscode-jsonrpc/node';
 export * from './index.js';
+export type { StdioOptions } from './transports/stdio.js';
+export { fromStdio } from './transports/stdio.js';
+export type { WebSocketLike } from './transports/ws.js';
+export { fromWebSocket } from './transports/ws.js';
 //# sourceMappingURL=node.d.ts.map

package/dist/node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAYA,OAAO,qBAAqB,CAAA;AAK5B,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,qBAAqB,CAAA;AAC5B,cAAc,YAAY,CAAA"}
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAYA,OAAO,qBAAqB,CAAA;AAK5B,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,qBAAqB,CAAA;AAC5B,cAAc,YAAY,CAAA;AAC1B,YAAY,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAEzD,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AACjD,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA"}

package/dist/node.js

@@ -16,4 +16,7 @@ import 'vscode-jsonrpc/node';
 // import, and guaranteed to be the instance this package installed the RAL into.
 export { IPCMessageReader, IPCMessageWriter, PortMessageReader, PortMessageWriter, SocketMessageReader, SocketMessageWriter, StreamMessageReader, StreamMessageWriter, } from 'vscode-jsonrpc/node';
 export * from './index.js';
+// High-level convenience constructors for Node transports.
+export { fromStdio } from './transports/stdio.js';
+export { fromWebSocket } from './transports/ws.js';
 //# sourceMappingURL=node.js.map

package/dist/node.js.map

@@ -1 +1 @@
-{"version":3,"file":"node.js","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA,uBAAuB;AACvB,EAAE;AACF,8EAA8E;AAC9E,0EAA0E;AAC1E,gFAAgF;AAChF,2EAA2E;AAC3E,gFAAgF;AAChF,4BAA4B;AAC5B,EAAE;AACF,mFAAmF;AACnF,4EAA4E;AAC5E,yEAAyE;AACzE,OAAO,qBAAqB,CAAA;AAE5B,+EAA+E;AAC/E,+EAA+E;AAC/E,iFAAiF;AACjF,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,qBAAqB,CAAA;AAC5B,cAAc,YAAY,CAAA"}
+{"version":3,"file":"node.js","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA,uBAAuB;AACvB,EAAE;AACF,8EAA8E;AAC9E,0EAA0E;AAC1E,gFAAgF;AAChF,2EAA2E;AAC3E,gFAAgF;AAChF,4BAA4B;AAC5B,EAAE;AACF,mFAAmF;AACnF,4EAA4E;AAC5E,yEAAyE;AACzE,OAAO,qBAAqB,CAAA;AAE5B,+EAA+E;AAC/E,+EAA+E;AAC/E,iFAAiF;AACjF,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,qBAAqB,CAAA;AAC5B,cAAc,YAAY,CAAA;AAE1B,2DAA2D;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AAEjD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA"}

package/dist/transports/stdio.d.ts

@@ -0,0 +1,19 @@
+import type { MdxpConnection } from '../connection.js';
+/** Streams for {@link fromStdio}; defaults to the process's stdio. */
+export interface StdioOptions {
+    input?: NodeJS.ReadableStream;
+    output?: NodeJS.WritableStream;
+}
+/**
+ * Create an {@link MdxpConnection} over Node streams — `process.stdin` /
+ * `process.stdout` by default. This is the native-messaging-host / CLI case:
+ * the parent process pipes JSON-RPC over the child's stdio.
+ *
+ * ```ts
+ * const conn = fromStdio()
+ * conn.onRequest('url/resolve', async (params) => {})
+ * conn.listen()
+ * ```
+ */
+export declare function fromStdio(options?: StdioOptions): MdxpConnection;
+//# sourceMappingURL=stdio.d.ts.map

package/dist/transports/stdio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.d.ts","sourceRoot":"","sources":["../../src/transports/stdio.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAGtD,sEAAsE;AACtE,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC,cAAc,CAAA;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC,cAAc,CAAA;CAC/B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,OAAO,GAAE,YAAiB,GAAG,cAAc,CAKpE"}

package/dist/transports/stdio.js

@@ -0,0 +1,17 @@
+import { StreamMessageReader, StreamMessageWriter } from 'vscode-jsonrpc/node';
+import { createMdxpConnection } from '../connection.js';
+/**
+ * Create an {@link MdxpConnection} over Node streams — `process.stdin` /
+ * `process.stdout` by default. This is the native-messaging-host / CLI case:
+ * the parent process pipes JSON-RPC over the child's stdio.
+ *
+ * ```ts
+ * const conn = fromStdio()
+ * conn.onRequest('url/resolve', async (params) => {})
+ * conn.listen()
+ * ```
+ */
+export function fromStdio(options = {}) {
+    return createMdxpConnection(new StreamMessageReader(options.input ?? process.stdin), new StreamMessageWriter(options.output ?? process.stdout));
+}
+//# sourceMappingURL=stdio.js.map

package/dist/transports/stdio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.js","sourceRoot":"","sources":["../../src/transports/stdio.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAE9E,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AAQvD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,SAAS,CAAC,UAAwB,EAAE;IAClD,OAAO,oBAAoB,CACzB,IAAI,mBAAmB,CAAC,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC,EACvD,IAAI,mBAAmB,CAAC,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,CAC1D,CAAA;AACH,CAAC"}

package/dist/transports/worker.d.ts

@@ -0,0 +1,27 @@
+import type { MdxpConnection } from '../connection.js';
+/**
+ * Minimal structural subset of a `MessagePort` / `Worker` /
+ * `DedicatedWorkerGlobalScope` — anything the browser RAL's reader/writer
+ * accept. Consumers pass their worker or port as-is.
+ */
+export interface WorkerLike {
+    postMessage(message: unknown): void;
+    addEventListener(type: 'message', listener: (event: {
+        readonly data: unknown;
+    }) => void): void;
+    removeEventListener(type: 'message', listener: (event: {
+        readonly data: unknown;
+    }) => void): void;
+}
+/**
+ * Create an {@link MdxpConnection} over a Worker or `MessagePort` (the browser
+ * `postMessage` transport).
+ *
+ * ```ts
+ * const conn = fromWorker(self) // inside a Web Worker
+ * conn.onNotification('$/task/progress', (p) => {})
+ * conn.listen()
+ * ```
+ */
+export declare function fromWorker(port: WorkerLike): MdxpConnection;
+//# sourceMappingURL=worker.d.ts.map

package/dist/transports/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../src/transports/worker.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAGtD;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAA;IACnC,gBAAgB,CACd,IAAI,EAAE,SAAS,EACf,QAAQ,EAAE,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,GACpD,IAAI,CAAA;IACP,mBAAmB,CACjB,IAAI,EAAE,SAAS,EACf,QAAQ,EAAE,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,GACpD,IAAI,CAAA;CACR;AAaD;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,cAAc,CAE3D"}

package/dist/transports/worker.js

@@ -0,0 +1,22 @@
+import { BrowserMessageReader, BrowserMessageWriter, } from 'vscode-jsonrpc/browser';
+import { createMdxpConnection } from '../connection.js';
+// vscode-jsonrpc types the port as `MessagePort | Worker | DedicatedWorkerGlobalScope`,
+// which are DOM / WebWorker globals. This package targets `lib: ES2022` (no DOM),
+// so re-type the constructors against the structural `WorkerLike` instead of
+// pulling the DOM libs into every consumer.
+const Reader = BrowserMessageReader;
+const Writer = BrowserMessageWriter;
+/**
+ * Create an {@link MdxpConnection} over a Worker or `MessagePort` (the browser
+ * `postMessage` transport).
+ *
+ * ```ts
+ * const conn = fromWorker(self) // inside a Web Worker
+ * conn.onNotification('$/task/progress', (p) => {})
+ * conn.listen()
+ * ```
+ */
+export function fromWorker(port) {
+    return createMdxpConnection(new Reader(port), new Writer(port));
+}
+//# sourceMappingURL=worker.js.map

package/dist/transports/worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.js","sourceRoot":"","sources":["../../src/transports/worker.ts"],"names":[],"mappings":"AACA,OAAO,EACL,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,wBAAwB,CAAA;AAE/B,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AAmBvD,wFAAwF;AACxF,kFAAkF;AAClF,6EAA6E;AAC7E,4CAA4C;AAC5C,MAAM,MAAM,GAAG,oBAEG,CAAA;AAClB,MAAM,MAAM,GAAG,oBAEG,CAAA;AAElB;;;;;;;;;GASG;AACH,MAAM,UAAU,UAAU,CAAC,IAAgB;IACzC,OAAO,oBAAoB,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAA;AACjE,CAAC"}

package/dist/transports/ws.d.ts

@@ -0,0 +1,35 @@
+import type { MdxpConnection } from '../connection.js';
+/**
+ * Minimal structural subset of a WebSocket shared by the browser `WebSocket`
+ * and the Node [`ws`](https://www.npmjs.com/package/ws) package. Consumers pass
+ * their socket as-is — no wrapping required.
+ */
+export interface WebSocketLike {
+    readonly readyState: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: 'message' | 'close' | 'error', listener: (event: {
+        readonly data?: unknown;
+    }) => void): void;
+    removeEventListener(type: 'message' | 'close' | 'error', listener: (event: {
+        readonly data?: unknown;
+    }) => void): void;
+}
+/**
+ * Create an {@link MdxpConnection} over a WebSocket.
+ *
+ * Each WebSocket message carries exactly one complete JSON-RPC 2.0 message —
+ * the WebSocket protocol already frames messages, so there is no Content-Length
+ * framing. Works with the browser `WebSocket` and the Node `ws` package alike
+ * (both satisfy {@link WebSocketLike}).
+ *
+ * Register handlers first, then call `listen()`:
+ *
+ * ```ts
+ * const conn = fromWebSocket(ws)
+ * conn.onNotification('$/task/progress', (p) => {})
+ * conn.listen()
+ * ```
+ */
+export declare function fromWebSocket(ws: WebSocketLike): MdxpConnection;
+//# sourceMappingURL=ws.d.ts.map

package/dist/transports/ws.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws.d.ts","sourceRoot":"","sources":["../../src/transports/ws.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAMtD;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3C,gBAAgB,CACd,IAAI,EAAE,SAAS,GAAG,OAAO,GAAG,OAAO,EACnC,QAAQ,EAAE,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,GACrD,IAAI,CAAA;IACP,mBAAmB,CACjB,IAAI,EAAE,SAAS,GAAG,OAAO,GAAG,OAAO,EACnC,QAAQ,EAAE,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,GACrD,IAAI,CAAA;CACR;AAsID;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,aAAa,GAAG,cAAc,CAK/D"}

package/dist/transports/ws.js

@@ -0,0 +1,144 @@
+import { Emitter } from 'vscode-jsonrpc';
+import { createMdxpConnection } from '../connection.js';
+/** `WebSocket.readyState` value for an open socket (browser and `ws` agree). */
+const OPEN = 1;
+function toText(data) {
+    if (typeof data === 'string')
+        return data;
+    if (data instanceof ArrayBuffer)
+        return new TextDecoder().decode(data);
+    // A typed array / DataView / Node Buffer. TS 6's generic `ArrayBufferView`
+    // typing is stricter than `TextDecoder.decode`'s runtime contract (which
+    // accepts any view), so widen to satisfy the compiler.
+    if (ArrayBuffer.isView(data)) {
+        return new TextDecoder().decode(data);
+    }
+    throw new Error('unsupported WebSocket message data type');
+}
+class WebSocketMessageReader {
+    ws;
+    errorEmitter = new Emitter();
+    closeEmitter = new Emitter();
+    partialEmitter = new Emitter();
+    callback = null;
+    attached = false;
+    constructor(ws) {
+        this.ws = ws;
+    }
+    get onError() {
+        return this.errorEmitter.event;
+    }
+    get onClose() {
+        return this.closeEmitter.event;
+    }
+    get onPartialMessage() {
+        return this.partialEmitter.event;
+    }
+    onMessage = (event) => {
+        if (!this.callback)
+            return;
+        let message;
+        try {
+            message = JSON.parse(toText(event.data));
+        }
+        catch (error) {
+            this.errorEmitter.fire(error instanceof Error ? error : new Error(String(error)));
+            return;
+        }
+        this.callback(message);
+    };
+    onCloseEvent = () => {
+        this.closeEmitter.fire(undefined);
+    };
+    onErrorEvent = () => {
+        this.errorEmitter.fire(new Error('WebSocket error'));
+    };
+    listen(callback) {
+        if (this.attached) {
+            throw new Error('WebSocketMessageReader is already listening');
+        }
+        this.callback = callback;
+        this.ws.addEventListener('message', this.onMessage);
+        this.ws.addEventListener('close', this.onCloseEvent);
+        this.ws.addEventListener('error', this.onErrorEvent);
+        this.attached = true;
+        return { dispose: () => this.dispose() };
+    }
+    dispose() {
+        if (!this.attached)
+            return;
+        this.ws.removeEventListener('message', this.onMessage);
+        this.ws.removeEventListener('close', this.onCloseEvent);
+        this.ws.removeEventListener('error', this.onErrorEvent);
+        this.attached = false;
+        this.callback = null;
+        this.errorEmitter.dispose();
+        this.closeEmitter.dispose();
+        this.partialEmitter.dispose();
+    }
+}
+class WebSocketMessageWriter {
+    ws;
+    errorEmitter = new Emitter();
+    closeEmitter = new Emitter();
+    attached = false;
+    onCloseEvent = () => {
+        this.closeEmitter.fire(undefined);
+    };
+    constructor(ws) {
+        this.ws = ws;
+        this.ws.addEventListener('close', this.onCloseEvent);
+        this.attached = true;
+    }
+    get onError() {
+        return this.errorEmitter.event;
+    }
+    get onClose() {
+        return this.closeEmitter.event;
+    }
+    async write(message) {
+        if (this.ws.readyState !== OPEN) {
+            throw new Error(`WebSocket is not open (readyState=${this.ws.readyState})`);
+        }
+        try {
+            this.ws.send(JSON.stringify(message));
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            this.errorEmitter.fire([err, message, undefined]);
+            throw err;
+        }
+    }
+    end() {
+        if (this.ws.readyState === OPEN)
+            this.ws.close();
+    }
+    dispose() {
+        if (!this.attached)
+            return;
+        this.ws.removeEventListener('close', this.onCloseEvent);
+        this.attached = false;
+        this.errorEmitter.dispose();
+        this.closeEmitter.dispose();
+    }
+}
+/**
+ * Create an {@link MdxpConnection} over a WebSocket.
+ *
+ * Each WebSocket message carries exactly one complete JSON-RPC 2.0 message —
+ * the WebSocket protocol already frames messages, so there is no Content-Length
+ * framing. Works with the browser `WebSocket` and the Node `ws` package alike
+ * (both satisfy {@link WebSocketLike}).
+ *
+ * Register handlers first, then call `listen()`:
+ *
+ * ```ts
+ * const conn = fromWebSocket(ws)
+ * conn.onNotification('$/task/progress', (p) => {})
+ * conn.listen()
+ * ```
+ */
+export function fromWebSocket(ws) {
+    return createMdxpConnection(new WebSocketMessageReader(ws), new WebSocketMessageWriter(ws));
+}
+//# sourceMappingURL=ws.js.map

package/dist/transports/ws.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws.js","sourceRoot":"","sources":["../../src/transports/ws.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motrix/mdxp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Motrix Download eXchange Protocol — JSON-RPC 2.0 wire types and connection helpers",
   "license": "MIT",
   "author": "Motrix",

package/src/browser.ts

@@ -20,3 +20,8 @@ export {
   BrowserMessageWriter,
 } from 'vscode-jsonrpc/browser'
 export * from './index.js'
+export type { WorkerLike } from './transports/worker.js'
+export { fromWorker } from './transports/worker.js'
+export type { WebSocketLike } from './transports/ws.js'
+// High-level convenience constructors for browser transports.
+export { fromWebSocket } from './transports/ws.js'

package/src/node.ts

@@ -26,3 +26,8 @@ export {
   StreamMessageWriter,
 } from 'vscode-jsonrpc/node'
 export * from './index.js'
+export type { StdioOptions } from './transports/stdio.js'
+// High-level convenience constructors for Node transports.
+export { fromStdio } from './transports/stdio.js'
+export type { WebSocketLike } from './transports/ws.js'
+export { fromWebSocket } from './transports/ws.js'

package/src/transports/stdio.ts

@@ -0,0 +1,27 @@
+import { StreamMessageReader, StreamMessageWriter } from 'vscode-jsonrpc/node'
+import type { MdxpConnection } from '../connection.js'
+import { createMdxpConnection } from '../connection.js'
+
+/** Streams for {@link fromStdio}; defaults to the process's stdio. */
+export interface StdioOptions {
+  input?: NodeJS.ReadableStream
+  output?: NodeJS.WritableStream
+}
+
+/**
+ * Create an {@link MdxpConnection} over Node streams — `process.stdin` /
+ * `process.stdout` by default. This is the native-messaging-host / CLI case:
+ * the parent process pipes JSON-RPC over the child's stdio.
+ *
+ * ```ts
+ * const conn = fromStdio()
+ * conn.onRequest('url/resolve', async (params) => {})
+ * conn.listen()
+ * ```
+ */
+export function fromStdio(options: StdioOptions = {}): MdxpConnection {
+  return createMdxpConnection(
+    new StreamMessageReader(options.input ?? process.stdin),
+    new StreamMessageWriter(options.output ?? process.stdout)
+  )
+}

package/src/transports/worker.ts

@@ -0,0 +1,49 @@
+import type { MessageReader, MessageWriter } from 'vscode-jsonrpc'
+import {
+  BrowserMessageReader,
+  BrowserMessageWriter,
+} from 'vscode-jsonrpc/browser'
+import type { MdxpConnection } from '../connection.js'
+import { createMdxpConnection } from '../connection.js'
+
+/**
+ * Minimal structural subset of a `MessagePort` / `Worker` /
+ * `DedicatedWorkerGlobalScope` — anything the browser RAL's reader/writer
+ * accept. Consumers pass their worker or port as-is.
+ */
+export interface WorkerLike {
+  postMessage(message: unknown): void
+  addEventListener(
+    type: 'message',
+    listener: (event: { readonly data: unknown }) => void
+  ): void
+  removeEventListener(
+    type: 'message',
+    listener: (event: { readonly data: unknown }) => void
+  ): void
+}
+
+// vscode-jsonrpc types the port as `MessagePort | Worker | DedicatedWorkerGlobalScope`,
+// which are DOM / WebWorker globals. This package targets `lib: ES2022` (no DOM),
+// so re-type the constructors against the structural `WorkerLike` instead of
+// pulling the DOM libs into every consumer.
+const Reader = BrowserMessageReader as unknown as new (
+  port: WorkerLike
+) => MessageReader
+const Writer = BrowserMessageWriter as unknown as new (
+  port: WorkerLike
+) => MessageWriter
+
+/**
+ * Create an {@link MdxpConnection} over a Worker or `MessagePort` (the browser
+ * `postMessage` transport).
+ *
+ * ```ts
+ * const conn = fromWorker(self) // inside a Web Worker
+ * conn.onNotification('$/task/progress', (p) => {})
+ * conn.listen()
+ * ```
+ */
+export function fromWorker(port: WorkerLike): MdxpConnection {
+  return createMdxpConnection(new Reader(port), new Writer(port))
+}

package/src/transports/ws.ts

@@ -0,0 +1,188 @@
+import type {
+  DataCallback,
+  Disposable,
+  Message,
+  MessageReader,
+  MessageWriter,
+  PartialMessageInfo,
+} from 'vscode-jsonrpc'
+import { Emitter } from 'vscode-jsonrpc'
+import type { MdxpConnection } from '../connection.js'
+import { createMdxpConnection } from '../connection.js'
+
+/** `WebSocket.readyState` value for an open socket (browser and `ws` agree). */
+const OPEN = 1
+
+/**
+ * Minimal structural subset of a WebSocket shared by the browser `WebSocket`
+ * and the Node [`ws`](https://www.npmjs.com/package/ws) package. Consumers pass
+ * their socket as-is — no wrapping required.
+ */
+export interface WebSocketLike {
+  readonly readyState: number
+  send(data: string): void
+  close(code?: number, reason?: string): void
+  addEventListener(
+    type: 'message' | 'close' | 'error',
+    listener: (event: { readonly data?: unknown }) => void
+  ): void
+  removeEventListener(
+    type: 'message' | 'close' | 'error',
+    listener: (event: { readonly data?: unknown }) => void
+  ): void
+}
+
+function toText(data: unknown): string {
+  if (typeof data === 'string') return data
+  if (data instanceof ArrayBuffer) return new TextDecoder().decode(data)
+  // A typed array / DataView / Node Buffer. TS 6's generic `ArrayBufferView`
+  // typing is stricter than `TextDecoder.decode`'s runtime contract (which
+  // accepts any view), so widen to satisfy the compiler.
+  if (ArrayBuffer.isView(data)) {
+    return new TextDecoder().decode(data as unknown as Uint8Array)
+  }
+  throw new Error('unsupported WebSocket message data type')
+}
+
+class WebSocketMessageReader implements MessageReader {
+  private readonly errorEmitter = new Emitter<Error>()
+  private readonly closeEmitter = new Emitter<void>()
+  private readonly partialEmitter = new Emitter<PartialMessageInfo>()
+  private callback: DataCallback | null = null
+  private attached = false
+
+  constructor(private readonly ws: WebSocketLike) {}
+
+  get onError() {
+    return this.errorEmitter.event
+  }
+
+  get onClose() {
+    return this.closeEmitter.event
+  }
+
+  get onPartialMessage() {
+    return this.partialEmitter.event
+  }
+
+  private readonly onMessage = (event: { readonly data?: unknown }): void => {
+    if (!this.callback) return
+    let message: Message
+    try {
+      message = JSON.parse(toText(event.data)) as Message
+    } catch (error) {
+      this.errorEmitter.fire(
+        error instanceof Error ? error : new Error(String(error))
+      )
+      return
+    }
+    this.callback(message)
+  }
+
+  private readonly onCloseEvent = (): void => {
+    this.closeEmitter.fire(undefined)
+  }
+
+  private readonly onErrorEvent = (): void => {
+    this.errorEmitter.fire(new Error('WebSocket error'))
+  }
+
+  listen(callback: DataCallback): Disposable {
+    if (this.attached) {
+      throw new Error('WebSocketMessageReader is already listening')
+    }
+    this.callback = callback
+    this.ws.addEventListener('message', this.onMessage)
+    this.ws.addEventListener('close', this.onCloseEvent)
+    this.ws.addEventListener('error', this.onErrorEvent)
+    this.attached = true
+    return { dispose: () => this.dispose() }
+  }
+
+  dispose(): void {
+    if (!this.attached) return
+    this.ws.removeEventListener('message', this.onMessage)
+    this.ws.removeEventListener('close', this.onCloseEvent)
+    this.ws.removeEventListener('error', this.onErrorEvent)
+    this.attached = false
+    this.callback = null
+    this.errorEmitter.dispose()
+    this.closeEmitter.dispose()
+    this.partialEmitter.dispose()
+  }
+}
+
+class WebSocketMessageWriter implements MessageWriter {
+  private readonly errorEmitter = new Emitter<
+    [Error, Message | undefined, number | undefined]
+  >()
+  private readonly closeEmitter = new Emitter<void>()
+  private attached = false
+
+  private readonly onCloseEvent = (): void => {
+    this.closeEmitter.fire(undefined)
+  }
+
+  constructor(private readonly ws: WebSocketLike) {
+    this.ws.addEventListener('close', this.onCloseEvent)
+    this.attached = true
+  }
+
+  get onError() {
+    return this.errorEmitter.event
+  }
+
+  get onClose() {
+    return this.closeEmitter.event
+  }
+
+  async write(message: Message): Promise<void> {
+    if (this.ws.readyState !== OPEN) {
+      throw new Error(
+        `WebSocket is not open (readyState=${this.ws.readyState})`
+      )
+    }
+    try {
+      this.ws.send(JSON.stringify(message))
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error))
+      this.errorEmitter.fire([err, message, undefined])
+      throw err
+    }
+  }
+
+  end(): void {
+    if (this.ws.readyState === OPEN) this.ws.close()
+  }
+
+  dispose(): void {
+    if (!this.attached) return
+    this.ws.removeEventListener('close', this.onCloseEvent)
+    this.attached = false
+    this.errorEmitter.dispose()
+    this.closeEmitter.dispose()
+  }
+}
+
+/**
+ * Create an {@link MdxpConnection} over a WebSocket.
+ *
+ * Each WebSocket message carries exactly one complete JSON-RPC 2.0 message —
+ * the WebSocket protocol already frames messages, so there is no Content-Length
+ * framing. Works with the browser `WebSocket` and the Node `ws` package alike
+ * (both satisfy {@link WebSocketLike}).
+ *
+ * Register handlers first, then call `listen()`:
+ *
+ * ```ts
+ * const conn = fromWebSocket(ws)
+ * conn.onNotification('$/task/progress', (p) => {})
+ * conn.listen()
+ * ```
+ */
+export function fromWebSocket(ws: WebSocketLike): MdxpConnection {
+  return createMdxpConnection(
+    new WebSocketMessageReader(ws),
+    new WebSocketMessageWriter(ws)
+  )
+}