virlen-remote 0.1.0

package/dist/protocol/identity.js

@@ -0,0 +1,143 @@
+/**
+ * 设备身份与授权凭证（M6，见 docs/phone-control-bridge.md §30）。
+ *
+ * 一句话：**设备 key 是「谁」，授权凭证是「凭什么是它」。**
+ *
+ * - **设备 key**：首次运行生成一次，之后**持久化不变**（手机写 localStorage，电脑写
+ *   `<data_dir>/phone-device.json`）。它不是硬件指纹 —— 见 §30.1 的取舍说明：
+ *   PWA 拿不到可靠的硬件指纹（浏览器升级 / 隐私模式 / 清数据即变，同型号还会撞），
+ *   所以唯一能同时满足「不重复」与「重新获取还是同一个」的做法就是随机生成 + 落盘。
+ * - **房间号**由电脑设备 key 派生（`roomFor`）：于是「第二次连接」只需要拿电脑 key 去问
+ *   信令服务「这台电脑在不在线」，不必再扫码。
+ * - **授权凭证**（grant）：由**电脑端**签发，绑定手机设备 key，默认 30 天有效、
+ *   每次成功连接**滑动续期**，但单次签发最长 `GRANT_MAX_LIFETIME_MS`（90 天）——
+ *   到顶后必须重新扫码授权（用户 2026-09-27 拍板）。
+ *
+ * 本模块**零依赖、两端同一份**：电脑端与手机端都必须用这里的常量与判定函数，
+ * 否则必然出现「一端认为有效、另一端认为过期」的分叉（§18.5 的教训）。
+ */
+/** 电脑设备 key 前缀（desktop key）。 */
+export const HOST_KEY_PREFIX = 'dk-';
+/** 手机设备 key 前缀（mobile key）。 */
+export const MOBILE_KEY_PREFIX = 'mk-';
+/** 授权凭证前缀（grant）。 */
+export const GRANT_PREFIX = 'gt-';
+/** 授权凭证的单次续期时长（30 天）。 */
+export const GRANT_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+/**
+ * 单次签发的**最长寿命**（90 天，从 `issuedAt` 起算）。
+ *
+ * 为什么要有硬上限：滑动续期若没有上限，一个凭证就等于永久授权 —— 手机丢失/被借用时
+ * 电脑端的「移除」是唯一刹车，而用户未必想得起来去看那张列表。
+ */
+export const GRANT_MAX_LIFETIME_MS = 90 * 24 * 60 * 60 * 1000;
+/** 房间名前缀（信令层）。与 M3 起的旧房间名同构：`virlen:<电脑标识>`。 */
+export const ROOM_PREFIX = 'virlen:';
+/** 生成 `prefix + 十六进制随机串`（默认 16 字节 = 32 hex）。 */
+export function randomKey(prefix, bytes = 16) {
+    const buf = new Uint8Array(bytes);
+    const c = globalThis.crypto;
+    if (c && typeof c.getRandomValues === 'function') {
+        c.getRandomValues(buf);
+    }
+    else {
+        // 无 WebCrypto 的环境（老 Node / 极端降级）：Math.random 兜底。
+        // ⚠️ 只用于「本地身份标识」，不是加密码 —— 真正的安全边界是授权凭证与电脑端确认弹窗。
+        for (let i = 0; i < buf.length; i += 1)
+            buf[i] = Math.floor(Math.random() * 256);
+    }
+    let out = prefix;
+    for (const b of buf)
+        out += b.toString(16).padStart(2, '0');
+    return out;
+}
+/** 生成一个设备 key（`host` → `dk-…`，`mobile` → `mk-…`）。 */
+export function newDeviceKey(kind) {
+    return randomKey(kind === 'host' ? HOST_KEY_PREFIX : MOBILE_KEY_PREFIX);
+}
+/** 生成一个授权凭证串。 */
+export function newGrantToken() {
+    return randomKey(GRANT_PREFIX, 24);
+}
+const KEY_RE = /^(dk|mk)-[0-9a-f]{8,64}$/;
+/**
+ * 是否为合法设备 key。`kind` 不传则不校验前缀归属。
+ *
+ * 只用于**早期拒掉明显是垃圾的输入**（日志可读、列表可渲染），不是安全校验 ——
+ * 真正的授权判定在电脑端的凭证表。
+ */
+export function isDeviceKey(value, kind) {
+    if (typeof value !== 'string' || !KEY_RE.test(value))
+        return false;
+    if (!kind)
+        return true;
+    return value.startsWith(kind === 'host' ? HOST_KEY_PREFIX : MOBILE_KEY_PREFIX);
+}
+/**
+ * 电脑设备 key → 信令房间号。
+ *
+ * ⚠️ 兼容 M3 的旧房间名：旧 `hostId`（如 `host-ab12cd34`，无前缀）传进来同样得到
+ * `virlen:host-ab12cd34` —— 与旧实现逐字一致，于是**旧二维码仍然可用**（§30.6）。
+ */
+export function roomFor(hostKey) {
+    return ROOM_PREFIX + hostKey;
+}
+/** 房间号 → 电脑设备 key（非本前缀派生时返回 `null`）。 */
+export function hostKeyFromRoom(room) {
+    if (typeof room !== 'string' || !room.startsWith(ROOM_PREFIX))
+        return null;
+    const key = room.slice(ROOM_PREFIX.length);
+    return key ? key : null;
+}
+/** 签发一条新凭证（`now` 可注入，便于测试）。 */
+export function issueGrant(now = Date.now()) {
+    return {
+        token: newGrantToken(),
+        issuedAt: now,
+        expiresAt: now + GRANT_TTL_MS,
+        lastSeenAt: now,
+    };
+}
+/** 凭证是否已过期。 */
+export function isGrantExpired(grant, now = Date.now()) {
+    return now >= grant.expiresAt;
+}
+/**
+ * 滑动续期：把到期时间推后到 `now + 30 天`，但**不超过** `issuedAt + 90 天`。
+ *
+ * 返回新对象（不原地改），调用方负责持久化 —— 「算」与「存」分开，便于测试与审计。
+ */
+export function renewGrant(grant, now = Date.now()) {
+    const cap = grant.issuedAt + GRANT_MAX_LIFETIME_MS;
+    return {
+        ...grant,
+        expiresAt: Math.min(now + GRANT_TTL_MS, cap),
+        lastSeenAt: now,
+    };
+}
+/**
+ * 凭证可用性判定（**两端共用**）。
+ * 返回 `null` = 可用；否则是拒绝原因。
+ */
+export function checkGrant(grant, now = Date.now()) {
+    if (!grant || typeof grant.token !== 'string' || !grant.token)
+        return 'invalid';
+    if (isGrantExpired(grant, now))
+        return 'expired';
+    return null;
+}
+/** 剩余有效期的自然语言（两端 UI 共用同一套口径，避免「还剩 3 天」与「2.9 天」打架）。 */
+export function describeGrantRemaining(grant, now = Date.now()) {
+    const left = grant.expiresAt - now;
+    if (left <= 0)
+        return '已过期';
+    const days = Math.floor(left / (24 * 60 * 60 * 1000));
+    if (days >= 1)
+        return `剩余 ${days} 天`;
+    const hours = Math.floor(left / (60 * 60 * 1000));
+    if (hours >= 1)
+        return `剩余 ${hours} 小时`;
+    const minutes = Math.max(1, Math.floor(left / 60000));
+    return `剩余 ${minutes} 分钟`;
+}
+//# sourceMappingURL=identity.js.map

