@aiquants/resize-panels 1.9.0 → 2.0.0

package/src/PanelResizeHandle.tsx

@@ -1,13 +1,23 @@
 /**
  * @file PanelResizeHandle component for custom resizable panels
  * カスタムリサイズ可能パネルのための PanelResizeHandle コンポーネント
+ *
+ * The handle does not compute where the boundary is. It renders a zero-length flex item — the anchor —
+ * between its two panels, so flex layout itself places it exactly on the boundary, and the interactive
+ * button is drawn symmetrically around that anchor. Whatever the panels do (a container resize between two
+ * React renders, padding on the group, right-to-left text, a vertical axis), the handle is on the boundary
+ * because it *is* the boundary.
+ * ハンドルは境界位置を計算しない。2 枚のパネルの間に長さ 0 のフレックスアイテム (アンカー) を描画するため、
+ * フレックスレイアウト自身がそれを境界へ配置し、操作用ボタンはそのアンカーを中心に対称に描かれる。
+ * コンテナのリサイズ・グループのパディング・RTL・垂直方向のいずれであっても、ハンドルは境界そのものなので必ず一致する。
  */
 
 import { type CSSProperties, memo, useCallback, useEffect, useId, useMemo, useRef, useState } from "react"
 import { twMerge } from "tailwind-merge"
+import { resolvePanelBounds } from "./allocateLayout"
 import { usePanelGroup } from "./context"
