@realsee/dnalogel 3.80.8-alpha.2 → 3.81.0-alpha.1

package/libs/DigitalPerformanceV2Plugin/core/CameraDirector.d.ts

@@ -0,0 +1,61 @@
+import type { Five } from '@realsee/five';
+import type { CameraTrack } from './CameraTrack';
+import type { PerformanceClock } from './PerformanceClock';
+import type { CameraState } from '../typings';
+/**
+ * CameraDirector —— 运镜导演（统一 Mapview / orbit 参数系）
+ *
+ * 绑定一条 CameraTrack，订阅统一时钟 tick，采样 CameraState 经 FiveModelCameraBridge 应用到相机。
+ * - 逐帧/seek 均以 immediately=true 贴合采样状态（不依赖 five 内插，跟随精确）。
+ * - setEnabled(false)：后续播放 tick 不接管相机、保留 five 当前状态。
+ * - 空轨道/无关键帧：不接管相机。
+ *
+ * 由于运镜统一为 Mapview orbit 位姿，导演接管期间 five 始终是合法 Mapview 状态；
+ * 暂停只需停止 tick 即把相机「交还用户」——无需任何 look-from→orbit 转换（旧 applyAsOrbit / releaseToUser 已移除）。
+ */
+export declare class CameraDirector {
+    private bridge;
+    private track;
+    private clock;
+    private enabled;
+    private unsubTick;
+    constructor(five: Five);
+    /** 绑定/替换轨道（传 null 解绑） */
+    bindTrack(track: CameraTrack | null): void;
+    /** 跟随时钟播放：订阅 onTick → 采样 → 应用（仅在时钟实际播放时接管，编辑期 seek 不接管） */
+    attach(clock: PerformanceClock): void;
+    /** 解除时钟订阅（不清空 track） */
+    detach(): void;
+    /** 编辑端 seek 预览：立即采样并应用到指定时间（不依赖播放状态） */
+    seek(time: number): void;
+    /**
+     * 直接将一个 CameraState 立即应用到 five（immediately=true），不经轨道/时钟。
+     * 供「章节默认视角」等编辑端能力使用。复用既有桥实例。
+     * 不受 enabled 开关与轨道是否有内容影响（调用方自行决定是否调用）。
+     * 应用后 five 即为合法 Mapview 状态，用户可立即正常拖拽（左键 orbit / 右键平移）。
+     */
+    applyCameraStateImmediately(state: CameraState): void;
+    /**
+     * 暂停态 scrub 预览：采样 `track.sample(time)` 并立即应用（预览后交还用户可立即拖拽）。
+     * 仅在 enabled 且 track 有内容时应用；否则 no-op（与 seek 预览的接管前置条件一致）。
+     */
+    previewAt(time: number): void;
+    /**
+     * 运镜开关。仅记录状态，不在此处写 five。
+     * - false：后续播放 tick 不接管相机。
+     * - true：后续播放 tick 按采样接管相机。
+     */
+    setEnabled(enabled: boolean): void;
+    isEnabled(): boolean;
+    /**
+     * 接管前 prepare（无突变 user→director 切换）。
+     * - enabled 且 track 有内容时：经 `bridge.applyAnimated(track.sample(time))` 以内插动画平滑回到目标视角，
+     *   await 过渡稳定后 resolve。暂停后用户拖动过的当前位姿与目标均为 Mapview 状态，动画为 orbit→orbit，干净不摆动。
+     * - 否则：立即 resolve（no-op）。
+     * 不触碰时钟、不改 enabled、不绑定/解绑轨道；调用方负责在时钟 start/resume 前 await，以保证 prepare 不计入播放时间。
+     */
+    prepareTo(time: number): Promise<void>;
+    /** 释放：解订阅并清空轨道 */
+    dispose(): void;
+    private applyAt;
+}

package/libs/DigitalPerformanceV2Plugin/core/CameraDirector.js

