@ray-js/ipc-player-integration 0.0.49 → 0.0.50-beta.0

package/lib/widgets/zoomTurntable/turntable/rjs/index.tyml

@@ -0,0 +1,7 @@
+<!-- 样式全部内联：rjs 目录下若存在 index.tyss，引用方构建时
+     style-compiler-loader 会为其注入 ./ray-styles.tyss 的 import，
+     而该伴生文件不在 lib 产物里，会报 Cannot find module './ray-styles.tyss' -->
+<canvas
+  canvas-id="{{canvasId}}"
+  style="display: block; width: {{canvasWidth}}px; height: {{canvasHeight}}px;"
+></canvas>

package/lib/widgets/zoomTurntable/turntable/type.d.ts

@@ -0,0 +1,95 @@
+export interface ZoomMark {
+    /** 刻度对应的焦距值（画面绝对倍率 curM） */
+    value: number;
+    /** 显示标签，如 '1' */
+    label: string;
+}
+export interface ZoomTurntableStyleOptions {
+    /** 顶部预留空间，scale=1 时的 px 值，默认 50 */
+    topSafeArea?: number;
+    /** 当前倍率字号，scale=1 时的 px 值，默认跟随 markLabelFontSize */
+    currentLabelFontSize?: number;
+    /** 普通刻度字号，scale=1 时的 px 值，默认 14 */
+    markLabelFontSize?: number;
+    /** 指示圆环半径，scale=1 时的 px 值，默认 12 */
+    pointerRadius?: number;
+    /** 指示圆环线宽，scale=1 时的 px 值，默认 3 */
+    pointerStrokeWidth?: number;
+    /** 普通刻度点半径，scale=1 时的 px 值，默认 2.4 */
+    markDotRadius?: number;
+    /** 右侧模式刻度文字向椭圆内侧收的横向距离，scale=1 时的 px 值，默认 22 */
+    innerLabelOffsetX?: number;
+    /** 右侧模式刻度文字向椭圆内侧收的纵向距离，scale=1 时的 px 值，默认 22 */
+    innerLabelOffsetY?: number;
+    /** 虚线长度，scale=1 时的 px 值，默认 8 */
+    dashLength?: number;
+    /** 虚线间隔，scale=1 时的 px 值，默认 8 */
+    dashGap?: number;
+    /** 虚线宽度，scale=1 时的 px 值，默认 2.2 */
+    trackLineWidth?: number;
+    /** 遮罩透明度，默认 0.44 */
+    overlayOpacity?: number;
+    /** 从上弧顶往下截取的比例，0-1，默认 0.2 */
+    cropRatio?: number;
+    /**
+     * 绘制内容整体纵向偏移，scale=1 时的 px 值，正值下移，默认 0。
+     * 仅平移画布坐标系，不影响刻度与文案的角度分布。
+     */
+    contentOffsetY?: number;
+    /**
+     * 触摸响应余量（横向 / 纵向），scale=1 时的 px 值，默认 0。
+     * canvas 是唯一能接收 touch 的元素，尺寸严格等于椭圆截面时，
+     * 椭圆上方与两侧的空白区域滑不动。向外扩一圈可让整个转盘区域都可拖动，
+     * 绘制原点会同步补偿，视觉位置不变。
+     */
+    hitPaddingX?: number;
+    hitPaddingY?: number;
+    /**
+     * 轨道（含刻度点、指针）与标记文字整体向椭圆内侧收的距离，
+     * scale=1 时的 px 值，默认 0。用于加大它们与遮罩边缘的间距；
+     * 遮罩半径不变，故不影响组件占位尺寸。
+     */
+    trackEdgeInset?: number;
+}
+export interface ZoomTurntableProps {
+    /** 整体缩放倍数，默认 1。1.0 = 完整椭圆 351×516，可见画布约 351×149；椭圆比例固定 351:516 */
+    scale?: number;
+    /** 展示方向。bottom 为底部向上展开，right 为横屏右侧向左展开 */
+    orientation?: 'bottom' | 'right';
+    /** 从上弧顶往下截取的比例，0-1，默认 0.2 */
+    cropRatio?: number;
+    /** 最小焦距值（thresholds[0]） */
+    min?: number;
+    /** 最大焦距值（thresholds 末位 = 手势放大上限） */
+    max?: number;
+    /** 步进精度，默认 0.1 */
+    step?: number;
+    /** 受控值（画面绝对倍率 curM） */
+    value?: number;
+    /** 非受控初始值 */
+    defaultValue?: number;
+    /** 值变化回调（拖动中实时触发） */
+    onChange?: (value: number) => void;
+    /** 拖动结束回调 */
+    onChangeEnd?: (value: number) => void;
+    /** 手指按上转盘（用于禁用原生手势） */
+    onTouchStart?: () => void;
+    /** 手指离开转盘，含 touchcancel（用于恢复原生手势） */
+    onTouchEnd?: () => void;
+    /** 主刻度标记数组 */
+    marks?: ZoomMark[];
+    /**
+     * 次刻度值列表。逐镜头区间按各自 step 生成，因此不同区间刻度疏密可以不同。
+     * 不传则沿 progress 均匀分布（兜底行为）。
+     */
+    ticks?: number[];
+    /**
+     * 非线性曲线：'log' 为对数曲线，数值为幂次因子（>1 小值精细）。
+     * 本项目固定用 1（线性）—— 倍率域已是分段线性叠加，再叠对数会让刻度与镜头临界点错位。
+     */
+    curve?: 'log' | number;
+    /** 当前值与指示圆环颜色，默认 '#FFFFFF' */
+    activeColor?: string;
+    /** 视觉样式微调项 */
+    styleOptions?: ZoomTurntableStyleOptions;
+}

