@aiquants/virtualscroll 2.3.0 → 2.5.0

package/src/ScrollPane.tsx

@@ -1,8 +1,10 @@
-import { forwardRef, useCallback, useEffect, useId, useImperativeHandle, useLayoutEffect, useMemo, useRef } from "react"
+import { forwardRef, useCallback, useEffect, useId, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState } from "react"
 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.
@@ -25,8 +27,32 @@ export type ScrollPaneProps = {
     children: (scrollPosition: number) => React.ReactNode
     /** The total size of the content. / コンテンツの総サイズ。 */
     contentSize: number
-    /** The size of the visible area. / 表示領域のサイズ。 */
-    viewportSize: number
+    /**
+     * Size of the visible band (px). Omit it to let the pane measure its own band.
+     * 可視帯の高さ (px)。省略するとペインが自分の帯を計測する。
+     *
+     * ❗ **省略が既定の使い方である。** この値は帯のクリップ窓・最大スクロール位置・つまみ写像・
+     * 描画枚数・スクロール可否のすべての基準であり、実際の帯と食い違うと 5 通りの壊れ方が
+     * **例外も警告も出さずに**発生する (はみ出し / 死に帯 / 末尾へ到達不能 / つまみが視野外へ /
+     * ホイールとドラッグの無効化)。自分で測れるものを消費側に渡させると、同じ正解を各画面で
+     * 書き直すことになり、実際に推測値や定数が代入される。
+     *
+     * 省略時は `.aqvs-scroll-pane-content` の実高さ (CSS の `height: 100%` が決める) を
+     * `ResizeObserver` で追跡する。**ホスト側がルート要素の高さを確定させること**が前提で
+     * (`h-full` / `flex-1` + `min-h-0` / 明示 px / `position: absolute` など)、高さが auto の
+     * ホストでは帯が 0 のままになる (開発ビルドで警告する)。
+     *
+     * 明示する正当なケースは「帯の高さを計測ではなく算出で知っている」場合のみである
+     * (例: ドロップダウンが件数 × 行高から高さを決める)。
+     */
+    viewportSize?: number
+    /**
+     * Notified when the self-measured viewport size changes (not called while `viewportSize` is given).
+     * 自己計測したビューポート高さが変化したときに通知する (`viewportSize` 指定時は呼ばれない)。
+     *
+     * 帯の数値を必要とする親 (`VirtualScroll` は描画枚数とアライン計算に使う) がこの口で受け取る。
+     */
+    onViewportSizeChange?: (viewportSize: number) => void
     /** The width of the scrollbar. / スクロールバーの幅。 */
     scrollBarWidth?: number
     /** Whether grabbing the scrollbar thumb is allowed. / スクロールバーのつまみ操作を許可するかどうか。 */
@@ -212,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
 }
 
 /**
@@ -224,7 +260,8 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
         {
             children,
             contentSize,
-            viewportSize,
+            viewportSize: viewportSizeProp,
+            onViewportSizeChange,
             scrollBarWidth = 12,
             enableThumbDrag = true,
             enableTrackClick = true,
@@ -256,6 +293,140 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
         const scrollPositionRef = useRef(Number.isFinite(initialScrollPosition) ? Math.max(0, initialScrollPosition) : 0)
         const scrollContainerRef = useRef<HTMLDivElement>(null)
         const contentAreaRef = useRef<HTMLDivElement>(null)
+
+        // viewportSize 未指定なら自分の帯を計測する。以降のすべての計算はこの解決済み値 (viewportSize) を使う。
+        // ❗ ScrollPane が持つ唯一の State であり、変化するのは**ホストの帯が変わったときだけ**である
+        // (スクロール中には一切変化しない)。ホットパスで setState しないという設計 (§1.1) は保たれる。
+        const isSelfMeasuringViewport = viewportSizeProp === undefined
+        const [measuredViewportSize, setMeasuredViewportSize] = useState(0)
+        const viewportSize = viewportSizeProp ?? measuredViewportSize
+        // 同一内容の警告を繰り返さないための最後の警告キー。
+        const lastViewportWarningRef = useRef<string | null>(null)
+
+        /**
+         * Tracks the real height of the content band so the pane can size itself.
+         * ペインが自分の帯の実高さを追跡し、自己サイズ決定できるようにする副作用。
+         *
+         * 計測対象は**コンテンツ要素**である。自己計測モードではこの要素へ高さのインラインスタイルを
+         * 書かず、CSS の `height: 100%` (= ルートの確定高さ) がレイアウトを所有するため、
+         * 「計測した数値を書き戻して自分のサイズを変える」フィードバックループが構造的に起こらない。
+         * ルート要素を測ると、消費側がルートへ付けた padding の分だけ帯を過大評価してしまう。
+         *
+         * ❗ **0 の計測は採用しない。** `display: none` のタブに置かれている等でレイアウトされて
+         * いないとき `offsetHeight` は 0 になる。0 を採ると `isScrollable` が偽になり、サイズ調整
+         * エフェクト (§9) が `scrollTo(0)` を発行して**タブ切替でスクロール位置が失われる**。
+         * 0 は「帯が 0」ではなく「まだ測れない」と解釈し、直前の値を保つ。
+         *
+         * 目的: 自己計測モードで帯の高さを State へ反映する。
+         * 依存関係: [contentSize, isSelfMeasuringViewport]
+         * クリーンアップ: ResizeObserver を切断する。
+         */
+        useLayoutEffect(() => {
+            if (!isSelfMeasuringViewport) {
+                return
+            }
+            const element = contentAreaRef.current
+            if (!element) {
+                return
+            }
+            // ResizeObserver の通知は layout の後・paint の前に届くため、ここでの読み取りは強制リフローにならない。
+            // transform: scale(...) の下でもレイアウト px を得るため rect ではなく offsetHeight を使う (整数丸め)。
+            const applyMeasuredSize = () => {
+                const measured = element.offsetHeight
+                if (measured > 0) {
+                    setMeasuredViewportSize((previous) => (previous === measured ? previous : measured))
+                    return
+                }
+                // offsetParent が null なら display: none 等で非表示 = 正常な未計測状態なので黙る。
+                // レイアウトされているのに 0 の場合はホストが高さを確定させていない (自己計測の前提破り)。
+                if (element.offsetParent !== null && contentSize > 0 && lastViewportWarningRef.current !== "zero") {
+                    lastViewportWarningRef.current = "zero"
+                    Logger.warn("[ScrollPane] The self-measured viewport is 0px. Give the scroll pane's host element a definite height (e.g. h-full, flex-1 + min-h-0, an explicit px height), or pass viewportSize explicitly.")
+                }
+            }
+            applyMeasuredSize()
+            if (typeof ResizeObserver !== "function") {
+                return
+            }
+            const observer = new ResizeObserver(applyMeasuredSize)
+            observer.observe(element)
+            return () => {
+                observer.disconnect()
+            }
+        }, [contentSize, isSelfMeasuringViewport])
+
+        /**
+         * Publishes the self-measured viewport size to the owner.
+         * 自己計測したビューポート高さを所有者へ通知する副作用。
+         *
+         * ❗ layout effect である。`VirtualScroll` は描画枚数とアライン計算にこの数値を使うため、
+         * paint 前に通知しないと初回フレームだけ 1 行しか描かれない見た目になる。
+         *
+         * 目的: 親が帯の数値を保持できるようにする。
+         * 依存関係: [isSelfMeasuringViewport, measuredViewportSize, onViewportSizeChange]
+         * クリーンアップ: 不要。
+         */
+        useLayoutEffect(() => {
+            if (!isSelfMeasuringViewport) {
+                return
+            }
+            onViewportSizeChange?.(measuredViewportSize)
+        }, [isSelfMeasuringViewport, measuredViewportSize, onViewportSizeChange])
+
+        /**
+         * Warns when an explicitly passed viewportSize disagrees with the host's real band.
+         * 明示された viewportSize がホストの実際の帯と食い違うときに警告する副作用。
+         *
+         * ❗ 食い違いは**例外も視覚的な破綻もなく**進行し、はみ出し / 死に帯 / 末尾へ到達不能 /
+         * つまみが視野外 / ホイールとドラッグの無効化を引き起こす。検知できるのはここだけである。
+         *
+         * 比較対象はルート要素の `clientHeight` である。コンテンツ要素は明示モードでは
+         * `height: viewportSize` を書かれているため測っても同義反復になる。ホストが高さを
+         * 確定させていない (auto) 場合はルートも `viewportSize` に一致するので警告は出ない
+         * — その場合は食い違い自体が存在しないため正しい。
+         *
+         * `Logger.warn` を無条件に使う (NODE_ENV で切らない): 単一ビルドを配布しており
+         * `process.env` の置換は消費側のバンドラ任せで信頼できないうえ、既存の誤用警告
+         * (`useLruCache` の無効容量、`scrollTo` の非有限値) と同じ扱いに揃えるため。
+         *
+         * 目的: 帯との食い違いを検知して通知する。
+         * 依存関係: [isSelfMeasuringViewport, viewportSize]
+         * クリーンアップ: ResizeObserver を切断する。
+         */
+        useLayoutEffect(() => {
+            if (isSelfMeasuringViewport) {
+                return
+            }
+            const element = scrollContainerRef.current
+            if (!element) {
+                return
+            }
+            const warnOnMismatch = () => {
+                const actual = element.clientHeight
+                // 0 は非表示 (display: none 等) の未計測状態なので比較しない。
+                if (actual <= 0 || Math.abs(actual - viewportSize) <= 1) {
+                    return
+                }
+                const key = `${viewportSize}/${actual}`
+                if (lastViewportWarningRef.current === key) {
+                    return
+                }
+                lastViewportWarningRef.current = key
+                Logger.warn(
+                    `[ScrollPane] viewportSize=${viewportSize} but the host band is ${actual}px. The clip window, max scroll position, thumb mapping, rendered row count and scrollability all derive from viewportSize, so they are now wrong. Omit viewportSize to let the pane measure itself.`,
+                )
+            }
+            warnOnMismatch()
+            if (typeof ResizeObserver !== "function") {
+                return
+            }
+            const observer = new ResizeObserver(warnOnMismatch)
+            observer.observe(element)
+            return () => {
+                observer.disconnect()
+            }
+        }, [isSelfMeasuringViewport, viewportSize])
+
         // 横委譲コールバックは ref 経由で参照し、wheel リスナの再登録を避ける。
         const onWheelHorizontalRef = useRef(onWheelHorizontal)
         useEffect(() => {
@@ -306,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 }
 
@@ -566,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)
             }
 
             /**
@@ -666,7 +900,7 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
                     scrollContainer.removeEventListener("pointerdown", handlePaneInteraction, { capture: true })
                 }
             }
-        }, [isScrollable, scrollTo, stopInertia, viewportSize, wheelSpeedMultiplier])
+        }, [applyWheel, stopInertia])
 
         useImperativeHandle(
             ref,
@@ -678,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()
@@ -1225,8 +1460,14 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
             [scrollTo, stopInertia],
         )
 
+        // ❗ 自己計測モードではルートに `data-self-measured` を出し、パッケージ CSS の
+        // `.aqvs-scroll-pane[data-self-measured="true"] { height: 100% }` でホストの帯まで伸ばす。
+        // 明示モードでは content のインライン高さがルートを押し広げるためルート自身に高さは不要だが、
+        // 高さを書かない自己計測モードでは「ルート auto → content の `height: 100%` が auto へ解決
+        // → 帯 0」に潰れる (実ブラウザで実測)。インラインで書かず data 属性 + クラスにするのは、
+        // 消費側が CSS で上書きできる状態を保つため (状態は data-* とパッケージ CSS で表現する方針)。
         return (
-            <div ref={scrollContainerRef} data-testid={testId} className={twMerge("aqvs-scroll-pane", className)} style={style}>
+            <div ref={scrollContainerRef} data-testid={testId} data-self-measured={isSelfMeasuringViewport ? "true" : undefined} className={twMerge("aqvs-scroll-pane", className)} style={style}>
                 <div
                     ref={contentAreaRef}
                     className={twMerge("aqvs-scroll-pane-content")}
@@ -1235,7 +1476,11 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
                     // コンテンツ領域には prop が無いため、パッケージ側で固定値を出す
                     data-testid="aqvs-scroll-pane-content"
                     style={{
-                        height: viewportSize,
+                        // ❗ 自己計測モードでは高さを書かない。CSS の `height: 100%` (= ルートの確定高さ) が
+                        // レイアウトを所有することで、「計測した値を書き戻して自分のサイズを変える」
+                        // フィードバックループが構造的に起こらず、初回 paint の時点でも帯は実寸で正しい
+                        // (数値の反映だけが 1 コミット遅れる)。明示モードは従来どおり px を書く。
+                        height: isSelfMeasuringViewport ? undefined : viewportSize,
                         paddingTop: resolvedInsets.top,
                         paddingBottom: resolvedInsets.bottom,
                         // スクロール不能時 (contentSize <= viewportSize) は touch-action を通常に戻し、