@aiquants/virtualscroll 3.5.0 → 3.6.0

package/src/VirtualGrid.tsx

@@ -7,21 +7,29 @@
  * row-axis scale profile (<= 2^53 - 1). Grid semantics (selection / editing / clipboard)
  * are deliberately NOT owned here — consumers attach them via getCellProps / getRowProps /
  * contentProps. Design: docs/plans/2026.09.01 virtualgrid-horizontal-axis-design-plan (v6).
+ * Since v3.6.0 the grid owns ONE unified two-axis tap circle (axis="xy", corner-anchored via the
+ * three-arm placement law) driven by useGridTapScroll; both per-bar circles are suppressed
+ * grid-side (docs/plans/2026.09.16 unified-tap-circle plan).
  *
  * VirtualGrid — 実証済みの VirtualScroll 行軸に、対称の横列エンジン (同一の兆スケール機構:
  * 疎 Fenwick 幅木・共有 computeRenderingRanges (BigInt huge 分岐込み)・ANCHOR_REBASE_DISTANCE
  * の量子化アンカー再基準化・総サイズ px を DOM に着地させない合成スクロール) を合成した
  * 汎用 2D 仮想化プリミティブ。列数は行軸のスケールプロファイル (≤ 2^53 − 1) を完全継承する。
  * グリッド操作の意味論 (選択 / 編集 / クリップボード) は意図的に非所有 — 消費側が
- * getCellProps / getRowProps / contentProps で装着する。
+ * getCellProps / getRowProps / contentProps で装着する。v3.6.0 からグリッドは統合 2 軸
+ * タップサークル (axis="xy"・3 アーム則のコーナーアンカー・useGridTapScroll 駆動) を 1 つ
+ * 所有し、両バーのサークルはグリッド側で抑止する。
  */
 
 import { type CSSProperties, forwardRef, type HTMLAttributes, type ReactNode, useCallback, useEffect, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState } from "react"
 import { twMerge } from "tailwind-merge"
+import type { TapScrollAxisSpeedParams } from "./computeTapScrollVelocity.ts"
 import { Logger } from "./logger.ts"
-import { ScrollBar } from "./ScrollBar.tsx"
+import { resolveTapScrollCircleOptions, ScrollBar, type ScrollBarTapCircleOptions } from "./ScrollBar.tsx"
 import type { ScrollPaneProps } from "./ScrollPane.tsx"
+import { TapScrollCircle } from "./TapScrollCircle.tsx"
 import { useFenwickMapTree } from "./useFenwickMapTree.ts"
+import { GRID_TAP_CIRCLE_DEFAULT_OFFSET, useGridTapScroll } from "./useGridTapScroll.ts"
 import { minmax } from "./utils.ts"
 import { ANCHOR_REBASE_DISTANCE, computeRenderingRanges, MAX_RENDERED_ITEMS, VirtualScroll, type VirtualScrollBehaviorOptions, type VirtualScrollHandle, type VirtualScrollRange, type VirtualScrollScrollBarOptions, ZERO_HEIGHT_RUN_LIMIT } from "./VirtualScroll.tsx"
 