@@ -0,0 +1,101 @@
+var k = Object.defineProperty;
+var d = (e, t, i) => t in e ? k(e, t, { enumerable: !0, configurable: !0, writable: !0, value: i }) : e[t] = i;
+var s = (e, t, i) => (d(e, typeof t != "symbol" ? t + "" : t, i), i);
+var l = (e, t, i) => new Promise((c, n) => {
+  var u = (a) => {
+    try {
+      r(i.next(a));
+    } catch (h) {
+      n(h);
+    }
+  }, p = (a) => {
+    try {
+      r(i.throw(a));
+    } catch (h) {
+      n(h);
+    }
+  }, r = (a) => a.done ? c(a.value) : Promise.resolve(a.value).then(u, p);
+  r((i = i.apply(e, t)).next());
+});
+import { FiveModelCameraBridge as b } from "./FiveModelCameraBridge.js";
+import "three";
+class f {
+  constructor(t) {
+    s(this, "bridge");
+    s(this, "track", null);
+    s(this, "clock", null);
+    s(this, "enabled", !0);
+    s(this, "unsubTick", null);
+    this.bridge = new b(t);
+  }
+  /** 绑定/替换轨道（传 null 解绑） */
+  bindTrack(t) {
+    this.track = t;
+  }
+  /** 跟随时钟播放：订阅 onTick → 采样 → 应用（仅在时钟实际播放时接管，编辑期 seek 不接管） */
+  attach(t) {
+    this.detach(), this.clock = t, this.unsubTick = t.onTick((i) => {
+      this.clock && this.clock.isPlaying() && this.applyAt(i);
+    });
+  }
+  /** 解除时钟订阅（不清空 track） */
+  detach() {
+    this.unsubTick && (this.unsubTick(), this.unsubTick = null), this.clock = null;
+  }
+  /** 编辑端 seek 预览：立即采样并应用到指定时间（不依赖播放状态） */
+  seek(t) {
+    this.applyAt(t);
+  }
+  /**
+   * 直接将一个 CameraState 立即应用到 five（immediately=true），不经轨道/时钟。
+   * 供「章节默认视角」等编辑端能力使用。复用既有桥实例。
+   * 不受 enabled 开关与轨道是否有内容影响（调用方自行决定是否调用）。
+   * 应用后 five 即为合法 Mapview 状态，用户可立即正常拖拽（左键 orbit / 右键平移）。
+   */
+  applyCameraStateImmediately(t) {
+    this.bridge.apply(t, !0);
+  }
+  /**
+   * 暂停态 scrub 预览：采样 `track.sample(time)` 并立即应用（预览后交还用户可立即拖拽）。
+   * 仅在 enabled 且 track 有内容时应用；否则 no-op（与 seek 预览的接管前置条件一致）。
+   */
+  previewAt(t) {
+    this.enabled && (!this.track || !this.track.hasContent() || this.bridge.apply(this.track.sample(t), !0));
+  }
+  /**
+   * 运镜开关。仅记录状态，不在此处写 five。
+   * - false：后续播放 tick 不接管相机。
+   * - true：后续播放 tick 按采样接管相机。
+   */
+  setEnabled(t) {
+    this.enabled = t;
+  }
+  isEnabled() {
+    return this.enabled;
+  }
+  /**
+   * 接管前 prepare（无突变 user→director 切换）。
+   * - enabled 且 track 有内容时：经 `bridge.applyAnimated(track.sample(time))` 以内插动画平滑回到目标视角，
+   *   await 过渡稳定后 resolve。暂停后用户拖动过的当前位姿与目标均为 Mapview 状态，动画为 orbit→orbit，干净不摆动。
+   * - 否则：立即 resolve（no-op）。
+   * 不触碰时钟、不改 enabled、不绑定/解绑轨道；调用方负责在时钟 start/resume 前 await，以保证 prepare 不计入播放时间。
+   */
+  prepareTo(t) {
+    return l(this, null, function* () {
+      this.enabled && (!this.track || !this.track.hasContent() || (yield this.bridge.applyAnimated(this.track.sample(t))));
+    });
+  }
+  /** 释放：解订阅并清空轨道 */
+  dispose() {
+    this.detach(), this.track = null;
+  }
+  applyAt(t) {
+    if (!this.enabled || !this.track || !this.track.hasContent())
+      return;
+    const i = this.track.sample(t);
+    this.bridge.apply(i, !0);
+  }
+}
+export {
+  f as CameraDirector
+};

