@aiquants/virtualscroll 1.18.5 → 1.19.0

package/src/TapScrollCircle.spec.tsx

@@ -0,0 +1,275 @@
+/**
+ * Provides regression tests for TapScrollCircle pointer-capture robustness.
+ *
+ * TapScrollCircle のポインタキャプチャ堅牢化に関する回帰テストを提供。
+ */
+import { act, cleanup, fireEvent, render } from "@testing-library/react"
+import { createRef } from "react"
+import { afterEach, beforeAll, describe, expect, it, vi } from "vitest"
+import { TapScrollCircle, type TapScrollCircleDragState, type TapScrollCircleHandle } from "./TapScrollCircle.tsx"
+
+// jsdom は PointerEvent とポインタキャプチャ API を持たないため補完する。
+// jsdom lacks PointerEvent and pointer-capture APIs; polyfill them for these tests.
+beforeAll(() => {
+    if (typeof window.PointerEvent === "undefined") {
+        class PointerEventPolyfill extends MouseEvent {
+            pointerId: number
+            pointerType: string
+            constructor(type: string, params: PointerEventInit = {}) {
+                super(type, params)
+                this.pointerId = params.pointerId ?? 0
+                this.pointerType = params.pointerType ?? "mouse"
+            }
+        }
+        // @ts-expect-error jsdom への PointerEvent 補完
+        window.PointerEvent = PointerEventPolyfill
+    }
+    HTMLElement.prototype.setPointerCapture ??= function setPointerCapture() {}
+    HTMLElement.prototype.releasePointerCapture ??= function releasePointerCapture() {}
+    HTMLElement.prototype.hasPointerCapture ??= function hasPointerCapture() {
+        return false
+    }
+})
+
+afterEach(() => {
+    cleanup()
+})
+
+/**
+ * Builds a PointerEvent-like init for jsdom fireEvent.pointer*.
+ *
+ * jsdom の fireEvent.pointer* 用に PointerEvent 相当の初期化を生成。
+ */
+const pointerInit = (pointerId: number, clientX: number, clientY: number) => ({
+    pointerId,
+    clientX,
+    clientY,
+    // jsdom は PointerEvent を持たないため bubbles/pointerType を明示する
+    bubbles: true,
+    pointerType: "touch",
+})
+
+describe("TapScrollCircle pointer capture robustness", () => {
+    it("does not throw when setPointerCapture fails (pointer already inactive)", () => {
+        const onDragChange = vi.fn()
+        const { getByTestId } = render(<TapScrollCircle onDragChange={onDragChange} opacity={1} />)
+        const circle = getByTestId("virtual-scroll-tap-circle") as HTMLDivElement
+
+        // ウインドウ外へ出た直後などをシミュレート: setPointerCapture が NotFoundError を投げる
+        circle.setPointerCapture = () => {
+            throw new DOMException("pointer not found", "NotFoundError")
+        }
+
+        expect(() => {
+            fireEvent.pointerDown(circle, pointerInit(1, 0, 100))
+        }).not.toThrow()
+
+        // キャプチャ失敗後もドラッグ状態は開始している
+        const last = onDragChange.mock.calls.at(-1)?.[0] as TapScrollCircleDragState
+        expect(last.active).toBe(true)
+    })
+
+    it("resets drag state and notifies inactive on lostpointercapture", () => {
+        const onDragChange = vi.fn()
+        const { getByTestId } = render(<TapScrollCircle onDragChange={onDragChange} opacity={1} />)
+        const circle = getByTestId("virtual-scroll-tap-circle") as HTMLDivElement
+        circle.setPointerCapture = vi.fn()
+
+        fireEvent.pointerDown(circle, pointerInit(1, 0, 100))
+        // 下方向へドラッグして direction を確定させる
+        fireEvent.pointerMove(circle, pointerInit(1, 0, 140))
+        const dragging = onDragChange.mock.calls.at(-1)?.[0] as TapScrollCircleDragState
+        expect(dragging.active).toBe(true)
+        expect(dragging.direction).not.toBe(0)
+
+        // 強制的なキャプチャ解放 (pointerup を受け取れないケース)
+        fireEvent.lostPointerCapture(circle, { pointerId: 1, bubbles: true })
+
+        const afterLost = onDragChange.mock.calls.at(-1)?.[0] as TapScrollCircleDragState
+        expect(afterLost.active).toBe(false)
+        expect(afterLost.direction).toBe(0)
+        expect(afterLost.pointerId).toBeNull()
+    })
+
+    it("ignores lostpointercapture for a non-matching pointerId", () => {
+        const onDragChange = vi.fn()
+        const { getByTestId } = render(<TapScrollCircle onDragChange={onDragChange} opacity={1} />)
+        const circle = getByTestId("virtual-scroll-tap-circle") as HTMLDivElement
+        circle.setPointerCapture = vi.fn()
+
+        fireEvent.pointerDown(circle, pointerInit(1, 0, 100))
+        fireEvent.pointerMove(circle, pointerInit(1, 0, 140))
+        const callsBefore = onDragChange.mock.calls.length
+
+        // 別ポインターの lostpointercapture では状態を触らない
+        fireEvent.lostPointerCapture(circle, { pointerId: 99, bubbles: true })
+        expect(onDragChange.mock.calls.length).toBe(callsBefore)
+        const last = onDragChange.mock.calls.at(-1)?.[0] as TapScrollCircleDragState
+        expect(last.active).toBe(true)
+    })
+
+    it("ignores a second pointer while dragging with the first", () => {
+        const onDragChange = vi.fn()
+        const { getByTestId } = render(<TapScrollCircle onDragChange={onDragChange} opacity={1} />)
+        const circle = getByTestId("virtual-scroll-tap-circle") as HTMLDivElement
+        const capture = vi.fn()
+        circle.setPointerCapture = capture
+
+        fireEvent.pointerDown(circle, pointerInit(1, 0, 100))
+        expect(capture).toHaveBeenCalledTimes(1)
+
+        // 2 本目のタッチ (別 pointerId) は無視されるべき
+        fireEvent.pointerDown(circle, pointerInit(2, 0, 100))
+        expect(capture).toHaveBeenCalledTimes(1)
+
+        // ドラッグ中の pointerId は 1 のまま
+        const last = onDragChange.mock.calls.at(-1)?.[0] as TapScrollCircleDragState
+        expect(last.pointerId).toBe(1)
+
+        // 2 本目のポインターの move は無視される
+        const callsBeforeMove = onDragChange.mock.calls.length
+        fireEvent.pointerMove(circle, pointerInit(2, 0, 200))
+        expect(onDragChange.mock.calls.length).toBe(callsBeforeMove)
+    })
+
+    it("hands off control to a waiting second pointer when the primary is released", () => {
+        const onDragChange = vi.fn()
+        const { getByTestId } = render(<TapScrollCircle onDragChange={onDragChange} opacity={1} />)
+        const circle = getByTestId("virtual-scroll-tap-circle") as HTMLDivElement
+        const capture = vi.fn()
+        circle.setPointerCapture = capture
+
+        // finger1 でドラッグ開始
+        fireEvent.pointerDown(circle, pointerInit(1, 0, 100))
+        fireEvent.pointerMove(circle, pointerInit(1, 0, 140))
+        expect((onDragChange.mock.calls.at(-1)?.[0] as TapScrollCircleDragState).active).toBe(true)
+
+        // finger2 をサークルに置く (待機候補として記録される)
+        fireEvent.pointerDown(circle, pointerInit(2, 0, 60))
+
+        // finger1 を離すと finger2 へ制御が移譲される
+        fireEvent.pointerUp(circle, pointerInit(1, 0, 140))
+        const afterHandoff = onDragChange.mock.calls.at(-1)?.[0] as TapScrollCircleDragState
+        expect(afterHandoff.active).toBe(true)
+        expect(afterHandoff.pointerId).toBe(2)
+        expect(capture).toHaveBeenCalledWith(2)
+
+        // 移譲後は finger2 の move でドラッグが継続する
+        fireEvent.pointerMove(circle, pointerInit(2, 0, 200))
+        const moved = onDragChange.mock.calls.at(-1)?.[0] as TapScrollCircleDragState
+        expect(moved.active).toBe(true)
+        expect(moved.pointerId).toBe(2)
+        expect(moved.offsetY).toBe(200)
+
+        // finger2 を離すと通常どおりリセットされる
+        fireEvent.pointerUp(circle, pointerInit(2, 0, 200))
+        const released = onDragChange.mock.calls.at(-1)?.[0] as TapScrollCircleDragState
+        expect(released.active).toBe(false)
+        expect(released.pointerId).toBeNull()
+    })
+
+    it("tracks the waiting pointer position so the handoff starts at its latest location", () => {
+        const onDragChange = vi.fn()
+        const { getByTestId } = render(<TapScrollCircle onDragChange={onDragChange} opacity={1} />)
+        const circle = getByTestId("virtual-scroll-tap-circle") as HTMLDivElement
+        circle.setPointerCapture = vi.fn()
+
+        fireEvent.pointerDown(circle, pointerInit(1, 0, 100))
+        fireEvent.pointerDown(circle, pointerInit(2, 0, 60))
+        // 待機中の finger2 が移動しても座標は追従する (onDragChange は発火しない)
+        const callsBefore = onDragChange.mock.calls.length
+        fireEvent.pointerMove(circle, pointerInit(2, 0, 160))
+        expect(onDragChange.mock.calls.length).toBe(callsBefore)
+
+        fireEvent.pointerUp(circle, pointerInit(1, 0, 100))
+        const afterHandoff = onDragChange.mock.calls.at(-1)?.[0] as TapScrollCircleDragState
+        expect(afterHandoff.active).toBe(true)
+        expect(afterHandoff.pointerId).toBe(2)
+        expect(afterHandoff.offsetY).toBe(160)
+    })
+
+    it("resets normally when the waiting pointer was already released before the primary", () => {
+        const onDragChange = vi.fn()
+        const { getByTestId } = render(<TapScrollCircle onDragChange={onDragChange} opacity={1} />)
+        const circle = getByTestId("virtual-scroll-tap-circle") as HTMLDivElement
+        circle.setPointerCapture = vi.fn()
+
+        fireEvent.pointerDown(circle, pointerInit(1, 0, 100))
+        fireEvent.pointerDown(circle, pointerInit(2, 0, 60))
+        // finger2 が先に離れた場合、候補は破棄され通常のリセットになる
+        fireEvent.pointerUp(circle, pointerInit(2, 0, 60))
+        fireEvent.pointerUp(circle, pointerInit(1, 0, 100))
+        const last = onDragChange.mock.calls.at(-1)?.[0] as TapScrollCircleDragState
+        expect(last.active).toBe(false)
+        expect(last.pointerId).toBeNull()
+    })
+
+    it("treats a cross-realm NotFoundError (name-based) as a dead candidate on handoff", () => {
+        const onDragChange = vi.fn()
+        const { getByTestId } = render(<TapScrollCircle onDragChange={onDragChange} opacity={1} />)
+        const circle = getByTestId("virtual-scroll-tap-circle") as HTMLDivElement
+
+        // クロスレルムの DOMException を模倣: instanceof DOMException は false だが name は NotFoundError
+        class CrossRealmDOMException extends Error {}
+        const crossRealmError = new CrossRealmDOMException("pointer not found")
+        crossRealmError.name = "NotFoundError"
+        expect(crossRealmError instanceof DOMException).toBe(false)
+
+        // 候補ポインタ (2) の生存プローブだけが失敗する
+        circle.setPointerCapture = (pointerId: number) => {
+            if (pointerId === 2) {
+                throw crossRealmError
+            }
+        }
+
+        fireEvent.pointerDown(circle, pointerInit(1, 0, 100))
+        fireEvent.pointerMove(circle, pointerInit(1, 0, 140))
+        // finger2 を待機候補として置くが、既に非アクティブ (プローブが NotFoundError)
+        fireEvent.pointerDown(circle, pointerInit(2, 0, 60))
+        fireEvent.pointerUp(circle, pointerInit(1, 0, 140))
+
+        // 死んだ候補へは移譲されず、状態はリセットされる (active=true 固着の防止)
+        const last = onDragChange.mock.calls.at(-1)?.[0] as TapScrollCircleDragState
+        expect(last.active).toBe(false)
+        expect(last.pointerId).toBeNull()
+    })
+
+    it("continues the handoff when the liveness probe fails with a non-NotFoundError error", () => {
+        const onDragChange = vi.fn()
+        const { getByTestId } = render(<TapScrollCircle onDragChange={onDragChange} opacity={1} />)
+        const circle = getByTestId("virtual-scroll-tap-circle") as HTMLDivElement
+
+        // NotFoundError 以外 (キャプチャ未サポート等) は生死不明のため移譲を継続する
+        circle.setPointerCapture = (pointerId: number) => {
+            if (pointerId === 2) {
+                throw new Error("capture not supported")
+            }
+        }
+
+        fireEvent.pointerDown(circle, pointerInit(1, 0, 100))
+        fireEvent.pointerDown(circle, pointerInit(2, 0, 60))
+        fireEvent.pointerUp(circle, pointerInit(1, 0, 100))
+
+        const last = onDragChange.mock.calls.at(-1)?.[0] as TapScrollCircleDragState
+        expect(last.active).toBe(true)
+        expect(last.pointerId).toBe(2)
+    })
+
+    it("reset() clears state via imperative handle", () => {
+        const onDragChange = vi.fn()
+        const ref = createRef<TapScrollCircleHandle>()
+        const { getByTestId } = render(<TapScrollCircle ref={ref} onDragChange={onDragChange} opacity={1} />)
+        const circle = getByTestId("virtual-scroll-tap-circle") as HTMLDivElement
+        circle.setPointerCapture = vi.fn()
+
+        fireEvent.pointerDown(circle, pointerInit(1, 0, 100))
+        fireEvent.pointerMove(circle, pointerInit(1, 0, 140))
+
+        act(() => {
+            ref.current?.reset()
+        })
+        const last = onDragChange.mock.calls.at(-1)?.[0] as TapScrollCircleDragState
+        expect(last.active).toBe(false)
+        expect(last.pointerId).toBeNull()
+    })
+})