package/lib/widgets/zoomTurntable/turntable/type.js

@@ -0,0 +1 @@
+export {};

package/lib/widgets/zoomTurntable/useLensZoom.d.ts

@@ -0,0 +1,37 @@
+import { ComponentConfigProps } from '../../interface';
+import { ZoomSkill } from './lensSkill';
+type Options = ComponentConfigProps & {
+    /** 业务侧的功能开关；实际是否渲染仍由 ipc_multi_zoom 解析出的 cnt 决定 */
+    showZoomTurntable?: boolean;
+    /** 调试用：直接注入镜头能力，跳过 ipc_multi_zoom DP 解析 */
+    mockZoomSkill?: ZoomSkill | boolean;
+    /** 跳过能力加载：Entry 常驻负责加载，Dock 作为消费方传 true 避免重复解析 */
+    skipLoad?: boolean;
+};
+/**
+ * 焦距能力与双层缩放状态机。
+ * zoomSkill / zoomLensIndex 存在 ctx 共享 atom 上，Entry / Dock / RealTimeMagnification 读同一份。
+ */
+export declare const useLensZoom: (options: Options) => {
+    /** 是否具备多镜头变焦能力（不具备则整个 widget 不出现） */
+    multiLensReady: boolean;
+    zoomSkill: ZoomSkill | null;
+    /** 镜头列表（按 value 升序），用于渲染倍率 tab */
+    lenses: import("./lensSkill").Lens[];
+    lensIndex: number;
+    /** 画面绝对倍率 */
+    curM: number;
+    min: number;
+    max: number;
+    step: number;
+    marks: {
+        value: number;
+        label: string;
+    }[];
+    /** 次刻度值：逐镜头区间按各自 step 生成，间距逐段不同 */
+    ticks: number[];
+    beginDrag: (this: unknown, value: number) => void;
+    applyZoom: (this: unknown, targetM: number) => Promise<void>;
+    switchToLens: (this: unknown, index: number) => Promise<void>;
+};
+export {};

package/lib/widgets/zoomTurntable/useLensZoom.js