package/libs/DigitalPerformanceV2Plugin/core/CameraSampler.d.ts

@@ -0,0 +1,53 @@
+import * as THREE from 'three';
+import type { CameraTransition, DigitalCameraKeyframe, CameraState } from '../typings';
+/**
+ * CameraSampler —— 带插值的运镜采样（共享底座），统一在 five **Mapview**（orbit）参数系下补帧。
+ *
+ * 关键帧以 orbit 位姿表达：{ target, longitude, latitude, distance, fov }。
+ * 相邻帧的区间缓动由「较早」关键帧 kf[i] 的 transition 决定（与 Requirement 2.1 一致）。
+ * - target：分量线性插值（Vector3 lerp）
+ * - longitude：最短弧角度插值（处理 ±π 环绕）
+ * - latitude / distance / fov：线性插值
+ * 末帧封顶、首帧夹紧；'instant' 直接 snap 到当前帧；不修改入参。
+ *
+ * 相对旧的「position+forward / look-from」表示：orbit 参数系下相邻帧的插值是「绕目标点的圆弧运动」，
+ * 与用户在 Mapview 编辑时所见一致（绕主体环绕），而非两点间直线 dolly。
+ */
+/** 把数值夹紧到 [min, max] */
+export declare function clamp(value: number, min: number, max: number): number;
+/**
+ * 二分查找：返回 timeStamp <= time 的最大关键帧下标。
+ * 前置：keyframes 非空且按 timeStamp 升序。后置：0 <= 返回 <= length-1；早于首帧返回 0。
+ */
+export declare function getKeyframeIndexByTime(time: number, keyframes: ReadonlyArray<{
+    timeStamp: number;
+}>): number;
+/**
+ * 缓动函数：把线性进度 p∈[0,1] 映射为缓动后的插值因子。
+ * - 'easeInOut' : smoothstep p*p*(3-2p)
+ * - 其它（含 'linear' / undefined） : 恒等
+ * 端点固定：ease(0)=0、ease(1)=1；值域有界：p∈[0,1] ⇒ 返回 ∈[0,1]。
+ */
+export declare function ease(p: number, transition?: CameraTransition): number;
+/**
+ * 归一化时间比例：p = clamp((time - curTs) / (nextTs - curTs), 0, 1)。
+ * nextTs <= curTs（异常或零长区间）时返回 0，避免除零。
+ */
+export declare function normalizedRatio(time: number, curTs: number, nextTs: number): number;
+/** 最短弧角度插值：沿 (-π,π] 的最短方向从 a 插到 b。 */
+export declare function lerpAngle(a: number, b: number, t: number): number;
+/** 采样 orbit 目标点（分量线性插值）。末帧封顶、'instant' 取当前帧。 */
+export declare function sampleTarget(time: number, keyframes: ReadonlyArray<DigitalCameraKeyframe>): THREE.Vector3;
+/** 采样 longitude（最短弧角度插值）。 */
+export declare function sampleLongitude(time: number, keyframes: ReadonlyArray<DigitalCameraKeyframe>): number;
+/** 采样 latitude（线性插值）。 */
+export declare function sampleLatitude(time: number, keyframes: ReadonlyArray<DigitalCameraKeyframe>): number;
+/** 采样 distance（线性插值）。 */
+export declare function sampleDistance(time: number, keyframes: ReadonlyArray<DigitalCameraKeyframe>): number;
+/** 采样 fov（线性插值）；末帧封顶、'instant' 取当前帧。 */
+export declare function sampleFov(time: number, keyframes: ReadonlyArray<DigitalCameraKeyframe>): number;
+/**
+ * 组装：按时间采样出统一 CameraState（已插值，Mapview orbit 位姿）。
+ * 单关键帧时对任意时间返回该唯一帧位姿。不修改入参。
+ */
+export declare function sampleCameraState(time: number, keyframes: ReadonlyArray<DigitalCameraKeyframe>): CameraState;

