artplayer-plugin-p2p 1.0.0

package/dist/chunk-IX2RPNML.mjs

@@ -0,0 +1,279 @@
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
+var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot " + msg);
+var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read from private field"), getter ? getter.call(obj) : member.get(obj));
+var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
+var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), setter ? setter.call(obj, value) : member.set(obj, value), value);
+var __privateMethod = (obj, member, method) => (__accessCheck(obj, member, "access private method"), method);
+
+// src/bandwidth.ts
+var _windowMs, _samples, _BandwidthCalculator_instances, removeExpired_fn;
+var BandwidthCalculator = class {
+  /**
+   * @param windowMs - 滑动时间窗长度（毫秒），窗口越长速率越平滑
+   */
+  constructor(windowMs) {
+    __privateAdd(this, _BandwidthCalculator_instances);
+    __privateAdd(this, _windowMs);
+    __privateAdd(this, _samples, []);
+    __privateSet(this, _windowMs, windowMs);
+  }
+  /**
+   * 记录一笔字节
+   *
+   * @param bytes - 字节数（非正值直接忽略，防御脏数据）
+   * @param timestampMs - 样本时间戳；缺省取 performance.now()，测试可注入固定时间
+   */
+  record(bytes, timestampMs = performance.now()) {
+    if (bytes <= 0) return;
+    __privateGet(this, _samples).push({ timestampMs, bytes });
+  }
+  /**
+   * 计算窗口内平均速率
+   *
+   * 读取时惰性清理过期样本；速率按整个窗口长度折算而非
+   * 首尾样本间隔，保证窗口未填满时（刚启动）读数平滑趋近真实值
+   *
+   * @param nowMs - 当前时间戳；缺省取 performance.now()，测试可注入固定时间
+   * @returns 速率 B/s
+   */
+  getSpeed(nowMs = performance.now()) {
+    __privateMethod(this, _BandwidthCalculator_instances, removeExpired_fn).call(this, nowMs);
+    let totalBytes = 0;
+    for (const sample of __privateGet(this, _samples)) {
+      totalBytes += sample.bytes;
+    }
+    return totalBytes / (__privateGet(this, _windowMs) / 1e3);
+  }
+  /** 清空全部样本 */
+  reset() {
+    __privateGet(this, _samples).length = 0;
+  }
+};
+_windowMs = new WeakMap();
+_samples = new WeakMap();
+_BandwidthCalculator_instances = new WeakSet();
+/**
+ * 移除窗口外的过期样本
+ *
+ * 样本时间戳单调递增（缺省时间源 performance.now 单调；
+ * 注入时间戳同样须单调），从头扫描至首个窗口内样本即可。
+ * 边界样本（age 恰等于窗口长）保留在窗口内，与 p2pml
+ * 官方带宽计算的过期判定语义保持一致
+ */
+removeExpired_fn = function(nowMs) {
+  const cutoff = nowMs - __privateGet(this, _windowMs);
+  let firstValid = __privateGet(this, _samples).length;
+  for (let i = 0; i < __privateGet(this, _samples).length; i++) {
+    if (__privateGet(this, _samples)[i].timestampMs >= cutoff) {
+      firstValid = i;
+      break;
+    }
+  }
+  __privateGet(this, _samples).splice(0, firstValid);
+};
+
+// src/constants.ts
+var DEFAULT_TYPE = "m3u8";
+var DEFAULT_FATAL_RETRY_MAX = 2;
+var BANDWIDTH_WINDOW_MS = 1e4;
+var STATS_POLLING_MS = 1e3;
+var P2P_EVENT_BRIDGE_MAP = {
+  onStreamAdded: "p2p:streamAdded",
+  onStreamRegistrationError: "p2p:streamRegistrationError",
+  onSegmentLoaded: "p2p:segmentLoaded",
+  onSegmentError: "p2p:segmentError",
+  onSegmentAbort: "p2p:segmentAbort",
+  onSegmentStart: "p2p:segmentStart",
+  onPeerConnect: "p2p:peerConnect",
+  onPeerConnectError: "p2p:peerConnectError",
+  onPeerClose: "p2p:peerClose",
+  onPeerError: "p2p:peerError",
+  onPeerWarning: "p2p:peerWarning",
+  onChunkDownloaded: "p2p:chunkDownloaded",
+  onChunkUploaded: "p2p:chunkUploaded",
+  onTrackerError: "p2p:trackerError",
+  onTrackerWarning: "p2p:trackerWarning"
+};
+
+// src/stats.ts
+var _peers, _peakPeers, _p2pDownloadedBytes, _httpDownloadedBytes, _uploadedBytes, _downloadBandwidths, _uploadBandwidth;
+var P2PStatsEngine = class {
+  constructor() {
+    __privateAdd(this, _peers, 0);
+    __privateAdd(this, _peakPeers, 0);
+    __privateAdd(this, _p2pDownloadedBytes, 0);
+    __privateAdd(this, _httpDownloadedBytes, 0);
+    __privateAdd(this, _uploadedBytes, 0);
+    __privateAdd(this, _downloadBandwidths, {
+      p2p: new BandwidthCalculator(BANDWIDTH_WINDOW_MS),
+      http: new BandwidthCalculator(BANDWIDTH_WINDOW_MS)
+    });
+    __privateAdd(this, _uploadBandwidth, new BandwidthCalculator(BANDWIDTH_WINDOW_MS));
+  }
+  /** 记录一个 peer 连接建立（同时维护峰值） */
+  recordPeerConnect() {
+    __privateSet(this, _peers, __privateGet(this, _peers) + 1);
+    if (__privateGet(this, _peers) > __privateGet(this, _peakPeers)) {
+      __privateSet(this, _peakPeers, __privateGet(this, _peers));
+    }
+  }
+  /** 记录一个 peer 连接断开（计数不小于零） */
+  recordPeerClose() {
+    if (__privateGet(this, _peers) > 0) {
+      __privateSet(this, _peers, __privateGet(this, _peers) - 1);
+    }
+  }
+  /**
+   * 记录一笔下行字节
+   *
+   * @param bytes - 字节数
+   * @param channel - 下载通道（http / p2p）
+   * @param timestampMs - 样本时间戳；缺省取 performance.now()，测试可注入固定时间
+   */
+  recordDownload(bytes, channel, timestampMs) {
+    if (bytes <= 0) return;
+    if (channel === "p2p") {
+      __privateSet(this, _p2pDownloadedBytes, __privateGet(this, _p2pDownloadedBytes) + bytes);
+    } else {
+      __privateSet(this, _httpDownloadedBytes, __privateGet(this, _httpDownloadedBytes) + bytes);
+    }
+    __privateGet(this, _downloadBandwidths)[channel].record(bytes, timestampMs);
+  }
+  /**
+   * 记录一笔 P2P 上行字节
+   *
+   * @param bytes - 字节数
+   * @param timestampMs - 样本时间戳；缺省取 performance.now()，测试可注入固定时间
+   */
+  recordUpload(bytes, timestampMs) {
+    if (bytes <= 0) return;
+    __privateSet(this, _uploadedBytes, __privateGet(this, _uploadedBytes) + bytes);
+    __privateGet(this, _uploadBandwidth).record(bytes, timestampMs);
+  }
+  /**
+   * 输出当前统计快照（累计量 + 派生指标一次算清）
+   *
+   * 带宽基准时间只取一次、每通道只计算一次，
+   * 保证快照内部指标自洽（downloadSpeed 恒等于两通道之和）
+   *
+   * @param nowMs - 带宽计算基准时间戳；缺省取 performance.now()，测试可注入固定时间
+   */
+  snapshot(nowMs) {
+    const totalDownloadedBytes = __privateGet(this, _p2pDownloadedBytes) + __privateGet(this, _httpDownloadedBytes);
+    const now = nowMs ?? performance.now();
+    const p2pDownloadSpeed = __privateGet(this, _downloadBandwidths).p2p.getSpeed(now);
+    const httpDownloadSpeed = __privateGet(this, _downloadBandwidths).http.getSpeed(now);
+    return {
+      peers: __privateGet(this, _peers),
+      peakPeers: __privateGet(this, _peakPeers),
+      p2pDownloadedBytes: __privateGet(this, _p2pDownloadedBytes),
+      httpDownloadedBytes: __privateGet(this, _httpDownloadedBytes),
+      uploadedBytes: __privateGet(this, _uploadedBytes),
+      totalDownloadedBytes,
+      p2pDownloadRatio: totalDownloadedBytes > 0 ? __privateGet(this, _p2pDownloadedBytes) / totalDownloadedBytes : 0,
+      downloadSpeed: p2pDownloadSpeed + httpDownloadSpeed,
+      p2pDownloadSpeed,
+      uploadSpeed: __privateGet(this, _uploadBandwidth).getSpeed(now)
+    };
+  }
+  /**
+   * 清零当前 peer 计数
+   *
+   * 动态关闭 P2P 或销毁播放实例后连接已全部断开（引擎销毁不保证
+   * 逐个发出 onPeerClose），主动清零防止残留计数污染下一次快照；
+   * 峰值与字节累计保留
+   */
+  resetPeers() {
+    __privateSet(this, _peers, 0);
+  }
+  /** 重置全部计数与样本（换源时调用） */
+  reset() {
+    __privateSet(this, _peers, 0);
+    __privateSet(this, _peakPeers, 0);
+    __privateSet(this, _p2pDownloadedBytes, 0);
+    __privateSet(this, _httpDownloadedBytes, 0);
+    __privateSet(this, _uploadedBytes, 0);
+    __privateGet(this, _downloadBandwidths).p2p.reset();
+    __privateGet(this, _downloadBandwidths).http.reset();
+    __privateGet(this, _uploadBandwidth).reset();
+  }
+};
+_peers = new WeakMap();
+_peakPeers = new WeakMap();
+_p2pDownloadedBytes = new WeakMap();
+_httpDownloadedBytes = new WeakMap();
+_uploadedBytes = new WeakMap();
+_downloadBandwidths = new WeakMap();
+_uploadBandwidth = new WeakMap();
+
+// src/config.ts
+function resolveUIOptions(ui) {
+  return ui.setting !== false;
+}
+function resolveSettingItems(setting) {
+  if (setting === void 0 || setting === true) {
+    return { p2pEnabled: true, uploadOnly: true, stats: true };
+  }
+  if (setting === false) {
+    return { p2pEnabled: false, uploadOnly: false, stats: false };
+  }
+  return {
+    p2pEnabled: setting.p2pEnabled ?? true,
+    uploadOnly: setting.uploadOnly ?? true,
+    stats: setting.stats ?? true
+  };
+}
+function resolveOptions(options) {
+  const uiEnabled = options.ui !== false;
+  let settingEnabled;
+  let settingItems;
+  if (typeof options.ui === "object" && options.ui !== null) {
+    settingEnabled = resolveUIOptions(options.ui);
+    settingItems = resolveSettingItems(options.ui.setting);
+  } else {
+    settingEnabled = uiEnabled;
+    settingItems = resolveSettingItems(uiEnabled ? void 0 : false);
+  }
+  return {
+    typeName: options.type ?? DEFAULT_TYPE,
+    fatalRetryMax: options.fatalRetryMax ?? DEFAULT_FATAL_RETRY_MAX,
+    p2pEnabled: options.enabled ?? true,
+    uploadEnabled: options.uploadEnabled ?? true,
+    uiEnabled,
+    statsEnabled: uiEnabled && options.stats !== false,
+    settingEnabled,
+    settingItems,
+    core: options.core,
+    tracker: options.tracker,
+    hls: options.hls
+  };
+}
+function mergeCoreConfig(options) {
+  return { ...options.core, ...options.tracker };
+}
+function applyRuntimeToggle(config, p2pEnabled, uploadEnabled) {
+  return {
+    ...config,
+    isP2PDisabled: !p2pEnabled,
+    isP2PUploadDisabled: !uploadEnabled
+  };
+}
+
+export {
+  __privateGet,
+  __privateAdd,
+  __privateSet,
+  __privateMethod,
+  BandwidthCalculator,
+  DEFAULT_TYPE,
+  DEFAULT_FATAL_RETRY_MAX,
+  BANDWIDTH_WINDOW_MS,
+  STATS_POLLING_MS,
+  P2P_EVENT_BRIDGE_MAP,
+  P2PStatsEngine,
+  resolveOptions,
+  mergeCoreConfig,
+  applyRuntimeToggle
+};

