@realsee/dnalogel 3.81.13 → 4.0.0-webgpu.3

package/dist/types/DigitalPerformanceV2Plugin/controller/index.d.ts

@@ -0,0 +1,402 @@
+import { Five } from '@realsee/five-webgpu';
+import { DigitalPerformanceV2PluginConfig, DigitalCameraKeyframe, DigitalCameraPlayer, CameraTransition, CameraCoordinateSpace, CameraState, GroupChapterTimeInfo, GroupProgress } from '../typings/index.js';
+import { PerformancePlayground } from '../core/Playground.js';
+import { AnimationScriptAdapterOptions } from '../../DigitalPerformancePlugin/animation-script-adapter.js';
+import { DigitalScript, DigitalChapter } from '../core/shared.js';
+/** 播放进度（当前章节内） */
+export interface V2Progress {
+    /** 当前时间(ms) */
+    currentTime: number;
+    /** 当前章节总时长(ms) */
+    totalTime: number;
+    /** 当前章节索引（0-based；无当前章节为 -1） */
+    currentChapterIndex: number;
+    /** 当前动画组内的章节总数 */
+    totalChapters: number;
+}
+export type V2ProgressListener = (progress: V2Progress) => void;
+/** 组级进度监听 */
+export type GroupProgressListener = (progress: GroupProgress) => void;
+/** 运镜关键帧捕获/编辑的可选项 */
+export interface CameraKeyframeOptions {
+    /** 到下一关键帧的过渡缓动（缺省 'linear'） */
+    transition?: CameraTransition;
+    /** 关键帧缩略图 URL（COS 直传得到；运行时忽略） */
+    thumbnail?: string;
+}
+/** 运镜关键帧增删改操作结果（拒绝时 success=false 并保持序列不变） */
+export interface CameraKeyframeResult {
+    success: boolean;
+    /** 失败原因（success=false 时存在） */
+    error?: string;
+    /** 操作后的最新关键帧序列（升序，副本） */
+    keyframes: DigitalCameraKeyframe[];
+}
+/** setTimelineTo 操作结果 */
+export interface SetTimelineResult {
+    success: boolean;
+    error?: string;
+}
+/** 序列化运镜 player 的结果 */
+export interface SerializeCameraResult {
+    success: boolean;
+    error?: string;
+    player?: DigitalCameraPlayer;
+}
+/** 关键帧序列变更监听（携带升序最新序列） */
+export type CameraKeyframesChangedListener = (keyframes: DigitalCameraKeyframe[]) => void;
+/** 当前章节信息（编辑端用） */
+export interface CurrentChapterInfo {
+    /** 当前章节索引（0-based；无当前章节为 -1） */
+    index: number;
+    /** 当前章节名称（无当前章节为空串） */
+    name: string;
+    /** 当前章节总时长(ms)：该章节模型动画时长（排除相机 player） */
+    duration: number;
+}
+/** 当前章节变更监听（携带最新当前章节信息） */
+export type CurrentChapterChangedListener = (info: CurrentChapterInfo) => void;
+/**
+ * DigitalPerformanceV2Plugin 控制器（最小可用版）
+ *
+ * 试点 fork：独立于现有 DigitalPerformancePlugin（Legacy），不修改其既有行为。
+ * 本版本提供：剧本加载（复用 Shared_Core 加载 + 模型入场景）、播放/暂停/续播、
+ * 基于统一时钟的进度与 seek 预览。相机运镜（CameraTrack/CameraDirector）在后续任务叠加。
+ */
+export default class DigitalPerformanceV2PluginController {
+    five: Five;
+    config: DigitalPerformanceV2PluginConfig;
+    readonly NAME = "Dnalogel-DigitalPerformanceV2Plugin";
+    playground: PerformancePlayground;
+    state: {
+        enabled: boolean;
+        playing: boolean;
+        continuousPlaying: boolean;
+        currentChapter: DigitalChapter | null;
+        currentScript: DigitalScript | null;
+        /** 编辑端：当前选中的运镜项下标（无选中为 null）。切换章节时清除。 */
+        selectedShotIndex: number | null;
+    };
+    private progressListeners;
+    private groupProgressListeners;
+    private keyframesChangedListeners;
+    private currentChapterChangedListeners;
+    private nameplate;
+    private unsubNameplateRender;
+    private unsubNameplateCameraUpdate;
+    private unsubClockTick;
+    /**
+     * 进入编辑时的运镜内存态快照：以章节对象为 key，值为该章节相机关键帧的深拷贝；
+     * 值为 null 表示进入编辑时该章节不存在 camera player。null（整体）表示尚未打过快照。
+     */
+    private cameraEditSnapshot;
+    /**
+     * 组级章节时间映射缓存（加法式）：按 currentScript 引用缓存。
+     * - `groupChapterTimeMapCacheScript` 记录缓存对应的 script 引用；
+     * - script 变更 / loadScript 时引用不一致 ⇒ 缓存失效、下次请求重算。
+     */
+    private groupChapterTimeMapCache;
+    private groupChapterTimeMapCacheScript;
+    /**
+     * D-SEEK-LIVE（方案 A）：连播中「跨章 seek」的重定向令牌。
+     * 播放态跨章 seek 时置位 { index, fromTime } 并 abortCurrentPlay；连播循环 await 返回后据此跳转到目标章节继续播放。
+     */
+    private seekRedirect;
+    /**
+     * 加法式：动画组「章节索引 → 楼层」映射（用于 Mapview 只显示当前章节所在楼层）。
+     * - number：该章节单一楼层 ⇒ `five.model.show(floor)`；
+     * - null：该章节内多段动画跨楼层 ⇒ `five.model.show()`（显示全部，避免藏掉其它层的动画）；
+     * - 映射缺项按显示全部处理。
+     * `null`（整体）表示未启用该能力（不触碰楼层可见性）。由消费方经 `setChapterFloorMap` 注入。
+     */
+    private chapterFloorMap;
+    /**
+     * 楼层可见性作用的目标模型（`show(floorIndex)` 的接收者）。
+     * - `null`：回退到 `five.model`（= `modelScene.models[0]`，单 VR 即唯一模型）。
+     * - 沙盘/联合现场：`five.model` 恒为 models[0]，未必是当前播放的子 VR，故消费方须显式注入
+     *   动画所属子 VR 的模型（`five.models.find(m => m.name === resourceCode)`），否则楼层隔离会落到
+     *   错误模型，被播放子 VR 保持全楼层可见（表现为「跨楼层动画所有楼层同时高亮」）。
+     */
+    private chapterFloorModel;
+    /** five 'modeChange' 楼层重放监听的反订阅句柄（chapterFloorMap 启用时挂载，停用/reset/dispose 时清理） */
+    private unsubFloorModeChange;
+    constructor(five: Five, config?: DigitalPerformanceV2PluginConfig);
+    /** 加载剧本：预加载资源 + 将模型加入 five 场景；autoPlay 时自动播放首章 */
+    private loadRevision;
+    loadScript(script: DigitalScript): Promise<void>;
+    /**
+     * 加载 raw animation detail。转换逻辑由 dnalogel 与 Legacy 插件共用，随后复用 canonical loadScript。
+     */
+    loadAnimationDetail(detail: unknown, options?: AnimationScriptAdapterOptions): Promise<DigitalScript>;
+    /** 播放指定章节 */
+    playChapter(chapter: DigitalChapter): Promise<void>;
+    /** 通过索引播放章节 */
+    playChapterByIndex(index: number): Promise<void>;
+    /** 从当前章节连续播放到最后一章（连播中跨章 seek 可经 seekRedirect 令牌无缝重定向） */
+    playAllRemaining(): Promise<void>;
+    /** 从第一章开始按顺序连续播放（用于"重播全部"，保留已捕获的各章节运镜） */
+    playAllFromStart(): Promise<void>;
+    /** 从指定章节索引开始，按顺序连续播放到本动画组最后一章（保留已捕获的各章节运镜） */
+    playFromChapterIndex(index: number): Promise<void>;
+    /**
+     * 编辑态：仅播放当前章节（不连播下一章）。
+     * 章节自然播放到末尾（ended）后，由 controller 执行「进度归零 + 恢复当前章节默认视角」，
+     * SHALL NOT 自动连播下一章节（区别于展示端 playAllRemaining 的章节连续播放）。
+     * 无当前章节时为 no-op。
+     */
+    playCurrentChapterForEdit(): Promise<void>;
+    /** 暂停 */
+    pause(): void;
+    /**
+     * 续播（当前章节）。
+     * - `continue()` / `continue({ prepare: false })`：同步 plain 续播，直接 resume 时钟，返回 `void`（既有语义不变）。
+     * - `continue({ prepare: true })`：先 `await prepareCameraTo(currentChapterTime)` 平滑 glide-back（不计时）再 resume，
+     *   返回 `Promise<void>`。展示端与编辑端均传 `prepare: true` 以保证续播无跳变（D-RESUME）。
+     */
+    continue(): void;
+    continue(options: {
+        prepare?: false;
+    }): void;
+    continue(options: {
+        prepare: true;
+    }): Promise<void>;
+    /**
+     * 编辑态暂停（playing→paused，相机由「导演」交还「用户」拥有）。
+     * 统一 Mapview 后，导演接管期间 five 始终是合法 Mapview orbit 状态，暂停瞬间画面不变、
+     * 且 five 手势天然为正常模型视角（左键绕 target orbit、右键平移），无需特殊转换。见设计 §5.3.1。
+     * 仅供编辑端（camera-mode）暂停路径调用。
+     */
+    pauseForEdit(): void;
+    /**
+     * 编辑态续播（当前章节）：在恢复时钟前先 `await prepareCameraTo(当前时间)`，
+     * 以内插动画平滑回到暂停瞬间对应的运镜视角（无突变 user→director 切换，Req 13.9 / 18.9），
+     * prepare 不计入播放时间（时钟在 prepare 期间不推进）后再 resume。
+     * 章节无运镜关键帧时 prepare 为 no-op。不改变通用 `continue()`/`pause()` 语义。
+     */
+    continueForEdit(): Promise<void>;
+    /** 运镜开关：关闭后播放仅驱动模型动画，不接管 five 相机（立即生效） */
+    setCameraDirectionEnabled(enabled: boolean): void;
+    /**
+     * 人物运动轨迹线开关（默认关闭、不显示）。仅 debug / 特殊需求由业务显式开启。
+     * 立即作用于当前所有 DigitalHuman，并记忆给后续加载的模型。
+     */
+    setTraceVisible(visible: boolean): void;
+    /**
+     * 加法式：设置「章节索引 → 楼层」映射，启用「播放/切章时 Mapview 只显示当前章节所在楼层」。
+     * - number：该章节单一楼层；null：该章节内跨楼层 → 显示全部；映射缺项按显示全部处理。
+     * - 传入非 null：立即对当前章节应用一次；此后在任意章节切换（连播推进 / 切章 / 播放预览切章）时自动应用。
+     * - 传入 null：停用该能力（不再随章节应用），但**不主动恢复**楼层可见性（恢复由 `reset()` 负责）。
+     * 楼层可见性是 five 空间模型的显隐（`five.model.show`），与运镜相机接管相互独立。
+     * 各消费方（workshop 编辑端 / NextVR 展示端）自行从各自数据算好映射注入，保证两端行为一致（parity）。
+     *
+     * @param model 楼层可见性作用的目标模型（缺省/undefined/null 回退到 `five.model`）。
+     *   单 VR 场景无需传（`five.model` 即唯一模型）；沙盘/联合现场须传动画所属子 VR 的模型
+     *   （`five.models.find(m => m.name === resourceCode)`），否则楼层隔离会落到 models[0] 而非播放中的子 VR，
+     *   导致跨楼层动画所有楼层同时高亮。传入 null 时清空目标模型回退到 `five.model`。
+     */
+    setChapterFloorMap(map: Record<number, number | null> | null, model?: {
+        show?: (floorIndex?: number) => void;
+    } | null): void;
+    /** 监听 five 'modeChange'：模态切换后（延后一帧）重放当前章节楼层，避免被外部 UI 覆盖（只挂一次） */
+    private hookFloorModeChange;
+    /** 取消 'modeChange' 楼层重放监听 */
+    private unhookFloorModeChange;
+    /** 按章节楼层映射对指定章节应用楼层可见性（映射未启用时 no-op） */
+    private applyChapterFloor;
+    /**
+     * 显示指定楼层（传 undefined 显示全部）。安全访问 model.show，避免类型/运行时缺失。
+     * 目标模型优先用消费方注入的 `chapterFloorModel`（沙盘下为播放中的子 VR），缺省回退 `five.model`。
+     */
+    private showModelFloor;
+    /**
+     * seek 预览：跳转到指定时间并渲染当前帧（不改变播放/暂停状态）。
+     * - 无当前章节：不改时钟、不渲染，返回失败指示且不抛异常。
+     * - 运镜启用：经 director seek 应用相机；运镜禁用：仅驱动 DigitalHuman。
+     */
+    setTimelineTo(time: number): SetTimelineResult;
+    /**
+     * 在指定时间捕获当前 five 相机为一个运镜关键帧。
+     * - 位姿取自 five 当前 Mapview 状态（target=offset、longitude、latitude、distance）；fov 取自 fiveState（缺省读 five.getCurrentState()）。
+     * - 按 timeStamp 升序插入；同 timeStamp 覆盖。
+     * 拒绝（保持序列不变并返回 error）：未加载 script / 无当前章节 / time 非负有限数校验失败。
+     */
+    addCameraKeyframe(time: number, fiveState?: {
+        fov?: number;
+    }, options?: CameraKeyframeOptions): CameraKeyframeResult;
+    /**
+     * 更新指定下标关键帧：合并 patch 中出现的字段，按 timeStamp 重排序。
+     * 拒绝（保持序列不变）：未加载 script / 无章节 / index 越界 / patch.timeStamp 非负有限数校验失败。
+     */
+    updateCameraKeyframe(index: number, patch: Partial<DigitalCameraKeyframe>): CameraKeyframeResult;
+    /** 移除指定下标关键帧。拒绝（保持序列不变）：未加载 script / 无章节 / index 越界。 */
+    removeCameraKeyframe(index: number): CameraKeyframeResult;
+    /** 获取当前章节的运镜关键帧（升序副本；无章节/无 camera player 时返回空数组） */
+    getCameraKeyframes(): DigitalCameraKeyframe[];
+    /**
+     * 序列化当前章节的运镜 player。
+     * keyframes 按 timeStamp 升序，仅写入已设置的可选字段（不写 undefined 占位）。
+     * 空/无 camera player 返回 keyframes:[]；未加载 script / 无章节 时拒绝并返回 error。
+     */
+    serializeCameraPlayer(): SerializeCameraResult;
+    /**
+     * 序列化全部章节中"含非空关键帧"的运镜 player，按章节索引返回。
+     * 供编辑端按"章节起始动画 id"聚合后整组保存。未加载 script 时返回空数组。
+     */
+    serializeAllCameraPlayers(): Array<{
+        chapterIndex: number;
+        player: DigitalCameraPlayer;
+    }>;
+    /**
+     * 按章节索引批量加载运镜（用于从持久化数据还原）：替换对应章节 camera player 的关键帧。
+     * 调用方负责"对账"（只传锚点命中的章节），越界索引忽略。
+     */
+    loadCameraPlayersByChapterIndex(byChapterIndex: Record<number, {
+        keyframes: DigitalCameraKeyframe[];
+        coordinateSpace?: CameraCoordinateSpace;
+        name?: string;
+    }>): void;
+    /** 注册关键帧序列变更监听（camera-keyframes-changed）；返回反订阅函数 */
+    onCameraKeyframesChanged(listener: CameraKeyframesChangedListener): () => void;
+    /**
+     * 章节默认视角（Chapter_Default_View）。始终为 **Mapview orbit** 视角（与运镜编辑「仅 Mapview」一致）。
+     * - 章节存在 ≥1 个运镜关键帧：返回该章节相机轨道 `sample(0)`（因首帧夹紧，等于首帧 CameraState）。
+     * - 章节存在 0 个运镜关键帧：几何派生一个「frame 该章节模型 t=0」的 Mapview orbit
+     *   （target=模型世界包围盒中心，distance 由包围盒尺寸派生，orbit 朝向沿用 five 当前角度以避免跳变）。
+     *   无可用模型几何时返回 `undefined`（调用方 no-op、保持当前视角）。
+     * 默认视角不单独持久化，完全派生（关键帧 / 模型几何），不在 cameraPlayers 新增字段。
+     */
+    getChapterDefaultView(chapterIndex: number): CameraState | undefined;
+    /**
+     * 应用章节默认视角到 five。
+     * - 章节存在关键帧：经 FiveModelCameraBridge 立即应用 `sample(0)`。
+     * - 章节 0 关键帧：应用几何派生的 Mapview orbit（frame 本章节模型）；无可用几何时 no-op。
+     */
+    applyChapterDefaultView(chapterIndex: number): void;
+    /**
+     * 无运镜章节的默认视角：几何派生一个「frame 该章节模型 t=0」的 Mapview orbit CameraState。
+     * - target = 章节内所有 model player 容器的世界包围盒中心（需先 prepareChapter 将模型渲染到 t=0）。
+     * - distance = 包围盒对角线 × 系数，钳制到 [MIN, MAX]（保证不过近/过远）。
+     * - orbit 朝向（longitude/latitude/fov）沿用 five 当前状态，避免切章时视角朝向突跳；缺省用兜底值。
+     * 无任何可用模型几何（未加载/无 model player/包围盒空）时返回 undefined。
+     */
+    private deriveChapterModelFramingView;
+    /**
+     * 设为当前编辑章节（不开始播放）。该次调用内联动完成：
+     * 切暂停 → `seek(0)`（进度归零、各 DigitalHuman 渲染 t=0）→ 重建 director 轨道到该章节关键帧 →
+     * 应用该章节默认视角 → 读取并更新该章节总时长 → 清除已选中运镜项 → 派发 onCurrentChapterChanged。
+     * 越界索引为 no-op。
+     */
+    setCurrentChapter(chapterIndex: number): void;
+    /** 当前章节信息：{ index, name, duration }；duration 为该章节模型动画时长（排除相机 player） */
+    getCurrentChapterInfo(): CurrentChapterInfo;
+    /** 注册当前章节变更监听（current-chapter-changed）；返回反订阅函数 */
+    onCurrentChapterChanged(listener: CurrentChapterChangedListener): () => void;
+    /**
+     * 进入运镜编辑：对全部章节运镜内存态打一次深快照（供 discardCameraChanges 还原）。
+     * 仅记录内存快照，不触碰持久化、不改相机/播放状态。
+     */
+    beginCameraEditSession(): void;
+    /**
+     * 放弃运镜修改：将运镜内存态还原到 `beginCameraEditSession` 时的快照（不走服务端重载）。
+     * 未打过快照时为 no-op。还原后重建当前章节 director 轨道并派发关键帧变更事件。
+     */
+    discardCameraChanges(): void;
+    /** 当前进度（当前章节内 currentTime/totalTime，单位 ms；含当前章节索引/总章节数） */
+    getProgress(): V2Progress;
+    /** 注册进度监听；返回反订阅函数 */
+    onProgressChanged(listener: V2ProgressListener): () => void;
+    /**
+     * 组级章节时间映射（加法式）：每章 { index, name, startTime, endTime, duration } 逐章累计。
+     * - duration[i] = getChapterPlaybackDuration(chapters[i])（排除 camera player）
+     * - startTime[0]=0、startTime[i]=endTime[i-1]、endTime[i]=startTime[i]+duration[i]
+     * - 未加载 / 空章节组返回 []；纯读，不修改任何引擎状态。
+     * 按 currentScript 引用缓存；loadScript / script 变更时失效重算。
+     */
+    getGroupChapterTimeMap(): GroupChapterTimeInfo[];
+    /**
+     * 组级进度聚合（加法式）：由章节级 getProgress() + getGroupChapterTimeMap() 派生。
+     * - groupTotalTime = Σ duration
+     * - groupCurrentTime = startTime[currentChapterIndex] + clamp(currentTime, 0, duration[idx])（无当前章节为 0）
+     * - 0 ≤ groupCurrentTime ≤ groupTotalTime；percentage ∈ [0,100]（groupTotalTime=0 时为 0）
+     * 纯读，不修改任何引擎状态。
+     */
+    getGroupProgress(): GroupProgress;
+    /**
+     * 注册组级进度监听（加法式，独立监听集合）；返回反订阅函数。
+     * 在既有 emitProgress() 内追加组级广播，每 tick / 章节切换 / pause / seek 时随章节级广播一并触发。
+     */
+    onGroupProgressChanged(listener: GroupProgressListener): () => void;
+    /**
+     * 播放/预览专用：设为当前章节（不开始播放，区别于编辑端 setCurrentChapter）。
+     * 透传 playground.prepareChapter：切模型可见性 + 重绑相机轨道 + 配置时钟时长并 seek 到 fromTime（不 start）。
+     * 不做编辑端默认视角设置 / 选中清理等联动。越界索引为 no-op。
+     */
+    setCurrentChapterForPlayback(index: number, fromTime: number): void;
+    /**
+     * 跳转到组级时间(ms)：映射为 (章节 index, 章节内时间)，必要时切章后 setTimelineTo。
+     * 保留 seek 前的播放/暂停状态（D-SEEK-LIVE，方案 A）：
+     * - 暂停态：跨章则先 setCurrentChapterForPlayback 切章，再 setTimelineTo 预览该帧后交还用户。
+     * - 播放态同章：clock.seek 续播（经 setTimelineTo）。
+     * - 播放态跨章：置 seekRedirect 并 abortCurrentPlay，由连播循环跳到目标章节从 localTime 继续。
+     * 越界钳制到 [0, groupTotalTime]；未加载 script 返回 { success:false } 不抛异常。
+     */
+    seekToGroupTime(groupTimeMs: number): SetTimelineResult;
+    /** 跳转到组级百分比 [0,100]（= seekToGroupTime(clamp(pct,0,100)/100 * groupTotalTime)） */
+    seekToGroupPercentage(percentage: number): SetTimelineResult;
+    /**
+     * 组级时间 → (章节索引, 章节内时间)（加法式内部）。
+     * - g ≤ 0          → { index: 0, localTime: 0 }
+     * - g ≥ groupTotal → { index: last, localTime: duration[last] }
+     * - 否则 startTime[index] ≤ g < endTime[index] 且 localTime = g - startTime[index]
+     * - 零时长章节（start==end）被自动跳过（不会定位其内部）
+     * 前置条件：timeMap 非空。
+     */
+    private mapGroupTimeToChapter;
+    /** 数值钳制工具 */
+    private clamp;
+    /** 当前可用章节 */
+    getChapters(): DigitalChapter[];
+    /** 当前状态快照 */
+    getState(): {
+        playing: boolean;
+        currentChapter: DigitalChapter | null;
+    };
+    /** 实时修改角色名牌；只更新文本和当前剧本，不重新加载模型/动画。 */
+    updateModelName(id: string, value: string): void;
+    private syncNameplates;
+    /** 重置播放（保留已加载资源） */
+    reset(): void;
+    /** 销毁插件、释放资源 */
+    dispose(): void;
+    /** 预加载模型 / 动画 / 道具（复用 Shared_Core 加载） */
+    private preloadResources;
+    private emitProgress;
+    /** 组级进度广播（加法式新增；独立监听集合，既有 onProgressChanged 语义不变） */
+    private emitGroupProgress;
+    /** 编辑前置校验：未加载 script / 无当前章节时返回拒绝结果，否则返回 null */
+    private guardKeyframeEdit;
+    /** 拒绝结果：保持当前序列不变并返回 error */
+    private rejectKeyframe;
+    /** 当前章节的 camera player（不存在返回 null） */
+    private getCameraPlayer;
+    /** 指定章节的 camera player（不存在返回 null） */
+    private cameraPlayerOf;
+    /** 把 camera player 的关键帧序列化为升序、仅含已设置可选字段的副本（Mapview 位姿） */
+    private serializeKeyframes;
+    /** 获取当前章节的 camera player，不存在则创建并挂到章节 players 上 */
+    private ensureCameraPlayer;
+    /** fov 取值：优先 fiveState.fov，否则读 five 当前状态 */
+    private resolveFov;
+    /** 捕获 five 当前 Mapview 位姿（target=offset、longitude、latitude、distance） */
+    private captureCameraPose;
+    /** 关键帧变更后：重建并绑定相机轨道（供 seek 预览/后续播放接管），派发事件，返回成功结果 */
+    private afterKeyframesChanged;
+    private emitKeyframesChanged;
+    private emitCurrentChapterChanged;
+    /** 当前章节索引（0-based；无当前章节为 -1），按引用或名称匹配 */
+    private getCurrentChapterIndex;
+    /** 由指定章节的相机关键帧构建一条 CameraTrack（无章节/无 camera player 返回 null） */
+    private buildChapterCameraTrack;
+    /** 深拷贝关键帧序列（数组字段亦深拷贝），供快照/还原使用（Mapview 位姿） */
+    private cloneKeyframes;
+}

