@ray-js/ipc-player-integration 0.0.50-beta.3 → 0.0.50-beta.4

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

@@ -57,6 +57,48 @@ export declare const QUERY_LENS_TIMEOUT = 3000;
  * 待 APP 提供 zoomFree 的「手势是否结束」参数后可改为由该参数触发。
  */
 export declare const GESTURE_SWITCH_DEBOUNCE = 500;
+/**
+ * 切镜头到位后，补下发目标倍率（d > 1）的延时（ms）。
+ *
+ * 新镜头的流刚起来，立刻打 scaleMultiple 有被原生层吞掉的风险；这段延时里的中间态回读
+ * 由 settleApplyStore 挡住，读数不会先闪回镜头正倍数。归正倍数（d = 1）不走延时，与旧行为一致。
+ */
+export declare const POST_SWITCH_APPLY_DELAY = 200;
+/**
+ * 补差值下发后，等回读追上目标 d 的最长时间（ms）。
+ * 超时解除中间态屏蔽 —— 原生层没按目标值回读时（量化、失败），读数不能被永久冻住。
+ */
+export declare const SETTLE_APPLY_TIMEOUT = 3000;
+/**
+ * 触底判定：连续多少帧 d ≈ 1 才认为「用户还在继续往下缩」。
+ *
+ * 取 2：第一帧是「正常缩到该镜头的光学正倍数」，从第二帧起 d 已经夹在协议下限动不了，
+ * 却仍有回读推上来，说明手指还在往里收。取 1 会把正常的「缩到正倍数」误判成越界。
+ */
+export declare const FLOOR_HIT_COUNT = 2;
+/** 触底计数的有效窗口（ms）：两帧间隔超过它就不算连续，计数重置 */
+export declare const FLOOR_HIT_WINDOW = 1200;
+/**
+ * 切镜头收尾后的触底静默期（ms）。
+ * 收尾自身的 emit(setScaleMultipleEvent, 1.0) 会引发一到两帧 d = 1 回读，
+ * 不挡掉就会被算进触底计数，刚切上去又被切回来。
+ */
+export declare const FLOOR_HIT_SETTLE_GUARD = 800;
+/** 相邻两次「触底自动下切镜头」的冷却（ms）：一次长手势不该连着切两级 */
+export declare const DOWN_SWITCH_COOLDOWN = 800;
+/**
+ * 同一次自动切镜头的跨实例去重窗口（ms）。
+ * Entry / Dock 各跑一份 useLensZoom，都订阅 zoomLevelChange，会同时判出同一次切换 ——
+ * 不去重就是两发 switchChannel。
+ */
+export declare const SWITCH_DEDUPE_WINDOW = 300;
+/**
+ * 转盘拖动跨镜头临界后，手停住多久（ms）就地切镜头。
+ *
+ * 逐帧切不行（switchChannel 是 P2P，几百毫秒级，会把通道打爆），只等松手也不行
+ * （拖过界的一路上画面是「冻」的）。折中：过界后手停住这么久就切，画面跟着拖动走。
+ */
+export declare const DRAG_CROSS_SWITCH_DELAY = 600;
 /** dock 层级，需高于四角容器的 z-index: 100 */
 export declare const ZOOM_DOCK_Z_INDEX = 120;
 /**

package/lib/widgets/zoomTurntable/constants.js

@@ -72,6 +72,56 @@ export const QUERY_LENS_TIMEOUT = 3000;
  */
 export const GESTURE_SWITCH_DEBOUNCE = 500;
 
+/**
+ * 切镜头到位后，补下发目标倍率（d > 1）的延时（ms）。
+ *
+ * 新镜头的流刚起来，立刻打 scaleMultiple 有被原生层吞掉的风险；这段延时里的中间态回读
+ * 由 settleApplyStore 挡住，读数不会先闪回镜头正倍数。归正倍数（d = 1）不走延时，与旧行为一致。
+ */
+export const POST_SWITCH_APPLY_DELAY = 200;
+
+/**
+ * 补差值下发后，等回读追上目标 d 的最长时间（ms）。
+ * 超时解除中间态屏蔽 —— 原生层没按目标值回读时（量化、失败），读数不能被永久冻住。
+ */
+export const SETTLE_APPLY_TIMEOUT = 3000;
+
+/**
+ * 触底判定：连续多少帧 d ≈ 1 才认为「用户还在继续往下缩」。
+ *
+ * 取 2：第一帧是「正常缩到该镜头的光学正倍数」，从第二帧起 d 已经夹在协议下限动不了，
+ * 却仍有回读推上来，说明手指还在往里收。取 1 会把正常的「缩到正倍数」误判成越界。
+ */
+export const FLOOR_HIT_COUNT = 2;
+
+/** 触底计数的有效窗口（ms）：两帧间隔超过它就不算连续，计数重置 */
+export const FLOOR_HIT_WINDOW = 1200;
+
+/**
+ * 切镜头收尾后的触底静默期（ms）。
+ * 收尾自身的 emit(setScaleMultipleEvent, 1.0) 会引发一到两帧 d = 1 回读，
+ * 不挡掉就会被算进触底计数，刚切上去又被切回来。
+ */
+export const FLOOR_HIT_SETTLE_GUARD = 800;
+
+/** 相邻两次「触底自动下切镜头」的冷却（ms）：一次长手势不该连着切两级 */
+export const DOWN_SWITCH_COOLDOWN = 800;
+
+/**
+ * 同一次自动切镜头的跨实例去重窗口（ms）。
+ * Entry / Dock 各跑一份 useLensZoom，都订阅 zoomLevelChange，会同时判出同一次切换 ——
+ * 不去重就是两发 switchChannel。
+ */
+export const SWITCH_DEDUPE_WINDOW = 300;
+
+/**
+ * 转盘拖动跨镜头临界后，手停住多久（ms）就地切镜头。
+ *
+ * 逐帧切不行（switchChannel 是 P2P，几百毫秒级，会把通道打爆），只等松手也不行
+ * （拖过界的一路上画面是「冻」的）。折中：过界后手停住这么久就切，画面跟着拖动走。
+ */
+export const DRAG_CROSS_SWITCH_DELAY = 600;
+
 /** dock 层级，需高于四角容器的 z-index: 100 */
 export const ZOOM_DOCK_Z_INDEX = 120;
 

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