package/dist/index.d.mts

@@ -0,0 +1,202 @@
+import Artplayer from 'artplayer';
+import { P as P2POptions, R as ResolvedOptions, a as P2PStatsEngine, b as P2PPluginHandle } from './stats-CFbDXEsi.mjs';
+export { B as BANDWIDTH_WINDOW_MS, D as DEFAULT_FATAL_RETRY_MAX, c as DEFAULT_TYPE, d as DownloadChannel, e as P2PSettingItemsOptions, f as P2PStats, g as P2PTrackerOptions, h as P2PUIOptions, i as P2P_EVENT_BRIDGE_MAP, S as STATS_POLLING_MS, j as StateChangeDetails, k as applyRuntimeToggle, m as mergeCoreConfig, r as resolveOptions } from './stats-CFbDXEsi.mjs';
+import Hls, { ErrorData } from 'hls.js';
+import { HlsJsP2PEngine, HlsWithP2PInstance } from 'p2p-media-loader-hlsjs';
+export { CoreConfig, DynamicCoreConfig } from 'p2p-media-loader-core';
+
+/**
+ * hls.js fatal 错误分级恢复策略
+ *
+ * 按 hls.js 官方最佳实践实施三级自愈：
+ * 网络级 startLoad() → 媒体级 recoverMediaError()（二次失败自动
+ * swapAudioCodec）→ 其他/超限交由上层销毁重建；全部动作有界。
+ * 通过回调注入通知上层（不依赖 ArtPlayer），保持模块可移植性
+ *
+ * @module recovery
+ */
+
+/** 恢复策略回调集合（由编排层注入并绑定到具体通知渠道） */
+interface FatalRecoveryOptions {
+    /** 单实例内软恢复的最大次数上限 */
+    retryMax: number;
+    /** 每次 fatal 发生时通知（含软恢复与放弃两种情形，附当前重试序号） */
+    onFatalError: (data: ErrorData, retryCount: number) => void;
+    /** 遇到不可软恢复的 fatal（其他类型错误），交由上层销毁重建 */
+    onUnrecoverable: (data: ErrorData, retryCount: number) => void;
+}
+/**
+ * fatal 分级恢复策略
+ *
+ * 挂载在单个 hls.js 实例的 ERROR 事件上，随实例销毁而失效；
+ * 软恢复计数为实例级（重建后的新实例从零计数）
+ */
+declare class FatalRecoveryPolicy {
+    #private;
+    /**
+     * @param hls - 目标 hls.js 实例
+     * @param hlsConstructor - hls.js 构造器（Events/ErrorTypes 枚举来源，
+     *   避免本模块引入 hls.js 运行时值以保持可移植性）
+     * @param options - 回调集合
+     */
+    constructor(hls: Hls, hlsConstructor: typeof Hls, options: FatalRecoveryOptions);
+}
+
+/**
+ * P2P 播放引擎工厂
+ *
+ * 职责：
+ * - 合并 tracker 快捷配置与 core 全量配置，并注入插件运行时开关状态
+ * - 缓存 injectMixin 生成的 HlsWithP2P 构造器（每个 hls.js 构造器仅生成一次）
+ * - 创建携带 P2P 能力的 hls.js 实例，并挂载 fatal 分级恢复策略
+ *
+ * P2P / 上传开关统一经运行时动态配置实现（见 controller），
+ * 实例创建时的初始注入保证重建后模式不丢失，
+ * 因此本模块不再提供"裸 hls.js 实例"工厂
+ *
+ * @module engine
+ */
+
+/** 引擎消费的选项结构化子集（ResolvedOptions 结构化兼容） */
+interface EngineOptions extends Pick<P2POptions, 'core' | 'tracker' | 'hls' | 'fatalRetryMax'> {
+    /** 当前 P2P 开关状态（注入 isP2PDisabled） */
+    p2pEnabled: boolean;
+    /** 当前上传开关状态（注入 isP2PUploadDisabled） */
+    uploadEnabled: boolean;
+}
+/** hls.js 构造器类型 */
+type HlsConstructor = typeof Hls;
+/**
+ * 引擎工厂钩子集合（由编排层注入）
+ *
+ * onEngineCreated 在引擎就绪时触发，供事件桥挂载；
+ * 其余两个钩子用于 fatal 通知与不可恢复错误上报
+ */
+interface EngineHooks {
+    /** P2P 引擎就绪（onHlsJsCreated 时机），供事件桥挂载 */
+    onEngineCreated: (engine: HlsJsP2PEngine) => void;
+    /** fatal 发生通知（含软恢复与放弃两种情形） */
+    onFatalError: (data: ErrorData, retryCount: number) => void;
+    /** 遇到不可软恢复的 fatal，由编排层决定销毁重建 */
+    onUnrecoverable: (data: ErrorData, retryCount: number) => void;
+}
+/**
+ * 创建携带 P2P 能力的 hls.js 播放实例
+ *
+ * core 配置经 applyRuntimeToggle 注入当前开关状态；
+ * 仅完成实例构造与 fatal 恢复挂载，loadSource / attachMedia
+ * 的调用时机由调用方决定
+ *
+ * @param options - 引擎选项（含透传配置与运行时开关状态）
+ * @param hlsConstructor - 宿主提供的 hls.js 构造器（peerDependency 实例）
+ * @param hooks - 引擎钩子集合
+ * @returns HlsWithP2P 播放实例
+ */
+declare function createHlsWithP2P(options: EngineOptions, hlsConstructor: HlsConstructor, hooks: EngineHooks): HlsWithP2PInstance<Hls>;
+
+/**
+ * P2P 实例生命周期控制器
+ *
+ * 唯一持有播放实例与跨实例状态（最近 URL / 视频 / 重建计数 /
+ * P2P 与上传开关）的状态机；换源、fatal 重建、开关切换、销毁
+ * 全部收敛为显式方法。art.hls 槽位的写入与清空只发生在本模块内
+ *
+ * 开关语义：
+ * - P2P / 上传开关经 engine.applyDynamicConfig 无损切换，
+ *   不销毁实例、不中断播放
+ * - 实例创建（首装 / fatal 重建 / 换源 / 重连）时按当前开关状态
+ *   注入初始配置，保证重建后模式不丢失
+ * - activate 不接受模式参数：模式一律取控制器运行时状态，
+ *   避免 customType 重入路径（video:error 重连）重置用户的开关选择
+ *
+ * @module controller
+ */
+
+/** 控制器状态：idle 未创建 / active 播放中 / destroyed 播放器已销毁 */
+type ControllerState = 'idle' | 'active' | 'destroyed';
+/** P2P 实例生命周期控制器 */
+declare class P2PController {
+    #private;
+    /**
+     * @param art - ArtPlayer 实例
+     * @param options - 解析后的插件选项（p2pEnabled / uploadEnabled 为初始开关状态）
+     * @param stats - 统计引擎实例（由入口层创建并共享给句柄）
+     */
+    constructor(art: Artplayer, options: ResolvedOptions, stats: P2PStatsEngine);
+    /** 当前控制器状态 */
+    get state(): ControllerState;
+    /** 当前 P2P 开关状态 */
+    get p2pEnabled(): boolean;
+    /** 当前上传开关状态 */
+    get uploadEnabled(): boolean;
+    /** 当前播放实例（与 art.hls 槽位同步） */
+    get hls(): HlsWithP2PInstance<Hls> | undefined;
+    /**
+     * 外部显式激活（customType 回调：首次加载 / 换源 / 重连共用）
+     *
+     * 视为新的播放意图：统计与重建计数全部归零，
+     * 以控制器当前开关状态创建实例（不接受模式参数）
+     *
+     * @param url - 播放地址
+     * @param video - 视频元素
+     */
+    activate(url: string, video: HTMLVideoElement): void;
+    /** 销毁当前播放实例（注销监听、清空 art.hls 槽位） */
+    deactivate(): void;
+    /** 销毁现有实例后按最近地址与当前开关模式重建 */
+    reload(): void;
+    /**
+     * P2P 运行时开关：经 applyDynamicConfig 无损切换
+     *
+     * 不销毁实例、不中断播放；关闭时 HybridLoader 被引擎销毁、
+     * peer 连接全断，主动清零 peer 计数防止残留（迟到关闭事件
+     * 由统计引擎的非负保护兜底）；字节统计冻结保留供模式对照
+     *
+     * @param enabled - 目标 P2P 状态
+     */
+    setP2PEnabled(enabled: boolean): void;
+    /**
+     * 上行运行时开关：仅信令广播（引擎内部处理），完全无缝
+     *
+     * @param enabled - 目标上传状态
+     */
+    setUploadEnabled(enabled: boolean): void;
+    /** 播放器销毁：终止一切并进入 destroyed（幂等） */
+    destroy(): void;
+}
+
+/**
+ * ArtPlayer P2P 插件入口
+ *
+ * 将 p2p-media-loader（hls.js 引擎）封装为 ArtPlayer 插件：
+ * 通过 option.plugins 注入即可为 m3u8 播放启用 P2P 分发，
+ * 支持自建 tracker 信令服务器配置、运行时开关与统计
+ *
+ * 组装流程依赖 ArtPlayer 的两个时序事实：
+ * 1. 插件工厂在 Player.optionInit 之后执行，首次 URL 加载已经发生，
+ *    因此 customType 注册完成后需要对匹配类型的源做二次赋值补救
+ * 2. video:error 重连经 art.url 重赋值会重新进入 customType 回调，
+ *    回调内控制器的 activate 幂等（先销毁再重建），重入安全
+ *
+ * 用法：
+ *   new Artplayer({
+ *     url: 'https://example.com/stream.m3u8',
+ *     type: 'm3u8',
+ *     plugins: [artplayerPluginP2P({ tracker: { announceTrackers: ['wss://tracker.example.com'] } })],
+ *   })
+ *
+ * @module index
+ */
+
+/**
+ * ArtPlayer P2P 插件工厂
+ *
+ * 自动注册 customType 并对首次加载做时序接管（用户零感知）；
+ * 返回的句柄挂载在 art.plugins.artplayerPluginP2P
+ *
+ * @param options - 插件选项
+ * @returns ArtPlayer 插件函数
+ */
+declare function artplayerPluginP2P(options?: P2POptions): (art: Artplayer) => P2PPluginHandle;
+
+export { type ControllerState, type EngineHooks, type EngineOptions, FatalRecoveryPolicy, P2PController, P2POptions, P2PPluginHandle, P2PStatsEngine, createHlsWithP2P, artplayerPluginP2P as default };

