virlen-remote 0.1.0

package/dist/protocol/endpoint.d.ts

@@ -0,0 +1,76 @@
+import type { Transport, TransportState } from '../transport/types.js';
+export interface CallContext {
+    readonly requestId: string;
+    readonly method: string;
+    readonly origin: 'remote';
+}
+export interface EventContext {
+    readonly topic: string;
+    readonly origin: 'remote';
+}
+export type RpcHandler = (params: unknown, ctx: CallContext) => unknown | Promise<unknown>;
+export type EventSubscriber = (payload: unknown, ctx: EventContext) => void;
+export interface CallOptions {
+    timeoutMs?: number;
+}
+export interface EndpointOptions {
+    transport: Transport;
+    /** 协议层默认超时；可随 hello 协商调整（§3.2）。 <=0 表示不超时。 */
+    defaultTimeoutMs?: number;
+    maxFramePayload?: number;
+    /** 幂等去重表容量（LRU）。 */
+    dedupeSize?: number;
+    /** 幂等去重表存活时间。 */
+    dedupeTtlMs?: number;
+}
+export declare class Endpoint {
+    private readonly transport;
+    private readonly defaultTimeoutMs;
+    private readonly maxFramePayload;
+    private readonly dedupeSize;
+    private readonly dedupeTtlMs;
+    private readonly handlers;
+    private readonly subscribers;
+    private readonly pending;
+    /** requestId → 上次结果（插入序即 LRU 淘汰序）。 */
+    private readonly dedupe;
+    private readonly reassembler;
+    private readonly detachers;
+    private msgId;
+    private lastState;
+    private disposed;
+    constructor(options: EndpointOptions);
+    /** 注册一个 handler；返回注销函数。 */
+    handle(method: string, fn: RpcHandler): () => void;
+    /** 订阅一个 topic；返回取消订阅函数。 */
+    subscribe(topic: string, fn: EventSubscriber): () => void;
+    /**
+     * 发起一次 RPC。链路非 open → **立即失败**（不发请求、不等待）。
+     * 长任务不要等它 resolve：见 §3.3，`host.session.send` 只回「投递确认」，过程靠事件推。
+     */
+    call(method: string, params?: unknown, options?: CallOptions): Promise<unknown>;
+    /** 发出一个事件（fire-and-forget）；返回是否发出。 */
+    emit(topic: string, payload?: unknown): boolean;
+    /** 发送一个心跳 ping（pong 由对端应答）。 */
+    ping(): boolean;
+    dispose(reason?: string): void;
+    get pendingCount(): number;
+    get transportState(): TransportState;
+    private onFrame;
+    private onCall;
+    private onResult;
+    private onEvent;
+    private onCtrl;
+    private onState;
+    /** 链路恢复：未决的 CALL 用同一 requestId 重发（对端靠去重表返回上次结果）。 */
+    private replayPending;
+    private finishCall;
+    private sendResult;
+    private sendCtrl;
+    private sendFrames;
+    private nextMsgId;
+    private clearPendingTimer;
+    private lookupDedupe;
+    private rememberDedupe;
+}
+//# sourceMappingURL=endpoint.d.ts.map

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

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

package/dist/protocol/endpoint.js