package/dist/protocol/identity.js.map

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

package/dist/protocol/ids.d.ts

@@ -0,0 +1,2 @@
+export declare function newRequestId(): string;
+//# sourceMappingURL=ids.d.ts.map

package/dist/protocol/ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../../src/protocol/ids.ts"],"names":[],"mappings":"AAWA,wBAAgB,YAAY,IAAI,MAAM,CAQrC"}

package/dist/protocol/ids.js

@@ -0,0 +1,20 @@
+/**
+ * requestId 生成 —— 零依赖。
+ *
+ * 用于 RPC 幂等（见 docs/phone-control-bridge.md §3.2）：手机网络会闪断，重连后必然重发，
+ * 电脑侧靠 requestId 去重、**返回上次结果而非重放**。
+ *
+ * 优先用 `crypto.randomUUID()`（浏览器安全上下文 / Node ≥ 19 均可用）；
+ * 退化为「时间戳 + 单调计数 + 随机」——**不用于安全用途**，仅需高概率唯一。
+ */
+let fallbackCounter = 0;
+export function newRequestId() {
+    const c = globalThis.crypto;
+    if (c && typeof c.randomUUID === 'function') {
+        return c.randomUUID();
+    }
+    fallbackCounter = (fallbackCounter + 1) >>> 0;
+    const rand = Math.random().toString(36).slice(2, 10);
+    return `${Date.now().toString(36)}-${fallbackCounter.toString(36)}-${rand}`;
+}
+//# sourceMappingURL=ids.js.map