@@ -33,8 +33,16 @@ export declare const toleranceOf: (skill: ZoomSkill, index: number) => number;
 export declare const DEFAULT_STEP = 0.1;
 /**
  * 画面倍率 → 目标镜头下标。
- * 容差取各镜头自己的 step；同时命中多个区间时取大镜头，避免临界处反复横跳。
- * 代价：临界带会被判到大镜头，画面至多向上吸附一个 step。
+ *
+ * **严格命中优先**：半开区间 [lo, hi)，最后一个镜头取闭区间 —— 2.9 判短焦、3.0 判长焦。
+ * 临界点本身仍归大镜头（3.0 是长焦的 basicRatio），但临界点**以下**不再被吸上去。
+ *
+ * 曾用「双向 ±step 容差 + 同时命中取大镜头」，那会让 [2.9, 3.0) 整条带子粘在长焦上：
+ * 转盘拖到 2.9 松手时 matchLens 判回长焦、不切镜头，而长焦画面最小只能到 3.0，
+ * 于是读数显示 2.9、画面停在 3.0，两者对不上。触底下切的目标值正好落在这条带子里，
+ * 所以这个吸附必须去掉。
+ *
+ * 容差退化为兜底：只在严格命中不到时用（浮点毛刺、越界值），此时才「同时命中取大镜头」。
  */
 export declare const matchLens: (skill: ZoomSkill, curM: number) => number;
 /** 由镜头 id 反查下标 */

package/lib/widgets/zoomTurntable/lensModel.js

@@ -68,20 +68,37 @@ export const DEFAULT_STEP = 0.1;
 
 /**
  * 画面倍率 → 目标镜头下标。
- * 容差取各镜头自己的 step；同时命中多个区间时取大镜头，避免临界处反复横跳。
- * 代价：临界带会被判到大镜头，画面至多向上吸附一个 step。
+ *
+ * **严格命中优先**：半开区间 [lo, hi)，最后一个镜头取闭区间 —— 2.9 判短焦、3.0 判长焦。
+ * 临界点本身仍归大镜头（3.0 是长焦的 basicRatio），但临界点**以下**不再被吸上去。
+ *
+ * 曾用「双向 ±step 容差 + 同时命中取大镜头」，那会让 [2.9, 3.0) 整条带子粘在长焦上：
+ * 转盘拖到 2.9 松手时 matchLens 判回长焦、不切镜头，而长焦画面最小只能到 3.0，
+ * 于是读数显示 2.9、画面停在 3.0，两者对不上。触底下切的目标值正好落在这条带子里，
+ * 所以这个吸附必须去掉。
+ *
+ * 容差退化为兜底：只在严格命中不到时用（浮点毛刺、越界值），此时才「同时命中取大镜头」。
  */
 export const matchLens = (skill, curM) => {
-  let hit = 0;
   const count = lensCount(skill);
+  if (count <= 0) return 0;
+  for (let i = 0; i < count; i++) {
+    const [lo, hi] = lensRange(skill, i);
+    const isLast = i === count - 1;
+    if (curM >= lo && (isLast ? curM <= hi : curM < hi)) return i;
+  }
+
+  // 严格命中不到：用各镜头自己的 step 作容差吸附，同时命中取大镜头
+  let hit = -1;
   for (let i = 0; i < count; i++) {
     const [lo, hi] = lensRange(skill, i);
     const tolerance = toleranceOf(skill, i);
-    if (curM >= lo - tolerance && curM <= hi + tolerance) {
-      hit = i;
-    }
+    if (curM >= lo - tolerance && curM <= hi + tolerance) hit = i;
   }
-  return hit;
+  if (hit >= 0) return hit;
+
+  // 彻底在倍率域之外：夹到最近的一端
+  return curM < lensRange(skill, 0)[0] ? 0 : count - 1;
 };
 
 /** 由镜头 id 反查下标 */