@@ -0,0 +1,307 @@
+/**
+ * Endpoint —— 协议层核心：把「四类接口」统一为 **2 个原语 × 2 个方向**
+ * （docs/phone-control-bridge.md §2.1）。
+ *
+ * ```
+ * handle(method, fn)      我实现的、供对方调用      ← 请求接口
+ * subscribe(topic, fn)    我订阅的、对方发来的事件  ← 事件接口
+ * call(method, params)    我发起的调用              ← 服务接口
+ * emit(topic, payload)    我发出的事件              ← 事件接口
+ * ```
+ * 四类接口是本形状的特例；各写一个模块会得到 4 份重复的序列化/超时/重连代码，且行为必然漂移。
+ *
+ * 内置可靠性（§3.2）：
+ * - **分片**：载荷 > 12KB 自动分片，接收侧按 msgId 归组，不完整则整体丢弃；
+ * - **幂等**：收到的 CALL 按 `requestId` 去重（LRU + TTL），命中则**回上次结果而非重放**；
+ * - **重连重放**：链路恢复时，未决的 CALL 用**同一 requestId** 重发 → 对端去重，避免重复执行；
+ * - **超时分层**：链路非 open → 立即 `E_TRANSPORT`；协议层默认 10s（可随 hello 协商调整）。
+ */
+import { BridgeError, toBridgeError } from './errors.js';
+import { DEFAULT_MAX_FRAME_PAYLOAD, FrameKind, Reassembler, encodeFrames, PROTOCOL_VERSION } from './frame.js';
+import { newRequestId } from './ids.js';
+const DEFAULT_TIMEOUT_MS = 10000;
+const DEFAULT_DEDUPE_SIZE = 200;
+const DEFAULT_DEDUPE_TTL_MS = 5 * 60000;
+export class Endpoint {
+    constructor(options) {
+        this.handlers = new Map();
+        this.subscribers = new Map();
+        this.pending = new Map();
+        /** requestId → 上次结果（插入序即 LRU 淘汰序）。 */
+        this.dedupe = new Map();
+        this.reassembler = new Reassembler();
+        this.detachers = [];
+        this.msgId = 0;
+        this.disposed = false;
+        this.transport = options.transport;
+        this.defaultTimeoutMs = options.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.maxFramePayload = options.maxFramePayload ?? DEFAULT_MAX_FRAME_PAYLOAD;
+        this.dedupeSize = options.dedupeSize ?? DEFAULT_DEDUPE_SIZE;
+        this.dedupeTtlMs = options.dedupeTtlMs ?? DEFAULT_DEDUPE_TTL_MS;
+        this.lastState = options.transport.state;
+        this.detachers.push(this.transport.onMessage((bytes) => this.onFrame(bytes)));
+        this.detachers.push(this.transport.onStateChange((state) => this.onState(state)));
+    }
+    // ───────────────────────────── 我实现的、供对方调用 ─────────────────────────────
+    /** 注册一个 handler；返回注销函数。 */
+    handle(method, fn) {
+        this.handlers.set(method, fn);
+        return () => {
+            if (this.handlers.get(method) === fn)
+                this.handlers.delete(method);
+        };
+    }
+    /** 订阅一个 topic；返回取消订阅函数。 */
+    subscribe(topic, fn) {
+        let set = this.subscribers.get(topic);
+        if (!set) {
+            set = new Set();
+            this.subscribers.set(topic, set);
+        }
+        set.add(fn);
+        return () => {
+            set.delete(fn);
+            if (set.size === 0)
+                this.subscribers.delete(topic);
+        };
+    }
+    // ───────────────────────────── 我发起的调用 / 我发出的事件 ─────────────────────────────
+    /**
+     * 发起一次 RPC。链路非 open → **立即失败**（不发请求、不等待）。
+     * 长任务不要等它 resolve：见 §3.3，`host.session.send` 只回「投递确认」，过程靠事件推。
+     */
+    call(method, params, options) {
+        if (this.disposed) {
+            return Promise.reject(new BridgeError('E_INTERNAL', 'endpoint disposed'));
+        }
+        if (this.transport.state !== 'open') {
+            return Promise.reject(new BridgeError('E_TRANSPORT', `transport is ${this.transport.state}`));
+        }
+        const requestId = newRequestId();
+        const call = { requestId, method, params };
+        const frames = encodeFrames(FrameKind.CALL, this.nextMsgId(), call, this.maxFramePayload);
+        return new Promise((resolve, reject) => {
+            const entry = { requestId, method, frames, resolve, reject };
+            const timeoutMs = options?.timeoutMs ?? this.defaultTimeoutMs;
+            if (Number.isFinite(timeoutMs) && timeoutMs > 0) {
+                entry.timer = setTimeout(() => {
+                    if (this.pending.delete(requestId)) {
+                        reject(new BridgeError('E_TIMEOUT', `${method} timed out after ${timeoutMs}ms`));
+                    }
+                }, timeoutMs);
+            }
+            this.pending.set(requestId, entry);
+            this.sendFrames(frames);
+        });
+    }
+    /** 发出一个事件（fire-and-forget）；返回是否发出。 */
+    emit(topic, payload) {
+        if (this.disposed || this.transport.state !== 'open')
+            return false;
+        const event = { topic, payload };
+        this.sendFrames(encodeFrames(FrameKind.EVENT, this.nextMsgId(), event, this.maxFramePayload));
+        return true;
+    }
+    /** 发送一个心跳 ping（pong 由对端应答）。 */
+    ping() {
+        if (this.disposed || this.transport.state !== 'open')
+            return false;
+        this.sendCtrl({ subtype: 'ping', ts: Date.now() });
+        return true;
+    }
+    dispose(reason = 'endpoint disposed') {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        for (const detach of this.detachers) {
+            try {
+                detach();
+            }
+            catch {
+                /* 忽略 */
+            }
+        }
+        const error = new BridgeError('E_TRANSPORT', reason);
+        for (const entry of this.pending.values()) {
+            this.clearPendingTimer(entry);
+            entry.reject(error);
+        }
+        this.pending.clear();
+    }
+    get pendingCount() {
+        return this.pending.size;
+    }
+    get transportState() {
+        return this.transport.state;
+    }
+    // ───────────────────────────── 接收入口 ─────────────────────────────
+    onFrame(bytes) {
+        if (this.disposed)
+            return;
+        let message;
+        try {
+            message = this.reassembler.accept(bytes);
+        }
+        catch {
+            // 坏帧/坏分片直接丢弃，不影响后续
+            return;
+        }
+        if (!message)
+            return;
+        if (message.header.version !== PROTOCOL_VERSION)
+            return; // 版本不符：丢弃
+        switch (message.header.kind) {
+            case FrameKind.CALL:
+                void this.onCall(message.payload);
+                break;
+            case FrameKind.RESULT:
+                this.onResult(message.payload);
+                break;
+            case FrameKind.EVENT:
+                this.onEvent(message.payload);
+                break;
+            case FrameKind.CTRL:
+                this.onCtrl(message.payload);
+                break;
+        }
+    }
+    async onCall(call) {
+        if (!call || typeof call.requestId !== 'string' || typeof call.method !== 'string')
+            return;
+        // 幂等：命中去重表则回上次结果，**不重放**
+        const cached = this.lookupDedupe(call.requestId);
+        if (cached) {
+            this.sendResult(cached.result);
+            return;
+        }
+        const handler = this.handlers.get(call.method);
+        if (!handler) {
+            this.finishCall(call.requestId, {
+                requestId: call.requestId,
+                ok: false,
+                error: new BridgeError('E_UNSUPPORTED', `unsupported method: ${call.method}`).toWire(),
+            });
+            return;
+        }
+        let result;
+        try {
+            const data = await handler(call.params, {
+                requestId: call.requestId,
+                method: call.method,
+                origin: 'remote',
+            });
+            result = { requestId: call.requestId, ok: true, data };
+        }
+        catch (err) {
+            const error = toBridgeError(err);
+            result = { requestId: call.requestId, ok: false, error: error.toWire() };
+        }
+        this.finishCall(call.requestId, result);
+    }
+    onResult(result) {
+        if (!result || typeof result.requestId !== 'string')
+            return;
+        const entry = this.pending.get(result.requestId);
+        if (!entry)
+            return; // 未知/超时后的迟到响应：忽略
+        this.pending.delete(result.requestId);
+        this.clearPendingTimer(entry);
+        if (result.ok) {
+            entry.resolve(result.data);
+        }
+        else if (result.error) {
+            entry.reject(BridgeError.fromWire(result.error));
+        }
+        else {
+            entry.reject(new BridgeError('E_INTERNAL', 'malformed RESULT (ok=false without error)'));
+        }
+    }
+    onEvent(event) {
+        if (!event || typeof event.topic !== 'string')
+            return;
+        const set = this.subscribers.get(event.topic);
+        if (!set)
+            return;
+        const ctx = { topic: event.topic, origin: 'remote' };
+        for (const fn of [...set]) {
+            try {
+                fn(event.payload, ctx);
+            }
+            catch {
+                // 单个订阅者抛错不得中断分发
+            }
+        }
+    }
+    onCtrl(ctrl) {
+        if (!ctrl || typeof ctrl.subtype !== 'string')
+            return;
+        if (ctrl.subtype === 'ping') {
+            this.sendCtrl({ subtype: 'pong', ts: ctrl.ts });
+        }
+        // 'pong' 由心跳逻辑消费（M2/M3）；一期无自动心跳
+    }
+    // ───────────────────────────── 内部工具 ─────────────────────────────
+    onState(state) {
+        const was = this.lastState;
+        this.lastState = state;
+        if (state === 'open' && was !== 'open') {
+            // 断线期间的分片已失效，重置归组器再重放
+            this.reassembler.reset();
+            this.replayPending();
+        }
+    }
+    /** 链路恢复：未决的 CALL 用同一 requestId 重发（对端靠去重表返回上次结果）。 */
+    replayPending() {
+        for (const entry of this.pending.values()) {
+            this.sendFrames(entry.frames);
+        }
+    }
+    finishCall(requestId, result) {
+        this.rememberDedupe(requestId, result);
+        this.sendResult(result);
+    }
+    sendResult(result) {
+        this.sendFrames(encodeFrames(FrameKind.RESULT, this.nextMsgId(), result, this.maxFramePayload));
+    }
+    sendCtrl(ctrl) {
+        this.sendFrames(encodeFrames(FrameKind.CTRL, this.nextMsgId(), ctrl, this.maxFramePayload));
+    }
+    sendFrames(frames) {
+        if (this.transport.state !== 'open')
+            return;
+        for (const frame of frames)
+            this.transport.send(frame);
+    }
+    nextMsgId() {
+        this.msgId = (this.msgId + 1) >>> 0;
+        if (this.msgId === 0)
+            this.msgId = 1;
+        return this.msgId;
+    }
+    clearPendingTimer(entry) {
+        if (entry.timer !== undefined) {
+            clearTimeout(entry.timer);
+            entry.timer = undefined;
+        }
+    }
+    lookupDedupe(requestId) {
+        const entry = this.dedupe.get(requestId);
+        if (!entry)
+            return undefined;
+        if (Date.now() - entry.at > this.dedupeTtlMs) {
+            this.dedupe.delete(requestId);
+            return undefined;
+        }
+        return entry;
+    }
+    rememberDedupe(requestId, result) {
+        this.dedupe.set(requestId, { result, at: Date.now() });
+        while (this.dedupe.size > this.dedupeSize) {
+            const oldest = this.dedupe.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.dedupe.delete(oldest);
+        }
+    }
+}
+//# sourceMappingURL=endpoint.js.map

