@aiquants/virtualscroll 2.4.0 → 2.5.0

package/dist/useWheelBridge.d.cts

@@ -0,0 +1,64 @@
+import { RefCallback, RefObject } from 'react';
+/**
+ * Anything that can apply a wheel event with the pane's own rules.
+ * ペイン自身の規則でホイールイベントを適用できるもの。
+ *
+ * `VirtualScrollHandle` と `ScrollPaneHandle` の両方が構造的にこれを満たすため、どちらのハンドルでも
+ * 同じフックが使える (`ScrollPane` を直接使う消費側が橋渡しを自作せずに済む)。
+ */
+export type WheelBridgeTarget = {
+    applyWheel: (event: WheelEvent) => boolean;
+};
+/**
+ * Options for {@link useWheelBridge}.
+ * {@link useWheelBridge} のオプション。
+ */
+export type WheelBridgeOptions = {
+    /**
+     * Set to `false` to detach the bridge without unmounting the element.
+     * 要素をアンマウントせずに橋渡しを止めたいとき `false` にする。既定 `true`。
+     */
+    enableBridge?: boolean;
+};
+/**
+ * Bridges wheel events from an element outside the pane into the list, with the pane's own semantics.
+ * ペイン外の要素のホイールを、ペイン自身と同じ意味論で一覧へ橋渡しするフック。
+ *
+ * 返り値を対象要素の `ref` に渡すだけでよい。
+ *
+ * ```tsx
+ * const listRef = useRef<VirtualScrollHandle>(null)
+ * const headerRef = useWheelBridge(listRef)
+ *
+ * <div ref={headerRef}>列ヘッダー (ペインの外)</div>
+ * <VirtualScroll ref={listRef} onWheelHorizontal={setScrollX} ... />
+ * ```
+ *
+ * ❗ **ホイールの意味論に影響する設定は一切受け取らないのが意図的な設計である。** 速度倍率・
+ * 横成分の委譲先・スクロール可否・慣性停止・軸分解のすべては、ハンドルの向こう側 (`applyWheel`) が
+ * 持つ。橋渡し側にも同じ設定口を用意すると同じグリッドなのに「ヘッダー帯の上だけスクロールが遅い」
+ * 「帯の上でだけ横に動かない」といった食い違いが静かに生まれる (橋渡し側にも設定口を置いた
+ * 実装途中の版で実測: `wheelSpeedMultiplier: 3` のとき同じ 1 ノッチがペイン上 30px / 帯の上 10px)。
+ * 唯一のオプション {@link WheelBridgeOptions.enableBridge} は意味論ではなく**橋渡し自体の ON/OFF** である。
+ * このフックの責務は **`{ passive: false }` での登録・後始末・その ON/OFF だけ**である。
+ *
+ * ❗ **`onWheel` プロップでは代用できない。** React 19 は `onWheel` を passive リスナーとして登録するため
+ * `preventDefault()` が効かず、ページ全体がスクロールしてしまう。
+ *
+ * ❗ **`handle.scrollTo` で自前に橋渡ししてはならない。** あれはジャンプ用 API で、絶対位置を丸めるため
+ * 1px 未満のデルタが消え、さらにスクロールアンカーを張るためサイズ変化のたびに一覧が過去の位置へ戻る。
+ *
+ * 自前の ref も必要なら合成してよい (多重登録に対して安全に作ってある)。
+ * ❗ **戻り値をそのまま `return` すること。** React 19 はこれをクリーンアップとして実行する。
+ * 返さない場合も動作は正しいままだが、`null` 呼び出しでは何も外さない設計のため、リスナーは
+ * 要素ごと GC されるまで残る。
+ *
+ * ```tsx
+ * <div ref={(node) => { myRef.current = node; return headerRef(node) }} />
+ * ```
+ *
+ * @param target - Ref to the list's imperative handle (`VirtualScrollHandle` / `ScrollPaneHandle`) / 一覧の命令ハンドルへの ref
+ * @param options - Bridge options / 橋渡しのオプション
+ * @returns A ref callback to attach to the source element / 発生元の要素へ渡す ref コールバック
+ */
+export declare const useWheelBridge: (target: RefObject<WheelBridgeTarget | null>, options?: WheelBridgeOptions) => RefCallback<HTMLElement>;

