@maoyugames/phaser-framework 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,1778 @@
+import { b as HttpRequestOptions, U as Unsubscribe, H as Handler, n as LogLevel, A as AdResult, r as PurchaseResult, o as LoginResult, d as IPlatform, i as IPlatformLifecycle, S as SafeArea } from './types-DtcRFbM0.js';
+export { a as HttpMethod, c as HttpResponse, I as IDisposable, e as IPlatformAds, f as IPlatformAnalytics, g as IPlatformAuth, h as IPlatformDevice, j as IPlatformNet, k as IPlatformPayment, l as IPlatformSocket, m as IPlatformStorage, L as LaunchOptions, P as PlatformInfo, p as PlatformName, q as PlatformUnsupportedError, R as Result, s as SocketOptions, t as SystemInfo, V as Vec2, u as err, v as ok } from './types-DtcRFbM0.js';
+import Phaser from 'phaser';
+
+/**
+ * 网络层契约。框架内置三种协议:
+ * - http       : 请求/响应,绝大多数场景够用(默认)
+ * - websocket  : 长连接,双向实时
+ * - kcp        : 基于 ARQ 的可靠 UDP 语义,低延迟实时对战;
+ *                浏览器/小游戏无原生 UDP,默认以"KCP over WebSocket(数据报)"承载,
+ *                Capacitor 下可替换为原生 UDP 传输。
+ *
+ * 三者都通过平台层的 IPlatformNet 拿到底层传输能力,从而跨平台一致。
+ */
+
+/** 协议类型 */
+type NetProtocol = 'http' | 'websocket' | 'kcp';
+interface HttpClientConfig {
+    /** 基础 URL,会与相对 path 拼接 */
+    baseURL?: string;
+    /** 默认请求头 */
+    headers?: Record<string, string>;
+    /** 默认超时(ms) */
+    timeout?: number;
+    /** 失败重试次数(幂等请求) */
+    retries?: number;
+}
+/** 请求/响应拦截器 */
+interface HttpInterceptors {
+    request?: (options: HttpRequestOptions) => HttpRequestOptions | Promise<HttpRequestOptions>;
+    response?: <T>(data: T, status: number) => T | Promise<T>;
+    error?: (error: Error) => void;
+}
+interface IHttpClient {
+    request<T = unknown>(options: HttpRequestOptions): Promise<T>;
+    get<T = unknown>(url: string, options?: Partial<HttpRequestOptions>): Promise<T>;
+    post<T = unknown>(url: string, body?: unknown, options?: Partial<HttpRequestOptions>): Promise<T>;
+    put<T = unknown>(url: string, body?: unknown, options?: Partial<HttpRequestOptions>): Promise<T>;
+    delete<T = unknown>(url: string, options?: Partial<HttpRequestOptions>): Promise<T>;
+    setHeader(key: string, value: string): void;
+    use(interceptors: HttpInterceptors): void;
+}
+
+type SocketState = 'connecting' | 'open' | 'closing' | 'closed';
+interface SocketClientConfig {
+    url: string;
+    /** 自动重连(默认开) */
+    autoReconnect?: boolean;
+    /** 重连最大次数(默认 Infinity) */
+    maxReconnect?: number;
+    /** 重连基础间隔 ms(指数退避基数,默认 1000) */
+    reconnectIntervalMs?: number;
+    /** 心跳间隔 ms(0 关闭,默认 0) */
+    heartbeatIntervalMs?: number;
+    /** 心跳包内容(string / ArrayBuffer) */
+    heartbeatPayload?: string | ArrayBuffer;
+}
+/**
+ * 长连接客户端统一接口。WebSocketClient 与 KcpClient 都实现它,
+ * 业务切换协议时只改创建处,收发逻辑零改动。
+ */
+interface ISocketClient {
+    readonly state: SocketState;
+    connect(): Promise<void>;
+    send(data: string | ArrayBuffer): void;
+    close(): void;
+    onOpen(cb: () => void): Unsubscribe;
+    onMessage(cb: (data: string | ArrayBuffer) => void): Unsubscribe;
+    onError(cb: (err: Error) => void): Unsubscribe;
+    onClose(cb: () => void): Unsubscribe;
+}
+interface KcpClientConfig extends SocketClientConfig {
+    /** KCP conv 会话号,需与服务端约定一致 */
+    conv: number;
+    /** 是否启用 nodelay 模式(低延迟) */
+    nodelay?: boolean;
+    /** flush 间隔 ms(KCP update 频率,默认 10) */
+    intervalMs?: number;
+    /** 快速重传阈值 */
+    resend?: number;
+    /** 是否关闭拥塞控制(实时对战常关) */
+    nc?: boolean;
+    /** 发送/接收窗口 */
+    sndWnd?: number;
+    rcvWnd?: number;
+}
+interface INetManager {
+    /** 创建 HTTP 客户端 */
+    http(config?: HttpClientConfig): IHttpClient;
+    /** 创建 WebSocket 客户端 */
+    websocket(config: SocketClientConfig): ISocketClient;
+    /** 创建 KCP 客户端 */
+    kcp(config: KcpClientConfig): ISocketClient;
+    /** 框架级默认 HTTP 客户端(单例,读取全局 config.apiBaseURL) */
+    readonly defaultHttp: IHttpClient;
+}
+
+/**
+ * 底层服务契约。业务通过 App 门面访问这些服务,永远不直接 new 实现类、
+ * 也不直接触碰平台 SDK。服务实现统一在平台抽象之上,自动跨平台。
+ */
+
+interface IEventBus {
+    on<T = unknown>(event: string, handler: Handler<T>): Unsubscribe;
+    once<T = unknown>(event: string, handler: Handler<T>): Unsubscribe;
+    off(event: string, handler: Handler<unknown>): void;
+    emit<T = unknown>(event: string, payload?: T): void;
+    clear(event?: string): void;
+}
+interface ILogger {
+    level: LogLevel;
+    debug(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+    /** 派生带标签的子 logger */
+    tag(label: string): ILogger;
+}
+/** 全局运行时配置,bootstrap 注入,业务只读 */
+interface AppConfig {
+    /** 业务后端基础地址 */
+    apiBaseURL: string;
+    /** 设计分辨率 */
+    designWidth: number;
+    designHeight: number;
+    /** 是否生产环境 */
+    production: boolean;
+    /**
+     * 广告位默认配置(D4):业务调用 App.ads.showRewarded() 不传 id 时,
+     * AdsManager 回退到这里声明的默认广告位 id。
+     */
+    ads?: {
+        /** 激励视频默认广告位 id */
+        rewardedUnitId?: string;
+        /** 插屏默认广告位 id */
+        interstitialUnitId?: string;
+    };
+    /**
+     * 数据上报后端配置(D4):是否启用"自有后端上报"通道及其上报路径。
+     * 启用后 AnalyticsManager 会把 track 事件经 App.net.defaultHttp POST 到 reportPath。
+     */
+    analytics?: {
+        /** 是否启用自有后端上报,默认 false(仅走平台原生埋点) */
+        backendEnabled?: boolean;
+        /** 上报路径(相对 apiBaseURL),默认 '/analytics/track' */
+        reportPath?: string;
+    };
+    /**
+     * 默认语言(优先级高于平台 system.language):
+     * 提供时 bootstrap 用它作为 I18n 的初始 locale。
+     */
+    defaultLocale?: string;
+    /** i18n 配置 */
+    i18n?: {
+        /** 兜底语言,默认 'en-US' */
+        fallbackLocale?: string;
+    };
+    /** 各平台广告位 / 商品等业务侧映射,按需扩展 */
+    extra?: Record<string, unknown>;
+}
+interface IConfigService {
+    readonly value: Readonly<AppConfig>;
+    get<T = unknown>(key: string, fallback?: T): T;
+}
+interface IAudioManager {
+    playMusic(key: string, opts?: {
+        loop?: boolean;
+        volume?: number;
+    }): void;
+    stopMusic(): void;
+    playSfx(key: string, opts?: {
+        volume?: number;
+    }): void;
+    setMusicVolume(v: number): void;
+    setSfxVolume(v: number): void;
+    muteAll(muted: boolean): void;
+}
+interface IStorageManager {
+    get<T = unknown>(key: string, fallback?: T): T | undefined;
+    set<T = unknown>(key: string, value: T): void;
+    remove(key: string): void;
+    clear(): void;
+}
+/**
+ * 资源加载抽象。处理各平台差异(如微信小游戏不支持 blob、需远程包/分包)。
+ * 真正的纹理/音频解码交给 Phaser,这里负责"按平台正确取到字节/URL"。
+ */
+interface IAssetLoader {
+    /** 取一个可被 Phaser.load 使用的 URL(小游戏侧可能是本地临时路径) */
+    resolveUrl(path: string): string;
+    loadText(path: string): Promise<string>;
+    loadJson<T = unknown>(path: string): Promise<T>;
+    loadArrayBuffer(path: string): Promise<ArrayBuffer>;
+}
+interface IAdsManager {
+    /** 是否当前平台支持广告 */
+    readonly available: boolean;
+    preloadRewarded(adUnitId?: string): Promise<void>;
+    /** 展示激励视频,resolve(true) 表示看完应发奖 */
+    showRewarded(adUnitId?: string): Promise<boolean>;
+    showInterstitial(adUnitId?: string): Promise<AdResult>;
+}
+interface IPaymentManager {
+    readonly available: boolean;
+    purchase(productId: string, extra?: Record<string, unknown>): Promise<PurchaseResult>;
+    restore(): Promise<PurchaseResult[]>;
+}
+interface IAnalyticsManager {
+    /** 业务自定义事件;内部按平台分发(平台原生埋点 + 自有后端) */
+    track(event: string, params?: Record<string, unknown>): void;
+    setUserId(id: string): void;
+    /**
+     * 启用自有后端上报通道(D4)。启用后,track 事件会经框架默认 HTTP 客户端
+     * (App.net.defaultHttp)POST 到 reportPath(默认 '/analytics/track')。
+     * bootstrap 据 config.analytics.backendEnabled 决定是否调用;
+     * 业务也可在确认后端就绪后自行调用以动态开启。
+     * @param opts.reportPath 自定义上报路径(相对 baseURL)
+     */
+    enableBackend(opts?: {
+        reportPath?: string;
+    }): void;
+}
+interface IAccountService {
+    /** 调用平台登录,拿到临时凭证(交业务后端换取登录态) */
+    login(): Promise<LoginResult>;
+    /**
+     * 获取用户公开信息(昵称 / 头像),需平台授权(D5)。
+     * 平台不支持或用户拒绝授权时 resolve(null),业务据此降级展示默认头像/昵称。
+     */
+    getProfile(): Promise<{
+        nickname: string;
+        avatarUrl: string;
+    } | null>;
+}
+/** 与 Phaser.Scene 解耦的场景管理门面 */
+interface ISceneManager {
+    /** 启动/切换到指定场景 */
+    goto(key: string, data?: unknown): void;
+    /** 叠加场景(如弹窗层) */
+    push(key: string, data?: unknown): void;
+    /** 关闭叠加场景 */
+    pop(key: string): void;
+}
+
+/**
+ * 多语言(i18n)运行时。
+ *
+ * 定位:框架级、与平台/UI 解耦的纯文案查找器。不负责加载语言包文件
+ * (那是业务/AssetLoader 的事),只负责:
+ *   - 注册语言包(addBundle)
+ *   - 切换当前语言(setLocale)
+ *   - 取文案并做占位替换(t)
+ *   - 缺失回退:当前 locale → fallback locale → key 本身(并 warn)
+ *
+ * locale 归一:外部来源(平台 system.language、用户设置)格式五花八门
+ * (zh_CN / zh-Hans / en_US / EN ...),内部统一用 normalizeLocale 归一成 xx-XX,
+ * 保证 addBundle 与 setLocale 用同一套键命名,避免"明明加了包却查不到"。
+ *
+ * 默认语言由整合阶段注入:
+ *   const i18n = new I18n({ fallbackLocale: 'en-US' });
+ *   i18n.setLocale(normalizeLocale(App.platform.info.system.language));
+ * (本文件不直接 new App / 读平台,只提供能力,默认值由调用方注入。)
+ */
+/** I18n 构造选项 */
+interface I18nOptions {
+    /** 兜底语言(当前 locale 查不到时回退到它),默认 'en-US' */
+    fallbackLocale?: string;
+    /** 初始当前语言,默认与 fallbackLocale 相同 */
+    locale?: string;
+}
+declare class I18n {
+    /** 当前语言(已归一) */
+    private _locale;
+    /** 兜底语言(已归一) */
+    private readonly fallbackLocale;
+    /** 语言包:locale → (key → 文案) */
+    private readonly bundles;
+    constructor(opts?: I18nOptions);
+    /** 当前语言(归一后的 xx-XX 形态) */
+    get locale(): string;
+    /** 切换当前语言(入参自动归一) */
+    setLocale(locale: string): void;
+    /**
+     * 合并注册一段语言包。多次对同一 locale 调用会浅合并(后注册覆盖同名 key),
+     * 便于按模块分包加载(如先注册通用包,再注册某场景专属包)。
+     * locale 入参自动归一。
+     */
+    addBundle(locale: string, dict: Record<string, string>): void;
+    /**
+     * 取文案。
+     * 查找顺序:当前 locale → fallback locale → 返回 key 本身(并 warn)。
+     * 命中后用 params 做 {name} 占位替换。
+     *
+     * @param key    文案键
+     * @param params 占位参数,如 t('hello', { name: 'Tom' }) 替换 "{name}"
+     */
+    t(key: string, params?: Record<string, string | number>): string;
+    /** 当前 locale 或 fallback locale 中是否存在该 key */
+    has(key: string): boolean;
+    /**
+     * 按"当前 locale → fallback locale"顺序查找原始模板,均无则 undefined。
+     * 不在此 warn(由 t 决定是否 warn,has 不应产生噪声日志)。
+     */
+    private lookup;
+}
+/**
+ * 把各种来源的语言标记尽力归一成 BCP-47 风格的 'xx-XX'(语言小写、地区大写)。
+ *
+ * 归一规则(尽力而为,覆盖常见形态;非穷举,够日常宿主语言用):
+ *   1. 统一分隔符:下划线 '_' 视同连字符 '-'(zh_CN → zh-CN)。
+ *   2. 拆成 [语言, 子标签...]:语言段强制小写。
+ *   3. 文字系统(script,4 字母如 Hans/Hant)映射到地区:
+ *        zh-Hans → zh-CN(简体),zh-Hant → zh-TW(繁体)。
+ *      这是游戏文案最常见的需求(只区分简繁),不做完整 script 保留。
+ *   4. 地区段(2 字母)强制大写:en-us → en-US。
+ *   5. 只有语言段时原样小写返回:en → en。
+ *   6. 空 / 非法输入回退 'en-US'。
+ *
+ * 注意:这不是完整的 BCP-47 解析器(不处理 variant / extension / 三字母语言),
+ * 只覆盖手游宿主常见的 zh-CN / zh-TW / en-US / ja-JP / ko-KR 等场景。
+ */
+declare function normalizeLocale(raw: string): string;
+
+/**
+ * 存档系统(SaveManager / SaveSlot)。
+ *
+ * 定位:在 App.storage(IStorageManager,已内置 JSON 序列化 + 异常兜底)之上,
+ * 再叠加一层"版本迁移 + 数据校验"的存档能力,解决两个真实痛点:
+ *
+ * 1. 版本迁移:游戏迭代过程中存档结构会变(新增字段、字段改名、结构调整)。
+ *    每个存档槽声明一个 version,旧存档读出来若版本落后,自动调用 migrate
+ *    升级到当前版本并写回,业务拿到的永远是最新结构。
+ *
+ * 2. 数据校验:本地存储可能被外部篡改 / 写入中途断电产生半截数据。
+ *    存档以 { v, data, sum } 落盘,sum 是对 data 序列化后的轻量校验和。
+ *    load 时若校验不通过,警告并回退到 defaults,避免业务拿到脏数据崩溃。
+ *
+ * 使用方式(整合阶段在 bootstrap 处构造单例并挂到 App 上,业务再 register):
+ *   const sm = new SaveManager();
+ *   const slot = sm.register<PlayerData>({
+ *     key: 'player', version: 3, defaults: { gold: 0, level: 1 },
+ *     migrate: (old, oldV) => migratePlayer(old, oldV),
+ *   });
+ *   const data = slot.load();
+ *   slot.patch({ gold: data.gold + 10 });
+ */
+/**
+ * 注册一个存档槽所需的配置。
+ * @template T 存档数据结构(业务自定义,需可 JSON 序列化)
+ */
+interface SaveSlotOptions<T> {
+    /** 存档键(会作为 App.storage 的 key,建议全局唯一,如 'player' / 'settings') */
+    key: string;
+    /** 当前存档结构版本号(从 1 开始递增,每次结构破坏性变更 +1) */
+    version: number;
+    /** 默认值:无存档 / 校验失败 / 迁移失败时回退到它(返回时深拷贝,避免外部改动污染) */
+    defaults: T;
+    /**
+     * 迁移函数:旧存档版本低于当前 version 时调用。
+     *
+     * 迁移策略:本实现采用"一次性迁移"——把整份旧 data 与其 oldVersion 交给 migrate,
+     * 由 migrate 负责一步到位升级到当前结构。之所以不做框架级"逐版本链式迁移",
+     * 是为了让业务对升级路径有完全掌控(可在 migrate 内部按 oldVersion 走 switch 自行逐版本处理),
+     * 框架不强加 1→2→3 的注册形态,保持 API 极简。
+     *
+     * @param oldData    旧版本读出的原始 data(结构未知,业务按 oldVersion 判断)
+     * @param oldVersion 旧存档的版本号
+     * @returns 升级到当前 version 的完整 data
+     */
+    migrate?: (oldData: any, oldVersion: number) => T;
+}
+/**
+ * 单个存档槽的读写句柄。
+ * @template T 存档数据结构
+ */
+interface SaveSlot<T> {
+    /**
+     * 读取存档。
+     * - 无记录 → 返回 defaults 的深拷贝;
+     * - 版本落后 → 调用 migrate 升级并写回新版本后返回;
+     * - 校验失败 → warn 并回退 defaults 深拷贝。
+     */
+    load(): T;
+    /** 全量保存:写入 data 并按当前 version 落盘 { v, data, sum } */
+    save(data: T): void;
+    /** 增量更新:读出当前存档,浅合并 partial,再保存 */
+    patch(partial: Partial<T>): void;
+    /** 重置为 defaults 并写回存储 */
+    reset(): void;
+    /** 当前存档槽的版本号(只读) */
+    readonly version: number;
+}
+/**
+ * 存档系统门面。负责注册存档槽;真正的读写逻辑在每个 SaveSlotImpl 内。
+ *
+ * 设计为可多次 register 不同 key 的轻量管理器;同一 key 重复 register 会复用已注册的槽
+ * (避免同一存档被两套配置写坏),并 warn 提示。
+ */
+declare class SaveManager {
+    /** 已注册的存档槽,按 key 去重 */
+    private readonly slots;
+    /**
+     * 注册一个存档槽。返回的 SaveSlot 即业务读写存档的唯一入口。
+     * @template T 存档数据结构
+     */
+    register<T>(opts: SaveSlotOptions<T>): SaveSlot<T>;
+}
+
+/**
+ * 单张配置表(ConfigTable)。
+ *
+ * 数据驱动:策划导出的数据(数组或字典)经主键索引后,业务按 id 读取。
+ * 表内数据视为只读,业务不应修改返回的对象引用。
+ */
+declare class ConfigTable<T> {
+    /** 主键(string|number 统一转 string 作为 Map key) -> 行数据 */
+    private readonly index;
+    /**
+     * @param rows 已构造好的行集合
+     * @param primaryKey 主键字段名(默认 'id'),用于建立索引
+     */
+    constructor(rows: T[], primaryKey?: string);
+    /** 按主键取一行;不存在返回 undefined */
+    get(id: string | number): T | undefined;
+    /** 返回全部行(顺序为插入顺序) */
+    all(): T[];
+    /** 是否存在某主键 */
+    has(id: string | number): boolean;
+    /** 行数 */
+    get size(): number;
+}
+
+/**
+ * 配置表管理器(ConfigTableManager)。
+ *
+ * 职责:按名加载 JSON 配置数据、建表并缓存,供全局按名复用。
+ *
+ * - 数据来源统一走 App.assets.loadJson(跨平台正确取字节/URL)。
+ * - 支持两种 JSON 形态:
+ *     数组形态 [{ id, ... }, ...]
+ *     字典形态 { "1001": { ... }, "1002": { ... } }
+ *   字典形态会把每个值取出组成行;若值自身缺主键字段,则用字典的 key 回填主键。
+ * - 同名表重复 load 直接复用缓存,不重复请求(除非先 unload)。
+ */
+
+declare class ConfigTableManager {
+    /** 表名 -> 已建好的配置表(用 unknown 擦除元素类型,get<T> 时再断言) */
+    private readonly tables;
+    /**
+     * 按名加载并缓存一张配置表。已缓存则直接返回缓存,不重复请求。
+     *
+     * @param name 表名(后续 get/has/unload 的键)
+     * @param path 资源路径(交给 App.assets.loadJson)
+     * @param primaryKey 主键字段名,默认 'id'
+     */
+    load<T>(name: string, path: string, primaryKey?: string): Promise<ConfigTable<T>>;
+    /**
+     * 取已加载的表;未加载抛出清晰错误(提示先 load)。
+     */
+    get<T>(name: string): ConfigTable<T>;
+    /** 是否已加载某表 */
+    has(name: string): boolean;
+    /** 卸载某表缓存(下次 load 会重新请求);返回是否确有该表 */
+    unload(name: string): boolean;
+    /**
+     * 把数组或字典两种形态归一化成行数组。
+     * - 数组:直接使用。
+     * - 字典:取所有值;若某值缺主键,则用字典 key 回填(便于字典形态省略 id)。
+     */
+    private normalize;
+}
+
+/**
+ * 面板管理器 PanelManager:统一管理"弹出式面板"的栈与层级。
+ *
+ * 设计目标:让业务只关心"开/关哪个面板",不关心加到哪个场景、设多少 depth、谁压谁。
+ * - 面板按"注册 key → 构造器"登记,open(key) 时按需实例化。
+ * - 面板加入"当前活动场景"的显示列表(取 game.scene.getScenes(true) 最上层那个)。
+ * - depth 用 `Layers.Panel + 栈深` 递增,保证后开的面板压在先开的之上。
+ * - 维护一个面板栈:closeTop / closeAll 配合返回键 / 全局关闭等常见交互。
+ *
+ * 与 bootstrap 的关系:整合阶段 bootstrap 创建 Phaser.Game 后调用 bindGame(game),
+ * 之后业务即可通过 App 门面拿到的 PanelManager 实例随处开关面板。
+ */
+
+/** 面板构造器签名:接收所属场景 */
+type PanelCtor = new (scene: Phaser.Scene) => BasePanel;
+/**
+ * 面板管理器对外契约,供 App 门面引用(业务面对接口而非实现)。
+ */
+interface IPanelManager {
+    /** 注册面板:key 唯一,ctor 为面板类构造器 */
+    register(key: string, ctor: PanelCtor): void;
+    /** 打开面板(已开则返回已有实例);异步,等 onCreate 完成后 resolve */
+    open(key: string, data?: unknown): Promise<BasePanel>;
+    /** 关闭指定 key 的面板 */
+    close(key: string): void;
+    /** 关闭栈顶面板 */
+    closeTop(): void;
+    /** 关闭全部面板 */
+    closeAll(): void;
+    /** 指定 key 的面板是否打开中 */
+    isOpen(key: string): boolean;
+}
+declare class PanelManager implements IPanelManager {
+    /** key → 构造器 */
+    private readonly registry;
+    /** 打开中的面板栈(后进者在数组尾,即栈顶) */
+    private readonly stack;
+    /** bootstrap 注入的 Phaser.Game,用于取当前活动场景 */
+    private game;
+    /** 由 bootstrap 在 Phaser.Game 创建后调用 */
+    bindGame(game: Phaser.Game): void;
+    register(key: string, ctor: PanelCtor): void;
+    /**
+     * 打开面板。流程:
+     *   取栈顶活动场景 → new 面板 → 加入场景显示列表 → setDepth(Layers.Panel + 栈深)
+     *   → await onCreate → onShow → 压栈
+     * 若同 key 已打开,直接返回已有实例(不重复创建)。
+     */
+    open(key: string, data?: unknown): Promise<BasePanel>;
+    close(key: string): void;
+    closeTop(): void;
+    closeAll(): void;
+    isOpen(key: string): boolean;
+    /** 当前打开的面板数量 */
+    get stackSize(): number;
+    /** 执行一个面板的 onHide → onClose(释放) */
+    private teardown;
+    /** 关闭非栈顶面板后,按当前栈顺序重排剩余面板的 depth */
+    private reindexDepth;
+    private find;
+    /**
+     * 取"当前活动场景"作为面板宿主:用 game.scene.getScenes(true)(运行中的场景)
+     * 的最上层(数组末尾,渲染序最高)那个。
+     *
+     * 扩展点:若业务需要把面板固定挂到某个专用 UI 场景(而非当前场景),
+     * 可在此处改为按指定 sceneKey 取场景,或给 open 增加 targetScene 参数后在此分发。
+     */
+    private activeScene;
+}
+
+/**
+ * 面板基类 BasePanel(基于 Phaser.GameObjects.Container)。
+ *
+ * 业务写一个面板(商店、背包、设置、对话框……)的标准姿势:
+ *   export class ShopPanel extends BasePanel {
+ *     protected async onCreate(data?: unknown) {
+ *       this.addDim();                                  // 半透明遮罩(可选)
+ *       const bg = this.scene.make.image({ ... }, false);
+ *       this.add(bg);                                   // 子对象 add 进容器,不重复加入场景根
+ *       const close = new Button(this.scene, { text: '关闭', onClick: () => this.close() });
+ *       this.add(close);
+ *       this.bind(this.app.events.on('coin:change', (n) => { ... })); // 订阅,关闭时自动清理
+ *     }
+ *     protected onShow() {  ...  }   // 入场动画 / 刷新数据
+ *     protected onHide() {  ...  }   // 退场动画
+ *     // onClose 一般不需覆写:基类默认会清理所有 bind 并 destroy 容器
+ *   }
+ *
+ * 设计要点(为减少 AI 漏清理导致的泄漏):
+ * - 生命周期清晰:onCreate(构建)→ onShow(显示)→ onHide(隐藏)→ onClose(释放)。
+ * - 清理自动化:任何需要在关闭时撤销的订阅/句柄,用 `this.bind(unsub)` 登记;
+ *   基类 onClose 默认实现会统一执行全部清理并销毁容器,业务无需手写 destroy。
+ * - 面板自身不直接出现在 PanelManager 之外的代码里管理生命周期;关闭走 `this.close()`。
+ */
+
+declare abstract class BasePanel extends Phaser.GameObjects.Container {
+    /** 打开本面板时所属的 key(由 PanelManager 在创建后注入,用于自我关闭) */
+    private _key;
+    /** 管理本面板的 PanelManager(由其在创建后注入) */
+    private _manager;
+    /** open 时透传进来的业务数据 */
+    private _data;
+    /** 关闭时需要逐一执行的清理句柄(订阅、定时器等) */
+    private readonly disposers;
+    /** 防止重复关闭 */
+    private closing;
+    constructor(scene: Phaser.Scene);
+    /** App 门面:面板内访问网络/音频/存储/事件等的统一入口 */
+    protected get app(): typeof App;
+    /**
+     * open 时传入的业务数据(子类在 onCreate/onShow 中读取)。
+     * 注意:Phaser.Container 自身的 `data` 字段是其内置 DataManager,
+     * 故业务数据用 `panelData` 暴露,避免与基类字段冲突。
+     */
+    protected get panelData(): unknown;
+    /** 本面板的注册 key */
+    get key(): string;
+    /**
+     * 构建 UI。子类覆写,在此创建并 add 所有子对象。
+     * 可返回 Promise(异步加载资源/数据时),PanelManager 会 await 后再 onShow。
+     * @param data open 时透传的业务数据(等价于 this.data)
+     */
+    protected onCreate(_data?: unknown): void | Promise<void>;
+    /** 显示时回调(入场动画 / 数据刷新)。子类按需覆写。 */
+    protected onShow(): void;
+    /** 隐藏时回调(退场动画)。子类按需覆写。在 onClose 之前调用。 */
+    protected onHide(): void;
+    /**
+     * 释放回调。默认实现:执行全部 bind 登记的清理 + 销毁容器。
+     * 子类如需自定义释放逻辑,覆写后请调用 super.onClose() 以保证基础清理执行。
+     */
+    protected onClose(): void;
+    /**
+     * 登记一个需在面板关闭时自动撤销的句柄(事件订阅返回的 Unsubscribe、
+     * 自定义清理函数等)。基类 onClose 会统一执行,业务无需手动记账。
+     */
+    protected bind(unsub: Unsubscribe): void;
+    /** 关闭自己(委托给 PanelManager 走完整的 onHide → onClose → 出栈)。 */
+    close(): void;
+    /**
+     * 添加一层覆盖全屏的半透明遮罩(放在面板最底层),点击可选触发关闭。
+     * 以设计稿尺寸铺满;遮罩本身加入容器,随面板一起销毁。
+     * @param opts.color 遮罩颜色(默认黑)
+     * @param opts.alpha 不透明度(默认 0.6)
+     * @param opts.closeOnClick 点击遮罩是否关闭面板(默认 false)
+     */
+    protected addDim(opts?: {
+        color?: number;
+        alpha?: number;
+        closeOnClick?: boolean;
+    }): Phaser.GameObjects.Graphics;
+    /**
+     * 把一个子对象放到设计稿正中(以设计稿坐标系)。
+     * 仅设置坐标,不负责 add(由调用方决定何时 add 进容器)。
+     */
+    protected centerChild(child: Phaser.GameObjects.Components.Transform): void;
+    /** 设计稿宽度(来自 App.config) */
+    protected get designWidth(): number;
+    /** 设计稿高度(来自 App.config) */
+    protected get designHeight(): number;
+    /**
+     * PanelManager 创建面板后注入归属信息。下划线前缀表示"框架内部使用",业务勿调。
+     */
+    __attach(manager: IPanelManager, key: string, data: unknown): void;
+    /** 触发 onCreate(可能异步)。仅 PanelManager 调用。 */
+    __create(): void | Promise<void>;
+    /** 触发 onShow。仅 PanelManager 调用。 */
+    __show(): void;
+    /** 触发 onHide。仅 PanelManager 调用。 */
+    __hide(): void;
+    /** 触发 onClose(释放)。仅 PanelManager 调用,带防重入。 */
+    __close(): void;
+    /** 逐一执行并清空已登记的清理句柄(单个失败不影响其余)。 */
+    private runDisposers;
+    /** 容器是否已被销毁(Phaser 销毁后 scene 引用会被清空) */
+    private get destroyed();
+}
+
+/**
+ * 全局层级(depth)常量。
+ *
+ * Phaser 用 `gameObject.setDepth(n)` 决定同一显示列表内的渲染先后:depth 大者后绘、显示在上层。
+ * 框架把"全屏 UI 类对象"划分为若干固定层段,业务统一引用本表,避免各处 setDepth 魔法数字打架。
+ *
+ * setDepth 约定:
+ * - 同一层段内可用 `Layers.X + 局部偏移` 微调先后(如 Panel 栈深),但不要跨段污染。
+ * - PanelManager 开面板时按 `Layers.Panel + 栈深` 设置,保证后开的面板压在先开的之上。
+ * - 业务自己的 HUD / Toast / Loading / Guide 也应取对应层段,确保它们恒在面板之上或之下的预期位置。
+ *
+ * 各层用途:
+ * - Scene   场景背景层(地图、天空盒、场景静态装饰)。
+ * - Entity  实体层(角色、怪物、道具、子弹等可玩对象)。
+ * - Hud     常驻 HUD(血条、分数、摇杆、顶栏),恒在实体之上、面板之下。
+ * - Panel   弹出式面板(商店、背包、设置、对话框),由 PanelManager 管理的栈。
+ * - Toast   轻提示(飘字、Toast、气泡),压在面板之上但不抢占输入焦点。
+ * - Loading 加载遮罩 / 转场遮罩,几乎盖住一切。
+ * - Guide   新手引导高亮 / 蒙层,需要在最顶层强制吸引注意。
+ */
+declare const Layers: {
+    /** 场景背景层 */
+    readonly Scene: 0;
+    /** 实体层(角色、道具、子弹等) */
+    readonly Entity: 100;
+    /** 常驻 HUD 层 */
+    readonly Hud: 1000;
+    /** 弹出面板层(PanelManager 管理) */
+    readonly Panel: 2000;
+    /** 轻提示 / Toast 层 */
+    readonly Toast: 3000;
+    /** 加载 / 转场遮罩层 */
+    readonly Loading: 4000;
+    /** 新手引导层(最顶) */
+    readonly Guide: 5000;
+};
+/** 层级键名联合类型(便于业务做类型约束) */
+type LayerName = keyof typeof Layers;
+
+/**
+ * 业务模块基类 BaseModule。
+ *
+ * "模块"是业务层的一块自治功能单元(如金币模块、任务模块、好友模块):
+ * 持有该功能的状态与逻辑,对外通过事件总线 / 公开方法协作,不直接耦合 UI/场景。
+ *
+ * 业务写一个模块的标准姿势:
+ *   export class CoinModule extends BaseModule {
+ *     readonly name = 'coin';
+ *     private coin = 0;
+ *     async init() {                              // 启动时初始化(可异步:读存档/拉服务端)
+ *       this.coin = this.app.storage.get('coin', 0)!;
+ *     }
+ *     add(n: number) {
+ *       this.coin += n;
+ *       this.app.storage.set('coin', this.coin);
+ *       this.app.events.emit('coin:change', this.coin);
+ *     }
+ *     dispose() {  ...  }                          // 释放(清订阅/定时器)
+ *   }
+ *
+ * 然后注册:registry.register(new CoinModule());  registry.initAll();
+ * 别处取用:registry.get<CoinModule>('coin').add(10);
+ *
+ * 设计要点:
+ * - name 唯一,作为 ModuleRegistry 的检索键。
+ * - 生命周期清晰:init(启动,可异步)→ dispose(释放)。
+ * - 通过 this.app 访问底层服务,模块之间不互相 new,而是经 registry.get 取依赖。
+ */
+
+declare abstract class BaseModule {
+    /** 模块唯一名,作为 ModuleRegistry 的检索键。子类必须提供。 */
+    abstract readonly name: string;
+    /** App 门面:模块内访问网络/存储/事件等的统一入口 */
+    protected get app(): typeof App;
+    /**
+     * 初始化。ModuleRegistry.initAll 按注册顺序调用,可返回 Promise 以等待
+     * 异步初始化(读存档、拉服务端配置等)完成后再初始化下一个模块。
+     * 默认空实现,子类按需覆写。
+     */
+    init(): void | Promise<void>;
+    /**
+     * 释放。ModuleRegistry.disposeAll 调用,清理订阅 / 定时器 / 缓存等。
+     * 默认空实现,子类按需覆写。
+     */
+    dispose(): void;
+}
+
+/**
+ * 模块注册表 ModuleRegistry:业务模块的容器与生命周期协调者。
+ *
+ * 职责:
+ * - register:登记模块(按 name 唯一)。
+ * - initAll:按"注册顺序"依次 init,await 异步初始化,保证依赖在前者先就绪。
+ * - disposeAll:释放全部模块(逆注册顺序,先释放后注册的,降低相互依赖踩坑)。
+ * - get / has:按 name 取模块,供模块间协作或 UI/场景获取业务能力。
+ *
+ * 典型接线(整合阶段或业务启动处):
+ *   const registry = new ModuleRegistry();
+ *   registry.register(new CoinModule());
+ *   registry.register(new TaskModule());     // 若 Task 依赖 Coin,Coin 先注册即先 init
+ *   await registry.initAll();
+ *   ...
+ *   registry.get<CoinModule>('coin').add(10);
+ */
+
+declare class ModuleRegistry {
+    /** name → 模块实例 */
+    private readonly modules;
+    /** 注册顺序(initAll 正序、disposeAll 逆序据此遍历) */
+    private readonly order;
+    /**
+     * 注册一个模块。name 重复将抛错(避免静默覆盖导致取到错误实例)。
+     */
+    register(module: BaseModule): void;
+    /**
+     * 按注册顺序依次初始化所有模块,await 异步 init。
+     * 串行(非并行)以尊重模块间的初始化依赖顺序。
+     */
+    initAll(): Promise<void>;
+    /**
+     * 释放所有模块。按逆注册顺序释放(后注册者先释放),
+     * 单个模块 dispose 抛错不阻断其余模块释放。
+     */
+    disposeAll(): void;
+    /**
+     * 按 name 取模块,取不到抛清晰错误(避免业务拿到 undefined 后在更深处崩溃)。
+     * 泛型 T 便于直接拿到具体模块类型,无需手动断言。
+     */
+    get<T extends BaseModule = BaseModule>(name: string): T;
+    /** 指定 name 的模块是否已注册 */
+    has(name: string): boolean;
+    /** 已注册模块数量 */
+    get size(): number;
+}
+
+/**
+ * App 门面契约。业务层唯一的"上帝对象":
+ *   import { App } from '@maoyugames/phaser-framework';
+ *   App.net / App.audio / App.scenes ...
+ *
+ * 由 bootstrap 在平台初始化完成后组装出具体实例,业务全程只用接口。
+ */
+
+interface IApp {
+    /** 当前平台(只读能力查询;具体调用优先用上层服务) */
+    readonly platform: IPlatform;
+    /** 网络:http() / websocket() / kcp() / defaultHttp */
+    readonly net: INetManager;
+    /** 全局事件总线 */
+    readonly events: IEventBus;
+    /** 日志 */
+    readonly log: ILogger;
+    /** 运行时配置(只读) */
+    readonly config: IConfigService;
+    /** 音频 */
+    readonly audio: IAudioManager;
+    /** 本地存储(带序列化) */
+    readonly storage: IStorageManager;
+    /** 资源加载(跨平台) */
+    readonly assets: IAssetLoader;
+    /** 广告 */
+    readonly ads: IAdsManager;
+    /** 支付/内购 */
+    readonly payment: IPaymentManager;
+    /** 数据上报 */
+    readonly analytics: IAnalyticsManager;
+    /** 账号/登录 */
+    readonly account: IAccountService;
+    /** 场景管理 */
+    readonly scenes: ISceneManager;
+    /** 多语言:t() 取文案 / setLocale 切换语言 */
+    readonly i18n: I18n;
+    /** 存档系统:register 存档槽,做版本迁移 + 校验 */
+    readonly save: SaveManager;
+    /** 配置表:按名 load / get 数据驱动配置 */
+    readonly tables: ConfigTableManager;
+    /** 弹出式面板栈:open/close 面板(业务面对接口,不触碰实现) */
+    readonly panels: IPanelManager;
+    /** 业务模块注册表:register/initAll/get 业务功能模块 */
+    readonly modules: ModuleRegistry;
+    /**
+     * 平台前后台生命周期(经门面暴露):onShow / onHide。
+     * 业务直接用 App.lifecycle 订阅,不再绕 App.platform.lifecycle。
+     */
+    readonly lifecycle: IPlatformLifecycle;
+}
+
+/**
+ * App 门面单例。业务层唯一的"上帝对象":
+ *   import { App } from '@maoyugames/phaser-framework';
+ *   App.net / App.audio / App.scenes ...
+ *
+ * 延迟注入模式:
+ * - 模块加载时 App 各字段尚未就绪(底层服务需等平台 init 完成才能构造)。
+ * - bootstrap 在平台初始化、各服务构造完成后,调用内部的 __initApp(parts) 一次性注入。
+ * - 注入前访问任意字段都会抛出清晰错误,提示"请通过 startGame() 启动",
+ *   而不是让业务拿到 undefined 后在更深处莫名其妙地崩溃。
+ *
+ * 实现手法:用闭包持有可空的 parts,导出的 App 是一个 getter 代理对象,
+ * 每个字段 getter 在未注入时抛错,已注入时返回真实服务实例。
+ */
+
+/**
+ * App 门面单例。所有字段为只读 getter,实现延迟注入。
+ * 类型严格实现 IApp,业务面对的就是接口,无法触碰底层实现细节。
+ */
+declare const App: IApp;
+
+/**
+ * 框架启动流程。平台入口(main.<platform>.ts)调用 startGame() 拉起整个游戏:
+ *
+ *   import { startGame } from '@maoyugames/phaser-framework';
+ *   import { WebPlatform } from '@maoyugames/phaser-framework/platform/web';
+ *   startGame({ platform: new WebPlatform(), config: gameConfig, scenes });
+ *
+ * 启动顺序:
+ *   ① PlatformContext.set(platform)   注入当前平台实现(全局唯一)
+ *   ② await platform.init()           平台初始化(读系统信息、注入 SDK、起适配器)
+ *   ③ 构造各底层服务                   NetManager / EventBus / Logger / Config / Storage /
+ *                                      Audio / Assets / Ads / Payment / Analytics / Account / Scene
+ *                                      + I18n / SaveManager / ConfigTableManager / ModuleRegistry / PanelManager
+ *                                      (lifecycle 直接复用 platform.lifecycle)
+ *   ④ __initApp(parts)                组装进 App 门面(此后业务可安全访问 App.*)
+ *   ⑤ new Phaser.Game(...)            创建 Phaser 实例(FIT + CENTER_BOTH,设计分辨率来自 config)
+ *   ⑥ 把 game 交给 AudioManager / SceneManager / PanelManager(它们依赖 game.sound / game.scene)
+ *   ⑦ await App.modules.initAll()     初始化业务注册的模块(业务在 startGame 前/中注册;无模块也安全)
+ *
+ * 跨平台说明:
+ * - DOM 平台(web/tiktok/capacitor):Phaser 自动创建 canvas 挂到 document.body。
+ * - 微信小游戏(hasDOM=false):由 weapp-adapter 提供 document.createElement('canvas')
+ *   及 window 等 shim,因此这里无需特判平台,Phaser 配置一致即可。
+ */
+
+/** startGame 入参 */
+interface StartGameOptions {
+    /** 当前平台实现(由平台入口静态 import 并 new) */
+    platform: IPlatform;
+    /** 全局运行时配置 */
+    config: AppConfig;
+    /** 业务场景列表(第一个为初始场景) */
+    scenes: Phaser.Types.Scenes.SceneType[];
+    /**
+     * 业务注册入口(可选)。在 App 门面就绪后、创建 Phaser 场景与初始化模块之前调用。
+     * 业务在此统一注册:模块(App.modules.register)、面板(App.panels.register)、
+     * 语言包(App.i18n.addBundle)、存档槽(App.save.register)、预加载配置表(App.tables.load)等。
+     * 支持 async(如需 await 配置表加载)。
+     */
+    setup?: (app: IApp) => void | Promise<void>;
+}
+/**
+ * 启动游戏。平台无关,可被任意平台入口复用。
+ * 返回的 Promise 在 Phaser.Game READY 后 resolve。
+ */
+declare function startGame(opts: StartGameOptions): Promise<void>;
+
+/**
+ * 调度器(Scheduler)。
+ *
+ * 统一封装延迟(delay)、周期(interval)、下一帧(nextTick)三类定时,
+ * 关键价值在于:所有句柄被集中跟踪,可一键 clearAll——
+ * 让场景/面板在销毁时把自己启动的所有定时器一次性清掉,杜绝泄漏与"幽灵回调"。
+ *
+ * 实现:底层用 setTimeout/setInterval;nextTick 优先用 microtask(Promise),
+ * 不可用时降级 setTimeout(0)。每个句柄 cancel 幂等(重复 cancel 无副作用)。
+ */
+interface ScheduleHandle {
+    /** 取消本次调度;幂等,可安全多次调用 */
+    cancel(): void;
+}
+declare class Scheduler {
+    /** 所有未结束的句柄;clearAll 时统一取消 */
+    private readonly handles;
+    /** 延迟 ms 后执行一次 fn */
+    delay(ms: number, fn: () => void): ScheduleHandle;
+    /** 每隔 ms 周期执行 fn,直到 cancel/clearAll */
+    interval(ms: number, fn: () => void): ScheduleHandle;
+    /** 下一个微任务(或 setTimeout 0)执行一次 fn */
+    nextTick(fn: () => void): ScheduleHandle;
+    /** 取消单个句柄(等价于 handle.cancel(),幂等) */
+    clear(handle: ScheduleHandle): void;
+    /** 取消并清空所有句柄 */
+    clearAll(): void;
+}
+
+/**
+ * 业务场景基类 BaseScene。
+ *
+ * 所有业务场景继承它(而非直接继承 Phaser.Scene),从而:
+ * - 通过 this.app 便捷访问 App 门面(等价于 import { App } from '@maoyugames/phaser-framework')。
+ * - 通过安全区辅助(this.safeArea / this.safeTop ...)规避刘海屏、小游戏胶囊按钮。
+ * - 通过设计分辨率辅助(this.designWidth/Height、this.centerX/Y、this.scaleToFit)
+ *   写出与具体屏幕无关、按设计稿坐标布局的场景。
+ *
+ * 设计分辨率取自 App.config(designWidth/designHeight),与 bootstrap 里 Phaser scale
+ * 配置一致(FIT + CENTER_BOTH),因此场景内可直接按设计稿坐标摆放元素。
+ */
+
+declare abstract class BaseScene extends Phaser.Scene {
+    /** App 门面:业务在场景内访问网络/音频/存储等的统一入口 */
+    protected get app(): typeof App;
+    /**
+     * 场景级定时器(E4)。
+     * 业务在场景内用 this.scheduler.delay/interval/nextTick 启动定时,
+     * 场景 shutdown / destroy 时框架自动 clearAll(),避免"幽灵回调"。
+     */
+    protected readonly scheduler: Scheduler;
+    /**
+     * 需在场景关闭时清理的订阅句柄登记表(E4)。
+     * 收集 App.events.on / socket.onMessage / platform.lifecycle.onShow 等返回的 Unsubscribe,
+     * 场景 shutdown / destroy 时统一执行并清空,避免订阅泄漏。
+     */
+    private readonly _bindings;
+    /** 清理钩子是否已注册(防止同一实例重复注册) */
+    private _cleanupArmed;
+    /**
+     * E4 构造时挂上场景生命周期清理钩子。
+     *
+     * Phaser 场景实例可被复用(stop → start 重启):重启时不会再走 constructor,
+     * 但会再次触发 create。因此清理逻辑必须在每次 SHUTDOWN 都执行,并在执行后
+     * 重新登记(re-arm),保证下一轮生命周期同样被覆盖;DESTROY(实例被移除)只需一次。
+     */
+    constructor(config?: string | Phaser.Types.Scenes.SettingsConfig);
+    /**
+     * 登记需在场景关闭时清理的订阅(E4)。
+     * @param unsub App.events.on / socket.onMessage 等返回的 Unsubscribe
+     *
+     * 用法:this.bind(this.app.events.on('xxx', handler));
+     */
+    protected bind(unsub: Unsubscribe): void;
+    /** 注册 SHUTDOWN / DESTROY 清理钩子;SHUTDOWN 用 once + 自重注册以覆盖场景重启 */
+    private armCleanupHooks;
+    /** 执行全部清理:解绑所有 bind 的订阅 + 清空场景调度器,并重置登记表 */
+    private runCleanup;
+    /** 设计稿宽度(来自 App.config) */
+    protected get designWidth(): number;
+    /** 设计稿高度(来自 App.config) */
+    protected get designHeight(): number;
+    /** 设计稿水平中心 X */
+    protected get centerX(): number;
+    /** 设计稿垂直中心 Y */
+    protected get centerY(): number;
+    /** 当前平台安全区(刘海/胶囊规避用),来自 App.platform.info.safeArea */
+    protected get safeArea(): SafeArea;
+    protected get safeTop(): number;
+    protected get safeBottom(): number;
+    protected get safeLeft(): number;
+    protected get safeRight(): number;
+    /**
+     * 安全区内的可用矩形(以设计稿坐标系表示)。
+     * 业务把关键 UI(返回按钮、顶栏)摆进这个矩形内即可避开遮挡。
+     */
+    protected get safeRect(): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /**
+     * 计算把内容(srcW × srcH)等比缩放以"填满"目标框(dstW × dstH)的缩放系数。
+     * 用于背景图铺满、保持比例的图标缩放等。
+     */
+    protected scaleToFill(srcW: number, srcH: number, dstW: number, dstH: number): number;
+    /**
+     * 计算把内容等比缩放以"放进"目标框(不裁切)的缩放系数。
+     */
+    protected scaleToFit(srcW: number, srcH: number, dstW: number, dstH: number): number;
+}
+
+/**
+ * 基础按钮组件 Button(基于 Phaser.GameObjects.Container)。
+ *
+ * 真实可用,作为 UI 基础设施示范:
+ * - 圆角背景(Graphics)+ 居中文本(Text)。
+ * - 支持点击回调 onClick、按下态(缩放 + 变暗)、禁用态。
+ * - 设置整体为可交互区域,处理 pointerover/out/down/up,跨平台触摸/鼠标一致。
+ *
+ * 业务用法:
+ *   const btn = new Button(this, { x, y, text: '开始', onClick: () => {...} });
+ *   this.add.existing(btn);  // 或 Button 构造内已自动加入场景
+ */
+
+interface ButtonStyle {
+    width?: number;
+    height?: number;
+    /** 背景颜色(常态) */
+    backgroundColor?: number;
+    /** 背景颜色(按下/悬停) */
+    backgroundColorActive?: number;
+    /** 圆角半径 */
+    radius?: number;
+    /** 文本颜色,如 '#ffffff' */
+    textColor?: string;
+    /** 字号 px */
+    fontSize?: number;
+    /** 字体族 */
+    fontFamily?: string;
+}
+interface ButtonConfig extends ButtonStyle {
+    x?: number;
+    y?: number;
+    text: string;
+    /** 点击回调(按下并在按钮内抬起才触发) */
+    onClick?: () => void;
+}
+declare class Button extends Phaser.GameObjects.Container {
+    private readonly bg;
+    private readonly label;
+    private readonly style;
+    private readonly onClick?;
+    /** 是否禁用 */
+    private _disabled;
+    /** 指针是否在按下且仍停留在按钮内 */
+    private pressed;
+    constructor(scene: Phaser.Scene, config: ButtonConfig);
+    /** 设置/更新按钮文案 */
+    setText(text: string): this;
+    /** 设置禁用态:禁用时变灰且不响应点击 */
+    setDisabled(disabled: boolean): this;
+    get disabled(): boolean;
+    /** 绘制圆角背景(以中心为原点) */
+    private drawBackground;
+    /** 绑定指针交互:悬停/按下/抬起,实现按下态与点击触发 */
+    private bindEvents;
+}
+
+/**
+ * 轻量状态管理(Store)。
+ *
+ * 目标:不引入任何外部库,提供一个浅合并 + 订阅 + 选择器的小型可观察状态容器。
+ * 适合存放局部 UI 状态、玩法运行时数据等。复杂跨模块状态仍建议拆分多个 Store。
+ *
+ * 语义要点:
+ * - set 用浅合并(Object.assign 语义),变更后同步通知所有订阅者。
+ * - subscribe 监听整个 state 的任何变更。
+ * - select 仅在所选子状态值变化(默认 Object.is 比较)时回调,避免无谓刷新。
+ * - reset 回到 initial 的深拷贝(structuredClone,降级 JSON 兜底),
+ *   保证多次 reset 互不污染,且不会把 initial 自身写脏。
+ */
+
+interface Store<T extends object> {
+    /** 取当前状态(只读视图) */
+    get(): Readonly<T>;
+    /** 浅合并补丁;补丁可为对象或基于当前状态计算补丁的函数 */
+    set(patch: Partial<T> | ((s: Readonly<T>) => Partial<T>)): void;
+    /** 订阅整个状态变更;返回取消订阅句柄 */
+    subscribe(fn: (s: Readonly<T>) => void): Unsubscribe;
+    /**
+     * 选择子状态,仅当其值变化时回调。
+     * @param selector 从状态中选出关注的值
+     * @param fn 值变化时回调,(新值, 旧值)
+     * @param equals 自定义相等判断,默认 Object.is
+     */
+    select<K>(selector: (s: Readonly<T>) => K, fn: (v: K, prev: K) => void, equals?: (a: K, b: K) => boolean): Unsubscribe;
+    /** 重置回 initial 的深拷贝 */
+    reset(): void;
+}
+/**
+ * 创建一个 Store。
+ * @param initial 初始状态;内部持有其深拷贝,reset 时复用,不会改写传入对象。
+ */
+declare function createStore<T extends object>(initial: T): Store<T>;
+
+/**
+ * 类型安全的事件总线 TypedEventBus<TMap>。
+ *
+ * 与全局 IEventBus(字符串事件名 + unknown payload)互补:当业务在一个模块内部
+ * 定义一组"事件名 → payload 类型"的映射时,用本类可获得编译期类型检查——
+ * emit 的 payload 类型必须与事件名匹配,on 的 handler 参数类型自动推断。
+ *
+ * 用法:
+ *   interface ShopEvents {
+ *     'item:bought': { id: string; price: number };
+ *     'panel:closed': void;
+ *   }
+ *   const bus = createTypedEventBus<ShopEvents>();
+ *   const off = bus.on('item:bought', (p) => console.log(p.id, p.price)); // p 自动推断
+ *   bus.emit('item:bought', { id: 'a', price: 10 });                       // payload 受检
+ *   off();                                                                  // 取消订阅
+ *
+ * 实现独立(不依赖、不修改 EventBus),逻辑等价:
+ * - 单事件 handler 数组保序;emit 时复制快照,回调内增删不影响本轮派发。
+ * - once 用包装器:触发后先解绑自身再调原 handler,保证重入语义正确。
+ */
+
+/**
+ * 类型化事件总线。TMap 形如 { 'a': PayloadA; 'b': PayloadB }。
+ * payload 为 void 的事件,emit 时第二参可省略。
+ */
+declare class TypedEventBus<TMap extends Record<string, unknown>> {
+    /** 事件名 → 订阅列表 */
+    private readonly map;
+    /**
+     * 订阅事件,返回取消订阅句柄。
+     */
+    on<K extends keyof TMap>(event: K, handler: (payload: TMap[K]) => void): Unsubscribe;
+    /**
+     * 订阅一次:触发后自动解绑。返回的句柄也可在触发前手动取消。
+     */
+    once<K extends keyof TMap>(event: K, handler: (payload: TMap[K]) => void): Unsubscribe;
+    /**
+     * 取消订阅:按原始 handler 匹配移除(只移除第一处匹配,与多次 on 的语义对应)。
+     */
+    off<K extends keyof TMap>(event: K, handler: (payload: TMap[K]) => void): void;
+    /**
+     * 触发事件。payload 类型由 TMap[K] 约束;void 事件可省略第二参。
+     */
+    emit<K extends keyof TMap>(event: K, payload: TMap[K]): void;
+    /**
+     * 清空订阅:传 event 只清该事件,不传清空全部。
+     */
+    clear(event?: keyof TMap): void;
+    private add;
+    private remove;
+}
+/**
+ * 工厂函数:创建一个类型化事件总线实例。
+ *   const bus = createTypedEventBus<MyEvents>();
+ */
+declare function createTypedEventBus<TMap extends Record<string, unknown>>(): TypedEventBus<TMap>;
+
+/**
+ * 通用对象池(ObjectPool)。
+ *
+ * 用途:高频创建/销毁的对象(子弹、特效、列表项节点等)复用,避免 GC 抖动。
+ *
+ * 语义:
+ * - acquire:有空闲则取空闲对象;否则用 factory 新建。新建会计入总数(size)。
+ * - release:可选 reset 后放回空闲队列;若空闲数已达 max,则丢弃(不放回),
+ *   被丢弃对象交给 GC,size 相应减少(它不再由池持有)。
+ * - preallocate:预创建 n 个空闲对象,摊平首次使用时的创建开销。
+ * - clear:清空空闲队列并把已创建总数归零(池放弃对所有对象的持有)。
+ *
+ * 注意:池只跟踪"空闲"对象,acquire 出去的对象由调用方负责 release;
+ * 调用方持有期间池不引用它们,符合"借出—归还"模型。
+ */
+declare class ObjectPool<T> {
+    /** 创建新对象的工厂 */
+    private readonly factory;
+    /** 归还时的重置回调(清状态),可选 */
+    private readonly resetFn?;
+    /** 空闲队列上限;超出则丢弃归还对象。<=0 视为不限制 */
+    private readonly maxSize;
+    /** 空闲对象栈(后进先出,缓存友好) */
+    private readonly free;
+    /** 已创建对象总数(含借出与空闲;被丢弃后相应减少) */
+    private created;
+    /**
+     * @param factory 创建新对象的工厂函数
+     * @param opts.reset 归还时重置对象状态的回调
+     * @param opts.initial 初始预创建数量
+     * @param opts.max 空闲队列上限(超出归还时丢弃);默认不限制
+     */
+    constructor(factory: () => T, opts?: {
+        reset?: (o: T) => void;
+        initial?: number;
+        max?: number;
+    });
+    /** 已创建对象总数(借出 + 空闲) */
+    get size(): number;
+    /** 当前空闲(可被 acquire 直接复用)的对象数 */
+    get available(): number;
+    /** 借出一个对象:优先复用空闲对象,无则新建 */
+    acquire(): T;
+    /**
+     * 归还一个对象。先 reset,再视空闲上限决定放回或丢弃。
+     * 丢弃时该对象不再由池持有,created 相应减少。
+     */
+    release(o: T): void;
+    /** 预创建 n 个空闲对象 */
+    preallocate(n: number): void;
+    /** 清空空闲队列并把已创建总数归零(池放弃所有持有) */
+    clear(): void;
+}
+
+/**
+ * 统一错误模型(FrameworkError)。
+ *
+ * 全框架抛出的"可识别"错误统一用 FrameworkError,携带枚举错误码 + 原始 cause,
+ * 便于上层按 code 分类处理(网络重试、超时提示、平台不支持降级等),
+ * 也便于上报时聚合。第三方/原生异常包到 cause 里,不丢失栈信息。
+ */
+/** 错误分类码 */
+declare enum ErrorCode {
+    /** 未分类错误 */
+    Unknown = 0,
+    /** 网络错误(连接失败、DNS、断网等) */
+    Network = 1,
+    /** 超时 */
+    Timeout = 2,
+    /** HTTP 非 2xx 状态 */
+    HttpStatus = 3,
+    /** WebSocket/长连接被关闭 */
+    SocketClosed = 4,
+    /** 本地存储读写失败 */
+    Storage = 5,
+    /** 当前平台不支持该能力 */
+    PlatformUnsupported = 6,
+    /** 支付/内购失败 */
+    Payment = 7,
+    /** 广告失败 */
+    Ads = 8,
+    /** 配置(配置表/参数)错误 */
+    Config = 9,
+    /** 存档读写/解析错误 */
+    Save = 10
+}
+declare class FrameworkError extends Error {
+    /** 错误分类码 */
+    readonly code: ErrorCode;
+    /** 原始底层异常(第三方/原生错误),可选 */
+    readonly cause?: unknown;
+    constructor(code: ErrorCode, message: string, cause?: unknown);
+    static network(message: string, cause?: unknown): FrameworkError;
+    static timeout(message: string, cause?: unknown): FrameworkError;
+    static httpStatus(message: string, cause?: unknown): FrameworkError;
+    static socketClosed(message: string, cause?: unknown): FrameworkError;
+    static storage(message: string, cause?: unknown): FrameworkError;
+    static platformUnsupported(message: string, cause?: unknown): FrameworkError;
+    static payment(message: string, cause?: unknown): FrameworkError;
+    static ads(message: string, cause?: unknown): FrameworkError;
+    static config(message: string, cause?: unknown): FrameworkError;
+    static save(message: string, cause?: unknown): FrameworkError;
+    static unknown(message: string, cause?: unknown): FrameworkError;
+}
+/** 类型守卫:判断一个值是否 FrameworkError */
+declare function isFrameworkError(e: unknown): e is FrameworkError;
+
+/**
+ * 网络消息层(MessageChannel)。
+ *
+ * 定位:在 ISocketClient(WebSocketClient / KcpClient 都实现它)之上,
+ * 提供"类型路由 + 请求-响应 + 重连钩子"三件套,让业务以"发某类型消息、
+ * 收某类型推送、发请求等响应"的语义收发,而不是手动 encode/decode + 自己配对 seq。
+ *
+ * 三大能力:
+ * 1. 类型路由(on):服务端按 type 推送,业务按 type 注册处理器,解码后自动派发。
+ * 2. 请求-响应(request):自增 seq 随消息发出,登记 pending Promise 与超时;
+ *    收到带同一 seq 的响应即 resolve;超时则 reject(MessageTimeoutError)。
+ * 3. 重连钩子(onReconnect):socket 第一次 open 记为"已连";之后每次 open
+ *    (重连成功)触发 onReconnect,供业务重新鉴权 / 重订阅 / 补偿状态。
+ *
+ * 编解码可插拔(MessageCodec),默认 JsonCodec(string JSON);
+ * 二进制协议(如 protobuf over KCP)可自定义 codec 走 ArrayBuffer。
+ *
+ * 与底层 socket 的职责边界:重连本身由 ISocketClient(及其 Reconnector)负责,
+ * MessageChannel 只在 socket 重新 open 时做应用层补偿(onReconnect),并管理
+ * "重连后 pending 请求"的超时——重连不会自动重发已 pending 的请求(语义上
+ * 旧请求是否还有效由业务决定),它们会照常按各自超时 reject,业务在 onReconnect 里重发。
+ */
+
+/** 消息信封:在 socket 原始字节之上的统一结构 */
+interface MessageEnvelope {
+    /** 消息类型(路由键),如 'chat.msg' / 'room.join' */
+    type: string;
+    /**
+     * 请求序号。request() 发出的消息带递增 seq,服务端响应须回带同一 seq;
+     * send() 单向消息不带 seq(undefined)。
+     */
+    seq?: number;
+    /** 业务负载(任意可被 codec 编码的数据) */
+    payload: unknown;
+}
+/** 编解码器:把信封 ↔ socket 可发送的原始数据(string / ArrayBuffer)互转 */
+interface MessageCodec {
+    encode(env: MessageEnvelope): string | ArrayBuffer;
+    decode(raw: string | ArrayBuffer): MessageEnvelope;
+}
+/** MessageChannel 构造选项 */
+interface MessageChannelOptions {
+    /** 自定义编解码器,默认 JsonCodec */
+    codec?: MessageCodec;
+    /** 请求超时(ms),默认 10000;<=0 表示不超时(谨慎使用,可能永久挂起) */
+    requestTimeoutMs?: number;
+}
+/** 请求超时 / 通道关闭等导致 request 失败的错误(FrameworkError 风格:带 name) */
+declare class MessageError extends Error {
+    constructor(message: string);
+}
+/**
+ * 默认编解码器:信封 → JSON string。
+ * - encode:JSON.stringify 整个信封。
+ * - decode:仅支持 string 输入(JSON 文本);若底层是 ArrayBuffer(二进制协议),
+ *   说明用错了 codec,decode 会抛错提示改用二进制 codec。
+ */
+declare class JsonCodec implements MessageCodec {
+    encode(env: MessageEnvelope): string;
+    decode(raw: string | ArrayBuffer): MessageEnvelope;
+}
+declare class MessageChannel {
+    private readonly socket;
+    private readonly codec;
+    private readonly requestTimeoutMs;
+    /** 递增请求序号(从 1 开始,0 留作"无 seq"语义之外的保留) */
+    private seqCounter;
+    /** 等待响应的请求:seq → pending */
+    private readonly pending;
+    /** 按 type 路由的服务端推送监听器:type → 处理器集合 */
+    private readonly typeListeners;
+    /** 重连(非首次 open)监听器 */
+    private readonly reconnectListeners;
+    /** 是否已发生过首次 open(用于区分"首连"与"重连") */
+    private opened;
+    /** 已注册到 socket 的事件取消句柄,close 时统一清理 */
+    private readonly socketUnsubs;
+    /** 是否已 close(关闭后拒绝新请求 / 不再派发) */
+    private closed;
+    constructor(socket: ISocketClient, opts?: MessageChannelOptions);
+    /** 建立连接(委托底层 socket.connect) */
+    connect(): Promise<void>;
+    /**
+     * 发送请求并等待同 seq 响应。
+     * @template TRes 期望响应 payload 类型
+     * @param type    消息类型
+     * @param payload 请求负载
+     * @returns 服务端响应的 payload(按 TRes 断言)
+     * @throws MessageError 超时 / 通道已关闭 / 发送失败
+     */
+    request<TRes = unknown>(type: string, payload?: unknown): Promise<TRes>;
+    /** 发送单向消息(不带 seq,不等响应) */
+    send(type: string, payload?: unknown): void;
+    /**
+     * 订阅某类型的服务端推送(无 seq 的消息,或带 seq 但无匹配 pending 的消息)。
+     * @template T 推送 payload 类型
+     * @returns 取消订阅句柄
+     */
+    on<T = unknown>(type: string, handler: (payload: T) => void): Unsubscribe;
+    /**
+     * 订阅"重连成功"事件:socket 首次 open 后,再次 open 时触发。
+     * 业务在此重新鉴权 / 重新订阅 / 补偿状态。
+     * @returns 取消订阅句柄
+     */
+    onReconnect(fn: () => void): Unsubscribe;
+    /**
+     * 关闭通道:关闭底层 socket、解绑事件、拒绝所有未决请求、清空监听器。
+     * 关闭后本通道不可再用(再次 connect/request/send 会抛错)。
+     */
+    close(): void;
+    /** 接线底层 socket 的 open / message 事件 */
+    private bindSocket;
+    /** socket open:首次记为"已连",之后每次都视为"重连"并触发 onReconnect */
+    private handleOpen;
+    /** 收到底层数据:解码 → 有 seq 命中 pending 则 resolve,否则按 type 派发 */
+    private handleMessage;
+    /** 取下一个请求序号 */
+    private nextSeq;
+    /** 清理某个 pending(清超时定时器并从表中移除) */
+    private clearPending;
+}
+
+/**
+ * 平台上下文:全局持有"当前平台实现"的唯一入口。
+ *
+ * - 由平台入口(main.<platform>.ts)在启动时通过 bootstrap 注入。
+ * - 网络层 / 服务层通过 PlatformContext.current 拿到平台能力,
+ *   从而与具体平台解耦。
+ */
+
+declare const PlatformContext: {
+    /** 注入当前平台实现(仅 bootstrap 调用一次) */
+    set(platform: IPlatform): void;
+    /** 当前平台实现 */
+    readonly current: IPlatform;
+    /** 是否已初始化 */
+    readonly ready: boolean;
+    /** 仅供测试重置 */
+    _resetForTest(): void;
+};
+
+/**
+ * 网络管理器(INetManager)。
+ *
+ * 作为网络层的工厂门面,业务通过 App.net 拿到它:
+ *   App.net.http()        创建一个 HTTP 客户端
+ *   App.net.websocket()   创建一个 WebSocket 长连接客户端
+ *   App.net.kcp()         创建一个 KCP 长连接客户端
+ *   App.net.defaultHttp   框架级默认 HTTP 单例(baseURL = 构造时传入的 apiBaseURL)
+ *
+ * 构造签名与服务层 bootstrap 约定一致:
+ *   new NetManager({ apiBaseURL })
+ */
+
+/** NetManager 构造参数 */
+interface NetManagerOptions {
+    /** 默认 HTTP 客户端使用的业务后端基址 */
+    apiBaseURL?: string;
+}
+declare class NetManager implements INetManager {
+    private readonly apiBaseURL;
+    /** defaultHttp 懒加载单例 */
+    private _defaultHttp;
+    constructor(opts?: NetManagerOptions);
+    /** 创建一个独立的 HTTP 客户端;不传 config 时默认带上全局 apiBaseURL */
+    http(config?: HttpClientConfig): IHttpClient;
+    /** 创建 WebSocket 长连接客户端 */
+    websocket(config: SocketClientConfig): ISocketClient;
+    /** 创建 KCP 长连接客户端 */
+    kcp(config: KcpClientConfig): ISocketClient;
+    /** 框架级默认 HTTP 单例(读取构造时的 apiBaseURL) */
+    get defaultHttp(): IHttpClient;
+}
+
+/**
+ * HTTP 客户端实现(IHttpClient)。
+ *
+ * 设计要点:
+ * - 不直接用 fetch / wx.request,而是通过 PlatformContext.current.net.request 发请求,
+ *   从而在 web / TikTok / 微信 / Facebook / Capacitor 上行为一致。
+ * - 支持 baseURL 拼接、默认 headers、超时、幂等重试(指数退避)、
+ *   请求 / 响应 / 错误三类拦截器(可链式 use)。
+ * - request<T> 按 responseType 解析并返回 data;get/post/put/delete 为便捷封装。
+ */
+
+declare class HttpClient implements IHttpClient {
+    private readonly baseURL;
+    private readonly headers;
+    private readonly timeout;
+    private readonly retries;
+    /** 拦截器按 use 顺序累积;请求拦截顺序执行,响应拦截顺序执行 */
+    private readonly requestInterceptors;
+    private readonly responseInterceptors;
+    private readonly errorInterceptors;
+    constructor(config?: HttpClientConfig);
+    /** 设置 / 覆盖一个默认请求头(作用于后续所有请求) */
+    setHeader(key: string, value: string): void;
+    /** 注册拦截器,可链式多次调用累积 */
+    use(interceptors: HttpInterceptors): void;
+    /** 核心请求方法:拼 URL、合并 header、跑拦截器、超时、重试、解析返回 */
+    request<T = unknown>(options: HttpRequestOptions): Promise<T>;
+    get<T = unknown>(url: string, options?: Partial<HttpRequestOptions>): Promise<T>;
+    post<T = unknown>(url: string, body?: unknown, options?: Partial<HttpRequestOptions>): Promise<T>;
+    put<T = unknown>(url: string, body?: unknown, options?: Partial<HttpRequestOptions>): Promise<T>;
+    delete<T = unknown>(url: string, options?: Partial<HttpRequestOptions>): Promise<T>;
+    /** 发一次底层请求(经平台层),不含重试 / 拦截器 */
+    private sendOnce;
+    /** baseURL + path 拼接:绝对 URL 原样返回,相对 path 拼基址(处理斜杠) */
+    private resolveUrl;
+    /** 第 attempt 次失败后的退避时长:base 100ms 指数增长,封顶 5s */
+    private backoffMs;
+}
+/** 携带 HTTP 状态码与响应体的错误类型 */
+declare class HttpError extends Error {
+    readonly status: number;
+    readonly data: unknown;
+    constructor(message: string, status: number, data: unknown);
+}
+
+/**
+ * WebSocket 长连接客户端(ISocketClient)。
+ *
+ * 设计要点:
+ * - 不直接 new WebSocket,而是通过 PlatformContext.current.net.createSocket 拿到
+ *   IPlatformSocket(底层是 WebSocket / wx.connectSocket),从而跨平台一致。
+ * - connect() 返回 Promise,在 open 时 resolve、连接失败时 reject。
+ * - 自动重连:autoReconnect / maxReconnect / reconnectIntervalMs 指数退避(复用 Reconnector)。
+ * - 心跳:heartbeatIntervalMs > 0 时定时发送 heartbeatPayload。
+ * - state 状态机:connecting / open / closing / closed;主动 close() 不触发重连。
+ */
+
+declare class WebSocketClient implements ISocketClient {
+    private readonly url;
+    private readonly heartbeatIntervalMs;
+    private readonly heartbeatPayload;
+    private socket;
+    private _state;
+    /** 当前底层 socket 上注册的取消订阅句柄,断开时统一清理 */
+    private socketUnsubs;
+    /** 心跳定时器 */
+    private heartbeatTimer;
+    /** 是否为主动关闭(主动关闭不重连) */
+    private manualClose;
+    /** 当前 connect() 的 resolve/reject(用于把首次连接结果回传给调用方) */
+    private pendingConnect;
+    private readonly reconnector;
+    private readonly openListeners;
+    private readonly messageListeners;
+    private readonly errorListeners;
+    private readonly closeListeners;
+    constructor(config: SocketClientConfig);
+    get state(): SocketState;
+    /** 建立连接:open 时 resolve,失败时 reject。重连由内部自动处理。 */
+    connect(): Promise<void>;
+    send(data: string | ArrayBuffer): void;
+    /** 主动关闭:停心跳、取消重连、关闭底层 socket */
+    close(): void;
+    onOpen(cb: () => void): Unsubscribe;
+    onMessage(cb: (data: string | ArrayBuffer) => void): Unsubscribe;
+    onError(cb: (err: Error) => void): Unsubscribe;
+    onClose(cb: () => void): Unsubscribe;
+    /** 打开一条底层 socket 并接线事件;返回的 Promise 在 open 时 resolve */
+    private openSocket;
+    /** 底层 close 事件处理:停心跳、回调,非主动关闭则安排重连 */
+    private handleClose;
+    /** 标记彻底关闭并通知业务 */
+    private setClosed;
+    /** 解绑当前 socket 的所有事件订阅 */
+    private teardownSocket;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private emitOpen;
+    private emitMessage;
+    private emitError;
+    private emitClose;
+}
+
+/**
+ * KCP 长连接客户端(ISocketClient,KCP 语义)。
+ *
+ * 设计要点:
+ * - KCP 本身只是一个 ARQ 算法层(见 ./kcp/ikcp.ts),需要一条底层 unreliable 数据报通道。
+ *   浏览器 / 小游戏没有原生 UDP,这里默认用 PlatformContext.current.net.createSocket
+ *   建立一条 binaryType=arraybuffer 的 WebSocket 当作"数据报"通道承载 KCP 包。
+ * - 接线:
+ *     kcp.output 回调           → transport.send(ArrayBuffer)   (KCP 产生的包发到网络)
+ *     transport.onMessage(ab)   → kcp.input(bytes)              (网络收到的包喂给 KCP)
+ *     setInterval(intervalMs)   → kcp.update(now) + 循环 kcp.recv() 把就绪消息吐给业务
+ * - send(string|ArrayBuffer):string 用 TextEncoder 转 bytes 再 kcp.send。
+ * - 应用 KcpClientConfig:conv / nodelay / intervalMs / resend / nc / sndWnd / rcvWnd
+ *   映射到 kcp.nodelay() 与 kcp.wndsize()。
+ * - 自动重连复用 Reconnector(与 WebSocketClient 同一套指数退避策略)。
+ *
+ * —— Capacitor 原生 UDP 替换点 ——
+ * 默认 transport 由 createDefaultTransport() 基于 WebSocket 构造。若在 Capacitor 上接入
+ * 原生 UDP 插件(真正的 unreliable datagram),只需提供一个实现 IKcpTransport 的对象,
+ * 通过构造参数 transportFactory 注入即可,KcpClient 其余逻辑零改动:
+ *
+ *   new KcpClient(config, () => new CapacitorUdpTransport(config.url));
+ *
+ * IKcpTransport 只要求 send(ArrayBuffer) + onMessage/onOpen/onError/onClose + close,
+ * 与具体是 WebSocket 还是原生 UDP 无关。
+ */
+
+/**
+ * KCP 底层数据报传输抽象。默认实现包裹 IPlatformSocket(WebSocket),
+ * Capacitor 原生 UDP 实现同样满足此接口即可注入替换。
+ */
+interface IKcpTransport {
+    /** 把一个 KCP 包发到网络(原始字节,不可靠语义由 KCP 负责) */
+    send(data: ArrayBuffer): void;
+    /** 关闭底层通道 */
+    close(): void;
+    onOpen(cb: () => void): Unsubscribe;
+    onMessage(cb: (data: ArrayBuffer) => void): Unsubscribe;
+    onError(cb: (err: Error) => void): Unsubscribe;
+    onClose(cb: () => void): Unsubscribe;
+}
+/** 传输工厂:给定 url 返回一条传输通道。默认基于 WebSocket。 */
+type KcpTransportFactory = (url: string) => IKcpTransport;
+declare class KcpClient implements ISocketClient {
+    private readonly url;
+    private readonly conv;
+    private readonly intervalMs;
+    private readonly cfgNodelay;
+    private readonly cfgResend;
+    private readonly cfgNc;
+    private readonly cfgSndWnd?;
+    private readonly cfgRcvWnd?;
+    private readonly transportFactory;
+    private kcp;
+    private transport;
+    private updateTimer;
+    private _state;
+    private manualClose;
+    private transportUnsubs;
+    private pendingConnect;
+    private readonly reconnector;
+    private readonly textEncoder;
+    private readonly openListeners;
+    private readonly messageListeners;
+    private readonly errorListeners;
+    private readonly closeListeners;
+    constructor(config: KcpClientConfig, transportFactory?: KcpTransportFactory);
+    get state(): SocketState;
+    connect(): Promise<void>;
+    send(data: string | ArrayBuffer): void;
+    close(): void;
+    onOpen(cb: () => void): Unsubscribe;
+    onMessage(cb: (data: string | ArrayBuffer) => void): Unsubscribe;
+    onError(cb: (err: Error) => void): Unsubscribe;
+    onClose(cb: () => void): Unsubscribe;
+    /** 打开底层传输并初始化 KCP;Promise 在传输 open 时 resolve */
+    private openTransport;
+    /** 初始化 KCP 控制块并接线 output、应用配置 */
+    private setupKcp;
+    /** 周期定时器:驱动 kcp.update 并把就绪消息吐给业务 */
+    private startUpdateLoop;
+    private stopUpdateLoop;
+    /** 驱动 KCP 一拍:update(now) + 循环 recv() 把所有就绪消息发给业务 */
+    private pump;
+    private handleClose;
+    private setClosed;
+    private teardownTransport;
+    /** 当前毫秒时间戳 */
+    private now;
+    /**
+     * 默认传输实现:基于 PlatformContext 的 IPlatformSocket(WebSocket / wx.connectSocket)。
+     * binaryType=arraybuffer,把它当作 KCP 的"数据报"通道。
+     *
+     * Capacitor 原生 UDP 替换:实现一个同样满足 IKcpTransport 的类(send 走原生 UDP socket,
+     * onMessage 把收到的 datagram 转 ArrayBuffer 回调),通过构造参数 transportFactory 注入。
+     */
+    private createDefaultTransport;
+    private emitOpen;
+    private emitMessage;
+    private emitError;
+    private emitClose;
+}
+
+/**
+ * 多平台打包配置 PlatformConfig。
+ *
+ * 这是"脚手架 / CLI 构建期"读取的平台元信息单一来源:用户项目在根目录的
+ * platform.config.ts 里 `export default { ... } satisfies PlatformConfig`,
+ * pf CLI 据此为各平台生成外壳(index.html / fbapp-config.json /
+ * game.json / project.config.json / capacitor.config.ts 等)与注入构建变量。
+ *
+ * 设计原则:
+ * - 每个平台一个可选子配置(只构建用到的平台才需填)。
+ * - 字段对应各平台后台/外壳里"必须由开发者填写"的占位项,命名贴合官方术语。
+ * - common 收敛跨平台共享项(后端基址、广告位),避免在每个平台里重复写。
+ *
+ * 注意:本类型描述的是**打包/平台外壳配置**,与运行时业务配置 AppConfig 互不相同
+ * (AppConfig 注入 startGame,PlatformConfig 喂给 CLI/构建)。
+ */
+/** 屏幕方向 */
+type Orientation = 'portrait' | 'landscape';
+/** 跨平台共享的广告位默认配置(可被各平台覆盖) */
+interface AdsConfig {
+    /** 激励视频默认广告位 id */
+    rewardedUnitId?: string;
+    /** 插屏默认广告位 id */
+    interstitialUnitId?: string;
+    /** banner 默认广告位 id */
+    bannerUnitId?: string;
+}
+/** Web(标准 H5)平台配置 */
+interface WebPlatformConfig {
+    /** 页面标题(注入 index.html <title>) */
+    title?: string;
+    /** 屏幕方向(用于 viewport / meta 提示) */
+    orientation?: Orientation;
+    /** 部署 base 路径(子目录部署时设置,如 '/game/') */
+    base?: string;
+    /** 该平台业务后端基址(覆盖 common.apiBaseURL) */
+    apiBaseURL?: string;
+    /** 该平台广告位配置(覆盖 common.ads) */
+    ads?: AdsConfig;
+}
+/** TikTok Mini Games 平台配置 */
+interface TikTokPlatformConfig {
+    /** TikTok 小游戏 SDK 脚本地址(注入 index.html) */
+    sdkUrl?: string;
+    /** 页面标题 */
+    title?: string;
+    /** 屏幕方向 */
+    orientation?: Orientation;
+    /** 业务后端基址(覆盖 common.apiBaseURL) */
+    apiBaseURL?: string;
+    /** 广告位配置(覆盖 common.ads) */
+    ads?: AdsConfig;
+}
+/** 微信小游戏平台配置 */
+interface WeChatPlatformConfig {
+    /** 微信小游戏 AppID(微信公众平台申请,形如 wxXXXXXXXX) */
+    appid: string;
+    /** 项目名称(写入 project.config.json projectname) */
+    projectname?: string;
+    /** 屏幕方向(写入 game.json deviceOrientation) */
+    orientation?: Orientation;
+    /** 业务后端基址(覆盖 common.apiBaseURL;须在微信后台配 request 合法域名) */
+    apiBaseURL?: string;
+    /** 广告位配置(覆盖 common.ads;微信广告位 id 形如 adunit-xxx) */
+    ads?: AdsConfig;
+}
+/** Facebook Instant Games 平台配置 */
+interface FacebookPlatformConfig {
+    /** Facebook 应用 ID(developers.facebook.com 创建 Instant Game 后获得) */
+    appId: string;
+    /** 应用名称 */
+    appName?: string;
+    /** Instant Games SDK 版本(写入 fbapp-config / index.html,如 '7.1') */
+    fbSdkVersion?: string;
+    /** 屏幕方向(写入 fbapp-config orientation,大写) */
+    orientation?: Orientation;
+    /** 业务后端基址(覆盖 common.apiBaseURL) */
+    apiBaseURL?: string;
+    /** 广告位配置(覆盖 common.ads) */
+    ads?: AdsConfig;
+}
+/** Capacitor(iOS + Android 原生 App)平台配置 */
+interface CapacitorPlatformConfig {
+    /** 应用包名/反向域名(写入 capacitor.config appId,如 com.example.app) */
+    appId: string;
+    /** 应用显示名(写入 capacitor.config appName) */
+    appName: string;
+    /** 屏幕方向 */
+    orientation?: Orientation;
+    /** 业务后端基址(覆盖 common.apiBaseURL) */
+    apiBaseURL?: string;
+    /** 广告位配置(覆盖 common.ads) */
+    ads?: AdsConfig;
+}
+/**
+ * 多平台打包配置根类型。
+ *
+ * 用户项目以 `satisfies PlatformConfig` 约束 platform.config.ts 默认导出。
+ * 各平台子配置均可选——只为实际构建的平台填写即可。
+ */
+interface PlatformConfig {
+    /** 跨平台共享项(各平台同名字段覆盖之) */
+    common?: {
+        /** 默认业务后端基址 */
+        apiBaseURL?: string;
+        /** 默认广告位配置 */
+        ads?: AdsConfig;
+    };
+    /** Web(标准 H5) */
+    web?: WebPlatformConfig;
+    /** TikTok Mini Games */
+    tiktok?: TikTokPlatformConfig;
+    /** 微信小游戏 */
+    wechat?: WeChatPlatformConfig;
+    /** Facebook Instant Games */
+    facebook?: FacebookPlatformConfig;
+    /** Capacitor 原生 App */
+    capacitor?: CapacitorPlatformConfig;
+}
+
+export { AdResult, type AdsConfig, App, type AppConfig, BaseModule, BasePanel, BaseScene, Button, type ButtonConfig, type ButtonStyle, type CapacitorPlatformConfig, ConfigTable, ConfigTableManager, ErrorCode, type FacebookPlatformConfig, FrameworkError, Handler, HttpClient, type HttpClientConfig, HttpError, type HttpInterceptors, HttpRequestOptions, I18n, type I18nOptions, type IAccountService, type IAdsManager, type IAnalyticsManager, type IApp, type IAssetLoader, type IAudioManager, type IConfigService, type IEventBus, type IHttpClient, type IKcpTransport, type ILogger, type INetManager, type IPanelManager, type IPaymentManager, IPlatform, IPlatformLifecycle, type ISceneManager, type ISocketClient, type IStorageManager, JsonCodec, KcpClient, type KcpClientConfig, type KcpTransportFactory, type LayerName, Layers, LogLevel, LoginResult, MessageChannel, type MessageChannelOptions, type MessageCodec, type MessageEnvelope, MessageError, ModuleRegistry, NetManager, type NetManagerOptions, type NetProtocol, ObjectPool, type Orientation, type PanelCtor, PanelManager, type PlatformConfig, PlatformContext, PurchaseResult, SafeArea, SaveManager, type SaveSlot, type SaveSlotOptions, type ScheduleHandle, Scheduler, type SocketClientConfig, type SocketState, type StartGameOptions, type Store, type TikTokPlatformConfig, TypedEventBus, Unsubscribe, type WeChatPlatformConfig, type WebPlatformConfig, WebSocketClient, createStore, createTypedEventBus, isFrameworkError, normalizeLocale, startGame };