package/dist/protocol/endpoint.js.map

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

package/dist/protocol/errors.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 错误模型（见 docs/phone-control-bridge.md §3.4）。
+ *
+ * 只有 `retryable === true` 才允许 UI 给「重试」按钮。
+ * `E_UNSUPPORTED` 是**版本兼容的关键**：老手机调新方法 → 明确报错 → UI 隐藏该功能，
+ * **永远不要靠版本号 if-else 分支**。
+ */
+export type ErrorCode = 'E_BAD_REQUEST' | 'E_NOT_FOUND' | 'E_DENIED' | 'E_UNSUPPORTED' | 'E_BUSY' | 'E_CONFLICT' | 'E_CONFIRM_REQUIRED' | 'E_TIMEOUT' | 'E_INTERNAL' | 'E_TRANSPORT' | 'E_REPLACED';
+/** 线上（wire）错误形态 —— 可序列化为 JSON。 */
+export interface WireError {
+    code: ErrorCode;
+    message: string;
+    retryable: boolean;
+    data?: unknown;
+}
+export interface BridgeErrorOptions {
+    retryable?: boolean;
+    data?: unknown;
+    cause?: unknown;
+}
+export declare class BridgeError extends Error {
+    readonly code: ErrorCode;
+    readonly retryable: boolean;
+    readonly data?: unknown;
+    constructor(code: ErrorCode, message: string, options?: BridgeErrorOptions);
+    toWire(): WireError;
+    static fromWire(w: WireError): BridgeError;
+    static is(value: unknown): value is BridgeError;
+}
+/** 把任意抛出物归一为 BridgeError（非 BridgeError 一律按 E_INTERNAL 处理）。 */
+export declare function toBridgeError(err: unknown): BridgeError;
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/protocol/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,SAAS,GACjB,eAAe,GACf,aAAa,GACb,UAAU,GACV,eAAe,GACf,QAAQ,GACR,YAAY,GACZ,oBAAoB,GACpB,WAAW,GACX,YAAY,GACZ,aAAa,GACb,YAAY,CAAA;AAEhB,kCAAkC;AAClC,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,SAAS,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,OAAO,CAAA;IAClB,IAAI,CAAC,EAAE,OAAO,CAAA;CACf;AAgBD,MAAM,WAAW,kBAAkB;IACjC,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;IAEvB,YAAY,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,EAUzE;IAED,MAAM,IAAI,SAAS,CAOlB;IAED,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,SAAS,GAAG,WAAW,CAEzC;IAED,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAE9C;CACF;AAED,8DAA8D;AAC9D,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,WAAW,CAIvD"}