package/dist/useWheelBridge.d.ts

@@ -0,0 +1,65 @@
+import { RefCallback, RefObject } from 'react';
+/**
+ * Anything that can apply a wheel event with the pane's own rules.
+ * ペイン自身の規則でホイールイベントを適用できるもの。
+ *
+ * `VirtualScrollHandle` と `ScrollPaneHandle` の両方が構造的にこれを満たすため、どちらのハンドルでも
+ * 同じフックが使える (`ScrollPane` を直接使う消費側が橋渡しを自作せずに済む)。
+ */
+export type WheelBridgeTarget = {
+    applyWheel: (event: WheelEvent) => boolean;
+};
+/**
+ * Options for {@link useWheelBridge}.
+ * {@link useWheelBridge} のオプション。
+ */
+export type WheelBridgeOptions = {
+    /**
+     * Set to `false` to detach the bridge without unmounting the element.
+     * 要素をアンマウントせずに橋渡しを止めたいとき `false` にする。既定 `true`。
+     */
+    enableBridge?: boolean;
+};
+/**
+ * Bridges wheel events from an element outside the pane into the list, with the pane's own semantics.
+ * ペイン外の要素のホイールを、ペイン自身と同じ意味論で一覧へ橋渡しするフック。
+ *
+ * 返り値を対象要素の `ref` に渡すだけでよい。
+ *
+ * ```tsx
+ * const listRef = useRef<VirtualScrollHandle>(null)
+ * const headerRef = useWheelBridge(listRef)
+ *
+ * <div ref={headerRef}>列ヘッダー (ペインの外)</div>
+ * <VirtualScroll ref={listRef} onWheelHorizontal={setScrollX} ... />
+ * ```
+ *
+ * ❗ **ホイールの意味論に影響する設定は一切受け取らないのが意図的な設計である。** 速度倍率・
+ * 横成分の委譲先・スクロール可否・慣性停止・軸分解のすべては、ハンドルの向こう側 (`applyWheel`) が
+ * 持つ。橋渡し側にも同じ設定口を用意すると同じグリッドなのに「ヘッダー帯の上だけスクロールが遅い」
+ * 「帯の上でだけ横に動かない」といった食い違いが静かに生まれる (橋渡し側にも設定口を置いた
+ * 実装途中の版で実測: `wheelSpeedMultiplier: 3` のとき同じ 1 ノッチがペイン上 30px / 帯の上 10px)。
+ * 唯一のオプション {@link WheelBridgeOptions.enableBridge} は意味論ではなく**橋渡し自体の ON/OFF** である。
+ * このフックの責務は **`{ passive: false }` での登録・後始末・その ON/OFF だけ**である。
+ *
+ * ❗ **`onWheel` プロップでは代用できない。** React 19 は `onWheel` を passive リスナーとして登録するため
+ * `preventDefault()` が効かず、ページ全体がスクロールしてしまう。
+ *
+ * ❗ **`handle.scrollTo` で自前に橋渡ししてはならない。** あれはジャンプ用 API で、絶対位置を丸めるため
+ * 1px 未満のデルタが消え、さらにスクロールアンカーを張るためサイズ変化のたびに一覧が過去の位置へ戻る。
+ *
+ * 自前の ref も必要なら合成してよい (多重登録に対して安全に作ってある)。
+ * ❗ **戻り値をそのまま `return` すること。** React 19 はこれをクリーンアップとして実行する。
+ * 返さない場合も動作は正しいままだが、`null` 呼び出しでは何も外さない設計のため、リスナーは
+ * 要素ごと GC されるまで残る。
+ *
+ * ```tsx
+ * <div ref={(node) => { myRef.current = node; return headerRef(node) }} />
+ * ```
+ *
+ * @param target - Ref to the list's imperative handle (`VirtualScrollHandle` / `ScrollPaneHandle`) / 一覧の命令ハンドルへの ref
+ * @param options - Bridge options / 橋渡しのオプション
+ * @returns A ref callback to attach to the source element / 発生元の要素へ渡す ref コールバック
+ */
+export declare const useWheelBridge: (target: RefObject<WheelBridgeTarget | null>, options?: WheelBridgeOptions) => RefCallback<HTMLElement>;
+//# sourceMappingURL=useWheelBridge.d.ts.map