package/dist/protocol/ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.js","sourceRoot":"","sources":["../../src/protocol/ids.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,IAAI,eAAe,GAAG,CAAC,CAAA;AAEvB,MAAM,UAAU,YAAY;IAC1B,MAAM,CAAC,GAAI,UAAkC,CAAC,MAAM,CAAA;IACpD,IAAI,CAAC,IAAI,OAAO,CAAC,CAAC,UAAU,KAAK,UAAU,EAAE,CAAC;QAC5C,OAAO,CAAC,CAAC,UAAU,EAAE,CAAA;IACvB,CAAC;IACD,eAAe,GAAG,CAAC,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,CAAA;IAC7C,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;IACpD,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,eAAe,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,IAAI,EAAE,CAAA;AAC7E,CAAC"}

package/dist/protocol/pairing.d.ts

@@ -0,0 +1,43 @@
+/** 当前载荷版本。v1 与 v2 形状相同（差异在语义：v2 起 `host` 是设备 key、`ticket` 是一次性票据）。 */
+export declare const PAIRING_PAYLOAD_VERSION = 2;
+/**
+ * 配对票据有效期（默认 5 分钟）。
+ *
+ * 用户反馈「扫码后提示二维码失效」时的值曾是 2 分钟；现在 **5 分钟 + 面板打开即重生成 +
+ * 到期自动重生成**（见 `phoneControlStore`）三管齐下，真机上基本不可能再扫到过期码。
+ */
+export declare const PAIRING_TICKET_TTL_MS: number;
+export interface PairingPayload {
+    v: number;
+    /** 电脑设备 key（也是房间号的来源）。 */
+    host: string;
+    /** 电脑显示名（手机列表里显示）。 */
+    name: string;
+    /** 一次性配对票据。 */
+    ticket: string;
+    /** 信令基址（如 `https://virlen.cn/api/rtc/`）。 */
+    signal?: string;
+    /** 信令房间号（缺省 `roomFor(host)`；旧码里带着它）。 */
+    room?: string;
+}
+/** 构造载荷（只填必要字段；`room` 交给两端各自派生，避免又多一处可漂移的冗余）。 */
+export declare function buildPairingPayload(input: {
+    host: string;
+    name: string;
+    ticket: string;
+    signal?: string;
+}): PairingPayload;
+/** 序列化为二维码内容。 */
+export declare function encodePairingPayload(payload: PairingPayload): string;
+/**
+ * 解析二维码 / 配对串。无法识别返回 `null`（调用方给「不是 Virlen 配对码」的文案）。
+ *
+ * 宽容点（都是真机上会遇到的东西）：
+ * - `v` 缺省按 1 处理（旧码）；
+ * - `name` 缺省回退 `host`；
+ * - `ticket` 允许是任意非空串（前缀只作可读性，不作校验 —— 电脑端的判定才是权威）。
+ */
+export declare function parsePairingPayload(text: string): PairingPayload | null;
+/** 载荷 → 房间号（显式 `room` 优先，否则由电脑 key 派生）。 */
+export declare function roomOfPayload(payload: PairingPayload): string;
+//# sourceMappingURL=pairing.d.ts.map