@@ -0,0 +1,418 @@
+import { useEffect, useRef, useState } from 'react';
+import { useMemoizedFn } from 'ahooks';
+import { useStore } from '../../ctx/store';
+import { PlayState } from '../../interface';
+import { useDpState } from '../../hooks/useDpState';
+import { setScaleMultipleEvent, zoomLevelChange } from '../../ui/constant';
+import { MOCK_ZOOM_SKILL, MULTI_ZOOM_DP_CODE, dumpChannelApis, isChannelChangeSupported, isZoomSkillValid, lensCount, parseZoomSkill, queryCurrentLens, showSmallMonitor, subscribeChannelChange, switchLens } from './lensSkill';
+import { DEFAULT_STEP, D_MIN, buildMarks, buildTickValues, indexOfLensId, matchLens, maxScaleMultiple, toDisplayZoom, toScaleMultiple, zoomBounds } from './lensModel';
+import { CHANNEL_SETTLE_TIMEOUT, D_MATCH_EPS, GESTURE_SWITCH_DEBOUNCE, SWITCH_LENS_TIMEOUT, zoomTurntableLensChange, zoomTurntableZoomChange } from './constants';
+/**
+ * 最近一次的本地数字缩放 d，按 devId 记录。
+ * 放模块级：Dock 动态挂载/卸载，组件内 ref 存不住，但它只是派生中间量，不值得占一个 atom。
+ */
+const lastDStore = new Map();
+const getLastD = devId => {
+  var _lastDStore$get;
+  return (_lastDStore$get = lastDStore.get(devId)) !== null && _lastDStore$get !== void 0 ? _lastDStore$get : D_MIN;
+};
+const setLastD = (devId, d) => lastDStore.set(devId, d);
+
+/**
+ * 进行中的切镜头（自己下发的那次）：目标镜头下标 + 超时兜底 timer。
+ *
+ * 同样放模块级按 devId 共享 —— Entry / Dock 是两个 hook 实例，
+ * 发起方（Dock 拖动、Entry 点 tab）与 channelChange 订阅方（Entry）常常不是同一个，
+ * 存组件内 ref 的话订阅方看不到 pending，发起方也等不到清除，会白屏蔽回读到超时。
+ */
+
+const pendingSwitchStore = new Map();
+/**
+ * 全景小窗当前的开关状态，按 devId 记。
+ * 同样放模块级：Entry / Dock 是两个 hook 实例，共用一份才能去重 ——
+ * 小窗只在「跨过 d=1 这条线」时切一次，回读每来一帧就调一次原生方法没必要。
+ */
+const smallMonitorStore = new Map();
+
+/** 自增序号：连着切到同一个镜头时，靠它认出「pending 还是不是我这次的」 */
+let switchSeq = 0;
+/** 是否正在切镜头（屏蔽回读用） */
+const isSwitching = devId => pendingSwitchStore.has(devId);
+const takePendingSwitch = devId => {
+  const pending = pendingSwitchStore.get(devId);
+  if (pending) {
+    clearTimeout(pending.timer);
+    pendingSwitchStore.delete(devId);
+  }
+  return pending;
+};
+
+/**
+ * 焦距能力与双层缩放状态机。
+ * zoomSkill / zoomLensIndex 存在 ctx 共享 atom 上，Entry / Dock / RealTimeMagnification 读同一份。
+ */
+export const useLensZoom = options => {
+  var _zoomSkill$lenses$sli, _zoomSkill$lenses, _zoomSkill$lenses$zoo, _zoomSkill$lenses2;
+  const {
+    devId,
+    event,
+    showZoomTurntable = false,
+    mockZoomSkill,
+    skipLoad = false,
+    setZoomSkill,
+    setZoomLensIndex,
+    IPCPlayerInstance
+  } = options;
+  const {
+    zoomSkill,
+    zoomLensIndex,
+    playState
+  } = useStore({
+    zoomSkill: options.zoomSkill,
+    zoomLensIndex: options.zoomLensIndex,
+    playState: options.playState
+  });
+
+  /** 镜头能力 DP；消费方（skipLoad）传空 devId 跳过订阅，直接读共享 atom */
+  const [dpState] = useDpState({
+    devId: skipLoad ? '' : devId,
+    dpCodes: [MULTI_ZOOM_DP_CODE]
+  });
+  const multiZoomDpValue = dpState[MULTI_ZOOM_DP_CODE];
+
+  /** 画面绝对倍率；挂载时按已记录的 d 恢复读数 */
+  const [curM, setCurM] = useState(() => zoomSkill ? toDisplayZoom(zoomSkill, zoomLensIndex, getLastD(devId)) : D_MIN);
+  /** 拖动中：屏蔽回读，避免指针被拽回 */
+  const draggingRef = useRef(false);
+  /** 手势缩放跨临界点判定的 trailing 防抖 */
+  const gestureTimerRef = useRef();
+  const lensIndexRef = useRef(zoomLensIndex);
+  lensIndexRef.current = zoomLensIndex;
+  const skillRef = useRef(zoomSkill);
+  skillRef.current = zoomSkill;
+
+  // ---------------- 能力加载 ----------------
+  useEffect(() => {
+    if (skipLoad || !devId || !showZoomTurntable) return undefined;
+
+    // mockZoomSkill 接管 DP 值：没有 ipc_multi_zoom 的设备上入口出不来，无法自测
+    if (mockZoomSkill) {
+      console.log('[zoomTurntable] mock 模式：跳过 ipc_multi_zoom DP 解析');
+    }
+    const raw = mockZoomSkill === true ? MOCK_ZOOM_SKILL : mockZoomSkill || multiZoomDpValue;
+    const skill = parseZoomSkill(raw);
+    if (!isZoomSkillValid(skill)) {
+      // DP 未上报 / 值畸形 / 单镜头设备：能力不可用，入口不出现
+      setZoomSkill(null);
+      return undefined;
+    }
+    setZoomSkill(skill);
+    return undefined;
+  }, [devId, showZoomTurntable, mockZoomSkill, multiZoomDpValue, skipLoad]);
+
+  /** 多镜头能力就绪：ipc_multi_zoom 解析出的 cnt > 1（单镜头设备不出现） */
+  const multiLensReady = showZoomTurntable && lensCount(zoomSkill) > 1;
+
+  // 手势缩放上限按当前镜头换算后下发给播放器：maxScaleMultiple 是 d 口径，
+  // 直接用画面绝对上限（如 6.0）会让画面放到该镜头区间之外。切镜头后跟着更新。
+  useEffect(() => {
+    if (skipLoad || !multiLensReady || !zoomSkill) return;
+    if (typeof (IPCPlayerInstance === null || IPCPlayerInstance === void 0 ? void 0 : IPCPlayerInstance.setMaxScaleMultiple) !== 'function') {
+      console.warn('[zoomTurntable] 播放器实例未就绪，maxScaleMultiple 未下发');
+      return;
+    }
+    const maxD = maxScaleMultiple(zoomSkill, zoomLensIndex);
+    IPCPlayerInstance.setMaxScaleMultiple({
+      maxScaleMultiple: maxD,
+      success: () => console.log('[zoomTurntable] setMaxScaleMultiple success', maxD),
+      fail: err => console.warn('[zoomTurntable] setMaxScaleMultiple fail', maxD, JSON.stringify(err !== null && err !== void 0 ? err : null))
+    });
+  }, [skipLoad, multiLensReady, zoomSkill, zoomLensIndex, IPCPlayerInstance]);
+
+  // ---------------- 全景小窗 ----------------
+  /**
+   * 开关全景小窗，并按 devId 去重（同一状态不重复下发）。
+   * 画面停在镜头光学正倍数（d≈1，即 1.0x / 3.0x / 8.0x）时不需要小窗；
+   * 在镜头区间内数字放大后（d>1）才显示，小窗放的是当前镜头的全景画面。
+   */
+  const applySmallMonitor = useMemoizedFn(visible => {
+    if (smallMonitorStore.get(devId) === visible) return;
+    smallMonitorStore.set(devId, visible);
+    showSmallMonitor(IPCPlayerInstance, visible);
+  });
+
+  /** 由本地数字缩放 d 决定小窗开关：d>1 说明画面不在镜头正倍数上 */
+  const syncSmallMonitorByD = useMemoizedFn(d => {
+    applySmallMonitor(d > 1 + D_MATCH_EPS);
+  });
+
+  // ---------------- 同步：把外部的「当前镜头 + d」落到 UI ----------------
+  /** 仅同步状态，不做任何下发；出流回读与 channelChange 共用 */
+  const syncToLens = useMemoizedFn((index, d) => {
+    const skill = skillRef.current;
+    if (!skill) return;
+    setZoomLensIndex(index);
+    lensIndexRef.current = index;
+    setLastD(devId, d);
+    setCurM(toDisplayZoom(skill, index, d));
+  });
+
+  // 出流后设备侧才答得上来「当前是哪个镜头」，故等 PLAYING 再查；
+  // 停流 → 再出流会重查一次，期间被别的端切过镜头也能对上
+  useEffect(() => {
+    if (skipLoad || !devId || !multiLensReady || playState !== PlayState.PLAYING) return undefined;
+    let cancelled = false;
+    queryCurrentLens(devId).then(current => {
+      // 查不到就保持现状，不要把镜头重置到第一个
+      if (cancelled || !current || !skillRef.current) return;
+      syncToLens(indexOfLensId(skillRef.current, current.lens_id), current.multiple);
+      // 出流时画面可能已经是放大态（上次退出前放大过），小窗状态跟着回读值对齐一次
+      syncSmallMonitorByD(current.multiple);
+    });
+    return () => {
+      cancelled = true;
+      // 停流 / 卸载后原生那边的小窗状态无从得知，去重记录一并丢掉，
+      // 下次出流按回读值重新下发一次，避免「记录说已开、实际已关」再也发不出去
+      smallMonitorStore.delete(devId);
+    };
+  }, [devId, multiLensReady, playState, skipLoad, syncToLens, syncSmallMonitorByD]);
+
+  // ---------------- 下发：curM → 切镜头 + d ----------------
+  const beginDrag = useMemoizedFn(value => {
+    draggingRef.current = true;
+    setCurM(value);
+  });
+
+  /**
+   * 镜头已切到 index 后的收尾：画面比例主动归 1 倍，读数即该镜头的 basicRatio。
+   * 正常路径由 channelChange 触发（等设备真正切完再动画面，中间态更干净）；
+   * 宿主不支持该事件时，退回 switchChannel 成功即收尾。
+   */
+  const settleLensSwitched = useMemoizedFn(index => {
+    var _skillRef$current;
+    const lens = (_skillRef$current = skillRef.current) === null || _skillRef$current === void 0 || (_skillRef$current = _skillRef$current.lenses) === null || _skillRef$current === void 0 ? void 0 : _skillRef$current[index];
+    if (!lens) return;
+    console.log('[scaleMultiple] zoomTurntable emit setScaleMultipleEvent', D_MIN, `lensIndex=${index}`, `lastD=${getLastD(devId)}`);
+    event.emit(setScaleMultipleEvent, D_MIN);
+    syncToLens(index, D_MIN);
+    // 切镜头即回到该镜头的光学正倍数，小窗关掉（onChannelChange / 超时兜底都会走到这里）
+    applySmallMonitor(false);
+    event.emit(zoomTurntableLensChange, {
+      lensId: lens.id,
+      lensIndex: index,
+      value: lens.basicRatio
+    });
+    event.emit(zoomTurntableZoomChange, {
+      curM: lens.basicRatio,
+      d: D_MIN,
+      lensIndex: index
+    });
+  });
+
+  /** 把目标倍率落到指定镜头上：同镜头内下发本地缩放，跨镜头则切物理镜头并归 1 倍 */
+  const applyToLens = useMemoizedFn(async (nextIndex, targetM) => {
+    var _skill$lenses;
+    const skill = skillRef.current;
+    if (!(skill !== null && skill !== void 0 && (_skill$lenses = skill.lenses) !== null && _skill$lenses !== void 0 && _skill$lenses[nextIndex])) return;
+    setCurM(targetM);
+    const prevIndex = lensIndexRef.current;
+    if (nextIndex === prevIndex) {
+      const d = toScaleMultiple(skill, prevIndex, targetM);
+      setLastD(devId, d);
+      event.emit(setScaleMultipleEvent, d);
+      event.emit(zoomTurntableZoomChange, {
+        curM: targetM,
+        d,
+        lensIndex: prevIndex
+      });
+      // 同镜头内变倍：直接按下发值切小窗，不必等画面回读
+      syncSmallMonitorByD(d);
+      return;
+    }
+
+    // 切物理镜头：从下发到 channelChange 回来这段屏蔽回读
+    console.log('[zoomTurntable] 切换镜头', `${prevIndex} -> ${nextIndex}`, `channel=${skill.lenses[nextIndex].id}`, `targetM=${targetM.toFixed(2)}`);
+    takePendingSwitch(devId); // 上一次没结算完的直接作废，以最新这次为准
+    switchSeq += 1;
+    const seq = switchSeq;
+    /** 读数退回「当前镜头 + 已记录的 d」；切没切成不确定时才用 */
+    const rollback = () => setCurM(toDisplayZoom(skill, lensIndexRef.current, getLastD(devId)));
+
+    // 第一段超时：switchChannel 回调始终不来 —— 切没切成未知，只能回滚
+    pendingSwitchStore.set(devId, {
+      seq,
+      index: nextIndex,
+      timer: setTimeout(() => {
+        pendingSwitchStore.delete(devId);
+        rollback();
+        console.warn('[zoomTurntable] switchChannel 无回调，读数已回滚', `${prevIndex} -> ${nextIndex}`, `${SWITCH_LENS_TIMEOUT}ms`);
+      }, SWITCH_LENS_TIMEOUT)
+    });
+    const ok = await switchLens(devId, skill.lenses[nextIndex]);
+    const pending = pendingSwitchStore.get(devId);
+    if ((pending === null || pending === void 0 ? void 0 : pending.seq) !== seq) return; // 已被超时 / 新的切换接管
+
+    if (!ok) {
+      takePendingSwitch(devId);
+      console.warn('[zoomTurntable] 切换镜头失败，读数已回滚', `${prevIndex} -> ${nextIndex}`);
+      setCurM(toDisplayZoom(skill, prevIndex, getLastD(devId)));
+      return;
+    }
+
+    // 下发成功不等于画面切完：收尾（归 1 倍 + 刷读数）留给 channelChange，
+    // 那时设备已经真的切过去了，画面不会先跳一下再稳定
+    if (!isChannelChangeSupported()) {
+      takePendingSwitch(devId);
+      settleLensSwitched(nextIndex);
+      return;
+    }
+
+    // 第二段超时：指令已被受理、只差事件 —— 此时**不能回滚**（物理镜头其实已经切了，
+    // 回滚读数只会和画面对不上），改为自己按下发结果收尾。
+    // 真机现状：设备侧暂未推 channelChange，切镜头基本都走到这里兜底
+    clearTimeout(pending.timer);
+    pending.timer = setTimeout(() => {
+      var _pendingSwitchStore$g;
+      if (((_pendingSwitchStore$g = pendingSwitchStore.get(devId)) === null || _pendingSwitchStore$g === void 0 ? void 0 : _pendingSwitchStore$g.seq) !== seq) return;
+      pendingSwitchStore.delete(devId);
+      // 走到这儿说明事件没在窗口内进 handler。定位顺序见下面这几条日志：
+      // 上面没有「channelChange 事件到达」→ 宿主没派发 / 方法名不对（看 dump）；
+      // 有到达但没有「镜头切换到位」→ 被 deviceId 或 channel 校验挡掉了
+      console.warn('[zoomTurntable] 等 channelChange 超时，按下发结果收尾', `${prevIndex} -> ${nextIndex}`, `channel=${skill.lenses[nextIndex].id}`, `${CHANNEL_SETTLE_TIMEOUT}ms`, `onChannelChange 可用=${isChannelChangeSupported()}`);
+      dumpChannelApis();
+      settleLensSwitched(nextIndex);
+    }, CHANNEL_SETTLE_TIMEOUT);
+  });
+
+  /** 拖动结束：按倍率匹配镜头后落地 */
+  const applyZoom = useMemoizedFn(async targetM => {
+    draggingRef.current = false;
+    const skill = skillRef.current;
+    if (!skill) return;
+    await applyToLens(matchLens(skill, targetM), targetM);
+  });
+
+  /** 点击倍率 tab：直接切到该镜头并归位到其光学倍数；不走 matchLens，免得容差判到相邻镜头 */
+  const switchToLens = useMemoizedFn(async index => {
+    var _skill$lenses2;
+    const skill = skillRef.current;
+    const lens = skill === null || skill === void 0 || (_skill$lenses2 = skill.lenses) === null || _skill$lenses2 === void 0 ? void 0 : _skill$lenses2[index];
+    if (!lens) return;
+    draggingRef.current = false;
+    await applyToLens(index, lens.basicRatio);
+  });
+
+  // ---------------- 镜头切换到位：channelChange ----------------
+  /**
+   * 切镜头的统一收尾入口：自己下发的（switchChannel）与外部来源（设备侧 / 其他端）都走这里。
+   * 自己下发的那次不在 switchChannel 回调里收尾，就是为了等这条事件 —— 设备真的切过去了再动画面。
+   */
+  const onChannelChange = useMemoizedFn(_ref => {
+    let {
+      channel
+    } = _ref;
+    const skill = skillRef.current;
+    if (!skill) {
+      console.warn('[zoomTurntable] 收到 channelChange 但镜头能力未就绪，已忽略', channel);
+      return;
+    }
+    const index = skill.lenses.findIndex(item => item.id === channel);
+    if (index < 0) {
+      console.warn('[zoomTurntable] channelChange 的 channel 不在镜头列表内', channel);
+      return;
+    }
+
+    // 自己下发的切换到位了，清掉超时兜底；此时镜头下标还没动过，不能按「和当前相同」早退
+    const pending = takePendingSwitch(devId);
+    if (!pending && index === lensIndexRef.current) {
+      console.log('[zoomTurntable] channelChange 指向当前镜头，无需处理', index);
+      return; // 外部来源的重复事件
+    }
+    console.log('[zoomTurntable] 镜头切换到位', `${lensIndexRef.current} -> ${index}`, pending ? '(本端下发)' : '(外部来源)');
+    // 读数以设备为准，进行中的拖动作废
+    draggingRef.current = false;
+    settleLensSwitched(index);
+  });
+  useEffect(() => {
+    // 订没订上必须能从日志看出来：没订上时切镜头一定走超时回滚，两者表象一样
+    if (skipLoad || !devId || !multiLensReady) {
+      console.log('[zoomTurntable] 跳过 channelChange 订阅', `skipLoad=${skipLoad}`, `devId=${devId || '(空)'}`, `multiLensReady=${multiLensReady}`);
+      return undefined;
+    }
+    // 订阅前先把宿主 ty.ipc 上 channel 相关的方法名打出来：事件收不到时先排除「方法名不对」
+    dumpChannelApis();
+    return subscribeChannelChange(devId, onChannelChange);
+  }, [devId, multiLensReady, skipLoad, onChannelChange]);
+
+  // ---------------- 回读：d → curM，并处理手势跨临界点 ----------------
+
+  /**
+   * 手势缩放（双指缩放播放器，非转盘）跨临界点时自动切镜头。
+   *
+   * zoomLevelChange 高频上报，按协议 §4.4 用 trailing 防抖等手势停下再判定；
+   * 待 APP 提供 zoomFree 的「手势是否结束」参数（§4.3 第 5 条）后可去掉防抖。
+   */
+  const scheduleGestureLensSwitch = useMemoizedFn(value => {
+    if (gestureTimerRef.current) clearTimeout(gestureTimerRef.current);
+    gestureTimerRef.current = setTimeout(() => {
+      gestureTimerRef.current = undefined;
+      const skill = skillRef.current;
+      if (!skill || draggingRef.current || isSwitching(devId)) return;
+      const nextIndex = matchLens(skill, value);
+      if (nextIndex === lensIndexRef.current) return;
+      console.log('[zoomTurntable] 手势跨临界点，切换镜头', `curM=${value.toFixed(2)}`, `${lensIndexRef.current} -> ${nextIndex}`);
+      applyToLens(nextIndex, value);
+    }, GESTURE_SWITCH_DEBOUNCE);
+  });
+  const onZoomLevelChange = useMemoizedFn(d => {
+    if (!(d > 0)) return;
+    setLastD(devId, d);
+    // 切镜头途中的中间态不算数（收尾时统一关掉），拖动中画面还没动
+    if (draggingRef.current || isSwitching(devId)) return;
+    const skill = skillRef.current;
+    if (!skill) return;
+    // 手势缩放不经过 applyToLens，小窗只能从这条回读上判定
+    syncSmallMonitorByD(d);
+    const next = toDisplayZoom(skill, lensIndexRef.current, d);
+    setCurM(next);
+    event.emit(zoomTurntableZoomChange, {
+      curM: next,
+      d,
+      lensIndex: lensIndexRef.current
+    });
+    scheduleGestureLensSwitch(next);
+  });
+  useEffect(() => {
+    if (!multiLensReady) return undefined;
+    event.on(zoomLevelChange, onZoomLevelChange);
+    return () => {
+      event.off(zoomLevelChange, onZoomLevelChange);
+    };
+  }, [event, multiLensReady, onZoomLevelChange]);
+  useEffect(() => {
+    return () => {
+      if (gestureTimerRef.current) clearTimeout(gestureTimerRef.current);
+    };
+  }, []);
+  const [min, max] = zoomSkill ? zoomBounds(zoomSkill) : [D_MIN, D_MIN];
+  return {
+    /** 是否具备多镜头变焦能力（不具备则整个 widget 不出现） */
+    multiLensReady,
+    zoomSkill,
+    /** 镜头列表（按 value 升序），用于渲染倍率 tab */
+    lenses: (_zoomSkill$lenses$sli = zoomSkill === null || zoomSkill === void 0 || (_zoomSkill$lenses = zoomSkill.lenses) === null || _zoomSkill$lenses === void 0 ? void 0 : _zoomSkill$lenses.slice(0, lensCount(zoomSkill))) !== null && _zoomSkill$lenses$sli !== void 0 ? _zoomSkill$lenses$sli : [],
+    lensIndex: zoomLensIndex,
+    /** 画面绝对倍率 */
+    curM,
+    min,
+    max,
+    // 步进直接取协议配置值（不做二次加工），各镜头可各自声明不同精度
+    step: (_zoomSkill$lenses$zoo = zoomSkill === null || zoomSkill === void 0 || (_zoomSkill$lenses2 = zoomSkill.lenses) === null || _zoomSkill$lenses2 === void 0 || (_zoomSkill$lenses2 = _zoomSkill$lenses2[zoomLensIndex]) === null || _zoomSkill$lenses2 === void 0 ? void 0 : _zoomSkill$lenses2.step) !== null && _zoomSkill$lenses$zoo !== void 0 ? _zoomSkill$lenses$zoo : DEFAULT_STEP,
+    marks: zoomSkill ? buildMarks(zoomSkill) : [],
+    /** 次刻度值：逐镜头区间按各自 step 生成，间距逐段不同 */
+    ticks: zoomSkill ? buildTickValues(zoomSkill) : [],
+    beginDrag,
+    applyZoom,
+    switchToLens
+  };
+};

package/lib/widgets/zoomTurntable/zoomTurntableDock.d.ts

@@ -0,0 +1,17 @@
+import React from 'react';
+import { ComponentConfigProps } from '../../interface';
+import './zoomTurntableDock.less';
+type Props = ComponentConfigProps & {
+    /** 由 ui.tsx 的 CoverView 分支注入（absolute-item-container） */
+    className?: string;
+};
+/**
+ * 焦距转盘浮层。
+ *
+ * 必须由 CoverView 承载（Entry 里 addContent 不设 absoluteNoCoverView）：
+ * 播放器是原生组件、层级高于普通 View，放在普通 View 里的 canvas 会被它盖住，
+ * touchstart 到不了 canvas，转盘完全滑不动（实测 setupEventListeners 成功但无任何 touch 日志）。
+ * 定位与层级由承载的 CoverView 通过 absolutePosition 提供。
+ */
+export declare const ZoomTurntableDock: (props: Props) => React.JSX.Element | null;
+export {};