@aiquants/resize-panels 1.9.0 → 2.0.0

package/src/hooks.ts

@@ -1,647 +1,220 @@
 /**
  * @file Custom hooks for resizable panels logic
  * リサイズ可能パネルのロジックのためのカスタムフック
+ *
+ * The hook owns everything the reducer cannot: it measures the container, keeps the panel order in step
+ * with the DOM, and forwards user intent as actions. It never computes a panel size itself.
+ * フックはリデューサーが担えない役割だけを持つ: コンテナの計測、DOM 順との同期、利用者の意図のアクション化。
+ * パネルサイズ自体はここでは一切計算しない。
  */
 
 import { type CSSProperties, useCallback, useEffect, useLayoutEffect, useMemo, useReducer, useRef, useState } from "react"
 import { usePanelGroup } from "./context"
-import { panelReducer } from "./reducer"
-import type { LayoutConstraintViolation, PanelCollapseDirection, PanelGroupProps, PanelLayoutData, PanelMeasurement, ResizeHandleLayoutData } from "./types"
-import { adjustPixelPanelsByPriority, clamp, getConstraintInPixels, getContainerSize, loadLayout, percentageToPixels, saveLayout, toRoundedPercentage } from "./utils"
+import { getPanelPreferenceInPixels, initialPanelGroupLayoutState, panelReducer } from "./reducer"
+import type { PanelCollapseDirection, PanelGroupProps, PanelMeasurement, PanelRegistration, PersistedPanelSize, ResizeHandleLayoutData } from "./types"
+import { getContainerSize, getGroupLayoutElements, loadLayout, saveLayout, touchesLayoutElements } from "./utils"
 import { Logger, LogLevel } from "./utils/simple-logger"
 
 const logger = new Logger(LogLevel.INFO, "[resize-panels]")
 
 /**
- * Orchestrate registration, constraint resolution, measurement sync, and persistence for a panel group.
- * パネルグループにおける登録処理・制約判定・計測同期・永続化の統括。
+ * Delay before the layout is written to storage, in milliseconds.
+ * レイアウトを保存領域へ書き出すまでの待機時間 (ms)。
+ */
+const AUTO_SAVE_DELAY_MS = 200
+
+/**
+ * Placeholder that stands for a handle anchor in the group's DOM-order key.
+ * グループの DOM 順を表す鍵の中で、ハンドルのアンカーを表す標識。
+ */
+const HANDLE_ANCHOR_ORDER_MARK = "\u0000handle"
+
+/**
+ * Orchestrate measurement, ordering, persistence and user intent for one panel group.
+ * 1 つのパネルグループにおける計測・順序同期・永続化・利用者操作の統括。
+ *
+ * @param props - Panel group props / パネルグループのプロパティ
+ * @returns Group ref, context value and the group's base style / グループ ref・コンテキスト値・基準スタイル
  */
 export const useResizablePanels = ({ direction, style, onLayout, autoSaveId, showDebugInfo = false }: PanelGroupProps) => {
-    const [panels, dispatch] = useReducer(panelReducer, [])
-    const [containerSize, setContainerSize] = useState({ width: 0, height: 0 })
-    const [isContainerReady, setIsContainerReady] = useState(false)
-    const [isInitialized, setIsInitialized] = useState(false)
-    const [layoutConstraintViolation, setLayoutConstraintViolation] = useState<LayoutConstraintViolation | null>(null)
+    const [layout, dispatch] = useReducer(panelReducer, initialPanelGroupLayoutState)
     const [panelMeasurements, setPanelMeasurements] = useState<Record<string, PanelMeasurement>>({})
     const [handleMeasurements, setHandleMeasurements] = useState<Record<string, ResizeHandleLayoutData>>({})
+
     const groupRef = useRef<HTMLDivElement>(null)
+    const [layoutOrderKey, setLayoutOrderKey] = useState("")
+    const registrationSignaturesRef = useRef<Record<string, string>>({})
     const layoutCallbackRef = useRef(onLayout)
-    const initializedRef = useRef(false)
-    const initializedPanelCountRef = useRef(0)
-    const prevContainerSizeRef = useRef(containerSize)
-    const containerInfoRef = useRef(containerSize)
-    const isContainerReadyRef = useRef(isContainerReady)
-    const violationReasonRef = useRef<LayoutConstraintViolation["reason"] | null>(layoutConstraintViolation?.reason ?? null)
-    const panelRegistrationSnapshotRef = useRef<Record<string, string>>({})
-    const lastStablePanelsRef = useRef<PanelLayoutData[] | null>(null)
-    const previousViolationRef = useRef<LayoutConstraintViolation | null>(null)
-    const containerSyncTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
-    const lastRawContainerSizeRef = useRef({ width: 0, height: 0 })
-    const committedContainerSizeRef = useRef({ width: 0, height: 0 })
-    const panelSyncTimersRef = useRef<Record<string, ReturnType<typeof setTimeout>>>({})
-    const lastRawPanelMeasurementsRef = useRef<Record<string, PanelMeasurement>>({})
-
-    const clonePanels = useCallback((panelList: PanelLayoutData[]) => {
-        return panelList.map((panel) => ({ ...panel }))
-    }, [])
-
-    useEffect(() => {
-        containerInfoRef.current = containerSize
-    }, [containerSize])
-
-    useEffect(() => {
-        isContainerReadyRef.current = isContainerReady
-    }, [isContainerReady])
-
-    useEffect(() => {
-        violationReasonRef.current = layoutConstraintViolation?.reason ?? null
-    }, [layoutConstraintViolation?.reason])
+    layoutCallbackRef.current = onLayout
 
-    useEffect(() => {
-        if (layoutConstraintViolation) {
-            return
-        }
-        const axisSize = direction === "horizontal" ? containerSize.width : containerSize.height
-        if (!Number.isFinite(axisSize) || axisSize <= 4) {
-            return
-        }
-        if (panels.length === 0) {
+    useLayoutEffect(() => {
+        // ResizeObserver でグループの内容領域長を追跡する。観測値は丸めも遅延もせずそのまま確定させる:
+        // 端数を落とすと、状態が持つ長さと描画される長さがずれたままになる。
+        // 主軸の長さが動かないフレーム (交差軸だけのリサイズ) はここで捨てる。reducer は同一状態を
+        // 返すものの、dispatch 自体がレンダーを予約してしまうため
+        const element = groupRef.current
+        if (!element || typeof ResizeObserver === "undefined") {
             return
         }
-        lastStablePanelsRef.current = clonePanels(panels)
-    }, [layoutConstraintViolation, panels, direction, containerSize.width, containerSize.height, clonePanels])
-
-    // 回復 effect から最新のパネル一覧を参照するための ref (依存に panels を入れると復元が違反解除の一回に限定できない)
-    const latestPanelsRef = useRef(panels)
-    useEffect(() => {
-        latestPanelsRef.current = panels
-    }, [panels])
 
-    useEffect(() => {
-        const previousViolation = previousViolationRef.current
-        if (layoutConstraintViolation) {
-            previousViolationRef.current = layoutConstraintViolation
-            return
-        }
-        if (previousViolation && !layoutConstraintViolation && lastStablePanelsRef.current) {
-            previousViolationRef.current = null
-            // 現在も登録されているパネルだけを復元する。
-            // 違反中に登録解除されたパネルをスナップショットから復活させると、対応するコンポーネントが
-            // 存在しないゾンビパネルとなり、違反も再発して解除不能になる
-            const registeredIds = new Set(latestPanelsRef.current.map((panel) => panel.id))
-            const snapshot = clonePanels(lastStablePanelsRef.current).filter((panel) => registeredIds.has(panel.id))
-            if (snapshot.length > 0) {
-                dispatch({ type: "SET_PANELS", panels: snapshot })
+        let lastContent = Number.NaN
+        const commitContentLength = (content: number) => {
+            if (content === lastContent) {
+                return
             }
-            return
+            lastContent = content
+            dispatch({ type: "SET_CONTAINER_SIZE", containerSize: content })
         }
-        previousViolationRef.current = layoutConstraintViolation
-    }, [layoutConstraintViolation, clonePanels])
 
-    // コンテナサイズの変化を監視し、実測値が不安定な場合も安定した寸法を状態へ反映
-    useLayoutEffect(() => {
-        if (!groupRef.current) return
-
-        const resizeObserver = new ResizeObserver((entries) => {
-            for (const entry of entries) {
-                const targetElement = entry.target as HTMLElement
-                // getContainerSize の inner (枠線控除済み) を優先し、取得できない場合は contentRect をフォールバックに使用
-                const widthMeasurement = targetElement ? getContainerSize(targetElement, "horizontal") : null
-                const heightMeasurement = targetElement ? getContainerSize(targetElement, "vertical") : null
-                const measuredWidth = widthMeasurement ? widthMeasurement.inner : 0
-                const measuredHeight = heightMeasurement ? heightMeasurement.inner : 0
-                const fallbackWidth = entry.contentRect.width
-                const fallbackHeight = entry.contentRect.height
-                const width = measuredWidth > 0 ? measuredWidth : fallbackWidth
-                const height = measuredHeight > 0 ? measuredHeight : fallbackHeight
-                lastRawContainerSizeRef.current = { width, height }
-
-                const prev = committedContainerSizeRef.current
-                const isWidthChanged = Math.abs(prev.width - width) >= 0.5
-                const isHeightChanged = Math.abs(prev.height - height) >= 0.5
-
-                if (isWidthChanged || isHeightChanged) {
-                    // 閾値を超える変化は即座に反映し、待機中の同期をキャンセル
-                    if (containerSyncTimerRef.current) {
-                        clearTimeout(containerSyncTimerRef.current)
-                        containerSyncTimerRef.current = null
-                    }
-                    if (!isContainerReady && width > 0 && height > 0) {
-                        setIsContainerReady(true)
-                    }
-                    setContainerSize({ width, height })
-                    committedContainerSizeRef.current = { width, height }
-                } else {
-                    // 微小な変化はノイズとして即時更新はせず、静止後に最終同期をスケジュール
-                    if (containerSyncTimerRef.current) {
-                        clearTimeout(containerSyncTimerRef.current)
-                    }
-                    containerSyncTimerRef.current = setTimeout(() => {
-                        const finalSize = lastRawContainerSizeRef.current
-                        setContainerSize(finalSize)
-                        committedContainerSizeRef.current = finalSize
-                        containerSyncTimerRef.current = null
-                    }, 150)
-                }
-            }
+        const observer = new ResizeObserver((entries) => {
+            commitContentLength(getContainerSize(element, direction, entries[0]).content)
         })
 
-        resizeObserver.observe(groupRef.current)
-        return () => {
-            resizeObserver.disconnect()
-            if (containerSyncTimerRef.current) {
-                clearTimeout(containerSyncTimerRef.current)
-            }
-        }
-    }, [isContainerReady])
+        observer.observe(element)
+        // 初回描画を正しい配分で塗るための種。観測が届いた時点で厳密値へ置き換わる
+        commitContentLength(getContainerSize(element, direction).content)
 
-    useEffect(() => {
-        // アンマウント時に全てのパネル同期タイマーをクリア
         return () => {
-            for (const timer of Object.values(panelSyncTimersRef.current)) {
-                clearTimeout(timer)
-            }
-        }
-    }, [])
-
-    useLayoutEffect(() => {
-        const prevSize = prevContainerSizeRef.current
-        const currentSize = containerSize
-        // 0.5px 未満の微小な変化はノイズとして扱い、リサイズイベントの発火を抑制
-        const hasResized = direction === "horizontal" ? Math.abs(prevSize.width - currentSize.width) >= 0.5 : Math.abs(prevSize.height - currentSize.height) >= 0.5
-
-        // 初期化完了後にコンテナサイズが一定以上変化した場合、リサイズイベントを発行
-        if (isInitialized && hasResized) {
-            const newContainerSize = direction === "horizontal" ? currentSize.width : currentSize.height
-            dispatch({ type: "CONTAINER_RESIZED", containerSize: newContainerSize, direction })
+            observer.disconnect()
         }
-
-        prevContainerSizeRef.current = currentSize
-    }, [containerSize, isInitialized, direction])
-
-    /**
-     * Resolve pending panel initialization, reconcile constraint bounds against fresh measurements, and recover stored sizes.
-     * 初期化時にパネル整合性を再判定し、最新計測と制約を突き合わせた上で保存済み寸法を復元する処理。
-     */
-    const initializePanelsIfNeeded = useCallback(() => {
-        logger.debug("panels[0]?.id", panels[0]?.id)
-        // 折り畳み可能パネルや一時的にゼロへスナップしたパネルで保存済みピクセルサイズまたはパーセンテージがあるのにサイズが未解決の場合を検出
-        const hasUnresolvedPanels = panels.some((panel) => {
-            if (panel.collapsed) {
-                return false
-            }
-            if (panel.sizeUnit !== "percentage") {
-                return false
-            }
-            // 折り畳み前または直近測定のピクセルサイズを取得し、スナップゼロの復元に備える
-            const panelIsCollapsible = panel.collapseFromStart || panel.collapseFromEnd
-            const storedPixel = panelIsCollapsible ? (panel.sizeBeforeCollapse ?? panel.measuredPixelSizeBeforeCollapse ?? panel.originalPixelSize ?? panel.measuredPixelSize ?? 0) : (panel.measuredPixelSize ?? panel.originalPixelSize ?? panel.size)
-            const hasStoredPercentage = panel.percentageSize !== undefined && panel.percentageSize > 0
-            return panel.size <= 0 && (storedPixel > 0 || hasStoredPercentage)
-        })
-
-        // containerSize は getContainerSize(inner) により枠線控除済みの実寸法
-        const axisSize = direction === "horizontal" ? containerSize.width : containerSize.height
-        const hasContainerMeasurement = axisSize > 0
-
-        // 制約違反が検出されている場合は初期化をスキップ
-        if (layoutConstraintViolation) {
-            return
-        }
-
-        // コンテナサイズが未計測の場合は初期化をスキップ
-        if (!hasContainerMeasurement) {
+    }, [direction])
+
+    const panels = layout.panels
+    const panelsRef = useRef(panels)
+    panelsRef.current = panels
+
+    const syncPanelOrder = useCallback(() => {
+        // パネルは DOM 順に並んでいることが前提の状態 (保存・onLayout・優先度の同順位比較) なので、
+        // 登録順と DOM 順がずれたら DOM 側へ合わせ直す
+        const element = groupRef.current
+        const currentPanels = panelsRef.current
+        if (!element) {
             return
         }
-
-        // 未初期化パネルや折り畳み復元待ちパネルが残っているか判定
-        const needsInitialization = panels.length > 0 && (panels.length !== initializedPanelCountRef.current || !isInitialized || hasUnresolvedPanels)
-
-        if (!needsInitialization) {
+        const layoutElements = getGroupLayoutElements(element)
+        // ハンドルが別の境界へ移っただけの並べ替えはパネルの id 列を変えない。
+        // アンカーの位置も含めた並びを鍵にして、ハンドル側の再検出も同じ変化で起こす
+        setLayoutOrderKey((previous) => {
+            const next = layoutElements.map((layoutElement) => layoutElement.dataset.panelId ?? HANDLE_ANCHOR_ORDER_MARK).join("\u0000")
+            return previous === next ? previous : next
+        })
+        if (currentPanels.length === 0) {
             return
         }
-
-        // ピクセル基準パネルを抽出し固定領域を先に確保
-        const pixelPanels = panels.filter((panel) => !panel.collapsed && (panel.originalPixelSize !== undefined || panel.sizeUnit === "pixels"))
-        const allocatedPixelSpace = pixelPanels.reduce((sum, panel) => {
-            const preferredPixelSize = panel.preferredPixelSize ?? panel.originalPixelSize ?? panel.size
-            return sum + Math.max(0, preferredPixelSize ?? 0)
-        }, 0)
-
-        const activePercentagePanels = panels.filter((panel) => panel.sizeUnit === "percentage" && !panel.collapsed)
-        const activePercentageIds = activePercentagePanels.map((panel) => panel.id)
-        // パーセンテージ指定パネルの希望ピクセル値を再計算
-        const preferredPixelSnapshots = activePercentagePanels.map((panel) => {
-            const preferredPercentage = panel.preferredPercentageSize ?? panel.percentageSize
-            if (preferredPercentage !== undefined && preferredPercentage > 0) {
-                return percentageToPixels(preferredPercentage, axisSize)
-            }
-            if (panel.size > 0) {
-                return panel.size
-            }
-            return 0
-        })
-        const totalPreferredPixels = preferredPixelSnapshots.reduce((sum, value) => sum + value, 0)
-
-        // 固定領域を除いた残余スペースを算出し柔軟パネル側の調整有無を判断
-        const remainingSpace = axisSize - allocatedPixelSpace
-        const remainingFlexibleSpace = Math.max(0, remainingSpace)
-        const hasFlexibleRoom = remainingFlexibleSpace > 0
-
-        // パネルごとに復元・再計算した最終的な状態を集約
-        // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: Panel resolution logic
-        const resolvedPanels = panels.map((panel) => {
-            if (panel.collapsed) {
-                // 折り畳み中パネルの復元用サイズを優先順で決定 (ピクセル基準)
-                // 優先順: sizeBeforeCollapse → measuredPixelSizeBeforeCollapse → originalPixelSize → size (pixels単位のみ)
-                const storedPixel = panel.sizeBeforeCollapse ?? panel.measuredPixelSizeBeforeCollapse ?? panel.originalPixelSize ?? (panel.sizeUnit === "pixels" ? panel.size : undefined)
-
-                // パーセンテージ単位パネルの場合は割合からピクセルへ変換
-                const restoredSizeFromPercentage = panel.sizeUnit === "percentage" && panel.percentageSize !== undefined ? percentageToPixels(panel.percentageSize, axisSize) : undefined
-
-                // 復元後に採用するサイズと測定スナップショットを決定
-                const recoveredSize = storedPixel ?? restoredSizeFromPercentage ?? 0
-                const recoveredMeasured = panel.measuredPixelSizeBeforeCollapse ?? panel.measuredPixelSize ?? recoveredSize
-
-                return {
-                    ...panel,
-                    size: 0,
-                    percentageSize: 0,
-                    preferredPercentageSize: panel.preferredPercentageSize,
-                    sizeBeforeCollapse: recoveredSize,
-                    percentageSizeBeforeCollapse: panel.percentageSizeBeforeCollapse ?? panel.percentageSize ?? panel.preferredPercentageSize ?? 0,
-                    preferredPercentageSizeBeforeCollapse: panel.preferredPercentageSizeBeforeCollapse ?? panel.preferredPercentageSize ?? panel.percentageSize ?? undefined,
-                    preferredPixelSizeBeforeCollapse: panel.preferredPixelSizeBeforeCollapse ?? panel.preferredPixelSize ?? recoveredSize,
-                    measuredPixelSizeBeforeCollapse: recoveredMeasured,
-                }
-            }
-
-            if (panel.sizeUnit === "pixels" || panel.originalPixelSize !== undefined) {
-                // 既にピクセル基準のパネルは測定値を再計算しつつそのまま採用
-                const pixelSize = panel.size
-                const percentageSize = axisSize > 0 ? toRoundedPercentage(pixelSize, axisSize) : 0
-
-                const nextPanel = {
-                    ...panel,
-                    size: pixelSize,
-                    percentageSize,
-                    preferredPixelSize: panel.preferredPixelSize ?? panel.originalPixelSize ?? pixelSize,
-                    preferredPercentageSize: panel.preferredPercentageSize !== undefined ? panel.preferredPercentageSize : percentageSize > 0 ? percentageSize : undefined,
-                }
-
-                if (panel.collapseFromStart || panel.collapseFromEnd) {
-                    // 折り畳み可能パネルは復元用のピクセルサイズと測定スナップショットを保持
-                    const storedSize = panel.sizeBeforeCollapse ?? pixelSize
-                    const storedMeasured = panel.measuredPixelSizeBeforeCollapse ?? panel.measuredPixelSize ?? storedSize
-                    nextPanel.sizeBeforeCollapse = storedSize
-                    nextPanel.measuredPixelSizeBeforeCollapse = storedMeasured
-                    nextPanel.preferredPixelSizeBeforeCollapse = panel.preferredPixelSizeBeforeCollapse ?? panel.preferredPixelSize ?? storedSize
-                }
-
-                return nextPanel
-            }
-
-            if (panel.sizeUnit === "percentage") {
-                // パーセンテージ基準パネルは希望寸法と制約を照らし合わせて実ピクセルへ再配分
-                const activeIndex = activePercentageIds.indexOf(panel.id)
-                const preferredPixels = activeIndex !== -1 ? preferredPixelSnapshots[activeIndex] : 0
-                const minSize = getConstraintInPixels(panel.minSize, 0, axisSize)
-                const maxSize = getConstraintInPixels(panel.maxSize, axisSize, axisSize)
-                // 過去の測定や折り畳み前サイズを重みとして再利用し柔軟パネルの再配分に最低限の基準を設ける
-                const fallbackPixels = Math.max(
-                    minSize,
-                    panel.sizeBeforeCollapse ?? 0,
-                    panel.measuredPixelSizeBeforeCollapse ?? 0,
-                    panel.measuredPixelSize ?? 0,
-                    panel.originalPixelSize ?? 0,
-                    panel.size > 0 ? panel.size : 0,
-                    panel.percentageSize !== undefined ? percentageToPixels(panel.percentageSize, axisSize) : 0,
-                    1,
-                )
-                const effectivePreferred = preferredPixels > 0 ? preferredPixels : fallbackPixels
-
-                let targetPixels: number
-
-                if (!hasFlexibleRoom) {
-                    // 柔軟領域が尽きている場合(ピクセルパネルがコンテナを使い切っている)、
-                    // パーセンテージパネルは最小サイズ(通常0)にする
-                    targetPixels = minSize
-                } else if (activeIndex !== -1 && totalPreferredPixels > 0) {
-                    // 希望比率に沿って残余領域を配分
-                    const ratio = effectivePreferred / totalPreferredPixels
-                    const candidatePixels = remainingFlexibleSpace * ratio
-                    targetPixels = clamp(candidatePixels, minSize, maxSize)
-                } else {
-                    // 現状または復元候補の寸法を基準に上限・下限内へ補正
-                    const currentPixels = panel.percentageSize !== undefined ? percentageToPixels(panel.percentageSize, axisSize) : panel.size
-                    const baselinePixels = currentPixels > 0 ? currentPixels : effectivePreferred
-                    targetPixels = clamp(baselinePixels, minSize, maxSize)
-                }
-
-                const nextPercentage = axisSize > 0 ? toRoundedPercentage(targetPixels, axisSize) : 0
-
-                const nextPanel = {
-                    ...panel,
-                    size: targetPixels,
-                    percentageSize: nextPercentage,
-                    preferredPercentageSize: panel.preferredPercentageSize !== undefined ? panel.preferredPercentageSize : nextPercentage > 0 ? nextPercentage : undefined,
-                }
-
-                if (panel.collapseFromStart || panel.collapseFromEnd) {
-                    const storedSize = panel.sizeBeforeCollapse ?? targetPixels
-                    const storedMeasured = panel.measuredPixelSizeBeforeCollapse ?? panel.measuredPixelSize ?? storedSize
-                    nextPanel.sizeBeforeCollapse = storedSize
-                    nextPanel.measuredPixelSizeBeforeCollapse = storedMeasured
-                    nextPanel.preferredPixelSizeBeforeCollapse = panel.preferredPixelSizeBeforeCollapse ?? panel.preferredPixelSize ?? storedSize
-                }
-
-                return nextPanel
-            }
-
-            return panel
-        })
-
-        // 柔軟パネルのインデックスを収集
-        const flexibleIndices: number[] = []
-        for (let index = 0; index < resolvedPanels.length; index += 1) {
-            const panel = resolvedPanels[index]
-            if (panel.sizeUnit === "percentage" && !panel.collapsed) {
-                flexibleIndices.push(index)
+        const ids: string[] = []
+        for (const layoutElement of layoutElements) {
+            const id = layoutElement.dataset.panelId
+            if (id !== undefined) {
+                ids.push(id)
             }
         }
-
-        // 柔軟パネルに割り当てたピクセル合計と残余スペースの差分を計算
-        const allocatedFlexiblePixels = flexibleIndices.reduce((sum, index) => sum + resolvedPanels[index].size, 0)
-        const flexibleDiff = remainingSpace - allocatedFlexiblePixels
-
-        // 差分が閾値を超える場合はピクセルパネルの優先度順に吸収
-        if (Math.abs(flexibleDiff) > 0) {
-            adjustPixelPanelsByPriority(resolvedPanels, flexibleDiff, axisSize, { enforceAutoMinSize: true })
+        if (new Set(ids).size !== ids.length) {
+            // 同じ id のパネルが同時に存在すると 1 つの状態を 2 枚が描画し、合計がコンテナを超える
+            logger.error("Duplicate panel id in one group.", { ids })
+            return
         }
-
-        dispatch({ type: "SET_PANELS", panels: resolvedPanels })
-        initializedPanelCountRef.current = panels.length
-        setIsInitialized(true)
-    }, [panels, direction, containerSize.width, containerSize.height, isInitialized, layoutConstraintViolation])
-
-    // 制約チェックを独立して実行（コンテナサイズ変更時にも常に動作）
-    useEffect(() => {
-        // containerSize は getContainerSize(inner) により枠線控除済みの実寸法
-        const axisSize = direction === "horizontal" ? containerSize.width : containerSize.height
-        const hasContainerMeasurement = axisSize > 0
-
-        // 実測コンテナ寸法と登録済みパネルの有無から制約評価の要否を判断
-        const shouldEvaluateConstraints = hasContainerMeasurement && panels.length > 0
-
-        // パネルが存在しなければ制約違反そのものが成立しない
-        // (下の stale な違反 totals へのフォールバックに入ると、全パネル登録解除後も違反が永続してしまう)
-        if (hasContainerMeasurement && panels.length === 0) {
-            if (layoutConstraintViolation) {
-                setLayoutConstraintViolation(null)
-            }
+        if (ids.length !== currentPanels.length || ids.every((id, index) => id === currentPanels[index].id)) {
             return
         }
+        dispatch({ type: "REORDER_PANELS", ids })
+    }, [])
 
-        // 有効なパネルが存在する場合は最小値と最大値の合計を算出
-        const totalMinimum = shouldEvaluateConstraints
-            ? panels.reduce((sum, panel) => {
-                  if (panel.collapsed) {
-                      return sum
-                  }
-                  const minPixels = getConstraintInPixels(panel.minSize, 0, axisSize)
-                  return sum + Math.max(0, minPixels)
-              }, 0)
-            : null
-        const totalMaximum = shouldEvaluateConstraints
-            ? panels.reduce((sum, panel) => {
-                  if (panel.collapsed) {
-                      return sum
-                  }
-                  const maxPixels = getConstraintInPixels(panel.maxSize, axisSize, axisSize)
-                  return sum + Math.max(0, maxPixels)
-              }, 0)
-            : null
-
-        // 直近の違反情報をフォールバックとして利用しつつ最新計算結果を優先
-        const effectiveMinimum = totalMinimum ?? layoutConstraintViolation?.totalMinimumSize ?? null
-        const effectiveMaximum = totalMaximum ?? layoutConstraintViolation?.totalMaximumSize ?? null
-
-        if (!hasContainerMeasurement) {
-            // 寸法が取得できていない場合は違反情報のみ更新し後段処理を停止
-            if (layoutConstraintViolation) {
-                setLayoutConstraintViolation((previous) => {
-                    if (!previous) {
-                        return previous
-                    }
-                    if (previous.availableContainerSize === axisSize) {
-                        return previous
-                    }
-                    return {
-                        reason: previous.reason,
-                        // totalMinimumSize: previous.totalMinimumSize,
-                        // totalMaximumSize: previous.totalMaximumSize,
-                        totalMinimumSize: null,
-                        totalMaximumSize: null,
-                        availableContainerSize: axisSize,
-                    }
-                })
-            }
+    useLayoutEffect(() => {
+        // 並べ替えは登録・解除を伴わないことがある (JSX 上の順序だけを入れ替えた場合など)。
+        // 状態の変化を待つと取りこぼすため、DOM の子要素の変化そのものを監視する
+        const element = groupRef.current
+        if (!element) {
             return
         }
-
-        // コンテナ寸法と総制約を比較して違反を検出
-        const minimumExceeded = effectiveMinimum !== null && effectiveMinimum - axisSize > Number.EPSILON
-        const maximumInsufficient = effectiveMaximum !== null && axisSize - effectiveMaximum > Number.EPSILON
-
-        if (minimumExceeded || maximumInsufficient) {
-            const reason = minimumExceeded ? "minimum-exceeded" : "maximum-insufficient"
-            const nextViolation: LayoutConstraintViolation = {
-                reason,
-                totalMinimumSize: effectiveMinimum,
-                totalMaximumSize: effectiveMaximum,
-                availableContainerSize: axisSize,
-            }
-
-            // 同一内容の違反通知を繰り返さないよう差分がある場合のみ更新
-            setLayoutConstraintViolation((previous) => {
-                if (
-                    previous &&
-                    previous.reason === nextViolation.reason &&
-                    Math.abs((previous.totalMinimumSize ?? 0) - (nextViolation.totalMinimumSize ?? 0)) <= Number.EPSILON &&
-                    Math.abs((previous.totalMaximumSize ?? 0) - (nextViolation.totalMaximumSize ?? 0)) <= Number.EPSILON &&
-                    Math.abs(previous.availableContainerSize - nextViolation.availableContainerSize) <= Number.EPSILON
-                ) {
-                    return previous
-                }
-                return nextViolation
-            })
+        syncPanelOrder()
+        if (typeof MutationObserver === "undefined") {
             return
         }
-
-        if (layoutConstraintViolation) {
-            // 違反が発生していた場合は解消済みかどうかを判定
-            const requiresMinimum = layoutConstraintViolation.reason === "minimum-exceeded"
-            const requiresMaximum = layoutConstraintViolation.reason === "maximum-insufficient"
-            const hasMinimumData = effectiveMinimum !== null
-            const hasMaximumData = effectiveMaximum !== null
-            const canEvaluateMinimum = !requiresMinimum || hasMinimumData
-            const canEvaluateMaximum = !requiresMaximum || hasMaximumData
-
-            if (canEvaluateMinimum && canEvaluateMaximum && !minimumExceeded && !maximumInsufficient) {
-                // 条件が揃い再違反が検出されなければ違反状態を解除
-                setLayoutConstraintViolation((previous) => (previous ? null : previous))
+        const observer = new MutationObserver((records) => {
+            // 配置要素に触れない変更は無視する。パネルの内容 (仮想化リストの行など) は毎フレーム
+            // 入れ替わるため、すべての変更で走査するとグループ全体に比例した費用を払い続ける
+            if (touchesLayoutElements(records)) {
+                syncPanelOrder()
             }
+        })
+        // 中間要素の中での並べ替えも拾うため subtree ごと監視する
+        observer.observe(element, { childList: true, subtree: true })
+        return () => {
+            observer.disconnect()
         }
-    }, [panels, direction, containerSize.width, containerSize.height, layoutConstraintViolation])
+    }, [syncPanelOrder])
 
-    // 初期化漏れを防止するために必要時にリソルブ処理を呼び出す
-    useEffect(() => {
-        initializePanelsIfNeeded()
-    }, [initializePanelsIfNeeded])
-
-    // 最新のレイアウト通知コールバックを参照に保持
-    useEffect(() => {
-        layoutCallbackRef.current = onLayout
-    }, [onLayout])
+    useLayoutEffect(() => {
+        syncPanelOrder()
+    }, [syncPanelOrder, panels])
 
-    // レイアウト通知のためにパネルサイズ一覧をメモ化
     const panelSizes = useMemo(() => panels.map((panel) => panel.size), [panels])
+    const hasMeasuredContainer = layout.containerSize > 0
 
-    // 初期化前の未確定サイズ (登録直後のパーセンテージパネルは 0) を onLayout や自動保存へ流さないためのゲート。
-    // 一度確定したら以降はゼロを含むレイアウト (スナップ等) も正しい状態として通知する
-    const hasSettledLayoutRef = useRef(false)
-
-    // 初期化後にレイアウトリスナーへ寸法を通知
     useLayoutEffect(() => {
-        if (panels.length === 0) {
-            // 全パネルが登録解除されたら次の構成のために未確定状態へ戻す
-            hasSettledLayoutRef.current = false
-            return
-        }
-        if (!hasSettledLayoutRef.current && (isInitialized || panels.every((panel) => panel.collapsed || panel.size > 0))) {
-            hasSettledLayoutRef.current = true
-        }
-        if (!hasSettledLayoutRef.current) {
+        // 未計測の 0 配列を通知しない。配分はコンテナ計測後に一度で確定するため、通知は常に確定値になる
+        if (!hasMeasuredContainer || panelSizes.length === 0) {
             return
         }
-        if (layoutCallbackRef.current) {
-            layoutCallbackRef.current(panelSizes)
-        }
-    }, [panelSizes, panels, isInitialized])
+        layoutCallbackRef.current?.(panelSizes)
+    }, [panelSizes, hasMeasuredContainer])
 
-    // 自動保存を遅延実行して書き込み回数を抑制
+    const restoredKeyRef = useRef<string | null>(null)
     useEffect(() => {
-        // 未確定レイアウト (初期化前のゼロ) を保存すると復元時に壊れた配置になるため確定後のみ保存する
-        if (autoSaveId && panelSizes.length > 0 && hasSettledLayoutRef.current) {
-            // デバウンス処理: 200ms 後に自動保存を実行
-            const timeoutId = setTimeout(() => {
-                saveLayout(autoSaveId, panelSizes)
-            }, 200)
-
-            return () => clearTimeout(timeoutId)
+        // 保存済みレイアウトは識別子ごとに一度だけ適用する
+        // (識別子が変われば、その識別子で保存された配置を読み直す)
+        if (!autoSaveId || restoredKeyRef.current === autoSaveId || !hasMeasuredContainer || panels.length === 0) {
+            return
+        }
+        restoredKeyRef.current = autoSaveId
+        const entries = loadLayout(autoSaveId)
+        if (entries) {
+            dispatch({ type: "RESTORE_LAYOUT", entries })
         }
-    }, [autoSaveId, panelSizes])
+    }, [autoSaveId, hasMeasuredContainer, panels.length])
 
-    // 保存済みレイアウトがあれば初回のみ読み込む
+    const pendingSaveRef = useRef<{ id: string; entries: PersistedPanelSize[] } | null>(null)
     useEffect(() => {
-        if (!autoSaveId || panels.length === 0 || initializedRef.current) {
+        if (!(autoSaveId && restoredKeyRef.current === autoSaveId && hasMeasuredContainer) || panels.length === 0) {
             return
         }
-
-        const axisSize = direction === "horizontal" ? containerSize.width : containerSize.height
-        if (axisSize <= 0) {
-            return
+        const entries = panels.map((panel) => ({ id: panel.id, size: getPanelPreferenceInPixels(panel, layout.containerSize), collapsed: panel.collapsed }))
+        pendingSaveRef.current = { id: autoSaveId, entries }
+        const timer = setTimeout(() => {
+            pendingSaveRef.current = null
+            saveLayout(autoSaveId, entries)
+        }, AUTO_SAVE_DELAY_MS)
+        // ここで保存まで行うと、ドラッグやリサイズの 1 フレームごとに同期 I/O が走り、待機時間が無意味になる
+        return () => {
+            clearTimeout(timer)
         }
+    }, [autoSaveId, panels, layout.containerSize, hasMeasuredContainer])
 
-        const savedSizes = loadLayout(autoSaveId)
-        if (savedSizes && savedSizes.length === panels.length) {
-            const updatedPanels = panels.map((panel, index) => {
-                const minPixels = getConstraintInPixels(panel.minSize, 0, axisSize)
-                const maxPixels = getConstraintInPixels(panel.maxSize, axisSize, axisSize)
-                const clampedSize = clamp(savedSizes[index], minPixels, maxPixels)
-                const nextPercentage = toRoundedPercentage(clampedSize, axisSize)
-                const nextPreferredPixelSize = panel.sizeUnit === "pixels" || panel.originalPixelSize !== undefined ? clampedSize : panel.preferredPixelSize
-                return {
-                    ...panel,
-                    size: clampedSize,
-                    percentageSize: nextPercentage,
-                    preferredPercentageSize: nextPercentage > 0 ? nextPercentage : panel.preferredPercentageSize,
-                    preferredPixelSize: nextPreferredPixelSize,
-                }
-            })
-            dispatch({ type: "SET_PANELS", panels: updatedPanels })
-            initializedRef.current = true
+    useEffect(() => {
+        // 書き出し前に画面を離れた場合でも最後の配置を残す (遷移直前に動かした幅が消えないように)
+        return () => {
+            const pending = pendingSaveRef.current
+            if (pending) {
+                pendingSaveRef.current = null
+                saveLayout(pending.id, pending.entries)
+            }
         }
-    }, [autoSaveId, panels, containerSize.width, containerSize.height, direction])
-
-    const registerPanel = useCallback((panel: PanelLayoutData) => {
-        const containerInfo = containerInfoRef.current
-        const registry = panelRegistrationSnapshotRef.current
-        const registrationSignature = JSON.stringify({
-            id: panel.id,
-            size: panel.size ?? null,
-            percentageSize: panel.percentageSize ?? null,
-            preferredPercentageSize: panel.preferredPercentageSize ?? null,
-            preferredPixelSize: panel.preferredPixelSize ?? null,
-            sizeUnit: panel.sizeUnit,
-            originalPixelSize: panel.originalPixelSize ?? null,
-            minSize: panel.minSize ?? null,
-            maxSize: panel.maxSize ?? null,
-            collapseFromStart: panel.collapseFromStart,
-            collapseFromEnd: panel.collapseFromEnd,
-            collapsed: panel.collapsed ?? false,
-            collapsedByDirection: panel.collapsedByDirection ?? null,
-            sizeBeforeCollapse: panel.sizeBeforeCollapse ?? null,
-            percentageSizeBeforeCollapse: panel.percentageSizeBeforeCollapse ?? null,
-            preferredPercentageSizeBeforeCollapse: panel.preferredPercentageSizeBeforeCollapse ?? null,
-            preferredPixelSizeBeforeCollapse: panel.preferredPixelSizeBeforeCollapse ?? null,
-            pixelAdjustPriority: panel.pixelAdjustPriority ?? null,
-            flexAdjustPriority: panel.flexAdjustPriority ?? null,
-            autoMinSize: panel.autoMinSize ?? null,
-        })
+    }, [])
 
-        if (registry[panel.id] === registrationSignature) {
-            logger.debug("useResizablePanels.registerPanel skipped", {
-                panelId: panel.id,
-                reason: "duplicate-registration",
-            })
+    const registerPanel = useCallback((panel: PanelRegistration) => {
+        // 同一内容の再登録は状態を触らない。props が変わっていないのに希望値を配り直すと、
+        // 直前のドラッグ結果を巻き戻してしまう
+        const signature = JSON.stringify(panel)
+        if (registrationSignaturesRef.current[panel.id] === signature) {
             return
         }
-
-        registry[panel.id] = registrationSignature
-        logger.debug("useResizablePanels.registerPanel", {
-            panelId: panel.id,
-            containerReady: isContainerReadyRef.current,
-            violationReason: violationReasonRef.current,
-            containerSize: {
-                width: containerInfo.width,
-                height: containerInfo.height,
-            },
-        })
-        // パネル登録アクションをディスパッチ
+        registrationSignaturesRef.current[panel.id] = signature
         dispatch({ type: "REGISTER_PANEL", panel })
     }, [])
 
     const unregisterPanel = useCallback((id: string) => {
-        const containerInfo = containerInfoRef.current
-        logger.debug("useResizablePanels.unregisterPanel", {
-            panelId: id,
-            containerReady: isContainerReadyRef.current,
-            violationReason: violationReasonRef.current,
-            containerSize: {
-                width: containerInfo.width,
-                height: containerInfo.height,
-            },
-        })
-        // パネル登録解除アクションをディスパッチし、測定情報もクリア
+        delete registrationSignaturesRef.current[id]
         dispatch({ type: "UNREGISTER_PANEL", id })
-        delete panelRegistrationSnapshotRef.current[id]
-        // 保留中の最終整合タイマーも破棄してゴーストエントリの再挿入を防ぐ
-        if (panelSyncTimersRef.current[id]) {
-            clearTimeout(panelSyncTimersRef.current[id])
-            delete panelSyncTimersRef.current[id]
-        }
-        delete lastRawPanelMeasurementsRef.current[id]
         setPanelMeasurements((previous) => {
             if (!(id in previous)) {
                 return previous
@@ -652,201 +225,41 @@ export const useResizablePanels = ({ direction, style, onLayout, autoSaveId, sho
         })
     }, [])
 
-    /**
-     * Apply constraint-aware pixel adjustments while resizing adjacent panels.
-     * 隣接パネルのリサイズ時に制約を考慮したピクセル調整を適用。
-     */
-    const resizePanels = useCallback(
-        (leftId: string, rightId: string, leftSize: number, rightSize: number) => {
-            // フック側は「制約を大きく外さない初期値」を作る役割、リデューサー側が「最終確定」の役割を担う
-            // フック側はドラッグ中の左右ペアに即座に制約を適用して「安全な候補サイズ」を算出するだけで、他パネルとの整合や割合正規化までは扱わない
-            // ここではリデューサーの最終判定前にドラッグ中のペアに即応する安全な暫定寸法だけを算出する
-
-            const currentContainerSize = direction === "horizontal" ? containerSize.width : containerSize.height
-
-            const leftPanel = panels.find((panel) => panel.id === leftId)
-            const rightPanel = panels.find((panel) => panel.id === rightId)
-
-            // パネル情報が未取得でも従来ロジックで更新を継続
-            if (!(leftPanel && rightPanel)) {
-                dispatch({ type: "RESIZE_PANELS", leftId, rightId, leftSize, rightSize, containerSize: currentContainerSize })
-                return
-            }
-
-            // いずれかのパネルが折りたたまれている場合はリサイズを中断
-            if (leftPanel.collapsed || rightPanel.collapsed) {
-                return
-            }
-
-            const leftMinSize = getConstraintInPixels(leftPanel.minSize, 0, currentContainerSize)
-            const leftMaxSize = getConstraintInPixels(leftPanel.maxSize, currentContainerSize, currentContainerSize)
-            const rightMinSize = getConstraintInPixels(rightPanel.minSize, 0, currentContainerSize)
-            const rightMaxSize = getConstraintInPixels(rightPanel.maxSize, currentContainerSize, currentContainerSize)
-
-            let constrainedLeftSize = clamp(leftSize, leftMinSize, leftMaxSize)
-            let constrainedRightSize = clamp(rightSize, rightMinSize, rightMaxSize)
-
-            const targetTotalSize = constrainedLeftSize + constrainedRightSize
-            const originalTotalSize = leftSize + rightSize
-
-            // 制約適用後のサイズ合計と元のサイズ合計が異なる場合は追加の調整を実施
-            if (Math.abs(targetTotalSize - originalTotalSize) > 1e-9) {
-                const sizeDifference = originalTotalSize - targetTotalSize
-
-                if (sizeDifference > 0) {
-                    // 差分が正の場合は両パネルの拡張可能量を按分して補填
-                    const leftExpansionCapacity = leftMaxSize - constrainedLeftSize
-                    const rightExpansionCapacity = rightMaxSize - constrainedRightSize
-                    const totalExpansionCapacity = leftExpansionCapacity + rightExpansionCapacity
-
-                    if (totalExpansionCapacity > 0) {
-                        const leftExpansion = Math.min(sizeDifference * (leftExpansionCapacity / totalExpansionCapacity), leftExpansionCapacity)
-                        const rightExpansion = Math.min(sizeDifference - leftExpansion, rightExpansionCapacity)
-
-                        constrainedLeftSize += leftExpansion
-                        constrainedRightSize += rightExpansion
-                    }
-                } else if (sizeDifference < 0) {
-                    // 差分が負の場合は両パネルの縮小可能量を按分して削減
-                    const absoluteDifference = Math.abs(sizeDifference)
-                    const leftReductionCapacity = constrainedLeftSize - leftMinSize
-                    const rightReductionCapacity = constrainedRightSize - rightMinSize
-                    const totalReductionCapacity = leftReductionCapacity + rightReductionCapacity
-
-                    if (totalReductionCapacity > 0) {
-                        const leftReduction = Math.min(absoluteDifference * (leftReductionCapacity / totalReductionCapacity), leftReductionCapacity)
-                        const rightReduction = Math.min(absoluteDifference - leftReduction, rightReductionCapacity)
-
-                        constrainedLeftSize -= leftReduction
-                        constrainedRightSize -= rightReduction
-                    }
-                }
-            }
-
-            // 最終的に制約範囲内に再クランプしてリサイズアクションを発行
-            constrainedLeftSize = clamp(constrainedLeftSize, leftMinSize, leftMaxSize)
-            constrainedRightSize = clamp(constrainedRightSize, rightMinSize, rightMaxSize)
-
-            if (Math.abs(constrainedLeftSize + constrainedRightSize - originalTotalSize) > 1e-9) {
-                logger.error("Total size after constraints should be close to the original total size.", { constrainedLeftSize, constrainedRightSize, originalTotalSize })
-            }
-
-            dispatch({ type: "RESIZE_PANELS", leftId, rightId, leftSize: constrainedLeftSize, rightSize: constrainedRightSize, containerSize: currentContainerSize })
-        },
-        [direction, containerSize.width, containerSize.height, panels],
-    )
+    const resizePanels = useCallback((startId: string, endId: string, startSize: number) => {
+        dispatch({ type: "RESIZE_PANELS", startId, endId, startSize })
+    }, [])
 
-    /**
-     * Collapse a panel while passing the current container size to the reducer.
-     * 現在のコンテナ寸法を渡しつつパネルの折り畳みを指示。
-     */
-    const collapsePanel = useCallback(
-        (id: string, from: PanelCollapseDirection) => {
-            // 現在のコンテナサイズを渡してパネル折りたたみアクションを発行
-            const currentContainerSize = direction === "horizontal" ? containerSize.width : containerSize.height
-            dispatch({ type: "COLLAPSE_PANEL", id, from, containerSize: currentContainerSize })
-        },
-        [direction, containerSize.width, containerSize.height],
-    )
+    const collapsePanel = useCallback((id: string, from: PanelCollapseDirection) => {
+        dispatch({ type: "COLLAPSE_PANEL", id, from })
+    }, [])
 
-    /**
-     * Expand a panel with an optional target size in pixels.
-     * 任意のピクセル指定を考慮したパネル展開の指示。
-     */
-    const expandPanel = useCallback(
-        (id: string, from: PanelCollapseDirection, targetSize?: number) => {
-            // 現在のコンテナサイズを渡してパネル展開アクションを発行
-            const currentContainerSize = direction === "horizontal" ? containerSize.width : containerSize.height
-            dispatch({ type: "EXPAND_PANEL", id, from, containerSize: currentContainerSize, targetSize })
-        },
-        [direction, containerSize.width, containerSize.height],
-    )
+    const expandPanel = useCallback((id: string, from: PanelCollapseDirection, targetSize?: number) => {
+        dispatch({ type: "EXPAND_PANEL", id, from, targetSize })
+    }, [])
 
-    /**
-     * Retrieve current layout data for the target panel.
-     * 対象パネルの最新レイアウトデータの取得。
-     */
-    const getPanel = useCallback(
-        (id: string) => {
-            // 指定 ID のパネルデータを返す
-            return panels.find((panel) => panel.id === id)
-        },
-        [panels],
-    )
+    const getPanel = useCallback((id: string) => panels.find((panel) => panel.id === id), [panels])
 
-    /**
-     * Synchronize reported panel measurements with local measurement state.
-     * パネルから報告された測定情報の状態同期。
-     */
     const reportPanelMeasurement = useCallback((panelId: string, measurement: PanelMeasurement | null) => {
-        if (measurement === null) {
-            // 保留中の最終整合タイマーと raw 測定値を破棄する
-            // (残したままだとパネル登録解除後にタイマーが発火してゴーストエントリを再挿入する)
-            if (panelSyncTimersRef.current[panelId]) {
-                clearTimeout(panelSyncTimersRef.current[panelId])
-                delete panelSyncTimersRef.current[panelId]
-            }
-            delete lastRawPanelMeasurementsRef.current[panelId]
-
-            // 測定結果が null の場合はエントリを削除
-            setPanelMeasurements((previous) => {
+        setPanelMeasurements((previous) => {
+            if (measurement === null) {
                 if (!(panelId in previous)) {
                     return previous
                 }
                 const next = { ...previous }
                 delete next[panelId]
                 return next
-            })
-            return
-        }
-
-        setPanelMeasurements((previous) => {
+            }
             const current = previous[panelId]
-            // 測定値が前回と実質的に同一であれば即時更新はスキップ (0.1px 未満の差異はノイズ)
-            const isPixelStable = current && Math.abs(current.pixelSize - measurement.pixelSize) < 0.1
-            const isPercentageStable = current && Math.abs(current.percentageSize - measurement.percentageSize) < 0.01
-
-            if (isPixelStable && isPercentageStable) {
-                // 静止後の最終整合のためにタイマーを再設定
-                if (panelSyncTimersRef.current[panelId]) {
-                    clearTimeout(panelSyncTimersRef.current[panelId])
-                }
-                lastRawPanelMeasurementsRef.current[panelId] = measurement
-                panelSyncTimersRef.current[panelId] = setTimeout(() => {
-                    const finalMeasurement = lastRawPanelMeasurementsRef.current[panelId]
-                    if (finalMeasurement) {
-                        setPanelMeasurements((prev) => ({
-                            ...prev,
-                            [panelId]: finalMeasurement,
-                        }))
-                    }
-                    delete panelSyncTimersRef.current[panelId]
-                }, 200)
-
+            if (current && current.pixelSize === measurement.pixelSize && current.percentageSize === measurement.percentageSize) {
                 return previous
             }
-
-            // 大きな変化があった場合は待機中のタイマーを解除
-            if (panelSyncTimersRef.current[panelId]) {
-                clearTimeout(panelSyncTimersRef.current[panelId])
-                delete panelSyncTimersRef.current[panelId]
-            }
-
-            return {
-                ...previous,
-                [panelId]: measurement,
-            }
+            return { ...previous, [panelId]: measurement }
         })
     }, [])
 
-    /**
-     * Synchronize resize-handle measurements while ignoring negligible differences.
-     * リサイズハンドル測定値の同期と僅少差分の無視。
-     */
     const reportHandleMeasurement = useCallback((handleId: string, measurement: ResizeHandleLayoutData | null) => {
         setHandleMeasurements((previous) => {
             if (measurement === null) {
-                // 測定結果が null の場合はエントリを削除
                 if (!(handleId in previous)) {
                     return previous
                 }
@@ -854,24 +267,11 @@ export const useResizablePanels = ({ direction, style, onLayout, autoSaveId, sho
                 delete next[handleId]
                 return next
             }
-
             const current = previous[handleId]
-            // 測定値が前回と実質的に同一であればスキップ
-            if (
-                current &&
-                Math.abs(current.thickness - measurement.thickness) <= 0.25 &&
-                current.visible === measurement.visible &&
-                current.direction === measurement.direction &&
-                current.startPanelId === measurement.startPanelId &&
-                current.endPanelId === measurement.endPanelId
-            ) {
+            if (current && current.thickness === measurement.thickness && current.visible === measurement.visible && current.direction === measurement.direction && current.startPanelId === measurement.startPanelId && current.endPanelId === measurement.endPanelId) {
                 return previous
             }
-
-            return {
-                ...previous,
-                [handleId]: measurement,
-            }
+            return { ...previous, [handleId]: measurement }
         })
     }, [])
 
@@ -879,8 +279,8 @@ export const useResizablePanels = ({ direction, style, onLayout, autoSaveId, sho
         () => ({
             direction,
             panels,
-            containerSize,
-            isContainerReady,
+            containerSize: layout.containerSize,
+            layoutOrderKey,
             showDebugInfo,
             registerPanel,
             unregisterPanel,
@@ -892,37 +292,45 @@ export const useResizablePanels = ({ direction, style, onLayout, autoSaveId, sho
             panelMeasurements,
             reportHandleMeasurement,
             handleMeasurements,
-            layoutConstraintViolation,
+            layoutConstraintViolation: layout.violation,
         }),
-        [direction, panels, containerSize, isContainerReady, showDebugInfo, registerPanel, unregisterPanel, resizePanels, collapsePanel, expandPanel, getPanel, reportPanelMeasurement, panelMeasurements, reportHandleMeasurement, handleMeasurements, layoutConstraintViolation],
+        [direction, panels, layout.containerSize, layoutOrderKey, layout.violation, showDebugInfo, registerPanel, unregisterPanel, resizePanels, collapsePanel, expandPanel, getPanel, reportPanelMeasurement, panelMeasurements, reportHandleMeasurement, handleMeasurements],
     )
 
     const groupStyle: CSSProperties = useMemo(
         () => ({
-            display: "flex",
-            flexDirection: direction === "horizontal" ? "row" : "column",
-            alignItems: "stretch",
+            // 見た目に関わる既定値は利用者が上書きできる
             width: "100%",
             height: "100%",
             minWidth: "0px",
             minHeight: "0px",
-            position: "relative",
-            overflow: "hidden", // リサイズハンドルのはみ出しでスクロールバーを表示させない
+            // ハンドルは境界をまたいで描かれるため、その張り出しでスクロールバーを出さない
+            overflow: "hidden",
             ...style,
+            // ここから下はレイアウトの前提そのもの。利用者のスタイルやクラスで変わると
+            // 配分結果と描画が一致しなくなるため、最後に適用して上書きを受け付けない:
+            // gap はパネルの合計に含まれない隙間を作り、flex-direction の反転は DOM 順と視覚順をずらし、
+            // writing-mode は主軸の向きそのものを変えてしまう
+            display: "flex",
+            flexDirection: direction === "horizontal" ? "row" : "column",
+            alignItems: "stretch",
+            gap: "0px",
+            position: "relative",
+            boxSizing: "border-box",
+            writingMode: "horizontal-tb",
         }),
         [direction, style],
     )
 
-    return {
-        groupRef,
-        contextValue,
-        groupStyle,
-    }
+    return { groupRef, contextValue, groupStyle }
 }
 
 /**
- * Provide imperative helpers for toggling a specific panel while preserving stored sizing.
- * 特定パネルの保存済みサイズを維持しつつ開閉を制御する命令型ユーティリティを提供するカスタムフック。
+ * Provide imperative helpers for toggling a specific panel while preserving its stored preference.
+ * 特定パネルの希望値を保ったまま開閉を制御する命令型ユーティリティを提供するカスタムフック。
+ *
+ * @param panelId - Identifier of the panel to control / 操作対象パネルの識別子
+ * @returns Panel state and collapse/expand/toggle helpers / パネル状態と開閉ヘルパー
  */
 export const usePanelControls = (panelId: string) => {
     const { getPanel, collapsePanel, expandPanel } = usePanelGroup()