package/dist/useWheelBridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useWheelBridge.d.ts","sourceRoot":"","sources":["../src/useWheelBridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,SAAS,EAAwC,MAAM,OAAO,CAAA;AAE9F;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC5B,UAAU,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAA;CAC7C,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC7B;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;CACzB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,eAAO,MAAM,cAAc,GAAI,QAAQ,SAAS,CAAC,iBAAiB,GAAG,IAAI,CAAC,EAAE,UAAU,kBAAkB,KAAG,WAAW,CAAC,WAAW,CA+DjI,CAAA"}

package/dist/wheelAxes.d.cts

@@ -0,0 +1,48 @@
+/**
+ * @module wheelAxes
+ * @description Single source of truth for how a wheel event is split into scroll axes.
+ * Used only by `ScrollPane.applyWheel`, which is itself the single seam every wheel caller goes
+ * through, so the rules cannot drift between the pane and elements outside it.
+ *
+ * @description ホイールイベントをスクロール軸へ分解する規則の単一の真実。呼び出し元は
+ * `ScrollPane.applyWheel` **だけ**であり、その `applyWheel` がすべてのホイール呼び出し元
+ * (ペイン根のリスナー / `useWheelBridge` / 消費側の直接呼び出し) の唯一のシームなので、
+ * ペイン内外で規則が食い違わない。
+ *
+ * ❗ **公開 API ではない** (`index.ts` から export しない)。公開すると `LINE_HEIGHT_PX = 16`・
+ * 同値時の横倒し・4 フィールドの形が恒久的に凍結される。
+ */
+/**
+ * Wheel axes resolved from a raw wheel event.
+ * 生のホイールイベントから解決した軸情報。
+ */
+export type ResolvedWheelAxes = {
+    /** True when ctrl is held, i.e. the browser treats it as zoom. Deltas are still reported as-is. / ctrl 押下 (ブラウザがズームとして扱う) の場合に true。デルタはそのまま報告する。 */
+    isZoomGesture: boolean;
+    /** True when the horizontal component dominates (includes shift+wheel). / 横成分が優勢な場合に true (shift+ホイールを含む)。 */
+    isHorizontalDominant: boolean;
+    /** Horizontal delta in px (deltaMode already converted). / px 単位の横方向デルタ (deltaMode 変換済み)。 */
+    horizontalDelta: number;
+    /** Vertical delta in px (deltaMode already converted). / px 単位の縦方向デルタ (deltaMode 変換済み)。 */
+    verticalDelta: number;
+};
+/**
+ * Splits a wheel event into scroll axes, in pixels, applying the package's gesture rules.
+ * ホイールイベントを px 単位の軸へ分解し、本パッケージのジェスチャ規則を適用する処理。
+ *
+ * 規則 (判定順序そのものが仕様):
+ *
+ * 1. **shift+ホイール**は `deltaX === 0` のとき縦量を横として読む (Windows 系の慣習)。ブラウザが既に
+ *    `deltaX` へマップ済みなら通常の軸のまま扱う。
+ * 2. **横優勢判定**は横成分と縦成分の絶対値比較。等しい場合 (`|h| === |v|`) は横に倒す。ただし
+ *    **両軸とも 0 のときは横優勢としない** — 慣性の惰性通知で毎 tick 送られる 0/0 を横として
+ *    消費すると、ページ側のスクロールを無言で飲み込む。
+ *
+ * ❗ **これは解決器であって方針ではない。** `isZoomGesture` (ctrl 押下) が true でもデルタは
+ * そのまま返す。「ズームは横取りしない」という**方針**は適用側 (`ScrollPane.applyWheel`) が持つ。
+ *
+ * @param event - The wheel event / ホイールイベント
+ * @param viewportSize - Viewport length for `DOM_DELTA_PAGE` conversion / `DOM_DELTA_PAGE` 変換に使うビューポート長
+ * @returns The resolved axes / 解決した軸情報
+ */
+export declare const resolveWheelAxes: (event: WheelEvent, viewportSize: number) => ResolvedWheelAxes;

