artplayer-plugin-p2p 1.0.0

package/dist/stats-CFbDXEsi.d.mts

@@ -0,0 +1,294 @@
+import { DownloadSource, CoreConfig, DynamicCoreConfig } from 'p2p-media-loader-core';
+import { HlsJsP2PEngine } from 'p2p-media-loader-hlsjs';
+import Hls, { HlsConfig } from 'hls.js';
+
+/**
+ * 插件公共类型契约
+ *
+ * 本文件是全项目的类型契约源头：下游模块（引擎 / 编排 / UI）
+ * 的签名均以此处定义为准，变更须先同步全部下游再动手
+ *
+ * @module types
+ */
+
+/**
+ * 信令服务器（Tracker）配置组
+ *
+ * 用于将 P2P 信令从公共 tracker 切换到自建 wt-tracker 等私有部署，
+ * 字段名与 p2p-media-loader 的 CoreConfig 完全一致，浅合并进 core
+ */
+interface P2PTrackerOptions {
+    /** WebTorrent tracker 地址列表；不配置时沿用 p2p-media-loader 官方默认公共 tracker */
+    announceTrackers?: string[];
+    /** WebRTC STUN/TURN 配置；自建 ICE 服务时覆盖默认的公共 STUN */
+    rtcConfig?: RTCConfiguration;
+}
+/**
+ * 设置开关组单项显示配置（未指定的项默认显示）
+ */
+interface P2PSettingItemsOptions {
+    /** 是否显示「P2P 加速」开关 */
+    p2pEnabled?: boolean;
+    /** 是否显示「仅上传模式」开关 */
+    uploadOnly?: boolean;
+    /** 是否显示「P2P 统计」开关（stats 关闭时无面板可开，此项不生效） */
+    stats?: boolean;
+}
+interface P2PUIOptions {
+    /**
+     * 设置开关组显示配置：
+     * - true / 省略：三项全显
+     * - false：整组不挂载
+     * - 对象：按项选择性显示
+     */
+    setting?: boolean | P2PSettingItemsOptions;
+}
+/** 插件选项 */
+interface P2POptions {
+    /** customType 注册的格式名，默认 'm3u8' */
+    type?: string;
+    /** 信令服务器配置组，与 core 配置浅合并（本组优先） */
+    tracker?: P2PTrackerOptions;
+    /** 完整 core 配置透传（Partial<CoreConfig>）；其中 isP2PDisabled / isP2PUploadDisabled 由插件开关状态接管 */
+    core?: Partial<CoreConfig>;
+    /** 透传给 hls.js 的配置 */
+    hls?: Partial<HlsConfig>;
+    /** fatal 错误销毁重建的最大次数，默认 2 */
+    fatalRetryMax?: number;
+    /** 初始 P2P 开关，默认 true；运行时可经句柄 setP2PEnabled 无损切换 */
+    enabled?: boolean;
+    /** 初始上传开关，默认 true；运行时可经句柄 setUploadEnabled 无缝切换 */
+    uploadEnabled?: boolean;
+    /** 统计展示总开关，默认 true；false 时不挂「P2P 统计」菜单项与面板，宿主仅能经 getStats() 编程读取 */
+    stats?: boolean;
+    /** UI 总闸：false 时完全无 UI（不挂菜单项 / 面板 / 设置开关组）；对象形式可单独控制设置开关组 */
+    ui?: boolean | P2PUIOptions;
+}
+/** P2P 运行时统计快照（一次性读取全部累计量与派生指标） */
+interface P2PStats {
+    /** 当前已连接的 peer 数量 */
+    peers: number;
+    /** 会话内出现过的峰值 peer 数量 */
+    peakPeers: number;
+    /** 累计 P2P 通道下行字节数 */
+    p2pDownloadedBytes: number;
+    /** 累计 HTTP 通道下行字节数 */
+    httpDownloadedBytes: number;
+    /** 累计 P2P 上行字节数 */
+    uploadedBytes: number;
+    /** 累计总下行字节数（P2P + HTTP） */
+    totalDownloadedBytes: number;
+    /** P2P 下行占总下行比例 0..1（总下行为 0 时为 0） */
+    p2pDownloadRatio: number;
+    /** 总下行速率 B/s（滑动时间窗） */
+    downloadSpeed: number;
+    /** P2P 通道下行速率 B/s（滑动时间窗） */
+    p2pDownloadSpeed: number;
+    /** P2P 上行速率 B/s（滑动时间窗） */
+    uploadSpeed: number;
+}
+/** `p2p:stateChange` 事件负载：开关切换后派发，供宿主同步自定义 UI */
+interface StateChangeDetails {
+    /** 当前 P2P 开关状态 */
+    p2pEnabled: boolean;
+    /** 当前上传开关状态 */
+    uploadEnabled: boolean;
+}
+/** 挂载在 art.plugins.artplayerPluginP2P 上的插件句柄 */
+interface P2PPluginHandle {
+    /** 插件名（ArtPlayer 以此作为挂载键） */
+    name: 'artplayerPluginP2P';
+    /** 当前 P2P 引擎实例（无活跃播放实例时为 undefined） */
+    readonly engine?: HlsJsP2PEngine;
+    /** 当前播放实例（与 art.hls 槽位同步） */
+    readonly hls?: Hls;
+    /** 销毁当前播放实例 */
+    destroy(): void;
+    /** 销毁现有实例后按当前 URL 重建 */
+    reload(): void;
+    /** 获取 P2P 运行时统计快照 */
+    getStats(): P2PStats;
+    /** P2P 运行时开关：经 applyDynamicConfig 无损切换，不销毁实例、不中断播放 */
+    setP2PEnabled(enabled: boolean): void;
+    /** 当前 P2P 是否处于启用状态 */
+    isP2PEnabled(): boolean;
+    /** 上行运行时开关：仅信令广播，完全无缝 */
+    setUploadEnabled(enabled: boolean): void;
+    /** 当前上传是否处于启用状态 */
+    isUploadEnabled(): boolean;
+    /** 运行时动态配置透传（DynamicCoreConfig；swarmId 等静态属性由 p2pml 内建防篡改） */
+    applyDynamicConfig(patch: DynamicCoreConfig): void;
+}
+/** 下载通道类型（别名自 p2p-media-loader 的 DownloadSource，随上游保持同步） */
+type DownloadChannel = DownloadSource;
+/**
+ * 内部使用：解析默认值后的插件选项
+ *
+ * 由入口层从 P2POptions 归一化生成，供引擎与编排层直接消费；
+ * 不对外发布，避免将内部归一化形态固化为公共 API
+ */
+interface ResolvedOptions {
+    /** customType 注册的格式名（已含默认值） */
+    typeName: string;
+    /** fatal 销毁重建的最大次数（已含默认值） */
+    fatalRetryMax: number;
+    /** 初始 P2P 开关（已含默认值） */
+    p2pEnabled: boolean;
+    /** 初始上传开关（已含默认值） */
+    uploadEnabled: boolean;
+    /** UI 总闸（ui !== false） */
+    uiEnabled: boolean;
+    /** 统计展示开关（uiEnabled 且 stats !== false） */
+    statsEnabled: boolean;
+    /** 设置开关组挂载开关（uiEnabled 且对象形式 setting !== false） */
+    settingEnabled: boolean;
+    /** 设置开关组单项显示配置（已含默认值） */
+    settingItems: P2PSettingItemsOptions;
+    /** 原始透传的 core / tracker / hls 配置 */
+    core?: Partial<CoreConfig>;
+    tracker?: P2PTrackerOptions;
+    hls?: Partial<HlsConfig>;
+}
+
+/**
+ * 插件常量定义
+ *
+ * @module constants
+ */
+/** customType 注册的默认格式名 */
+declare const DEFAULT_TYPE = "m3u8";
+/** fatal 错误销毁重建的默认最大次数 */
+declare const DEFAULT_FATAL_RETRY_MAX = 2;
+/**
+ * 统计带宽计算的滑动时间窗长度（毫秒）
+ *
+ * 直播切片通常 2-6s，10 秒窗口可平滑速率抖动
+ */
+declare const BANDWIDTH_WINDOW_MS = 10000;
+/** P2P 面板打开期间的轮询刷新周期（毫秒），与 ArtPlayer 的 INFO_LOOP_TIME 对齐 */
+declare const STATS_POLLING_MS = 1000;
+/**
+ * Core 事件到 ArtPlayer 自定义事件的映射表
+ *
+ * 键集合与 p2p-media-loader 的 CoreEventMap 完全一致，
+ * 通过 satisfies 做编译期穷尽性检查：Core 新增事件或本表遗漏/多余键时
+ * 构建直接失败，保证事件桥不丢失任何事件
+ */
+declare const P2P_EVENT_BRIDGE_MAP: {
+    readonly onStreamAdded: "p2p:streamAdded";
+    readonly onStreamRegistrationError: "p2p:streamRegistrationError";
+    readonly onSegmentLoaded: "p2p:segmentLoaded";
+    readonly onSegmentError: "p2p:segmentError";
+    readonly onSegmentAbort: "p2p:segmentAbort";
+    readonly onSegmentStart: "p2p:segmentStart";
+    readonly onPeerConnect: "p2p:peerConnect";
+    readonly onPeerConnectError: "p2p:peerConnectError";
+    readonly onPeerClose: "p2p:peerClose";
+    readonly onPeerError: "p2p:peerError";
+    readonly onPeerWarning: "p2p:peerWarning";
+    readonly onChunkDownloaded: "p2p:chunkDownloaded";
+    readonly onChunkUploaded: "p2p:chunkUploaded";
+    readonly onTrackerError: "p2p:trackerError";
+    readonly onTrackerWarning: "p2p:trackerWarning";
+};
+
+/**
+ * 插件配置解析与合并逻辑
+ *
+ * 独立于引擎模块的纯函数集合，可在 Node 环境直接测试：
+ * - resolveOptions：归一化插件选项（默认值合并、stats/ui 降级兼容）
+ * - mergeCoreConfig：合并 core 配置与 tracker 快捷配置组
+ * - applyRuntimeToggle：将插件运行时开关状态注入 core 配置
+ *
+ * @module config
+ */
+
+/**
+ * 解析插件选项：填充默认值并归一化 stats / ui 开关
+ *
+ * 仅做归一化，不修改任何透传配置的内容；
+ * core / tracker / hls 原样保留给引擎层合并
+ *
+ * @param options - 用户传入的插件选项
+ * @returns 下游模块可直接消费的解析后选项
+ */
+declare function resolveOptions(options: P2POptions): ResolvedOptions;
+/**
+ * 合并 core 配置与 tracker 快捷配置组
+ *
+ * tracker 组字段与 CoreConfig 同名，浅合并且优先级高于 core；
+ * 两组皆未配置时返回空对象，保持 p2p-media-loader 官方默认行为
+ *
+ * @param options - 含 core / tracker 配置的选项（结构化子集即可）
+ * @returns 传给 HlsJsP2PEngine 的 core 配置
+ */
+declare function mergeCoreConfig(options: Pick<P2POptions, 'core' | 'tracker'>): Partial<CoreConfig>;
+/**
+ * 将插件运行时开关状态注入 core 配置
+ *
+ * isP2PDisabled / isP2PUploadDisabled 由插件开关状态接管
+ * （最高优先级）：保证 fatal 重建、换源、重连后重建的实例
+ * 携带与用户当前选择一致的模式，不因重建而静默丢失开关状态；
+ * 宿主表达初始意图应使用 enabled / uploadEnabled 选项
+ *
+ * @param config - mergeCoreConfig 合并后的 core 配置
+ * @param p2pEnabled - 当前 P2P 开关状态
+ * @param uploadEnabled - 当前上传开关状态
+ * @returns 注入开关状态后的 core 配置
+ */
+declare function applyRuntimeToggle(config: Partial<CoreConfig>, p2pEnabled: boolean, uploadEnabled: boolean): Partial<CoreConfig>;
+
+/**
+ * P2P 统计引擎
+ *
+ * 累加器 + 三个带宽通道（P2P 下行 / HTTP 下行 / 上行）+ 派生指标；
+ * 由事件桥喂点，对外提供快照读取与重置。
+ * 纯逻辑实现：不触碰任何播放器与引擎状态，Node 可直接单测
+ *
+ * @module stats
+ */
+
+/** P2P 统计引擎 */
+declare class P2PStatsEngine {
+    #private;
+    /** 记录一个 peer 连接建立（同时维护峰值） */
+    recordPeerConnect(): void;
+    /** 记录一个 peer 连接断开（计数不小于零） */
+    recordPeerClose(): void;
+    /**
+     * 记录一笔下行字节
+     *
+     * @param bytes - 字节数
+     * @param channel - 下载通道（http / p2p）
+     * @param timestampMs - 样本时间戳；缺省取 performance.now()，测试可注入固定时间
+     */
+    recordDownload(bytes: number, channel: DownloadChannel, timestampMs?: number): void;
+    /**
+     * 记录一笔 P2P 上行字节
+     *
+     * @param bytes - 字节数
+     * @param timestampMs - 样本时间戳；缺省取 performance.now()，测试可注入固定时间
+     */
+    recordUpload(bytes: number, timestampMs?: number): void;
+    /**
+     * 输出当前统计快照（累计量 + 派生指标一次算清）
+     *
+     * 带宽基准时间只取一次、每通道只计算一次，
+     * 保证快照内部指标自洽（downloadSpeed 恒等于两通道之和）
+     *
+     * @param nowMs - 带宽计算基准时间戳；缺省取 performance.now()，测试可注入固定时间
+     */
+    snapshot(nowMs?: number): P2PStats;
+    /**
+     * 清零当前 peer 计数
+     *
+     * 动态关闭 P2P 或销毁播放实例后连接已全部断开（引擎销毁不保证
+     * 逐个发出 onPeerClose），主动清零防止残留计数污染下一次快照；
+     * 峰值与字节累计保留
+     */
+    resetPeers(): void;
+    /** 重置全部计数与样本（换源时调用） */
+    reset(): void;
+}
+
+export { BANDWIDTH_WINDOW_MS as B, DEFAULT_FATAL_RETRY_MAX as D, type P2POptions as P, type ResolvedOptions as R, STATS_POLLING_MS as S, P2PStatsEngine as a, type P2PPluginHandle as b, DEFAULT_TYPE as c, type DownloadChannel as d, type P2PSettingItemsOptions as e, type P2PStats as f, type P2PTrackerOptions as g, type P2PUIOptions as h, P2P_EVENT_BRIDGE_MAP as i, type StateChangeDetails as j, applyRuntimeToggle as k, mergeCoreConfig as m, resolveOptions as r };