package/lib/widgets/zoomTurntable/lensModel.test.js

@@ -167,16 +167,20 @@ describe('镜头匹配', () => {
     expect(matchLens(DOUBLE, 4.0)).toBe(1);
     expect(matchLens(DOUBLE, 6.0)).toBe(1);
   });
-  it('临界点归大镜头，避免横跳', () => {
-    // 3.0 同时落在 lens0 [1,3] 与 lens1 [3,6]，取 basicRatio 大者
+  it('临界点本身归大镜头，避免横跳', () => {
+    // 半开区间 [lo, hi)：3.0 是 lens1 的下界，归长焦
     expect(matchLens(DOUBLE, 3.0)).toBe(1);
   });
-  it('容差取镜头 step（0.1）：2.9 起进长焦，2.8 仍在短焦', () => {
-    expect(matchLens(DOUBLE, 2.9)).toBe(1); // 2.9 在 lens1 的 [2.9, 6.1] 容差内 → 归大镜头
-    expect(matchLens(DOUBLE, 2.8)).toBe(0); // 超出 lens1 容差下界 → 短焦
+  it('临界点以下不再被吸到大镜头：2.9 判短焦', () => {
+    // 旧实现双向 ±step 容差会让 [2.9, 3.0) 整条带子粘在长焦上，于是
+    // 转盘拖到 2.9 松手时不切镜头、画面被夹在 3.0，读数与画面对不上。
+    // 触底下切的落位（上限 − 1 step）正好在这条带子里，必须判成短焦。
+    expect(matchLens(DOUBLE, 2.9)).toBe(0);
+    expect(matchLens(DOUBLE, 2.99)).toBe(0);
     expect(matchLens(DOUBLE, 3.1)).toBe(1);
   });
-  it('容差随各镜头 step 变化，未声明 step 时用缺省 0.1', () => {
+  it('容差退化为兜底：只在严格命中不到（越界）时吸附', () => {
+    // 区间内一律严格命中，step 多粗都不影响归属
     const coarse = {
       cnt: 2,
       thresholds: [1.0, 3.0, 6.0],
@@ -194,7 +198,7 @@ describe('镜头匹配', () => {
       ]
     };
     expect(toleranceOf(coarse, 1)).toBe(0.5);
-    expect(matchLens(coarse, 2.6)).toBe(1); // 落在 lens1 的 [2.5, 6.5] 内
+    expect(matchLens(coarse, 2.6)).toBe(0);
     expect(matchLens(coarse, 2.4)).toBe(0);
     const noStep = {
       cnt: 2,
@@ -210,14 +214,22 @@ describe('镜头匹配', () => {
       }]
     };
     expect(toleranceOf(noStep, 1)).toBe(DEFAULT_MATCH_TOLERANCE);
-    expect(matchLens(noStep, 2.9)).toBe(1);
+    expect(matchLens(noStep, 2.9)).toBe(0);
     expect(matchLens(noStep, 2.8)).toBe(0);
+
+    // 越界值：严格命中不到，用容差吸到相邻镜头
+    expect(matchLens(DOUBLE, 6.05)).toBe(1);
+    expect(matchLens(DOUBLE, 0.95)).toBe(0);
+    // 彻底在域外：夹到最近的一端
+    expect(matchLens(DOUBLE, 0.1)).toBe(0);
+    expect(matchLens(DOUBLE, 99)).toBe(1);
   });
   it('三目：跨两次临界点', () => {
     expect(matchLens(TRIPLE, 1.5)).toBe(0);
     expect(matchLens(TRIPLE, 4.0)).toBe(1);
     expect(matchLens(TRIPLE, 9.0)).toBe(2);
     expect(matchLens(TRIPLE, 6.0)).toBe(2); // 临界归大
+    expect(matchLens(TRIPLE, 5.9)).toBe(1); // 临界以下留在中焦
   });
   it('镜头 id 反查下标', () => {
     expect(indexOfLensId(DOUBLE, 1)).toBe(1);

package/lib/widgets/zoomTurntable/useLensZoom.js

@@ -6,7 +6,7 @@ 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, lensRange, matchLens, maxScaleMultiple, toDisplayZoom, toScaleMultiple, zoomBounds } from './lensModel';
-import { CHANNEL_SETTLE_TIMEOUT, D_MATCH_EPS, GESTURE_SWITCH_DEBOUNCE, SWITCH_LENS_TIMEOUT, ZOOM_PREVIEW_THROTTLE, zoomTurntableLensChange, zoomTurntableSwitching, zoomTurntableZoomChange } from './constants';
+import { CHANNEL_SETTLE_TIMEOUT, DOWN_SWITCH_COOLDOWN, DRAG_CROSS_SWITCH_DELAY, D_MATCH_EPS, FLOOR_HIT_COUNT, FLOOR_HIT_SETTLE_GUARD, FLOOR_HIT_WINDOW, GESTURE_SWITCH_DEBOUNCE, POST_SWITCH_APPLY_DELAY, SETTLE_APPLY_TIMEOUT, SWITCH_DEDUPE_WINDOW, SWITCH_LENS_TIMEOUT, ZOOM_PREVIEW_THROTTLE, zoomTurntableLensChange, zoomTurntableSwitching, zoomTurntableZoomChange } from './constants';
 /**
  * 内部调试开关：置 true 时用 MOCK_ZOOM_SKILL 顶替 ipc_multi_zoom 的上报值。
  *
@@ -42,6 +42,37 @@ const pendingSwitchStore = new Map();
  */
 const smallMonitorStore = new Map();
 
+/**
+ * 切镜头收尾后正在补下发的目标 d（按 devId）。
+ *
+ * 收尾时读数 / tab 已经按目标值落地，画面却要等 setScaleMultiple 走完才到位；
+ * 中间原生层会先把画面复位到 1 倍并回读一帧。不挡掉的话读数会先闪回镜头正倍数再跳到目标值。
+ */
+const settleApplyStore = new Map();
+
+/** 触底计数（按 devId）：画面已夹在 d = 1、用户还在继续缩小的连续帧数 */
+const floorHitStore = new Map();
+
+/** 最近一次切镜头收尾的时间（按 devId）：收尾自身的 d = 1 回读不算触底 */
+const settledAtStore = new Map();
+
+/** 最近一次「触底自动下切」的时间（按 devId）：冷却用 */
+const downSwitchAtStore = new Map();
+
+/** 最近一次切镜头下发（按 devId）：Entry / Dock 两份 hook 判出同一次切换时去重 */
+const switchReqStore = new Map();
+
+/**
+ * 是否有转盘正在被拖动（按 devId）。
+ *
+ * 组件内的 draggingRef 只挡自己那份的回读，管不到别的实例：拖动中 previewZoom 会把
+ * 夹住的 d 连续下发，回读到 Entry 那份就成了「一直在推 d = 1」，正好被触底判定当成
+ * 「用户还在往下缩」，于是拖动落地和触底下切会同时切镜头。拖动路径自带落地逻辑，
+ * 手势那套自动切镜头必须整体让路，所以这个标记要跨实例共享。
+ */
+const draggingStore = new Map();
+const isDraggingAnywhere = devId => draggingStore.get(devId) === true;
+
 /** 自增序号：连着切到同一个镜头时，靠它认出「pending 还是不是我这次的」 */
 let switchSeq = 0;
 /** 是否正在切镜头（屏蔽回读用） */
@@ -55,6 +86,46 @@ const takePendingSwitch = devId => {
   return pending;
 };
 
+/**
+ * 补差值下发期间的中间态回读要丢掉。
+ *
+ * 只丢「d ≈ 1」这一种 —— 那是原生层切完通道后画面自己的复位帧。ui.tsx 里
+ * 「先对齐 actual 再设 target」产生的那一帧已被它自己的 alignPending 抑制，不会到这儿。
+ * 收到任何非复位值就认为补差值已落地，解除屏蔽。
+ */
+const shouldDropSettleEcho = (devId, d) => {
+  const applying = settleApplyStore.get(devId);
+  if (!applying) return false;
+  if (Date.now() > applying.expireAt) {
+    // 原生层没按目标值回读（量化 / 下发失败），不能把读数永久冻住
+    console.warn('[zoomTurntable] 补差值回读超时，解除中间态屏蔽', applying.d);
+    settleApplyStore.delete(devId);
+    return false;
+  }
+  if (Math.abs(d - D_MIN) <= D_MATCH_EPS) return true;
+  settleApplyStore.delete(devId);
+  return false;
+};
+
+/**
+ * 抢一次切镜头的下发权。
+ * Entry / Dock 都订阅 zoomLevelChange，同一帧回读会让两份 hook 判出同一次切换；
+ * 不去重就是两发 switchChannel（第二发还会把第一发的 pending 作废，读数更乱）。
+ */
+const claimSwitch = (devId, index) => {
+  const last = switchReqStore.get(devId);
+  const now = Date.now();
+  if (last && last.index === index && now - last.at < SWITCH_DEDUPE_WINDOW) {
+    console.log('[zoomTurntable] 同一次切镜头已由另一实例下发，跳过', index);
+    return false;
+  }
+  switchReqStore.set(devId, {
+    index,
+    at: now
+  });
+  return true;
+};
+
 /**
  * 焦距能力与双层缩放状态机。
  * zoomSkill / zoomLensIndex 存在 ctx 共享 atom 上，Entry / Dock / RealTimeMagnification 读同一份。
@@ -101,6 +172,19 @@ export const useLensZoom = options => {
   const gestureTimerRef = useRef();
   /** 拖动中连续下发的节流时间戳 */
   const previewAtRef = useRef(0);
+  /** 触底下切的 trailing 防抖（等手指停下再切，免得和正在进行的手势打架） */
+  const downTimerRef = useRef();
+  /** 拖动跨界后「手停住」的 trailing 防抖 */
+  const dragCrossTimerRef = useRef();
+
+  /**
+   * 自动切镜头（手势触底 / 跨临界）的驱动方：只由能力加载方（Entry）负责。
+   *
+   * Entry / Dock 各跑一份 hook，都订阅 zoomLevelChange。触底判定是**按帧计数**的，
+   * 两份都计数会让阈值形同减半；Entry 常驻（转盘展开时它只是被 CSS 藏起来，没卸载），
+   * 拿它当唯一驱动方最稳。拖动路径反过来只有 Dock 有，各管一段互不重叠。
+   */
+  const isAutoSwitchDriver = !skipLoad;
   const lensIndexRef = useRef(zoomLensIndex);
   lensIndexRef.current = zoomLensIndex;
   const skillRef = useRef(zoomSkill);
@@ -238,42 +322,79 @@ export const useLensZoom = options => {
   });
   const beginDrag = useMemoizedFn(value => {
     draggingRef.current = true;
+    draggingStore.set(devId, true);
     setCurM(value);
-    previewZoom(value);
+    // 切镜头进行中（拖动跨界会在手指还按着时切）：画面归收尾流程管，这里只更新读数
+    if (!isSwitching(devId)) previewZoom(value);
+    scheduleDragCross(value);
   });
 
   /**
-   * 镜头已切到 index 后的收尾：画面比例主动归 1 倍，读数即该镜头的 basicRatio。
+   * 镜头已切到 index 后的收尾：把画面落到目标倍率上（**补差值**），读数与 tab 同步。
+   *
    * 正常路径由 channelChange 触发（等设备真正切完再动画面，中间态更干净）；
    * 宿主不支持该事件时，退回 switchChannel 成功即收尾。
+   *
+   * @param targetM 目标画面绝对倍率。本端下发的切换都会带（从 pendingSwitch 取），
+   *   落位就是用户实际要的那个值：转盘拖到 2.5 就落 2.5、手势停在 3.5 就落 3.5、
+   *   触底下切落「上一镜头上限 − 1 step」。**不带**时才归该镜头的光学正倍数 ——
+   *   只有外部来源（设备侧 / 其他端切镜头）走这条，那时本端没有目标值可言。
+   *
+   *   早期设计是「切镜头一律归 1 倍、不补差值」，那会让下切必然掉到新镜头的 basicRatio：
+   *   从 3.0 往下拖到 2.5，切到短焦后画面直接变成 1.0，跨度大到像是坏了。
    */
-  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);
+  const settleLensSwitched = useMemoizedFn((index, targetM) => {
+    var _skill$lenses;
+    const skill = skillRef.current;
+    const lens = skill === null || skill === void 0 || (_skill$lenses = skill.lenses) === null || _skill$lenses === void 0 ? void 0 : _skill$lenses[index];
+    if (!skill || !lens) return;
+    // 目标值夹进新镜头区间：跨界落点可能略微越界（容差、浮点毛刺）
+    const [lo, hi] = lensRange(skill, index);
+    const finalM = targetM == null ? lens.basicRatio : Math.min(hi, Math.max(lo, targetM));
+    const d = toScaleMultiple(skill, index, finalM);
+    const isBase = d <= D_MIN + D_MATCH_EPS;
+    console.log('[scaleMultiple] zoomTurntable 切镜头收尾', `lensIndex=${index}`, `finalM=${finalM.toFixed(2)}`, `d=${d.toFixed(3)}`, isBase ? '(归正倍数)' : '(补差值)', `lastD=${getLastD(devId)}`);
+
+    // 状态先落地：读数 / tab 立刻对齐，不等画面下发走完 P2P
+    syncToLens(index, d);
     markSwitching(-1);
-    // 切镜头即回到该镜头的光学正倍数，小窗关掉（onChannelChange / 超时兜底都会走到这里）
-    applySmallMonitor(false);
+    settledAtStore.set(devId, Date.now());
+    floorHitStore.delete(devId);
+    // 小窗跟最终 d 走：补差值后 d > 1（画面不在正倍数上），小窗该开着 ——
+    // 旧实现无条件 applySmallMonitor(false)，补差值后就与画面状态不符了
+    syncSmallMonitorByD(d);
     event.emit(zoomTurntableLensChange, {
       lensId: lens.id,
       lensIndex: index,
-      value: lens.basicRatio
+      value: finalM
     });
     event.emit(zoomTurntableZoomChange, {
-      curM: lens.basicRatio,
-      d: D_MIN,
+      curM: finalM,
+      d,
       lensIndex: index
     });
+    if (isBase) {
+      // 归正倍数：与旧行为一致，立即下发
+      event.emit(setScaleMultipleEvent, D_MIN);
+      return;
+    }
+    // 补差值：新流刚起来，立刻打 scaleMultiple 有被吞的风险，延一拍；
+    // 这段窗口内的复位帧回读由 settleApplyStore 挡掉
+    settleApplyStore.set(devId, {
+      d,
+      expireAt: Date.now() + SETTLE_APPLY_TIMEOUT
+    });
+    setTimeout(() => {
+      console.log('[scaleMultiple] zoomTurntable 补差值下发', d, `lensIndex=${index}`);
+      event.emit(setScaleMultipleEvent, d);
+    }, POST_SWITCH_APPLY_DELAY);
   });
 
   /** 把目标倍率落到指定镜头上：同镜头内下发本地缩放，跨镜头则切物理镜头并归 1 倍 */
   const applyToLens = useMemoizedFn(async (nextIndex, targetM) => {
-    var _skill$lenses;
+    var _skill$lenses2;
     const skill = skillRef.current;
-    if (!(skill !== null && skill !== void 0 && (_skill$lenses = skill.lenses) !== null && _skill$lenses !== void 0 && _skill$lenses[nextIndex])) return;
+    if (!(skill !== null && skill !== void 0 && (_skill$lenses2 = skill.lenses) !== null && _skill$lenses2 !== void 0 && _skill$lenses2[nextIndex])) return;
     setCurM(targetM);
     const prevIndex = lensIndexRef.current;
     if (nextIndex === prevIndex) {
@@ -290,6 +411,9 @@ export const useLensZoom = options => {
       return;
     }
 
+    // Entry / Dock 同一帧判出同一次切换时只放一次过（读数已在上面各自更新过）
+    if (!claimSwitch(devId, nextIndex)) return;
+
     // 切物理镜头：从下发到 channelChange 回来这段屏蔽回读
     console.log('[zoomTurntable] 切换镜头', `${prevIndex} -> ${nextIndex}`, `channel=${skill.lenses[nextIndex].id}`, `targetM=${targetM.toFixed(2)}`);
     takePendingSwitch(devId); // 上一次没结算完的直接作废，以最新这次为准
@@ -305,6 +429,7 @@ export const useLensZoom = options => {
     pendingSwitchStore.set(devId, {
       seq,
       index: nextIndex,
+      targetM,
       timer: setTimeout(() => {
         pendingSwitchStore.delete(devId);
         markSwitching(-1);
@@ -328,7 +453,7 @@ export const useLensZoom = options => {
     // 那时设备已经真的切过去了，画面不会先跳一下再稳定
     if (!isChannelChangeSupported()) {
       takePendingSwitch(devId);
-      settleLensSwitched(nextIndex);
+      settleLensSwitched(nextIndex, targetM);
       return;
     }
 
@@ -345,10 +470,49 @@ export const useLensZoom = options => {
       // 有到达但没有「镜头切换到位」→ 被 deviceId 或 channel 校验挡掉了
       console.warn('[zoomTurntable] 等 channelChange 超时，按下发结果收尾', `${prevIndex} -> ${nextIndex}`, `channel=${skill.lenses[nextIndex].id}`, `${CHANNEL_SETTLE_TIMEOUT}ms`, `onChannelChange 可用=${isChannelChangeSupported()}`);
       dumpChannelApis();
-      settleLensSwitched(nextIndex);
+      settleLensSwitched(nextIndex, targetM);
     }, CHANNEL_SETTLE_TIMEOUT);
   });
 
+  /**
+   * 拖动跨镜头临界：过界后**手停住** DRAG_CROSS_SWITCH_DELAY 就地切镜头，画面跟着拖动走。
+   *
+   * previewZoom 把下发值夹在当前镜头区间内，所以拖过界之后画面是「冻」住的 ——
+   * 只等松手才切的话，从 3.0 往下拖到 2.5 的一路上画面纹丝不动，手感像是没响应。
+   * 逐帧切也不行：switchChannel 是 P2P、几百毫秒级，逐帧下发会把通道打爆。
+   * 折中成 trailing 防抖：值一直在变就一直不切，停住才切。
+   *
+   * 切换期间 draggingRef 保持 true（见 onChannelChange 里的说明），松手后 applyZoom
+   * 再按最终值落一次 —— 那时镜头通常已经对了，走的是同镜头内下发 d 的分支。
+   */
+  const scheduleDragCross = useMemoizedFn(value => {
+    const clearPending = () => {
+      if (dragCrossTimerRef.current) {
+        clearTimeout(dragCrossTimerRef.current);
+        dragCrossTimerRef.current = undefined;
+      }
+    };
+    const skill = skillRef.current;
+    if (!skill) return;
+    // 回到当前镜头区间内 / 已在切换中：撤掉待切
+    if (matchLens(skill, value) === lensIndexRef.current || isSwitching(devId)) {
+      clearPending();
+      return;
+    }
+    clearPending();
+    dragCrossTimerRef.current = setTimeout(() => {
+      dragCrossTimerRef.current = undefined;
+      // 已松手 → 交给 applyZoom 落地，不在这儿抢
+      if (!draggingRef.current || isSwitching(devId)) return;
+      const cur = skillRef.current;
+      if (!cur) return;
+      const nextIndex = matchLens(cur, value);
+      if (nextIndex === lensIndexRef.current) return;
+      console.log('[zoomTurntable] 拖动跨界停留，就地切镜头', `${lensIndexRef.current} -> ${nextIndex}`, `targetM=${value.toFixed(2)}`);
+      applyToLens(nextIndex, value);
+    }, DRAG_CROSS_SWITCH_DELAY);
+  });
+
   /**
    * 拖动状态兜底复位。
    *
@@ -359,11 +523,22 @@ export const useLensZoom = options => {
    */
   const endDrag = useMemoizedFn(() => {
     draggingRef.current = false;
+    draggingStore.delete(devId);
+    if (dragCrossTimerRef.current) {
+      clearTimeout(dragCrossTimerRef.current);
+      dragCrossTimerRef.current = undefined;
+    }
   });
 
   /** 拖动结束：按倍率匹配镜头后落地 */
   const applyZoom = useMemoizedFn(async targetM => {
     draggingRef.current = false;
+    draggingStore.delete(devId);
+    // 松手即是最终值，待切的那次作废，直接按最终值走
+    if (dragCrossTimerRef.current) {
+      clearTimeout(dragCrossTimerRef.current);
+      dragCrossTimerRef.current = undefined;
+    }
     const skill = skillRef.current;
     if (!skill) return;
     await applyToLens(matchLens(skill, targetM), targetM);
@@ -371,11 +546,12 @@ export const useLensZoom = options => {
 
   /** 点击倍率 tab：直接切到该镜头并归位到其光学倍数；不走 matchLens，免得容差判到相邻镜头 */
   const switchToLens = useMemoizedFn(async index => {
-    var _skill$lenses2;
+    var _skill$lenses3;
     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];
+    const lens = skill === null || skill === void 0 || (_skill$lenses3 = skill.lenses) === null || _skill$lenses3 === void 0 ? void 0 : _skill$lenses3[index];
     if (!lens) return;
     draggingRef.current = false;
+    draggingStore.delete(devId);
     await applyToLens(index, lens.basicRatio);
   });
 
@@ -406,9 +582,11 @@ export const useLensZoom = options => {
       return; // 外部来源的重复事件
     }
     console.log('[zoomTurntable] 镜头切换到位', `${lensIndexRef.current} -> ${index}`, pending ? '(本端下发)' : '(外部来源)');
-    // 读数以设备为准，进行中的拖动作废
-    draggingRef.current = false;
-    settleLensSwitched(index);
+    // 只有外部来源（设备侧 / 其他端）才作废进行中的拖动 —— 读数得以设备为准。
+    // 本端下发的那次不能动 draggingRef：拖动跨界会在**手指还按着**的时候切镜头，
+    // 置 false 会放开回读屏蔽，回读帧和拖动帧互相打架，指针会抖。
+    if (!pending) draggingRef.current = false;
+    settleLensSwitched(index, pending === null || pending === void 0 ? void 0 : pending.targetM);
   });
   useEffect(() => {
     // 订没订上必须能从日志看出来：没订上时切镜头一定走超时回滚，两者表象一样
@@ -434,15 +612,94 @@ export const useLensZoom = options => {
     gestureTimerRef.current = setTimeout(() => {
       gestureTimerRef.current = undefined;
       const skill = skillRef.current;
-      if (!skill || draggingRef.current || isSwitching(devId)) return;
+      if (!skill || draggingRef.current || isDraggingAnywhere(devId) || 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);
   });
+
+  /**
+   * 触底继续缩 → 往下切一个镜头（trailing 防抖，等手指停下再切）。
+   *
+   * 现象：在非首个镜头上把画面缩到该镜头的光学正倍数后（d = 1，协议下限），用户继续
+   * 双指往里收，播放器的 d 已经夹住动不了，画面纹丝不动，读数也停在 basicRatio。
+   * 此时 zoomLevelChange 仍然按帧推 d = 1 上来 —— 这就是唯一可用的信号
+   * （detail.scaleMode「自由缩放状态标识」实测不准，不能拿来判定）。
+   *
+   * 落位取「上一个镜头区间上限 − 1 step」（如 3.0 → 2.9）：那正是画面能继续变小的第一格，
+   * 换算到短焦上是 d ≈ 3.85，用户接着往里收就能顺畅地一路缩到 1.0。
+   */
+  const scheduleDownSwitch = useMemoizedFn(() => {
+    var _downSwitchAtStore$ge;
+    if (Date.now() - ((_downSwitchAtStore$ge = downSwitchAtStore.get(devId)) !== null && _downSwitchAtStore$ge !== void 0 ? _downSwitchAtStore$ge : 0) < DOWN_SWITCH_COOLDOWN) return;
+    if (downTimerRef.current) clearTimeout(downTimerRef.current);
+    downTimerRef.current = setTimeout(() => {
+      var _skill$lenses$target$, _skill$lenses4;
+      downTimerRef.current = undefined;
+      const skill = skillRef.current;
+      const index = lensIndexRef.current;
+      if (!skill || index <= 0) return;
+      if (draggingRef.current || isDraggingAnywhere(devId) || isSwitching(devId)) return;
+      // 防抖这 500ms 里可能又被放大了，切之前再确认画面确实还夹在正倍数上
+      if (getLastD(devId) > D_MIN + D_MATCH_EPS) {
+        floorHitStore.delete(devId);
+        return;
+      }
+      const target = index - 1;
+      const [, upper] = lensRange(skill, target);
+      const stepOfTarget = (_skill$lenses$target$ = (_skill$lenses4 = skill.lenses) === null || _skill$lenses4 === void 0 || (_skill$lenses4 = _skill$lenses4[target]) === null || _skill$lenses4 === void 0 ? void 0 : _skill$lenses4.step) !== null && _skill$lenses$target$ !== void 0 ? _skill$lenses$target$ : DEFAULT_STEP;
+      const targetM = upper - stepOfTarget;
+      downSwitchAtStore.set(devId, Date.now());
+      floorHitStore.delete(devId);
+      console.log('[zoomTurntable] 触底继续缩，向下切镜头', `${index} -> ${target}`, `targetM=${targetM.toFixed(2)}`);
+      applyToLens(target, targetM);
+    }, GESTURE_SWITCH_DEBOUNCE);
+  });
+
+  /**
+   * 触底计数。返回 true 表示已排下切，本帧不再走上界 / 防抖那套判定。
+   * 只由驱动方计数 —— 两份 hook 都数会让阈值形同减半。
+   */
+  const handleFloorHit = useMemoizedFn(d => {
+    var _settledAtStore$get;
+    if (!isAutoSwitchDriver) return false;
+    // 拖动中：落地由 applyZoom / 跨界停留负责，触底那套整体让路
+    if (isDraggingAnywhere(devId)) {
+      floorHitStore.delete(devId);
+      return false;
+    }
+    // 不在正倍数上：正常缩放，清计数
+    if (d > D_MIN + D_MATCH_EPS) {
+      floorHitStore.delete(devId);
+      return false;
+    }
+    // 首个镜头已经是倍率域下界，再缩没有镜头可切
+    if (lensIndexRef.current <= 0) return false;
+    const now = Date.now();
+    // 收尾自身会引发一到两帧 d = 1 回读，静默期内不计数，否则刚切上去又被切回来
+    if (now - ((_settledAtStore$get = settledAtStore.get(devId)) !== null && _settledAtStore$get !== void 0 ? _settledAtStore$get : 0) < FLOOR_HIT_SETTLE_GUARD) return false;
+    const prev = floorHitStore.get(devId);
+    const count = prev && now - prev.lastAt <= FLOOR_HIT_WINDOW ? prev.count + 1 : 1;
+    floorHitStore.set(devId, {
+      count,
+      lastAt: now
+    });
+    // 每一帧都打：真机上「触底还缩不缩得动」全靠这条日志判断 ——
+    // 如果原生只在 d 真正变化时才推事件，这里会永远停在 count=1、下切一次都不会触发，
+    // 那就说明这条信号不成立，得改由 APP 侧补「手势下界」参数（协议 §4.3 第 5 条）
+    console.log('[zoomTurntable] 触底回读', `count=${count}/${FLOOR_HIT_COUNT}`, `lensIndex=${lensIndexRef.current}`);
+    // 第一帧是「正常缩到正倍数」，从第二帧起才是「夹住了还在缩」
+    if (count < FLOOR_HIT_COUNT) return false;
+    console.log('[zoomTurntable] 画面已夹在正倍数仍有缩放回读，排下切', `count=${count}`);
+    scheduleDownSwitch();
+    return true;
+  });
   const onZoomLevelChange = useMemoizedFn(d => {
     if (!(d > 0)) return;
+    // 补差值下发期间原生画面会先复位到 1 倍，那一帧不能让它把读数拽回镜头正倍数
+    if (shouldDropSettleEcho(devId, d)) return;
     setLastD(devId, d);
     // 切镜头途中的中间态不算数（收尾时统一关掉），拖动中画面还没动
     if (draggingRef.current || isSwitching(devId)) return;
@@ -458,6 +715,13 @@ export const useLensZoom = options => {
       lensIndex: lensIndexRef.current
     });
 
+    // 触底继续缩：往下切一个镜头（下界，与下面的上界对称）
+    if (handleFloorHit(d)) return;
+    if (!isAutoSwitchDriver) return;
+    // 拖动中：previewZoom 把下发值夹在当前镜头区间内，回读会一直贴着区间边界，
+    // 不让路的话「触到上界立即切」会和拖动跨界停留同时切镜头
+    if (isDraggingAnywhere(devId)) return;
+
     // 画面已经顶到当前镜头区间的上界（也就是下一个镜头的光学倍数，如 1x 镜头放到 3.0）：
     // 这个边界值在归属上属于下一个镜头，必须立刻切过去。
     // 走 trailing 防抖的话，那 500ms 里 tab 会挂着「下一镜头的值」显示在当前镜头上。
@@ -484,6 +748,8 @@ export const useLensZoom = options => {
   useEffect(() => {
     return () => {
       if (gestureTimerRef.current) clearTimeout(gestureTimerRef.current);
+      if (downTimerRef.current) clearTimeout(downTimerRef.current);
+      if (dragCrossTimerRef.current) clearTimeout(dragCrossTimerRef.current);
     };
   }, []);
   const [min, max] = zoomSkill ? zoomBounds(zoomSkill) : [D_MIN, D_MIN];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ray-js/ipc-player-integration",
-  "version": "0.0.50-beta.3",
+  "version": "0.0.50-beta.4",
   "description": "IPC 融合播放器",
   "main": "lib/index",
   "files": [