package/dist/wheelAxes.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @module wheelAxes
+ * @description Single source of truth for how a wheel event is split into scroll axes.
+ * Used only by `ScrollPane.applyWheel`, which is itself the single seam every wheel caller goes
+ * through, so the rules cannot drift between the pane and elements outside it.
+ *
+ * @description ホイールイベントをスクロール軸へ分解する規則の単一の真実。呼び出し元は
+ * `ScrollPane.applyWheel` **だけ**であり、その `applyWheel` がすべてのホイール呼び出し元
+ * (ペイン根のリスナー / `useWheelBridge` / 消費側の直接呼び出し) の唯一のシームなので、
+ * ペイン内外で規則が食い違わない。
+ *
+ * ❗ **公開 API ではない** (`index.ts` から export しない)。公開すると `LINE_HEIGHT_PX = 16`・
+ * 同値時の横倒し・4 フィールドの形が恒久的に凍結される。
+ */
+/**
+ * Wheel axes resolved from a raw wheel event.
+ * 生のホイールイベントから解決した軸情報。
+ */
+export type ResolvedWheelAxes = {
+    /** True when ctrl is held, i.e. the browser treats it as zoom. Deltas are still reported as-is. / ctrl 押下 (ブラウザがズームとして扱う) の場合に true。デルタはそのまま報告する。 */
+    isZoomGesture: boolean;
+    /** True when the horizontal component dominates (includes shift+wheel). / 横成分が優勢な場合に true (shift+ホイールを含む)。 */
+    isHorizontalDominant: boolean;
+    /** Horizontal delta in px (deltaMode already converted). / px 単位の横方向デルタ (deltaMode 変換済み)。 */
+    horizontalDelta: number;
+    /** Vertical delta in px (deltaMode already converted). / px 単位の縦方向デルタ (deltaMode 変換済み)。 */
+    verticalDelta: number;
+};
+/**
+ * Splits a wheel event into scroll axes, in pixels, applying the package's gesture rules.
+ * ホイールイベントを px 単位の軸へ分解し、本パッケージのジェスチャ規則を適用する処理。
+ *
+ * 規則 (判定順序そのものが仕様):
+ *
+ * 1. **shift+ホイール**は `deltaX === 0` のとき縦量を横として読む (Windows 系の慣習)。ブラウザが既に
+ *    `deltaX` へマップ済みなら通常の軸のまま扱う。
+ * 2. **横優勢判定**は横成分と縦成分の絶対値比較。等しい場合 (`|h| === |v|`) は横に倒す。ただし
+ *    **両軸とも 0 のときは横優勢としない** — 慣性の惰性通知で毎 tick 送られる 0/0 を横として
+ *    消費すると、ページ側のスクロールを無言で飲み込む。
+ *
+ * ❗ **これは解決器であって方針ではない。** `isZoomGesture` (ctrl 押下) が true でもデルタは
+ * そのまま返す。「ズームは横取りしない」という**方針**は適用側 (`ScrollPane.applyWheel`) が持つ。
+ *
+ * @param event - The wheel event / ホイールイベント
+ * @param viewportSize - Viewport length for `DOM_DELTA_PAGE` conversion / `DOM_DELTA_PAGE` 変換に使うビューポート長
+ * @returns The resolved axes / 解決した軸情報
+ */
+export declare const resolveWheelAxes: (event: WheelEvent, viewportSize: number) => ResolvedWheelAxes;
+//# sourceMappingURL=wheelAxes.d.ts.map

package/dist/wheelAxes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wheelAxes.d.ts","sourceRoot":"","sources":["../src/wheelAxes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC5B,qJAAqJ;IACrJ,aAAa,EAAE,OAAO,CAAA;IACtB,8GAA8G;IAC9G,oBAAoB,EAAE,OAAO,CAAA;IAC7B,6FAA6F;IAC7F,eAAe,EAAE,MAAM,CAAA;IACvB,2FAA2F;IAC3F,aAAa,EAAE,MAAM,CAAA;CACxB,CAAA;AAuBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,gBAAgB,GAAI,OAAO,UAAU,EAAE,cAAc,MAAM,KAAG,iBAgB1E,CAAA"}

package/dist/wheelConsumption.d.cts