package/dist/stats-CFbDXEsi.d.ts

@@ -0,0 +1,294 @@
+import { DownloadSource, CoreConfig, DynamicCoreConfig } from 'p2p-media-loader-core';
+import { HlsJsP2PEngine } from 'p2p-media-loader-hlsjs';
+import Hls, { HlsConfig } from 'hls.js';
+
+/**
+ * 插件公共类型契约
+ *
+ * 本文件是全项目的类型契约源头：下游模块（引擎 / 编排 / UI）
+ * 的签名均以此处定义为准，变更须先同步全部下游再动手
+ *
+ * @module types
+ */
+
+/**
+ * 信令服务器（Tracker）配置组
+ *
+ * 用于将 P2P 信令从公共 tracker 切换到自建 wt-tracker 等私有部署，
+ * 字段名与 p2p-media-loader 的 CoreConfig 完全一致，浅合并进 core
+ */
+interface P2PTrackerOptions {
+    /** WebTorrent tracker 地址列表；不配置时沿用 p2p-media-loader 官方默认公共 tracker */
+    announceTrackers?: string[];
+    /** WebRTC STUN/TURN 配置；自建 ICE 服务时覆盖默认的公共 STUN */
+    rtcConfig?: RTCConfiguration;
+}
+/**
+ * 设置开关组单项显示配置（未指定的项默认显示）
+ */
+interface P2PSettingItemsOptions {
+    /** 是否显示「P2P 加速」开关 */
+    p2pEnabled?: boolean;
+    /** 是否显示「仅上传模式」开关 */
+    uploadOnly?: boolean;
+    /** 是否显示「P2P 统计」开关（stats 关闭时无面板可开，此项不生效） */
+    stats?: boolean;
+}
+interface P2PUIOptions {
+    /**
+     * 设置开关组显示配置：
+     * - true / 省略：三项全显
+     * - false：整组不挂载
+     * - 对象：按项选择性显示
+     */
+    setting?: boolean | P2PSettingItemsOptions;
+}
+/** 插件选项 */
+interface P2POptions {
+    /** customType 注册的格式名，默认 'm3u8' */
+    type?: string;
+    /** 信令服务器配置组，与 core 配置浅合并（本组优先） */
+    tracker?: P2PTrackerOptions;
+    /** 完整 core 配置透传（Partial<CoreConfig>）；其中 isP2PDisabled / isP2PUploadDisabled 由插件开关状态接管 */
+    core?: Partial<CoreConfig>;
+    /** 透传给 hls.js 的配置 */
+    hls?: Partial<HlsConfig>;
+    /** fatal 错误销毁重建的最大次数，默认 2 */
+    fatalRetryMax?: number;
+    /** 初始 P2P 开关，默认 true；运行时可经句柄 setP2PEnabled 无损切换 */
+    enabled?: boolean;
+    /** 初始上传开关，默认 true；运行时可经句柄 setUploadEnabled 无缝切换 */
+    uploadEnabled?: boolean;
+    /** 统计展示总开关，默认 true；false 时不挂「P2P 统计」菜单项与面板，宿主仅能经 getStats() 编程读取 */
+    stats?: boolean;
+    /** UI 总闸：false 时完全无 UI（不挂菜单项 / 面板 / 设置开关组）；对象形式可单独控制设置开关组 */
+    ui?: boolean | P2PUIOptions;
+}
+/** P2P 运行时统计快照（一次性读取全部累计量与派生指标） */
+interface P2PStats {
+    /** 当前已连接的 peer 数量 */
+    peers: number;
+    /** 会话内出现过的峰值 peer 数量 */
+    peakPeers: number;
+    /** 累计 P2P 通道下行字节数 */
+    p2pDownloadedBytes: number;
+    /** 累计 HTTP 通道下行字节数 */
+    httpDownloadedBytes: number;
+    /** 累计 P2P 上行字节数 */
+    uploadedBytes: number;
+    /** 累计总下行字节数（P2P + HTTP） */
+    totalDownloadedBytes: number;
+    /** P2P 下行占总下行比例 0..1（总下行为 0 时为 0） */
+    p2pDownloadRatio: number;
+    /** 总下行速率 B/s（滑动时间窗） */
+    downloadSpeed: number;
+    /** P2P 通道下行速率 B/s（滑动时间窗） */
+    p2pDownloadSpeed: number;
+    /** P2P 上行速率 B/s（滑动时间窗） */
+    uploadSpeed: number;
+}
+/** `p2p:stateChange` 事件负载：开关切换后派发，供宿主同步自定义 UI */
+interface StateChangeDetails {
+    /** 当前 P2P 开关状态 */
+    p2pEnabled: boolean;
+    /** 当前上传开关状态 */
+    uploadEnabled: boolean;
+}
+/** 挂载在 art.plugins.artplayerPluginP2P 上的插件句柄 */
+interface P2PPluginHandle {
+    /** 插件名（ArtPlayer 以此作为挂载键） */
+    name: 'artplayerPluginP2P';
+    /** 当前 P2P 引擎实例（无活跃播放实例时为 undefined） */
+    readonly engine?: HlsJsP2PEngine;
+    /** 当前播放实例（与 art.hls 槽位同步） */
+    readonly hls?: Hls;
+    /** 销毁当前播放实例 */
+    destroy(): void;
+    /** 销毁现有实例后按当前 URL 重建 */
+    reload(): void;
+    /** 获取 P2P 运行时统计快照 */
+    getStats(): P2PStats;
+    /** P2P 运行时开关：经 applyDynamicConfig 无损切换，不销毁实例、不中断播放 */
+    setP2PEnabled(enabled: boolean): void;
+    /** 当前 P2P 是否处于启用状态 */
+    isP2PEnabled(): boolean;
+    /** 上行运行时开关：仅信令广播，完全无缝 */
+    setUploadEnabled(enabled: boolean): void;
+    /** 当前上传是否处于启用状态 */
+    isUploadEnabled(): boolean;
+    /** 运行时动态配置透传（DynamicCoreConfig；swarmId 等静态属性由 p2pml 内建防篡改） */
+    applyDynamicConfig(patch: DynamicCoreConfig): void;
+}
+/** 下载通道类型（别名自 p2p-media-loader 的 DownloadSource，随上游保持同步） */
+type DownloadChannel = DownloadSource;
+/**
+ * 内部使用：解析默认值后的插件选项
+ *
+ * 由入口层从 P2POptions 归一化生成，供引擎与编排层直接消费；
+ * 不对外发布，避免将内部归一化形态固化为公共 API
+ */
+interface ResolvedOptions {
+    /** customType 注册的格式名（已含默认值） */
+    typeName: string;
+    /** fatal 销毁重建的最大次数（已含默认值） */
+    fatalRetryMax: number;
+    /** 初始 P2P 开关（已含默认值） */
+    p2pEnabled: boolean;
+    /** 初始上传开关（已含默认值） */
+    uploadEnabled: boolean;
+    /** UI 总闸（ui !== false） */
+    uiEnabled: boolean;
+    /** 统计展示开关（uiEnabled 且 stats !== false） */
+    statsEnabled: boolean;
+    /** 设置开关组挂载开关（uiEnabled 且对象形式 setting !== false） */
+    settingEnabled: boolean;
+    /** 设置开关组单项显示配置（已含默认值） */
+    settingItems: P2PSettingItemsOptions;
+    /** 原始透传的 core / tracker / hls 配置 */
+    core?: Partial<CoreConfig>;
+    tracker?: P2PTrackerOptions;
+    hls?: Partial<HlsConfig>;
+}
+
+/**
+ * 插件常量定义
+ *
+ * @module constants
+ */
+/** customType 注册的默认格式名 */
+declare const DEFAULT_TYPE = "m3u8";
+/** fatal 错误销毁重建的默认最大次数 */
+declare const DEFAULT_FATAL_RETRY_MAX = 2;
+/**
+ * 统计带宽计算的滑动时间窗长度（毫秒）
+ *
+ * 直播切片通常 2-6s，10 秒窗口可平滑速率抖动
+ */
+declare const BANDWIDTH_WINDOW_MS = 10000;
+/** P2P 面板打开期间的轮询刷新周期（毫秒），与 ArtPlayer 的 INFO_LOOP_TIME 对齐 */
+declare const STATS_POLLING_MS = 1000;
+/**
+ * Core 事件到 ArtPlayer 自定义事件的映射表
+ *
+ * 键集合与 p2p-media-loader 的 CoreEventMap 完全一致，
+ * 通过 satisfies 做编译期穷尽性检查：Core 新增事件或本表遗漏/多余键时
+ * 构建直接失败，保证事件桥不丢失任何事件
+ */
+declare const P2P_EVENT_BRIDGE_MAP: {
+    readonly onStreamAdded: "p2p:streamAdded";
+    readonly onStreamRegistrationError: "p2p:streamRegistrationError";
+    readonly onSegmentLoaded: "p2p:segmentLoaded";
+    readonly onSegmentError: "p2p:segmentError";
+    readonly onSegmentAbort: "p2p:segmentAbort";
+    readonly onSegmentStart: "p2p:segmentStart";
+    readonly onPeerConnect: "p2p:peerConnect";
+    readonly onPeerConnectError: "p2p:peerConnectError";
+    readonly onPeerClose: "p2p:peerClose";
+    readonly onPeerError: "p2p:peerError";
+    readonly onPeerWarning: "p2p:peerWarning";
+    readonly onChunkDownloaded: "p2p:chunkDownloaded";
+    readonly onChunkUploaded: "p2p:chunkUploaded";
+    readonly onTrackerError: "p2p:trackerError";
+    readonly onTrackerWarning: "p2p:trackerWarning";
+};
+
+/**
+ * 插件配置解析与合并逻辑
+ *
+ * 独立于引擎模块的纯函数集合，可在 Node 环境直接测试：
+ * - resolveOptions：归一化插件选项（默认值合并、stats/ui 降级兼容）
+ * - mergeCoreConfig：合并 core 配置与 tracker 快捷配置组
+ * - applyRuntimeToggle：将插件运行时开关状态注入 core 配置
+ *
+ * @module config
+ */
+
+/**
+ * 解析插件选项：填充默认值并归一化 stats / ui 开关
+ *
+ * 仅做归一化，不修改任何透传配置的内容；
+ * core / tracker / hls 原样保留给引擎层合并
+ *
+ * @param options - 用户传入的插件选项
+ * @returns 下游模块可直接消费的解析后选项
+ */
+declare function resolveOptions(options: P2POptions): ResolvedOptions;
+/**
+ * 合并 core 配置与 tracker 快捷配置组
+ *
+ * tracker 组字段与 CoreConfig 同名，浅合并且优先级高于 core；
+ * 两组皆未配置时返回空对象，保持 p2p-media-loader 官方默认行为
+ *
+ * @param options - 含 core / tracker 配置的选项（结构化子集即可）
+ * @returns 传给 HlsJsP2PEngine 的 core 配置
+ */
+declare function mergeCoreConfig(options: Pick<P2POptions, 'core' | 'tracker'>): Partial<CoreConfig>;
+/**
+ * 将插件运行时开关状态注入 core 配置
+ *
+ * isP2PDisabled / isP2PUploadDisabled 由插件开关状态接管
+ * （最高优先级）：保证 fatal 重建、换源、重连后重建的实例
+ * 携带与用户当前选择一致的模式，不因重建而静默丢失开关状态；
+ * 宿主表达初始意图应使用 enabled / uploadEnabled 选项
+ *
+ * @param config - mergeCoreConfig 合并后的 core 配置
+ * @param p2pEnabled - 当前 P2P 开关状态
+ * @param uploadEnabled - 当前上传开关状态
+ * @returns 注入开关状态后的 core 配置
+ */
+declare function applyRuntimeToggle(config: Partial<CoreConfig>, p2pEnabled: boolean, uploadEnabled: boolean): Partial<CoreConfig>;
+
+/**
+ * P2P 统计引擎
+ *
+ * 累加器 + 三个带宽通道（P2P 下行 / HTTP 下行 / 上行）+ 派生指标；
+ * 由事件桥喂点，对外提供快照读取与重置。
+ * 纯逻辑实现：不触碰任何播放器与引擎状态，Node 可直接单测
+ *
+ * @module stats
+ */
+
+/** P2P 统计引擎 */
+declare class P2PStatsEngine {
+    #private;
+    /** 记录一个 peer 连接建立（同时维护峰值） */
+    recordPeerConnect(): void;
+    /** 记录一个 peer 连接断开（计数不小于零） */
+    recordPeerClose(): void;
+    /**
+     * 记录一笔下行字节
+     *
+     * @param bytes - 字节数
+     * @param channel - 下载通道（http / p2p）
+     * @param timestampMs - 样本时间戳；缺省取 performance.now()，测试可注入固定时间
+     */
+    recordDownload(bytes: number, channel: DownloadChannel, timestampMs?: number): void;
+    /**
+     * 记录一笔 P2P 上行字节
+     *
+     * @param bytes - 字节数
+     * @param timestampMs - 样本时间戳；缺省取 performance.now()，测试可注入固定时间
+     */
+    recordUpload(bytes: number, timestampMs?: number): void;
+    /**
+     * 输出当前统计快照（累计量 + 派生指标一次算清）
+     *
+     * 带宽基准时间只取一次、每通道只计算一次，
+     * 保证快照内部指标自洽（downloadSpeed 恒等于两通道之和）
+     *
+     * @param nowMs - 带宽计算基准时间戳；缺省取 performance.now()，测试可注入固定时间
+     */
+    snapshot(nowMs?: number): P2PStats;
+    /**
+     * 清零当前 peer 计数
+     *
+     * 动态关闭 P2P 或销毁播放实例后连接已全部断开（引擎销毁不保证
+     * 逐个发出 onPeerClose），主动清零防止残留计数污染下一次快照；
+     * 峰值与字节累计保留
+     */
+    resetPeers(): void;
+    /** 重置全部计数与样本（换源时调用） */
+    reset(): void;
+}
+
+export { BANDWIDTH_WINDOW_MS as B, DEFAULT_FATAL_RETRY_MAX as D, type P2POptions as P, type ResolvedOptions as R, STATS_POLLING_MS as S, P2PStatsEngine as a, type P2PPluginHandle as b, DEFAULT_TYPE as c, type DownloadChannel as d, type P2PSettingItemsOptions as e, type P2PStats as f, type P2PTrackerOptions as g, type P2PUIOptions as h, P2P_EVENT_BRIDGE_MAP as i, type StateChangeDetails as j, applyRuntimeToggle as k, mergeCoreConfig as m, resolveOptions as r };

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "artplayer-plugin-p2p",
+  "version": "1.0.0",
+  "description": "P2P media streaming plugin for ArtPlayer, powered by p2p-media-loader (hls.js engine)",
+  "license": "MIT",
+  "author": {
+    "name": "iuk-ink"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iuk-ink/artplayer-plugin-p2p.git"
+  },
+  "homepage": "https://github.com/iuk-ink/artplayer-plugin-p2p#readme",
+  "bugs": {
+    "url": "https://github.com/iuk-ink/artplayer-plugin-p2p/issues"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/index.d.mts",
+        "require": "./dist/index.d.ts"
+      },
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./pure": {
+      "types": {
+        "import": "./dist/pure.d.mts",
+        "require": "./dist/pure.d.ts"
+      },
+      "import": "./dist/pure.mjs",
+      "require": "./dist/pure.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "unpkg": "./dist/artplayer-plugin-p2p.iife.js",
+  "jsdelivr": "./dist/artplayer-plugin-p2p.iife.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "node scripts/test-plugin.mjs",
+    "test:pure": "node scripts/test-pure.mjs",
+    "smoke:dist": "node --conditions=p2pml:core-as-bundle scripts/smoke-dist.mjs",
+    "prepublishOnly": "npm run typecheck && npm run build && npm test"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "p2p-media-loader-core": "^4.0.0",
+    "p2p-media-loader-hlsjs": "^4.0.0"
+  },
+  "peerDependencies": {
+    "artplayer": ">=5.0.0",
+    "hls.js": "^1.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.4.1",
+    "artplayer": "^5.4.0",
+    "hls.js": "^1.7.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "keywords": [
+    "artplayer",
+    "p2p",
+    "p2p-media-loader",
+    "hls",
+    "hls.js",
+    "webrtc",
+    "video",
+    "player",
+    "plugin"
+  ]
+}