package/libs/DigitalPerformanceV2Plugin/core/CameraSampler.js

@@ -0,0 +1,91 @@
+import * as p from "three";
+function l(o, t, i) {
+  return o < t ? t : o > i ? i : o;
+}
+function u(o, t) {
+  const i = t.length;
+  if (i <= 1 || o <= t[0].timeStamp)
+    return 0;
+  if (o >= t[i - 1].timeStamp)
+    return i - 1;
+  let n = 0, r = i - 1;
+  for (; r - n > 1; ) {
+    const c = n + r >> 1;
+    t[c].timeStamp <= o ? n = c : r = c;
+  }
+  return n;
+}
+function e(o, t) {
+  const i = l(o, 0, 1);
+  return t === "easeInOut" ? i * i * (3 - 2 * i) : i;
+}
+function a(o, t, i) {
+  const n = i - t;
+  return n <= 0 ? 0 : l((o - t) / n, 0, 1);
+}
+function d(o, t, i) {
+  const n = Math.atan2(Math.sin(t - o), Math.cos(t - o));
+  return o + n * i;
+}
+function s(o) {
+  var i, n, r, c;
+  const t = (i = o.target) != null ? i : [0, 0, 0];
+  return new p.Vector3((n = t[0]) != null ? n : 0, (r = t[1]) != null ? r : 0, (c = t[2]) != null ? c : 0);
+}
+function g(o, t) {
+  const i = u(o, t), n = t[i];
+  if (i === t.length - 1 || n.transition === "instant")
+    return s(n);
+  const r = t[i + 1], c = e(a(o, n.timeStamp, r.timeStamp), n.transition);
+  return s(n).lerp(s(r), c);
+}
+function S(o, t) {
+  const i = u(o, t), n = t[i];
+  if (i === t.length - 1 || n.transition === "instant")
+    return n.longitude;
+  const r = t[i + 1], c = e(a(o, n.timeStamp, r.timeStamp), n.transition);
+  return d(n.longitude, r.longitude, c);
+}
+function f(o, t) {
+  const i = u(o, t), n = t[i];
+  if (i === t.length - 1 || n.transition === "instant")
+    return n.latitude;
+  const r = t[i + 1], c = e(a(o, n.timeStamp, r.timeStamp), n.transition);
+  return n.latitude + (r.latitude - n.latitude) * c;
+}
+function h(o, t) {
+  const i = u(o, t), n = t[i];
+  if (i === t.length - 1 || n.transition === "instant")
+    return n.distance;
+  const r = t[i + 1], c = e(a(o, n.timeStamp, r.timeStamp), n.transition);
+  return n.distance + (r.distance - n.distance) * c;
+}
+function x(o, t) {
+  const i = u(o, t), n = t[i];
+  if (i === t.length - 1 || n.transition === "instant")
+    return n.fov;
+  const r = t[i + 1], c = e(a(o, n.timeStamp, r.timeStamp), n.transition);
+  return n.fov + (r.fov - n.fov) * c;
+}
+function m(o, t) {
+  return {
+    target: g(o, t),
+    longitude: S(o, t),
+    latitude: f(o, t),
+    distance: h(o, t),
+    fov: x(o, t)
+  };
+}
+export {
+  l as clamp,
+  e as ease,
+  u as getKeyframeIndexByTime,
+  d as lerpAngle,
+  a as normalizedRatio,
+  m as sampleCameraState,
+  h as sampleDistance,
+  x as sampleFov,
+  f as sampleLatitude,
+  S as sampleLongitude,
+  g as sampleTarget
+};