package/dist/protocol/errors.js

@@ -0,0 +1,56 @@
+/**
+ * 错误模型（见 docs/phone-control-bridge.md §3.4）。
+ *
+ * 只有 `retryable === true` 才允许 UI 给「重试」按钮。
+ * `E_UNSUPPORTED` 是**版本兼容的关键**：老手机调新方法 → 明确报错 → UI 隐藏该功能，
+ * **永远不要靠版本号 if-else 分支**。
+ */
+const RETRYABLE = {
+    E_BAD_REQUEST: false,
+    E_NOT_FOUND: false,
+    E_DENIED: false,
+    E_UNSUPPORTED: false,
+    E_BUSY: true,
+    E_CONFLICT: false,
+    E_CONFIRM_REQUIRED: false,
+    E_TIMEOUT: true,
+    E_INTERNAL: false,
+    E_TRANSPORT: true,
+    E_REPLACED: false,
+};
+export class BridgeError extends Error {
+    constructor(code, message, options) {
+        super(message);
+        this.name = 'BridgeError';
+        this.code = code;
+        this.retryable = options?.retryable ?? RETRYABLE[code] ?? false;
+        this.data = options?.data;
+        if (options?.cause !== undefined) {
+            // 避免依赖 ES2022 的 ErrorOptions，直接挂 cause 字段
+            ;
+            this.cause = options.cause;
+        }
+    }
+    toWire() {
+        return {
+            code: this.code,
+            message: this.message,
+            retryable: this.retryable,
+            ...(this.data !== undefined ? { data: this.data } : {}),
+        };
+    }
+    static fromWire(w) {
+        return new BridgeError(w.code, w.message, { retryable: w.retryable, data: w.data });
+    }
+    static is(value) {
+        return value instanceof BridgeError;
+    }
+}
+/** 把任意抛出物归一为 BridgeError（非 BridgeError 一律按 E_INTERNAL 处理）。 */
+export function toBridgeError(err) {
+    if (err instanceof BridgeError)
+        return err;
+    const message = err instanceof Error ? err.message : String(err);
+    return new BridgeError('E_INTERNAL', message, { cause: err });
+}
+//# sourceMappingURL=errors.js.map