@@ -997,6 +1005,16 @@ const VirtualGridInner = <T,>(
      */
     const scrollBandWidthRef = useCallback(() => Math.max(0, viewportRef.current.width - frozenWidthRef.current - trailingWidthRef.current), [])
 
+    /**
+     * The ONE extracted x clamp law (v3.6.0 §3.5-7 SSOT): `max(0, totalWidth − W_F − W_T −
+     * bandWidth)`. Consumed by `applyHx` (pure refactor — behavior byte-identical) AND the tap
+     * driver (boundary / pinned detection + `gridScrollable`). No second copy of the law exists.
+     * 唯一抽出の x クランプ則 (v3.6.0 §3.5-7 SSOT)。`applyHx` (純リファクタ — 挙動バイト恒等)
+     * とタップドライバ (境界 / ピン判定 + `gridScrollable`) の両方が消費する。第 2 の複製は
+     * 存在しない。
+     */
+    const getMaxHx = useCallback(() => Math.max(0, totalWidthRef.current - frozenWidthRef.current - trailingWidthRef.current - scrollBandWidthRef()), [scrollBandWidthRef])
+
     // ---- 列窓の再計算 (setState は窓 / アンカー変化時のみ — key 比較で bail) ----
     const refreshColumns = useCallback(() => {
         // 凍結帯 (§8-a): 窓探索は木座標 W_F + hx 始まり・帯幅 = viewport − W_F − W_T (3.5.0 一般化)
@@ -1122,9 +1140,8 @@ const VirtualGridInner = <T,>(
         (next: number): number => {
             // 凍結帯 (§8): スクロール帯幅 = viewport − W_F − W_T (3.5.0 一般化)。maxHx =
             // (総幅 − W_F − W_T) − 帯幅で、W_F + W_T < viewport のとき従来式 (総幅 − viewport)
-            // と一致する (F = T = 0 で恒等)
-            const bandWidth = scrollBandWidthRef()
-            const maxHx = Math.max(0, totalWidthRef.current - frozenWidthRef.current - trailingWidthRef.current - bandWidth)
+            // と一致する (F = T = 0 で恒等)。クランプ則の所有者は getMaxHx (v3.6.0 SSOT)
+            const maxHx = getMaxHx()
             const clamped = minmax(next, 0, maxHx)
             if (clamped !== hxRef.current) {
                 hxRef.current = clamped
@@ -1135,7 +1152,7 @@ const VirtualGridInner = <T,>(
             }
             return clamped
         },
-        [writeResidual, refreshColumns, scheduleBarSync, scrollBandWidthRef],
+        [writeResidual, refreshColumns, scheduleBarSync, getMaxHx],
     )
     const applyHxRef = useRef(applyHx)
     applyHxRef.current = applyHx
@@ -1289,6 +1306,111 @@ const VirtualGridInner = <T,>(
         }
     }, [trailingWidth, effectiveTrailingCols])
 
+    // ---- 統合 2 軸タップサークル (v3.6.0 — ADR-27..32) ----
+    // 埋め込み VirtualScroll へ転送するオプションのメモ化フォーク (§3.1): tapScrollCircleOptions
+    // だけ enabled: false を強制し、兄弟フィールド (width 等) は必ず生存させる。両バーの
+    // サークルはグリッド側だけで抑止し、単体 VirtualScroll / ScrollPane / ScrollBar は触らない
+    const embeddedScrollBarOptions = useMemo<VirtualScrollScrollBarOptions>(() => ({ ...scrollBarOptions, tapScrollCircleOptions: { ...scrollBarOptions?.tapScrollCircleOptions, enabled: false } }), [scrollBarOptions])
+    const rawTapScrollCircleOptions = scrollBarOptions?.tapScrollCircleOptions
+    // hasCustomMaxSpeedMultiplier は**生**オプションからのピン (§8.3 — ScrollBar stepAutoScroll 内の
+    // 導出の双子)。リゾルバ出力からの導出 (typeof resolved.maxSpeedMultiplier === "number") は
+    // 常に true で、1,200 px/s 自動床を minSpeed へ無言反転させる T1 破壊 (MV-XY28)
+    const hasCustomTapMaxSpeedMultiplier = typeof rawTapScrollCircleOptions?.maxSpeedMultiplier === "number"
+    // 生オプションへ両オフセットのグリッド既定 (−200) を注入してから解決する (§8.4-5)。バー既定
+    // −80/0 はバーアンカー則の符号でありコーナーアンカーでは無意味
+    const gridTapOptions = useMemo<ScrollBarTapCircleOptions>(
+        () => ({
+            ...rawTapScrollCircleOptions,
+            offsetX: rawTapScrollCircleOptions?.offsetX === undefined ? GRID_TAP_CIRCLE_DEFAULT_OFFSET : rawTapScrollCircleOptions.offsetX,
+            offsetY: rawTapScrollCircleOptions?.offsetY === undefined ? GRID_TAP_CIRCLE_DEFAULT_OFFSET : rawTapScrollCircleOptions.offsetY,
+        }),
+        [rawTapScrollCircleOptions],
+    )
+    // 軸別解決 (§8.4-5): resolveTapScrollCircleOptions を軸ごとに 1 回 (itemCount = 軸カウント —
+    // 不変量 8 保存)。視覚フィールドはどちらの結果から読んでも同一 (構造上) — x 側から読む
+    const resolvedTapX = useMemo(() => resolveTapScrollCircleOptions(gridTapOptions, Math.max(0, colCount - effectiveFrozenCols - effectiveTrailingCols)), [gridTapOptions, colCount, effectiveFrozenCols, effectiveTrailingCols])
+    const resolvedTapY = useMemo(() => resolveTapScrollCircleOptions(gridTapOptions, scrollRowCount), [gridTapOptions, scrollRowCount])
+    const tapCircleEnabled = resolvedTapX.enabled
+    const tapMaxDistance = Math.max(resolvedTapX.maxVisualDistance, 1)
+    // 軸別速度パラメータ (§4.1): 今日の 2 バー構成そのもの — x はスクロール帯幅 × 列カウント、
+    // y は埋め込みペイン高 × スクロール行カウント。min/max/curve は共有 (1 オプションオブジェクト)
+    const tapXSpeedParams: TapScrollAxisSpeedParams = {
+        viewportSize: Math.max(0, viewport.width - frozenWidth - trailingWidth),
+        minSpeedMultiplier: resolvedTapX.minSpeedMultiplier,
+        maxSpeedMultiplier: resolvedTapX.maxSpeedMultiplier,
+        hasCustomMaxSpeedMultiplier: hasCustomTapMaxSpeedMultiplier,
+        curve: resolvedTapX.maxSpeedCurve,
+    }
+    const tapYSpeedParams: TapScrollAxisSpeedParams = {
+        viewportSize: Math.max(0, viewport.height - frozenHeight - trailingHeight),
+        minSpeedMultiplier: resolvedTapY.minSpeedMultiplier,
+        maxSpeedMultiplier: resolvedTapY.maxSpeedMultiplier,
+        hasCustomMaxSpeedMultiplier: hasCustomTapMaxSpeedMultiplier,
+        curve: resolvedTapY.maxSpeedCurve,
+    }
+    const getHx = useCallback(() => hxRef.current, [])
+    const getVy = useCallback(() => vyRef.current, [])
+    /**
+     * Fresh y extent through the embedded handle — the same freshness channel the vertical bar
+     * uses (`contentSize − viewportSize` floored at 0). Never re-derived from grid-side trees.
+     * 埋め込みハンドル経由の鮮度 y 延長 — vbar と同じ鮮度チャネル (`contentSize − viewportSize`
+     * の 0 下支え)。グリッド側の木から再導出しない (§3.5-7)。
+     */
+    const getMaxVy = useCallback(() => {
+        const inner = scrollHandleRef.current
+        if (inner === null) {
+            return 0
+        }
+        return Math.max(0, Math.max(0, inner.getContentSize()) - Math.max(0, inner.getViewportSize()))
+    }, [])
+    /**
+     * The y apply seam (§3.5-8): wraps the embedded `scrollBy` AND syncs `vyRef.current =
+     * applied` before returning — the grid handle `scrollBy` y-half twin, symmetric with
+     * `applyHxRef`. Without the sync, x-frame `onScroll({ x, y: vyRef.current })` notifications
+     * during a diagonal drag carry y stale by up to the `callbackThrottleMs` window (MV-XY29).
+     * y 適用シーム (§3.5-8): 埋め込み `scrollBy` をラップし、**返す前に** `vyRef.current =
+     * applied` を同期する — グリッドハンドル `scrollBy` の y 半分の双子で `applyHxRef` と対称。
+     * 同期が無いと対角ドラッグ中の x フレーム通知が stale y を運ぶ (MV-XY29)。
+     */
+    const applyVy = useCallback((delta: number): number => {
+        const inner = scrollHandleRef.current
+        if (inner === null) {
+            // ハンドル未接続時は現在値を返して動かない (グリッドハンドル scrollBy と同じ姿勢)
+            return vyRef.current
+        }
+        const applied = inner.scrollBy(delta)
+        vyRef.current = applied
+        return applied
+    }, [])
+    // gridScrollable (§8.4-6): 動く軸が 1 つあれば十分 — y-only グリッドは x 成分が境界ピンの
+    // まま動くサークルを保持する (MV-XY20/21)。バーを駆動するのと同じ鮮度チャネル (x:
+    // columnWindow / 総幅、y: 縦レンジ state = notifiedRowCount の通知駆動再レンダー) で再計算される
+    const gridScrollable = getMaxHx() > 0 || getMaxVy() > 0
+    // 延長成長の再武装キー (§3.5-3): 保持中の境界パークを鮮度チャネルの成長で再開する
+    const tapXExtentFreshness = `${totalWidth}:${frozenWidth}:${trailingWidth}:${viewport.width}:${columnWindow.key}`
+    const tapYExtentFreshness = `${rowCount}:${notifiedRowCount ?? -1}:${frozenHeight}:${trailingHeight}:${viewport.height}`
+    const { isTapActive, handleTapCircleDragChange, tapCircleHandleRef } = useGridTapScroll({
+        enabled: tapCircleEnabled && gridScrollable,
+        maxDistance: tapMaxDistance,
+        xSpeedParams: tapXSpeedParams,
+        ySpeedParams: tapYSpeedParams,
+        applyHxRef,
+        getHx,
+        getMaxHx,
+        applyVy,
+        getVy,
+        getMaxVy,
+        pendingColAnchorRef,
+        xExtentFreshness: tapXExtentFreshness,
+        yExtentFreshness: tapYExtentFreshness,
+    })
+    // バーの 2 行 opacity memo の複製 (§8.4-5): インライン opacity の着地先はサークルルート
+    // (props 経由) — 値と要素同一性はテストでピン (MV-XY23/27)
+    const tapCircleOpacityValue = useMemo(() => {
+        const baseOpacity = isTapActive ? 1 : 0.8
+        return minmax(baseOpacity * resolvedTapX.opacity, 0, 1)
+    }, [isTapActive, resolvedTapX.opacity])
+
     // ---- ビューポート / 総幅 / 幅エポック変化での再クランプ + 列窓追随。保留列アンカーが
     //      あれば位置はアンカーから再導出 (単なる再クランプでは推定空間の hx が残留する) ----
     useLayoutEffect(() => {
@@ -1739,7 +1861,7 @@ const VirtualGridInner = <T,>(
                     viewportSize={viewport.height > 0 ? Math.max(0, viewport.height - frozenHeight - trailingHeight) : undefined}
                     callbackThrottleMs={callbackThrottleMs}
                     behaviorOptions={behaviorOptions}
-                    scrollBarOptions={scrollBarOptions}
+                    scrollBarOptions={embeddedScrollBarOptions}
                     contentProps={contentProps}
                     background={background}
                     contentInsets={contentInsets}
@@ -1789,7 +1911,6 @@ const VirtualGridInner = <T,>(
             <div className="aqvs-grid-hbar-strip" style={{ height: scrollBarWidth, paddingRight: effectiveTrailingCols > 0 ? scrollBarWidth + trailingVisibleSize(trailingWidth, frozenWidth, viewport.width) : scrollBarWidth }} data-testid={testId ? `${testId}-hbar` : undefined}>
                 <ScrollBar
                     horizontal
-                    enableHorizontalTapCircle
                     contentSize={Math.max(0, totalWidth - frozenWidth - trailingWidth)}
                     viewportSize={Math.max(0, viewport.width - frozenWidth - trailingWidth)}
                     scrollPosition={barHx}
@@ -1806,6 +1927,32 @@ const VirtualGridInner = <T,>(
                     scrollBarWidth={scrollBarWidth}
                 />
             </div>
+            {tapCircleEnabled && gridScrollable && (
+                // 統合 2 軸タップサークル (v3.6.0 — ADR-30 の 3 アーム則): (C) 可視上限
+                // `100% − (sbw + size)` / (R) 到達性 `100% − sbw + off` / (Q) 遠象限床
+                // `75% − size/2`。全アームが root 寸・sbw・size・オフセットのみに依存 —
+                // 帯幅非依存 (凍結トグル不変)。wrapper は純配置で transition を持たない
+                // (フェードはサークルルートのインライン opacity — §8.7)。hbar strip の後・
+                // live region の前 = 共有 z-50 層の DOM 後勝ちで最前
+                <div
+                    className="aqvs-grid-tap-circle-wrapper"
+                    data-aqvs-grid-tap-circle=""
+                    style={{
+                        left: `min(calc(100% - ${scrollBarWidth + resolvedTapX.size}px), max(calc(100% - ${scrollBarWidth}px + ${resolvedTapX.offsetX}px), calc(75% - ${resolvedTapX.size / 2}px)))`,
+                        top: `min(calc(100% - ${scrollBarWidth + resolvedTapX.size}px), max(calc(100% - ${scrollBarWidth}px + ${resolvedTapX.offsetY}px), calc(75% - ${resolvedTapX.size / 2}px)))`,
+                    }}>
+                    <TapScrollCircle
+                        axis="xy"
+                        ref={tapCircleHandleRef}
+                        className={twMerge("aqvs-grid-tap-circle", resolvedTapX.className)}
+                        size={resolvedTapX.size}
+                        maxVisualDistance={tapMaxDistance}
+                        opacity={tapCircleOpacityValue}
+                        renderVisual={resolvedTapX.renderVisual}
+                        onDragChange={handleTapCircleDragChange}
+                    />
+                </div>
+            )}
             {liveRegion !== undefined ? (
                 <div className="aqvs-grid-live-region" aria-live="polite" data-testid={testId ? `${testId}-live` : undefined}>
                     {liveMessage}

package/src/computeTapScrollVelocity.ts

@@ -0,0 +1,150 @@
+/**
+ * Pure two-axis velocity decomposition for the unified grid tap circle (v3.6.0).
+ * 統合 2 軸タップサークル (v3.6.0) 用の純関数 2 軸速度分解モジュール。
+ */
+
+import { computeTapScrollSpeed } from "./ScrollBar.tsx"
+
+/**
+ * Per-axis speed parameters for `computeTapScrollVelocity` — the exact tuple one bar resolves
+ * today. Deliberately an explicit structural type (NOT `Omit<TapScrollSpeedInput, …>`):
+ * api-extractor cannot roll up `Omit<>` on the public surface (house rule).
+ * `computeTapScrollVelocity` の軸別速度パラメータ — 今日 1 本のバーが解決する組そのもの。
+ * 意図的な明示構造型 (`Omit<>` 非使用 — api-extractor がロールアップできないための既定方針)。
+ */
+export type TapScrollAxisSpeedParams = {
+    /** Viewport length on this axis (px). / この軸のビューポート長 (px)。 */
+    viewportSize: number
+    /** Minimum speed multiplier (viewport-relative). / 最小速度倍率 (ビューポート比)。 */
+    minSpeedMultiplier: number
+    /** Maximum speed multiplier (viewport-relative). / 最大速度倍率 (ビューポート比)。 */
+    maxSpeedMultiplier: number
+    /** Whether `maxSpeedMultiplier` was explicitly supplied (controls the 1,200 px/s auto floor). / `maxSpeedMultiplier` が明示指定か (1,200 px/s 自動床の制御)。 */
+    hasCustomMaxSpeedMultiplier: boolean
+    /** Optional speed-curve shape (same contract as `TapScrollSpeedInput.curve`). / 任意の速度曲線形状 (`TapScrollSpeedInput.curve` と同契約)。 */
+    curve?: { exponentialSteepness: number; exponentialScale?: number; easedOffset?: number }
+}
+
+/**
+ * Input for `computeTapScrollVelocity`.
+ * `computeTapScrollVelocity` の入力。
+ */
+export type TapScrollVelocityInput = {
+    /** Signed px from the circle center (state canonical field). / サークル中心からの符号付き px (state 正準フィールド)。 */
+    offsetX: number
+    /** Signed px from the circle center (state canonical field). / サークル中心からの符号付き px (state 正準フィールド)。 */
+    offsetY: number
+    /** Shared pull range (= `max(maxVisualDistance, 1)`). / 共有引き範囲 (= `max(maxVisualDistance, 1)`)。 */
+    maxDistance: number
+    /** Horizontal-axis speed parameters. / 横軸の速度パラメータ。 */
+    x: TapScrollAxisSpeedParams
+    /** Vertical-axis speed parameters. / 縦軸の速度パラメータ。 */
+    y: TapScrollAxisSpeedParams
+}
+
+/**
+ * Decomposes a 2-D tap-circle pull into per-axis scroll velocities (px/s, signed):
+ *
+ * ```text
+ * r = 0  =>  v = (0, 0)
+ * r > 0  =>  v = ( s_x(r) * ox / r ,  s_y(r) * oy / r )
+ * ```
+ *
+ * where `r = ||(ox, oy)||_2` and `s_a` is the UNCHANGED `computeTapScrollSpeed` under axis `a`'s
+ * parameters (`distance: r`, shared `maxDistance`).
+ *
+ * Derivation summary (the axioms this law is the unique solution of):
+ *
+ * - D1 (legacy reproduction): pure-axis inputs reproduce each 1-D bar law to within 1 ulp
+ *   under the pinned order — deviations hit a config-dependent ~9% of probed pure-axis points,
+ *   so never assert bit-equality (`toBe` / `Object.is`) of a pure-axis component against
+ *   `computeTapScrollSpeed` outside the committed exact fixtures. The rejected order
+ *   `s * (o / r)` would be bit-exact on pure axes (`o / r = ±1` exactly); the pin below
+ *   trades that for fixture-order independence (plan §4.2 T1 / §4.3).
+ * - D2 (radial law under isotropy): when `s_x = s_y = s`, `|v| = s(r)` at every angle.
+ * - D3 (separability): `v_a = s_a(r) * u_a(theta)` for a direction-only unit field `u`.
+ * - D4 (isotropic direction fidelity — a CHOSEN axiom, not derived): when `s_x = s_y`,
+ *   `v` is parallel to the offset with a positive scalar (rotational equivariance).
+ *
+ * D1-D3 alone do NOT force this law: they admit the whole family
+ * `u = (cos phi(theta), sin phi(theta))` for any continuous strictly increasing angle remap
+ * `phi` fixing the four cardinal angles (e.g. `phi(theta) = theta - epsilon * sin(4 theta)`).
+ * D4 pins `phi = id`. That family is the registered invariant-preserving tuning point for
+ * near-axis leakage (plan §4.4); v3.6.0 ships `phi = id`.
+ *
+ * Evaluation-order pin: each component is computed literally as `s_a(r) * o_a / r`
+ * (left-to-right, i.e. `(s * o) / r`). The two orders differ by 1 ulp for SOME inputs —
+ * verified witness: `40 * (7 / 25) = 11.200000000000001` while `(40 * 7) / 25 = 11.2` exactly.
+ * The committed spec fixtures happen to agree under BOTH orders (`200 * (30 / 50) === 120`
+ * etc. — the products land inside half-ulp and round back); the pin exists so the fixtures'
+ * `toBe` exactness never depends on that luck of the operand set. Do NOT "test" the old,
+ * numerically false claim that `200 * (30 / 50)` misrounds — it does not; deleting this pin
+ * because that claim fails would discard a sound pin.
+ *
+ * Totality: non-finite `ox` / `oy` are sanitized to 0 and `r = 0` returns `(0, 0)` (the origin
+ * has no continuous extension — the limit depends on the approach angle). Components are always
+ * finite: `s_a` is the existing sole NaN barrier and `|o_a| / r <= 1`.
+ *
+ * External reproduction of what a bar/grid actually resolves (same pattern as the
+ * `computeTapScrollSpeed` docstring):
+ *
+ * ```ts
+ * const velocity = computeTapScrollVelocity({
+ *     offsetX,
+ *     offsetY,
+ *     maxDistance: options.maxVisualDistance ?? TAP_SCROLL_SPEED_DEFAULTS.maxDistance,
+ *     x: {
+ *         viewportSize: bandWidth,
+ *         minSpeedMultiplier: options.minSpeedMultiplier ?? TAP_SCROLL_SPEED_DEFAULTS.minSpeedMultiplier,
+ *         maxSpeedMultiplier: options.maxSpeedMultiplier ?? computeAutoTapScrollMaxSpeedMultiplier(colCount),
+ *         hasCustomMaxSpeedMultiplier: options.maxSpeedMultiplier !== undefined,
+ *         curve: options.maxSpeedCurve,
+ *     },
+ *     y: { …same with the pane height and rowCount… },
+ * })
+ * ```
+ *
+ * 2 次元のタップサークル引きを軸別スクロール速度 (px/s、符号付き) へ分解する処理。方向余弦
+ * 分解 `v = (s_x(r)·ox/r, s_y(r)·oy/r)` — `s_a` は無改造の `computeTapScrollSpeed`。D4
+ * (等方時の方向忠実) は導出ではなく選択公理で、許容リマップ族 `u = (cos φ(θ), sin φ(θ))` を
+ * `φ = id` に固定する。評価順序は `s_a(r) * o_a / r` (左から右) にピン — 1 ulp 証人は
+ * `40*(7/25) ≠ (40*7)/25`。D1 の純軸再現はピン順序下で ≤ 1 ulp (構成依存の約 9% の点で乖離 —
+ * ビット恒等は棄却順序 `s·(o/r)` の側で、ピンはそれをフィクスチャ順序非依存と引き換えた)。
+ * 非有限オフセットは 0 へ消毒し、`r = 0` は `(0, 0)`。
+ *
+ * @param input Offsets, shared pull range, and per-axis speed parameters. / オフセット・共有引き範囲・軸別速度パラメータ。
+ * @returns Signed per-axis velocities in px/s (always finite). / 軸別の符号付き速度 (px/s、常に有限)。
+ */
+export const computeTapScrollVelocity = ({ offsetX, offsetY, maxDistance, x, y }: TapScrollVelocityInput): { x: number; y: number } => {
+    // 非有限オフセットの消毒 (finiteOr 規律): 素通しすると r と両成分が NaN 化し、
+    // スクロール位置の NaN 汚染 (文書化済みの回復不能故障) へ直結する
+    const ox = Number.isFinite(offsetX) ? offsetX : 0
+    const oy = Number.isFinite(offsetY) ? offsetY : 0
+    const r = Math.hypot(ox, oy)
+    // 原点は連続拡張が存在しない (極限が接近角に依存) ため全域関数規約で (0, 0) を返す。
+    // ドライバのゲートが積分時 r >= 6 を保証するので、この分岐は純関数側の防御でもある
+    if (r === 0) {
+        return { x: 0, y: 0 }
+    }
+    const speedX = computeTapScrollSpeed({
+        distance: r,
+        maxDistance,
+        viewportSize: x.viewportSize,
+        minSpeedMultiplier: x.minSpeedMultiplier,
+        maxSpeedMultiplier: x.maxSpeedMultiplier,
+        hasCustomMaxSpeedMultiplier: x.hasCustomMaxSpeedMultiplier,
+        curve: x.curve,
+    })
+    const speedY = computeTapScrollSpeed({
+        distance: r,
+        maxDistance,
+        viewportSize: y.viewportSize,
+        minSpeedMultiplier: y.minSpeedMultiplier,
+        maxSpeedMultiplier: y.maxSpeedMultiplier,
+        hasCustomMaxSpeedMultiplier: y.hasCustomMaxSpeedMultiplier,
+        curve: y.curve,
+    })
+    // 評価順序ピン (§4.3): s_a(r) * o_a / r — 左から右。括弧で順序を固定し、
+    // 「同値だから」と (s·(o/r)) へ並べ替える 1 ulp ドリフトを封じる
+    return { x: (speedX * ox) / r, y: (speedY * oy) / r }
+}

package/src/index.ts

@@ -5,6 +5,7 @@
  * 可変なアイテム高さに対応したReact用の高性能仮想スクロールコンポーネント。
  */
 
+export { computeTapScrollVelocity, type TapScrollAxisSpeedParams, type TapScrollVelocityInput } from "./computeTapScrollVelocity.ts"
 export { createResidualQuantizer, type ResidualQuantizer, type ResidualQuantizerOptions } from "./residualQuantizer.ts"
 export { computeAutoTapScrollMaxSpeedMultiplier, computeTapScrollSpeed, ScrollBar, type ScrollBarProps, type ScrollBarTapCircleOptions, type ScrollBarThumbOverlayRenderProps, TAP_SCROLL_SPEED_DEFAULTS, type TapScrollSpeedInput } from "./ScrollBar.tsx"
 export { ScrollPane, type ScrollPaneContentInsets, type ScrollPaneHandle, type ScrollPaneInertiaOptions, type ScrollPaneProps } from "./ScrollPane.tsx"

package/src/styles/virtualscroll.css

@@ -526,3 +526,34 @@
   white-space: nowrap;
   border: 0;
 }
+
+/* 統合 2 軸タップサークル (v3.6.0)。
+ * 純配置 — 意図的に transition を持たない: フェードする opacity は子 (サークルルート) に
+ * 住む。バー配置の「効果における双子」(DOM 形状の双子ではない)。 */
+.aqvs-grid-tap-circle-wrapper {
+  position: absolute;
+  z-index: 50; /* バーと同層 (.aqvs-scrollbar) — DOM 後勝ちで最前 */
+  pointer-events: auto;
+}
+
+/* ❗ このファイル内で .aqvs-tap-scroll-circle より「後」に置くこと: 両規則が同一要素へ
+ * 同特異度で transition longhand を設定し、後の規則が丸ごと勝つ — 出荷済み
+ * .aqvs-scrollbar-tap-circle-wrapper が今日それを行っているのと同一機構。バーサークルの
+ * 実効 transition (opacity のみ 150ms) をバイト再現し、transform 平滑化は意図的に無し
+ * (出荷挙動と一致)。順序はテストでピンする (プラン §10.2)。 */
+.aqvs-grid-tap-circle {
+  transition-property: opacity;
+  transition-duration: 150ms;
+  transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+/* パッケージ全域・単一所有者 — 本 CSS 初の forced-colors 規則: グラデーション視覚は
+ * forced-colors で平坦化され、輪郭なしではサークルが不可視になる (描画モード修正 —
+ * 単体サークルにも輪郭が付くのは登記済みの挙動非変更デルタ)。 */
+@media (forced-colors: active) {
+  .aqvs-tap-scroll-circle {
+    outline: 1px solid CanvasText;
+    outline-offset: -1px;
+    border-radius: 50%;
+  }
+}