package/libs/DigitalPerformanceV2Plugin/core/CameraTrack.d.ts

@@ -0,0 +1,21 @@
+import type { CameraState, DigitalCameraKeyframe } from '../typings';
+/**
+ * CameraTrack —— 相机轨道
+ *
+ * 把运镜关键帧序列封装为可按时间采样（含插值）的轨道，委托 CameraSampler 完成补帧。
+ * 关键帧统一为 Mapview orbit 位姿 { target, longitude, latitude, distance, fov }。
+ */
+export declare class CameraTrack {
+    private keyframes;
+    /** 设置/替换关键帧序列（按 timeStamp 升序，不修改入参数组） */
+    setKeyframes(keyframes: ReadonlyArray<DigitalCameraKeyframe>): void;
+    /** 按时间采样出统一 CameraState（已插值） */
+    sample(time: number): CameraState;
+    /** 本轨道有效时间范围（首帧~末帧 timeStamp） */
+    getTimeRange(): {
+        start: number;
+        end: number;
+    };
+    /** 是否有可用关键帧 */
+    hasContent(): boolean;
+}

package/libs/DigitalPerformanceV2Plugin/core/CameraTrack.js

@@ -0,0 +1,32 @@
+var s = Object.defineProperty;
+var i = (r, e, t) => e in r ? s(r, e, { enumerable: !0, configurable: !0, writable: !0, value: t }) : r[e] = t;
+var a = (r, e, t) => (i(r, typeof e != "symbol" ? e + "" : e, t), t);
+import { sampleCameraState as n } from "./CameraSampler.js";
+import "three";
+class p {
+  constructor() {
+    a(this, "keyframes", []);
+  }
+  /** 设置/替换关键帧序列（按 timeStamp 升序，不修改入参数组） */
+  setKeyframes(e) {
+    this.keyframes = [...e].sort((t, m) => t.timeStamp - m.timeStamp);
+  }
+  /** 按时间采样出统一 CameraState（已插值） */
+  sample(e) {
+    return n(e, this.keyframes);
+  }
+  /** 本轨道有效时间范围（首帧~末帧 timeStamp） */
+  getTimeRange() {
+    return this.keyframes.length === 0 ? { start: 0, end: 0 } : {
+      start: this.keyframes[0].timeStamp,
+      end: this.keyframes[this.keyframes.length - 1].timeStamp
+    };
+  }
+  /** 是否有可用关键帧 */
+  hasContent() {
+    return this.keyframes.length > 0;
+  }
+}
+export {
+  p as CameraTrack
+};

package/libs/DigitalPerformanceV2Plugin/core/FiveModelCameraBridge.d.ts