package/src/TapScrollCircle.tsx

@@ -0,0 +1,363 @@
+/**
+ * Provides a touch-friendly tap circle for continuous scrolling interactions.
+ * タッチ操作向けのタップサークルを提供し、連続スクロール操作を実現するモジュール。
+ */
+
+import type { CSSProperties, ReactNode, PointerEvent as ReactPointerEvent } from "react"
+import { forwardRef, memo, useCallback, useImperativeHandle, useRef, useState } from "react"
+import { twMerge } from "tailwind-merge"
+
+export type TapScrollCircleDragState = {
+    /** Whether the pointer is actively dragging. / ポインターがドラッグ中かどうか。 */
+    active: boolean
+    /** Signed horizontal offset from the circle center. / サークル中心からの符号付き水平方向オフセット。 */
+    offsetX: number
+    /** Signed vertical offset from the circle center. / サークル中心からの符号付き垂直オフセット。 */
+    offsetY: number
+    /** Absolute distance between pointer and center. / ポインターと中心の距離。 */
+    distance: number
+    /** Drag direction relative to the circle. / サークルに対するドラッグ方向。 */
+    direction: -1 | 0 | 1
+    /** The ID of the pointer that initiated the drag. / ドラッグを開始したポインターの ID。 */
+    pointerId: number | null
+}
+
+export type TapScrollCircleProps = {
+    /** Called whenever the drag state updates. / ドラッグ状態が更新された際に呼び出されるコールバック。 */
+    onDragChange: (state: TapScrollCircleDragState) => void
+    /** Additional class names for styling. / 追加のスタイル用クラス名。 */
+    className?: string
+    /** Maximum distance used for visual stretching. / 視覚的な伸縮に使用する最大距離。 */
+    maxVisualDistance?: number
+    /** Diameter of the circle in pixels. / サークルの直径 (ピクセル)。 */
+    size?: number
+    /** Additional inline styles. / 追加のインラインスタイル。 */
+    style?: CSSProperties
+    /** Base opacity applied to the circle. / サークル全体に適用する基準透明度。 */
+    opacity: number
+    /** Custom rendering logic for the visual contents. / ビジュアル内容を描画するカスタムロジック。 */
+    renderVisual?: (props: TapScrollCircleRenderProps) => ReactNode
+}
+
+export type TapScrollCircleHandle = {
+    /**
+     * Resets the drag state and releases pointer capture if active.
+     *
+     * ドラッグ状態をリセットし、必要に応じてポインタキャプチャを解除する。
+     */
+    reset: () => void
+    /**
+     * Returns the underlying DOM element of the tap circle.
+     *
+     * タップサークルの DOM 要素を返す。
+     */
+    getElement: () => HTMLDivElement | null
+}
+
+const INITIAL_STATE: TapScrollCircleDragState = {
+    active: false,
+    offsetX: 0,
+    offsetY: 0,
+    distance: 0,
+    direction: 0,
+    pointerId: null,
+}
+
+const DEAD_ZONE = 6
+const DIRECTION_HYSTERESIS = 8
+
+export type TapScrollCircleRenderProps = {
+    /** Current drag state snapshot. / 現在のドラッグ状態のスナップショット。 */
+    dragState: TapScrollCircleDragState
+    /** Normalized distance within [0, 1]. / 正規化距離 (0 から 1 の範囲)。 */
+    normalizedDistance: number
+    /** Relative scale based on size. / サイズに基づく相対スケール。 */
+    sizeScale: number
+    /** Circle diameter in pixels. / サークル直径 (ピクセル)。 */
+    size: number
+    /** Applied opacity value. / 適用中の不透明度値。 */
+    opacity: number
+}
+
+const defaultRenderVisual = ({ dragState, normalizedDistance }: TapScrollCircleRenderProps) => {
+    const scale = 1 + normalizedDistance * 0.18
+    const glow = 0.16 + normalizedDistance * 0.24
+    const innerOpacity = 0.38 + normalizedDistance * 0.28
+    const baseTransition = dragState.active ? "80ms ease-out" : "220ms ease"
+
+    return (
+        <>
+            <div
+                className="aqvs-tap-scroll-circle-visual-outer"
+                style={{
+                    background: "linear-gradient(140deg, rgba(255,255,255,0.62), rgba(72,72,72,0.48))",
+                    boxShadow: `0 0 0 1px rgba(255,255,255,0.28), 0 10px 22px rgba(0,0,0,${glow})`,
+                    transform: `scale(${scale})`,
+                    transition: `${baseTransition}, ${dragState.active ? "80ms" : "260ms"} box-shadow ease`,
+                }}
+            />
+            <div
+                className="aqvs-tap-scroll-circle-inner"
+                style={{
+                    background: "linear-gradient(140deg, rgba(255,255,255,0.72), rgba(28,28,28,0.58))",
+                    boxShadow: "inset 0 4px 10px rgba(0,0,0,0.24), inset 0 0 2px rgba(255,255,255,0.55)",
+                    opacity: innerOpacity,
+                    transition: dragState.active ? "120ms opacity ease-out" : "220ms opacity ease",
+                }}
+            />
+        </>
+    )
+}
+
+/**
+ * A circular touch handle that stretches toward the drag direction.
+ * タップした方向へ伸縮するタッチ操作用サークル。
+ */
+export const TapScrollCircle = memo(
+    forwardRef<TapScrollCircleHandle, TapScrollCircleProps>(({ onDragChange, className, maxVisualDistance = 160, size = 40, style, opacity = 1, renderVisual }, ref) => {
+        const [dragState, setDragState] = useState<TapScrollCircleDragState>(INITIAL_STATE)
+        const pointerIdRef = useRef<number | null>(null)
+        // アクティブなドラッグ中に押下された別ポインタ (2 本目のタッチ) を「待機候補」として保持する。
+        // プライマリの解放時にこの候補へ制御を移譲し、指のハンドオフ (指の持ち替え) を可能にする。
+        // Holds a second pointer pressed during an active drag as a pending candidate; control is
+        // handed off to it when the primary pointer is released, enabling finger handoff.
+        const pendingPointerRef = useRef<{ pointerId: number; clientX: number; clientY: number } | null>(null)
+        const centerRef = useRef<{ x: number; y: number }>({ x: 0, y: 0 })
+        const rootRef = useRef<HTMLDivElement>(null)
+        const lastStableDirectionRef = useRef<-1 | 0 | 1>(0)
+
+        /**
+         * Updates drag state and notifies listeners.
+         *
+         * ドラッグ状態を更新してリスナーに通知。
+         */
+        const applyDragState = useCallback(
+            (nextState: TapScrollCircleDragState) => {
+                setDragState(nextState)
+                onDragChange(nextState)
+            },
+            [onDragChange],
+        )
+
+        const updateDragState = useCallback(
+            (clientX: number, clientY: number, capture: boolean = false) => {
+                const { x, y } = centerRef.current
+                const offsetX = clientX - x
+                const offsetY = clientY - y
+                const distance = Math.abs(offsetY)
+                const rawDirection: -1 | 0 | 1 = distance < DEAD_ZONE ? 0 : offsetY < 0 ? -1 : 1
+                const previousDirection = lastStableDirectionRef.current
+                let direction: -1 | 0 | 1 = rawDirection
+
+                const hysteresisThreshold = DEAD_ZONE + DIRECTION_HYSTERESIS
+
+                if (rawDirection === 0) {
+                    if (previousDirection !== 0 && distance < hysteresisThreshold) {
+                        direction = previousDirection
+                    } else {
+                        direction = 0
+                        if (!capture) {
+                            lastStableDirectionRef.current = 0
+                        }
+                    }
+                } else if (rawDirection !== previousDirection && previousDirection !== 0 && distance < hysteresisThreshold) {
+                    direction = previousDirection
+                } else {
+                    lastStableDirectionRef.current = rawDirection
+                }
+
+                // 僅かなドラッグ揺れによる方向反転を防ぐヒステリシスを適用
+                applyDragState({
+                    active: capture || distance >= DEAD_ZONE,
+                    offsetX,
+                    offsetY,
+                    distance,
+                    direction,
+                    pointerId: pointerIdRef.current,
+                })
+            },
+            [applyDragState],
+        )
+
+        const releasePointerCapture = useCallback((pointerId: number | null) => {
+            if (pointerId === null) {
+                return
+            }
+            const element = rootRef.current
+            if (element?.hasPointerCapture(pointerId)) {
+                element.releasePointerCapture(pointerId)
+            }
+        }, [])
+
+        const resetState = useCallback(
+            (releasePointer: boolean = false) => {
+                if (releasePointer) {
+                    releasePointerCapture(pointerIdRef.current)
+                }
+                pointerIdRef.current = null
+                pendingPointerRef.current = null
+                lastStableDirectionRef.current = 0
+                applyDragState(INITIAL_STATE)
+            },
+            [applyDragState, releasePointerCapture],
+        )
+
+        const handlePointerDown = useCallback(
+            (event: ReactPointerEvent<HTMLDivElement>) => {
+                // ドラッグ中に発生した別ポインター (2 本目のタッチ) は待機候補として記録し、
+                // プライマリの解放時に制御を移譲できるようにする (指のハンドオフ)。
+                // Record a second pointer pressed mid-drag as a pending candidate so control can be
+                // handed off to it when the primary pointer is released (finger handoff).
+                if (pointerIdRef.current !== null && pointerIdRef.current !== event.pointerId) {
+                    pendingPointerRef.current = { pointerId: event.pointerId, clientX: event.clientX, clientY: event.clientY }
+                    event.preventDefault()
+                    event.stopPropagation()
+                    return
+                }
+                event.preventDefault()
+                event.stopPropagation()
+                const element = rootRef.current ?? event.currentTarget
+                const { left, top, width, height } = element.getBoundingClientRect()
+                centerRef.current = { x: left + width / 2, y: top + height / 2 }
+                pointerIdRef.current = event.pointerId
+                try {
+                    element.setPointerCapture(event.pointerId)
+                } catch {
+                    // ポインタが既に非アクティブ (ウインドウ外へ出た等) だと setPointerCapture は
+                    // NotFoundError を投げ得る。キャプチャ無しでもドラッグ処理は継続できるため握り潰す。
+                    // setPointerCapture can throw NotFoundError if the pointer is already inactive
+                    // (e.g. moved outside the browser window); dragging still works without capture.
+                }
+                updateDragState(event.clientX, event.clientY, true)
+            },
+            [updateDragState],
+        )
+
+        const handlePointerMove = useCallback(
+            (event: ReactPointerEvent<HTMLDivElement>) => {
+                if (pointerIdRef.current !== event.pointerId) {
+                    // 待機候補ポインタの移動は座標のみ追従させ、ハンドオフ時の開始位置に使う
+                    if (pendingPointerRef.current !== null && pendingPointerRef.current.pointerId === event.pointerId) {
+                        pendingPointerRef.current = { pointerId: event.pointerId, clientX: event.clientX, clientY: event.clientY }
+                    }
+                    return
+                }
+                event.preventDefault()
+                updateDragState(event.clientX, event.clientY)
+            },
+            [updateDragState],
+        )
+
+        const handlePointerUp = useCallback(
+            (event: ReactPointerEvent<HTMLDivElement>) => {
+                if (pointerIdRef.current !== event.pointerId) {
+                    // 待機候補ポインタが先に離れた/キャンセルされた場合は候補を破棄する
+                    if (pendingPointerRef.current !== null && pendingPointerRef.current.pointerId === event.pointerId) {
+                        pendingPointerRef.current = null
+                    }
+                    return
+                }
+                event.preventDefault()
+                event.stopPropagation()
+                const pending = pendingPointerRef.current
+                pendingPointerRef.current = null
+                if (pending !== null) {
+                    // プライマリの解放時、待機中の 2 本目のポインタへ制御を移譲する (指のハンドオフ)。
+                    // 候補がサークル外で既に離されていると要素は pointerup を受け取れず候補が残留するため、
+                    // setPointerCapture を生存プローブとして使う: 非アクティブなポインタには仕様上
+                    // NotFoundError が投げられるので、失敗時は移譲せずリセットに倒す (active=true 固着の防止)。
+                    // Use setPointerCapture as a liveness probe: it throws NotFoundError for inactive
+                    // pointers, so a dead candidate resets the state instead of getting promoted.
+                    releasePointerCapture(event.pointerId)
+                    const element = rootRef.current
+                    let candidateAlive = true
+                    if (element !== null && typeof element.setPointerCapture === "function") {
+                        try {
+                            element.setPointerCapture(pending.pointerId)
+                        } catch (error) {
+                            // NotFoundError = 候補ポインタが既に非アクティブ (サークル外で解放済み等)。
+                            // クロスレルム (iframe への portal 等) では DOMException の instanceof が
+                            // false になるため、name ベースで判定する (DOMException も name を持つので包含)。
+                            // それ以外 (キャプチャ未実装環境等) は生死不明のため移譲を継続する。
+                            const errorName = typeof error === "object" && error !== null && "name" in error ? (error as { name?: unknown }).name : undefined
+                            if (errorName === "NotFoundError") {
+                                candidateAlive = false
+                            }
+                        }
+                    }
+                    if (candidateAlive) {
+                        pointerIdRef.current = pending.pointerId
+                        updateDragState(pending.clientX, pending.clientY, true)
+                        return
+                    }
+                }
+                resetState(true)
+            },
+            [resetState, releasePointerCapture, updateDragState],
+        )
+
+        const handleLostPointerCapture = useCallback(
+            (event: ReactPointerEvent<HTMLDivElement>) => {
+                if (pointerIdRef.current !== event.pointerId) {
+                    return
+                }
+                // OS/ブラウザ都合でキャプチャが強制解放されると pointerup/pointercancel を受け取れず、
+                // ドラッグ状態が固着して連続スクロールが止まらなくなる。ここで状態をリセットする。
+                // A forced capture release (by the OS/browser) means pointerup/pointercancel may never
+                // arrive; reset the drag state here so continuous scrolling does not get stuck.
+                // キャプチャは既に解放済みなので、再解放は試みない (releasePointer=false)。
+                resetState(false)
+            },
+            [resetState],
+        )
+
+        useImperativeHandle(
+            ref,
+            () => ({
+                reset: () => {
+                    resetState(true)
+                },
+                getElement: () => rootRef.current,
+            }),
+            [resetState],
+        )
+
+        const clampedOpacity = Math.min(Math.max(opacity, 0), 1)
+        const sizeScale = size / 64
+        const normalized = Math.min(dragState.distance, maxVisualDistance) / maxVisualDistance
+        const pullOffset = dragState.direction * normalized * 10 * sizeScale
+        const visualRenderer = renderVisual ?? defaultRenderVisual
+        const visualProps: TapScrollCircleRenderProps = {
+            dragState,
+            normalizedDistance: normalized,
+            sizeScale,
+            size,
+            opacity: clampedOpacity,
+        }
+        const rootStyle: CSSProperties = {
+            ...style,
+            width: size,
+            height: size,
+            transform: `translateY(${pullOffset}px)`,
+        }
+        rootStyle.opacity = clampedOpacity
+        return (
+            <div
+                ref={rootRef}
+                data-testid="virtual-scroll-tap-circle"
+                className={twMerge("aqvs-tap-scroll-circle", className)}
+                style={rootStyle}
+                tabIndex={-1}
+                onPointerDown={handlePointerDown}
+                onPointerMove={handlePointerMove}
+                onPointerUp={handlePointerUp}
+                onPointerCancel={handlePointerUp}
+                onLostPointerCapture={handleLostPointerCapture}
+                role="presentation">
+                {visualRenderer(visualProps)}
+            </div>
+        )
+    }),
+)
+
+TapScrollCircle.displayName = "TapScrollCircle"