package/dist/protocol/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/protocol/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAuBH,MAAM,SAAS,GAA+B;IAC5C,aAAa,EAAE,KAAK;IACpB,WAAW,EAAE,KAAK;IAClB,QAAQ,EAAE,KAAK;IACf,aAAa,EAAE,KAAK;IACpB,MAAM,EAAE,IAAI;IACZ,UAAU,EAAE,KAAK;IACjB,kBAAkB,EAAE,KAAK;IACzB,SAAS,EAAE,IAAI;IACf,UAAU,EAAE,KAAK;IACjB,WAAW,EAAE,IAAI;IACjB,UAAU,EAAE,KAAK;CAClB,CAAA;AAQD,MAAM,OAAO,WAAY,SAAQ,KAAK;IAKpC,YAAY,IAAe,EAAE,OAAe,EAAE,OAA4B;QACxE,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,aAAa,CAAA;QACzB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,SAAS,GAAG,OAAO,EAAE,SAAS,IAAI,SAAS,CAAC,IAAI,CAAC,IAAI,KAAK,CAAA;QAC/D,IAAI,CAAC,IAAI,GAAG,OAAO,EAAE,IAAI,CAAA;QACzB,IAAI,OAAO,EAAE,KAAK,KAAK,SAAS,EAAE,CAAC;YACjC,0CAA0C;YAC1C,CAAC;YAAC,IAA4B,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAA;QACtD,CAAC;IACH,CAAC;IAED,MAAM;QACJ,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACxD,CAAA;IACH,CAAC;IAED,MAAM,CAAC,QAAQ,CAAC,CAAY;QAC1B,OAAO,IAAI,WAAW,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAA;IACrF,CAAC;IAED,MAAM,CAAC,EAAE,CAAC,KAAc;QACtB,OAAO,KAAK,YAAY,WAAW,CAAA;IACrC,CAAC;CACF;AAED,8DAA8D;AAC9D,MAAM,UAAU,aAAa,CAAC,GAAY;IACxC,IAAI,GAAG,YAAY,WAAW;QAAE,OAAO,GAAG,CAAA;IAC1C,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;IAChE,OAAO,IAAI,WAAW,CAAC,YAAY,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAA;AAC/D,CAAC"}