@@ -0,0 +1,39 @@
+import type { Five } from '@realsee/five';
+import type { CameraState } from '../typings';
+/**
+ * FiveModelCameraBridge —— CameraState ↔ five **Mapview**（地图态 / orbit）参数的唯一收敛点。
+ *
+ * 统一运镜采用 Mapview orbit 位姿：相机绕 `target` 旋转，
+ *   相机位置 = target − coordinatesToVector(longitude, latitude) × distance，视线恒指向 `target`。
+ * 因此「播放逐帧接管」与「暂停交还用户拖拽」处于同一参数系：
+ * 暂停瞬间 five 已是合法 Mapview 状态（offset=target、distance>0），用户可直接左键 orbit / 右键平移，
+ * 无需任何 look-from→orbit 转换、无跳变。
+ *
+ * apply：target→offset、longitude/latitude/distance 直传、fov 钳制、mode='Mapview'。
+ * capture：从 five 当前 Mapview 位姿反读一个 CameraState。
+ *
+ * 注：类名沿用历史 `FiveModelCameraBridge`（避免大范围改名）；实际目标模态为 Mapview。
+ */
+export declare class FiveModelCameraBridge {
+    private five;
+    constructor(five: Five);
+    /**
+     * 将 CameraState 应用到 five（mode:'Mapview'）。对 `five.setState` 恰好一次。
+     * - fov 钳制到开区间 (0,180)（含 fov<=0 与 NaN），不拒绝、不抛错。
+     * @param immediately five.setState 第二参数。true（缺省）= 立即贴合目标（逐帧驱动/seek 用）；false = 走 five 内插动画。
+     */
+    apply(state: CameraState, immediately?: boolean): void;
+    /**
+     * 加法式：以「走 five 内插动画」的方式应用 CameraState（`apply` 的 immediately=false 分支），
+     * 返回一个在过渡完成后 resolve 的 Promise。
+     * - 映射规则与 `apply` 完全一致，对 `five.setState` 恰好一次，仅第二参数取 false（动画）。
+     * - 完成信号：`five.setState` 返回 void、无可等待对象，故以一次过渡时长（CAMERA_TRANSITION_MS）兜底后 resolve。
+     */
+    applyAnimated(state: CameraState): Promise<void>;
+    /**
+     * 从 five 当前 Mapview 位姿反读一个 CameraState。
+     * five.getCurrentState() 返回 { offset, longitude, latitude, distance, fov }（来自相机 pose），
+     * 其中 offset 即 orbit 目标点（target）。
+     */
+    capture(): CameraState;
+}

package/libs/DigitalPerformanceV2Plugin/core/FiveModelCameraBridge.js

@@ -0,0 +1,72 @@
+var u = Object.defineProperty;
+var d = (t, e, i) => e in t ? u(t, e, { enumerable: !0, configurable: !0, writable: !0, value: i }) : t[e] = i;
+var n = (t, e, i) => (d(t, typeof e != "symbol" ? e + "" : e, i), i);
+import * as a from "three";
+const o = 1e-6, l = 700;
+function r(t) {
+  return t > 0 ? t >= 180 ? 180 - o : t : o;
+}
+class f {
+  constructor(e) {
+    n(this, "five");
+    this.five = e;
+  }
+  /**
+   * 将 CameraState 应用到 five（mode:'Mapview'）。对 `five.setState` 恰好一次。
+   * - fov 钳制到开区间 (0,180)（含 fov<=0 与 NaN），不拒绝、不抛错。
+   * @param immediately five.setState 第二参数。true（缺省）= 立即贴合目标（逐帧驱动/seek 用）；false = 走 five 内插动画。
+   */
+  apply(e, i = !0) {
+    this.five.setState(
+      {
+        offset: e.target.clone(),
+        longitude: e.longitude,
+        latitude: e.latitude,
+        distance: e.distance,
+        fov: r(e.fov),
+        mode: "Mapview"
+      },
+      i
+    );
+  }
+  /**
+   * 加法式：以「走 five 内插动画」的方式应用 CameraState（`apply` 的 immediately=false 分支），
+   * 返回一个在过渡完成后 resolve 的 Promise。
+   * - 映射规则与 `apply` 完全一致，对 `five.setState` 恰好一次，仅第二参数取 false（动画）。
+   * - 完成信号：`five.setState` 返回 void、无可等待对象，故以一次过渡时长（CAMERA_TRANSITION_MS）兜底后 resolve。
+   */
+  applyAnimated(e) {
+    return this.five.setState(
+      {
+        offset: e.target.clone(),
+        longitude: e.longitude,
+        latitude: e.latitude,
+        distance: e.distance,
+        fov: r(e.fov),
+        mode: "Mapview"
+      },
+      /* immediately */
+      !1
+    ), new Promise((i) => {
+      setTimeout(i, l);
+    });
+  }
+  /**
+   * 从 five 当前 Mapview 位姿反读一个 CameraState。
+   * five.getCurrentState() 返回 { offset, longitude, latitude, distance, fov }（来自相机 pose），
+   * 其中 offset 即 orbit 目标点（target）。
+   */
+  capture() {
+    const e = this.five.getCurrentState();
+    return {
+      target: e.offset ? e.offset.clone() : new a.Vector3(),
+      longitude: Number.isFinite(e.longitude) ? e.longitude : 0,
+      latitude: Number.isFinite(e.latitude) ? e.latitude : 0,
+      distance: Number.isFinite(e.distance) ? e.distance : 0,
+      fov: e.fov
+    };
+  }
+}
+export {
+  f as FiveModelCameraBridge
+};

