@motrix/mdxp 0.1.1 → 0.3.0

package/README.md

@@ -33,7 +33,11 @@ top of it.
 - **Transport-agnostic.** Works over anything that implements
   `MessageReader`/`MessageWriter`.
 - **Platform RAL entry points.** `./node` and `./browser` install the matching
-  `vscode-jsonrpc` runtime abstraction layer for you.
+  `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.
@@ -46,10 +50,11 @@ npm install @motrix/mdxp
 ```
 
 Runtime dependency: [`vscode-jsonrpc`](https://www.npmjs.com/package/vscode-jsonrpc)
-`^9`, a direct dependency installed alongside this package. The examples below
-also import reader/writer classes straight from `vscode-jsonrpc/node` and
-`vscode-jsonrpc/browser`; if you do the same, declare `vscode-jsonrpc` in your
-own dependencies rather than relying on hoisting. ESM-only; requires
+`^9`, installed alongside this package. Its transport classes (reader/writer)
+and the primitives that surface in this package's API — `MessageReader`,
+`MessageConnection`, `CancellationToken`, `CancellationTokenSource`, … — are
+re-exported from `@motrix/mdxp` (see [Entry points](#entry-points)), so you
+rarely need to import `vscode-jsonrpc` directly. ESM-only; requires
 Node.js ≥ 18 or a modern bundler.
 
 ### Entry points
@@ -63,21 +68,20 @@ Node.js ≥ 18 or a modern bundler.
 `vscode-jsonrpc` v9 requires a runtime abstraction layer (RAL) to be installed
 before a connection can be created. Importing `@motrix/mdxp/node` or
 `@motrix/mdxp/browser` installs the right one into the **same** `vscode-jsonrpc`
-instance this package uses, and re-exports the entire public API — so a host
-imports everything from a single place.
+instance this package uses, and re-exports the entire public API **plus that
+platform's transport classes** (`StreamMessageReader`/`Writer` for Node,
+`BrowserMessageReader`/`Writer` for the browser) — so a host imports everything,
+including its reader/writer, from a single place.
 
 ## Quick start
 
 ### Node host (over stdio)
 
 ```ts
-import { createMdxpConnection } from '@motrix/mdxp/node'
-import { StreamMessageReader, StreamMessageWriter } from 'vscode-jsonrpc/node'
+import { fromStdio } from '@motrix/mdxp/node'
 
-const conn = createMdxpConnection(
-  new StreamMessageReader(process.stdin),
-  new StreamMessageWriter(process.stdout),
-)
+// Over process.stdin / process.stdout (the native-messaging / CLI case).
+const conn = fromStdio()
 
 // Register handlers BEFORE listen().
 conn.onNotification('$/task/progress', (p) => {
@@ -88,21 +92,31 @@ conn.onNotification('$/task/progress', (p) => {
 conn.listen()
 ```
 
-### Browser host
+### Browser host (over WebSocket)
 
 ```ts
-// Installs the browser RAL, then re-exports the full API.
-import { createMdxpConnection } from '@motrix/mdxp/browser'
-import { BrowserMessageReader, BrowserMessageWriter } from 'vscode-jsonrpc/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
@@ -245,7 +259,7 @@ conn.onNotification('$/task/error', (p) => {
 handler observes `token.isCancellationRequested`.
 
 ```ts
-import { CancellationTokenSource } from 'vscode-jsonrpc'
+import { CancellationTokenSource } from '@motrix/mdxp'
 
 const cts = new CancellationTokenSource()
 const pending = conn.sendRequest('url/resolve', { url }, cts.token)
@@ -311,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'`). |
@@ -321,6 +336,7 @@ const tools = toAgentToolCatalog()
 | `toAgentToolCatalog()` | function | The `agentFacing` subset as JSON-Schema tools. |
 | `SERVER_INITIATED_METHODS` | const | Methods the server calls on the client (`url/probe`, `url/resolve`). |
 | `*Schema` | Zod schema | Every wire shape, for runtime validation. |
+| `MessageReader` · `MessageWriter` · `MessageConnection` · `CancellationToken` · `CancellationTokenSource` · `Disposable` | re-export | `vscode-jsonrpc` primitives used across the API. Platform transport classes (`StreamMessageReader`/`Writer`, `BrowserMessageReader`/`Writer`) are re-exported from `./node` and `./browser`. |
 
 ### Methods
 

package/README.zh-CN.md

@@ -28,7 +28,10 @@
   调用处无需任何 cast。
 - **transport-agnostic**：只要实现了 `MessageReader`/`MessageWriter`，任何双工流都能用。
 - **平台 RAL 入口**：`./node` 与 `./browser` 会替你装好对应的 `vscode-jsonrpc`
-  runtime abstraction layer。
+  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。
@@ -41,10 +44,11 @@ npm install @motrix/mdxp
 ```
 
 运行时依赖：[`vscode-jsonrpc`](https://www.npmjs.com/package/vscode-jsonrpc)
-`^9`，是本包的直接 `dependency`，会随本包一并装上。下面的示例还直接从
-`vscode-jsonrpc/node` 和 `vscode-jsonrpc/browser` import reader/writer 类；若你也
-这样用，请在自己的 dependencies 里显式声明 `vscode-jsonrpc`，不要依赖 hoisting。
-仅 ESM；需要 Node.js ≥ 18 或现代 bundler。
+`^9`，随本包一并装上。它的 transport class（reader/writer），以及在本包 API 中出现的
+那些 primitive —— `MessageReader`、`MessageConnection`、`CancellationToken`、
+`CancellationTokenSource` 等 —— 都已从 `@motrix/mdxp` re-export（见
+[入口点](#入口点)），因此你几乎无需直接 import `vscode-jsonrpc`。仅 ESM；需要
+Node.js ≥ 18 或现代 bundler。
 
 ### 入口点
 
@@ -56,21 +60,19 @@ npm install @motrix/mdxp
 
 `vscode-jsonrpc` v9 要求先装好一层 runtime abstraction layer（RAL），才能创建连接。
 import `@motrix/mdxp/node` 或 `@motrix/mdxp/browser` 会把对应的 RAL 装进本包所用的
-**同一个** `vscode-jsonrpc` 实例，并 re-export 完整的公开 API —— 于是 host 只需从
-一个入口 import 一切。
+**同一个** `vscode-jsonrpc` 实例，并 re-export 完整的公开 API，**外加该平台的
+transport class**（Node 的 `StreamMessageReader`/`Writer`、浏览器的
+`BrowserMessageReader`/`Writer`）—— 于是 host 连同 reader/writer 都只需从一个入口 import。
 
 ## 快速开始
 
 ### Node host（走 stdio）
 
 ```ts
-import { createMdxpConnection } from '@motrix/mdxp/node'
-import { StreamMessageReader, StreamMessageWriter } from 'vscode-jsonrpc/node'
+import { fromStdio } from '@motrix/mdxp/node'
 
-const conn = createMdxpConnection(
-  new StreamMessageReader(process.stdin),
-  new StreamMessageWriter(process.stdout),
-)
+// 走 process.stdin / process.stdout（native-messaging / CLI 场景）。
+const conn = fromStdio()
 
 // 务必在 listen() 之前注册 handler。
 conn.onNotification('$/task/progress', (p) => {
@@ -81,21 +83,30 @@ conn.onNotification('$/task/progress', (p) => {
 conn.listen()
 ```
 
-### 浏览器 host
+### 浏览器 host（走 WebSocket）
 
 ```ts
-// 装好 browser RAL，并 re-export 全量 API。
-import { createMdxpConnection } from '@motrix/mdxp/browser'
-import { BrowserMessageReader, BrowserMessageWriter } from 'vscode-jsonrpc/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**
@@ -232,7 +243,7 @@ conn.onNotification('$/task/error', (p) => {
 `token.isCancellationRequested` 即可响应。
 
 ```ts
-import { CancellationTokenSource } from 'vscode-jsonrpc'
+import { CancellationTokenSource } from '@motrix/mdxp'
 
 const cts = new CancellationTokenSource()
 const pending = conn.sendRequest('url/resolve', { url }, cts.token)
@@ -296,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'`）。 |
@@ -306,6 +318,7 @@ const tools = toAgentToolCatalog()
 | `toAgentToolCatalog()` | function | 取 `agentFacing` 子集，转成 JSON-Schema tools。 |
 | `SERVER_INITIATED_METHODS` | const | 由 server 向 client 发起的 method（`url/probe`、`url/resolve`）。 |
 | `*Schema` | Zod schema | 全部 wire 形态，供运行时校验。 |
+| `MessageReader` · `MessageWriter` · `MessageConnection` · `CancellationToken` · `CancellationTokenSource` · `Disposable` | re-export | 本包 API 中用到的 `vscode-jsonrpc` primitive。平台 transport class（`StreamMessageReader`/`Writer`、`BrowserMessageReader`/`Writer`）从 `./node` 与 `./browser` re-export。 |
 
 ### Methods
 

package/dist/browser.d.ts

@@ -1,3 +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;AAE/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

@@ -10,5 +10,13 @@
 // `@motrix/mdxp/browser` once at startup. The full public API is re-exported, so
 // `import { createMdxpConnection } from '@motrix/mdxp/browser'` also works.
 import 'vscode-jsonrpc/browser';
+// Browser transport classes, re-exported so a browser host imports its
+// reader/writer from the same place as `createMdxpConnection` — no separate
+// `vscode-jsonrpc` import, and guaranteed to be the instance this package
+// 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,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/index.d.ts

@@ -1,3 +1,5 @@
+export type { Disposable, MessageConnection, MessageReader, MessageWriter, } from 'vscode-jsonrpc';
+export { CancellationToken, CancellationTokenSource } from 'vscode-jsonrpc';
 export type { MdxpConnection, MdxpNotificationMap, MdxpRequestMap, } from './connection.js';
 export { createMdxpConnection } from './connection.js';
 export type { ErrorCode, MdxpError, MdxpErrorData } from './errors.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,YAAY,EACV,cAAc,EACd,mBAAmB,EACnB,cAAc,GACf,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AACtD,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AACtE,OAAO,EACL,UAAU,EACV,aAAa,EACb,eAAe,EACf,aAAa,GACd,MAAM,aAAa,CAAA;AACpB,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AACxD,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAGrD,cAAc,oBAAoB,CAAA;AAClC,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAGxD,OAAO,EACL,wBAAwB,EACxB,KAAK,EACL,kBAAkB,GACnB,MAAM,YAAY,CAAA;AAEnB,mBAAmB,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA,YAAY,EACV,UAAU,EACV,iBAAiB,EACjB,aAAa,EACb,aAAa,GACd,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAA;AAC3E,YAAY,EACV,cAAc,EACd,mBAAmB,EACnB,cAAc,GACf,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AACtD,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AACtE,OAAO,EACL,UAAU,EACV,aAAa,EACb,eAAe,EACf,aAAa,GACd,MAAM,aAAa,CAAA;AACpB,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AACxD,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAGrD,cAAc,oBAAoB,CAAA;AAClC,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAGxD,OAAO,EACL,wBAAwB,EACxB,KAAK,EACL,kBAAkB,GACnB,MAAM,YAAY,CAAA;AAEnB,mBAAmB,YAAY,CAAA"}

package/dist/index.js

@@ -1,5 +1,6 @@
 // MDXP — Motrix Download eXchange Protocol
 // Public API surface for both Motrix desktop and the browser extension.
+export { CancellationToken, CancellationTokenSource } from 'vscode-jsonrpc';
 export { createMdxpConnection } from './connection.js';
 export { ErrorCodes, isMotrixError, isProtocolError, makeMdxpError, } from './errors.js';
 export { Methods, Notifications } from './methods.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAC3C,wEAAwE;AAOxE,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AAEtD,OAAO,EACL,UAAU,EACV,aAAa,EACb,eAAe,EACf,aAAa,GACd,MAAM,aAAa,CAAA;AAEpB,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAErD,qDAAqD;AACrD,cAAc,oBAAoB,CAAA;AAGlC,wCAAwC;AACxC,OAAO,EACL,wBAAwB,EACxB,KAAK,EACL,kBAAkB,GACnB,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAC3C,wEAAwE;AAYxE,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAA;AAM3E,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AAEtD,OAAO,EACL,UAAU,EACV,aAAa,EACb,eAAe,EACf,aAAa,GACd,MAAM,aAAa,CAAA;AAEpB,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAErD,qDAAqD;AACrD,cAAc,oBAAoB,CAAA;AAGlC,wCAAwC;AACxC,OAAO,EACL,wBAAwB,EACxB,KAAK,EACL,kBAAkB,GACnB,MAAM,YAAY,CAAA"}

package/dist/node.d.ts

@@ -1,3 +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;AAE5B,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

@@ -11,5 +11,12 @@
 // once at bootstrap. The full public API is re-exported for convenience, so
 // `import { createMdxpConnection } from '@motrix/mdxp/node'` also works.
 import 'vscode-jsonrpc/node';
+// Node transport classes, re-exported so a Node host imports its reader/writer
+// from the same place as `createMdxpConnection` — no separate `vscode-jsonrpc`
+// 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,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.1.1",
+  "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

@@ -11,4 +11,17 @@
 // `import { createMdxpConnection } from '@motrix/mdxp/browser'` also works.
 import 'vscode-jsonrpc/browser'
 
+// Browser transport classes, re-exported so a browser host imports its
+// reader/writer from the same place as `createMdxpConnection` — no separate
+// `vscode-jsonrpc` import, and guaranteed to be the instance this package
+// installed the RAL into.
+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'
+// High-level convenience constructors for browser transports.
+export { fromWebSocket } from './transports/ws.js'

package/src/index.ts

@@ -1,6 +1,17 @@
 // MDXP — Motrix Download eXchange Protocol
 // Public API surface for both Motrix desktop and the browser extension.
 
+// vscode-jsonrpc primitives that appear in this package's public API surface,
+// re-exported so consumers import them from `@motrix/mdxp` instead of reaching
+// for a second package. Platform transport classes (StreamMessageReader,
+// BrowserMessageReader, …) are re-exported from `./node` and `./browser`.
+export type {
+  Disposable,
+  MessageConnection,
+  MessageReader,
+  MessageWriter,
+} from 'vscode-jsonrpc'
+export { CancellationToken, CancellationTokenSource } from 'vscode-jsonrpc'
 export type {
   MdxpConnection,
   MdxpNotificationMap,

package/src/node.ts

@@ -12,4 +12,22 @@
 // `import { createMdxpConnection } from '@motrix/mdxp/node'` also works.
 import 'vscode-jsonrpc/node'
 
+// Node transport classes, re-exported so a Node host imports its reader/writer
+// from the same place as `createMdxpConnection` — no separate `vscode-jsonrpc`
+// 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'
+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)
+  )
+}