@cyia/chrome-trpc 1.0.0 → 1.0.1

package/client/chromeLink.d.ts

@@ -0,0 +1,7 @@
+import { TRPCLink } from '@trpc/client';
+import type { AnyRouter, AnyTRPCRouter, inferTRPCClientTypes } from '@trpc/server';
+import { TransformerOptions } from '@trpc/client/unstable-internals';
+export type ChromeLinkOptions<TRouter extends AnyTRPCRouter> = TransformerOptions<inferTRPCClientTypes<TRouter>>;
+export declare function chromeLink<TRouter extends AnyRouter>(opts: ChromeLinkOptions<TRouter> & {
+    port: chrome.runtime.Port;
+}): TRPCLink<TRouter>;

package/client/index.d.ts

@@ -0,0 +1 @@
+export * from './chromeLink';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cyia/chrome-trpc",
-  "version": "1.0.0",
-  "description": "tRPC integration for VS Code Extension-Webview communication",
+  "version": "1.0.1",
+  "description": "tRPC Adapter for Chrome Extension",
   "module": "esm",
   "type": "module",
   "scripts": {
@@ -10,7 +10,9 @@
   },
   "author": "wszgrcy",
   "license": "MIT",
-  "repository": {},
+  "repository": {
+    "url": "https://github.com/wszgrcy/chrome-trpc"
+  },
   "homepage": "https://github.com/wszgrcy/chrome-trpc/tree/main/packages/trpc#readme",
   "bugs": {
     "url": "https://github.com/wszgrcy/chrome-trpc/issues"

package/readme.md

@@ -1,192 +1,192 @@
-# @cyia/chrome-trpc
-
-[English](./readme.md) | [中文](./readme.zh-hans.md)
-
-[![npm version](https://badge.fury.io/js/%40cyia%2Fchrome-trpc.svg)](https://badge.fury.io/js/%40cyia%2Fchrome-trpc)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-A **tRPC adapter** tailored for Chrome extensions, enabling you to make type-safe remote procedure calls securely and conveniently between different extension contexts (popup, content script, background).  
-It deeply integrates Chrome’s internal `runtime.connect` / `tabs.connect` channels and includes built-in binary data compression, greatly improving the transmission efficiency of large `Uint8Array` payloads.
-
-## ✨ Features
-
-- **Full type safety**: End-to-end type inference powered by tRPC, eliminating manual message parsing.
-- **Three communication modes out of the box**:
-  - Popup → Content Script
-  - Content Script → Background
-  - Popup → Background
-- **Binary compression**: Automatically compresses `Uint8Array` using Snappy, with fine-grained control over compression scope to reduce message size and speed up transmission.
-- **Zero-configuration server**: The server (receiving end) only needs a single line of code to start listening for connections.
-- **Lightweight**: Core logic is concise and does not intrude into your existing architecture.
-- **Native Promise support**: Calling a remote function feels just like a local async call.
-
-## 📦 Installation
-
-```bash
-npm install @cyia/chrome-trpc @trpc/client @trpc/server
-```
-
-Or use yarn/pnpm.  
-`@trpc/client` and `@trpc/server` are peer dependencies; please ensure compatible versions (^11.18.0).
-
-## 🚀 Quick Start
-
-### 1. Define a shared router (types)
-
-Define your router in a shared `router.ts` file using `@trpc/server` so that both ends can reuse the types.
-
-```typescript
-import { initTRPC } from '@trpc/server';
-import { z } from 'zod'; // or another validation library like valibot
-
-const t = initTRPC.create();
-
-export const appRouter = t.router({
-  greet: t.procedure.input(z.string()).query(({ input }) => `Hello ${input}`),
-  getData: t.procedure.query(() => ({ payload: new Uint8Array([1, 2, 3]) })),
-});
-
-export type AppRouter = typeof appRouter;
-```
-
-### 2. Server (receiving end)
-
-In the script that provides the service (e.g., background or content script), use `createChromeHandler` to listen for connections from other parts.
-
-```typescript
-// background.ts or content-script.ts
-import { createChromeHandler } from '@cyia/chrome-trpc/server';
-import { appRouter } from './router';
-
-// One-liner to start, automatically handles chrome.runtime.onConnect connections
-createChromeHandler({ router: appRouter });
-```
-
-> 💡 Which script acts as the "server" depends on your communication direction.  
-> For example: Popup → Background – Background is the server;  
-> Popup → Content Script – Content Script is the server.
-
-### 3. Client (calling end)
-
-In the script that initiates calls (e.g., popup or content script), create a tRPC client and pass in a Chrome port.
-
-```typescript
-// popup.ts or content-script.ts
-import { createTRPCProxyClient } from '@trpc/client';
-import { chromeLink } from '@cyia/chrome-trpc/client';
-import type { AppRouter } from './router';
-
-// Establish connection to the target context (depends on communication mode)
-const port = chrome.runtime.connect();
-
-const trpc = createTRPCProxyClient<AppRouter>({
-  links: [chromeLink({ port })],
-});
-
-// Now you can call remote procedures like local functions
-const greeting = await trpc.greet.query('World');
-console.log(greeting); // "Hello World"
-```
-
-## 🔌 Three Communication Modes Explained
-
-| Direction                      | Client (caller) | Server (receiver) | How to obtain the `port`                                                    |
-| ------------------------------ | --------------- | ----------------- | --------------------------------------------------------------------------- |
-| **Popup → Background**          | Popup           | Background        | `chrome.runtime.connect()`                                                  |
-| **Content Script → Background** | Content Script  | Background        | `chrome.runtime.connect()`                                                  |
-| **Popup → Content Script**      | Popup           | Content Script    | First get the tabId via `chrome.tabs.query`,<br>then `chrome.tabs.connect(tabId)` |
-
-### Example: Popup calling Content Script
-
-**content-script.ts (server)**
-
-```typescript
-import { createChromeHandler } from '@cyia/chrome-trpc/server';
-import { appRouter } from './router';
-createChromeHandler({ router: appRouter });
-```
-
-**popup.ts (client)**
-
-```typescript
-import { chromeLink } from '@cyia/chrome-trpc/client';
-import { createTRPCProxyClient } from '@trpc/client';
-import type { AppRouter } from './router';
-
-const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
-if (tab.id) {
-  const port = chrome.tabs.connect(tab.id);
-  const trpc = createTRPCProxyClient<AppRouter>({
-    links: [chromeLink({ port })],
-  });
-  const data = await trpc.getData.query();
-}
-```
-
-## 📦 Binary Compression
-
-The adapter uses the [Snappy](https://github.com/zhipeng-jia/snappyjs) algorithm to compress and decompress `Uint8Array` data, significantly reducing the transfer size.
-
-### Response Compression (server configuration)
-
-In some scenarios you may want to explicitly specify which response paths should be compressed, or a procedure may return data that is not a plain `Uint8Array` but is still large.  
-In such cases you can pass the `compressPathObj` option to `createChromeHandler`. The keys are the procedure route paths, and a value of `true` enables compression.
-
-For example, suppose you extended your router with a `res` sub-router and a `cmp` query:
-
-```typescript
-// router.ts extended
-export const appRouter = t.router({
-  greet: t.procedure.input(z.string()).query(({ input }) => `Hello ${input}`),
-  getData: t.procedure.query(() => ({ payload: new Uint8Array([1, 2, 3]) })),
-  res: t.router({
-    cmp: t.procedure.query(() => {
-      return new Uint8Array([1, 2, 3, 4]);
-    }),
-  }),
-});
-```
-
-Server configuration compressing the path `'res.cmp'`:
-
-```typescript
-createChromeHandler({
-  router: appRouter,
-  // Explicitly declare the procedure paths whose responses should be compressed (relative to appRouter)
-  compressPathObj: { 'res.cmp': true },
-});
-```
-
-> Paths use `.` to separate router levels, e.g., `'res.cmp'` corresponds to `appRouter.res.cmp`.  
-> When `compressPathObj` is specified, only the listed paths will have their responses forcibly compressed.
-
-### Request Compression (client configuration)
-
-If the client needs to send large parameters (e.g., big arrays, complex objects), you can enable request compression via `context` at call time, without any server-side changes.
-
-```typescript
-// Assume the router has a clientCmp procedure that accepts complex parameters
-// On the client side, pass { context: { compress: true } }
-const result = await trpc.clientCmp.query(
-  { arr1: [1, 2, 3], num1: 1, str1: '1', b1: true },
-  { context: { compress: true } },
-);
-```
-
-This way, `Uint8Array` or serializable data in the request body will be automatically compressed before transmission. The server decompresses it transparently, making the process invisible to your business logic.
-
-By combining response compression and request compression, you can efficiently exchange large amounts of data between different parts of your Chrome extension.
-
-## 💡 Notes
-
-- **Type sharing**: Make sure the `AppRouter` type is shared between client and server (usually extracted as a common file).
-- **Content script environment**: If the content script acts as the server, ensure it is properly injected via `content_scripts` in `manifest.json` and runs at the appropriate time.
-- **Manifest permissions**: Ensure the required permissions are declared in `manifest.json` (e.g., `"tabs"` for Popup → Content Script connections).
-- **Compression paths**: The paths in `compressPathObj` must exactly match the router structure, otherwise the configuration will not take effect.
-- **Request compression**: When enabling `compress: true` on the client, ensure the input parameters contain compressible data (like `Uint8Array`), otherwise the compression effect may be negligible.
-
-## 🔗 Related Links
-
-- [GitHub Repository](https://github.com/wszgrcy/chrome-trpc)
-- [Issue Tracker](https://github.com/wszgrcy/chrome-trpc/issues)
-- [tRPC Official Documentation](https://trpc.io)
+# @cyia/chrome-trpc
+
+[English](./readme.md) | [中文](./readme.zh-hans.md)
+
+[![npm version](https://badge.fury.io/js/%40cyia%2Fchrome-trpc.svg)](https://badge.fury.io/js/%40cyia%2Fchrome-trpc)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A **tRPC adapter** tailored for Chrome extensions, enabling you to make type-safe remote procedure calls securely and conveniently between different extension contexts (popup, content script, background).  
+It deeply integrates Chrome’s internal `runtime.connect` / `tabs.connect` channels and includes built-in binary data compression, greatly improving the transmission efficiency of large `Uint8Array` payloads.
+
+## ✨ Features
+
+- **Full type safety**: End-to-end type inference powered by tRPC, eliminating manual message parsing.
+- **Three communication modes out of the box**:
+  - Popup → Content Script
+  - Content Script → Background
+  - Popup → Background
+- **Binary compression**: Automatically compresses `Uint8Array` using Snappy, with fine-grained control over compression scope to reduce message size and speed up transmission.
+- **Zero-configuration server**: The server (receiving end) only needs a single line of code to start listening for connections.
+- **Lightweight**: Core logic is concise and does not intrude into your existing architecture.
+- **Native Promise support**: Calling a remote function feels just like a local async call.
+
+## 📦 Installation
+
+```bash
+npm install @cyia/chrome-trpc @trpc/client @trpc/server
+```
+
+Or use yarn/pnpm.  
+`@trpc/client` and `@trpc/server` are peer dependencies; please ensure compatible versions (^11.18.0).
+
+## 🚀 Quick Start
+
+### 1. Define a shared router (types)
+
+Define your router in a shared `router.ts` file using `@trpc/server` so that both ends can reuse the types.
+
+```typescript
+import { initTRPC } from '@trpc/server';
+import { z } from 'zod'; // or another validation library like valibot
+
+const t = initTRPC.create();
+
+export const appRouter = t.router({
+  greet: t.procedure.input(z.string()).query(({ input }) => `Hello ${input}`),
+  getData: t.procedure.query(() => ({ payload: new Uint8Array([1, 2, 3]) })),
+});
+
+export type AppRouter = typeof appRouter;
+```
+
+### 2. Server (receiving end)
+
+In the script that provides the service (e.g., background or content script), use `createChromeHandler` to listen for connections from other parts.
+
+```typescript
+// background.ts or content-script.ts
+import { createChromeHandler } from '@cyia/chrome-trpc/server';
+import { appRouter } from './router';
+
+// One-liner to start, automatically handles chrome.runtime.onConnect connections
+createChromeHandler({ router: appRouter });
+```
+
+> 💡 Which script acts as the "server" depends on your communication direction.  
+> For example: Popup → Background – Background is the server;  
+> Popup → Content Script – Content Script is the server.
+
+### 3. Client (calling end)
+
+In the script that initiates calls (e.g., popup or content script), create a tRPC client and pass in a Chrome port.
+
+```typescript
+// popup.ts or content-script.ts
+import { createTRPCProxyClient } from '@trpc/client';
+import { chromeLink } from '@cyia/chrome-trpc/client';
+import type { AppRouter } from './router';
+
+// Establish connection to the target context (depends on communication mode)
+const port = chrome.runtime.connect();
+
+const trpc = createTRPCProxyClient<AppRouter>({
+  links: [chromeLink({ port })],
+});
+
+// Now you can call remote procedures like local functions
+const greeting = await trpc.greet.query('World');
+console.log(greeting); // "Hello World"
+```
+
+## 🔌 Three Communication Modes Explained
+
+| Direction                      | Client (caller) | Server (receiver) | How to obtain the `port`                                                    |
+| ------------------------------ | --------------- | ----------------- | --------------------------------------------------------------------------- |
+| **Popup → Background**          | Popup           | Background        | `chrome.runtime.connect()`                                                  |
+| **Content Script → Background** | Content Script  | Background        | `chrome.runtime.connect()`                                                  |
+| **Popup → Content Script**      | Popup           | Content Script    | First get the tabId via `chrome.tabs.query`,<br>then `chrome.tabs.connect(tabId)` |
+
+### Example: Popup calling Content Script
+
+**content-script.ts (server)**
+
+```typescript
+import { createChromeHandler } from '@cyia/chrome-trpc/server';
+import { appRouter } from './router';
+createChromeHandler({ router: appRouter });
+```
+
+**popup.ts (client)**
+
+```typescript
+import { chromeLink } from '@cyia/chrome-trpc/client';
+import { createTRPCProxyClient } from '@trpc/client';
+import type { AppRouter } from './router';
+
+const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
+if (tab.id) {
+  const port = chrome.tabs.connect(tab.id);
+  const trpc = createTRPCProxyClient<AppRouter>({
+    links: [chromeLink({ port })],
+  });
+  const data = await trpc.getData.query();
+}
+```
+
+## 📦 Binary Compression
+
+The adapter uses the [Snappy](https://github.com/zhipeng-jia/snappyjs) algorithm to compress and decompress `Uint8Array` data, significantly reducing the transfer size.
+
+### Response Compression (server configuration)
+
+In some scenarios you may want to explicitly specify which response paths should be compressed, or a procedure may return data that is not a plain `Uint8Array` but is still large.  
+In such cases you can pass the `compressPathObj` option to `createChromeHandler`. The keys are the procedure route paths, and a value of `true` enables compression.
+
+For example, suppose you extended your router with a `res` sub-router and a `cmp` query:
+
+```typescript
+// router.ts extended
+export const appRouter = t.router({
+  greet: t.procedure.input(z.string()).query(({ input }) => `Hello ${input}`),
+  getData: t.procedure.query(() => ({ payload: new Uint8Array([1, 2, 3]) })),
+  res: t.router({
+    cmp: t.procedure.query(() => {
+      return new Uint8Array([1, 2, 3, 4]);
+    }),
+  }),
+});
+```
+
+Server configuration compressing the path `'res.cmp'`:
+
+```typescript
+createChromeHandler({
+  router: appRouter,
+  // Explicitly declare the procedure paths whose responses should be compressed (relative to appRouter)
+  compressPathObj: { 'res.cmp': true },
+});
+```
+
+> Paths use `.` to separate router levels, e.g., `'res.cmp'` corresponds to `appRouter.res.cmp`.  
+> When `compressPathObj` is specified, only the listed paths will have their responses forcibly compressed.
+
+### Request Compression (client configuration)
+
+If the client needs to send large parameters (e.g., big arrays, complex objects), you can enable request compression via `context` at call time, without any server-side changes.
+
+```typescript
+// Assume the router has a clientCmp procedure that accepts complex parameters
+// On the client side, pass { context: { compress: true } }
+const result = await trpc.clientCmp.query(
+  { arr1: [1, 2, 3], num1: 1, str1: '1', b1: true },
+  { context: { compress: true } },
+);
+```
+
+This way, `Uint8Array` or serializable data in the request body will be automatically compressed before transmission. The server decompresses it transparently, making the process invisible to your business logic.
+
+By combining response compression and request compression, you can efficiently exchange large amounts of data between different parts of your Chrome extension.
+
+## 💡 Notes
+
+- **Type sharing**: Make sure the `AppRouter` type is shared between client and server (usually extracted as a common file).
+- **Content script environment**: If the content script acts as the server, ensure it is properly injected via `content_scripts` in `manifest.json` and runs at the appropriate time.
+- **Manifest permissions**: Ensure the required permissions are declared in `manifest.json` (e.g., `"tabs"` for Popup → Content Script connections).
+- **Compression paths**: The paths in `compressPathObj` must exactly match the router structure, otherwise the configuration will not take effect.
+- **Request compression**: When enabling `compress: true` on the client, ensure the input parameters contain compressible data (like `Uint8Array`), otherwise the compression effect may be negligible.
+
+## 🔗 Related Links
+
+- [GitHub Repository](https://github.com/wszgrcy/chrome-trpc)
+- [Issue Tracker](https://github.com/wszgrcy/chrome-trpc/issues)
+- [tRPC Official Documentation](https://trpc.io)

package/readme.zh-hans.md

@@ -1,192 +1,192 @@
-# @cyia/chrome-trpc
-
-[English](./readme.md) | [中文](./readme.zh-hans.md)
-
-[![npm version](https://badge.fury.io/js/%40cyia%2Fchrome-trpc.svg)](https://badge.fury.io/js/%40cyia%2Fchrome-trpc)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-为 Chrome 扩展（插件）量身定制的 **tRPC 适配器**，让您能在扩展的不同运行时（popup、content script、background）之间安全、便捷地进行类型安全的远程过程调用。  
-它深度整合了 Chrome 内部的 `runtime.connect` / `tabs.connect` 通道，并内置二进制数据压缩，大幅提升大型 `Uint8Array` 的传输效率。
-
-## ✨ 特性
-
-- **全类型安全**：基于 tRPC 实现端到端类型推导，杜绝手动解析消息。
-- **三种通讯方式开箱即用**：
-  - Popup → Content Script
-  - Content Script → Background
-  - Popup → Background
-- **二进制压缩**：自动使用 Snappy 压缩 `Uint8Array`，并可精细控制压缩范围，减少消息体积，加快传输。
-- **零配置服务端**：服务端（接收端）只需一行代码即可监听连接。
-- **轻量级**：核心逻辑简洁，不侵入现有架构。
-- **原生 Promise 支持**：调用远程函数如同本地异步调用。
-
-## 📦 安装
-
-```bash
-npm install @cyia/chrome-trpc @trpc/client @trpc/server
-```
-
-或使用 yarn/pnpm。  
-`@trpc/client` 与 `@trpc/server` 为 peer dependencies，请确保版本兼容（^11.18.0）。
-
-## 🚀 快速开始
-
-### 1. 定义共享路由（类型）
-
-在一个公共的 `router.ts` 文件中使用 `@trpc/server` 定义路由，以便两端复用类型。
-
-```typescript
-import { initTRPC } from '@trpc/server';
-import { z } from 'zod'; // 或其他验证库，如 valibot
-
-const t = initTRPC.create();
-
-export const appRouter = t.router({
-  greet: t.procedure.input(z.string()).query(({ input }) => `Hello ${input}`),
-  getData: t.procedure.query(() => ({ payload: new Uint8Array([1, 2, 3]) })),
-});
-
-export type AppRouter = typeof appRouter;
-```
-
-### 2. 服务端（接收端）
-
-在需要提供服务的脚本（如 background 或 content script）中，使用 `createChromeHandler` 监听来自其他部分的连接。
-
-```typescript
-// background.ts 或 content-script.ts
-import { createChromeHandler } from '@cyia/chrome-trpc/server';
-import { appRouter } from './router';
-
-// 一行启动，自动处理 chrome.runtime.onConnect 连接
-createChromeHandler({ router: appRouter });
-```
-
-> 💡 哪个脚本作为“服务端”，取决于您的通讯方向。  
-> 例如：Popup → Background 时，Background 为服务端；  
-> Popup → Content Script 时，Content Script 为服务端。
-
-### 3. 客户端（调用端）
-
-在需要发起调用的脚本（如 popup 或 content script）中，创建 tRPC 客户端并传入 Chrome 端口。
-
-```typescript
-// popup.ts 或 content-script.ts
-import { createTRPCProxyClient } from '@trpc/client';
-import { chromeLink } from '@cyia/chrome-trpc/client';
-import type { AppRouter } from './router';
-
-// 建立与目标运行时的连接（取决于通讯方式）
-const port = chrome.runtime.connect();
-
-const trpc = createTRPCProxyClient<AppRouter>({
-  links: [chromeLink({ port })],
-});
-
-// 现在即可像调用本地函数一样调用远程过程
-const greeting = await trpc.greet.query('世界');
-console.log(greeting); // "Hello 世界"
-```
-
-## 🔌 三种通讯方式详解
-
-| 方向                            | 客户端（调用方） | 服务端（接收方） | 如何获取 `port`                                                              |
-| ------------------------------- | ---------------- | ---------------- | ---------------------------------------------------------------------------- |
-| **Popup → Background**          | Popup            | Background       | `chrome.runtime.connect()`                                                   |
-| **Content Script → Background** | Content Script   | Background       | `chrome.runtime.connect()`                                                   |
-| **Popup → Content Script**      | Popup            | Content Script   | 先通过 `chrome.tabs.query` 获取 tabId，<br>然后 `chrome.tabs.connect(tabId)` |
-
-### 示例：Popup 调用 Content Script
-
-**content-script.ts (服务端)**
-
-```typescript
-import { createChromeHandler } from '@cyia/chrome-trpc/server';
-import { appRouter } from './router';
-createChromeHandler({ router: appRouter });
-```
-
-**popup.ts (客户端)**
-
-```typescript
-import { chromeLink } from '@cyia/chrome-trpc/client';
-import { createTRPCProxyClient } from '@trpc/client';
-import type { AppRouter } from './router';
-
-const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
-if (tab.id) {
-  const port = chrome.tabs.connect(tab.id);
-  const trpc = createTRPCProxyClient<AppRouter>({
-    links: [chromeLink({ port })],
-  });
-  const data = await trpc.getData.query();
-}
-```
-
-## 📦 二进制压缩
-
-适配器使用 [Snappy](https://github.com/zhipeng-jia/snappyjs) 算法对 `Uint8Array` 数据进行压缩与解压，大幅降低传输体积。
-
-### 响应内容压缩（服务端配置）
-
-某些场景下，您可能希望显式指定需要压缩的响应路径，或者过程返回的数据并非纯 `Uint8Array` 但体积较大。  
-此时可在 `createChromeHandler` 中传入 `compressPathObj` 参数，键为过程的路由路径，值为 `true` 表示启用压缩。
-
-例如，假设您的路由中定义了 `res` 子路由和 `cmp` 查询：
-
-```typescript
-// router.ts 扩展
-export const appRouter = t.router({
-  greet: t.procedure.input(z.string()).query(({ input }) => `Hello ${input}`),
-  getData: t.procedure.query(() => ({ payload: new Uint8Array([1, 2, 3]) })),
-  res: t.router({
-    cmp: t.procedure.query(() => {
-      return new Uint8Array([1, 2, 3, 4]);
-    }),
-  }),
-});
-```
-
-服务端配置压缩路径 `'res.cmp'`：
-
-```typescript
-createChromeHandler({
-  router: appRouter,
-  // 显式声明需要压缩响应的过程路径（相对 appRouter）
-  compressPathObj: { 'res.cmp': true },
-});
-```
-
-> 路径使用 `.` 分隔路由层级，如 `'res.cmp'` 对应 `appRouter.res.cmp`。  
-> 指定了 `compressPathObj` ，只有列表中标记的会强制压缩响应体
-
-### 请求参数压缩（客户端配置）
-
-如果客户端需要发送大型参数（如大数组、复杂对象），可以在调用时通过 `context` 启用请求压缩，无需修改服务端配置。
-
-```typescript
-// 假设路由中存在 clientCmp 过程，接受复杂参数
-// 客户端调用时，传入 { context: { compress: true } }
-const result = await trpc.clientCmp.query(
-  { arr1: [1, 2, 3], num1: 1, str1: '1', b1: true },
-  { context: { compress: true } },
-);
-```
-
-这样，请求体中的 `Uint8Array` 或可序列化数据会被自动压缩后再传输，服务端收到后自动解压，整个过程对业务逻辑透明。
-
-结合响应压缩与请求压缩，您可以高效地在 Chrome 扩展的不同部分之间交换大量数据。
-
-## 💡 注意事项
-
-- **类型共享**：务必确保 `AppRouter` 类型在客户端与服务端之间共享（通常抽取为公共文件）。
-- **Content Script 环境**：若 Content Script 作为服务端，请确保它在 `manifest.json` 的 `content_scripts` 中正确注入，且运行在适当的时机。
-- **Manifest 权限**：确保 `manifest.json` 中已声明所需的权限（如 `"tabs"` 用于 Popup → Content Script 连接）。
-- **压缩路径**：`compressPathObj` 中的路径必须与路由结构精确匹配，否则配置不会生效。
-- **请求压缩**：客户端启用 `compress: true` 时，请确保输入参数中包含可压缩的数据（如 `Uint8Array`），否则压缩效果不明显。
-
-## 🔗 相关链接
-
-- [GitHub 仓库](https://github.com/wszgrcy/chrome-trpc)
-- [问题反馈](https://github.com/wszgrcy/chrome-trpc/issues)
-- [tRPC 官方文档](https://trpc.io)
+# @cyia/chrome-trpc
+
+[English](./readme.md) | [中文](./readme.zh-hans.md)
+
+[![npm version](https://badge.fury.io/js/%40cyia%2Fchrome-trpc.svg)](https://badge.fury.io/js/%40cyia%2Fchrome-trpc)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+为 Chrome 扩展（插件）量身定制的 **tRPC 适配器**，让您能在扩展的不同运行时（popup、content script、background）之间安全、便捷地进行类型安全的远程过程调用。  
+它深度整合了 Chrome 内部的 `runtime.connect` / `tabs.connect` 通道，并内置二进制数据压缩，大幅提升大型 `Uint8Array` 的传输效率。
+
+## ✨ 特性
+
+- **全类型安全**：基于 tRPC 实现端到端类型推导，杜绝手动解析消息。
+- **三种通讯方式开箱即用**：
+  - Popup → Content Script
+  - Content Script → Background
+  - Popup → Background
+- **二进制压缩**：自动使用 Snappy 压缩 `Uint8Array`，并可精细控制压缩范围，减少消息体积，加快传输。
+- **零配置服务端**：服务端（接收端）只需一行代码即可监听连接。
+- **轻量级**：核心逻辑简洁，不侵入现有架构。
+- **原生 Promise 支持**：调用远程函数如同本地异步调用。
+
+## 📦 安装
+
+```bash
+npm install @cyia/chrome-trpc @trpc/client @trpc/server
+```
+
+或使用 yarn/pnpm。  
+`@trpc/client` 与 `@trpc/server` 为 peer dependencies，请确保版本兼容（^11.18.0）。
+
+## 🚀 快速开始
+
+### 1. 定义共享路由（类型）
+
+在一个公共的 `router.ts` 文件中使用 `@trpc/server` 定义路由，以便两端复用类型。
+
+```typescript
+import { initTRPC } from '@trpc/server';
+import { z } from 'zod'; // 或其他验证库，如 valibot
+
+const t = initTRPC.create();
+
+export const appRouter = t.router({
+  greet: t.procedure.input(z.string()).query(({ input }) => `Hello ${input}`),
+  getData: t.procedure.query(() => ({ payload: new Uint8Array([1, 2, 3]) })),
+});
+
+export type AppRouter = typeof appRouter;
+```
+
+### 2. 服务端（接收端）
+
+在需要提供服务的脚本（如 background 或 content script）中，使用 `createChromeHandler` 监听来自其他部分的连接。
+
+```typescript
+// background.ts 或 content-script.ts
+import { createChromeHandler } from '@cyia/chrome-trpc/server';
+import { appRouter } from './router';
+
+// 一行启动，自动处理 chrome.runtime.onConnect 连接
+createChromeHandler({ router: appRouter });
+```
+
+> 💡 哪个脚本作为“服务端”，取决于您的通讯方向。  
+> 例如：Popup → Background 时，Background 为服务端；  
+> Popup → Content Script 时，Content Script 为服务端。
+
+### 3. 客户端（调用端）
+
+在需要发起调用的脚本（如 popup 或 content script）中，创建 tRPC 客户端并传入 Chrome 端口。
+
+```typescript
+// popup.ts 或 content-script.ts
+import { createTRPCProxyClient } from '@trpc/client';
+import { chromeLink } from '@cyia/chrome-trpc/client';
+import type { AppRouter } from './router';
+
+// 建立与目标运行时的连接（取决于通讯方式）
+const port = chrome.runtime.connect();
+
+const trpc = createTRPCProxyClient<AppRouter>({
+  links: [chromeLink({ port })],
+});
+
+// 现在即可像调用本地函数一样调用远程过程
+const greeting = await trpc.greet.query('世界');
+console.log(greeting); // "Hello 世界"
+```
+
+## 🔌 三种通讯方式详解
+
+| 方向                            | 客户端（调用方） | 服务端（接收方） | 如何获取 `port`                                                              |
+| ------------------------------- | ---------------- | ---------------- | ---------------------------------------------------------------------------- |
+| **Popup → Background**          | Popup            | Background       | `chrome.runtime.connect()`                                                   |
+| **Content Script → Background** | Content Script   | Background       | `chrome.runtime.connect()`                                                   |
+| **Popup → Content Script**      | Popup            | Content Script   | 先通过 `chrome.tabs.query` 获取 tabId，<br>然后 `chrome.tabs.connect(tabId)` |
+
+### 示例：Popup 调用 Content Script
+
+**content-script.ts (服务端)**
+
+```typescript
+import { createChromeHandler } from '@cyia/chrome-trpc/server';
+import { appRouter } from './router';
+createChromeHandler({ router: appRouter });
+```
+
+**popup.ts (客户端)**
+
+```typescript
+import { chromeLink } from '@cyia/chrome-trpc/client';
+import { createTRPCProxyClient } from '@trpc/client';
+import type { AppRouter } from './router';
+
+const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
+if (tab.id) {
+  const port = chrome.tabs.connect(tab.id);
+  const trpc = createTRPCProxyClient<AppRouter>({
+    links: [chromeLink({ port })],
+  });
+  const data = await trpc.getData.query();
+}
+```
+
+## 📦 二进制压缩
+
+适配器使用 [Snappy](https://github.com/zhipeng-jia/snappyjs) 算法对 `Uint8Array` 数据进行压缩与解压，大幅降低传输体积。
+
+### 响应内容压缩（服务端配置）
+
+某些场景下，您可能希望显式指定需要压缩的响应路径，或者过程返回的数据并非纯 `Uint8Array` 但体积较大。  
+此时可在 `createChromeHandler` 中传入 `compressPathObj` 参数，键为过程的路由路径，值为 `true` 表示启用压缩。
+
+例如，假设您的路由中定义了 `res` 子路由和 `cmp` 查询：
+
+```typescript
+// router.ts 扩展
+export const appRouter = t.router({
+  greet: t.procedure.input(z.string()).query(({ input }) => `Hello ${input}`),
+  getData: t.procedure.query(() => ({ payload: new Uint8Array([1, 2, 3]) })),
+  res: t.router({
+    cmp: t.procedure.query(() => {
+      return new Uint8Array([1, 2, 3, 4]);
+    }),
+  }),
+});
+```
+
+服务端配置压缩路径 `'res.cmp'`：
+
+```typescript
+createChromeHandler({
+  router: appRouter,
+  // 显式声明需要压缩响应的过程路径（相对 appRouter）
+  compressPathObj: { 'res.cmp': true },
+});
+```
+
+> 路径使用 `.` 分隔路由层级，如 `'res.cmp'` 对应 `appRouter.res.cmp`。  
+> 指定了 `compressPathObj` ，只有列表中标记的会强制压缩响应体
+
+### 请求参数压缩（客户端配置）
+
+如果客户端需要发送大型参数（如大数组、复杂对象），可以在调用时通过 `context` 启用请求压缩，无需修改服务端配置。
+
+```typescript
+// 假设路由中存在 clientCmp 过程，接受复杂参数
+// 客户端调用时，传入 { context: { compress: true } }
+const result = await trpc.clientCmp.query(
+  { arr1: [1, 2, 3], num1: 1, str1: '1', b1: true },
+  { context: { compress: true } },
+);
+```
+
+这样，请求体中的 `Uint8Array` 或可序列化数据会被自动压缩后再传输，服务端收到后自动解压，整个过程对业务逻辑透明。
+
+结合响应压缩与请求压缩，您可以高效地在 Chrome 扩展的不同部分之间交换大量数据。
+
+## 💡 注意事项
+
+- **类型共享**：务必确保 `AppRouter` 类型在客户端与服务端之间共享（通常抽取为公共文件）。
+- **Content Script 环境**：若 Content Script 作为服务端，请确保它在 `manifest.json` 的 `content_scripts` 中正确注入，且运行在适当的时机。
+- **Manifest 权限**：确保 `manifest.json` 中已声明所需的权限（如 `"tabs"` 用于 Popup → Content Script 连接）。
+- **压缩路径**：`compressPathObj` 中的路径必须与路由结构精确匹配，否则配置不会生效。
+- **请求压缩**：客户端启用 `compress: true` 时，请确保输入参数中包含可压缩的数据（如 `Uint8Array`），否则压缩效果不明显。
+
+## 🔗 相关链接
+
+- [GitHub 仓库](https://github.com/wszgrcy/chrome-trpc)
+- [问题反馈](https://github.com/wszgrcy/chrome-trpc/issues)
+- [tRPC 官方文档](https://trpc.io)

package/server/createChromeHandler.d.ts

@@ -0,0 +1,15 @@
+import type { AnyRouter, inferRouterContext } from '@trpc/server';
+type Awaitable<T> = T | Promise<T>;
+type ChromHandleOptions<TRouter extends AnyRouter> = {
+    createContext?: () => Awaitable<inferRouterContext<TRouter>>;
+    router: TRouter;
+    compressPathObj?: Record<string, boolean>;
+};
+declare class ChromeHandler<TRouter extends AnyRouter> {
+    #private;
+    private options;
+    constructor(options: ChromHandleOptions<TRouter>);
+    init(): void;
+}
+export declare const createChromeHandler: <TRouter extends AnyRouter>(options: ChromHandleOptions<TRouter>) => ChromeHandler<TRouter>;
+export {};

package/server/handleChromeMessage.d.ts

@@ -0,0 +1,10 @@
+import type { AnyTRPCRouter, inferRouterContext } from '@trpc/server';
+import { Message } from '../type';
+export declare function handleChromeMessage<TRouter extends AnyTRPCRouter>({ router, createContext, message, subscriptions, compressPathObj, port, }: {
+    router: TRouter;
+    createContext?: () => Promise<inferRouterContext<TRouter>>;
+    message: Message;
+    subscriptions: Map<string, AbortController>;
+    compressPathObj?: Record<string, boolean>;
+    port: chrome.runtime.Port;
+}): Promise<void>;

package/server/index.d.ts

@@ -0,0 +1,2 @@
+export * from './createChromeHandler';
+export * from './type';

package/server/type.d.ts

@@ -0,0 +1,3 @@
+export interface CreateContextOptions {
+    [name: string]: any;
+}

package/server/utils.d.ts

@@ -0,0 +1,2 @@
+import { TRPCError } from '@trpc/server';
+export declare function getTRPCErrorFromUnknown(cause: unknown): TRPCError;

package/type.d.ts

@@ -0,0 +1,6 @@
+import type { Operation } from '@trpc/client';
+export interface Message {
+    method: string;
+    operation: Operation;
+    id: string;
+}

package/util/json.d.ts

@@ -0,0 +1,12 @@
+import { SuperJSON, SuperJSONResult } from 'superjson';
+declare class DefaultSuperJSON {
+    superJson: SuperJSON;
+    constructor();
+}
+declare const defaultSuperJSON: DefaultSuperJSON;
+export declare function initJsonConvert(): void;
+export declare function serialize(object: Parameters<typeof defaultSuperJSON.superJson.serialize>[0], compress?: boolean): string | SuperJSONResult;
+export declare function deserialize<T = unknown>(payload: SuperJSONResult & {
+    __compress?: boolean;
+}): T;
+export {};