package/libs/DigitalPerformanceV2Plugin/core/PerformanceClock.d.ts

@@ -0,0 +1,55 @@
+import type { Five } from '@realsee/five';
+export type ClockTickListener = (time: number, delta: number) => void;
+export type ClockEndedListener = () => void;
+/**
+ * PerformanceClock —— 统一章节时钟（共享底座）
+ *
+ * 以 five 的 'renderFrame' 为唯一节拍源，维护章节内全局播放时间 t 并广播 tick。
+ * 取代各 DigitalHuman 内部独立的 requestAnimationFrame 与 Math.max 进度反推。
+ *
+ * 不变量：0 <= time <= duration；playing 期间相邻 tick 的 time 非递减（封顶 duration）。
+ */
+export declare class PerformanceClock {
+    private five;
+    private duration;
+    private time;
+    private playing;
+    private lastFrameTs;
+    private tickListeners;
+    private endedListeners;
+    constructor(five: Five);
+    /**
+     * 启动时钟。
+     * - duration<=0：不订阅 renderFrame、time 置 0、立即触发一次 ended。
+     * - 否则：time = clamp(fromTime, 0, duration)，订阅 renderFrame 作为唯一节拍源。
+     */
+    start(duration: number, fromTime?: number): void;
+    /**
+     * 配置时长但不启动、不订阅 renderFrame（供播放/预览专用切章 prepareChapter 使用）。
+     * 加法式新增：仅设置 duration 并把当前 time 夹紧到新 duration，不改变 playing 状态。
+     */
+    setDuration(duration: number): void;
+    /** 暂停：停止累加并保留当前 time */
+    pause(): void;
+    /** 续播：从保留的 time 继续；续播后首帧 delta 记 0，不产生跳变 */
+    resume(): void;
+    /** 跳转（seek 预览）：不改变播放状态；重置帧基准并广播一次 tick(0) */
+    seek(targetTime: number): void;
+    /** 停止：停表、解订阅、time 归零，可被再次 start */
+    stop(): void;
+    getTime(): number;
+    getDuration(): number;
+    isPlaying(): boolean;
+    /** 注册每帧 tick 监听；返回反订阅函数 */
+    onTick(listener: ClockTickListener): () => void;
+    /** 注册自然结束监听；返回反订阅函数 */
+    onEnded(listener: ClockEndedListener): () => void;
+    /** 释放：解订阅并清空监听 */
+    dispose(): void;
+    private clampTime;
+    private subscribeFrame;
+    private unsubscribeFrame;
+    private onFrame;
+    private emitTick;
+    private emitEnded;
+}

package/libs/DigitalPerformanceV2Plugin/core/PerformanceClock.js