package/dist/index.d.ts

@@ -0,0 +1,202 @@
+import Artplayer from 'artplayer';
+import { P as P2POptions, R as ResolvedOptions, a as P2PStatsEngine, b as P2PPluginHandle } from './stats-CFbDXEsi.js';
+export { B as BANDWIDTH_WINDOW_MS, D as DEFAULT_FATAL_RETRY_MAX, c as DEFAULT_TYPE, d as DownloadChannel, e as P2PSettingItemsOptions, f as P2PStats, g as P2PTrackerOptions, h as P2PUIOptions, i as P2P_EVENT_BRIDGE_MAP, S as STATS_POLLING_MS, j as StateChangeDetails, k as applyRuntimeToggle, m as mergeCoreConfig, r as resolveOptions } from './stats-CFbDXEsi.js';
+import Hls, { ErrorData } from 'hls.js';
+import { HlsJsP2PEngine, HlsWithP2PInstance } from 'p2p-media-loader-hlsjs';
+export { CoreConfig, DynamicCoreConfig } from 'p2p-media-loader-core';
+
+/**
+ * hls.js fatal 错误分级恢复策略
+ *
+ * 按 hls.js 官方最佳实践实施三级自愈：
+ * 网络级 startLoad() → 媒体级 recoverMediaError()（二次失败自动
+ * swapAudioCodec）→ 其他/超限交由上层销毁重建；全部动作有界。
+ * 通过回调注入通知上层（不依赖 ArtPlayer），保持模块可移植性
+ *
+ * @module recovery
+ */
+
+/** 恢复策略回调集合（由编排层注入并绑定到具体通知渠道） */
+interface FatalRecoveryOptions {
+    /** 单实例内软恢复的最大次数上限 */
+    retryMax: number;
+    /** 每次 fatal 发生时通知（含软恢复与放弃两种情形，附当前重试序号） */
+    onFatalError: (data: ErrorData, retryCount: number) => void;
+    /** 遇到不可软恢复的 fatal（其他类型错误），交由上层销毁重建 */
+    onUnrecoverable: (data: ErrorData, retryCount: number) => void;
+}
+/**
+ * fatal 分级恢复策略
+ *
+ * 挂载在单个 hls.js 实例的 ERROR 事件上，随实例销毁而失效；
+ * 软恢复计数为实例级（重建后的新实例从零计数）
+ */
+declare class FatalRecoveryPolicy {
+    #private;
+    /**
+     * @param hls - 目标 hls.js 实例
+     * @param hlsConstructor - hls.js 构造器（Events/ErrorTypes 枚举来源，
+     *   避免本模块引入 hls.js 运行时值以保持可移植性）
+     * @param options - 回调集合
+     */
+    constructor(hls: Hls, hlsConstructor: typeof Hls, options: FatalRecoveryOptions);
+}
+
+/**
+ * P2P 播放引擎工厂
+ *
+ * 职责：
+ * - 合并 tracker 快捷配置与 core 全量配置，并注入插件运行时开关状态
+ * - 缓存 injectMixin 生成的 HlsWithP2P 构造器（每个 hls.js 构造器仅生成一次）
+ * - 创建携带 P2P 能力的 hls.js 实例，并挂载 fatal 分级恢复策略
+ *
+ * P2P / 上传开关统一经运行时动态配置实现（见 controller），
+ * 实例创建时的初始注入保证重建后模式不丢失，
+ * 因此本模块不再提供"裸 hls.js 实例"工厂
+ *
+ * @module engine
+ */
+
+/** 引擎消费的选项结构化子集（ResolvedOptions 结构化兼容） */
+interface EngineOptions extends Pick<P2POptions, 'core' | 'tracker' | 'hls' | 'fatalRetryMax'> {
+    /** 当前 P2P 开关状态（注入 isP2PDisabled） */
+    p2pEnabled: boolean;
+    /** 当前上传开关状态（注入 isP2PUploadDisabled） */
+    uploadEnabled: boolean;
+}
+/** hls.js 构造器类型 */
+type HlsConstructor = typeof Hls;
+/**
+ * 引擎工厂钩子集合（由编排层注入）
+ *
+ * onEngineCreated 在引擎就绪时触发，供事件桥挂载；
+ * 其余两个钩子用于 fatal 通知与不可恢复错误上报
+ */
+interface EngineHooks {
+    /** P2P 引擎就绪（onHlsJsCreated 时机），供事件桥挂载 */
+    onEngineCreated: (engine: HlsJsP2PEngine) => void;
+    /** fatal 发生通知（含软恢复与放弃两种情形） */
+    onFatalError: (data: ErrorData, retryCount: number) => void;
+    /** 遇到不可软恢复的 fatal，由编排层决定销毁重建 */
+    onUnrecoverable: (data: ErrorData, retryCount: number) => void;
+}
+/**
+ * 创建携带 P2P 能力的 hls.js 播放实例
+ *
+ * core 配置经 applyRuntimeToggle 注入当前开关状态；
+ * 仅完成实例构造与 fatal 恢复挂载，loadSource / attachMedia
+ * 的调用时机由调用方决定
+ *
+ * @param options - 引擎选项（含透传配置与运行时开关状态）
+ * @param hlsConstructor - 宿主提供的 hls.js 构造器（peerDependency 实例）
+ * @param hooks - 引擎钩子集合
+ * @returns HlsWithP2P 播放实例
+ */
+declare function createHlsWithP2P(options: EngineOptions, hlsConstructor: HlsConstructor, hooks: EngineHooks): HlsWithP2PInstance<Hls>;
+
+/**
+ * P2P 实例生命周期控制器
+ *
+ * 唯一持有播放实例与跨实例状态（最近 URL / 视频 / 重建计数 /
+ * P2P 与上传开关）的状态机；换源、fatal 重建、开关切换、销毁
+ * 全部收敛为显式方法。art.hls 槽位的写入与清空只发生在本模块内
+ *
+ * 开关语义：
+ * - P2P / 上传开关经 engine.applyDynamicConfig 无损切换，
+ *   不销毁实例、不中断播放
+ * - 实例创建（首装 / fatal 重建 / 换源 / 重连）时按当前开关状态
+ *   注入初始配置，保证重建后模式不丢失
+ * - activate 不接受模式参数：模式一律取控制器运行时状态，
+ *   避免 customType 重入路径（video:error 重连）重置用户的开关选择
+ *
+ * @module controller
+ */
+
+/** 控制器状态：idle 未创建 / active 播放中 / destroyed 播放器已销毁 */
+type ControllerState = 'idle' | 'active' | 'destroyed';
+/** P2P 实例生命周期控制器 */
+declare class P2PController {
+    #private;
+    /**
+     * @param art - ArtPlayer 实例
+     * @param options - 解析后的插件选项（p2pEnabled / uploadEnabled 为初始开关状态）
+     * @param stats - 统计引擎实例（由入口层创建并共享给句柄）
+     */
+    constructor(art: Artplayer, options: ResolvedOptions, stats: P2PStatsEngine);
+    /** 当前控制器状态 */
+    get state(): ControllerState;
+    /** 当前 P2P 开关状态 */
+    get p2pEnabled(): boolean;
+    /** 当前上传开关状态 */
+    get uploadEnabled(): boolean;
+    /** 当前播放实例（与 art.hls 槽位同步） */
+    get hls(): HlsWithP2PInstance<Hls> | undefined;
+    /**
+     * 外部显式激活（customType 回调：首次加载 / 换源 / 重连共用）
+     *
+     * 视为新的播放意图：统计与重建计数全部归零，
+     * 以控制器当前开关状态创建实例（不接受模式参数）
+     *
+     * @param url - 播放地址
+     * @param video - 视频元素
+     */
+    activate(url: string, video: HTMLVideoElement): void;
+    /** 销毁当前播放实例（注销监听、清空 art.hls 槽位） */
+    deactivate(): void;
+    /** 销毁现有实例后按最近地址与当前开关模式重建 */
+    reload(): void;
+    /**
+     * P2P 运行时开关：经 applyDynamicConfig 无损切换
+     *
+     * 不销毁实例、不中断播放；关闭时 HybridLoader 被引擎销毁、
+     * peer 连接全断，主动清零 peer 计数防止残留（迟到关闭事件
+     * 由统计引擎的非负保护兜底）；字节统计冻结保留供模式对照
+     *
+     * @param enabled - 目标 P2P 状态
+     */
+    setP2PEnabled(enabled: boolean): void;
+    /**
+     * 上行运行时开关：仅信令广播（引擎内部处理），完全无缝
+     *
+     * @param enabled - 目标上传状态
+     */
+    setUploadEnabled(enabled: boolean): void;
+    /** 播放器销毁：终止一切并进入 destroyed（幂等） */
+    destroy(): void;
+}
+
+/**
+ * ArtPlayer P2P 插件入口
+ *
+ * 将 p2p-media-loader（hls.js 引擎）封装为 ArtPlayer 插件：
+ * 通过 option.plugins 注入即可为 m3u8 播放启用 P2P 分发，
+ * 支持自建 tracker 信令服务器配置、运行时开关与统计
+ *
+ * 组装流程依赖 ArtPlayer 的两个时序事实：
+ * 1. 插件工厂在 Player.optionInit 之后执行，首次 URL 加载已经发生，
+ *    因此 customType 注册完成后需要对匹配类型的源做二次赋值补救
+ * 2. video:error 重连经 art.url 重赋值会重新进入 customType 回调，
+ *    回调内控制器的 activate 幂等（先销毁再重建），重入安全
+ *
+ * 用法：
+ *   new Artplayer({
+ *     url: 'https://example.com/stream.m3u8',
+ *     type: 'm3u8',
+ *     plugins: [artplayerPluginP2P({ tracker: { announceTrackers: ['wss://tracker.example.com'] } })],
+ *   })
+ *
+ * @module index
+ */
+
+/**
+ * ArtPlayer P2P 插件工厂
+ *
+ * 自动注册 customType 并对首次加载做时序接管（用户零感知）；
+ * 返回的句柄挂载在 art.plugins.artplayerPluginP2P
+ *
+ * @param options - 插件选项
+ * @returns ArtPlayer 插件函数
+ */
+declare function artplayerPluginP2P(options?: P2POptions): (art: Artplayer) => P2PPluginHandle;
+
+export { type ControllerState, type EngineHooks, type EngineOptions, FatalRecoveryPolicy, P2PController, P2POptions, P2PPluginHandle, P2PStatsEngine, createHlsWithP2P, artplayerPluginP2P as default };