-import { roundHalfToEven } from "./roundHalfToEven"
 import {
+    PANEL_ALLOCATION_EPSILON,
     PANEL_COLLAPSE_THRESHOLD_MAX,
     PANEL_COLLAPSE_THRESHOLD_RATIO,
     PANEL_EXPAND_THRESHOLD_MAX,
@@ -23,14 +33,15 @@ import {
     PANEL_INDICATOR_THICKNESS,
     PANEL_KEYBOARD_RESIZE_STEP,
     PANEL_VISIBLE_INDICATOR_SPACING,
+    type PanelLayoutData,
     type PanelResizeHandleProps,
     type ResizeHandleLayoutData,
 } from "./types"
-import { calculateSnapThreshold, getConstraintInPixels, getContainerSize } from "./utils"
+import { calculateSnapThreshold, findOwningGroup, getGroupLayoutElements, getVisualScale } from "./utils"
 
 /**
- * Common styles applied to hide the handle and its interactive area entirely.
- * 非表示時のハンドルおよび操作領域全体に適用する共通スタイル定数。
+ * Styles that remove the handle and its anchor from layout and interaction.
+ * ハンドルとアンカーをレイアウトと操作の両方から外すスタイル。
  */
 const HIDDEN_HANDLE_STYLE: CSSProperties = {
     display: "none",
@@ -39,8 +50,8 @@ const HIDDEN_HANDLE_STYLE: CSSProperties = {
 }
 
 /**
- * Common styles applied to collapse the visual indicator.
- * 視覚インジケーターを非表示にする共通スタイル定数。
+ * Style that collapses the visual indicator.
+ * 視覚インジケーターを非表示にするスタイル。
  */
 const HIDDEN_INDICATOR_STYLE: CSSProperties = {
     display: "none",
@@ -48,7 +59,7 @@ const HIDDEN_INDICATOR_STYLE: CSSProperties = {
 
 /**
  * Sanitize an optional dimension to ensure a positive finite number.
- * オプション寸法を正の有限数値へ正規化する。
+ * オプション寸法を正の有限数値へ正規化する処理。
  */
 const sanitizeDimension = (value: unknown, defaultValue: number): number => {
     if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
@@ -59,278 +70,298 @@ const sanitizeDimension = (value: unknown, defaultValue: number): number => {
 
 /**
  * Ensure a numeric spacing value is an even integer for symmetric pixel alignment.
- * ピクセル配置の対称性を担保するため数値を偶数整数に整流する。
+ * ピクセル配置の対称性を担保するため数値を偶数整数に整流する処理。
  */
 const ensureEven = (value: number): number => {
     const rounded = Math.round(value)
     return rounded % 2 === 0 ? rounded : rounded + 1
 }
 
+/**
+ * Report whether an element is laid out right-to-left at this moment.
+ * その時点で要素が右から左へレイアウトされているかの判定。
+ *
+ * The direction is read at the start of each gesture instead of being cached, so a language switch takes
+ * effect without remounting the group.
+ * 方向はキャッシュせずジェスチャー開始のたびに読む。言語切替がグループの再マウント無しで反映されるようにするため。
+ */
+const isRightToLeft = (element: HTMLElement | null): boolean => {
+    if (!element || typeof window === "undefined") {
+        return false
+    }
+    return window.getComputedStyle(element).direction === "rtl"
+}
+
+/**
+ * Travel range of the boundary a handle sits on, in pixels from the start of the panel pair.
+ * ハンドルが載る境界の可動域 (パネル対の start からのピクセル距離)。
+ */
+type SeparatorBounds = {
+    /** Where the boundary sits now / 境界の現在位置 */
+    position: number
+    /** Lowest position this handle can reach, collapsing included / このハンドルが到達できる最小位置 (折りたたみを含む) */
+    lower: number
+    /** Highest position this handle can reach, collapsing included / このハンドルが到達できる最大位置 (折りたたみを含む) */
+    upper: number
+    /** Lowest position a plain resize can reach / 単なるリサイズで到達できる最小位置 */
+    resizeLower: number
+    /** Highest position a plain resize can reach / 単なるリサイズで到達できる最大位置 */
+    resizeUpper: number
+}
+
+/**
+ * Resolve where the boundary between two panels is and how far it can travel.
+ * 2 枚のパネルの境界が今どこにあり、どこまで動けるかを解決する処理。
+ *
+ * The range is what **this** handle can reach, not what the pair could reach through any means. Collapsing
+ * is a position the boundary can hold, so it widens the range — but only in the direction this handle is
+ * allowed to collapse, and a panel already collapsed can only be reopened from the side it was closed from
+ * (`EXPAND_PANEL` rejects any other direction). A handle that can reach nothing therefore reports a range of
+ * zero width instead of advertising travel it would swallow the key press for.
+ * 公開するのは **このハンドル** が到達できる範囲であり、対が何らかの手段で到達しうる範囲ではない。
+ * 折りたたみは境界が取りうる位置なので範囲を広げるが、広がるのはこのハンドルが折りたためる向きだけで、
+ * 既に折りたたまれたパネルは閉じたのと同じ向きからしか開けない (`EXPAND_PANEL` が他の向きを拒否する)。
+ * どこへも動けないハンドルは、幅 0 の範囲を報告する (動けると偽って キー入力だけ飲み込まないために)。
+ *
+ * @param startPanel - Panel before the boundary / 境界より手前のパネル
+ * @param endPanel - Panel after the boundary / 境界より奥のパネル
+ * @param containerSize - Container content-box length / コンテナ内容領域長
+ * @returns Boundary position and its travel range, or undefined when the pair has no length / 境界位置と可動域、対に長さが無ければ undefined
+ */
+const resolveSeparatorBounds = (startPanel: PanelLayoutData, endPanel: PanelLayoutData, containerSize: number): SeparatorBounds | undefined => {
+    const startSize = startPanel.collapsed ? 0 : startPanel.size
+    const endSize = endPanel.collapsed ? 0 : endPanel.size
+    const total = startSize + endSize
+    if (total <= 0) {
+        return undefined
+    }
+    const startBounds = resolvePanelBounds(startPanel, containerSize)
+    const endBounds = resolvePanelBounds(endPanel, containerSize)
+    // 単なるリサイズで届く範囲は、双方の制約が同時に効いた区間 (reducer の RESIZE_PANELS と同じ式)
+    const resizeLower = Math.max(startBounds.min, total - endBounds.max)
+    const resizeUpper = Math.max(resizeLower, Math.min(startBounds.max, total - endBounds.min))
+
+    if (startPanel.collapsed) {
+        // 閉じた向きと同じ向きからしか開けない。手前のパネルはこのハンドルから見て "end" 側で閉じている
+        const canReopen = startPanel.collapsedByDirection === "end"
+        return { position: 0, lower: 0, upper: canReopen ? Math.max(0, resizeUpper) : 0, resizeLower, resizeUpper }
+    }
+    if (endPanel.collapsed) {
+        const canReopen = endPanel.collapsedByDirection === "start"
+        return { position: total, lower: canReopen ? Math.min(total, resizeLower) : total, upper: total, resizeLower, resizeUpper }
+    }
+
+    // 折りたたみは境界が対の端へ到達した状態そのものなので、許される向きだけ範囲を端まで広げる
+    const lower = Math.min(startSize, startPanel.collapseFromEnd ? 0 : resizeLower)
+    const upper = Math.max(startSize, lower, endPanel.collapseFromStart ? total : resizeUpper)
+    return { position: startSize, lower, upper, resizeLower, resizeUpper }
+}
+
 /**
  * Render an interactive divider that manages adjacent panel resizing gestures.
  * 隣接パネルのリサイズ操作を管理するインタラクティブなディバイダーを描画するコンポーネント。
  */
 export const PanelResizeHandle = memo((props: PanelResizeHandleProps) => {
-    const { id, disabled = false, className, style, children, onDragging, thickness, indicator = true, indicatorThickness, indicatorLength, indicatorBarThickness, indicatorBarLength, title } = props
-    const { direction, resizePanels, getPanel, collapsePanel, expandPanel, panels, reportHandleMeasurement, containerSize, layoutConstraintViolation } = usePanelGroup()
+    const { id, disabled = false, className, style, children, onDragging, thickness, indicator = true, indicatorThickness, indicatorLength, indicatorBarThickness, indicatorBarLength, title, onPointerDown, onKeyDown, ...elementProps } = props
+    const { direction, resizePanels, getPanel, collapsePanel, expandPanel, panels, layoutOrderKey, reportHandleMeasurement, containerSize, layoutConstraintViolation } = usePanelGroup()
+
     const [isDragging, setIsDragging] = useState(false)
-    const handleRef = useRef<HTMLButtonElement>(null)
-    const containerRef = useRef<HTMLElement | null>(null)
+    const [adjacentPanelIds, setAdjacentPanelIds] = useState<{ start: string | null; end: string | null }>({ start: null, end: null })
 
-    const leftPanelId = useRef<string>("")
-    const rightPanelId = useRef<string>("")
+    const anchorRef = useRef<HTMLDivElement>(null)
+    const handleRef = useRef<HTMLButtonElement>(null)
+    // ドラッグ中の move ハンドラーは開始時のクロージャで動き続けるため、最新の状態は ref 経由で読む。
+    // これが無いと、同じジェスチャーの中で折りたたんだパネルを引き戻しても展開できない
+    const layoutRef = useRef({ getPanel, containerSize })
+    layoutRef.current = { getPanel, containerSize }
+    const startPanelIdRef = useRef("")
+    const endPanelIdRef = useRef("")
     // 進行中ドラッグの後始末関数。アンマウント時や次のドラッグ開始時の残留リスナー掃除に使う
     const dragCleanupRef = useRef<(() => void) | null>(null)
-    // RTL コンテキストでは DOM 順 (論理順) と視覚順が反転するため、座標計算の符号とオーバーレイ位置を切り替える
-    const [isRtl, setIsRtl] = useState(false)
-    const [adjacentPanelIds, setAdjacentPanelIds] = useState<{ left: string | null; right: string | null }>({ left: null, right: null })
+    const lastMeasurementRef = useRef<ResizeHandleLayoutData | null>(null)
+
     const generatedId = useId()
     const handleIdRef = useRef(id ?? `resize-handle-${generatedId}`)
-    const lastHandleMeasurementRef = useRef<ResizeHandleLayoutData | null>(null)
     const resolvedHandleId = id ?? handleIdRef.current
+    const isHorizontal = direction === "horizontal"
     const hasLayoutConstraintViolation = Boolean(layoutConstraintViolation)
     const isHandleDisabled = disabled || hasLayoutConstraintViolation
 
     /**
-     * Detect the panels adjacent to this handle by scanning sibling DOM elements.
-     * DOM の兄弟要素を走査してこのハンドルに隣接する左右のパネルを検出する。
+     * Detect the panels this handle sits between by scanning its siblings in the DOM.
+     * DOM の兄弟要素を走査して、このハンドルが挟んでいるパネルを検出する処理。
      */
     const detectAdjacentPanels = useCallback(() => {
-        const handleElement = handleRef.current
-        if (!handleElement) return
-
-        const parent = handleElement.parentElement
-        if (!parent) return
-
-        containerRef.current = parent
-        if (typeof window !== "undefined") {
-            setIsRtl(window.getComputedStyle(parent).direction === "rtl")
+        const anchor = anchorRef.current
+        // 中間要素が挟まると親はグループではないため、所有グループを辿って解決する
+        const group = findOwningGroup(anchor)
+        if (!(anchor && group)) {
+            return
         }
-        const childrenElements = Array.from(parent.children)
-        const index = childrenElements.indexOf(handleElement)
-
-        let leftPanelElement: HTMLElement | null = null
-        let rightPanelElement: HTMLElement | null = null
 
-        for (let i = index - 1; i >= 0; i -= 1) {
-            const element = childrenElements[i] as HTMLElement
-            if (element.dataset.panelId) {
-                leftPanelElement = element
+        const elements = getGroupLayoutElements(group)
+        const index = elements.indexOf(anchor)
+        let startId = ""
+        let endId = ""
+        for (let cursor = index - 1; cursor >= 0; cursor -= 1) {
+            const candidate = elements[cursor].dataset.panelId
+            if (candidate !== undefined) {
+                startId = candidate
                 break
             }
         }
-
-        for (let i = index + 1; i < childrenElements.length; i += 1) {
-            const element = childrenElements[i] as HTMLElement
-            if (element.dataset.panelId) {
-                rightPanelElement = element
+        for (let cursor = index + 1; cursor < elements.length; cursor += 1) {
+            const candidate = elements[cursor].dataset.panelId
+            if (candidate !== undefined) {
+                endId = candidate
                 break
             }
         }
 
-        const nextLeftId = leftPanelElement?.dataset.panelId || ""
-        const nextRightId = rightPanelElement?.dataset.panelId || ""
-
-        if (nextLeftId === leftPanelId.current && nextRightId === rightPanelId.current) {
+        if (startId === startPanelIdRef.current && endId === endPanelIdRef.current) {
             return
         }
-
-        leftPanelId.current = nextLeftId
-        rightPanelId.current = nextRightId
-
-        setAdjacentPanelIds({
-            left: nextLeftId || null,
-            right: nextRightId || null,
-        })
+        startPanelIdRef.current = startId
+        endPanelIdRef.current = endId
+        setAdjacentPanelIds({ start: startId || null, end: endId || null })
     }, [])
 
-    // パネル構成 (ID 列) の変化を検知するためのキー。ドラッグ中のサイズ更新では変化しない
-    const panelIdsKey = useMemo(() => panels.map((panel) => panel.id).join("|"), [panels])
-
     useEffect(() => {
-        // マウント時とパネルの増減・並び替え時に隣接パネルを再検出する
-        // (マウント時のみだと兄弟 Panel の条件付き追加/削除でハンドルが古い ID を掴んだままになる)
+        // マウント時と、グループの DOM 順が変わるたびに隣接パネルを再検出する。
+        // パネルの id 列だけを見ていると、ハンドル自身が別の境界へ移った並べ替えを取りこぼし、
+        // 見た目とは違う 2 枚を掴み続ける
         detectAdjacentPanels()
-    }, [detectAdjacentPanels, panelIdsKey])
-
-    useEffect(() => {
-        // ハンドル ID が外部から変更された場合に、旧 ID の測定結果をクリーンアップする
-        if (resolvedHandleId === handleIdRef.current) {
-            return
-        }
-
-        const previousId = handleIdRef.current
-        handleIdRef.current = resolvedHandleId
-        lastHandleMeasurementRef.current = null
-
-        if (previousId !== resolvedHandleId) {
-            reportHandleMeasurement(previousId, null)
-        }
-    }, [reportHandleMeasurement, resolvedHandleId])
+    }, [detectAdjacentPanels, layoutOrderKey])
 
     useEffect(() => {
-        // コンポーネントのアンマウント時に、このハンドルの測定結果を破棄する
-        const finalId = handleIdRef.current
-        return () => {
-            reportHandleMeasurement(finalId, null)
-        }
-    }, [reportHandleMeasurement])
-
-    useEffect(() => {
-        // ドラッグ中にアンマウントされた場合も document リスナーとドラッグ状態を確実に破棄する
         return () => {
+            // ドラッグ中にアンマウントされた場合も document リスナーとドラッグ状態を確実に破棄する
             dragCleanupRef.current?.()
         }
     }, [])
 
     /**
-     * Initiates a resize drag interaction when the handle receives a pointer down event.
+     * Start a resize drag when the handle receives a pointer down event.
      * リサイズハンドルがポインタダウンを受けた際にドラッグ操作を開始する処理。
      */
     const handlePointerDown = useCallback(
         (event: React.PointerEvent<HTMLButtonElement>) => {
-            if (isHandleDisabled || !containerRef.current) return
-
+            if (isHandleDisabled) {
+                return
+            }
             // 既にドラッグ中の場合は 2 本目のポインタで新たなドラッグを開始しない
-            if (dragCleanupRef.current) return
+            if (dragCleanupRef.current) {
+                return
+            }
+            // 主ボタン以外は掴まない。右ボタンで掴むと、コンテキストメニューを開きながらレイアウトが動く
+            // (タッチ・ペンの pointerdown も主ボタンとして 0 が届く)
+            if (event.button !== 0) {
+                return
+            }
+
+            const startPanel = getPanel(startPanelIdRef.current)
+            const endPanel = getPanel(endPanelIdRef.current)
+            if (!(startPanel && endPanel)) {
+                return
+            }
 
             event.preventDefault()
             event.stopPropagation()
 
-            const container = containerRef.current
-            const { inner: containerSize } = getContainerSize(container, direction)
-            const startPosition = { x: event.clientX, y: event.clientY }
-
-            const leftPanel = getPanel(leftPanelId.current)
-            const rightPanel = getPanel(rightPanelId.current)
-
-            if (!(leftPanel && rightPanel)) return
-
-            const initialLeftSize = leftPanel.size
-            const initialRightSize = rightPanel.size
-
-            let lastUpdateTime = 0
-            const throttleMs = PANEL_HANDLE_DRAG_THROTTLE_MS
-
-            setIsDragging(true)
-            onDragging?.(true)
+            const startId = startPanelIdRef.current
+            const endId = endPanelIdRef.current
+            const initialStartSize = startPanel.size
+            const initialTotal = startPanel.size + endPanel.size
+            const origin = isHorizontal ? event.clientX : event.clientY
+            const group = findOwningGroup(anchorRef.current)
+            // RTL では DOM 順 (論理順) と視覚順が反転するため、水平ドラッグの変位符号を反転する
+            const directionSign = isHorizontal && isRightToLeft(group) ? -1 : 1
+            // ポインタ座標は視覚ピクセル、配分器が扱うのはレイアウトピクセル。
+            // 変形された祖先の下で換算を省くと、掴んだ点がカーソルから滑り出していく
+            const visualScale = group ? getVisualScale(group, direction) : 1
 
-            // このドラッグを開始したポインタだけを追跡する (2 本目のタッチ等の混入を防ぐ)
             const dragPointerId = event.pointerId
             const captureTarget = event.currentTarget
+            // 追従は document の pointermove / pointerup で行うため、キャプチャは無くても成立する。
+            // 実装しない環境 (jsdom など) で例外を投げると、利用者側のテストがドラッグを検証できなくなる
+            captureTarget.setPointerCapture?.(dragPointerId)
 
-            // RTL では DOM 順 (論理順) と視覚順が反転するため、水平ドラッグの変位符号を反転する
-            const isRtlDrag = direction === "horizontal" && typeof window !== "undefined" && window.getComputedStyle(container).direction === "rtl"
-
-            // ポインタキャプチャを取得してドラッグ中のイベント配送を固定
-            captureTarget.setPointerCapture(dragPointerId)
-
-            /**
-             * Handle pointer move events emitted during an active resize drag interaction.
-             * リサイズドラッグ操作中に発生するポインタ移動イベントを処理する関数。
-             */
-            const handlePointerMove = (moveEvent: PointerEvent) => {
-                // 別ポインタのイベントはドラッグ計算に混入させない
-                if (moveEvent.pointerId !== dragPointerId) return
-                if (!handleRef.current) return
+            setIsDragging(true)
+            onDragging?.(true)
 
-                moveEvent.preventDefault()
-                moveEvent.stopPropagation()
+            let lastUpdateTime = 0
+            let throttledMove: PointerEvent | null = null
 
-                const now = performance.now()
-                if (now - lastUpdateTime < throttleMs) return
-                lastUpdateTime = now
+            const applyMove = (moveEvent: PointerEvent) => {
+                const delta = (((isHorizontal ? moveEvent.clientX : moveEvent.clientY) - origin) * directionSign) / visualScale
+                const nextStartSize = initialStartSize + delta
+                const nextEndSize = initialTotal - nextStartSize
 
-                const rawPixelDelta = direction === "horizontal" ? moveEvent.clientX - startPosition.x : moveEvent.clientY - startPosition.y
-                const pixelDelta = isRtlDrag ? -rawPixelDelta : rawPixelDelta
-                if (pixelDelta === 0) {
+                const layout = layoutRef.current
+                const currentStart = layout.getPanel(startId)
+                const currentEnd = layout.getPanel(endId)
+                if (!(currentStart && currentEnd)) {
                     return
                 }
 
-                const newLeftSizeInPixels = initialLeftSize + pixelDelta
-                const newRightSizeInPixels = initialRightSize - pixelDelta
-
-                const updatedLeftPanel = getPanel(leftPanelId.current)
-                const updatedRightPanel = getPanel(rightPanelId.current)
+                const collapseThreshold = Math.min(layout.containerSize * PANEL_COLLAPSE_THRESHOLD_RATIO, PANEL_COLLAPSE_THRESHOLD_MAX)
+                const expandThreshold = Math.min(layout.containerSize * PANEL_EXPAND_THRESHOLD_RATIO, PANEL_EXPAND_THRESHOLD_MAX)
 
-                if (updatedLeftPanel && updatedRightPanel && leftPanelId.current && rightPanelId.current) {
-                    const leftMinSizePixels = getConstraintInPixels(updatedLeftPanel.minSize, 0, containerSize)
-                    const rightMinSizePixels = getConstraintInPixels(updatedRightPanel.minSize, 0, containerSize)
-
-                    const collapseThresholdPixels = Math.min(containerSize * PANEL_COLLAPSE_THRESHOLD_RATIO, PANEL_COLLAPSE_THRESHOLD_MAX)
-                    const expandThresholdPixels = Math.min(containerSize * PANEL_EXPAND_THRESHOLD_RATIO, PANEL_EXPAND_THRESHOLD_MAX)
-
-                    const rightCanCollapseFromStart = updatedRightPanel.collapseFromStart
-                    const rightCollapseDirection = updatedRightPanel.collapsedByDirection ?? "start"
-                    if (rightCanCollapseFromStart && !updatedRightPanel.collapsed && newRightSizeInPixels <= Math.max(rightMinSizePixels * 0.3, collapseThresholdPixels)) {
-                        collapsePanel(rightPanelId.current, "start")
-                        return
-                    }
-
-                    const leftCanCollapseFromEnd = updatedLeftPanel.collapseFromEnd
-                    const leftCollapseDirection = updatedLeftPanel.collapsedByDirection ?? "end"
-                    if (leftCanCollapseFromEnd && !updatedLeftPanel.collapsed && newLeftSizeInPixels <= Math.max(leftMinSizePixels * 0.3, collapseThresholdPixels)) {
-                        collapsePanel(leftPanelId.current, "end")
-                        return
+                if (currentEnd.collapsed) {
+                    if (nextEndSize > expandThreshold) {
+                        expandPanel(endId, "start", nextEndSize)
                     }
-
-                    if (updatedRightPanel.collapsed && newRightSizeInPixels > Math.max(rightMinSizePixels * 0.3, expandThresholdPixels)) {
-                        expandPanel(rightPanelId.current, rightCollapseDirection, newRightSizeInPixels)
-                        return
-                    }
-
-                    if (updatedLeftPanel.collapsed && newLeftSizeInPixels > Math.max(leftMinSizePixels * 0.3, expandThresholdPixels)) {
-                        expandPanel(leftPanelId.current, leftCollapseDirection, newLeftSizeInPixels)
-                        return
+                    return
+                }
+                if (currentStart.collapsed) {
+                    if (nextStartSize > expandThreshold) {
+                        expandPanel(startId, "end", nextStartSize)
                     }
+                    return
+                }
+                if (currentEnd.collapseFromStart && nextEndSize <= collapseThreshold) {
+                    collapsePanel(endId, "start")
+                    return
+                }
+                if (currentStart.collapseFromEnd && nextStartSize <= collapseThreshold) {
+                    collapsePanel(startId, "end")
+                    return
+                }
 
-                    if (containerSize > 0) {
-                        const totalPanelPixels = updatedLeftPanel.size + updatedRightPanel.size
-                        const snapThreshold = calculateSnapThreshold(containerSize)
-                        let snapped = false
-
-                        if (leftMinSizePixels <= snapThreshold && newLeftSizeInPixels <= snapThreshold && initialLeftSize !== 0) {
-                            const snappedLeft = 0
-                            const snappedRight = Math.max(0, totalPanelPixels - snappedLeft)
-
-                            if (snappedRight >= rightMinSizePixels) {
-                                resizePanels(leftPanelId.current, rightPanelId.current, snappedLeft, snappedRight)
-                                snapped = true
-                            }
-                        } else if (rightMinSizePixels <= snapThreshold && newRightSizeInPixels <= snapThreshold && initialRightSize !== 0) {
-                            const snappedRight = 0
-                            const snappedLeft = Math.max(0, totalPanelPixels - snappedRight)
-
-                            if (snappedLeft >= leftMinSizePixels) {
-                                resizePanels(leftPanelId.current, rightPanelId.current, snappedLeft, snappedRight)
-                                snapped = true
-                            }
-                        }
-
-                        if (snapped) {
-                            return
-                        }
-                    }
+                resizePanels(startId, endId, nextStartSize)
+            }
 
-                    if (updatedLeftPanel.collapsed || updatedRightPanel.collapsed) {
-                        return
-                    }
+            const handlePointerMove = (moveEvent: PointerEvent) => {
+                // 別ポインタのイベントはドラッグ計算に混入させない
+                if (moveEvent.pointerId !== dragPointerId) {
+                    return
+                }
+                moveEvent.preventDefault()
+                moveEvent.stopPropagation()
 
-                    resizePanels(leftPanelId.current, rightPanelId.current, newLeftSizeInPixels, newRightSizeInPixels)
+                const now = performance.now()
+                if (now - lastUpdateTime < PANEL_HANDLE_DRAG_THROTTLE_MS) {
+                    // 間引いた移動は捨てずに保持する。離上時に反映しないと、指を離した位置と確定した境界がずれる
+                    throttledMove = moveEvent
+                    return
                 }
+                lastUpdateTime = now
+                throttledMove = null
+                applyMove(moveEvent)
             }
 
             /**
              * Tear down the active drag: remove listeners, release capture, and reset state.
-             * 進行中ドラッグの後始末: リスナー除去・キャプチャ解放・状態リセットを一括で行う。
+             * 進行中ドラッグの後始末 (リスナー除去・キャプチャ解放・状態リセット)。
              * pointerup / pointercancel / lostpointercapture / アンマウントのどこから呼ばれても一度だけ実行される。
              */
             let dragActive = true
             const stopDragging = () => {
-                if (!dragActive) return
+                if (!dragActive) {
+                    return
+                }
                 dragActive = false
                 dragCleanupRef.current = null
-
                 setIsDragging(false)
                 onDragging?.(false)
 
@@ -345,20 +376,27 @@ export const PanelResizeHandle = memo((props: PanelResizeHandleProps) => {
 
             const handlePointerUp = (upEvent: PointerEvent) => {
                 // 別ポインタの離上ではドラッグを終了しない
-                if (upEvent.pointerId !== dragPointerId) return
+                if (upEvent.pointerId !== dragPointerId) {
+                    return
+                }
+                if (throttledMove) {
+                    const pending = throttledMove
+                    throttledMove = null
+                    applyMove(pending)
+                }
                 stopDragging()
             }
-
             const handlePointerCancel = (cancelEvent: PointerEvent) => {
                 // OS 割込み (タッチジェスチャ奪取等) でキャンセルされた場合もドラッグ状態を残さない
-                if (cancelEvent.pointerId !== dragPointerId) return
-                stopDragging()
+                if (cancelEvent.pointerId === dragPointerId) {
+                    stopDragging()
+                }
             }
-
             const handleLostPointerCapture = (lostEvent: PointerEvent) => {
                 // キャプチャ喪失 (要素の DOM 離脱等) 時のフォールバック終了処理
-                if (lostEvent.pointerId !== dragPointerId) return
-                stopDragging()
+                if (lostEvent.pointerId === dragPointerId) {
+                    stopDragging()
+                }
             }
 
             document.addEventListener("pointermove", handlePointerMove)
@@ -367,203 +405,103 @@ export const PanelResizeHandle = memo((props: PanelResizeHandleProps) => {
             captureTarget.addEventListener("lostpointercapture", handleLostPointerCapture)
             dragCleanupRef.current = stopDragging
         },
-        [isHandleDisabled, direction, resizePanels, getPanel, collapsePanel, expandPanel, onDragging],
+        [isHandleDisabled, isHorizontal, direction, getPanel, resizePanels, collapsePanel, expandPanel, onDragging],
     )
 
     /**
      * Resize adjacent panels with arrow keys for keyboard accessibility.
      * キーボード (矢印キー) で隣接パネルをリサイズするアクセシビリティ対応。
-     * Shift 併用で 5 倍のステップ幅を適用する。
      */
     const handleKeyDown = useCallback(
         (event: React.KeyboardEvent<HTMLButtonElement>) => {
-            if (isHandleDisabled) return
+            if (isHandleDisabled) {
+                return
+            }
+            const decreaseKey = isHorizontal ? "ArrowLeft" : "ArrowUp"
+            const increaseKey = isHorizontal ? "ArrowRight" : "ArrowDown"
+            if (event.key !== decreaseKey && event.key !== increaseKey) {
+                return
+            }
 
-            const isHorizontalDirection = direction === "horizontal"
-            const decreaseKey = isHorizontalDirection ? "ArrowLeft" : "ArrowUp"
-            const increaseKey = isHorizontalDirection ? "ArrowRight" : "ArrowDown"
-            if (event.key !== decreaseKey && event.key !== increaseKey) return
+            const startId = startPanelIdRef.current
+            const endId = endPanelIdRef.current
+            const startPanel = getPanel(startId)
+            const endPanel = getPanel(endId)
+            if (!(startPanel && endPanel)) {
+                return
+            }
+            const bounds = resolveSeparatorBounds(startPanel, endPanel, containerSize)
+            // どこへも動けないハンドルはキーを飲み込まない。飲み込むと、何も起きないまま
+            // ページのスクロールまで止まる「効かないキー」になる
+            if (!bounds || bounds.upper - bounds.lower <= PANEL_ALLOCATION_EPSILON) {
+                return
+            }
 
             event.preventDefault()
             event.stopPropagation()
 
-            let delta = (event.key === increaseKey ? 1 : -1) * (event.shiftKey ? PANEL_KEYBOARD_RESIZE_STEP * 5 : PANEL_KEYBOARD_RESIZE_STEP)
-            // RTL では DOM 順 (論理順) と視覚順が反転するため符号を反転する (ドラッグ開始時と同様に押下時点の値を都度参照)
-            const isRtlNow = isHorizontalDirection && typeof window !== "undefined" && containerRef.current !== null && window.getComputedStyle(containerRef.current).direction === "rtl"
-            if (isRtlNow) {
-                delta = -delta
-            }
-
-            const leftPanel = getPanel(leftPanelId.current)
-            const rightPanel = getPanel(rightPanelId.current)
-            if (!(leftPanel && rightPanel) || leftPanel.collapsed || rightPanel.collapsed) return
-
-            // 制約の最終判定はリデューサー側で行われる
-            resizePanels(leftPanelId.current, rightPanelId.current, leftPanel.size + delta, rightPanel.size - delta)
-        },
-        [isHandleDisabled, direction, getPanel, resizePanels],
-    )
-
-    const isHorizontal = direction === "horizontal"
-    const cursor = isHorizontal ? "cursor-col-resize" : "cursor-row-resize"
-
-    const baseHandleClasses = useMemo(
-        () =>
-            twMerge(
-                "group absolute z-20 flex select-none items-center justify-center border-none bg-transparent transition-colors duration-150 overflow-visible",
-                cursor,
-                isHorizontal ? "h-full" : "w-full",
-                !isHandleDisabled && "hover:bg-gray-200/70 dark:hover:bg-gray-700/70",
-                !isHandleDisabled && "active:bg-blue-300/60 dark:active:bg-blue-700/60",
-                isDragging && "bg-blue-200/80 dark:bg-blue-800/60",
-                isHandleDisabled && "cursor-not-allowed opacity-50",
-                "focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-opacity-50",
-                className,
-            ),
-        [cursor, isHorizontal, isHandleDisabled, isDragging, className],
-    )
-
-    const adjacentIndices = useMemo(() => {
-        const findIndex = (panelId: string | null) => {
-            if (!panelId) {
-                return -1
+            const step = event.shiftKey ? PANEL_KEYBOARD_RESIZE_STEP * 5 : PANEL_KEYBOARD_RESIZE_STEP
+            // RTL では DOM 順 (論理順) と視覚順が反転するため符号を反転する
+            const directionSign = isHorizontal && isRightToLeft(findOwningGroup(anchorRef.current)) ? -1 : 1
+            const delta = (event.key === increaseKey ? step : -step) * directionSign
+
+            // 折りたたまれたパネルは、境界を自分の方へ押し返すキーで開く。
+            // 開けないと、キーボードだけを使う利用者にとって折りたたみは戻れない行き止まりになる
+            if (startPanel.collapsed) {
+                if (delta > 0) {
+                    // 目標長を渡さずに開く: 折りたたむ前の長さへ戻すのが「開く」の意味であり、
+                    // 1 ステップ分だけ開いても最小値へ切り上げられるだけで何も伝わらない
+                    expandPanel(startId, "end")
+                }
+                return
             }
-            for (let index = 0; index < panels.length; index += 1) {
-                if (panels[index].id === panelId) {
-                    return index
+            if (endPanel.collapsed) {
+                if (delta < 0) {
+                    expandPanel(endId, "start")
                 }
+                return
             }
-            return -1
-        }
 
-        return {
-            left: findIndex(adjacentPanelIds.left),
-            right: findIndex(adjacentPanelIds.right),
-        }
-    }, [adjacentPanelIds.left, adjacentPanelIds.right, panels])
-
-    const containerLength = isHorizontal ? containerSize.width : containerSize.height
-
-    const boundaryOffset = useMemo(() => {
-        const safeSum = (startIndex: number, endIndexInclusive: number) => {
-            if (startIndex > endIndexInclusive) {
-                return 0
+            // リサイズで届く端まで来たパネルをさらに押すキーは、ドラッグで端まで引いたときと同じく折りたたみになる。
+            // 判定に使うのはパネル自身の最小値ではなく対の可動域の端である。隣の上限が先に効く構成では、
+            // パネルは自分の最小値へ決して到達できず、キーボードからは永久に折りたためなくなる
+            if (delta < 0 && startPanel.collapseFromEnd && bounds.position <= bounds.resizeLower + PANEL_ALLOCATION_EPSILON) {
+                collapsePanel(startId, "end")
+                return
             }
-            let total = 0
-            for (let index = startIndex; index <= endIndexInclusive; index += 1) {
-                const panel = panels[index]
-                if (!panel) {
-                    continue
-                }
-                const candidateSize = panel.size ?? 0
-                const sanitizedSize = Math.max(0, candidateSize)
-                total += panel.collapsed ? 0 : sanitizedSize
+            if (delta > 0 && endPanel.collapseFromStart && bounds.position >= bounds.resizeUpper - PANEL_ALLOCATION_EPSILON) {
+                collapsePanel(endId, "start")
+                return
             }
-            return total
-        }
-
-        if (adjacentIndices.left >= 0) {
-            return safeSum(0, adjacentIndices.left)
-        }
-
-        if (adjacentIndices.right > 0) {
-            return safeSum(0, adjacentIndices.right - 1)
-        }
-
-        return 0
-    }, [adjacentIndices.left, adjacentIndices.right, panels])
-
-    const clampedOffset = useMemo(() => {
-        if (!Number.isFinite(boundaryOffset) || boundaryOffset < 0) {
-            return 0
-        }
-        if (containerLength > 0 && boundaryOffset > containerLength) {
-            return containerLength
-        }
-        return boundaryOffset
-    }, [boundaryOffset, containerLength])
+            resizePanels(startId, endId, startPanel.size + delta)
+        },
+        [isHandleDisabled, isHorizontal, getPanel, resizePanels, collapsePanel, expandPanel, containerSize],
+    )
 
     const indicatorConfig = typeof indicator === "object" && indicator !== null ? indicator : undefined
     const isIndicatorExplicitlyHidden = indicator === false || indicatorConfig?.visible === false
 
-    const rawThickness = sanitizeDimension(thickness, PANEL_HANDLE_THICKNESS)
+    const resolvedThickness = Math.max(1, sanitizeDimension(thickness, PANEL_HANDLE_THICKNESS))
     const defaultIndicatorLength = isHorizontal ? PANEL_INDICATOR_LENGTH_HORIZONTAL : PANEL_INDICATOR_LENGTH_VERTICAL
     const defaultBarLength = isHorizontal ? PANEL_INDICATOR_BAR_LENGTH_HORIZONTAL : PANEL_INDICATOR_BAR_LENGTH_VERTICAL
 
-    const rawIndicatorThickness = sanitizeDimension(indicatorThickness ?? indicatorConfig?.thickness, PANEL_INDICATOR_THICKNESS)
-    const rawIndicatorLength = sanitizeDimension(indicatorLength ?? indicatorConfig?.length, defaultIndicatorLength)
-    const rawBarThickness = sanitizeDimension(indicatorBarThickness ?? indicatorConfig?.barThickness, PANEL_INDICATOR_BAR_THICKNESS)
-    const rawBarLength = sanitizeDimension(indicatorBarLength ?? indicatorConfig?.barLength, defaultBarLength)
-
     // 幾何学的内包不変条件: 内部バー寸法がインジケーター外枠およびハンドル操作領域を超えないようクランプ
-    const resolvedThickness = Math.max(1, rawThickness)
-    const resolvedIndicatorThickness = Math.min(resolvedThickness, Math.max(1, rawIndicatorThickness))
-    const resolvedIndicatorLength = Math.max(1, rawIndicatorLength)
-    const resolvedBarThickness = Math.min(resolvedIndicatorThickness, Math.max(1, rawBarThickness))
-    const resolvedBarLength = Math.min(resolvedIndicatorLength, Math.max(1, rawBarLength))
-
-    // 静的 CSS 変数はドラッグ中に変化しないため、スタイル再計算時の不要なプロパティ再設定を防止
-    const customProperties = useMemo<Record<string, string>>(
-        () => ({
-            "--rp-handle-thickness": `${resolvedThickness}px`,
-            "--rp-indicator-thickness": `${resolvedIndicatorThickness}px`,
-            "--rp-indicator-length": `${resolvedIndicatorLength}px`,
-            "--rp-indicator-bar-thickness": `${resolvedBarThickness}px`,
-            "--rp-indicator-bar-length": `${resolvedBarLength}px`,
-        }),
-        [resolvedThickness, resolvedIndicatorThickness, resolvedIndicatorLength, resolvedBarThickness, resolvedBarLength],
-    )
-
-    const overlayBaseStyle = useMemo<CSSProperties>(() => {
-        // RTL では右端起点から論理距離を差し引いた位置が物理境界中心線となる
-        const centerLine = isHorizontal && isRtl && containerLength > 0 ? containerLength - clampedOffset : clampedOffset
-
-        // transform: translate(-50%) による 0.5px サブピクセル滲みを防ぐため、中心線から半厚みを引き銀行丸めで整数ピクセル原点を決定
-        const startCoord = roundHalfToEven(centerLine - resolvedThickness / 2, 0)
-
-        const base: CSSProperties = {
-            position: "absolute",
-            zIndex: 20,
-            touchAction: "none",
-            ...customProperties,
-        }
-
-        if (isHorizontal) {
-            base.top = 0
-            base.left = `${startCoord}px`
-            base.width = `${resolvedThickness}px`
-            base.height = "100%"
-        } else {
-            base.left = 0
-            base.top = `${startCoord}px`
-            base.height = `${resolvedThickness}px`
-            base.width = "100%"
-        }
-
-        return base
-    }, [clampedOffset, isHorizontal, isRtl, containerLength, resolvedThickness, customProperties])
+    const resolvedIndicatorThickness = Math.min(resolvedThickness, Math.max(1, sanitizeDimension(indicatorThickness ?? indicatorConfig?.thickness, PANEL_INDICATOR_THICKNESS)))
+    const resolvedIndicatorLength = Math.max(1, sanitizeDimension(indicatorLength ?? indicatorConfig?.length, defaultIndicatorLength))
+    const resolvedBarThickness = Math.min(resolvedIndicatorThickness, Math.max(1, sanitizeDimension(indicatorBarThickness ?? indicatorConfig?.barThickness, PANEL_INDICATOR_BAR_THICKNESS)))
+    const resolvedBarLength = Math.min(resolvedIndicatorLength, Math.max(1, sanitizeDimension(indicatorBarLength ?? indicatorConfig?.barLength, defaultBarLength)))
 
     const indicatorGrouping = useMemo(() => {
-        const snapThreshold = calculateSnapThreshold(containerLength)
+        // 隣接パネルが閉じていると複数のハンドルが同じ境界へ重なるため、その重なり具合を数える
+        const snapThreshold = calculateSnapThreshold(containerSize)
         const isEffectivelyCollapsed = (panelIndex: number) => {
-            if (panelIndex < 0 || panelIndex >= panels.length) {
-                return false
-            }
             const target = panels[panelIndex]
             if (!target) {
                 return false
             }
-            if (target.collapsed) {
-                return true
-            }
-            return target.size <= snapThreshold
+            return target.collapsed || target.size <= snapThreshold
         }
-
         const countCollapsed = (startIndex: number, step: 1 | -1) => {
-            if (!isEffectivelyCollapsed(startIndex)) {
-                return 0
-            }
-
             let count = 0
             for (let index = startIndex; index >= 0 && index < panels.length; index += step) {
                 if (!isEffectivelyCollapsed(index)) {
@@ -574,18 +512,13 @@ export const PanelResizeHandle = memo((props: PanelResizeHandleProps) => {
             return count
         }
 
-        const leftIndex = adjacentIndices.left
-        const rightIndex = adjacentIndices.right
-        const leftCollapsedCount = leftIndex >= 0 ? countCollapsed(leftIndex, -1) : 0
-        const rightCollapsedCount = rightIndex >= 0 ? countCollapsed(rightIndex, 1) : 0
-        const groupSize = leftCollapsedCount + rightCollapsedCount + 1
-        const overlapIndex = leftCollapsedCount
+        const startIndex = panels.findIndex((panel) => panel.id === adjacentPanelIds.start)
+        const endIndex = panels.findIndex((panel) => panel.id === adjacentPanelIds.end)
+        const startCollapsedCount = startIndex >= 0 ? countCollapsed(startIndex, -1) : 0
+        const endCollapsedCount = endIndex >= 0 ? countCollapsed(endIndex, 1) : 0
 
-        return {
-            groupSize,
-            overlapIndex,
-        }
-    }, [adjacentIndices.left, adjacentIndices.right, panels, containerLength])
+        return { groupSize: startCollapsedCount + endCollapsedCount + 1, overlapIndex: startCollapsedCount }
+    }, [adjacentPanelIds.start, adjacentPanelIds.end, panels, containerSize])
 
     const shouldHideHandle = useMemo(() => {
         if (hasLayoutConstraintViolation) {
@@ -595,61 +528,106 @@ export const PanelResizeHandle = memo((props: PanelResizeHandleProps) => {
             return false
         }
         // 折りたたみ重なり時の視覚重複を防ぐため端点以外の重複ハンドルを不可視化
-        const lastIndex = indicatorGrouping.groupSize - 1
-        return indicatorGrouping.overlapIndex > 0 && indicatorGrouping.overlapIndex < lastIndex
+        return indicatorGrouping.overlapIndex > 0 && indicatorGrouping.overlapIndex < indicatorGrouping.groupSize - 1
     }, [indicatorGrouping, hasLayoutConstraintViolation])
 
     const indicatorOffset = useMemo(() => {
         if (indicatorGrouping.groupSize <= 1 || shouldHideHandle) {
             return 0
         }
+        // 重なった 2 つの端点インジケーターを等間隔で振り分ける (半ピクセル除算を避けるため偶数間隔)
+        const spacing = ensureEven(Math.max(PANEL_VISIBLE_INDICATOR_SPACING, resolvedIndicatorThickness + 4))
+        return (indicatorGrouping.overlapIndex === 0 ? -0.5 : 0.5) * spacing
+    }, [indicatorGrouping, shouldHideHandle, resolvedIndicatorThickness])
 
-        const visibleCount = indicatorGrouping.groupSize > 1 ? 2 : 1
-        if (visibleCount === 1) {
-            return 0
-        }
-
-        // 半ピクセル除算による非対称性を防ぐため偶数スペーシングを保証
-        const dynamicSpacing = ensureEven(Math.max(PANEL_VISIBLE_INDICATOR_SPACING, resolvedIndicatorThickness + 4))
-        const visibleIndex = indicatorGrouping.overlapIndex === 0 ? 0 : visibleCount - 1
-        const centerIndex = (visibleCount - 1) / 2
-        const rawOffset = (visibleIndex - centerIndex) * dynamicSpacing
+    const anchorStyle = useMemo<CSSProperties>(() => {
+        const base: CSSProperties = {
+            // 長さ 0 のフレックスアイテム: フレックスレイアウトがこれを境界そのものへ配置する
+            position: "relative",
+            flex: "0 0 0px",
+            alignSelf: "stretch",
+            // DOM 順を配置順の真実として扱うため、クラス由来の order で並びが変わらないようにする
+            order: 0,
+            margin: 0,
+            overflow: "visible",
+            ...(isHorizontal ? { width: 0, minWidth: 0 } : { height: 0, minHeight: 0 }),
+        }
+        return shouldHideHandle ? { ...base, ...HIDDEN_HANDLE_STYLE } : base
+    }, [isHorizontal, shouldHideHandle])
+
+    // 利用者が独自に装飾できるよう、解決済みの寸法を CSS 変数として公開する
+    const customProperties = useMemo<Record<string, string>>(
+        () => ({
+            "--rp-handle-thickness": `${resolvedThickness}px`,
+            "--rp-indicator-thickness": `${resolvedIndicatorThickness}px`,
+            "--rp-indicator-length": `${resolvedIndicatorLength}px`,
+            "--rp-indicator-bar-thickness": `${resolvedBarThickness}px`,
+            "--rp-indicator-bar-length": `${resolvedBarLength}px`,
+        }),
+        [resolvedThickness, resolvedIndicatorThickness, resolvedIndicatorLength, resolvedBarThickness, resolvedBarLength],
+    )
 
-        // 水平かつ RTL の環境では start パネルが物理右側にあるため論理順の正シフトを物理左方向（負）へ反転
-        return isHorizontal && isRtl ? -rawOffset : rawOffset
-    }, [indicatorGrouping, shouldHideHandle, resolvedIndicatorThickness, isHorizontal, isRtl])
+    const handleStyle = useMemo<CSSProperties>(() => {
+        // アンカー原点が境界。半厚みだけ手前へずらすと操作領域の中心線が境界に重なる。
+        // 端数は描画時にピクセルへスナップされるため、ここで丸める必要はない
+        return {
+            ...customProperties,
+            ...style,
+            // ここから下は境界に載るという前提そのもの。利用者のスタイルやクラスで変わると
+            // 操作領域の中心が境界から外れ、touch-action が戻るとタッチではスクロールが優先されてしまう
+            position: "absolute",
+            zIndex: 20,
+            touchAction: "none",
+            // 位置は論理プロパティで与える。アンカーは寸法 0 なので RTL でも同じ点に重なるが、
+            // 「境界からの距離」という意図をそのまま表せる
+            ...(isHorizontal ? { insetBlockStart: 0, insetInlineStart: `${-resolvedThickness / 2}px`, width: `${resolvedThickness}px`, height: "100%" } : { insetInlineStart: 0, insetBlockStart: `${-resolvedThickness / 2}px`, height: `${resolvedThickness}px`, width: "100%" }),
+        }
+    }, [isHorizontal, resolvedThickness, customProperties, style])
 
     const indicatorWrapperStyle = useMemo<CSSProperties>(() => {
         if (shouldHideHandle || isIndicatorExplicitlyHidden) {
             return HIDDEN_INDICATOR_STYLE
         }
-
-        const width = isHorizontal ? resolvedIndicatorThickness : resolvedIndicatorLength
-        const height = isHorizontal ? resolvedIndicatorLength : resolvedIndicatorThickness
-
         const dynamicStyle: CSSProperties = {
-            width: `${width}px`,
-            height: `${height}px`,
+            width: `${isHorizontal ? resolvedIndicatorThickness : resolvedIndicatorLength}px`,
+            height: `${isHorizontal ? resolvedIndicatorLength : resolvedIndicatorThickness}px`,
             flexShrink: 0,
         }
-
         if (indicatorOffset !== 0) {
-            dynamicStyle.transform = isHorizontal ? `translateX(${indicatorOffset}px)` : `translateY(${indicatorOffset}px)`
+            // 論理方向のオフセットなので RTL では自動的に鏡像になる (符号を分岐させない)
+            dynamicStyle.position = "relative"
+            if (isHorizontal) {
+                dynamicStyle.insetInlineStart = `${indicatorOffset}px`
+            } else {
+                dynamicStyle.insetBlockStart = `${indicatorOffset}px`
+            }
         }
-
         return dynamicStyle
     }, [shouldHideHandle, isIndicatorExplicitlyHidden, isHorizontal, resolvedIndicatorThickness, resolvedIndicatorLength, indicatorOffset])
 
-    const indicatorBarStyle = useMemo<CSSProperties>(() => {
-        const width = isHorizontal ? resolvedBarThickness : resolvedBarLength
-        const height = isHorizontal ? resolvedBarLength : resolvedBarThickness
-
-        return {
-            width: `${width}px`,
-            height: `${height}px`,
+    const indicatorBarStyle = useMemo<CSSProperties>(
+        () => ({
+            width: `${isHorizontal ? resolvedBarThickness : resolvedBarLength}px`,
+            height: `${isHorizontal ? resolvedBarLength : resolvedBarThickness}px`,
             flexShrink: 0,
-        }
-    }, [isHorizontal, resolvedBarThickness, resolvedBarLength])
+        }),
+        [isHorizontal, resolvedBarThickness, resolvedBarLength],
+    )
+
+    const baseHandleClasses = useMemo(
+        () =>
+            twMerge(
+                "group absolute z-20 flex select-none items-center justify-center border-none bg-transparent transition-colors duration-150 overflow-visible",
+                isHorizontal ? "cursor-col-resize h-full" : "cursor-row-resize w-full",
+                !isHandleDisabled && "hover:bg-gray-200/70 dark:hover:bg-gray-700/70",
+                !isHandleDisabled && "active:bg-blue-300/60 dark:active:bg-blue-700/60",
+                isDragging && "bg-blue-200/80 dark:bg-blue-800/60",
+                isHandleDisabled && "cursor-not-allowed opacity-50",
+                "focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-opacity-50",
+                className,
+            ),
+        [isHorizontal, isHandleDisabled, isDragging, className],
+    )
 
     const indicatorWrapperClasses = useMemo(
         () =>
@@ -673,125 +651,108 @@ export const PanelResizeHandle = memo((props: PanelResizeHandleProps) => {
         [isDragging, isHandleDisabled, indicatorConfig?.barClassName],
     )
 
-    const updateHandleMeasurement = useCallback(() => {
-        const element = handleRef.current
-        if (!element) {
+    useEffect(() => {
+        // ハンドル ID が外部から変更された場合に、旧 ID の測定結果を破棄する
+        if (resolvedHandleId === handleIdRef.current) {
             return
         }
+        const previousId = handleIdRef.current
+        handleIdRef.current = resolvedHandleId
+        lastMeasurementRef.current = null
+        reportHandleMeasurement(previousId, null)
+    }, [reportHandleMeasurement, resolvedHandleId])
 
-        let thickness = 0
-
-        if (!shouldHideHandle) {
-            const baseSize = direction === "horizontal" ? element.offsetWidth : element.offsetHeight
-            let marginStart = 0
-            let marginEnd = 0
-
-            if (typeof window !== "undefined") {
-                const computedStyle = window.getComputedStyle(element)
-                if (direction === "horizontal") {
-                    marginStart = Number.parseFloat(computedStyle.marginLeft || "0")
-                    marginEnd = Number.parseFloat(computedStyle.marginRight || "0")
-                } else {
-                    marginStart = Number.parseFloat(computedStyle.marginTop || "0")
-                    marginEnd = Number.parseFloat(computedStyle.marginBottom || "0")
-                }
-            }
-
-            const candidates = [baseSize, marginStart, marginEnd]
-            thickness = candidates.reduce((sum, value) => {
-                if (!Number.isFinite(value)) {
-                    return sum
-                }
-                return sum + value
-            }, 0)
-        }
-
-        if (!Number.isFinite(thickness) || thickness < 0) {
-            thickness = 0
-        }
-
+    useEffect(() => {
         const measurement: ResizeHandleLayoutData = {
             id: resolvedHandleId,
-            thickness,
+            thickness: shouldHideHandle ? 0 : resolvedThickness,
             direction,
-            visible: !shouldHideHandle && thickness > PANEL_HANDLE_VISIBILITY_THRESHOLD,
-            startPanelId: adjacentPanelIds.left,
-            endPanelId: adjacentPanelIds.right,
-        }
-
-        const lastMeasurement = lastHandleMeasurementRef.current
-
-        if (
-            lastMeasurement &&
-            Math.abs(lastMeasurement.thickness - measurement.thickness) <= 0.25 &&
-            lastMeasurement.visible === measurement.visible &&
-            lastMeasurement.direction === measurement.direction &&
-            lastMeasurement.startPanelId === measurement.startPanelId &&
-            lastMeasurement.endPanelId === measurement.endPanelId
-        ) {
-            return
+            visible: !shouldHideHandle && resolvedThickness > PANEL_HANDLE_VISIBILITY_THRESHOLD,
+            startPanelId: adjacentPanelIds.start,
+            endPanelId: adjacentPanelIds.end,
         }
-
-        lastHandleMeasurementRef.current = measurement
+        lastMeasurementRef.current = measurement
         reportHandleMeasurement(resolvedHandleId, measurement)
-    }, [direction, adjacentPanelIds.left, adjacentPanelIds.right, reportHandleMeasurement, resolvedHandleId, shouldHideHandle])
+    }, [resolvedHandleId, resolvedThickness, shouldHideHandle, direction, adjacentPanelIds.start, adjacentPanelIds.end, reportHandleMeasurement])
 
     useEffect(() => {
-        updateHandleMeasurement()
-    }, [updateHandleMeasurement])
-
-    useEffect(() => {
-        const element = handleRef.current
-        if (!element) {
-            return
+        return () => {
+            // アンマウント時にこのハンドルの測定結果を破棄する。
+            // ID は effect の実行時ではなく後始末の時点で読む (途中で ID を変えたハンドルの登録が残らないように)
+            reportHandleMeasurement(handleIdRef.current, null)
         }
+    }, [reportHandleMeasurement])
 
-        if (typeof ResizeObserver === "undefined") {
-            updateHandleMeasurement()
-            return
-        }
+    // 利用者のハンドラーを黙って捨てず、先に呼んでから自分の処理へ進む。
+    // preventDefault() されたイベントは利用者が握り潰したものとして、ジェスチャーを開始しない
+    const composedPointerDown = useCallback(
+        (event: React.PointerEvent<HTMLButtonElement>) => {
+            onPointerDown?.(event)
+            if (!event.defaultPrevented) {
+                handlePointerDown(event)
+            }
+        },
+        [onPointerDown, handlePointerDown],
+    )
 
-        const observer = new ResizeObserver(() => {
-            updateHandleMeasurement()
-        })
+    const composedKeyDown = useCallback(
+        (event: React.KeyboardEvent<HTMLButtonElement>) => {
+            onKeyDown?.(event)
+            if (!event.defaultPrevented) {
+                handleKeyDown(event)
+            }
+        },
+        [onKeyDown, handleKeyDown],
+    )
 
-        observer.observe(element)
+    const accessibleLabel = `Resize ${isHorizontal ? "columns" : "rows"} - Drag or use arrow keys to resize, drag to the edge to collapse/expand panels`
 
-        return () => {
-            observer.disconnect()
+    const separatorValues = useMemo(() => {
+        // スプリッターの現在値は「境界より手前のパネルがコンテナに占める割合」。可動域も同じ尺度で公開する。
+        // 折りたたまれたパネルは長さ 0 として扱う: 値を落とすと role="separator" が必須属性を失い、
+        // 支援技術からは「動かせない仕切り」に見えてしまう
+        const startPanel = adjacentPanelIds.start === null ? undefined : getPanel(adjacentPanelIds.start)
+        const endPanel = adjacentPanelIds.end === null ? undefined : getPanel(adjacentPanelIds.end)
+        if (!(startPanel && endPanel) || containerSize <= 0) {
+            return undefined
         }
-    }, [updateHandleMeasurement])
-
-    const combinedStyle = useMemo<CSSProperties>(() => {
-        const merged = style ? { ...overlayBaseStyle, ...style } : overlayBaseStyle
-        if (shouldHideHandle) {
-            return {
-                ...merged,
-                ...HIDDEN_HANDLE_STYLE,
-            }
+        const bounds = resolveSeparatorBounds(startPanel, endPanel, containerSize)
+        if (!bounds) {
+            return undefined
         }
-        return merged
-    }, [overlayBaseStyle, shouldHideHandle, style])
+        const toPercentage = (value: number) => Math.round((value / containerSize) * 100)
+        return { now: toPercentage(bounds.position), min: toPercentage(bounds.lower), max: toPercentage(bounds.upper) }
+    }, [adjacentPanelIds.start, adjacentPanelIds.end, getPanel, containerSize])
 
     return (
-        <button
-            type="button"
-            ref={handleRef}
-            className={baseHandleClasses}
-            style={combinedStyle}
-            onPointerDown={handlePointerDown}
-            onKeyDown={handleKeyDown}
-            disabled={isHandleDisabled}
-            aria-hidden={shouldHideHandle || undefined}
-            aria-label={`Resize ${isHorizontal ? "columns" : "rows"} - Drag or use arrow keys to resize, drag to the edge to collapse/expand panels`}
-            data-resize-handle-id={resolvedHandleId}
-            title={title ?? `Resize ${isHorizontal ? "columns" : "rows"} - Drag or use arrow keys to resize, drag to the edge to collapse/expand panels`}>
-            {children ||
-                (!isIndicatorExplicitlyHidden && (
-                    <div className={indicatorWrapperClasses} style={indicatorWrapperStyle} data-resize-handle-indicator="" aria-hidden="true">
-                        <span className={indicatorBarClasses} style={indicatorBarStyle} data-resize-handle-indicator-bar="" aria-hidden="true" />
-                    </div>
-                ))}
-        </button>
+        <div ref={anchorRef} style={anchorStyle} data-resize-handle-anchor="">
+            {/* biome-ignore lint/a11y/useSemanticElements: 操作できるスプリッターは <hr> では表現できない (WAI-ARIA の window splitter パターンは focusable な role="separator" を要求する) */}
+            <button
+                {...elementProps}
+                type="button"
+                ref={handleRef}
+                className={baseHandleClasses}
+                style={handleStyle}
+                onPointerDown={composedPointerDown}
+                onKeyDown={composedKeyDown}
+                disabled={isHandleDisabled}
+                role="separator"
+                aria-orientation={isHorizontal ? "vertical" : "horizontal"}
+                aria-valuenow={separatorValues?.now}
+                aria-valuemin={separatorValues?.min}
+                aria-valuemax={separatorValues?.max}
+                aria-disabled={isHandleDisabled || undefined}
+                aria-hidden={shouldHideHandle || undefined}
+                aria-label={elementProps["aria-label"] ?? accessibleLabel}
+                data-resize-handle-id={resolvedHandleId}
+                title={title ?? accessibleLabel}>
+                {children ||
+                    (!isIndicatorExplicitlyHidden && (
+                        <div className={indicatorWrapperClasses} style={indicatorWrapperStyle} data-resize-handle-indicator="" aria-hidden="true">
+                            <span className={indicatorBarClasses} style={indicatorBarStyle} data-resize-handle-indicator-bar="" aria-hidden="true" />
+                        </div>
+                    ))}
+            </button>
+        </div>
     )
 })