@@ -0,0 +1,98 @@
+var r = Object.defineProperty;
+var n = (s, i, t) => i in s ? r(s, i, { enumerable: !0, configurable: !0, writable: !0, value: t }) : s[i] = t;
+var e = (s, i, t) => (n(s, typeof i != "symbol" ? i + "" : i, t), t);
+class h {
+  constructor(i) {
+    e(this, "five");
+    e(this, "duration", 0);
+    e(this, "time", 0);
+    e(this, "playing", !1);
+    e(this, "lastFrameTs", null);
+    e(this, "tickListeners", /* @__PURE__ */ new Set());
+    e(this, "endedListeners", /* @__PURE__ */ new Set());
+    e(this, "onFrame", () => {
+      if (!this.playing)
+        return;
+      this.five.needsRender = !0;
+      const i = performance.now();
+      this.lastFrameTs === null && (this.lastFrameTs = i);
+      let t = i - this.lastFrameTs;
+      this.lastFrameTs = i, (t > 200 || t < 0) && (t = 0), this.time = Math.min(this.time + t, this.duration), this.emitTick(t), this.time >= this.duration && (this.playing = !1, this.unsubscribeFrame(), this.emitEnded());
+    });
+    this.five = i;
+  }
+  /**
+   * 启动时钟。
+   * - duration<=0：不订阅 renderFrame、time 置 0、立即触发一次 ended。
+   * - 否则：time = clamp(fromTime, 0, duration)，订阅 renderFrame 作为唯一节拍源。
+   */
+  start(i, t = 0) {
+    if (this.duration = i, !(i > 0)) {
+      this.duration = 0, this.time = 0, this.playing = !1, this.lastFrameTs = null, this.unsubscribeFrame(), this.emitEnded();
+      return;
+    }
+    this.time = this.clampTime(t), this.playing = !0, this.lastFrameTs = null, this.subscribeFrame();
+  }
+  /**
+   * 配置时长但不启动、不订阅 renderFrame（供播放/预览专用切章 prepareChapter 使用）。
+   * 加法式新增：仅设置 duration 并把当前 time 夹紧到新 duration，不改变 playing 状态。
+   */
+  setDuration(i) {
+    this.duration = i > 0 ? i : 0, this.time = this.clampTime(this.time);
+  }
+  /** 暂停：停止累加并保留当前 time */
+  pause() {
+    this.playing = !1;
+  }
+  /** 续播：从保留的 time 继续；续播后首帧 delta 记 0，不产生跳变 */
+  resume() {
+    this.playing || this.duration <= 0 || this.time >= this.duration || (this.playing = !0, this.lastFrameTs = null, this.subscribeFrame());
+  }
+  /** 跳转（seek 预览）：不改变播放状态；重置帧基准并广播一次 tick(0) */
+  seek(i) {
+    this.time = this.clampTime(i), this.lastFrameTs = null, this.emitTick(0);
+  }
+  /** 停止：停表、解订阅、time 归零，可被再次 start */
+  stop() {
+    this.playing = !1, this.time = 0, this.lastFrameTs = null, this.unsubscribeFrame();
+  }
+  getTime() {
+    return this.time;
+  }
+  getDuration() {
+    return this.duration;
+  }
+  isPlaying() {
+    return this.playing;
+  }
+  /** 注册每帧 tick 监听；返回反订阅函数 */
+  onTick(i) {
+    return this.tickListeners.add(i), () => this.tickListeners.delete(i);
+  }
+  /** 注册自然结束监听；返回反订阅函数 */
+  onEnded(i) {
+    return this.endedListeners.add(i), () => this.endedListeners.delete(i);
+  }
+  /** 释放：解订阅并清空监听 */
+  dispose() {
+    this.unsubscribeFrame(), this.tickListeners.clear(), this.endedListeners.clear();
+  }
+  clampTime(i) {
+    return i > 0 ? i > this.duration ? this.duration : i : 0;
+  }
+  subscribeFrame() {
+    this.five.off("renderFrame", this.onFrame), this.five.on("renderFrame", this.onFrame);
+  }
+  unsubscribeFrame() {
+    this.five.off("renderFrame", this.onFrame);
+  }
+  emitTick(i) {
+    this.tickListeners.forEach((t) => t(this.time, i));
+  }
+  emitEnded() {
+    this.endedListeners.forEach((i) => i());
+  }
+}
+export {
+  h as PerformanceClock
+};