package/dist/protocol/pairing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pairing.d.ts","sourceRoot":"","sources":["../../src/protocol/pairing.ts"],"names":[],"mappings":"AAcA,sEAAsE;AACtE,eAAO,MAAM,uBAAuB,IAAI,CAAA;AAExC;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,QAAgB,CAAA;AAElD,MAAM,WAAW,cAAc;IAC7B,CAAC,EAAE,MAAM,CAAA;IACT,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,sBAAsB;IACtB,IAAI,EAAE,MAAM,CAAA;IACZ,eAAe;IACf,MAAM,EAAE,MAAM,CAAA;IACd,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,wCAAwC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,iDAAiD;AACjD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE;IACzC,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,GAAG,cAAc,CAQjB;AAED,iBAAiB;AACjB,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,CAEpE;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAqBvE;AAED,2CAA2C;AAC3C,wBAAgB,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,CAE7D"}

package/dist/protocol/pairing.js

@@ -0,0 +1,78 @@
+/**
+ * 配对载荷（二维码 / 配对串的内容）—— **两端同一份**（M6，见 docs/phone-control-bridge.md §30.2）。
+ *
+ * 为什么搬到共享包：此前电脑端 `pairingPayload()` 与手机端 `parsePayload()` 各写一份 interface，
+ * 字段含义靠注释对齐 —— 这类「契约写两份」的分叉只会在真机上暴露（§26/§29 都是这个形状的缺陷）。
+ *
+ * 字段：
+ * - `host`：**电脑设备 key**（`dk-…`；M3 的旧码是 `host-…`，同样能解析）。
+ * - `ticket`：**一次性**配对票据（不是长期凭证！兑换后电脑端签发 `grant` 回传，见 §30.3）。
+ * - `signal`：信令基址；缺省 = 同源 Broadcast 联调（生产必有）。
+ * - `room`：信令房间号；**缺省由 `roomFor(host)` 派生**。保留字段只为兼容旧码。
+ */
+import { roomFor } from './identity.js';
+/** 当前载荷版本。v1 与 v2 形状相同（差异在语义：v2 起 `host` 是设备 key、`ticket` 是一次性票据）。 */
+export const PAIRING_PAYLOAD_VERSION = 2;
+/**
+ * 配对票据有效期（默认 5 分钟）。
+ *
+ * 用户反馈「扫码后提示二维码失效」时的值曾是 2 分钟；现在 **5 分钟 + 面板打开即重生成 +
+ * 到期自动重生成**（见 `phoneControlStore`）三管齐下，真机上基本不可能再扫到过期码。
+ */
+export const PAIRING_TICKET_TTL_MS = 5 * 60 * 1000;
+/** 构造载荷（只填必要字段；`room` 交给两端各自派生，避免又多一处可漂移的冗余）。 */
+export function buildPairingPayload(input) {
+    return {
+        v: PAIRING_PAYLOAD_VERSION,
+        host: input.host,
+        name: input.name,
+        ticket: input.ticket,
+        ...(input.signal ? { signal: input.signal } : {}),
+    };
+}
+/** 序列化为二维码内容。 */
+export function encodePairingPayload(payload) {
+    return JSON.stringify(payload);
+}
+/**
+ * 解析二维码 / 配对串。无法识别返回 `null`（调用方给「不是 Virlen 配对码」的文案）。
+ *
+ * 宽容点（都是真机上会遇到的东西）：
+ * - `v` 缺省按 1 处理（旧码）；
+ * - `name` 缺省回退 `host`；
+ * - `ticket` 允许是任意非空串（前缀只作可读性，不作校验 —— 电脑端的判定才是权威）。
+ */
+export function parsePairingPayload(text) {
+    if (typeof text !== 'string' || !text.trim())
+        return null;
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const obj = raw;
+    if (typeof obj.host !== 'string' || !obj.host.trim())
+        return null;
+    if (typeof obj.ticket !== 'string' || !obj.ticket.trim())
+        return null;
+    const payload = {
+        v: typeof obj.v === 'number' ? obj.v : 1,
+        host: obj.host.trim(),
+        name: typeof obj.name === 'string' && obj.name.trim() ? obj.name.trim() : obj.host.trim(),
+        ticket: obj.ticket.trim(),
+    };
+    if (typeof obj.signal === 'string' && obj.signal.trim())
+        payload.signal = obj.signal.trim();
+    if (typeof obj.room === 'string' && obj.room.trim())
+        payload.room = obj.room.trim();
+    return payload;
+}
+/** 载荷 → 房间号（显式 `room` 优先，否则由电脑 key 派生）。 */
+export function roomOfPayload(payload) {
+    return payload.room ?? roomFor(payload.host);
+}
+//# sourceMappingURL=pairing.js.map