package/dist/types/DigitalPerformanceV2Plugin/core/CameraDirector.d.ts

@@ -0,0 +1,61 @@
+import { Five } from '@realsee/five-webgpu';
+import { CameraTrack } from './CameraTrack.js';
+import { PerformanceClock } from './PerformanceClock.js';
+import { CameraState } from '../typings/index.js';
+/**
+ * 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/dist/types/DigitalPerformanceV2Plugin/core/CameraSampler.d.ts

@@ -0,0 +1,53 @@
+import { CameraTransition, DigitalCameraKeyframe, CameraState } from '../typings/index.js';
+import * as THREE from 'three/webgpu';
+/**
+ * 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/dist/types/DigitalPerformanceV2Plugin/core/CameraTrack.d.ts

@@ -0,0 +1,21 @@
+import { CameraState, DigitalCameraKeyframe } from '../typings/index.js';
+/**
+ * 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/dist/types/DigitalPerformanceV2Plugin/core/FiveModelCameraBridge.d.ts

@@ -0,0 +1,39 @@
+import { Five } from '@realsee/five-webgpu';
+import { CameraState } from '../typings/index.js';
+/**
+ * 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/dist/types/DigitalPerformanceV2Plugin/core/PerformanceClock.d.ts

@@ -0,0 +1,55 @@
+import { Five } from '@realsee/five-webgpu';
+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;
+}