@@ -0,0 +1,29 @@
+/**
+ * @module wheelConsumption
+ * @description Tracks which wheel events this package has already applied.
+ *
+ * @description 本パッケージが既に適用したホイールイベントを記録するモジュール。
+ *
+ * ❗ **`event.defaultPrevented` では代用できない。** あれは「誰かがこのイベントを止めた」であって
+ * 「**我々が**消費した」ではない。両者を混同すると、ページ全体のスクロールロック
+ * (`document` に capture + `preventDefault` を張る定番の実装) を掛けただけで一覧が
+ * まったくスクロールできなくなる。逆に印が無いと、ペインの入れ子や祖先に張った `useWheelBridge` で
+ * **同じデルタが 2 回適用**される (実測: 内側と外側の一覧が 1 ノッチで両方 100px 動く)。
+ *
+ * `WeakSet` なのでイベントオブジェクトの寿命を延ばさない。
+ */
+/**
+ * Marks a wheel event as applied by this package.
+ * ホイールイベントを「本パッケージが適用済み」として記録する処理。
+ *
+ * @param event - The wheel event that was applied / 適用したホイールイベント
+ */
+export declare const markWheelConsumed: (event: WheelEvent) => void;
+/**
+ * Reports whether this package already applied the given wheel event.
+ * 指定のホイールイベントを本パッケージが既に適用済みかどうかを返す処理。
+ *
+ * @param event - The wheel event to test / 判定するホイールイベント
+ * @returns True when it was already applied / 既に適用済みの場合に true
+ */
+export declare const wasWheelConsumed: (event: WheelEvent) => boolean;

package/dist/wheelConsumption.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @module wheelConsumption
+ * @description Tracks which wheel events this package has already applied.
+ *
+ * @description 本パッケージが既に適用したホイールイベントを記録するモジュール。
+ *
+ * ❗ **`event.defaultPrevented` では代用できない。** あれは「誰かがこのイベントを止めた」であって
+ * 「**我々が**消費した」ではない。両者を混同すると、ページ全体のスクロールロック
+ * (`document` に capture + `preventDefault` を張る定番の実装) を掛けただけで一覧が
+ * まったくスクロールできなくなる。逆に印が無いと、ペインの入れ子や祖先に張った `useWheelBridge` で
+ * **同じデルタが 2 回適用**される (実測: 内側と外側の一覧が 1 ノッチで両方 100px 動く)。
+ *
+ * `WeakSet` なのでイベントオブジェクトの寿命を延ばさない。
+ */
+/**
+ * Marks a wheel event as applied by this package.
+ * ホイールイベントを「本パッケージが適用済み」として記録する処理。
+ *
+ * @param event - The wheel event that was applied / 適用したホイールイベント
+ */
+export declare const markWheelConsumed: (event: WheelEvent) => void;
+/**
+ * Reports whether this package already applied the given wheel event.
+ * 指定のホイールイベントを本パッケージが既に適用済みかどうかを返す処理。
+ *
+ * @param event - The wheel event to test / 判定するホイールイベント
+ * @returns True when it was already applied / 既に適用済みの場合に true
+ */
+export declare const wasWheelConsumed: (event: WheelEvent) => boolean;
+//# sourceMappingURL=wheelConsumption.d.ts.map