package/dist/protocol/pairing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pairing.js","sourceRoot":"","sources":["../../src/protocol/pairing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAEpC,sEAAsE;AACtE,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAA;AAExC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAA;AAgBlD,iDAAiD;AACjD,MAAM,UAAU,mBAAmB,CAAC,KAKnC;IACC,OAAO;QACL,CAAC,EAAE,uBAAuB;QAC1B,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAClD,CAAA;AACH,CAAC;AAED,iBAAiB;AACjB,MAAM,UAAU,oBAAoB,CAAC,OAAuB;IAC1D,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAA;AAChC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE;QAAE,OAAO,IAAI,CAAA;IACzD,IAAI,GAAY,CAAA;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;IACxB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAA;IACb,CAAC;IACD,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAA;IAChD,MAAM,GAAG,GAAG,GAA8B,CAAA;IAC1C,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE;QAAE,OAAO,IAAI,CAAA;IACjE,IAAI,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE;QAAE,OAAO,IAAI,CAAA;IACrE,MAAM,OAAO,GAAmB;QAC9B,CAAC,EAAE,OAAO,GAAG,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACxC,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE;QACrB,IAAI,EAAE,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE;QACzF,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE;KAC1B,CAAA;IACD,IAAI,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE;QAAE,OAAO,CAAC,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAA;IAC3F,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE;QAAE,OAAO,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAA;IACnF,OAAO,OAAO,CAAA;AAChB,CAAC;AAED,2CAA2C;AAC3C,MAAM,UAAU,aAAa,CAAC,OAAuB;IACnD,OAAO,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;AAC9C,CAAC"}

package/dist/testing/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `virlen-remote/testing` —— 测试/演示专用的宿主实现（**不进生产包**）。
+ */
+export { createMockHostDataSource } from './mock-host.js';
+export type { MockHostDataSource, MockHostOptions, MockInteractionSpec } from './mock-host.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAA;AACtD,YAAY,EAAE,kBAAkB,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA"}

package/dist/testing/index.js

@@ -0,0 +1,5 @@
+/**
+ * `virlen-remote/testing` —— 测试/演示专用的宿主实现（**不进生产包**）。
+ */
+export { createMockHostDataSource } from './mock-host.js';
+//# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAA"}

package/dist/testing/mock-host.d.ts

