@ckylinmc/mp-sdk 0.1.0

package/dist/ckylmp.js

@@ -0,0 +1,842 @@
+/**
+ * CKyLyn 小程序桥 TS SDK（单文件，零依赖）。
+ *
+ * 双通道（宿主侧实现见 `app/mp-lynx/src/main/java/in/ckyl/superapp/mplynx/bridge/`，
+ * 规范见 `app/docs/NATIVE_MODULES.md`）：
+ *
+ * 1. **事件桥**（兼容/交互，永久保留）：
+ *    - JS→宿主：`NativeModules.CkylMpBridge.invoke(msgid, event, payloadJson)`
+ *    - 宿主→JS 回执：`ckylinmp::reply` → `[msgid, event, ok, dataJson, errorJson]`
+ *    - 宿主→JS 推送：`ckylinmp::event` → `[event, dataJson]`（下载进度等）
+ *    回执按 msgid 关联（对齐旧版 apibridge.js 语义），默认 10s 超时。
+ * 2. **原生模块**（二进制/高频；byte[] ↔ ArrayBuffer 直达，无 base64）：
+ *    - `NativeModules.CkylMpFile.{readBytes,saveBytes,scopeReadBytes,scopeWriteBytes}`
+ *    - `NativeModules.CkylMpWebRtc.{sendText,sendBytes,setMicrophone,setSpeaker}`
+ *    - `NativeModules.CkylMpShare.shareFile(spec)`
+ *    回执统一 `(errorCode|null, errorMessage|null, meta|null, bytes|null)`；
+ *    缺模块（旧宿主）时按 API 降级（写入/文本分享回退事件桥；读取/文件分享明确失败）。
+ *
+ * ⚠️ 约定：GlobalEventEmitter 监听必须注册于**后台线程**（Lynx 4.0.0 行为），
+ * 本 SDK 在首次调用时惰性注册，请勿在渲染关键路径上延迟首次调用时机。
+ */
+/** 桥错误：宿主结构化错误码（见 docs/MP_PERMS.md 错误码表） */
+export class CkylMpError extends Error {
+    constructor(code, message, extra = {}) {
+        super(message);
+        this.name = "CkylMpError";
+        this.code = code;
+        this.extra = extra;
+    }
+}
+// ── 内部：传输层 ─────────────────────────────────────────────
+const REPLY_EVENT = "ckylinmp::reply";
+const PUSH_EVENT = "ckylinmp::event";
+const DEFAULT_TIMEOUT_MS = 10000;
+let seq = 0;
+let listenerInstalled = false;
+const pending = new Map();
+/** 推送订阅：handler 可选第二参 [bytes]（`ckylinmp::event` 三元组 `[event, dataJson, binary?]`） */
+const pushHandlers = new Map();
+function installListeners() {
+    if (listenerInstalled)
+        return;
+    // 环境守卫：GlobalEventEmitter 缺失（裸 JS/Node/单测）时跳过注册，
+    // invoke 会在「无桥」分支快速失败（NOT_IMPLEMENTED），避免 ReferenceError。
+    let emitter;
+    try {
+        emitter = typeof GlobalEventEmitter !== "undefined" ? GlobalEventEmitter : undefined;
+    }
+    catch {
+        emitter = undefined;
+    }
+    if (!emitter)
+        return;
+    listenerInstalled = true;
+    emitter.addListener(REPLY_EVENT, (...args) => {
+        const [msgid, , ok, dataJson, errorJson] = args;
+        const call = pending.get(msgid);
+        if (!call)
+            return; // 已超时/未知回执
+        pending.delete(msgid);
+        clearTimeout(call.timer);
+        if (ok) {
+            call.resolve(dataJson || "{}");
+        }
+        else {
+            let parsed = { code: "INTERNAL", message: errorJson };
+            try {
+                parsed = { ...parsed, ...JSON.parse(errorJson) };
+            }
+            catch {
+                /* 保留原始文本作 message */
+            }
+            const { code, message, ...extra } = parsed;
+            call.reject(new CkylMpError(code || "INTERNAL", message || "未知错误", extra));
+        }
+    });
+    emitter.addListener(PUSH_EVENT, (...args) => {
+        const [event, dataJson, bytes] = args;
+        const handlers = pushHandlers.get(event);
+        if (!handlers || handlers.size === 0)
+            return;
+        let data = dataJson;
+        try {
+            data = JSON.parse(dataJson);
+        }
+        catch {
+            /* 非 JSON 载荷按原文分发 */
+        }
+        handlers.forEach((h) => {
+            try {
+                h(data, bytes);
+            }
+            catch {
+                /* 单个 handler 异常不影响其他订阅者 */
+            }
+        });
+    });
+}
+function invoke(event, payload = {}, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    return new Promise((resolve, reject) => {
+        const bridge = safeBridge();
+        if (!bridge) {
+            reject(new CkylMpError("NOT_IMPLEMENTED", "当前宿主不支持小程序桥"));
+            return;
+        }
+        installListeners();
+        const msgid = `msg_${Date.now()}_${++seq}`;
+        const timer = setTimeout(() => {
+            pending.delete(msgid);
+            reject(new CkylMpError("TIMEOUT", `等待 ${event} 回执超时（${timeoutMs}ms）`));
+        }, timeoutMs);
+        pending.set(msgid, {
+            resolve: (dataJson) => {
+                try {
+                    resolve(JSON.parse(dataJson));
+                }
+                catch {
+                    resolve({});
+                }
+            },
+            reject,
+            timer,
+        });
+        bridge.invoke(msgid, event, JSON.stringify(payload));
+    });
+}
+// ── 原生模块通道（二进制/高频路径，docs/NATIVE_MODULES.md）────
+// 与事件桥的关系：类型化原生模块（@LynxMethod + byte[] 直达）承载
+// 文件字节/WebRTC 实时/非文本分享；事件桥保持为兼容与交互通道。
+// 缺模块（旧宿主）时按 API 降级：二进制读取/文件分享明确失败（NOT_IMPLEMENTED），
+// 写入/文本分享自动回退 base64 事件桥路径。
+/** 探测某原生模块是否可用（缺模块 = 旧宿主） */
+export function hasNativeCapability(module) {
+    try {
+        return typeof NativeModules !== "undefined" && NativeModules[module] != null;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 调用类型化原生模块方法（Callback 契约
+ * `(errorCode|null, errorMessage|null, meta|null, bytes|null)`）。
+ * 模块缺失 → NOT_IMPLEMENTED（由调用方决定降级或明确失败）。
+ */
+function callNative(module, method, args, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    return new Promise((resolve, reject) => {
+        const mod = safeNative(module);
+        const fn = mod?.[method];
+        if (typeof fn !== "function") {
+            reject(new CkylMpError("NOT_IMPLEMENTED", `当前宿主不支持原生模块 ${module}.${method}`));
+            return;
+        }
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            reject(new CkylMpError("TIMEOUT", `等待 ${module}.${method} 回执超时（${timeoutMs}ms）`));
+        }, timeoutMs);
+        const cb = (errorCode, errorMessage, meta, bytes) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (errorCode) {
+                reject(new CkylMpError(errorCode, errorMessage ?? "未知错误", meta ?? {}));
+                return;
+            }
+            resolve({ meta: meta ?? {}, bytes });
+        };
+        try {
+            fn.apply(mod, [...args, cb]);
+        }
+        catch (e) {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            reject(new CkylMpError("INTERNAL", e?.message ?? "原生模块调用失败"));
+        }
+    });
+}
+/** 安全读取 NativeModules（环境中不存在时返回 undefined） */
+function safeNative(module) {
+    try {
+        return NativeModules[module];
+    }
+    catch {
+        return undefined;
+    }
+}
+/** 安全读取事件桥模块（NativeModules / NativeModules.CkylMpBridge 缺失时返回 undefined） */
+function safeBridge() {
+    try {
+        return typeof NativeModules !== "undefined"
+            ? NativeModules.CkylMpBridge
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Blob/ArrayBuffer/视图 → ArrayBuffer（原生模块 byte[] 输入） */
+function toArrayBuffer(data) {
+    if (data instanceof ArrayBuffer)
+        return Promise.resolve(data);
+    if (ArrayBuffer.isView(data)) {
+        const view = data;
+        return Promise.resolve(view.buffer.slice(view.byteOffset, view.byteOffset + view.byteLength));
+    }
+    return data.arrayBuffer();
+}
+/** 二进制输入判定（Blob / ArrayBuffer / TypedArray / DataView） */
+function isBinaryLike(data) {
+    return (typeof Blob !== "undefined" && data instanceof Blob ||
+        data instanceof ArrayBuffer ||
+        ArrayBuffer.isView(data));
+}
+/** WebRTC 数据通道单条消息上限（原生模块 byte[] 直达；与宿主常量一致） */
+const WEBRTC_MAX_MSG_BYTES = 256 * 1024;
+/** WebRTC 调用超时（数据通道 send 即刻回执，放宽少许） */
+const WEBRTC_CALL_TIMEOUT_MS = 30000;
+/** 文件/二进制类交互超时（与事件桥文件类一致的长交互放宽） */
+const FILE_ACTION_TIMEOUT_MS = 300000;
+/** 二进制读取超时（8–16MB 一次性读取，逐设备 IO 放宽） */
+const READ_BINARY_TIMEOUT_MS = 120000;
+// ── 推送事件订阅 ─────────────────────────────────────────────
+/** 订阅宿主推送事件（如 download_progress、webrtc_binary）；返回取消函数 */
+export function on(event, handler) {
+    installListeners();
+    let set = pushHandlers.get(event);
+    if (!set) {
+        set = new Set();
+        pushHandlers.set(event, set);
+    }
+    set.add(handler);
+    return () => off(event, handler);
+}
+/** 取消订阅 */
+export function off(event, handler) {
+    pushHandlers.get(event)?.delete(handler);
+}
+/**
+ * 冷启动 deeplink 参数（宿主 globalProps 注入，同步可读；无参数 = 空数组）。
+ * 必须在启动早期调用（globalProps 渲染前即曝光，任意时点读取均含启动值）。
+ */
+export function getLaunchOptions() {
+    const gp = (() => {
+        try {
+            return typeof lynx !== "undefined" ? lynx.__globalProps : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    })();
+    const launch = gp?.launchOptions;
+    if (launch && Array.isArray(launch.query)) {
+        const query = launch.query.filter((item) => Array.isArray(item) &&
+            item.length === 2 &&
+            typeof item[0] === "string" &&
+            typeof item[1] === "string");
+        return { query };
+    }
+    return { query: [] };
+}
+/**
+ * 订阅「小程序已启动时」的带参 deeplink 推送（`deeplink_called`）；
+ * 无参数的 deeplink 不推送。返回取消函数。
+ */
+export function onDeeplinkCalled(handler) {
+    return on("deeplink_called", (raw) => {
+        const query = (raw?.query ?? []);
+        try {
+            handler({ query: Array.isArray(query) ? query : [] });
+        }
+        catch {
+            /* 单 handler 异常不影响其他订阅者 */
+        }
+    });
+}
+// 返回监听：handler 集合 + 一次性注册（back.on/off 幂等；宿主端失败静默忽略）
+const backHandlers = new Set();
+let backEventInstalled = false;
+let backRegistered = false;
+/**
+ * 返回监听：注册后宿主**单次返回**推送 `back_press` 给本小程序（宿主不再双击退出），
+ * 小程序可借 `exitApp()` 在「返回到达最顶层」时退出。返回取消函数；全部取消后自动注销。
+ */
+export function onBackPress(handler) {
+    if (!backEventInstalled) {
+        backEventInstalled = true;
+        on("back_press", () => {
+            backHandlers.forEach((h) => {
+                try {
+                    h();
+                }
+                catch {
+                    /* 单 handler 异常不影响其他订阅者 */
+                }
+            });
+        });
+    }
+    if (!backRegistered) {
+        backRegistered = true;
+        invoke("back.on", {}, 5000).catch(() => {
+            /* 宿主不支持返回监听时静默（事件订阅同失效） */
+        });
+    }
+    backHandlers.add(handler);
+    return () => {
+        backHandlers.delete(handler);
+        if (backHandlers.size === 0 && backRegistered) {
+            backRegistered = false;
+            invoke("back.off", {}, 5000).catch(() => { });
+        }
+    };
+}
+/** 退出本小程序（宿主关闭小程序任务；返回监听模式下「返回到底」的关闭出口） */
+export async function exitApp() {
+    await invoke("app.exit");
+}
+// ── 权限 ─────────────────────────────────────────────────────
+/**
+ * 批量申请权限（必须已在小程序 `perms` 字段声明）。
+ *
+ * - 全部已裁决：立即返回已允许列表，不弹窗；
+ * - 含待定项：宿主弹出一次性授权弹窗（仅一次/保持允许/永久拒绝）；
+ * - 返回本次调用后生效允许的权限 key 列表（含历史已允许项）。
+ */
+export async function requestPerms(perms) {
+    const res = await invoke("requestPerms", { perms });
+    return res.perms;
+}
+/**
+ * 获取作用域 token（需已授权 token 权限；未授权返回 PERM_DENIED，
+ * 请先 `requestPerms(["token"])`）。
+ */
+export async function getToken() {
+    const res = await invoke("getToken");
+    return res.token;
+}
+/**
+ * 获取宿主当前用户的昵称/头像/UserId（需已授权 `profile` 权限；
+ * 未授权抛 `PERM_DENIED`，请先 `requestPerms(["profile"])`——首次弹授权窗，
+ * 文案「获取您的头像、昵称」；宿主未登录抛 `AUTH_REQUIRED`）。
+ */
+export async function getProfile() {
+    return invoke("getProfile");
+}
+// ── store（隔离 KV）──────────────────────────────────────────
+export const store = {
+    async get(key) {
+        const res = await invoke("store.get", { key });
+        return res.value;
+    },
+    async set(key, value) {
+        await invoke("store.set", { key, value });
+    },
+    async remove(key) {
+        await invoke("store.remove", { key });
+    },
+    async keys() {
+        const res = await invoke("store.keys");
+        return res.keys;
+    },
+    async clear() {
+        await invoke("store.clear");
+    },
+};
+// ── 能力 ─────────────────────────────────────────────────────
+/**
+ * 系统分享面板：文本（事件桥）或 文本+图片/文件附件（原生模块通道）。
+ * `file` 提供时经 `CkylMpShare.shareFile`（bytes 落宿主临时文件，FileProvider
+ * 授权）；仅文本时走事件桥 `share`（旧宿主兼容）。`text`/`file` 至少其一。
+ */
+export async function share(options) {
+    if (options.file !== undefined) {
+        const spec = options.file;
+        if (!hasNativeCapability("CkylMpShare")) {
+            throw new CkylMpError("NOT_IMPLEMENTED", "当前宿主不支持文件分享");
+        }
+        if (spec.uri === undefined && spec.data === undefined) {
+            throw new CkylMpError("BAD_REQUEST", "share: file.uri / file.data 至少其一");
+        }
+        const data = spec.data !== undefined ? await toArrayBuffer(spec.data) : undefined;
+        await callNative("CkylMpShare", "shareFile", [
+            options.text ?? null,
+            options.title ?? null,
+            spec.uri ?? null,
+            data ?? null,
+            spec.filename ?? null,
+            spec.mime ?? null,
+        ], FILE_ACTION_TIMEOUT_MS);
+        return;
+    }
+    if (!options.text)
+        throw new CkylMpError("BAD_REQUEST", "share: 需要 text 或 file");
+    await invoke("share", { text: options.text, title: options.title });
+}
+/**
+ * 系统 DownloadManager 下载，返回下载 id 与文件名；
+ * 进度/完成/失败经推送事件分发（见 [onDownloadProgress]/[onDownloadSettled]）。
+ * `openAfterComplete` = 完成后由宿主直接打开文件。
+ */
+export async function download(options) {
+    return invoke("download", { ...options });
+}
+/** 订阅下载进度推送；返回取消函数 */
+export function onDownloadProgress(handler) {
+    return on("download_progress", (data) => handler(data));
+}
+/** 订阅下载完成/失败推送 */
+export function onDownloadSettled(handler) {
+    const offComplete = on("download_complete", (d) => handler("download_complete", d));
+    const offFailed = on("download_failed", (d) => handler("download_failed", d));
+    return () => {
+        offComplete();
+        offFailed();
+    };
+}
+/** 拉起宿主扫码页，返回二维码原文（用户取消抛 USER_CANCELLED） */
+export async function scanQR() {
+    const res = await invoke("scanQR", {}, 120000);
+    return res.result;
+}
+/** 获取当前位置（宿主运行时权限弹窗；超时抛 INTERNAL） */
+export async function getLocation(options = {}) {
+    return invoke("getLocation", { ...options }, Math.max((options.timeoutMs ?? 15000) + 5000, DEFAULT_TIMEOUT_MS));
+}
+/** 经宿主转发 Intent（结构性消毒：仅 action/data/categories/package/string extras） */
+export async function sendIntent(spec) {
+    await invoke("sendIntent", { ...spec });
+}
+// ── 文件能力（writefile/selectfolder/selectfile/readfile/selectmedia）─────────
+// 统一经宿主 SAF 系统选择器；用户取消抛 USER_CANCELLED；需先 requestPerms 对应权限。
+// 超时放宽：选择器/对话框为长交互，按 5 分钟兜底。
+/** 保存对话框：文件名可改、选择保存位置、保存或取消（需 writefile 权限） */
+export async function writeFile(options) {
+    // 二进制快路径：Blob/ArrayBuffer/视图 → byte[] 直达宿主（无 base64、无 JSON 字符串）；
+    // 旧宿主（无 CkylMpFile）自动回退 base64 事件桥路径。
+    if (isBinaryLike(options.data) && hasNativeCapability("CkylMpFile")) {
+        const bytes = await toArrayBuffer(options.data);
+        const { meta } = await callNative("CkylMpFile", "saveBytes", [
+            bytes,
+            options.filename ?? null,
+            options.mime ?? null,
+        ], FILE_ACTION_TIMEOUT_MS);
+        return {
+            uri: String(meta.uri ?? ""),
+            name: String(meta.name ?? ""),
+            size: Number(meta.size ?? 0),
+        };
+    }
+    const normalized = await normalizeData(options.data, options.encoding);
+    return invoke("writeFile", {
+        filename: options.filename,
+        data: normalized.data,
+        encoding: normalized.encoding,
+        mime: options.mime,
+    }, FILE_ACTION_TIMEOUT_MS);
+}
+/**
+ * 二进制读取（需 readfile 权限；**原生模块通道**，byte[] 直达）：
+ * 返回字节而非 base64/文本，默认上限 8MB（maxBytes 上限 16MB，超限 FILE_TOO_LARGE）。
+ * 旧宿主不支持时抛 NOT_IMPLEMENTED（明确失败，不回退——1MB base64 不是等价能力）。
+ */
+export async function readFileBytes(options) {
+    const { meta, bytes } = await callNative("CkylMpFile", "readBytes", [
+        options.uri,
+        options.maxBytes ?? 0,
+    ], READ_BINARY_TIMEOUT_MS);
+    if (!bytes)
+        throw new CkylMpError("INTERNAL", "宿主未返回字节数据");
+    return {
+        uri: String(meta.uri ?? options.uri),
+        name: String(meta.name ?? ""),
+        size: Number(meta.size ?? bytes.byteLength),
+        mime: meta.mime != null ? String(meta.mime) : undefined,
+        bytes: new Uint8Array(bytes),
+    };
+}
+/** 目录选择：返回 tree URI + 展示名 + primary 真实路径（需 selectfolder 权限） */
+export async function selectFolder(options = {}) {
+    return invoke("selectFolder", { persist: options.persist ?? true }, FILE_ACTION_TIMEOUT_MS);
+}
+/**
+ * 文件选择：单/多选 + 类型过滤（MIME/扩展名）+ 默认打开目录（需 selectfile 权限）。
+ * `initialUri` 传 selectFolder 返回的 uri；`types` 为空 = 不限类型。
+ */
+export async function selectFiles(options = {}) {
+    return invoke("selectFiles", { ...options }, FILE_ACTION_TIMEOUT_MS);
+}
+/**
+ * 读取指定 URI 文件内容（需 readfile 权限；文件 ≤1MB，超限抛 FILE_TOO_LARGE）。
+ * encoding: auto（默认，按内容判定文本/二进制）| utf8 | base64。
+ */
+export async function readFile(options) {
+    return invoke("readFile", { ...options }, FILE_ACTION_TIMEOUT_MS);
+}
+/**
+ * 系统相册选择（需 selectmedia 权限）：
+ * - 系统 Photo Picker（API 33+ 原生 / 30-32 backport / 更老设备降级 OpenDocument）；
+ * - `mediaType` 图片/视频/全部；`multiple` 多选（maxCount 上限 20）；
+ * - Photo Picker 不支持自定义类型过滤：`filters`/`maxSizeBytes` 为宿主**后置过滤**，
+ *   未命中项出现在 `skipped`。
+ */
+export async function selectMedia(options = {}) {
+    return invoke("selectMedia", { ...options }, FILE_ACTION_TIMEOUT_MS);
+}
+// ── controlfolder（scope 逐项授权 + 目录完全控制）────────────────────────────
+// 每个 scope 前缀必须单独授权（controlFolder.request 弹说明对话框 + 用户选择目录）；
+// 操作路径必须为绝对路径且落在已授权 scope 前缀下（目录穿越一律 SCOPE_NOT_GRANTED）。
+/** 授权一个目录范围（需 controlfolder 权限；用户取消抛 USER_CANCELLED） */
+export async function requestFolderScope(scope) {
+    return invoke("controlFolder.request", { scope }, FILE_ACTION_TIMEOUT_MS);
+}
+/** 列出已授权范围 */
+export async function folderScopes() {
+    return invoke("controlFolder.scopes", {});
+}
+/** controlfolder 操作集（path 均为绝对路径且必须在已授权 scope 前缀下） */
+export const controlFolder = {
+    createDir(path) {
+        return invoke("controlFolder.createDir", { path });
+    },
+    createFile(path, options = {}) {
+        return buildDataInvoke("controlFolder.createFile", path, options, options.data !== undefined);
+    },
+    writeFile(path, options) {
+        // 二进制快路径：byte[] 直达（无 base64）；旧宿主自动回退事件桥 base64。
+        if (isBinaryLike(options.data) && hasNativeCapability("CkylMpFile")) {
+            return writeScopeBytes(path, options.data);
+        }
+        return buildDataInvoke("controlFolder.writeFile", path, options, true);
+    },
+    /**
+     * 二进制读取（controlfolder 字节态；默认 8MB，上限 16MB，超限 FILE_TOO_LARGE）。
+     * 旧宿主不支持时抛 NOT_IMPLEMENTED。
+     */
+    readFileBytes(path, options = {}) {
+        return readScopeBytes(path, options.maxBytes);
+    },
+    /**
+     * 二进制写入（controlfolder 字节态，覆盖写，≤32MB；显式快路径，旧宿主 NOT_IMPLEMENTED）。
+     * 说明：`writeFile` 自动按输入走本路径或事件桥，正常情况下无需直接用本方法。
+     */
+    writeFileBytes(path, data, options = {}) {
+        if (!hasNativeCapability("CkylMpFile")) {
+            return Promise.reject(new CkylMpError("NOT_IMPLEMENTED", "当前宿主不支持二进制写入"));
+        }
+        return writeScopeBytes(path, data);
+    },
+    readFile(path, options = {}) {
+        return invoke("controlFolder.readFile", { path, ...options }, FILE_ACTION_TIMEOUT_MS);
+    },
+    list(path, options = {}) {
+        return invoke("controlFolder.list", { ...(path !== undefined ? { path } : {}), recursive: options.recursive }, FILE_ACTION_TIMEOUT_MS);
+    },
+    rename(path, newName) {
+        return invoke("controlFolder.rename", { path, newName });
+    },
+    delete(path) {
+        return invoke("controlFolder.delete", { path });
+    },
+    copy(src, dest) {
+        return invoke("controlFolder.copy", { src, dest }, FILE_ACTION_TIMEOUT_MS);
+    },
+    move(src, dest) {
+        return invoke("controlFolder.move", { src, dest }, FILE_ACTION_TIMEOUT_MS);
+    },
+};
+/** controlfolder 二进制写入（scopeWriteBytes；字节直达，路径须命中已授权 scope） */
+async function writeScopeBytes(path, data) {
+    const bytes = await toArrayBuffer(data);
+    const { meta } = await callNative("CkylMpFile", "scopeWriteBytes", [
+        path, bytes, null,
+    ], FILE_ACTION_TIMEOUT_MS);
+    return { path: String(meta.path ?? path) };
+}
+/** controlfolder 二进制读取（scopeReadBytes；≤16MB） */
+async function readScopeBytes(path, maxBytes) {
+    const { meta, bytes } = await callNative("CkylMpFile", "scopeReadBytes", [
+        path, maxBytes ?? 0,
+    ], READ_BINARY_TIMEOUT_MS);
+    if (!bytes)
+        throw new CkylMpError("INTERNAL", "宿主未返回字节数据");
+    return {
+        path: String(meta.path ?? path),
+        name: String(meta.name ?? ""),
+        size: Number(meta.size ?? bytes.byteLength),
+        mime: meta.mime != null ? String(meta.mime) : undefined,
+        bytes: new Uint8Array(bytes),
+    };
+}
+async function buildDataInvoke(event, path, options, withData) {
+    const payload = { path };
+    if (withData && options.data !== undefined) {
+        const normalized = await normalizeData(options.data, options.encoding);
+        payload.data = normalized.data;
+        payload.encoding = normalized.encoding;
+    }
+    return invoke(event, payload, FILE_ACTION_TIMEOUT_MS);
+}
+/** 载荷归一：文本 utf8 原样；Blob/ArrayBuffer/Uint8Array 转 base64；允许显式指定编码 */
+async function normalizeData(data, encoding) {
+    if (data instanceof Blob) {
+        const base64 = await blobToBase64(data);
+        return { data: base64, encoding: "base64" };
+    }
+    if (data instanceof ArrayBuffer || ArrayBuffer.isView(data)) {
+        return { data: toBase64(data), encoding: "base64" };
+    }
+    return { data, encoding: encoding ?? "utf8" };
+}
+function blobToBase64(blob) {
+    return new Promise((resolve, reject) => {
+        const reader = new FileReader();
+        reader.onload = () => {
+            const result = reader.result;
+            if (typeof result === "string") {
+                resolve(result.slice(result.indexOf(",") + 1));
+            }
+            else {
+                reject(new Error("无法读取 Blob"));
+            }
+        };
+        reader.onerror = () => reject(reader.error ?? new Error("Blob 读取失败"));
+        reader.readAsDataURL(blob);
+    });
+}
+function toBase64(input) {
+    const bytes = input instanceof ArrayBuffer ? new Uint8Array(input) : new Uint8Array(input.buffer, input.byteOffset, input.byteLength);
+    let binary = "";
+    for (let i = 0; i < bytes.length; i++)
+        binary += String.fromCharCode(bytes[i]);
+    return btoa(binary);
+}
+export class MpDataChannel {
+    constructor(pcId, dcId, label) {
+        this.messageHandlers = new Set();
+        this.pcId = pcId;
+        this.dcId = dcId;
+        this.label = label;
+    }
+    /** 发送文本（UTF-8）；单条上限 64KB（事件桥路径） */
+    send(data) {
+        return invoke("webrtc.dataChannel.send", { pcId: this.pcId, dcId: this.dcId, data, binary: false });
+    }
+    /**
+     * 发送二进制：**原生模块路径**（byte[] 直达，≤256KB；应用层自行分帧）。
+     * 旧宿主（无 CkylMpWebRtc）自动回退 base64 事件桥（≤48KB 实际字节）。
+     */
+    async sendBytes(data) {
+        const buf = await toArrayBuffer(data);
+        if (buf.byteLength > WEBRTC_MAX_MSG_BYTES) {
+            throw new CkylMpError("BAD_REQUEST", `单条消息超过 ${WEBRTC_MAX_MSG_BYTES / 1024}KB 上限`);
+        }
+        if (hasNativeCapability("CkylMpWebRtc")) {
+            await callNative("CkylMpWebRtc", "sendBytes", [this.pcId, this.dcId, buf], WEBRTC_CALL_TIMEOUT_MS);
+            return;
+        }
+        await invoke("webrtc.dataChannel.send", { pcId: this.pcId, dcId: this.dcId, data: toBase64(buf), binary: true }, WEBRTC_CALL_TIMEOUT_MS);
+    }
+    /** 发送二进制（base64 文本，legacy）；解码后单条上限 64KB */
+    sendBinary(base64) {
+        return invoke("webrtc.dataChannel.send", { pcId: this.pcId, dcId: this.dcId, data: base64, binary: true });
+    }
+    /** 订阅消息；返回取消函数 */
+    onMessage(handler) {
+        this.messageHandlers.add(handler);
+        return () => {
+            this.messageHandlers.delete(handler);
+        };
+    }
+    /** 内部分发入口（[MpPeerConnection] 路由 webrtc_event / webrtc_binary 用） */
+    dispatch(data, binary, bytes) {
+        this.messageHandlers.forEach((h) => {
+            try {
+                h({ data, bytes, binary });
+            }
+            catch {
+                /* 单个 handler 异常不影响其他订阅者 */
+            }
+        });
+    }
+}
+/**
+ * P2P 连接（仅音频 + 数据通道）。回调属性按需赋值；
+ * [close] 后事件订阅自动解除。
+ */
+export class MpPeerConnection {
+    constructor(pcId) {
+        this.channels = new Map();
+        this.pcId = pcId;
+        const offEvent = on("webrtc_event", (raw) => {
+            const e = raw;
+            if (e.pcId !== this.pcId)
+                return;
+            switch (e.type) {
+                case "ice_candidate":
+                    this.onIceCandidate?.({
+                        candidate: e.candidate,
+                        sdpMid: e.sdpMid,
+                        sdpMLineIndex: e.sdpMLineIndex,
+                    });
+                    break;
+                case "ice_gathering_state":
+                    this.onIceGatheringStateChange?.(e.state);
+                    break;
+                case "connection_state":
+                    this.onConnectionStateChange?.(e.state);
+                    break;
+                case "remote_audio":
+                    this.onRemoteAudio?.(e.state);
+                    break;
+                case "data_channel": {
+                    const dc = new MpDataChannel(this.pcId, e.dcId, e.label ?? "");
+                    this.channels.set(dc.dcId, dc);
+                    this.onDataChannel?.(dc);
+                    break;
+                }
+                case "data_channel_message":
+                    this.channels.get(e.dcId)?.dispatch(e.data ?? null, e.binary ?? false);
+                    break;
+            }
+        });
+        // 二进制消息（字节直达，无 base64）：`webrtc_binary` 推送三元组 [event, dataJson, bytes]
+        const offBinary = on("webrtc_binary", (raw, bytes) => {
+            const e = raw;
+            if (e.pcId !== this.pcId)
+                return;
+            this.channels.get(e.dcId)?.dispatch(null, true, bytes ?? new ArrayBuffer(0));
+        });
+        this.unsubscribe = () => {
+            offEvent();
+            offBinary();
+        };
+    }
+    createOffer() {
+        return invoke("webrtc.createOffer", { pcId: this.pcId });
+    }
+    createAnswer() {
+        return invoke("webrtc.createAnswer", { pcId: this.pcId });
+    }
+    setLocalDescription(desc) {
+        return invoke("webrtc.setLocalDescription", { pcId: this.pcId, ...desc });
+    }
+    setRemoteDescription(desc) {
+        return invoke("webrtc.setRemoteDescription", { pcId: this.pcId, ...desc });
+    }
+    addIceCandidate(candidate) {
+        return invoke("webrtc.addIceCandidate", { pcId: this.pcId, ...candidate });
+    }
+    /** 新建本地数据通道（需先完成 offer/answer 协商） */
+    async createDataChannel(label) {
+        const res = await invoke("webrtc.createDataChannel", { pcId: this.pcId, label });
+        const dc = new MpDataChannel(this.pcId, res.dcId, label);
+        this.channels.set(dc.dcId, dc);
+        return dc;
+    }
+    /** 麦克风开关：首次开启触发宿主运行时权限弹窗（超时放宽至 60s） */
+    setMicrophone(enabled) {
+        return invoke("webrtc.setMicrophone", { pcId: this.pcId, enabled }, 60000);
+    }
+    /** 关闭并释放（幂等；同时解除事件订阅） */
+    close() {
+        this.unsubscribe();
+        return invoke("webrtc.close", { pcId: this.pcId });
+    }
+}
+/**
+ * 新建 P2P 连接（需已授权 webrtc 权限，否则 PERM_DENIED）。
+ * 典型流程：createPeerConnection → createOffer/setLocalDescription →
+ * 信令交换 → setRemoteDescription/addIceCandidate → 建数据通道或开麦。
+ */
+export async function createPeerConnection(config = {}) {
+    const res = await invoke("webrtc.createPeerConnection", {
+        iceServers: config.iceServers ?? [],
+    });
+    return new MpPeerConnection(res.pcId);
+}
+/** 音频输出路由：`true` 扬声器，`false` 听筒 */
+export function setSpeaker(enabled) {
+    return invoke("webrtc.setSpeaker", { enabled });
+}
+// ── HTTP 流式桥（宿主 SSE 代理）───────────────────────────
+// 宿主 OkHttp 逐行读取 + 宿主侧 UTF-8 解码，经推送事件（http_stream）逐行回传，
+// 规避 JS 运行时缺 ReadableStream/TextDecoder（真逐字流式）。ungated，与 fetch 同列。
+const EVENT_HTTP_STREAM = "http_stream";
+/** 宿主桥是否可用（纯读全局，供探针判定 bridgeStreamOk；不触发监听注册） */
+export function isBridgeAvailable() {
+    try {
+        return typeof NativeModules !== "undefined" && !!NativeModules.CkylMpBridge;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 发起宿主 SSE 流式请求。先订阅 http_stream 再 invoke（宿主快速 ack），避免丢首行；
+ * end/error 到达即自动退订。返回句柄供主动 cancel。
+ */
+export async function streamHttp(req, handlers) {
+    const streamId = `hs_${Date.now()}_${++seq}`;
+    const off = on(EVENT_HTTP_STREAM, (raw) => {
+        const e = raw;
+        if (e.streamId !== streamId)
+            return;
+        if (e.type === "line") {
+            handlers.onLine(e.data ?? "");
+        }
+        else if (e.type === "end") {
+            off();
+            handlers.onEnd();
+        }
+        else if (e.type === "error") {
+            off();
+            handlers.onError(e.status ?? 0, e.message ?? "");
+        }
+    });
+    try {
+        await invoke("http.stream", {
+            streamId,
+            url: req.url,
+            method: req.method ?? "POST",
+            headers: req.headers ?? {},
+            body: req.body ?? "",
+        });
+    }
+    catch (e) {
+        off();
+        throw e;
+    }
+    return {
+        streamId,
+        cancel: () => {
+            off();
+            return invoke("http.stream.cancel", { streamId });
+        },
+    };
+}