package/dist/wheelConsumption.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wheelConsumption.d.ts","sourceRoot":"","sources":["../src/wheelConsumption.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,GAAI,OAAO,UAAU,KAAG,IAErD,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAAI,OAAO,UAAU,KAAG,OAAyC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiquants/virtualscroll",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "High-performance virtual scrolling component for React with variable item heights",
   "sideEffects": [
     "**/*.css"

package/src/ScrollPane.tsx

@@ -3,6 +3,8 @@ import { twMerge } from "tailwind-merge"
 import { Logger } from "./logger.ts"
 import { ScrollBar, type ScrollBarTapCircleOptions, type ScrollBarThumbOverlayRenderProps, TAP_SCROLL_CANCEL_EVENT } from "./ScrollBar.tsx"
 import { minmax } from "./utils.ts"
+import { resolveWheelAxes } from "./wheelAxes.ts"
+import { markWheelConsumed, wasWheelConsumed } from "./wheelConsumption.ts"
 
 /**
  * Props for the ScrollPane component.
@@ -236,6 +238,16 @@ export type ScrollPaneHandle = {
     getScrollPosition: () => number
     getContentSize: () => number
     getViewportSize: () => number
+    /**
+     * Applies one wheel event with the pane's own rules; returns whether it was consumed.
+     * ペイン自身の規則で 1 つのホイールイベントを適用し、消費したかどうかを返す。
+     *
+     * ペインの**外**に置いた要素 (列ヘッダー帯など) のホイールを、ペイン内と寸分違わぬ意味論で
+     * 流し込むための唯一の口。軸分解・速度倍率・スクロール可否・横委譲先・慣性停止のすべてが
+     * ペイン側の 1 箇所で決まるため、消費側が規則を書き直したり食い違わせたりできない。
+     * 直接使うより `useWheelBridge` (passive:false 登録と後始末込み) を推奨する。
+     */
+    applyWheel: (event: WheelEvent) => boolean
 }
 
 /**
@@ -465,6 +477,10 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
         // contentSize と viewportSize を ref として保持
         // const sizeRef = useRef({ contentSize, viewportSize })
 
+        // ❗ render 本体で代入する。layout effect へ移すと、サイズ変更と同じコミット内で走る
+        // 他の layout effect からの scrollTo が 1 コミット古い寸法でクランプされ、タップスクロールの
+        // 走破が短くなる (実機 E2E の等速性テストがサンプル数不足で落ちる形で退行が出る)。
+        // 既知の代償は下の wheelPolicyRef のコメントを参照。
         const sizeRef = useRef({ contentSize, viewportSize })
         sizeRef.current = { contentSize, viewportSize }
 
@@ -725,73 +741,132 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
             }
         }, [isScrollable, scrollTo, contentSize, viewportSize])
 
-        useEffect(() => {
-            // ホイールイベントのハンドラ
-            const handleWheel = (event: WheelEvent) => {
-                // ctrl+wheel はブラウザのズーム (ピンチズーム/ctrl+shift+ホイール等) なので横取りせず常に素通しする
-                if (event.ctrlKey) {
-                    return
-                }
+        // ホイール適用の方針値。保持されたハンドル越しの呼び出しでも凍結させないため ref で持つ。
+        //
+        // ❗ **代入のタイミングは `sizeRef` と必ず揃える。** 片方だけを layout effect にすると、
+        // 中断されたトランジション中に `applyWheel` は「スクロール可能」と判断して消費する一方、
+        // `scrollTo` は 1 コミット古い寸法でクランプして 0 を返す、という最悪の組み合わせになる
+        // (実測: 5,000 行の一覧が 1 ノッチで先頭へ飛び、以後 0 に貼り付く)。
+        //
+        // ❗ **既知の限界 (未修正)**: render 本体での ref 書き込みは、中断されたトランジションで
+        // **コミットされなかった値**を残す。その間のホイールは画面に出ていない寸法で判断されるため、
+        // 「スクロール可能な一覧なのにホイールが効かない」状態が保留中だけ起きる。両 ref を
+        // layout effect へ移すのが筋だが、それだけではタップスクロールの走破が 1 コミット遅れて
+        // 短くなる退行が出る (実機 E2E で実証済み)。恒久対応にはクランプ経路の見直しが必要。
+        const wheelPolicyRef = useRef({ isScrollable, viewportSize, wheelSpeedMultiplier })
+        wheelPolicyRef.current = { isScrollable, viewportSize, wheelSpeedMultiplier }
 
-                // Shiftキー押下による軸変換(deltaX=0, deltaY!=0) または 通常のdeltaX/deltaYから横優勢判定
-                const usesShiftAxis = event.shiftKey && event.deltaX === 0
-                const horizontalDelta = usesShiftAxis ? event.deltaY : event.deltaX
-                const verticalDelta = usesShiftAxis ? 0 : event.deltaY
-                const isHorizontalDominant = horizontalDelta !== 0 && Math.abs(horizontalDelta) >= Math.abs(verticalDelta)
+        /**
+         * Applies one wheel event with the pane's own rules and reports whether it was consumed.
+         *
+         * ペイン自身の規則で 1 つのホイールイベントを適用し、消費したかどうかを返す処理。
+         *
+         * ❗ **ホイールの意味論はここが単一の真実である。** ペイン根に張るリスナーも、ペインの外の要素へ
+         * 同じ意味論を与える `useWheelBridge` も、この 1 つの関数を通す。軸分解 (`resolveWheelAxes`) だけを
+         * 共有して残り (速度倍率・スクロール可否・横委譲先・慣性停止) を各所に書くと、同じグリッドなのに
+         * 「ヘッダー帯の上だけスクロールが遅い」といった食い違いが静かに生まれる (橋渡し側にも設定口を
+         * 置いた実装途中の版で実測: 倍率 3 のとき同じ 1 ノッチがペイン上 30px / 帯の上 10px)。
+         *
+         * 判定順序そのものが仕様:
+         *
+         * 0. 本パッケージが既に適用済みの印があれば何もしない (ペインの入れ子・祖先の橋渡しでの二重適用防止)
+         * 1. ctrl+wheel はブラウザのズームなので横取りせず素通しする
+         * 2. 横優勢 (shift+ホイールを含む) は `onWheelHorizontal` へ委譲。未指定なら消費せず祖先へ委ねる
+         * 3. スクロール不能なら消費しない
+         * 4. px 換算後の縦成分が 0 なら消費しない (適用できる量が無いのに祖先のスクロールを奪わない)
+         * 5. 消費済みの印 + `preventDefault()` + 慣性停止 + 速度倍率を掛けて相対スクロール
+         *
+         * @param event - The wheel event to apply / 適用するホイールイベント
+         * @returns True when this pane applied the event / このペインが適用した場合に true。
+         *          ❗ 適用時は `preventDefault()` も呼ぶが、`cancelable` でないイベント
+         *          (合成イベントの既定) では preventDefault は効かないため、返値は
+         *          「`defaultPrevented` になったか」ではなく「**適用したか**」を意味する
+         */
+        const applyWheel = useCallback(
+            (event: WheelEvent): boolean => {
+                // ❗ **このペイン群が既に消費したイベントは二度と適用しない。** 冪等性の規則を
+                // 適用シームの内側に置くことで、どの呼び出し元 (ペイン根のリスナー / useWheelBridge /
+                // 消費側の直接呼び出し) からも同じ保証が効く。
+                //
+                // ❗ `event.defaultPrevented` で代用してはならない。あれは「誰かが止めた」であって
+                // 「我々が消費した」ではない。ページ全体のスクロールロック (`document` に capture +
+                // preventDefault を張る定番の実装) と区別できず、ロック中に一覧が
+                // **まったくスクロールできなくなる** (実測)。
+                if (wasWheelConsumed(event)) {
+                    return false
+                }
+                // ❗ 値は ref から読む。lexical に閉じ込めると、消費側が保持したハンドルが
+                // **その時点の方針を凍結**する (実測: 一覧が絞り込みでスクロール不能になった後も
+                // 保持済みハンドルは preventDefault し続け、ページのスクロールを殺す)。
+                // `VirtualScrollHandle.applyWheel` は毎回 ref を辿るため凍結しない。両者の
+                // 非対称は `WheelBridgeTarget` が両方を等価に扱う設計と噛み合わない。
+                const { isScrollable: currentIsScrollable, viewportSize: currentViewportSize, wheelSpeedMultiplier: currentWheelSpeedMultiplier } = wheelPolicyRef.current
+                const axes = resolveWheelAxes(event, currentViewportSize)
+
+                // ❗ ctrl+wheel はブラウザのズーム (ピンチズーム/ctrl+shift+ホイール等) なので横取りせず常に素通しする。
+                // 解決器はデルタを潰さないため、この判定を外すと ctrl+shift+ホイールを横スクロールとして食う
+                if (axes.isZoomGesture) {
+                    return false
+                }
 
-                if (isHorizontalDominant) {
+                if (axes.isHorizontalDominant) {
                     // 横委譲コールバックが指定されている場合は横スクロールとして処理
                     if (onWheelHorizontalRef.current) {
+                        markWheelConsumed(event)
                         event.preventDefault()
                         stopInertia()
-                        let deltaX = horizontalDelta
-                        if (event.deltaMode === 1) {
-                            deltaX *= 16 // DOM_DELTA_LINE
-                        } else if (event.deltaMode === 2) {
-                            deltaX *= viewportSize // DOM_DELTA_PAGE
-                        }
-                        onWheelHorizontalRef.current(deltaX)
+                        onWheelHorizontalRef.current(axes.horizontalDelta)
+                        return true
                     }
                     // ハンドラ未指定時であっても、横優勢スクロールや Shift+ホイール は
                     // 縦スクロールとして横取りせず、親要素のネイティブ横スクロールへ委ねる
-                    return
+                    return false
                 }
 
-                if (!isScrollable) {
-                    return
+                if (!currentIsScrollable) {
+                    return false
                 }
 
                 // 縦方向の移動が無いホイール（水平スワイプ等）は祖先のスクロールへ委ねる
                 // A wheel event without vertical delta (e.g. horizontal swipe) is left to ancestor scrolling.
-                if (event.deltaY === 0) {
-                    return
+                //
+                // ❗ 判定は **px 換算後** の値で行う。`deltaMode: DOM_DELTA_PAGE` かつ帯が 0 のとき
+                // (自己計測の初回コミット等) 換算後は 0 になり、適用しても 1px も動かない。ここで
+                // `event.deltaY` (生値) を見ると preventDefault だけして何も起きず、**祖先のスクロールも
+                // 奪う**死角になる。「適用できる量が無いなら消費しない」に揃える。
+                if (axes.verticalDelta === 0) {
+                    return false
                 }
 
+                markWheelConsumed(event)
                 event.preventDefault()
-
                 stopInertia()
 
-                let deltaY = event.deltaY
-
-                // deltaMode に応じてスクロール量を調整
-                if (event.deltaMode === 1) {
-                    // DOM_DELTA_LINE: 行単位のスクロール
-                    const lineHeight = 16 // 1行のおおよその高さ (ピクセル)
-                    deltaY *= lineHeight
-                } else if (event.deltaMode === 2) {
-                    // DOM_DELTA_PAGE: ページ単位のスクロール
-                    deltaY *= viewportSize // ビューポートの高さを基準にスクロール
-                }
-
-                if (wheelSpeedMultiplier !== 1) {
-                    deltaY *= wheelSpeedMultiplier
+                let deltaY = axes.verticalDelta
+                if (currentWheelSpeedMultiplier !== 1) {
+                    deltaY *= currentWheelSpeedMultiplier
                 }
 
                 // ホットパスのためログ引数はサンクで遅延評価し、抑制時は DOM 読み取り (scrollTop) も発生させない
-                Logger.debug("[ScrollPane] wheel event", () => ({ deltaY, scrollPosition: scrollPositionRef.current, wheelSpeedMultiplier, deltaMode: event.deltaMode, scrollTop: contentAreaRef.current?.scrollTop }))
+                Logger.debug("[ScrollPane] wheel event", () => ({ deltaY, scrollPosition: scrollPositionRef.current, wheelSpeedMultiplier: currentWheelSpeedMultiplier, deltaMode: event.deltaMode, scrollTop: contentAreaRef.current?.scrollTop }))
 
                 // スクロール位置を更新
                 scrollTo((prev) => prev + deltaY)
+                return true
+            },
+            [scrollTo, stopInertia],
+        )
+
+        useEffect(() => {
+            // ホイールイベントのハンドラ (適用規則そのものは applyWheel が持つ)
+            //
+            // ❗ ここに `defaultPrevented` のガードを置いてはならない。ページ全体のスクロールロック
+            // (`document` に capture + preventDefault を張る定番の実装) を掛けただけで一覧が
+            // **まったくスクロールできなくなる** (実測: ガード無しではスクロールできる)。
+            // 二重適用の防止は `applyWheel` 内の「自分が消費した印」が担う (ペインの入れ子・
+            // 祖先の橋渡しのいずれも、印を見て 2 回目を弾く)。
+            const handleWheel = (event: WheelEvent) => {
+                applyWheel(event)
             }
 
             /**
@@ -825,7 +900,7 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
                     scrollContainer.removeEventListener("pointerdown", handlePaneInteraction, { capture: true })
                 }
             }
-        }, [isScrollable, scrollTo, stopInertia, viewportSize, wheelSpeedMultiplier])
+        }, [applyWheel, stopInertia])
 
         useImperativeHandle(
             ref,
@@ -837,8 +912,9 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
                 getScrollPosition: () => scrollPositionRef.current,
                 getContentSize: () => contentSize,
                 getViewportSize: () => viewportSize,
+                applyWheel,
             }),
-            [scrollTo, contentSize, viewportSize, stopInertia],
+            [scrollTo, contentSize, viewportSize, stopInertia, applyWheel],
         )
 
         const id = useId()