@@ -0,0 +1,66 @@
+import type { HostDataSource, HostEmit } from '../protocol/host.js';
+import type { ApprovalTier } from '../protocol/api.js';
+export interface MockHostOptions {
+    /** 流式段数。 */
+    streamSteps?: number;
+    /** 每段间隔（ms）。 */
+    streamDelayMs?: number;
+    /**
+     * `demo-1` 的预置消息条数（默认 2）。
+     *
+     * 供分页验证 / harness 压测用：默认值下只有 2 条，永远触发不了「还有更早的消息」。
+     */
+    demoMessageCount?: number;
+    /**
+     * 给 `demo-1` 追加一条带工具名的工具消息（默认关：会改变默认消息条数，影响分页用例）。
+     *
+     * 打开后手机端能看到「工具 · list_files」气泡（harness 人工验证用）。
+     */
+    demoToolMessage?: boolean;
+}
+/** 构造演示用交互（供 harness / 单测触发手机端卡片）。 */
+export interface MockInteractionSpec {
+    kind?: 'choice' | 'authorization';
+    tier?: ApprovalTier;
+    sessionId?: string;
+    question?: string;
+    options?: string[];
+    multi?: boolean;
+    permName?: string;
+    title?: string;
+    subTitle?: string;
+    desc?: string;
+    hint?: string;
+    risk?: string;
+    sandboxBypass?: boolean;
+    presentation?: 'modal' | 'terminal';
+}
+export interface MockHostDataSource extends HostDataSource {
+    /** 由 harness / 测试在注册后回填（把 `HostEvents` 推给对端）。 */
+    bind(emit: HostEmit): void;
+    /** 推一个待应答交互给手机（返回其 `interactionId`）。 */
+    triggerInteraction(spec?: MockInteractionSpec): string;
+    /** 当前仍挂起的交互 id。 */
+    pendingInteractions(): string[];
+    /**
+     * 已收到的 RPC 方法名流水（M5）。
+     *
+     * 供单测断言「请求确实到达了电脑侧」—— 否则只能靠副作用反推，
+     * 而像 `cancel` 这种「无事发生」的方法就没有可观察的副作用。
+     */
+    readonly calls: string[];
+    /** 手动推一次上下文占用变化（模拟电脑侧使用量增长 / 压缩），供手机端 UI 联调。 */
+    bumpContext(sessionId: string, tokens: number): void;
+    /**
+     * 手动推一次「工具参数生成进度」（§27），供手机端 UI 联调 / 单测。
+     *
+     * 真实链路里由引擎的 `AgentEvent.tool_progress` 驱动 —— 那是 provider 在**累积 tool 参数**
+     * 期间唯一的事件（其余时间静默）。`progress = null` 表示清空（工具开始执行 / 本轮结束）。
+     */
+    setToolProgress(sessionId: string, progress: {
+        name: string;
+        chars: number;
+    } | null): void;
+}
+export declare function createMockHostDataSource(options?: MockHostOptions): MockHostDataSource;
+//# sourceMappingURL=mock-host.d.ts.map

package/dist/testing/mock-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-host.d.ts","sourceRoot":"","sources":["../../src/testing/mock-host.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAEhE,OAAO,KAAK,EAGV,YAAY,EAiBb,MAAM,iBAAiB,CAAA;AAGxB,MAAM,WAAW,eAAe;IAC9B,YAAY;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,gBAAgB;IAChB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAA;CAC1B;AAED,sCAAsC;AACtC,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,EAAE,QAAQ,GAAG,eAAe,CAAA;IACjC,IAAI,CAAC,EAAE,YAAY,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,YAAY,CAAC,EAAE,OAAO,GAAG,UAAU,CAAA;CACpC;AAED,MAAM,WAAW,kBAAmB,SAAQ,cAAc;IACxD,iDAAiD;IACjD,IAAI,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAA;IAC1B,wCAAwC;IACxC,kBAAkB,CAAC,IAAI,CAAC,EAAE,mBAAmB,GAAG,MAAM,CAAA;IACtD,mBAAmB;IACnB,mBAAmB,IAAI,MAAM,EAAE,CAAA;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,CAAA;IACxB,gDAAgD;IAChD,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACpD;;;;;OAKG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,GAAG,IAAI,CAAA;CAC3F;AAWD,wBAAgB,wBAAwB,CAAC,OAAO,GAAE,eAAoB,GAAG,kBAAkB,CAqiB1F"}