package/dist/protocol/frame.d.ts

@@ -0,0 +1,51 @@
+export declare const PROTOCOL_VERSION = 1;
+export declare const HEADER_SIZE = 12;
+/** 超过该阈值的载荷即分片（见 §3.2）。 */
+export declare const DEFAULT_MAX_FRAME_PAYLOAD: number;
+export declare const FrameKind: {
+    readonly CALL: 1;
+    readonly RESULT: 2;
+    readonly EVENT: 3;
+    readonly CTRL: 4;
+};
+export type FrameKind = (typeof FrameKind)[keyof typeof FrameKind];
+export interface FrameHeader {
+    version: number;
+    kind: FrameKind;
+    chunkIndex: number;
+    chunkCount: number;
+    flags: number;
+    msgId: number;
+}
+/** 一个已完整还原的逻辑消息。 */
+export interface DecodedMessage<T = unknown> {
+    header: FrameHeader;
+    payload: T;
+}
+export declare function encodeHeader(header: FrameHeader): Uint8Array;
+export declare function decodeHeader(bytes: Uint8Array, offset?: number): FrameHeader;
+/** 读取帧体（不含头）。 */
+export declare function frameBody(frame: Uint8Array): Uint8Array;
+/**
+ * 把一条逻辑消息编码为 1..N 个帧。载荷 > `maxFramePayload` 时自动分片。
+ * 返回的数组顺序即分片顺序（chunkIndex 0..n-1）。
+ */
+export declare function encodeFrames(kind: FrameKind, msgId: number, payload: unknown, maxFramePayload?: number): Uint8Array[];
+/**
+ * 分片归组器 —— 按 `msgId` 收集分片，**完整才交付**（不完整则整体丢弃，不做部分应用）。
+ *
+ * 天然容忍：分片乱序、多条消息交错（不同 msgId 各自独立累积）。
+ */
+export declare class Reassembler {
+    private readonly maxPartials;
+    private readonly partials;
+    constructor(maxPartials?: number);
+    /** 喂入一帧；返回已完整还原的消息，否则 null。 */
+    accept(frame: Uint8Array): DecodedMessage | null;
+    /** 正在等待后续分片的逻辑消息数（诊断用）。 */
+    get pendingCount(): number;
+    reset(): void;
+    private decodePayload;
+    private evictOldest;
+}
+//# sourceMappingURL=frame.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"frame.d.ts","sourceRoot":"","sources":["../../src/protocol/frame.ts"],"names":[],"mappings":"AAoBA,eAAO,MAAM,gBAAgB,IAAI,CAAA;AACjC,eAAO,MAAM,WAAW,KAAK,CAAA;AAC7B,2BAA2B;AAC3B,eAAO,MAAM,yBAAyB,QAAY,CAAA;AAElD,eAAO,MAAM,SAAS;aACpB,IAAI,EAAE,CAAC;aACP,MAAM,EAAE,CAAC;aACT,KAAK,EAAE,CAAC;aACR,IAAI,EAAE,CAAC;CACC,CAAA;AACV,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,OAAO,SAAS,CAAC,CAAA;AAOlE,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,SAAS,CAAA;IACf,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;CACd;AAED,oBAAoB;AACpB,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,OAAO;IACzC,MAAM,EAAE,WAAW,CAAA;IACnB,OAAO,EAAE,CAAC,CAAA;CACX;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,UAAU,CAU5D;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,SAAI,GAAG,WAAW,CAavE;AAED,iBAAiB;AACjB,wBAAgB,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAEvD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,SAAS,EACf,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,OAAO,EAChB,eAAe,GAAE,MAAkC,GAClD,UAAU,EAAE,CAgBd;AAQD;;;;GAIG;AACH,qBAAa,WAAW;IAGV,OAAO,CAAC,QAAQ,CAAC,WAAW;IAFxC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoC;IAE7D,YAA6B,WAAW,SAAK,EAAI;IAEjD,+BAA+B;IAC/B,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,cAAc,GAAG,IAAI,CAgC/C;IAED,2BAA2B;IAC3B,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,KAAK,IAAI,IAAI,CAEZ;IAED,OAAO,CAAC,aAAa;IAKrB,OAAO,CAAC,WAAW;CAIpB"}