@xmaxai/web-sdk 1.0.8 → 1.0.9

package/dist/{chunk-JGDZ3RD3.js → chunk-ILZL4W2G.js}

@@ -1,6 +1,6 @@
-var __defProp = Object.defineProperty;
-var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
-var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+import {
+  __publicField
+} from "./chunk-V6TY7KAL.js";
 
 // src/Foundation/Runtime/XmaxEnvironment.ts
 var XmaxEnvironment = /* @__PURE__ */ ((XmaxEnvironment3) => {
@@ -205,7 +205,7 @@ var XmaxError = class _XmaxError extends Error {
 };
 
 // src/Foundation/Runtime/RuntimeInfo.ts
-var XMAX_SDK_VERSION = "1.0.8";
+var XMAX_SDK_VERSION = "1.0.9";
 var _RuntimeInfo = class _RuntimeInfo {
   /**
    * 序列化为接口传输使用的 snake_case 字段。
@@ -602,6 +602,8 @@ var RealtimeModel = /* @__PURE__ */ ((RealtimeModel2) => {
   RealtimeModel2["x2_0_trtc"] = "x2.0-trtc";
   RealtimeModel2["x2_1_preview"] = "x2.1-preview";
   RealtimeModel2["x2_1_preview_1014"] = "x2.1-preview-1014";
+  RealtimeModel2["x2_1_1_preview_cn"] = "x2.1.1-preview-cn";
+  RealtimeModel2["x2_1_1_preview_us"] = "x2.1.1-preview-us";
   return RealtimeModel2;
 })(RealtimeModel || {});
 function isKnownModel(model) {
@@ -617,11 +619,15 @@ var MODEL_DISPLAY_NAMES = {
   ["x2.0" /* x2_0 */]: "X2.0",
   ["x2.0-trtc" /* x2_0_trtc */]: "X2.1-preview-trtc",
   ["x2.1-preview" /* x2_1_preview */]: "X2.1-preview-agora",
-  ["x2.1-preview-1014" /* x2_1_preview_1014 */]: "X2.1-preview-1014"
+  ["x2.1-preview-1014" /* x2_1_preview_1014 */]: "X2.1-preview-1014",
+  ["x2.1.1-preview-cn" /* x2_1_1_preview_cn */]: "X2.1.1-preview-cn",
+  ["x2.1.1-preview-us" /* x2_1_1_preview_us */]: "X2.1.1-preview-us"
 };
 var MODEL_BASE_URLS = {
   ["x2.1-preview" /* x2_1_preview */]: "https://cloud.xmax.22duck.cn/open/api/v1",
-  ["x2.1-preview-1014" /* x2_1_preview_1014 */]: "https://dev.xmaxai.com/open/api/v1"
+  ["x2.1-preview-1014" /* x2_1_preview_1014 */]: "https://dev.xmaxai.com/open/api/v1",
+  ["x2.1.1-preview-cn" /* x2_1_1_preview_cn */]: "https://cloud.xmax.22duck.cn/open/api/v1",
+  ["x2.1.1-preview-us" /* x2_1_1_preview_us */]: "https://api.xmax.ai/open/api/v1"
 };
 var RESOLUTION_BUCKETS = {
   ["x2.0" /* x2_0 */]: [],
@@ -636,13 +642,23 @@ var RESOLUTION_BUCKETS = {
   ["x2.1-preview-1014" /* x2_1_preview_1014 */]: [
     { width: 1024, height: 1920 },
     { width: 1920, height: 1024 }
+  ],
+  ["x2.1.1-preview-cn" /* x2_1_1_preview_cn */]: [
+    { width: 1024, height: 1920 },
+    { width: 1920, height: 1024 }
+  ],
+  ["x2.1.1-preview-us" /* x2_1_1_preview_us */]: [
+    { width: 1024, height: 1920 },
+    { width: 1920, height: 1024 }
   ]
 };
 var MAXIMUM_INPUT_PIXELS = {
   ["x2.0" /* x2_0 */]: 128e4,
   ["x2.0-trtc" /* x2_0_trtc */]: 21e5,
   ["x2.1-preview" /* x2_1_preview */]: 21e5,
-  ["x2.1-preview-1014" /* x2_1_preview_1014 */]: 21e5
+  ["x2.1-preview-1014" /* x2_1_preview_1014 */]: 21e5,
+  ["x2.1.1-preview-cn" /* x2_1_1_preview_cn */]: 21e5,
+  ["x2.1.1-preview-us" /* x2_1_1_preview_us */]: 21e5
 };
 function modelDisplayName(model) {
   return isKnownModel(model) ? MODEL_DISPLAY_NAMES[model] : model;
@@ -675,7 +691,9 @@ var MODEL_RTC_PROVIDERS = {
   ["x2.0" /* x2_0 */]: Object.freeze(["vertc" /* vertc */]),
   ["x2.0-trtc" /* x2_0_trtc */]: Object.freeze(["trtc" /* trtc */]),
   ["x2.1-preview" /* x2_1_preview */]: Object.freeze(["agora" /* agora */]),
-  ["x2.1-preview-1014" /* x2_1_preview_1014 */]: Object.freeze(["agora" /* agora */])
+  ["x2.1-preview-1014" /* x2_1_preview_1014 */]: Object.freeze(["agora" /* agora */]),
+  ["x2.1.1-preview-cn" /* x2_1_1_preview_cn */]: Object.freeze(["agora" /* agora */]),
+  ["x2.1.1-preview-us" /* x2_1_1_preview_us */]: Object.freeze(["agora" /* agora */])
 };
 function supportedRtcProviders(model) {
   return isKnownModel(model) ? MODEL_RTC_PROVIDERS[model] : CUSTOM_MODEL_RTC_PROVIDERS;
@@ -2133,6 +2151,12 @@ var _AgoraRtcManager = class _AgoraRtcManager {
     if (volume > 0 && this.requestedAudio.has(String(user.uid))) track.play();
     else track.stop();
   }
+  /**
+   * 获取原始远端音轨，不依赖声网音频播放器是否处于播放状态。
+   */
+  getRemoteAudioTrack(userID) {
+    return this.client?.remoteUsers.find((user) => String(user.uid) === userID)?.audioTrack?.getMediaStreamTrack();
+  }
   /**
    * 按房间顺序发送消息，限制每秒包数与总字节；失败返回给原业务调用。
    */
@@ -3031,6 +3055,15 @@ var TrtcRtcManager = class {
   get supportsRemoteAudioVolumeControl() {
     return canControlTrtcRemoteAudioVolume();
   }
+  /**
+   * 获取原始远端音轨；不支持独立播放音量的平台暂不开放录制。
+   */
+  getRemoteAudioTrack(userID) {
+    if (!canControlTrtcRemoteAudioVolume()) {
+      throw new XmaxError("MEDIA_ERROR" /* mediaError */, "TRTC recording cannot preserve remote audio while muted on this platform");
+    }
+    return this.requireEngine().getAudioTrack(userID) ?? void 0;
+  }
   /**
    * 设置指定远端用户的音频播放音量。
    *
@@ -3656,6 +3689,12 @@ var VeRtcManager = class {
     this.audioPlayers.set(userID, player);
     this.applyAudioVolume(userID);
   }
+  /**
+   * 获取原始远端音轨，独立于 audio 元素的静音和播放音量。
+   */
+  getRemoteAudioTrack(userID) {
+    return this.requireEngine().getRemoteStreamTrack(userID, this.sdk.StreamIndex.STREAM_INDEX_MAIN, "audio");
+  }
   setRemoteAudioVolume(volume, userID) {
     this.audioVolumes.set(userID, Number.isFinite(volume) ? Math.max(0, Math.min(100, Math.round(volume))) : 0);
     this.applyAudioVolume(userID);
@@ -3919,6 +3958,48 @@ function createRtcManager(provider, environment) {
   }
 }
 
+// src/Service/Realtime/RealtimeExtraParams.ts
+var RESERVED_PARAMS = /* @__PURE__ */ new Set([
+  "model",
+  "face_replace",
+  "size",
+  "target_size",
+  "prompt",
+  "ref_image_path",
+  "mirror",
+  "ref_video_path",
+  "sample_method"
+]);
+function snapshotExtraParams(params) {
+  if (params === void 0) return void 0;
+  const invalid2 = (message) => {
+    throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, message);
+  };
+  if (!params || typeof params !== "object" || Array.isArray(params)) {
+    return invalid2("extraParams must be a JSON object");
+  }
+  for (const key of Object.keys(params)) {
+    if (RESERVED_PARAMS.has(key)) return invalid2(`extraParams conflicts with SDK parameter: ${key}`);
+  }
+  const ancestors = /* @__PURE__ */ new Set();
+  const validate = (value) => {
+    if (value === null || typeof value === "string" || typeof value === "boolean") return;
+    if (typeof value === "number" && Number.isFinite(value)) return;
+    if (typeof value !== "object" || !value) return invalid2("extraParams must contain only JSON values");
+    if (ancestors.has(value)) return invalid2("extraParams must not contain circular references");
+    const prototype = Object.getPrototypeOf(value);
+    if (!Array.isArray(value) && prototype !== Object.prototype && prototype !== null) {
+      return invalid2("extraParams must contain only JSON objects and arrays");
+    }
+    if (Object.getOwnPropertySymbols(value).length) return invalid2("extraParams must not contain symbol keys");
+    ancestors.add(value);
+    for (const child of Array.isArray(value) ? value : Object.values(value)) validate(child);
+    ancestors.delete(value);
+  };
+  validate(params);
+  return JSON.parse(JSON.stringify(params));
+}
+
 // src/Foundation/Media/Camera/CameraFrameValidator.ts
 var CAMERA_WARMUP_MS = 200;
 function waitForValidCameraFrame(track, signal) {
@@ -4413,121 +4494,26 @@ var _CameraController = class _CameraController {
 __publicField(_CameraController, "localVideoTrackID", "video0");
 var CameraController = _CameraController;
 
-// src/Service/Realtime/RealtimeReferenceVideo.ts
-var RealtimeVideoSampleMethod = /* @__PURE__ */ ((RealtimeVideoSampleMethod2) => {
-  RealtimeVideoSampleMethod2["time"] = "time";
-  RealtimeVideoSampleMethod2["fps"] = "fps";
-  return RealtimeVideoSampleMethod2;
-})(RealtimeVideoSampleMethod || {});
-
-// src/Media/Video/NetworkVideoController.ts
-var NetworkVideoController = class {
-  constructor() {
-    /**
-     * 当前视频源与完成通知
-     */
-    __publicField(this, "currentTrack");
-    __publicField(this, "reference");
-    __publicField(this, "onFinish");
-    /**
-     * 预览进度与视图资源
-     */
-    __publicField(this, "position", 0);
-    __publicField(this, "ended", false);
-    __publicField(this, "bindings", /* @__PURE__ */ new Map());
-  }
-  /**
-   * 创建网络视频源，校验地址、采样方式和模型支持的尺寸；不请求视频下载。
-   */
-  create(options, mediaService) {
-    let url;
-    try {
-      url = new URL(options.url);
-    } catch {
-      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Network video requires an absolute HTTP or HTTPS URL");
-    }
-    if (!["http:", "https:"].includes(url.protocol) || !url.hostname || url.username || url.password) {
-      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Network video requires an HTTP or HTTPS URL without embedded credentials");
-    }
-    const sampleMethod = options.sampleMethod ?? "time" /* time */;
-    if (!Object.values(RealtimeVideoSampleMethod).includes(sampleMethod)) {
-      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Unsupported video sample method");
-    }
-    if (this.currentTrack) {
-      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Close the current network video stream before creating another one");
-    }
-    options.videoFormat.validate();
-    const size = mediaService.resolveModelInputSize(options.videoFormat);
-    const track = new RealtimeVideoTrack({
-      id: "network-video",
-      videoFormat: options.videoFormat.resized(size.width, size.height)
-    });
-    this.currentTrack = track;
-    this.reference = Object.freeze({ path: options.url.trim(), sampleMethod });
-    this.onFinish = options.onFinish;
-    VideoRenderRegistry.register(track, {
-      attachHandler: (view) => this.attach(view),
-      detachHandler: (view) => this.detach(view)
-    });
-    return new RealtimeMediaStream({ id: "stream0" /* local */, videoTrack: track });
-  }
-  /**
-   * 释放全部预览绑定及源信息，不影响其他媒体源。
-   */
-  stop() {
-    for (const view of this.bindings.keys()) {
-      this.detach(view);
-    }
-    if (this.currentTrack) {
-      VideoRenderRegistry.unregister(this.currentTrack);
-    }
-    this.currentTrack = void 0;
-    this.reference = void 0;
-    this.onFinish = void 0;
-    this.position = 0;
-    this.ended = false;
-  }
-  /**
-   * 绑定播放器，恢复预览位置；本地播放错误仅记录，不中断服务端生成。
-   */
-  attach(view) {
-    if (!this.reference || !view.videoElement || !view.setVideoURL) {
-      throw new XmaxError("MEDIA_ERROR" /* mediaError */, "This render target does not support network video preview");
-    }
-    this.detach(view);
-    const video = view.videoElement;
-    video.autoplay = !this.ended;
-    const restore = () => {
-      if (this.position > 0) {
-        video.currentTime = Math.min(this.position, Math.max(0, video.duration - 1e-3) || this.position);
-      }
-      if (this.ended) {
-        video.pause();
+// src/Media/LocalMediaVideoFormat.ts
+function resolveLocalMediaVideoFormat(format, mediaService) {
+  format.validate();
+  const buckets = resolutionBuckets(mediaService.model);
+  let target = buckets.find((size2) => size2.width === format.width && size2.height === format.height);
+  if (!target && buckets.length > 0) {
+    const ratio = format.width / format.height;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    for (const bucket of buckets) {
+      const distance = Math.abs(Math.log(bucket.width / bucket.height / ratio));
+      const tied = Math.abs(distance - bestDistance) < 1e-9;
+      if (distance < bestDistance - 1e-9 || tied && bucket.width >= bucket.height && target && target.width < target.height) {
+        target = bucket;
+        bestDistance = distance;
       }
-    };
-    const fail = () => {
-      XmaxLogger.render.warning(() => "\u7F51\u7EDC\u89C6\u9891\u9884\u89C8\u5931\u8D25 (Network Video Preview Failed)");
-    };
-    video.addEventListener("loadedmetadata", restore);
-    video.addEventListener("error", fail);
-    this.bindings.set(view, () => {
-      this.position = video.currentTime;
-      this.ended = video.ended || this.ended;
-      video.removeEventListener("loadedmetadata", restore);
-      video.removeEventListener("error", fail);
-      view.setVideoURL?.(null);
-    });
-    view.isMirrored = false;
-    view.setVideoURL(this.reference.path);
-  }
-  /**
-   * 保存预览进度并释放该视图的地址和事件监听。
-   */
-  detach(view) {
-    this.bindings.get(view)?.();
-    this.bindings.delete(view);
+    }
   }
-};
+  const size = mediaService.resolveModelInputSize(target ?? format);
+  return format.resized(size.width, size.height);
+}
 
 // src/Media/Video/LocalVideoController.ts
 var LocalVideoController = class {
@@ -4571,7 +4557,7 @@ var LocalVideoController = class {
     if (!(options.file instanceof Blob) || options.file.size === 0) {
       throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Local video requires a non-empty File or Blob");
     }
-    const format = this.resolveVideoFormat(options.videoFormat, mediaService);
+    const format = resolveLocalMediaVideoFormat(options.videoFormat, mediaService);
     if (signal.aborted) {
       throw this.cancelled();
     }
@@ -4798,29 +4784,6 @@ var LocalVideoController = class {
     context.fillRect(0, 0, canvas.width, canvas.height);
     context.drawImage(video, (canvas.width - width) / 2, (canvas.height - height) / 2, width, height);
   }
-  /**
-   * 仅为本地文件选择最接近宽高比的模型档位；比例距离相同时优先横屏。
-   * 无固定档位时保留公共尺寸解析规则，帧率和显式编码配置不变。
-   */
-  resolveVideoFormat(format, mediaService) {
-    format.validate();
-    const buckets = resolutionBuckets(mediaService.model);
-    let target = buckets.find((size2) => size2.width === format.width && size2.height === format.height);
-    if (!target && buckets.length > 0) {
-      const ratio = format.width / format.height;
-      let bestDistance = Number.POSITIVE_INFINITY;
-      for (const bucket of buckets) {
-        const distance = Math.abs(Math.log(bucket.width / bucket.height / ratio));
-        const tied = Math.abs(distance - bestDistance) < 1e-9;
-        if (distance < bestDistance - 1e-9 || tied && bucket.width >= bucket.height && target && target.width < target.height) {
-          target = bucket;
-          bestDistance = distance;
-        }
-      }
-    }
-    const size = mediaService.resolveModelInputSize(target ?? format);
-    return format.resized(size.width, size.height);
-  }
   /**
    * 解码或绘制失败时停止媒体推进，并报告一次运行期错误。
    */
@@ -4842,59 +4805,1271 @@ var LocalVideoController = class {
   }
 };
 
-// src/Media/Video/ExternalVideoController.ts
-var ExternalVideoController = class {
-  constructor(onError) {
-    __publicField(this, "onError", onError);
-    __publicField(this, "track");
-    __publicField(this, "onEnded", () => {
-      this.onError(new XmaxError("MEDIA_ERROR" /* mediaError */, "External video source ended"));
-    });
-  }
-  get currentTrack() {
-    return this.track;
+// src/Service/Realtime/RealtimeReferenceVideo.ts
+var RealtimeVideoSampleMethod = /* @__PURE__ */ ((RealtimeVideoSampleMethod2) => {
+  RealtimeVideoSampleMethod2["time"] = "time";
+  RealtimeVideoSampleMethod2["fps"] = "fps";
+  return RealtimeVideoSampleMethod2;
+})(RealtimeVideoSampleMethod || {});
+
+// src/Media/Video/NetworkVideoController.ts
+var NetworkVideoController = class {
+  constructor() {
+    /**
+     * 当前视频源与完成通知
+     */
+    __publicField(this, "currentTrack");
+    __publicField(this, "reference");
+    __publicField(this, "onFinish");
+    /**
+     * 预览进度与视图资源
+     */
+    __publicField(this, "position", 0);
+    __publicField(this, "ended", false);
+    __publicField(this, "bindings", /* @__PURE__ */ new Map());
   }
+  /**
+   * 创建网络视频源，校验地址、采样方式和模型支持的尺寸；不请求视频下载。
+   */
   create(options, mediaService) {
-    if (this.track) throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Close the current external video first");
-    const { videoTrack, videoFormat } = options;
-    if (!videoTrack || videoTrack.kind !== "video" || videoTrack.readyState !== "live" || typeof videoTrack.clone !== "function") {
-      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "External video requires a live video MediaStreamTrack");
+    let url;
+    try {
+      url = new URL(options.url);
+    } catch {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Network video requires an absolute HTTP or HTTPS URL");
     }
-    videoFormat.validate();
-    const size = mediaService.resolveModelInputSize(videoFormat);
-    const format = videoFormat.resized(size.width, size.height);
-    const nativeTrack = videoTrack.clone();
-    if (nativeTrack.readyState !== "live") {
-      nativeTrack.stop();
-      throw new XmaxError("MEDIA_ERROR" /* mediaError */, "External video source ended during setup");
+    if (!["http:", "https:"].includes(url.protocol) || !url.hostname || url.username || url.password) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Network video requires an HTTP or HTTPS URL without embedded credentials");
     }
-    const track = new RealtimeVideoTrack({ id: "external-video", videoFormat: format });
-    track.mediaStreamTrack = nativeTrack;
-    nativeTrack.addEventListener("ended", this.onEnded);
-    this.track = track;
+    const sampleMethod = options.sampleMethod ?? "time" /* time */;
+    if (!Object.values(RealtimeVideoSampleMethod).includes(sampleMethod)) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Unsupported video sample method");
+    }
+    if (this.currentTrack) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Close the current network video stream before creating another one");
+    }
+    options.videoFormat.validate();
+    const size = mediaService.resolveModelInputSize(options.videoFormat);
+    const track = new RealtimeVideoTrack({
+      id: "network-video",
+      videoFormat: options.videoFormat.resized(size.width, size.height)
+    });
+    this.currentTrack = track;
+    this.reference = Object.freeze({ path: options.url.trim(), sampleMethod });
+    this.onFinish = options.onFinish;
+    VideoRenderRegistry.register(track, {
+      attachHandler: (view) => this.attach(view),
+      detachHandler: (view) => this.detach(view)
+    });
     return new RealtimeMediaStream({ id: "stream0" /* local */, videoTrack: track });
   }
+  /**
+   * 释放全部预览绑定及源信息，不影响其他媒体源。
+   */
   stop() {
-    const nativeTrack = this.track?.mediaStreamTrack;
-    this.track = void 0;
-    nativeTrack?.removeEventListener("ended", this.onEnded);
-    nativeTrack?.stop();
+    for (const view of this.bindings.keys()) {
+      this.detach(view);
+    }
+    if (this.currentTrack) {
+      VideoRenderRegistry.unregister(this.currentTrack);
+    }
+    this.currentTrack = void 0;
+    this.reference = void 0;
+    this.onFinish = void 0;
+    this.position = 0;
+    this.ended = false;
   }
-};
-
-// src/Service/Realtime/RealtimeContext.ts
-var RealtimeContext = class {
   /**
-   * 创建实时生成条件并规范化文本和参考路径。
+   * 绑定播放器，恢复预览位置；本地播放错误仅记录，不中断服务端生成。
    */
-  constructor(init) {
-    /**
-     * 服务端直接读取的网络视频。
-     */
-    __publicField(this, "referenceVideo");
-    /**
-     * 生成条件
-     */
+  attach(view) {
+    if (!this.reference || !view.videoElement || !view.setVideoURL) {
+      throw new XmaxError("MEDIA_ERROR" /* mediaError */, "This render target does not support network video preview");
+    }
+    this.detach(view);
+    const video = view.videoElement;
+    video.autoplay = !this.ended;
+    const restore = () => {
+      if (this.position > 0) {
+        video.currentTime = Math.min(this.position, Math.max(0, video.duration - 1e-3) || this.position);
+      }
+      if (this.ended) {
+        video.pause();
+      }
+    };
+    const fail = () => {
+      XmaxLogger.render.warning(() => "\u7F51\u7EDC\u89C6\u9891\u9884\u89C8\u5931\u8D25 (Network Video Preview Failed)");
+    };
+    video.addEventListener("loadedmetadata", restore);
+    video.addEventListener("error", fail);
+    this.bindings.set(view, () => {
+      this.position = video.currentTime;
+      this.ended = video.ended || this.ended;
+      video.removeEventListener("loadedmetadata", restore);
+      video.removeEventListener("error", fail);
+      view.setVideoURL?.(null);
+    });
+    view.isMirrored = false;
+    view.setVideoURL(this.reference.path);
+  }
+  /**
+   * 保存预览进度并释放该视图的地址和事件监听。
+   */
+  detach(view) {
+    this.bindings.get(view)?.();
+    this.bindings.delete(view);
+  }
+};
+
+// src/Media/Video/ExternalVideoController.ts
+var ExternalVideoController = class {
+  constructor(onError) {
+    __publicField(this, "onError", onError);
+    __publicField(this, "track");
+    __publicField(this, "onEnded", () => {
+      this.onError(new XmaxError("MEDIA_ERROR" /* mediaError */, "External video source ended"));
+    });
+  }
+  get currentTrack() {
+    return this.track;
+  }
+  create(options, mediaService) {
+    if (this.track) throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Close the current external video first");
+    const { videoTrack, videoFormat } = options;
+    if (!videoTrack || videoTrack.kind !== "video" || videoTrack.readyState !== "live" || typeof videoTrack.clone !== "function") {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "External video requires a live video MediaStreamTrack");
+    }
+    videoFormat.validate();
+    const size = mediaService.resolveModelInputSize(videoFormat);
+    const format = videoFormat.resized(size.width, size.height);
+    const nativeTrack = videoTrack.clone();
+    if (nativeTrack.readyState !== "live") {
+      nativeTrack.stop();
+      throw new XmaxError("MEDIA_ERROR" /* mediaError */, "External video source ended during setup");
+    }
+    const track = new RealtimeVideoTrack({ id: "external-video", videoFormat: format });
+    track.mediaStreamTrack = nativeTrack;
+    nativeTrack.addEventListener("ended", this.onEnded);
+    this.track = track;
+    return new RealtimeMediaStream({ id: "stream0" /* local */, videoTrack: track });
+  }
+  stop() {
+    const nativeTrack = this.track?.mediaStreamTrack;
+    this.track = void 0;
+    nativeTrack?.removeEventListener("ended", this.onEnded);
+    nativeTrack?.stop();
+  }
+};
+
+// src/Media/Image/LocalImageController.ts
+var LocalImageController = class {
+  /**
+   * 注入运行期错误通知，不创建浏览器资源。
+   */
+  constructor(onError) {
+    __publicField(this, "onError", onError);
+    /**
+     * 当前图片源，包含尚未完成的解码操作。
+     */
+    __publicField(this, "source");
+  }
+  /**
+   * 是否持有正在准备或可用的图片源。
+   */
+  get isActive() {
+    return this.source !== void 0;
+  }
+  /**
+   * 已准备的本地图片视频轨。
+   */
+  get currentTrack() {
+    return this.source?.track;
+  }
+  /**
+   * 解码图片、准备静止画面并持续输出帧；取消或失败时释放本次资源。
+   */
+  async create(options, mediaService, signal) {
+    if (this.source) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Close the current local image before creating another one");
+    }
+    if (!(options.file instanceof Blob) || options.file.size === 0) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Local image requires a non-empty File or Blob");
+    }
+    const format = resolveLocalMediaVideoFormat(options.videoFormat, mediaService);
+    if (signal.aborted) {
+      throw this.cancelled();
+    }
+    if (typeof document === "undefined") {
+      throw new XmaxError("MEDIA_ERROR" /* mediaError */, "Local image requires a browser");
+    }
+    const image = document.createElement("img");
+    const canvas = document.createElement("canvas");
+    const context = canvas.getContext("2d");
+    if (!context || typeof canvas.captureStream !== "function") {
+      throw new XmaxError("MEDIA_ERROR" /* mediaError */, "Canvas video capture is unavailable");
+    }
+    canvas.width = format.width;
+    canvas.height = format.height;
+    const source = {
+      image,
+      canvas,
+      url: URL.createObjectURL(options.file),
+      abort: new AbortController(),
+      targets: /* @__PURE__ */ new Set()
+    };
+    this.source = source;
+    try {
+      await this.load(source, signal);
+      if (signal.aborted || this.source !== source) {
+        throw this.cancelled();
+      }
+      if (!image.naturalWidth || !image.naturalHeight) {
+        throw new XmaxError("MEDIA_ERROR" /* mediaError */, "The image has no valid dimensions");
+      }
+      const scale = Math.min(canvas.width / image.naturalWidth, canvas.height / image.naturalHeight);
+      const width = image.naturalWidth * scale;
+      const height = image.naturalHeight * scale;
+      context.fillStyle = "black";
+      context.fillRect(0, 0, canvas.width, canvas.height);
+      context.drawImage(image, (canvas.width - width) / 2, (canvas.height - height) / 2, width, height);
+      source.stream = canvas.captureStream(format.fps);
+      const nativeTrack = source.stream.getVideoTracks()[0];
+      if (!nativeTrack || nativeTrack.readyState !== "live") {
+        throw new XmaxError("MEDIA_ERROR" /* mediaError */, "Canvas did not provide a live video track");
+      }
+      const track = new RealtimeVideoTrack({ id: "local-image", videoFormat: format });
+      track.mediaStreamTrack = nativeTrack;
+      source.track = track;
+      const refresh = () => {
+        context.drawImage(canvas, 0, 0);
+        if (typeof nativeTrack.requestFrame === "function") {
+          nativeTrack.requestFrame();
+        }
+      };
+      refresh();
+      source.timer = setInterval(() => {
+        if (this.source !== source) {
+          return;
+        }
+        try {
+          refresh();
+        } catch {
+          this.handleError(source);
+        }
+      }, 1e3 / format.fps);
+      source.onEnded = () => this.handleError(source);
+      nativeTrack.addEventListener("ended", source.onEnded);
+      VideoRenderRegistry.register(track, {
+        attachHandler: (view) => {
+          if (this.source !== source) {
+            return;
+          }
+          view.isMirrored = false;
+          view.setMediaStream(source.stream);
+          source.targets.add(view);
+        },
+        detachHandler: (view) => {
+          source.targets.delete(view);
+          view.setMediaStream(null);
+        }
+      });
+      return new RealtimeMediaStream({ id: "stream0" /* local */, videoTrack: track });
+    } catch (error) {
+      if (this.source === source) {
+        this.stop();
+      }
+      throw XmaxError.from(error);
+    }
+  }
+  /**
+   * 取消解码、清空预览并释放视频轨、定时器和对象 URL。
+   */
+  stop() {
+    const source = this.source;
+    this.source = void 0;
+    if (!source) {
+      return;
+    }
+    source.abort.abort();
+    clearInterval(source.timer);
+    if (source.track) {
+      VideoRenderRegistry.unregister(source.track);
+      if (source.onEnded) {
+        source.track.mediaStreamTrack?.removeEventListener("ended", source.onEnded);
+      }
+      source.track.mediaStreamTrack = void 0;
+    }
+    for (const view of source.targets) {
+      try {
+        view.setMediaStream(null);
+      } catch {
+      }
+    }
+    source.targets.clear();
+    source.stream?.getTracks().forEach((track) => track.stop());
+    source.image.removeAttribute("src");
+    URL.revokeObjectURL(source.url);
+    source.canvas.width = 0;
+    source.canvas.height = 0;
+  }
+  /**
+   * 等待浏览器完成图片解码，支持主动停止、操作取消和超时。
+   */
+  load(source, signal) {
+    return new Promise((resolve, reject) => {
+      const finish = (error) => {
+        clearTimeout(timer);
+        source.image.removeEventListener("load", loaded);
+        source.image.removeEventListener("error", failed);
+        signal.removeEventListener("abort", aborted);
+        source.abort.signal.removeEventListener("abort", aborted);
+        if (error) {
+          reject(error);
+        } else {
+          resolve();
+        }
+      };
+      const loaded = () => finish();
+      const failed = () => finish(new XmaxError("MEDIA_ERROR" /* mediaError */, "The browser cannot decode this image file"));
+      const aborted = () => finish(this.cancelled());
+      const timer = setTimeout(() => finish(new XmaxError("TIMEOUT" /* timeout */, "Local image preparation timed out")), 1e4);
+      source.image.addEventListener("load", loaded, { once: true });
+      source.image.addEventListener("error", failed, { once: true });
+      signal.addEventListener("abort", aborted, { once: true });
+      source.abort.signal.addEventListener("abort", aborted, { once: true });
+      if (signal.aborted || source.abort.signal.aborted) {
+        aborted();
+      } else {
+        source.image.src = source.url;
+      }
+    });
+  }
+  /**
+   * 输出失效时停止刷新并仅报告一次，资源由业务生命周期统一释放。
+   */
+  handleError(source) {
+    if (this.source !== source || source.timer === void 0) {
+      return;
+    }
+    clearInterval(source.timer);
+    source.timer = void 0;
+    this.onError(new XmaxError("MEDIA_ERROR" /* mediaError */, "Local image video output failed"));
+  }
+  /**
+   * 构造统一的图片操作取消错误。
+   */
+  cancelled() {
+    return new XmaxError("CANCELLED" /* cancelled */, "Local image operation was cancelled");
+  }
+};
+
+// src/Foundation/Media/Video/VideoContentMode.ts
+var VideoContentMode = /* @__PURE__ */ ((VideoContentMode2) => {
+  VideoContentMode2["fit"] = "fit";
+  VideoContentMode2["fill"] = "fill";
+  return VideoContentMode2;
+})(VideoContentMode || {});
+
+// src/Service/Realtime/RealtimePoint.ts
+var RealtimePoint = class {
+  /**
+   * 创建模型输入像素坐标点。
+   *
+   * @param init.x 模型输入像素横坐标。
+   * @param init.y 模型输入像素纵坐标。
+   */
+  constructor(init) {
+    /**
+     * 坐标
+     */
+    /**
+     * 模型输入像素横坐标。
+     */
+    __publicField(this, "x");
+    /**
+     * 模型输入像素纵坐标。
+     */
+    __publicField(this, "y");
+    this.x = init.x;
+    this.y = init.y;
+  }
+};
+
+// src/Media/Interaction/InteractionCoordinateMapper.ts
+var InteractionCoordinateMapper = class {
+  /**
+   * 计算居中显示的视频矩形；fill 允许矩形超出视口，fit 留出黑边。
+   */
+  static displayedFrame(viewport, video, mode) {
+    if (![viewport.width, viewport.height, video.width, video.height].every((value) => Number.isFinite(value) && value > 0)) {
+      return void 0;
+    }
+    const scale = (mode === "fill" /* fill */ ? Math.max : Math.min)(viewport.width / video.width, viewport.height / video.height);
+    const width = video.width * scale;
+    const height = video.height * scale;
+    return { x: (viewport.width - width) / 2, y: (viewport.height - height) / 2, width, height };
+  }
+  /**
+   * 忽略黑边和无效点，撤销显示镜像后取整并限制在模型输入范围内。
+   */
+  static map(point, frame, video) {
+    const rect = this.displayedFrame(frame.viewportSize, video, frame.contentMode);
+    if (!rect || !Number.isFinite(point.x) || !Number.isFinite(point.y)) {
+      return void 0;
+    }
+    if (frame.contentMode === "fit" /* fit */ && (point.x < rect.x || point.x > rect.x + rect.width || point.y < rect.y || point.y > rect.y + rect.height)) {
+      return void 0;
+    }
+    const x = (point.x - rect.x) / rect.width;
+    const y = (point.y - rect.y) / rect.height;
+    return new RealtimePoint({
+      x: Math.min(video.width - 1, Math.max(0, Math.round((frame.mirrored ? 1 - x : x) * video.width))),
+      y: Math.min(video.height - 1, Math.max(0, Math.round(y * video.height)))
+    });
+  }
+};
+
+// src/Media/Interaction/InteractionController.ts
+var InteractionController = class {
+  /**
+   * 注入发送能力，不持有房间或具体 RTC。
+   */
+  constructor(listener) {
+    __publicField(this, "listener", listener);
+    /**
+     * 活动任务与待发送采样；上下文对象身份隔离任务切换。
+     */
+    __publicField(this, "active");
+    __publicField(this, "pending");
+    __publicField(this, "draining");
+  }
+  /**
+   * 激活或更新任务输入格式，清除旧采样。
+   */
+  startInteraction(taskID, videoFormat) {
+    this.stopInteraction();
+    if (taskID) {
+      this.active = { taskID, videoFormat };
+    }
+  }
+  /**
+   * 立即使交互上下文失效；已提交给 RTC 的消息无法撤回。
+   */
+  stopInteraction() {
+    this.active = void 0;
+    this.pending = void 0;
+    this.draining = void 0;
+  }
+  /**
+   * 同步转换数据，发送忙时用最新采样覆盖旧采样，避免弱网积压。
+   */
+  submitInteraction(frame) {
+    const context = this.active;
+    if (!context) {
+      return;
+    }
+    const points = frame.points.flatMap((point) => {
+      const mapped = InteractionCoordinateMapper.map(point, frame, context.videoFormat);
+      return mapped ? [mapped] : [];
+    });
+    if (!points.length) {
+      return;
+    }
+    this.pending = { context, points };
+    if (this.draining !== context) {
+      void this.drain(context);
+    }
+  }
+  /**
+   * 顺序发送；失败只丢弃当前帧，不终止生成或阻止后续交互。
+   */
+  async drain(context) {
+    this.draining = context;
+    try {
+      while (this.active === context && this.pending?.context === context) {
+        const { points } = this.pending;
+        this.pending = void 0;
+        try {
+          await this.listener(context.taskID, points);
+        } catch {
+          if (context === this.active) {
+            XmaxLogger.interaction.warning(() => "\u53D1\u9001\u4EA4\u4E92\u8F68\u8FF9\u5931\u8D25\uFF0C\u5DF2\u4E22\u5F03\u5F53\u524D\u91C7\u6837\u5E27 (Interaction Sample Dropped)");
+          }
+        }
+      }
+    } finally {
+      if (this.draining === context) {
+        this.draining = void 0;
+      }
+    }
+  }
+};
+
+// src/Media/MediaController.ts
+var MediaController = class {
+  /**
+   * 注入基础能力与错误、交互输出，不自行创建跨层业务组件。
+   */
+  constructor(dependencies) {
+    __publicField(this, "dependencies", dependencies);
+    /**
+     * 本地媒体与交互组件
+     */
+    __publicField(this, "camera");
+    __publicField(this, "video");
+    __publicField(this, "image");
+    __publicField(this, "network", new NetworkVideoController());
+    __publicField(this, "external");
+    __publicField(this, "interaction");
+    this.camera = dependencies.cameraController ?? new CameraController({
+      rtcManager: dependencies.rtcManager,
+      mediaService: dependencies.mediaService,
+      errorListener: dependencies.onCameraError
+    });
+    this.video = new LocalVideoController(dependencies.onVideoError);
+    this.image = new LocalImageController(dependencies.onImageError);
+    this.external = new ExternalVideoController(dependencies.onExternalError);
+    this.interaction = new InteractionController(dependencies.interactionListener);
+  }
+  /**
+   * 当前可发布的轨道。
+   */
+  get uplinkTrack() {
+    return this.external.currentTrack ?? this.video.currentTrack ?? this.image.currentTrack ?? this.camera.currentTrack;
+  }
+  /**
+   * 当前本地源轨道，包含无上行的网络视频。
+   */
+  get currentTrack() {
+    return this.uplinkTrack ?? this.network.currentTrack;
+  }
+  /**
+   * 从实际资源推导来源，不维护另一份媒体状态。
+   */
+  get source() {
+    if (this.external.currentTrack) {
+      return "externalVideo";
+    }
+    if (this.video.isActive) {
+      return "localVideo";
+    }
+    if (this.image.isActive) {
+      return "localImage";
+    }
+    if (this.network.currentTrack) {
+      return "networkVideo";
+    }
+    if (this.camera.currentTrack) {
+      return "camera";
+    }
+    return void 0;
+  }
+  /**
+   * 当前源需要发布的音频能力。
+   */
+  get hasAudio() {
+    return this.video.isActive ? !!this.video.audioTrack : this.source === "camera" && this.camera.useMicrophone;
+  }
+  /**
+   * 非相机源不等待相机预热。
+   */
+  get isFrameValidationEnabled() {
+    return this.source === "camera" && this.camera.isFrameValidationEnabled;
+  }
+  /**
+   * 网络视频的服务端读取参数。
+   */
+  get referenceVideo() {
+    return this.network.reference;
+  }
+  /**
+   * 网络视频完成回调。
+   */
+  get onNetworkVideoFinish() {
+    return this.network.onFinish;
+  }
+  /**
+   * 创建前拒绝覆盖活动源或尚未完成的文件准备。
+   */
+  ensureNoLocalSource() {
+    if (this.currentTrack || this.video.isActive || this.image.isActive) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Close the current local stream before creating another one");
+    }
+  }
+  /**
+   * 保持现有外部轨道能力校验与错误语义。
+   */
+  validateExternalMediaSupport(kind) {
+    if (!this.dependencies.rtcManager.setExternalMediaTracks) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, `The RTC provider does not support ${kind} video streams`);
+    }
+  }
+  /**
+   * 创建相机流，由相机组件管理 RTC 和预览。
+   */
+  createLocalCameraStream(options) {
+    this.ensureNoLocalSource();
+    return this.camera.createLocalCameraStream(options);
+  }
+  /**
+   * 同步准备网络视频源；地址校验失败不初始化 RTC。
+   */
+  createNetworkVideoStream(options) {
+    this.ensureNoLocalSource();
+    return this.network.create(options, this.dependencies.mediaService);
+  }
+  /**
+   * 先解锁用户触发的播放，再由 prepareSource 初始化 RTC。
+   */
+  createLocalVideoStream(options, signal) {
+    this.ensureNoLocalSource();
+    return this.video.create(options, this.dependencies.mediaService, signal);
+  }
+  /**
+   * 解码本地图片并准备静止视频轨，不申请设备权限。
+   */
+  createLocalImageStream(options, signal) {
+    this.ensureNoLocalSource();
+    return this.image.create(options, this.dependencies.mediaService, signal);
+  }
+  /**
+   * 接管外部视频轨副本，不停止调用方原始轨道。
+   */
+  createExternalVideoStream(options) {
+    this.ensureNoLocalSource();
+    return this.external.create(options, this.dependencies.mediaService);
+  }
+  /**
+   * 初始化 RTC 并绑定非相机轨道；取消后不继续安装轨道。
+   */
+  async prepareSource(ensureCurrent) {
+    const rtc = this.dependencies.rtcManager;
+    await rtc.initialize();
+    ensureCurrent();
+    const track = this.external.currentTrack ?? this.video.currentTrack ?? this.image.currentTrack;
+    if (track?.mediaStreamTrack) {
+      await rtc.setExternalMediaTracks({ videoTrack: track.mediaStreamTrack, audioTrack: this.video.audioTrack });
+      ensureCurrent();
+    }
+  }
+  /**
+   * 设置相机预览就绪通知。
+   */
+  setCameraPreviewReadyHandler(handler) {
+    this.camera.setPreviewReadyHandler(handler);
+  }
+  /**
+   * 等待相机预热。
+   */
+  waitForValidCameraFrame(signal) {
+    return this.camera.waitForValidCameraFrame(signal);
+  }
+  /**
+   * 切换相机；外部采集不由 SDK 控制。
+   */
+  switchCamera() {
+    if (this.external.currentTrack) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "External video capture is managed by the caller");
+    }
+    return this.camera.switchCamera();
+  }
+  /**
+   * 停止相机资源。
+   */
+  stopLocalCameraStream() {
+    return this.camera.stopLocalCameraStream();
+  }
+  /**
+   * 生成开始后启动文件播放。
+   */
+  startLocalVideo(signal) {
+    return this.video.start(signal);
+  }
+  /**
+   * 断开时保留文件预览资源但暂停时间线。
+   */
+  pauseLocalVideo() {
+    this.video.pause();
+  }
+  /**
+   * 释放当前源，RTC 销毁失败也释放外部轨和解码器。
+   */
+  async stopLocalStream() {
+    this.stopInteraction();
+    const external = this.source !== void 0 && this.source !== "camera";
+    this.network.stop();
+    try {
+      if (external) {
+        await this.dependencies.rtcManager.destroy();
+      } else {
+        await this.camera.stopLocalCameraStream();
+      }
+    } finally {
+      this.external.stop();
+      if (this.image.isActive) {
+        this.image.stop();
+      }
+      if (this.video.isActive) {
+        await this.video.stop();
+      }
+    }
+  }
+  /**
+   * 使用生成格式启用交互，不读取弱网调档后的上行规格。
+   */
+  startInteraction(taskID, format) {
+    this.interaction.startInteraction(taskID, format);
+  }
+  /**
+   * 结束任务时立即清除待发采样。
+   */
+  stopInteraction() {
+    this.interaction.stopInteraction();
+  }
+  /**
+   * 接收渲染层快照并交给坐标与发送队列处理。
+   */
+  submitInteraction(frame) {
+    this.interaction.submitInteraction(frame);
+  }
+};
+
+// src/Service/Realtime/RealtimeRecordingEvent.ts
+var RealtimeRecordingEventType = /* @__PURE__ */ ((RealtimeRecordingEventType2) => {
+  RealtimeRecordingEventType2["completed"] = "completed";
+  RealtimeRecordingEventType2["interrupted"] = "interrupted";
+  RealtimeRecordingEventType2["failed"] = "failed";
+  return RealtimeRecordingEventType2;
+})(RealtimeRecordingEventType || {});
+var RealtimeRecordingFinishReason = /* @__PURE__ */ ((RealtimeRecordingFinishReason2) => {
+  RealtimeRecordingFinishReason2["durationLimit"] = "durationLimit";
+  RealtimeRecordingFinishReason2["generationEnded"] = "generationEnded";
+  RealtimeRecordingFinishReason2["restarted"] = "restarted";
+  RealtimeRecordingFinishReason2["mediaInterrupted"] = "mediaInterrupted";
+  return RealtimeRecordingFinishReason2;
+})(RealtimeRecordingFinishReason || {});
+
+// src/Media/Recording/RecordingController.ts
+var _RecordingController = class _RecordingController {
+  constructor() {
+    /**
+     * 任务资源与结果监听
+     */
+    __publicField(this, "session");
+    __publicField(this, "listener");
+  }
+  /**
+   * 设置统一结果监听器；传入 undefined 清除，不停止正在进行的录制。
+   */
+  setListener(listener) {
+    this.listener = listener;
+  }
+  /**
+   * 开始准备当前任务的录制；准备和录制失败只通过独立事件通知。
+   */
+  start(taskID, readTracks) {
+    if (this.session && !this.session.finished) {
+      void this.stop("restarted" /* restarted */);
+    }
+    try {
+      const tracks = readTracks();
+      if (!tracks || tracks.videoTrack.readyState === "ended") {
+        throw new XmaxError("MEDIA_ERROR" /* mediaError */, "Remote video is unavailable for recording");
+      }
+      if (typeof MediaRecorder === "undefined" || typeof AudioContext === "undefined") {
+        throw new XmaxError("MEDIA_ERROR" /* mediaError */, "Audio/video recording is not supported by this browser");
+      }
+      let resolve;
+      const completion = new Promise((done) => {
+        resolve = done;
+      });
+      const session = {
+        taskID,
+        readTracks,
+        videoTrack: tracks.videoTrack,
+        chunks: [],
+        bytes: 0,
+        hasAudio: false,
+        stopping: false,
+        finished: false,
+        reason: "durationLimit" /* durationLimit */,
+        completion,
+        resolve
+      };
+      this.session = session;
+      session.timer = setTimeout(() => {
+        this.fail(session, new XmaxError("TIMEOUT" /* timeout */, "Timed out preparing remote recording"));
+      }, _RecordingController.preparationTimeoutMs);
+      void this.prepare(session).catch((error) => this.fail(session, XmaxError.from(error)));
+    } catch (error) {
+      this.reportFailure(taskID, XmaxError.from(error));
+    }
+  }
+  /**
+   * 请求收尾并等待最终数据；重复停止共享完成结果，且绝不停止 RTC 原始轨道。
+   */
+  stop(reason) {
+    const session = this.session;
+    if (!session) {
+      return Promise.resolve();
+    }
+    this.stopSession(session, reason);
+    return session.completion;
+  }
+  /**
+   * 不支持的录制请求使用同一错误出口，不改变生成生命周期。
+   */
+  reportFailure(taskID, error) {
+    this.emit({ type: "failed" /* failed */, taskID, error });
+  }
+  /**
+   * 使用固定音频输出轨处理晚到的音频；不在 MediaRecorder 运行中增删轨道。
+   */
+  async prepare(session) {
+    const context = new AudioContext();
+    session.audioContext = context;
+    session.audioDestination = context.createMediaStreamDestination();
+    const silence = context.createConstantSource();
+    silence.offset.value = 0;
+    silence.connect(session.audioDestination);
+    silence.start();
+    session.silenceSource = silence;
+    await context.resume();
+    if (session.stopping || session.finished) {
+      return;
+    }
+    if (context.state !== "running") {
+      throw new XmaxError("MEDIA_ERROR" /* mediaError */, "Browser did not allow recording audio to start");
+    }
+    this.updateAudio(session);
+    const video = document.createElement("video");
+    session.video = video;
+    video.muted = true;
+    video.playsInline = true;
+    video.srcObject = new MediaStream([session.videoTrack]);
+    const ready = () => {
+      if (!session.stopping && !session.finished && video.readyState >= 2) {
+        this.beginRecording(session);
+      }
+    };
+    if (typeof video.requestVideoFrameCallback === "function") {
+      session.frameCallback = video.requestVideoFrameCallback(ready);
+    } else {
+      video.onloadeddata = ready;
+      video.onplaying = ready;
+    }
+    video.onerror = () => this.fail(session, new XmaxError("MEDIA_ERROR" /* mediaError */, "Cannot read remote recording video"));
+    try {
+      await video.play();
+    } catch (error) {
+      if (!session.recorder && !session.stopping && !session.finished) {
+        throw error;
+      }
+    }
+    if (typeof video.requestVideoFrameCallback !== "function") {
+      ready();
+    }
+  }
+  /**
+   * 首帧可用后启动单个音视频录制器，计时不包含连接和媒体准备阶段。
+   */
+  beginRecording(session) {
+    if (session.recorder || session.stopping || session.finished) {
+      return;
+    }
+    try {
+      session.hasAudio = false;
+      this.updateAudio(session);
+      const stream = new MediaStream([session.videoTrack, ...session.audioDestination.stream.getAudioTracks()]);
+      const mimeType = ["video/mp4;codecs=avc1,mp4a.40.2", "video/webm;codecs=vp8,opus", "video/mp4", "video/webm"].find((type) => MediaRecorder.isTypeSupported(type));
+      if (!mimeType) {
+        throw new XmaxError("MEDIA_ERROR" /* mediaError */, "No supported audio/video recording format");
+      }
+      const recorder = new MediaRecorder(stream, { mimeType, videoBitsPerSecond: 6e6, audioBitsPerSecond: 128e3 });
+      session.recorder = recorder;
+      recorder.ondataavailable = (event) => {
+        if (session.finished || session.error || !event.data.size) {
+          return;
+        }
+        if (session.bytes + event.data.size > _RecordingController.maximumBytes) {
+          this.fail(session, new XmaxError("MEDIA_ERROR" /* mediaError */, "Recording exceeded the memory limit"));
+          return;
+        }
+        session.chunks.push(event.data);
+        session.bytes += event.data.size;
+      };
+      recorder.onerror = () => {
+        this.fail(session, new XmaxError("MEDIA_ERROR" /* mediaError */, "Remote recording encoder failed"));
+      };
+      recorder.onstop = () => {
+        if (!session.stopping) {
+          session.reason = "mediaInterrupted" /* mediaInterrupted */;
+        }
+        this.finish(session);
+      };
+      recorder.start(1e3);
+      clearTimeout(session.timer);
+      session.timer = setTimeout(() => this.stopSession(session, "durationLimit" /* durationLimit */), _RecordingController.durationMs);
+      session.monitor = setInterval(() => {
+        try {
+          const tracks = session.readTracks();
+          if (!tracks || tracks.videoTrack !== session.videoTrack || session.videoTrack.readyState === "ended") {
+            this.stopSession(session, "mediaInterrupted" /* mediaInterrupted */);
+          } else if (session.audioContext?.state !== "running") {
+            this.fail(session, new XmaxError("MEDIA_ERROR" /* mediaError */, "Recording audio context was suspended"));
+          } else {
+            this.updateAudio(session);
+          }
+        } catch (error) {
+          this.fail(session, XmaxError.from(error));
+        }
+      }, 100);
+      this.releaseVideoProbe(session);
+    } catch (error) {
+      this.fail(session, XmaxError.from(error));
+    }
+  }
+  /**
+   * 轮询仅在录制期间运行；接入原始音频，不连接扬声器，不受播放音量影响。
+   */
+  updateAudio(session) {
+    const track = session.readTracks()?.audioTrack;
+    const liveTrack = track?.readyState === "live" ? track : void 0;
+    if (liveTrack !== session.audioTrack) {
+      session.audioSource?.disconnect();
+      session.audioSource = void 0;
+      session.audioTrack = liveTrack;
+      if (liveTrack) {
+        session.audioSource = session.audioContext.createMediaStreamSource(new MediaStream([liveTrack]));
+        session.audioSource.connect(session.audioDestination);
+      }
+    }
+    if (liveTrack && !liveTrack.muted && liveTrack.enabled) {
+      session.hasAudio = true;
+    }
+  }
+  /**
+   * 标记失败并尽力停止编码；任何错误都不能冒泡到实时生成。
+   */
+  fail(session, error) {
+    if (session.finished) {
+      return;
+    }
+    session.error ?? (session.error = error);
+    this.stopSession(session, "mediaInterrupted" /* mediaInterrupted */);
+  }
+  /**
+   * 保留最后一个 dataavailable，等待 stop 后再封装；异常路径有收尾超时保护。
+   */
+  stopSession(session, reason) {
+    if (session.stopping || session.finished) {
+      return;
+    }
+    session.stopping = true;
+    session.reason = reason;
+    clearTimeout(session.timer);
+    clearInterval(session.monitor);
+    this.releaseVideoProbe(session);
+    if (!session.recorder || session.recorder.state === "inactive") {
+      this.finish(session);
+      return;
+    }
+    session.finalizationTimer = setTimeout(() => {
+      session.error ?? (session.error = new XmaxError("TIMEOUT" /* timeout */, "Timed out finalizing remote recording"));
+      this.finish(session);
+    }, _RecordingController.finalizationTimeoutMs);
+    try {
+      session.recorder.stop();
+    } catch (error) {
+      session.error ?? (session.error = XmaxError.from(error));
+      this.finish(session);
+    }
+  }
+  /**
+   * 一次性交付结果并释放所有自有资源，不保留文件副本。
+   */
+  finish(session) {
+    if (session.finished) {
+      return;
+    }
+    session.finished = true;
+    clearTimeout(session.timer);
+    clearTimeout(session.finalizationTimer);
+    clearInterval(session.monitor);
+    this.releaseVideoProbe(session);
+    const blob = new Blob(session.chunks, { type: session.recorder?.mimeType ?? session.chunks[0]?.type });
+    session.chunks = [];
+    session.audioSource?.disconnect();
+    session.silenceSource?.stop();
+    session.silenceSource?.disconnect();
+    session.audioDestination?.stream.getTracks().forEach((track) => track.stop());
+    if (session.audioContext && session.audioContext.state !== "closed") {
+      void session.audioContext.close().catch(() => {
+      });
+    }
+    if (session.recorder) {
+      session.recorder.ondataavailable = null;
+      session.recorder.onerror = null;
+      session.recorder.onstop = null;
+    }
+    if (this.session === session) {
+      this.session = void 0;
+    }
+    if (session.error || !blob.size) {
+      this.reportFailure(session.taskID, session.error ?? new XmaxError("MEDIA_ERROR" /* mediaError */, "Recording ended without usable media"));
+    } else {
+      void this.deliverResult(session.taskID, blob, session.hasAudio, session.reason);
+    }
+    session.resolve();
+  }
+  /**
+   * 按需加载后处理，成功后回调；处理失败仍交付原文件，不丢失已完成的录像。
+   */
+  async deliverResult(taskID, original, hasAudio, reason) {
+    let blob = original;
+    try {
+      const { RecordingProcessor } = await import("./RecordingProcessor-ZSBJFF4J.js");
+      blob = await new RecordingProcessor().process(original);
+    } catch (error) {
+      XmaxLogger.realtime.warning(() => `Recording gap removal failed; keeping original clip: ${XmaxError.from(error).message}`);
+    }
+    this.emit({
+      type: reason === "durationLimit" /* durationLimit */ ? "completed" /* completed */ : "interrupted" /* interrupted */,
+      taskID,
+      result: { blob, hasAudio, reason }
+    });
+  }
+  /**
+   * 释放首帧探测元素；srcObject 原始轨道不调用 stop。
+   */
+  releaseVideoProbe(session) {
+    const video = session.video;
+    if (!video) {
+      return;
+    }
+    if (session.frameCallback !== void 0) {
+      video.cancelVideoFrameCallback(session.frameCallback);
+    }
+    video.onloadeddata = null;
+    video.onplaying = null;
+    video.onerror = null;
+    video.pause();
+    video.srcObject = null;
+    session.video = void 0;
+  }
+  /**
+   * 隔离接入方监听器异常，包括异步监听器的 Promise 拒绝。
+   */
+  emit(event) {
+    try {
+      void Promise.resolve(this.listener?.(event)).catch(() => {
+        XmaxLogger.realtime.warning(() => "Recording listener rejected");
+      });
+    } catch {
+      XmaxLogger.realtime.warning(() => "Recording listener threw an error");
+    }
+  }
+};
+/**
+ * 录制资源上限
+ */
+__publicField(_RecordingController, "durationMs", 2e4);
+__publicField(_RecordingController, "maximumBytes", 64 * 1024 * 1024);
+__publicField(_RecordingController, "preparationTimeoutMs", 1e4);
+__publicField(_RecordingController, "finalizationTimeoutMs", 5e3);
+var RecordingController = _RecordingController;
+
+// src/Render/Trajectory/TrajectoryBinding.ts
+var TrajectoryBinding = class {
+  /**
+   * 注入采样回调及模型输入格式，不引用 Media Controller 实例。
+   */
+  constructor(listener, format) {
+    __publicField(this, "listener", listener);
+    __publicField(this, "format", format);
+    /**
+     * 绑定视图与可用性
+     */
+    __publicField(this, "overlay");
+    __publicField(this, "enabled", false);
+    __publicField(this, "valid", true);
+  }
+  /**
+   * 一个远端绑定只由一个交互视图持有，迁移时取消旧视图的触点。
+   */
+  attach(overlay) {
+    if (!this.valid) {
+      return;
+    }
+    if (this.overlay !== overlay) {
+      this.overlay?.setBinding(void 0);
+    }
+    this.overlay = overlay;
+    overlay.setBinding(this, this.format, this.enabled);
+  }
+  /**
+   * 只解除当前所有者，旧视图迟到的 detach 不影响新视图。
+   */
+  detach(overlay) {
+    if (this.overlay === overlay) {
+      this.overlay = void 0;
+      overlay.setBinding(void 0);
+    }
+  }
+  /**
+   * 开始、更新或结束任务时同步交互能力，并取消旧手势。
+   */
+  update(enabled, format = this.format) {
+    this.enabled = enabled;
+    this.format = format;
+    this.overlay?.setBinding(this, format, enabled);
+  }
+  /**
+   * 转发当前视图采样；注销或停用后忽略。
+   */
+  submit(frame) {
+    if (this.valid && this.enabled) {
+      this.listener(frame);
+    }
+  }
+  /**
+   * 注销绑定并释放视图交互资源，不允许旧引用重新挂载。
+   */
+  invalidate() {
+    this.valid = false;
+    this.overlay?.setBinding(void 0);
+    this.overlay = void 0;
+  }
+};
+
+// src/Render/Trajectory/TrajectoryRegistry.ts
+var TrajectoryRegistry = class {
+  /**
+   * 替换绑定前先使旧绑定失效。
+   */
+  static register(track, binding) {
+    this.unregister(track);
+    this.bindings.set(track, binding);
+  }
+  /**
+   * 查询交互能力，本地轨道不注册该能力。
+   */
+  static binding(track) {
+    return this.bindings.get(track);
+  }
+  /**
+   * 主动清理视图资源，不能仅依赖 WeakMap 垃圾回收。
+   */
+  static unregister(track) {
+    this.bindings.get(track)?.invalidate();
+    this.bindings.delete(track);
+  }
+};
+__publicField(TrajectoryRegistry, "bindings", /* @__PURE__ */ new WeakMap());
+
+// src/Render/RenderController.ts
+var RenderController = class {
+  /**
+   * 注入显示生命周期通知，不持有 Core 对象。
+   */
+  constructor(callbacks = {}) {
+    __publicField(this, "callbacks", callbacks);
+    /**
+     * 当前轨道与唯一渲染目标
+     */
+    __publicField(this, "track");
+    __publicField(this, "target");
+    __publicField(this, "interactionEnabled", false);
+  }
+  /**
+   * 注册新轨道并使旧绑定失效；本地轨道不经过该入口。
+   */
+  registerRemoteTrack(track, listener) {
+    this.resetRemoteTrack();
+    this.track = track;
+    if (track.videoFormat) {
+      TrajectoryRegistry.register(track, new TrajectoryBinding(listener, track.videoFormat));
+    }
+    VideoRenderRegistry.register(track, {
+      frameDisplayHandler: () => {
+        if (this.track === track) {
+          this.callbacks.onFrameDisplayed?.();
+        }
+      },
+      attachHandler: (view) => {
+        if (this.track !== track) {
+          return;
+        }
+        this.target?.setFrameInterpolation?.(void 0);
+        view.isMirrored = false;
+        this.target = view;
+        this.callbacks.onAttached?.();
+        view.setMediaStream(track.mediaStreamTrack ? new MediaStream([track.mediaStreamTrack]) : null);
+      },
+      detachHandler: (view) => {
+        if (this.target === view) {
+          this.callbacks.onDetached?.();
+          this.target = void 0;
+        }
+        view.setFrameInterpolation?.(void 0);
+        view.setMediaStream(null);
+      }
+    });
+  }
+  /**
+   * 更新媒体画面；暂停显示时同时禁用交互。
+   */
+  setRemoteMedia(track) {
+    if (this.track) {
+      TrajectoryRegistry.binding(this.track)?.update(!!track && this.interactionEnabled);
+    }
+    this.target?.setMediaStream(track ? new MediaStream([track]) : null);
+  }
+  /**
+   * 转交插帧配置，不重建交互视图。
+   */
+  setFrameInterpolation(options) {
+    this.target?.setFrameInterpolation?.(options);
+  }
+  /**
+   * 更新交互绑定的输入格式和可用性。
+   */
+  setInteractionEnabled(enabled, format) {
+    this.interactionEnabled = enabled;
+    if (this.track) {
+      TrajectoryRegistry.binding(this.track)?.update(enabled, format);
+    }
+  }
+  /**
+   * 先使能力失效再清空画面，迟到首帧和旧手势不能恢复已结束任务。
+   */
+  resetRemoteTrack() {
+    const track = this.track;
+    this.track = void 0;
+    this.interactionEnabled = false;
+    if (track) {
+      TrajectoryRegistry.unregister(track);
+      VideoRenderRegistry.unregister(track);
+    }
+    this.target?.setFrameInterpolation?.(void 0);
+    this.target?.setMediaStream(null);
+    this.target = void 0;
+  }
+};
+
+// src/Service/Realtime/RealtimeContext.ts
+var RealtimeContext = class {
+  /**
+   * 创建实时生成条件并规范化文本和参考路径。
+   */
+  constructor(init) {
+    /**
+     * 服务端直接读取的网络视频。
+     */
+    __publicField(this, "referenceVideo");
+    /**
+     * 生成条件
+     */
     /**
      * 实时生成使用的文本条件。
      */
@@ -5425,6 +6600,16 @@ var RemoteStream = class {
 var RoomEvent = class _RoomEvent {
   /**
    * 生成开始信令。
+   *
+   * @param options.userID 业务用户标识。
+   * @param options.taskID 当前生成任务标识。
+   * @param options.videoFormat 模型生成使用的视频规格。
+   * @param options.context 本次生成条件。
+   * @param options.targetSize 回传尺寸，缺省时不发送；网络视频默认使用生成尺寸。
+   * @param options.mirror 是否由后端镜像输入画面，默认 false。
+   * @param options.faceRestoration 是否回贴原始人脸，默认 false。
+   * @param options.extraParams 已校验的本次扩展参数，合并到 params。
+   * @returns 序列化后的 start 房间消息。
    */
   static start(options) {
     return _RoomEvent.encode({
@@ -5448,6 +6633,15 @@ var RoomEvent = class _RoomEvent {
   }
   /**
    * 生成条件变更信令。
+   *
+   * @param options.userID 业务用户标识。
+   * @param options.taskID 当前生成任务标识。
+   * @param options.videoFormat 模型生成使用的视频规格。
+   * @param options.context 本次生成条件。
+   * @param options.targetSize 回传尺寸，缺省时不发送。
+   * @param options.faceRestoration 是否回贴原始人脸，默认 false。
+   * @param options.extraParams 已校验的本次扩展参数，合并到 params。
+   * @returns 序列化后的 change_condition 房间消息。
    */
   static changeCondition(options) {
     return _RoomEvent.encode({
@@ -5504,7 +6698,10 @@ var RoomEvent = class _RoomEvent {
     });
   }
   /**
-   * 生成条件参数：模型、生成尺寸、回传尺寸、文本与参考图路径。
+   * 组装生成条件参数，包含人脸回贴配置及本次扩展参数。
+   *
+   * @param options 本次生成条件类信令的参数。
+   * @returns start 与 change_condition 共用的 params 字段。
    */
   static generationParameters(options) {
     return {
@@ -5516,7 +6713,8 @@ var RoomEvent = class _RoomEvent {
         Math.round(options.targetSize.height)
       ] : void 0,
       prompt: options.context.prompt,
-      ref_image_path: options.context.referencePath
+      ref_image_path: options.context.referencePath,
+      ...options.extraParams
     };
   }
   /**
@@ -5880,46 +7078,50 @@ var RoomController = class {
   /**
    * 发送生成开始信令。
    *
-   * @param options.faceRestoration 是否回贴原始人脸，默认 false。
-   * @param options.mirror 是否由后端镜像输入画面，默认 false。
    * @param options.taskID 当前生成任务标识。
    * @param options.videoFormat 模型生成使用的视频规格。
-   * @param options.targetSize 服务端生成后的回传尺寸，缺省使用生成尺寸。
    * @param options.context 本次生成条件。
+   * @param options.targetSize 回传尺寸，缺省时不发送；网络视频默认使用生成尺寸。
+   * @param options.mirror 是否由后端镜像输入画面，默认 false。
+   * @param options.faceRestoration 是否回贴原始人脸，默认 false。
+   * @param options.extraParams 合并到本次 start 的 params，不缓存。
    * @throws 房间未就绪或信令发送失败时抛出错误。
    */
   startGeneration(options) {
     return this.send(
       RoomEvent.start({
-        mirror: options.mirror ?? false,
-        faceRestoration: options.faceRestoration ?? false,
         userID: this.requireUserID(),
         taskID: options.taskID,
         videoFormat: options.videoFormat,
+        context: options.context,
         targetSize: options.targetSize,
-        context: options.context
+        mirror: options.mirror ?? false,
+        faceRestoration: options.faceRestoration ?? false,
+        extraParams: options.extraParams
       })
     );
   }
   /**
    * 发送生成条件变更信令。
    *
-   * @param options.faceRestoration 是否回贴原始人脸，默认 false。
    * @param options.taskID 当前生成任务标识。
    * @param options.videoFormat 模型生成使用的视频规格。
-   * @param options.targetSize 服务端生成后的回传尺寸。
    * @param options.context 本次生成条件。
+   * @param options.targetSize 服务端生成后的回传尺寸，缺省时不发送。
+   * @param options.faceRestoration 是否回贴原始人脸，默认 false。
+   * @param options.extraParams 合并到本次 change_condition 的 params，不缓存。
    * @throws 房间未就绪或信令发送失败时抛出错误。
    */
   changeGenerationCondition(options) {
     return this.send(
       RoomEvent.changeCondition({
-        faceRestoration: options.faceRestoration ?? false,
         userID: this.requireUserID(),
         taskID: options.taskID,
         videoFormat: options.videoFormat,
+        context: options.context,
         targetSize: options.targetSize,
-        context: options.context
+        faceRestoration: options.faceRestoration ?? false,
+        extraParams: options.extraParams
       })
     );
   }
@@ -6316,6 +7518,17 @@ var StreamController = class {
   get hasGenerationTask() {
     return this.state.generationTaskID !== void 0;
   }
+  /**
+   * 按活动结果流身份读取原始音视频，避免录制房间内其他用户的媒体。
+   */
+  getRemoteRecordingTracks() {
+    const userID = this.state.activeRemoteStream?.userID;
+    const videoTrack = userID && this.state.remoteVideoTracks.get(userID);
+    if (!userID || !videoTrack) {
+      return void 0;
+    }
+    return { videoTrack, audioTrack: this.rtcManager.getRemoteAudioTrack(userID) };
+  }
   /**
    * 设置本地主视频流统计监听器，不改变 RTC 事件监听权。
    */
@@ -6397,8 +7610,17 @@ var StreamController = class {
   /**
    * 建立生成任务并发送开始信令。
    *
+   * @param options.taskID 当前生成任务标识。
+   * @param options.videoFormat 模型生成使用的视频规格。
+   * @param options.context 本次生成条件。
+   * @param options.restart 是否保留连接并替换当前生成任务，默认 false；不预先发送 stop。
+   * @param options.targetSize 回传尺寸，缺省时不发送；网络视频默认使用生成尺寸。
+   * @param options.mirror 是否由后端镜像输入画面，默认 false。
+   * @param options.faceRestoration 是否回贴原始人脸，默认 false。
+   * @param options.onStartSent start 发送成功后的回调，不等待生成确认。
+   * @param options.extraParams 合并到本次 start 的 params，不缓存。
    * @returns 等待远端结果流确认的 Promise。
-   * @throws 任务标识无效、RTC 房间未就绪或已有生成任务时同步抛错；
+   * @throws 任务标识无效、RTC 房间未就绪、旧任务仍在启动或未指定 restart 且已有生成任务时同步抛错；
    * 发送失败或确认超时通过返回的 Promise 拒绝。
    */
   beginGeneration(options) {
@@ -6412,7 +7634,7 @@ var StreamController = class {
     if (!this.state.roomID) {
       throw new XmaxError("RTC_ERROR" /* rtcError */, "RTC room is not configured");
     }
-    if (this.state.generationTaskID) {
+    if (this.state.generationTaskID && (!options.restart || this.state.generationWaiter)) {
       throw new XmaxError(
         "RTC_ERROR" /* rtcError */,
         "Realtime generation is already active"
@@ -6447,11 +7669,12 @@ var StreamController = class {
     try {
       const sending = this.roomController.startGeneration({
         taskID,
-        mirror: options.mirror ?? false,
-        faceRestoration: options.faceRestoration ?? false,
         videoFormat: options.videoFormat,
+        context: options.context,
         targetSize: options.targetSize,
-        context: options.context
+        mirror: options.mirror ?? false,
+        faceRestoration: options.faceRestoration ?? false,
+        extraParams: options.extraParams
       });
       const state2 = this.state;
       const sent = Promise.resolve(sending).then(async () => {
@@ -6503,16 +7726,26 @@ var StreamController = class {
   /**
    * 发送生成条件变更信令。
    *
+   * @param options.taskID 当前生成任务标识。
+   * @param options.videoFormat 模型生成使用的视频规格。
+   * @param options.context 本次生成条件。
+   * @param options.restart 本次条件更新不使用该字段。
+   * @param options.targetSize 回传尺寸，缺省时不发送。
+   * @param options.mirror 本次条件更新不使用该字段。
+   * @param options.faceRestoration 是否回贴原始人脸，默认 false。
+   * @param options.onStartSent 本次条件更新不调用该回调。
+   * @param options.extraParams 合并到本次 change_condition 的 params，不缓存。
    * @throws RTC 房间未就绪或条件变更信令发送失败时抛出错误。
    */
   async updateGeneration(options) {
     try {
       await this.roomController.changeGenerationCondition({
         taskID: options.taskID,
-        faceRestoration: options.faceRestoration ?? false,
         videoFormat: options.videoFormat,
+        context: options.context,
         targetSize: options.targetSize,
-        context: options.context
+        faceRestoration: options.faceRestoration ?? false,
+        extraParams: options.extraParams
       });
     } catch (error) {
       throw XmaxError.from(error);
@@ -7106,8 +8339,9 @@ function qualityVideoFormat(baseline, level) {
 
 // src/Stream/Quality/QualityHistory.ts
 var QualityHistory = class {
-  constructor(model) {
+  constructor(model, provider) {
     __publicField(this, "model", model);
+    __publicField(this, "provider", provider);
   }
   /** 无记录、损坏、SSR 或浏览器禁止存储时使用默认 L2。 */
   read(direction) {
@@ -7127,7 +8361,7 @@ var QualityHistory = class {
     }
   }
   key(direction) {
-    return `xmax:quality:v1:agora:${encodeURIComponent(this.model)}:${direction}`;
+    return `xmax:quality:v1:${this.provider}:${encodeURIComponent(this.model)}:${direction}`;
   }
   isValid(level) {
     return Number.isInteger(level) && level >= 1 && level <= Object.keys(QUALITY_TIERS).length;
@@ -7676,7 +8910,6 @@ var XmaxRealtimeConnectionManager = class {
      * 远端轨道与渲染绑定
      */
     __publicField(this, "activeRemoteTrack");
-    __publicField(this, "remoteTarget");
   }
   /**
    * 当前活动会话标识；尚未连接或清理完成后为空。
@@ -7766,21 +8999,15 @@ var XmaxRealtimeConnectionManager = class {
       videoFormat: options.remoteVideoFormat ?? options.localTrack.videoFormat
     });
     this.activeRemoteTrack = remoteTrack;
-    this.registerRemoteBinding(remoteTrack);
+    this.dependencies.renderController.registerRemoteTrack(remoteTrack, this.dependencies.onInteraction);
     streamController.setRemoteAudioVolume(this.dependencies.remoteAudioVolume());
     return new RealtimeMediaStream({ id: "stream1" /* remote */, videoTrack: remoteTrack });
   }
-  /**
-   * 更新已绑定远端视图的插帧配置；传 undefined 停用插帧。
-   */
-  setFrameInterpolation(options) {
-    this.remoteTarget?.setFrameInterpolation?.(options);
-  }
   /**
    * 清空远端视图的媒体流，保留轨道与视图绑定以供统一清理。
    */
   clearRemoteMedia() {
-    this.remoteTarget?.setMediaStream(null);
+    this.dependencies.renderController.setRemoteMedia(null);
   }
   /**
    * 停止会话心跳；未配置会话服务时不执行操作。
@@ -7860,7 +9087,7 @@ var XmaxRealtimeConnectionManager = class {
       if (track) {
         track.mediaStreamTrack = void 0;
       }
-      this.remoteTarget?.setMediaStream(null);
+      this.dependencies.renderController.setRemoteMedia(null);
       return;
     }
     if (!track) {
@@ -7870,35 +9097,7 @@ var XmaxRealtimeConnectionManager = class {
       );
     }
     track.mediaStreamTrack = binding.videoTrack;
-    this.remoteTarget?.setMediaStream(new MediaStream([binding.videoTrack]));
-  }
-  /**
-   * 为远端轨道注册渲染绑定：attach 时挂流占位，媒体轨到达后送入画面。
-   */
-  registerRemoteBinding(track) {
-    VideoRenderRegistry.register(track, {
-      frameDisplayHandler: () => {
-        if (this.activeRemoteTrack === track) {
-          this.dependencies.onFrameDisplayed();
-        }
-      },
-      attachHandler: (view) => {
-        this.remoteTarget?.setFrameInterpolation?.(void 0);
-        view.isMirrored = false;
-        this.remoteTarget = view;
-        this.dependencies.onRenderAttached();
-        const mediaTrack = track.mediaStreamTrack;
-        view.setMediaStream(mediaTrack ? new MediaStream([mediaTrack]) : null);
-      },
-      detachHandler: (view) => {
-        if (this.remoteTarget === view) {
-          this.dependencies.onRenderDetached();
-          this.remoteTarget = void 0;
-        }
-        view.setFrameInterpolation?.(void 0);
-        view.setMediaStream(null);
-      }
-    });
+    this.dependencies.renderController.setRemoteMedia(binding.videoTrack);
   }
   /**
    * 构造当前远端生成结果媒体流。
@@ -7971,12 +9170,11 @@ var XmaxRealtimeConnectionManager = class {
     }
     const track = this.activeRemoteTrack;
     if (track) {
-      VideoRenderRegistry.unregister(track);
+      this.dependencies.renderController.resetRemoteTrack();
       track.mediaStreamTrack = void 0;
     }
     this.activeSession = void 0;
     this.activeRemoteTrack = void 0;
-    this.remoteTarget = void 0;
     if (sessionID && this.dependencies.sessionService) {
       try {
         await this.dependencies.sessionService.closeSession(sessionID);
@@ -8006,8 +9204,10 @@ var XmaxRealtimeGenerationManager = class _XmaxRealtimeGenerationManager {
   /**
    * 注入房间传输组件和任务标识生成器，不创建会话或启动生成。
    */
-  constructor(streamController, taskIDGenerator = _XmaxRealtimeGenerationManager.createTaskID) {
+  constructor(streamController, interactionController, renderController, taskIDGenerator = _XmaxRealtimeGenerationManager.createTaskID) {
     __publicField(this, "streamController", streamController);
+    __publicField(this, "interactionController", interactionController);
+    __publicField(this, "renderController", renderController);
     __publicField(this, "taskIDGenerator", taskIDGenerator);
     /**
      * 当前生成条件与任务标识
@@ -8033,37 +9233,50 @@ var XmaxRealtimeGenerationManager = class _XmaxRealtimeGenerationManager {
    * 发送生成指令并等待确认、远端就绪和音频激活，成功后返回任务标识。
    * 条件上下文在生成确认后缓存；启动失败时尽力停止本次任务并保留原始错误。
    * @param options.videoFormat 模型生成使用的视频规格。
-   * @param options.targetSize 服务端生成后的回传尺寸，缺省使用生成尺寸。
-   * @param options.context 生成条件，缺省复用最近缓存的上下文。
-   * @param options.faceRestoration 是否回贴原始人脸，默认 false。
-   * @param options.mirror 是否由后端水平翻转输入，默认 false；仅用于 start 信令。
    * @param options.signal 取消本次生成启动的信号。
    * @param options.ensureCurrent 校验当前操作仍有效。
    * @param options.waitUntilRemoteReady 等待远端生成流就绪。
+   * @param options.context 生成条件，缺省复用最近缓存的上下文。
+   * @param options.restart 是否替换当前任务并重新发送 start，默认 false；不发送 stop。
+   * @param options.targetSize 服务端生成后的回传尺寸，缺省时不发送。
+   * @param options.mirror 是否由后端水平翻转输入，默认 false；仅用于 start 信令。
+   * @param options.faceRestoration 是否回贴原始人脸，默认 false。
    * @param options.onStartSent start 信令发送成功后的可选异步回调。
+   * @param options.onRemoteReady 远端视频就绪后通知任务标识，不等待录制等附加功能。
+   * @param options.extraParams 合并到本次 start 的 params，不缓存。
    */
   async start(options) {
     const context = this.validateContext(options.context);
     options.ensureCurrent();
     const taskID = this.taskIDGenerator();
+    if (options.restart) {
+      this.interactionController.stopInteraction();
+      this.renderController.setInteractionEnabled(false);
+    }
     this.activeTaskID = taskID;
     try {
       const confirmation = this.streamController.beginGeneration({
         taskID,
         videoFormat: options.videoFormat,
         context,
+        restart: options.restart,
         ...options.targetSize && { targetSize: options.targetSize },
         mirror: options.mirror ?? false,
         faceRestoration: options.faceRestoration ?? false,
-        ...options.onStartSent && { onStartSent: options.onStartSent }
+        ...options.onStartSent && { onStartSent: options.onStartSent },
+        extraParams: options.extraParams
       });
       await this.awaitConfirmation(confirmation, options.signal);
       options.ensureCurrent();
       this.currentContext = context;
       await options.waitUntilRemoteReady();
       options.ensureCurrent();
+      options.onRemoteReady?.(taskID);
+      options.ensureCurrent();
       await this.streamController.activateRemoteAudio();
       options.ensureCurrent();
+      this.interactionController.startInteraction(taskID, options.videoFormat);
+      this.renderController.setInteractionEnabled(true, options.videoFormat);
       return taskID;
     } catch (error) {
       await this.stop(taskID);
@@ -8074,9 +9287,10 @@ var XmaxRealtimeGenerationManager = class _XmaxRealtimeGenerationManager {
    * 更新活动任务的生成条件；信令发送成功后才覆盖缓存，无任务或上下文时抛错。
    * @param taskID 当前活动任务标识。
    * @param options.videoFormat 模型生成使用的视频规格。
-   * @param options.targetSize 服务端生成后的回传尺寸。
    * @param options.context 生成条件，缺省复用最近缓存的上下文。
+   * @param options.targetSize 服务端生成后的回传尺寸，缺省时不发送。
    * @param options.faceRestoration 是否回贴原始人脸，默认 false。
+   * @param options.extraParams 合并到本次 change_condition 的 params，不缓存。
    */
   async update(taskID, options) {
     const context = options.context ?? this.currentContext;
@@ -8087,11 +9301,14 @@ var XmaxRealtimeGenerationManager = class _XmaxRealtimeGenerationManager {
       taskID,
       videoFormat: options.videoFormat,
       context,
+      ...options.targetSize && { targetSize: options.targetSize },
       faceRestoration: options.faceRestoration ?? false,
-      ...options.targetSize && { targetSize: options.targetSize }
+      extraParams: options.extraParams
     });
     if (this.activeTaskID !== taskID) throw RealtimeCoordinator.cancelledError();
     this.currentContext = context;
+    this.interactionController.startInteraction(taskID, options.videoFormat);
+    this.renderController.setInteractionEnabled(true, options.videoFormat);
   }
   /**
    * 幂等停止指定活动任务；并发调用共享结果，停止失败仅记录日志。
@@ -8102,6 +9319,8 @@ var XmaxRealtimeGenerationManager = class _XmaxRealtimeGenerationManager {
     }
     if (!taskID || this.activeTaskID !== taskID) return;
     this.activeTaskID = void 0;
+    this.interactionController.stopInteraction();
+    this.renderController.setInteractionEnabled(false);
     const completion = (async () => {
       try {
         await this.streamController.stopGeneration(taskID);
@@ -8122,6 +9341,8 @@ var XmaxRealtimeGenerationManager = class _XmaxRealtimeGenerationManager {
    */
   async reset(taskID) {
     this.currentContext = void 0;
+    this.interactionController.stopInteraction();
+    this.renderController.setInteractionEnabled(false);
     await this.stop(this.activeTaskID ?? (taskID || void 0));
   }
   /**
@@ -8178,6 +9399,10 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
      */
     __publicField(this, "options");
     __publicField(this, "mediaService");
+    /**
+     * 可选的任务录制；未开启时不分配浏览器录制资源。
+     */
+    __publicField(this, "recordingController", new RecordingController());
     /**
      * 本地流创建时的生成格式；上行编码调整不改变模型输入配置与远端插帧尺寸。
      */
@@ -8194,15 +9419,8 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
      */
     __publicField(this, "coordinator");
     __publicField(this, "errorHandler");
-    __publicField(this, "cameraController");
-    __publicField(this, "networkVideoController", new NetworkVideoController());
-    __publicField(this, "localVideoController", new LocalVideoController((error) => {
-      void this.coordinator.terminateWithError(error, 0 /* connection */);
-    }));
-    __publicField(this, "externalVideoController", new ExternalVideoController((error) => {
-      void this.coordinator.terminateWithError(error, 1 /* all */);
-    }));
-    __publicField(this, "rtcManager");
+    __publicField(this, "mediaController");
+    __publicField(this, "renderController");
     /**
      * 启动计时与首帧通知
      */
@@ -8247,14 +9465,6 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
     this.supportsInterpolation = dependencies?.supportsFrameInterpolation ?? (async (size) => await frameInterpolationAdapter(size) !== null);
     this.errorHandler = new RealtimeErrorHandler();
     const rtcManager = dependencies?.rtcManager ?? createRtcManager(options.provider, dependencies?.environment ?? "china" /* china */);
-    this.rtcManager = rtcManager;
-    this.cameraController = dependencies?.cameraController ?? new CameraController({
-      rtcManager,
-      mediaService: this.mediaService,
-      errorListener: (error) => {
-        void this.errorHandler.report(error);
-      }
-    });
     const sessionService = dependencies?.sessionService ?? (dependencies?.apiService ? new RealtimeSessionService({ apiService: dependencies.apiService, provider: options.provider }) : void 0);
     this.streamController = dependencies?.streamController ?? new StreamController({
       rtcManager,
@@ -8265,10 +9475,38 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
         void this.errorHandler.report(error);
       },
       remoteStreamListener: (binding) => {
+        if (!binding) {
+          void this.recordingController.stop("mediaInterrupted" /* mediaInterrupted */);
+        }
         this.clearRemoteVideoStatistics();
         this.connectionManager.handleRemoteStreamBinding(binding);
       }
     });
+    this.mediaController = new MediaController({
+      rtcManager,
+      mediaService: this.mediaService,
+      cameraController: dependencies?.cameraController,
+      onCameraError: (error) => {
+        void this.errorHandler.report(error);
+      },
+      onVideoError: (error) => {
+        void this.coordinator.terminateWithError(error, 0 /* connection */);
+      },
+      onExternalError: (error) => {
+        void this.coordinator.terminateWithError(error, 1 /* all */);
+      },
+      onImageError: (error) => {
+        void this.coordinator.terminateWithError(error, 1 /* all */);
+      },
+      interactionListener: (taskID, points) => this.streamController.sendTracks(taskID, points)
+    });
+    this.renderController = new RenderController({
+      onFrameDisplayed: () => this.remoteFrameDisplayHandler?.(),
+      onAttached: () => this.applyRemoteInterpolation(),
+      onDetached: () => {
+        this.interpolationRevision++;
+      }
+    });
     this.connectionManager = new XmaxRealtimeConnectionManager({
       provider: options.provider,
       sessionService,
@@ -8278,34 +9516,19 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
       onHeartbeatFailure: (sessionID, error) => {
         void this.handleHeartbeatFailure(sessionID, error);
       },
-      onFrameDisplayed: () => this.remoteFrameDisplayHandler?.(),
-      onRenderAttached: () => this.applyRemoteInterpolation(),
-      onRenderDetached: () => {
-        this.interpolationRevision++;
-      }
+      renderController: this.renderController,
+      onInteraction: (frame) => this.mediaController.submitInteraction(frame)
     });
-    this.generationManager = new XmaxRealtimeGenerationManager(this.streamController);
+    this.generationManager = new XmaxRealtimeGenerationManager(this.streamController, this.mediaController, this.renderController);
     this.coordinator = new RealtimeCoordinator({
       errorHandler: this.errorHandler,
       cleanup: (scope, taskID) => this.performCleanup(scope, taskID)
     });
-    if (options.provider === "agora" /* agora */) {
-      this.qualityHistory = new QualityHistory(options.model);
+    if (options.provider === "agora" /* agora */ || options.provider === "trtc" /* trtc */) {
+      this.qualityHistory = new QualityHistory(options.model, options.provider);
       this.qualityController = new QualityController(async (change, signal) => {
-        if (signal.aborted || this.currentState.connectionState !== "Generating" /* generating */) {
-          throw new XmaxError("CANCELLED" /* cancelled */, "Adaptive video format update was cancelled");
-        }
         await this.coordinator.run("configuration" /* configuration */, void 0, async (token) => {
-          const track = this.currentUplinkTrack;
-          const state2 = track && this.qualityStates.get(track);
-          if (!track || !state2) throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Adaptive video baseline is unavailable");
-          const format = qualityVideoFormat(state2.baseline, change.to);
-          await this.streamController.updateUplinkVideoFormat(format);
-          token.ensureCurrent();
-          this.generationVideoFormat ?? (this.generationVideoFormat = state2.baseline);
-          track.updateVideoFormat(format);
-          state2.level = change.to;
-          this.qualityHistory?.write("uplink", change.to);
+          await this.applyUplinkQuality(change.to, token, signal);
         });
       });
       this.downlinkQualityController = new QualityController(async (change, signal) => {
@@ -8363,13 +9586,58 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
       this.applyRemoteInterpolation();
     });
   }
+  /**
+   * 手动调整上行档位，保留原始基准，自动调档从新档位继续。
+   * @param direction 升一档或降一档；到达 L1/L5 边界时不重复应用。
+   */
+  async adjustUplinkQuality(direction) {
+    await this.coordinator.run("configuration" /* configuration */, void 0, async (token) => {
+      const controller = this.qualityController;
+      const track = this.currentUplinkTrack;
+      const state2 = track && this.qualityStates.get(track);
+      if (!controller || !state2 || this.currentState.connectionState !== "Generating" /* generating */ || direction !== "upgrade" && direction !== "downgrade") {
+        throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Uplink quality adjustment requires an active adaptive-quality generation and a valid direction");
+      }
+      const level = Math.max(1, Math.min(Object.keys(QUALITY_TIERS).length, state2.level + (direction === "upgrade" ? -1 : 1)));
+      if (level === state2.level) return;
+      this.adaptiveQualityRevision++;
+      controller.resetSamples();
+      await this.applyUplinkQuality(level, token);
+      controller.start(level);
+    });
+  }
+  async applyUplinkQuality(level, token, signal) {
+    const track = this.currentUplinkTrack;
+    const state2 = track && this.qualityStates.get(track);
+    const ensureActive2 = () => {
+      token.ensureCurrent();
+      if (signal?.aborted || !track || !state2 || track !== this.currentUplinkTrack || state2 !== this.qualityStates.get(track) || this.currentState.connectionState !== "Generating" /* generating */) {
+        throw new XmaxError("CANCELLED" /* cancelled */, "Adaptive video format update was cancelled");
+      }
+    };
+    ensureActive2();
+    if (!track || !state2) return;
+    const target = this.uplinkQualityFormat(state2.baseline, level);
+    let format;
+    if (this.options.provider === "trtc" /* trtc */) {
+      format = await this.streamController.updateUplinkFrameRate(target.fps);
+    } else {
+      await this.streamController.updateUplinkVideoFormat(target);
+      format = target;
+    }
+    ensureActive2();
+    this.generationVideoFormat ?? (this.generationVideoFormat = state2.baseline);
+    track.updateVideoFormat(format);
+    state2.level = level;
+    this.qualityHistory?.write("uplink", level);
+  }
   /** 手动调试与自动调档使用同一尺寸信令路径，不修改生成或上行配置。 */
   async adjustDownlinkQuality(direction) {
     await this.coordinator.run("configuration" /* configuration */, void 0, async (token) => {
       const controller = this.downlinkQualityController;
       const state2 = this.downlinkQualityState;
       if (!controller || !state2 || this.currentState.connectionState !== "Generating" /* generating */ || direction !== "upgrade" && direction !== "downgrade") {
-        throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Downlink quality adjustment requires an active Agora generation and a valid direction");
+        throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Downlink quality adjustment requires an active adaptive-quality generation and a valid direction");
       }
       const level = Math.max(1, Math.min(Object.keys(QUALITY_TIERS).length, state2.level + (direction === "upgrade" ? -1 : 1)));
       if (level === state2.level) return;
@@ -8451,7 +9719,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
   applyRemoteInterpolation() {
     const revision = ++this.interpolationRevision;
     const size = this.interpolationSize;
-    this.connectionManager.setFrameInterpolation(size ? {
+    this.renderController.setFrameInterpolation(size ? {
       size,
       onFailure: (error) => {
         if (revision === this.interpolationRevision) this.handleInterpolationFailure(error);
@@ -8621,7 +9889,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
       "media" /* media */,
       void 0,
       async (token) => {
-        this.ensureNoLocalSource();
+        this.mediaController.ensureNoLocalSource();
         await this.coordinator.commit(
           new RealtimeState({
             connectionState: "Preparing" /* preparing */
@@ -8642,7 +9910,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
         let stream;
         try {
           token.ensureCurrent();
-          stream = await this.cameraController.createLocalCameraStream(options);
+          stream = await this.mediaController.createLocalCameraStream(options);
         } catch (error) {
           this.disposePermissionWatch();
           this.launchTimer.cancel();
@@ -8651,7 +9919,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
         token.ensureCurrent();
         this.generationVideoFormat = stream.videoTrack?.videoFormat;
         completeCamera();
-        this.cameraController.setPreviewReadyHandler((isCurrent) => {
+        this.mediaController.setCameraPreviewReadyHandler((isCurrent) => {
           void this.coordinator.localPreviewDidBecomeReady(isCurrent);
         });
         return stream;
@@ -8667,12 +9935,12 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    */
   async createNetworkVideoStream(options) {
     return this.coordinator.run("media" /* media */, void 0, async (token) => {
-      this.ensureNoLocalSource();
-      const stream = this.networkVideoController.create(options, this.mediaService);
+      this.mediaController.ensureNoLocalSource();
+      const stream = this.mediaController.createNetworkVideoStream(options);
       token.setFailureScope(1 /* all */);
       this.launchTimer.start();
       this.clearVideoStatistics();
-      await this.rtcManager.initialize();
+      await this.mediaController.prepareSource(() => token.ensureCurrent());
       token.ensureCurrent();
       this.generationVideoFormat = stream.videoTrack?.videoFormat;
       await this.coordinator.commit(new RealtimeState({ connectionState: "Ready" /* ready */ }), token);
@@ -8688,22 +9956,32 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    */
   async createLocalVideoStream(options) {
     return this.coordinator.run("media" /* media */, void 0, async (token) => {
-      this.ensureNoLocalSource();
-      if (!this.rtcManager.setExternalMediaTracks) {
-        throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "The RTC provider does not support local video streams");
-      }
+      this.mediaController.ensureNoLocalSource();
+      this.mediaController.validateExternalMediaSupport("local");
       token.setFailureScope(1 /* all */);
       this.launchTimer.start();
       this.clearVideoStatistics();
-      const stream = await this.localVideoController.create(options, this.mediaService, token.signal);
-      token.ensureCurrent();
-      await this.rtcManager.initialize();
+      const stream = await this.mediaController.createLocalVideoStream(options, token.signal);
       token.ensureCurrent();
-      await this.rtcManager.setExternalMediaTracks({
-        videoTrack: stream.videoTrack.mediaStreamTrack,
-        audioTrack: this.localVideoController.audioTrack
-      });
+      await this.mediaController.prepareSource(() => token.ensureCurrent());
+      this.generationVideoFormat = stream.videoTrack?.videoFormat;
+      await this.coordinator.commit(new RealtimeState({ connectionState: "Ready" /* ready */ }), token);
+      return stream;
+    });
+  }
+  /**
+   * 创建本地图片静止视频源并准备 RTC，失败或取消时释放本次资源。
+   */
+  async createLocalImageStream(options) {
+    return this.coordinator.run("media" /* media */, void 0, async (token) => {
+      this.mediaController.ensureNoLocalSource();
+      this.mediaController.validateExternalMediaSupport("image");
+      token.setFailureScope(1 /* all */);
+      this.launchTimer.start();
+      this.clearVideoStatistics();
+      const stream = await this.mediaController.createLocalImageStream(options, token.signal);
       token.ensureCurrent();
+      await this.mediaController.prepareSource(() => token.ensureCurrent());
       this.generationVideoFormat = stream.videoTrack?.videoFormat;
       await this.coordinator.commit(new RealtimeState({ connectionState: "Ready" /* ready */ }), token);
       return stream;
@@ -8716,18 +9994,13 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    */
   async createExternalVideoStream(options) {
     return this.coordinator.run("media" /* media */, void 0, async (token) => {
-      this.ensureNoLocalSource();
-      if (!this.rtcManager.setExternalMediaTracks) {
-        throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "The RTC provider does not support external video streams");
-      }
-      const stream = this.externalVideoController.create(options, this.mediaService);
+      this.mediaController.ensureNoLocalSource();
+      this.mediaController.validateExternalMediaSupport("external");
+      const stream = this.mediaController.createExternalVideoStream(options);
       token.setFailureScope(1 /* all */);
       this.launchTimer.start();
       this.clearVideoStatistics();
-      await this.rtcManager.initialize();
-      token.ensureCurrent();
-      await this.rtcManager.setExternalMediaTracks({ videoTrack: stream.videoTrack.mediaStreamTrack });
-      token.ensureCurrent();
+      await this.mediaController.prepareSource(() => token.ensureCurrent());
       this.generationVideoFormat = stream.videoTrack?.videoFormat;
       await this.coordinator.commit(new RealtimeState({ connectionState: "Ready" /* ready */ }), token);
       return stream;
@@ -8735,19 +10008,11 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
   }
   /** 当前可发布的本地视频轨，不包含服务端直接读取的网络视频。 */
   get currentUplinkTrack() {
-    return this.externalVideoController.currentTrack ?? this.localVideoController.currentTrack ?? this.cameraController.currentTrack;
+    return this.mediaController.uplinkTrack;
   }
   /** 当前 Manager 拥有的媒体源轨道。 */
   get currentLocalTrack() {
-    return this.currentUplinkTrack ?? this.networkVideoController.currentTrack;
-  }
-  /**
-   * 创建前拒绝覆盖活动源，避免旧预览或连接资源被静默遗留。
-   */
-  ensureNoLocalSource() {
-    if (this.currentLocalTrack || this.localVideoController.isActive) {
-      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Close the current local stream before creating another one");
-    }
+    return this.mediaController.currentTrack;
   }
   /**
    * 移除媒体权限弹窗观察；授权决定已记录或不再需要观察时调用。
@@ -8856,7 +10121,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    * 停止本地相机流并释放本地预览与 RTC 资源。
    */
   async stopLocalCameraStream() {
-    if (this.networkVideoController.currentTrack || this.localVideoController.isActive || this.externalVideoController.currentTrack) {
+    if (this.mediaController.source && this.mediaController.source !== "camera") {
       return;
     }
     await this.coordinator.run(
@@ -8866,7 +10131,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
         this.launchTimer.cancel();
         this.clearVideoStatistics();
         this.disposePermissionWatch();
-        await this.cameraController.stopLocalCameraStream();
+        await this.mediaController.stopLocalCameraStream();
         token.ensureCurrent();
         this.generationVideoFormat = void 0;
         await this.coordinator.commit(
@@ -8889,11 +10154,11 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
       "cameraSwitch" /* cameraSwitch */,
       void 0,
       async (token) => {
-        if (this.externalVideoController.currentTrack) {
+        if (this.mediaController.source === "externalVideo") {
           throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "External video capture is managed by the caller");
         }
         this.qualityController?.stop();
-        const stream = await this.cameraController.switchCamera();
+        const stream = await this.mediaController.switchCamera();
         token.ensureCurrent();
         return stream;
       }
@@ -8930,19 +10195,24 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
   /**
    * 按需建立连接并开始生成。
    *
-   * 尚未连接时先建立实时连接；已在生成时仅更新生成条件，不重启生成。
+   * 尚未连接时先建立实时连接；已在生成时默认更新条件，restart 为 true 时重新开始生成。
    * 首次生成必须提供条件上下文，之后缺省时复用最近一次缓存的上下文。
    *
    * @param options.localStream 由当前 Manager 创建的摄像头、外部视频轨、本地文件或网络视频源。
    * @param options.context 本次生成使用的条件上下文；缺省时复用缓存。
+   * @param options.restart 是否保留 RTC 连接并创建新任务发送 start，默认 false；不预先发送 stop。
    * @param options.faceRestoration 是否启用原始人脸回贴，默认 false；正在生成时通过 change_condition 更新。
+   * @param options.extraParams 合并到本次 start 或 change_condition 的 params；不缓存，自动恢复时不携带，不允许覆盖 SDK 字段。
+   * @param options.record 是否录制远端原始音视频约 20 秒，默认 false；仅 start 有效，条件更新时忽略，重启录制暂不支持。
    * @returns 承载远端生成画面的媒体流。
+   * @throws extraParams 包含非 JSON 数据、循环引用或 SDK 保留字段时，在连接或更新前抛出 invalidConfiguration。
    * @throws 本地流不属于当前 Manager、缺少可用的条件上下文、信令发送
    * 或生成确认失败时抛出错误；失败时自动停止生成任务并释放连接资源。
    */
   async startGeneration(options) {
+    const extraParams = snapshotExtraParams(options.extraParams);
     return this.coordinator.run(
-      "generation" /* generation */,
+      options.restart === true ? "generationRestart" /* generationRestart */ : "generation" /* generation */,
       void 0,
       async (token) => {
         const localTrack = options.localStream.videoTrack;
@@ -8960,34 +10230,50 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
           );
         }
         const currentState = this.coordinator.currentState;
-        if (currentState.connectionState === "Generating" /* generating */) {
+        const isGenerating = currentState.connectionState === "Generating" /* generating */;
+        if (isGenerating && options.restart !== true) {
           await this.generationManager.update(currentState.taskID, {
             videoFormat,
-            faceRestoration: options.faceRestoration ?? false,
+            context: options.context,
             targetSize: this.downlinkQualityController ? this.downlinkQualityState?.size : void 0,
-            context: options.context
+            faceRestoration: options.faceRestoration ?? false,
+            extraParams
           });
           token.ensureCurrent();
           return this.connectionManager.makeRemoteStream();
         }
         const supplied = this.generationManager.validateContext(options.context);
-        const referenceVideo = this.networkVideoController.reference;
+        const referenceVideo = this.mediaController.referenceVideo;
         if (!referenceVideo && supplied.referenceVideo) {
           throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Create a network video stream before using a reference video");
         }
         const context = referenceVideo ? new RealtimeContext({ ...supplied, referenceVideo }) : supplied;
-        if (currentState.connectionState !== "Connected" /* connected */) {
+        if (currentState.connectionState !== "Connected" /* connected */ && !isGenerating) {
           await this.performConnect(options.localStream, token);
         }
-        return this.performStartGeneration(token, videoFormat, context, options.faceRestoration ?? false);
+        return this.performStartGeneration(
+          token,
+          videoFormat,
+          context,
+          options.restart ?? false,
+          options.faceRestoration ?? false,
+          extraParams,
+          options.record ?? false
+        );
       }
     );
   }
+  /**
+   * 设置录制最终事件监听器；清除监听不停止录制，录制错误不影响生成。
+   */
+  setRecordingListener(listener) {
+    this.recordingController.setListener(listener);
+  }
   /**
    * 断开实时连接并保留当前本地媒体预览。
    */
   async disconnect() {
-    this.localVideoController.pause();
+    this.mediaController.pauseLocalVideo();
     this.launchTimer.cancel();
     this.clearVideoStatistics();
     await this.coordinator.disconnect();
@@ -8997,15 +10283,20 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    * 关闭期间重复调用会等待同一个释放任务；关闭完成后仍可重新创建本地流。
    */
   async close() {
-    this.localVideoController.pause();
+    this.mediaController.pauseLocalVideo();
     this.launchTimer.cancel();
     this.clearVideoStatistics();
     await this.coordinator.terminate(1 /* all */);
   }
+  /** TRTC 临时只按档位调整帧率；启动时也保留原始分辨率。 */
+  uplinkQualityFormat(baseline, level) {
+    const format = qualityVideoFormat(baseline, level);
+    return this.options.provider === "trtc" /* trtc */ ? format.resized(baseline.width, baseline.height) : format;
+  }
   /** 仅为尚无档位记录的本地上行选择初始档位；不应用配置或覆盖重连状态。 */
   resolveInitialUplinkQuality(track) {
     if (!this.qualityController) return void 0;
-    if (this.networkVideoController.currentTrack) return void 0;
+    if (this.mediaController.source === "networkVideo") return void 0;
     if (this.qualityStates.has(track)) return void 0;
     const baseline = track.videoFormat;
     if (!baseline) return void 0;
@@ -9038,8 +10329,8 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
     if (token.signal.aborted) abortWarmup();
     try {
       let beforePublish;
-      if (localTrack === this.cameraController.currentTrack && this.cameraController.isFrameValidationEnabled) {
-        const cameraReady = this.cameraController.waitForValidCameraFrame(warmupController.signal).then(() => {
+      if (this.mediaController.isFrameValidationEnabled) {
+        const cameraReady = this.mediaController.waitForValidCameraFrame(warmupController.signal).then(() => {
           token.ensureCurrent();
         });
         void cameraReady.catch(() => {
@@ -9047,7 +10338,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
         beforePublish = () => cameraReady;
       }
       const initialQuality = this.resolveInitialUplinkQuality(localTrack);
-      const initialFormat = initialQuality ? qualityVideoFormat(initialQuality.baseline, initialQuality.level) : void 0;
+      const initialFormat = initialQuality ? this.uplinkQualityFormat(initialQuality.baseline, initialQuality.level) : void 0;
       const remote = await this.connectionManager.connect({
         localTrack,
         remoteVideoFormat: this.generationVideoFormat ?? localTrack.videoFormat,
@@ -9060,8 +10351,8 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
           this.qualityHistory?.write("uplink", initialQuality.level);
         },
         model: this.options.model,
-        includeLocalAudio: this.localVideoController.isActive ? this.localVideoController.audioTrack !== void 0 : localTrack === this.cameraController.currentTrack && this.cameraController.useMicrophone,
-        publishLocalMedia: !this.networkVideoController.currentTrack,
+        includeLocalAudio: this.mediaController.hasAudio,
+        publishLocalMedia: this.mediaController.source !== "networkVideo",
         ensureCurrent: () => token.ensureCurrent(),
         onPublished: () => {
           this.acceptsVideoStatistics = true;
@@ -9083,9 +10374,21 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
   }
   /**
    * 编排插帧、首帧计时和生成状态，任务与确认由生成管理器负责。
-   */
-  async performStartGeneration(token, videoFormat, context, faceRestoration) {
+   *
+   * @param token 当前生成操作的取消与状态控制令牌。
+   * @param videoFormat 模型生成使用的视频规格。
+   * @param context 本次已解析的生成条件。
+   * @param restart 是否替换当前生成任务并重新发送 start。
+   * @param faceRestoration 是否回贴原始人脸。
+   * @param extraParams 合并到本次 start 的 params，不缓存。
+   * @param record 是否为本次任务开启独立录制，不影响生成返回时间。
+   * @returns 承载生成结果的远端媒体流。
+   */
+  async performStartGeneration(token, videoFormat, context, restart, faceRestoration, extraParams, record2 = false) {
     token.setFailureScope(0 /* connection */);
+    if (restart) {
+      void this.recordingController.stop("restarted" /* restarted */);
+    }
     const initialLevel = this.qualityHistory?.read("downlink") ?? 1;
     const targetSize = this.downlinkQualityController ? qualityVideoSize(videoFormat, initialLevel) : void 0;
     await this.prepareFrameInterpolation(targetSize ?? videoFormat, token);
@@ -9095,21 +10398,33 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
     };
     const taskID = await this.generationManager.start({
       videoFormat,
-      targetSize,
-      context,
-      faceRestoration,
-      mirror: this.currentLocalTrack === this.cameraController.currentTrack && this.cameraController.currentTrack?.position === "front" /* front */,
       signal: token.signal,
       ensureCurrent: () => token.ensureCurrent(),
-      onStartSent: this.localVideoController.isActive ? async () => {
-        token.ensureCurrent();
-        await this.localVideoController.start(token.signal);
-        token.ensureCurrent();
-      } : void 0,
       waitUntilRemoteReady: () => this.connectionManager.waitUntilRemoteTrackReady(
         REMOTE_FIRST_FRAME_TIMEOUT_MS,
         token.signal
-      )
+      ),
+      context,
+      restart,
+      onRemoteReady: record2 ? (taskID2) => {
+        if (restart) {
+          this.recordingController.reportFailure(taskID2, new XmaxError(
+            "INVALID_CONFIGURATION" /* invalidConfiguration */,
+            "Recording restarted generation tasks is not supported"
+          ));
+        } else {
+          this.recordingController.start(taskID2, () => this.streamController.getRemoteRecordingTracks());
+        }
+      } : void 0,
+      targetSize,
+      mirror: this.mediaController.source === "camera" && this.currentLocalTrack?.position === "front" /* front */,
+      faceRestoration,
+      onStartSent: this.mediaController.source === "localVideo" ? async () => {
+        token.ensureCurrent();
+        await this.mediaController.startLocalVideo(token.signal);
+        token.ensureCurrent();
+      } : void 0,
+      extraParams
     });
     const sessionID = this.connectionManager.currentSessionID;
     if (!sessionID) {
@@ -9127,13 +10442,14 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
       token
     );
     this.qualityHistory?.write("downlink", initialLevel);
-    const onFinish = this.networkVideoController.onFinish;
-    if (this.networkVideoController.currentTrack) {
-      this.streamController.activateNetworkVideoCompletion(onFinish && (() => {
+    const onFinish = this.mediaController.onNetworkVideoFinish;
+    if (this.mediaController.source === "networkVideo") {
+      this.streamController.activateNetworkVideoCompletion(() => {
         if (this.currentState.taskID === taskID && this.currentState.connectionState === "Generating" /* generating */) {
-          return onFinish();
+          void this.recordingController.stop("generationEnded" /* generationEnded */);
+          return onFinish?.();
         }
-      }));
+      });
     }
     return this.connectionManager.makeRemoteStream();
   }
@@ -9151,7 +10467,8 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    * 统一清理顺序：停止心跳与生成，再断开连接；all 额外释放本地媒体。
    */
   async performCleanup(scope, taskID) {
-    this.localVideoController.pause();
+    const recordingFinished = this.recordingController.stop("generationEnded" /* generationEnded */);
+    this.mediaController.pauseLocalVideo();
     this.launchTimer.cancel();
     this.remoteFrameDisplayHandler = void 0;
     this.clearVideoStatistics();
@@ -9161,27 +10478,17 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
     this.connectionManager.stopHeartbeat();
     await this.generationManager.reset(taskID);
     const sessionID = await this.connectionManager.disconnect();
+    await recordingFinished;
     if (scope === 1 /* all */) {
-      const hadExternalSource = this.networkVideoController.currentTrack !== void 0 || this.localVideoController.isActive || this.externalVideoController.currentTrack !== void 0;
-      this.networkVideoController.stop();
       this.generationVideoFormat = void 0;
       this.disposePermissionWatch();
       try {
-        if (hadExternalSource) {
-          await this.rtcManager.destroy();
-        } else {
-          await this.cameraController.stopLocalCameraStream();
-        }
+        await this.mediaController.stopLocalStream();
       } catch (error) {
         XmaxLogger.realtime.error(
           () => `\u91CA\u653E\u672C\u5730\u5A92\u4F53\u5931\u8D25 (Failed to Release Local Media)
 \u2514\u2500 ${XmaxLogger.localized("\u539F\u56E0\uFF1A", "Reason: ")}${XmaxError.from(error).message}`
         );
-      } finally {
-        this.externalVideoController.stop();
-        if (this.localVideoController.isActive) {
-          await this.localVideoController.stop();
-        }
       }
     }
     return {
@@ -9759,13 +11066,6 @@ var RealtimeConfiguration = class {
   }
 };
 
-// src/Foundation/Media/Video/VideoContentMode.ts
-var VideoContentMode = /* @__PURE__ */ ((VideoContentMode2) => {
-  VideoContentMode2["fit"] = "fit";
-  VideoContentMode2["fill"] = "fill";
-  return VideoContentMode2;
-})(VideoContentMode || {});
-
 // src/Render/Video/RenderStatisticsController.ts
 var RenderStatisticsController = class {
   /**
@@ -12275,6 +13575,498 @@ var RemoteVideoFramePipeline = class {
   }
 };
 
+// src/Render/Trajectory/TrajectoryOverlayView.ts
+var TrajectoryOverlayView = class {
+  /**
+   * 安装透明交互层及独立 Renderer；只有任务就绪时接管指针。
+   */
+  constructor(renderer) {
+    __publicField(this, "renderer", renderer);
+    /**
+     * 视图与显示配置
+     */
+    __publicField(this, "element", document.createElement("div"));
+    __publicField(this, "binding");
+    __publicField(this, "format");
+    __publicField(this, "contentMode", "fill" /* fill */);
+    __publicField(this, "mirrored", false);
+    __publicField(this, "requested", true);
+    __publicField(this, "enabled", false);
+    /**
+     * 手势采样与生命周期资源
+     */
+    __publicField(this, "pointers", /* @__PURE__ */ new Map());
+    __publicField(this, "nextID", 0);
+    __publicField(this, "animation");
+    __publicField(this, "lastSample", 0);
+    __publicField(this, "resizeObserver");
+    __publicField(this, "viewport");
+    __publicField(this, "visibilityChanged", () => {
+      if (document.hidden) {
+        this.cancel();
+      }
+      this.updateStyle();
+    });
+    __publicField(this, "onDown", (event) => this.begin(event));
+    __publicField(this, "onMove", (event) => this.move(event));
+    __publicField(this, "onEnd", (event) => this.end(event.pointerId));
+    Object.assign(this.element.style, { position: "absolute", inset: "0", zIndex: "2", overflow: "hidden" });
+    Object.assign(renderer.element.style, { position: "absolute", inset: "0", width: "100%", height: "100%", pointerEvents: "none" });
+    this.element.appendChild(renderer.element);
+    this.element.addEventListener("pointerdown", this.onDown);
+    this.element.addEventListener("pointermove", this.onMove);
+    this.element.addEventListener("pointerup", this.onEnd);
+    this.element.addEventListener("pointercancel", this.onEnd);
+    this.element.addEventListener("lostpointercapture", this.onEnd);
+    document.addEventListener("visibilitychange", this.visibilityChanged);
+    if (typeof ResizeObserver !== "undefined") {
+      this.resizeObserver = new ResizeObserver(() => this.cancel());
+      this.resizeObserver.observe(this.element);
+    }
+    this.updateStyle();
+  }
+  /**
+   * 更新任务绑定，清除旧任务手势和采样。
+   */
+  setBinding(binding, format, enabled = false) {
+    this.cancel();
+    this.binding = binding;
+    this.format = format;
+    this.enabled = enabled;
+    this.updateStyle();
+  }
+  /**
+   * 同步显示配置；配置变化后旧坐标不再继续发送。
+   */
+  configure(mode, mirrored, enabled) {
+    if (this.contentMode !== mode || this.mirrored !== mirrored || this.requested !== enabled) {
+      this.cancel();
+    }
+    this.contentMode = mode;
+    this.mirrored = mirrored;
+    this.requested = enabled;
+    this.updateStyle();
+  }
+  /**
+   * 卸载时取消采样、动画、捕获和事件监听；Renderer 可以再次挂载。
+   */
+  dispose() {
+    this.binding?.detach(this);
+    this.cancel();
+    this.resizeObserver?.disconnect();
+    document.removeEventListener("visibilitychange", this.visibilityChanged);
+    this.element.removeEventListener("pointerdown", this.onDown);
+    this.element.removeEventListener("pointermove", this.onMove);
+    this.element.removeEventListener("pointerup", this.onEnd);
+    this.element.removeEventListener("pointercancel", this.onEnd);
+    this.element.removeEventListener("lostpointercapture", this.onEnd);
+    this.element.remove();
+  }
+  /**
+   * 无任务或被禁用时不阻止页面滚动。
+   */
+  updateStyle() {
+    const active = this.requested && this.enabled && !!this.binding && !document.hidden;
+    this.element.style.pointerEvents = active ? "auto" : "none";
+    this.element.style.touchAction = active ? "none" : "auto";
+    this.element.style.userSelect = active ? "none" : "auto";
+  }
+  /**
+   * 根据实际显示区域拒绝黑边，移动到视口外时限制在可见视频边缘。
+   */
+  point(event, id, clamp) {
+    const viewport = this.element.getBoundingClientRect();
+    if (!this.format) {
+      return void 0;
+    }
+    const rect = InteractionCoordinateMapper.displayedFrame(viewport, this.format, this.contentMode);
+    if (!rect || !Number.isFinite(event.clientX) || !Number.isFinite(event.clientY)) {
+      return void 0;
+    }
+    const minX = Math.max(0, rect.x);
+    const minY = Math.max(0, rect.y);
+    const maxX = Math.min(viewport.width, rect.x + rect.width);
+    const maxY = Math.min(viewport.height, rect.y + rect.height);
+    let x = event.clientX - viewport.left;
+    let y = event.clientY - viewport.top;
+    if (!clamp && (x < minX || x > maxX || y < minY || y > maxY)) {
+      return void 0;
+    }
+    x = Math.max(minX, Math.min(maxX, x));
+    y = Math.max(minY, Math.min(maxY, y));
+    return Object.freeze({
+      id,
+      location: Object.freeze({ x, y }),
+      normalizedLocation: Object.freeze({ x: (x - rect.x) / rect.width, y: (y - rect.y) / rect.height }),
+      timestamp: performance.now()
+    });
+  }
+  /**
+   * 按下立即采样，不等待定时窗口；只接受鼠标主键。
+   */
+  begin(event) {
+    if (!this.requested || !this.enabled || !this.binding || document.hidden || event.button !== 0) {
+      return;
+    }
+    const point = this.point(event, ++this.nextID, false);
+    if (!point) {
+      return;
+    }
+    event.preventDefault();
+    this.pointers.set(event.pointerId, point);
+    try {
+      this.element.setPointerCapture(event.pointerId);
+    } catch {
+    }
+    this.render(() => this.renderer.renderBegan([point]));
+    this.sample(performance.now(), true);
+    this.schedule();
+  }
+  /**
+   * 高频指针事件只更新最新位置及视觉效果，不直接发送网络消息。
+   */
+  move(event) {
+    const previous = this.pointers.get(event.pointerId);
+    if (!previous) {
+      return;
+    }
+    const point = this.point(event, previous.id, true);
+    if (point) {
+      this.pointers.set(event.pointerId, point);
+      this.render(() => this.renderer.renderMoved([point]));
+    }
+  }
+  /**
+   * 释放单个指针，多指交互继续；最后一个指针释放后停止采样。
+   */
+  end(pointerID) {
+    const point = this.pointers.get(pointerID);
+    if (!point) {
+      return;
+    }
+    this.pointers.delete(pointerID);
+    try {
+      this.element.releasePointerCapture(pointerID);
+    } catch {
+    }
+    this.render(() => this.renderer.renderEnded([point.id]));
+    if (!this.pointers.size) {
+      this.stopSampling();
+    }
+  }
+  /**
+   * 取消全部手势及视觉效果，不保留跨生命周期轨迹。
+   */
+  cancel() {
+    for (const id of [...this.pointers.keys()]) {
+      this.end(id);
+    }
+    this.stopSampling();
+    this.render(() => this.renderer.reset());
+  }
+  /**
+   * 清理采样回调与视口快照。
+   */
+  stopSampling() {
+    if (this.animation !== void 0) {
+      cancelAnimationFrame(this.animation);
+    }
+    this.animation = void 0;
+    this.viewport = void 0;
+    this.lastSample = 0;
+  }
+  /**
+   * 只在存在活动触点时运行动画时钟。
+   */
+  schedule() {
+    if (this.animation === void 0 && this.pointers.size) {
+      this.animation = requestAnimationFrame((now) => {
+        this.animation = void 0;
+        this.sample(now);
+        this.schedule();
+      });
+    }
+  }
+  /**
+   * 固定频率发送所有活动触点的快照，布局变化时取消而非发送旧坐标。
+   */
+  sample(now, force = false) {
+    if (document.hidden) {
+      this.cancel();
+      return;
+    }
+    const { width, height } = this.element.getBoundingClientRect();
+    if (this.viewport && (width !== this.viewport.width || height !== this.viewport.height)) {
+      this.cancel();
+      return;
+    }
+    this.viewport = { width, height };
+    if (!force && now - this.lastSample < 1e3 / 30) {
+      return;
+    }
+    this.lastSample = now;
+    this.binding?.submit({
+      points: [...this.pointers.values()].map((point) => point.location),
+      viewportSize: this.viewport,
+      contentMode: this.contentMode,
+      mirrored: this.mirrored
+    });
+  }
+  /**
+   * 自定义效果异常不影响触点采集和网络发送。
+   */
+  render(action) {
+    try {
+      action();
+    } catch {
+      XmaxLogger.render.warning(() => "\u8F68\u8FF9\u6548\u679C\u7ED8\u5236\u5931\u8D25 (Trajectory Rendering Failed)");
+    }
+  }
+};
+
+// src/Render/Trajectory/DefaultTrajectoryEffectRenderer.ts
+var VISUAL = {
+  outerWidth: 18,
+  outerBlur: 12,
+  outerAlpha: 0.35,
+  middleWidth: 10,
+  middleBlur: 6,
+  middleAlpha: 0.75,
+  coreWidth: 3,
+  headRadius: 5,
+  headGlowRadius: 14,
+  headGlowAlpha: 0.9,
+  ringCount: 2,
+  ringStartRadius: 10,
+  ringSpacing: 14,
+  ringLineWidth: 2,
+  ringPulseSpeed: 1.2,
+  ringMaxAlpha: 0.6,
+  particleCount: 4,
+  particleRadius: 3,
+  particleOrbitRadius: 22,
+  particleSpeed: 0.06,
+  particleAlpha: 0.6,
+  fadeAlpha: 0.05,
+  idleFadeFrames: 64
+};
+var DefaultTrajectoryEffectRenderer = class {
+  /**
+   * 安装独立视觉图层，不注册指针事件。
+   */
+  constructor() {
+    /**
+     * 画布与动画资源；尾迹保留像素渐隐，触点装饰每帧重绘。
+     */
+    __publicField(this, "element", document.createElement("div"));
+    __publicField(this, "trailCanvas", document.createElement("canvas"));
+    __publicField(this, "effectCanvas", document.createElement("canvas"));
+    __publicField(this, "animation");
+    __publicField(this, "hasTrailPixels", false);
+    __publicField(this, "idleFadeFrames", 0);
+    /**
+     * 活动触点和等待下一帧绘制的线段。
+     */
+    __publicField(this, "pointers", /* @__PURE__ */ new Map());
+    __publicField(this, "segments", []);
+    for (const canvas of [this.trailCanvas, this.effectCanvas]) {
+      Object.assign(canvas.style, { position: "absolute", inset: "0", width: "100%", height: "100%", pointerEvents: "none" });
+      this.element.appendChild(canvas);
+    }
+  }
+  /**
+   * 开始触点装饰，脉冲动画以本次按下时间为起点。
+   */
+  renderBegan(points) {
+    for (const point of points) {
+      this.pointers.set(point.id, { point, startedAt: point.timestamp });
+    }
+    this.idleFadeFrames = 0;
+    this.schedule();
+  }
+  /**
+   * 只绘制新线段，旧像素自然衰减，不反复加亮整条历史轨迹。
+   */
+  renderMoved(points) {
+    for (const point of points) {
+      const pointer = this.pointers.get(point.id);
+      if (pointer) {
+        this.segments.push({ from: pointer.point, to: point });
+        pointer.point = point;
+      }
+    }
+    this.schedule();
+  }
+  /**
+   * 释放触点后移除装饰，仅保留尾迹的渐隐动画。
+   */
+  renderEnded(identifiers) {
+    for (const id of identifiers) {
+      this.pointers.delete(id);
+    }
+    this.schedule();
+  }
+  /**
+   * 清除画面、待绘制数据及动画，允许同一 Renderer 再次挂载。
+   */
+  reset() {
+    if (this.animation !== void 0) {
+      cancelAnimationFrame(this.animation);
+    }
+    this.animation = void 0;
+    this.pointers.clear();
+    this.segments.length = 0;
+    this.hasTrailPixels = false;
+    this.idleFadeFrames = 0;
+    for (const canvas of [this.trailCanvas, this.effectCanvas]) {
+      canvas.getContext("2d")?.clearRect(0, 0, canvas.width, canvas.height);
+    }
+  }
+  /**
+   * 仅在触点、待绘制线段或残留尾迹存在时申请下一帧。
+   */
+  schedule() {
+    if (this.animation === void 0 && (this.pointers.size || this.segments.length || this.hasTrailPixels)) {
+      this.animation = requestAnimationFrame((now) => this.draw(now));
+    }
+  }
+  /**
+   * 同步画布分辨率，分别更新尾迹和触点视觉图层。
+   */
+  draw(now) {
+    this.animation = void 0;
+    const trail = this.trailCanvas.getContext("2d");
+    const effects = this.effectCanvas.getContext("2d");
+    if (!trail || !effects) {
+      this.reset();
+      return;
+    }
+    const rect = this.element.getBoundingClientRect();
+    const dpr = globalThis.devicePixelRatio || 1;
+    const width = Math.max(1, Math.round(rect.width * dpr));
+    const height = Math.max(1, Math.round(rect.height * dpr));
+    for (const canvas of [this.trailCanvas, this.effectCanvas]) {
+      if (canvas.width !== width || canvas.height !== height) {
+        canvas.width = width;
+        canvas.height = height;
+        this.hasTrailPixels = false;
+      }
+    }
+    if (this.hasTrailPixels) {
+      trail.save();
+      trail.globalCompositeOperation = "destination-out";
+      trail.fillStyle = "rgba(0,0,0," + VISUAL.fadeAlpha + ")";
+      trail.fillRect(0, 0, width, height);
+      trail.restore();
+    }
+    if (this.segments.length) {
+      this.drawSegments(trail, dpr);
+      this.segments.length = 0;
+      this.hasTrailPixels = true;
+      this.idleFadeFrames = 0;
+    }
+    effects.clearRect(0, 0, width, height);
+    effects.save();
+    effects.globalCompositeOperation = "lighter";
+    for (const { point, startedAt } of this.pointers.values()) {
+      const x = point.location.x * dpr;
+      const y = point.location.y * dpr;
+      if (this.pointers.size === 1) {
+        this.drawRings(effects, x, y, dpr, (now - startedAt) / 1e3);
+        this.drawParticles(effects, x, y, dpr, (now - startedAt) / 1e3);
+      }
+      this.drawGlow(effects, x, y, VISUAL.headGlowRadius * dpr, VISUAL.headGlowAlpha, true);
+      effects.fillStyle = "rgba(255,255,255,1)";
+      effects.beginPath();
+      effects.arc(x, y, VISUAL.headRadius * dpr, 0, Math.PI * 2);
+      effects.fill();
+    }
+    effects.restore();
+    if (this.pointers.size) {
+      this.idleFadeFrames = 0;
+    } else if (this.hasTrailPixels && ++this.idleFadeFrames > VISUAL.idleFadeFrames) {
+      trail.clearRect(0, 0, width, height);
+      this.hasTrailPixels = false;
+      this.idleFadeFrames = 0;
+    }
+    this.schedule();
+  }
+  /**
+   * 叠加绿色外晕、中层和白色线芯；多指时省略阴影降低绘制开销。
+   */
+  drawSegments(context, dpr) {
+    const layers = [
+      { width: VISUAL.outerWidth, blur: VISUAL.outerBlur, color: this.green(VISUAL.outerAlpha) },
+      { width: VISUAL.middleWidth, blur: VISUAL.middleBlur, color: this.green(VISUAL.middleAlpha) },
+      { width: VISUAL.coreWidth, blur: 0, color: "rgba(255,255,255,1)" }
+    ];
+    for (const layer of layers) {
+      context.save();
+      context.globalCompositeOperation = "lighter";
+      context.lineCap = "round";
+      context.lineJoin = "round";
+      context.lineWidth = layer.width * dpr;
+      context.strokeStyle = layer.color;
+      context.shadowBlur = this.pointers.size > 1 ? 0 : layer.blur * dpr;
+      context.shadowColor = context.shadowBlur ? layer.color : "transparent";
+      context.beginPath();
+      for (const { from, to } of this.segments) {
+        context.moveTo(from.location.x * dpr, from.location.y * dpr);
+        context.lineTo(to.location.x * dpr, to.location.y * dpr);
+      }
+      context.stroke();
+      context.restore();
+    }
+  }
+  /**
+   * 绘制触点周围两层不同相位的脉冲圆环。
+   */
+  drawRings(context, x, y, dpr, elapsed) {
+    context.lineWidth = VISUAL.ringLineWidth * dpr;
+    for (let index = 0; index < VISUAL.ringCount; index++) {
+      const pulse = (Math.sin((elapsed * VISUAL.ringPulseSpeed + index * 0.5) * Math.PI * 2) + 1) / 2;
+      const radius = (VISUAL.ringStartRadius + index * VISUAL.ringSpacing + pulse * 6) * dpr;
+      context.strokeStyle = this.green(VISUAL.ringMaxAlpha * (1 - index * 0.2) * (0.5 + pulse * 0.5));
+      context.beginPath();
+      context.arc(x, y, radius, 0, Math.PI * 2);
+      context.stroke();
+    }
+  }
+  /**
+   * 绘制四个反向交错运动的柔和环绕粒子。
+   */
+  drawParticles(context, x, y, dpr, elapsed) {
+    for (let index = 0; index < VISUAL.particleCount; index++) {
+      const direction = index % 2 === 0 ? 1 : -1;
+      const angle = index / VISUAL.particleCount * Math.PI * 2 + elapsed * VISUAL.particleSpeed * direction;
+      const radius = VISUAL.particleOrbitRadius * dpr;
+      const alpha = VISUAL.particleAlpha * (0.6 + Math.sin(elapsed * 3 + index) * 0.4);
+      this.drawGlow(context, x + Math.cos(angle) * radius, y + Math.sin(angle) * radius, VISUAL.particleRadius * 2 * dpr, alpha);
+    }
+  }
+  /**
+   * 绘制径向绿色光晕，触点核心增加中间色阶。
+   */
+  drawGlow(context, x, y, radius, alpha, head = false) {
+    const gradient = context.createRadialGradient(x, y, 0, x, y, radius);
+    gradient.addColorStop(0, this.green(alpha));
+    if (head) {
+      gradient.addColorStop(0.4, this.green(alpha * 0.6));
+    }
+    gradient.addColorStop(1, this.green(0));
+    context.fillStyle = gradient;
+    context.beginPath();
+    context.arc(x, y, radius, 0, Math.PI * 2);
+    context.fill();
+  }
+  /**
+   * 统一轨迹主题色，透明度由各视觉层指定。
+   */
+  green(alpha) {
+    return "rgba(0,255,100," + alpha + ")";
+  }
+};
+
 // src/Render/Video/XmaxVideoView.ts
 var OBJECT_FIT = {
   ["fit" /* fit */]: "contain",
@@ -12332,7 +14124,14 @@ var XmaxVideoView = class {
      * DOM 挂载状态
      */
     __publicField(this, "detached", false);
+    /**
+     * 轨迹交互配置与懒加载视图
+     */
+    __publicField(this, "interactionEnabled", true);
+    __publicField(this, "customTrajectoryRenderer");
+    __publicField(this, "trajectoryOverlay");
     this.contentMode = options?.videoContentMode ?? "fill" /* fill */;
+    this.interactionEnabled = options?.isInteractionEnabled ?? true;
     this.element = document.createElement("div");
     this.element.style.position = "relative";
     this.element.style.overflow = "hidden";
@@ -12349,6 +14148,36 @@ var XmaxVideoView = class {
     this.applyContentMode();
     this.element.appendChild(this.videoElement);
   }
+  /**
+   * 是否允许远端轨迹交互；本地轨道没有交互绑定，不受此开关影响。
+   */
+  get isInteractionEnabled() {
+    return this.interactionEnabled;
+  }
+  /**
+   * 关闭时立即取消当前手势，不影响视频播放。
+   */
+  set isInteractionEnabled(enabled) {
+    this.interactionEnabled = enabled;
+    this.trajectoryOverlay?.configure(this.contentMode, this.mirrored, enabled);
+  }
+  /**
+   * 自定义轨迹视觉效果；undefined 表示使用 SDK 默认效果。
+   */
+  get trajectoryRenderer() {
+    return this.customTrajectoryRenderer;
+  }
+  /**
+   * 替换效果前释放旧动画，采样及网络发送仍由 SDK 管理。
+   */
+  set trajectoryRenderer(renderer) {
+    if (this.customTrajectoryRenderer === renderer) {
+      return;
+    }
+    this.disposeTrajectory();
+    this.customTrajectoryRenderer = renderer;
+    this.attachTrajectory();
+  }
   /**
    * 当前显示的视频轨道；切换时自动解绑旧轨道。
    */
@@ -12421,6 +14250,7 @@ var XmaxVideoView = class {
   attach(to) {
     this.detached = false;
     to.appendChild(this.element);
+    this.attachTrajectory();
     if ((this.videoElement.srcObject || this.videoElement.getAttribute("src")) && this.videoElement.autoplay && !this.videoElement.ended && this.videoElement.paused && typeof this.videoElement.play === "function") {
       void this.videoElement.play().catch((error) => {
         XmaxLogger.render.warning(() => `\u6062\u590D\u89C6\u9891\u64AD\u653E\u5931\u8D25 (Failed to Resume Video Playback)
@@ -12438,6 +14268,7 @@ var XmaxVideoView = class {
    */
   detach() {
     this.detached = true;
+    this.disposeTrajectory();
     this.statisticsController.stop();
     this.stopInterpolation();
     this.cancelFrameDisplayNotification();
@@ -12544,6 +14375,7 @@ var XmaxVideoView = class {
     const binding = VideoRenderRegistry.binding(track);
     if (binding) {
       binding.attachHandler(this, this.contentMode);
+      this.attachTrajectory();
       return;
     }
     if (track.mediaStreamTrack) {
@@ -12558,6 +14390,7 @@ var XmaxVideoView = class {
    * 解绑当前轨道并清空渲染内容。
    */
   detachCurrentTrack() {
+    this.disposeTrajectory();
     this.statisticsController.stop();
     const track = this.currentTrack;
     if (track) {
@@ -12617,6 +14450,7 @@ var XmaxVideoView = class {
    * 应用显示模式与镜像样式。
    */
   applyContentMode() {
+    this.trajectoryOverlay?.configure(this.contentMode, this.mirrored, this.interactionEnabled);
     this.videoElement.style.objectFit = OBJECT_FIT[this.contentMode];
     this.videoElement.style.transform = this.mirrored ? "scaleX(-1)" : "";
     if (this.interpolationCanvas) {
@@ -12630,6 +14464,30 @@ var XmaxVideoView = class {
   startRenderStatistics() {
     if (!this.detached) this.statisticsController.start();
   }
+  /**
+   * 仅为具备交互能力的轨道创建覆盖层，普通视频和本地预览不分配 Canvas。
+   */
+  attachTrajectory() {
+    if (this.detached || this.trajectoryOverlay || !this.currentTrack) {
+      return;
+    }
+    const binding = TrajectoryRegistry.binding(this.currentTrack);
+    if (!binding) {
+      return;
+    }
+    const overlay = new TrajectoryOverlayView(this.customTrajectoryRenderer ?? new DefaultTrajectoryEffectRenderer());
+    this.trajectoryOverlay = overlay;
+    overlay.configure(this.contentMode, this.mirrored, this.interactionEnabled);
+    this.element.appendChild(overlay.element);
+    binding.attach(overlay);
+  }
+  /**
+   * 换轨或卸载时移除全部交互资源；再次挂载时重新建立绑定。
+   */
+  disposeTrajectory() {
+    this.trajectoryOverlay?.dispose();
+    this.trajectoryOverlay = void 0;
+  }
 };
 
 // src/Render/Video/XmaxRealtimeVideoView.ts
@@ -12668,8 +14526,8 @@ var XmaxRealtimeVideoView = class {
     this.element.style.position = "relative";
     this.element.style.overflow = "hidden";
     this.element.style.backgroundColor = "black";
-    this.localVideoView = new XmaxVideoView({ videoContentMode: this.contentMode });
-    this.remoteVideoView = new XmaxVideoView({ videoContentMode: this.contentMode });
+    this.localVideoView = new XmaxVideoView({ videoContentMode: this.contentMode, isInteractionEnabled: false });
+    this.remoteVideoView = new XmaxVideoView({ videoContentMode: this.contentMode, isInteractionEnabled: options?.isInteractionEnabled });
     for (const view of [this.localVideoView, this.remoteVideoView]) {
       view.element.style.position = "absolute";
       view.element.style.inset = "0";
@@ -12684,6 +14542,30 @@ var XmaxRealtimeVideoView = class {
   get localTrack() {
     return this.currentLocalTrack;
   }
+  /**
+   * 只控制远端视图的轨迹交互，本地预览始终不接管手势。
+   */
+  get isInteractionEnabled() {
+    return this.remoteVideoView.isInteractionEnabled;
+  }
+  /**
+   * 转交远端交互开关。
+   */
+  set isInteractionEnabled(enabled) {
+    this.remoteVideoView.isInteractionEnabled = enabled;
+  }
+  /**
+   * 远端视图的自定义轨迹效果。
+   */
+  get trajectoryRenderer() {
+    return this.remoteVideoView.trajectoryRenderer;
+  }
+  /**
+   * undefined 恢复默认效果，不改变轨迹发送逻辑。
+   */
+  set trajectoryRenderer(renderer) {
+    this.remoteVideoView.trajectoryRenderer = renderer;
+  }
   /**
    * 替换本地预览轨道；轨道未变化时保留当前绑定。
    */
@@ -12815,6 +14697,9 @@ export {
   RealtimeVideoTrack,
   RealtimeMediaStream,
   RealtimeVideoSampleMethod,
+  VideoContentMode,
+  RealtimeRecordingEventType,
+  RealtimeRecordingFinishReason,
   RealtimeContext,
   RealtimeConnectionState,
   RealtimeReason,
@@ -12825,8 +14710,7 @@ export {
   NonRealtimeTaskError,
   XmaxClient,
   RealtimeConfiguration,
-  VideoContentMode,
   XmaxVideoView,
   XmaxRealtimeVideoView
 };
-//# sourceMappingURL=chunk-JGDZ3RD3.js.map
+//# sourceMappingURL=chunk-ILZL4W2G.js.map