@aiquants/spreadsheet 0.8.0

package/src/overlay/SelectionOverlay.tsx

@@ -0,0 +1,1425 @@
+/**
+ * @fileoverview Viewport-space selection overlay (ADR-4 / §6.7.2). All paint goes through the
+ * single repaintOverlay() function (React re-render path and scroll-notification path share it);
+ * the drag rect is a resident node written directly by onDragFrame. The sink lives INSIDE the
+ * overlay (the only pointer-events: auto element). v0.5 layer structure: every write pass
+ * resolves a layer set — one main layer at F = 0, or a frozen layer (clip [0, W_F), identity
+ * mapX) plus a scroll layer (clip [W_F, →), mapX = tree − hx − W_F) at F > 0 — each with its
+ * own container, resident node set, and fill pool; boundary-crossing rects are clipped per
+ * layer (standard frozen-pane technique).
+ *
+ * ビューポート空間の選択オーバーレイ (ADR-4 / §6.7.2)。塗りは repaintOverlay() 1 本に集約
+ * (React 再レンダー経路とスクロール通知経路が共有)。ドラッグ矩形は常設ノードへの直書き。
+ * シンクはオーバーレイ内に常駐する (唯一の pointer-events: auto)。v0.5 の層構造: 書込パス毎に
+ * 層集合を解決 — F = 0 は主層 1 枚、F > 0 は凍結層 (クリップ [0, W_F)・恒等 mapX) +
+ * スクロール層 (クリップ [W_F, →)・mapX = 木 − hx − W_F)。各層が専用コンテナ / 常設ノード束 /
+ * 塗りプールを持ち、境界跨ぎ矩形は各層のクリップが切る (標準の凍結ペイン技法)。
+ *
+ * v0.8 rich cells (plan §2.4 / §4.2.12): every capability below is a DECLARATION — when the root
+ * does not pass it the overlay reproduces the v0.7 DOM and style writes exactly.
+ * - Highlight bands: per range (tail BAND_RANGE_CAP ranges) five resident nodes — two row
+ *   segments, two column segments and the intersection — inserted UNDER the fills. Partitioned
+ *   BY INPUT: a segment's main-axis size is the layer's clamp extent, written only when that
+ *   extent changes (the `layersFor` heal pass); per frame only its `transform` places the inner
+ *   edge at `clamp(edge, 0, extent)`, so a range scrolled out of view still yields full-viewport
+ *   coverage and the scroll path is transform-only by construction. Cross-axis sizes and the
+ *   intersection node are rewritten only when their numbers change (selection / axis / clamp
+ *   movement — a JS-side same-value cache, never a DOM read). Colours flow through
+ *   `--aqsp-band-*`, written by ONE layout effect and removed again when the palette retires.
+ * - Edit paint: the sink's `paddingTop` follows `EditPaint.lineBoxPx` / `verticalAlign`.
+ * - Popover anchors: two nodes owned by the popover layer are placed on their cells by the same
+ *   frozen-partition mapping as the fill handle (hidden under a frozen band / off-viewport).
+ * - Drag-rect mode "point" (formula-reference drag) paints `data-aqsp-drag-mode="point"`.
+ *
+ * v0.8 リッチセル (計画 §2.4 / §4.2.12): 以下の能力は全て**宣言** — root が渡さなければ v0.7 の
+ * DOM と style 書込を厳密に再現する。
+ * - 強調帯: レンジ毎 (末尾 BAND_RANGE_CAP 件) に常設 5 ノード — 行 2 セグメント / 列 2 セグメント /
+ *   交点 — を fill の**下**へ挿入。**入力で分割**: セグメントの主軸サイズは層のクランプ幅 / 高さで、
+ *   その値が変わるとき (`layersFor` の heal パス) だけ書き、毎フレームは `transform` だけで内側の辺を
+ *   `clamp(edge, 0, extent)` へ置く — 画面外へスクロールしたレンジでも viewport 全幅を覆い、スクロール
+ *   経路は構造的に transform のみ。交差軸サイズと交点ノードは数値が変わったときだけ書く (選択 / 軸 /
+ *   クランプ移動 — JS 側の同値キャッシュ、DOM 読みなし)。色は `--aqsp-band-*` を layout effect が 1 回書き、
+ *   パレットの退役で外す。
+ * - エディタ塗り: シンクの `paddingTop` は `EditPaint.lineBoxPx` / `verticalAlign` に従う。
+ * - ポップオーバーアンカー: ポップオーバー層所有の 2 ノードを fill ハンドルと同じ凍結分割写像でセルへ
+ *   配置 (凍結帯の下 / viewport 外は非表示)。
+ * - ドラッグ矩形モード "point" (参照ドラッグ) は `data-aqsp-drag-mode="point"` を描く。
+ */
+
+import { useWheelBridge, type VirtualGridHandle } from "@aiquants/virtualscroll"
+import { type ReactNode, type RefObject, useCallback, useEffect, useLayoutEffect, useMemo, useRef } from "react"
+import type { AxisModel } from "../model/axisModel.ts"
+import { isWholeCols, isWholeRows } from "../model/cellAnnotations.ts"
+import { type CellCoord, type CellRange, makeRange } from "../model/cellCoord.ts"
+import { type EditPaint, IDLE_EDIT_PAINT } from "../model/cellPaint.ts"
+import { colToViewportX, frozenHeightOf, frozenWidthOf, rowToViewportY } from "../model/frozenPartition.ts"
+import { SCROLLBAR_WIDTH } from "../model/viewStore.ts"
+import type { PopoverAnchorState } from "../popover/usePopovers.ts"
+import type { SelectionState } from "../selection/selectionState.ts"
+
+/** Viewport-space rect (private — distinct from the logical-space LogicalRect). / ビューポート矩形 (非公開)。 */
+type ViewportRect = { top: number; left: number; width: number; height: number }
+
+/** Clamp margin: one screen each side. / クランプ余白 (± 1 画面)。 */
+const CLAMP_MARGIN_SCREENS = 1
+
+/** Ants-band outset in logical px (kept in sync with the CSS var fallback -3px). / アンツ帯の外側オフセット論理 px (CSS 変数フォールバック -3px と同期)。 */
+const CLIP_MARQUEE_OUTSET = 3
+
+/**
+ * Progressive per-edge ants outset: extend outward by the available headroom, floored (floor
+ * is strictly overshoot-free — round would poke the band up to 0.5px past the clip edge).
+ * Exported for the direct fractional-input pin (barrel-private).
+ * 漸進端別アウトセット: 余白ぶんだけ外へ (floor — round は最大 0.5px はみ出す)。小数入力の直接
+ * ピン用にモジュール export (バレル非公開)。
+ */
+export const clipMarqueeOutset = (headroom: number): string => `${-Math.min(CLIP_MARQUEE_OUTSET, Math.max(0, Math.floor(headroom)))}px`
+
+/** Row / column / intersection highlight switches (v0.8 §2.4 — default all off = zero band nodes). / 行 / 列 / 交点強調のスイッチ (v0.8 §2.4 — 既定全 off = 帯ノード 0)。 */
+export type HighlightState = { row: boolean; column: boolean; intersection: boolean }
+
+/** Band colours + shared opacity, written to `--aqsp-band-*` by ONE layout effect (never per frame). / 帯の色 + 共通不透明度 (`--aqsp-band-*` へ layout effect が 1 回書く — 毎フレームは書かない)。 */
+export type HighlightColors = { row: string; column: string; intersection: string; opacity: number }
+
+/** Default band palette (plan §1.9) — the same values the `.aqsp-root` CSS variables fall back to. / 既定の帯パレット (計画 §1.9) — `.aqsp-root` の CSS 変数既定と同値。 */
+export const DEFAULT_HIGHLIGHT_COLORS: HighlightColors = Object.freeze({ row: "#0084FF", column: "#42FF4F", intersection: "#E1FF00", opacity: 0.2 })
+
+/** Range cap of the band pool: beyond it only the TAIL ranges carry bands (deviation row). / 帯プールのレンジ上限 (超過は末尾レンジだけ — 逸脱行)。 */
+export const BAND_RANGE_CAP = 16
+
+/** Live drag-rect modes: §3.2 add / subtract plus the v0.8 "point" (formula-reference drag). / ドラッグ矩形のモード: §3.2 の add / subtract + v0.8 の "point" (参照ドラッグ)。 */
+export type DragFrameMode = "add" | "subtract" | "point"
+
+/** Band kinds (the `data-aqsp-band` vocabulary). / 帯の種別 (`data-aqsp-band` の語彙)。 */
+type BandKind = "row" | "column" | "intersection"
+
+/** Segment edges (the `data-aqsp-band-edge` vocabulary of the four segments). / セグメントの辺 (4 セグメントの `data-aqsp-band-edge` 語彙)。 */
+type BandEdge = "left" | "right" | "above" | "below"
+
+/**
+ * Last-written numbers of one band group — JS-side same-value suppression so a frame writes a
+ * size, a display or the cross tint only when it actually changes (no DOM reads on the hot
+ * path). `crossTint` is the colour family the cross node currently paints ("intersection" = the
+ * CSS default, no inline background).
+ * 帯 1 組の直近書込値 — JS 側の同値抑止で、サイズ / display / 交点の色は実際に変わるフレームだけ書く
+ * (ホットパスで DOM を読まない)。`crossTint` は交点ノードが現在塗る色族 ("intersection" = CSS 既定、
+ * インライン background なし)。
+ */
+type BandWriteState = { rowShown: boolean; colShown: boolean; crossShown: boolean; crossTint: BandKind; rowHeight: number; colWidth: number; crossWidth: number; crossHeight: number }
+
+/** One range's band group: two row segments, two column segments and the intersection node. / レンジ 1 つの帯組: 行 2 セグメント + 列 2 セグメント + 交点ノード。 */
+export type BandNodes = { rowLeft: HTMLDivElement; rowRight: HTMLDivElement; colAbove: HTMLDivElement; colBelow: HTMLDivElement; cross: HTMLDivElement; last: BandWriteState }
+
+/** Geometry rect consumed by the band placer (structural — the private ViewportRect satisfies it). / 帯配置が消費する矩形 (構造型 — 非公開 ViewportRect が満たす)。 */
+type BandRect = { top: number; left: number; width: number; height: number }
+
+/** Layer clamp extents consumed by the band placer (structural subset of LayerCtx). / 帯配置が消費する層のクランプ範囲 (LayerCtx の構造的部分集合)。 */
+type BandExtents = { clampWidth: number; clampHeight: number }
+
+/** Creates one hidden band node with its drawing traits and DOM hooks. / 描画特性と DOM フックを持つ帯ノード 1 個を非表示で生成。 */
+const makeBandNode = (kind: BandKind, edge: BandEdge | null): HTMLDivElement => {
+    const node = document.createElement("div")
+    node.className = "aqsp-band"
+    node.setAttribute("data-aqsp-band", kind)
+    // 4 セグメントだけが辺を名乗る (交点は辺を持たない)
+    if (edge !== null) {
+        node.setAttribute("data-aqsp-band-edge", edge)
+    }
+    node.style.display = "none"
+    return node
+}
+
+/**
+ * Creates a band group (5 hidden nodes + an empty write cache). Barrel-private; exported for
+ * the synthetic-layer geometry pins.
+ * 帯組 (非表示 5 ノード + 空の書込キャッシュ) を生成。バレル非公開 — 合成層の幾何ピン用に export。
+ */
+export const createBandNodes = (): BandNodes => ({
+    rowLeft: makeBandNode("row", "left"),
+    rowRight: makeBandNode("row", "right"),
+    colAbove: makeBandNode("column", "above"),
+    colBelow: makeBandNode("column", "below"),
+    cross: makeBandNode("intersection", null),
+    last: { rowShown: false, colShown: false, crossShown: false, crossTint: "intersection", rowHeight: -1, colWidth: -1, crossWidth: -1, crossHeight: -1 },
+})
+
+/** The group's nodes in DOM (= paint) order: segments under the intersection. / 帯組のノードを DOM (= 描画) 順に: セグメントの上に交点。 */
+const bandNodeList = (nodes: BandNodes): readonly HTMLDivElement[] => [nodes.rowLeft, nodes.rowRight, nodes.colAbove, nodes.colBelow, nodes.cross]
+
+/**
+ * Heal pass of the band geometry (§2.4): the MAIN-axis size of every segment is the layer's
+ * clamp extent — row segments are `clampWidth` wide, column segments `clampHeight` tall. This is
+ * the ONLY writer of those sizes; the per-frame placer never touches them.
+ * 帯幾何の heal パス (§2.4): 各セグメントの**主軸**サイズは層のクランプ範囲 — 行セグメントは幅
+ * `clampWidth`、列セグメントは高さ `clampHeight`。このサイズの唯一の書き手で、毎フレームの配置は触らない。
+ */
+export const healBandGeometry = (nodes: BandNodes, clampWidth: number, clampHeight: number): void => {
+    const width = `${clampWidth}px`
+    const height = `${clampHeight}px`
+    nodes.rowLeft.style.width = width
+    nodes.rowRight.style.width = width
+    nodes.colAbove.style.height = height
+    nodes.colBelow.style.height = height
+}
+
+/** Clamps a coordinate into [0, max]. / 座標を [0, max] へクランプ。 */
+const clampTo = (value: number, max: number): number => Math.min(Math.max(value, 0), max)
+
+/**
+ * The popover anchors' hidden state (`placeAnchor`): a clip that paints nothing and takes no
+ * hits while the node stays rendered, so a focused editor inside survives (no browser focus
+ * fixup — `display: none` / `visibility: hidden` would blur it).
+ * ポップオーバーアンカーの非表示状態 (`placeAnchor`): 何も描かずヒットも取らないがノードは描画ツリーに
+ * 残る clip — 中のフォーカス中エディタが生き残る (ブラウザの focus fixup が走らない。`display: none` /
+ * `visibility: hidden` はフォーカスを外す)。
+ */
+const ANCHOR_HIDDEN_CLIP = "inset(100%)"
+
+/** Toggles display on a node list. / ノード列の display を切替。 */
+const setShown = (nodes: readonly HTMLDivElement[], shown: boolean): void => {
+    for (const node of nodes) {
+        node.style.display = shown ? "block" : "none"
+    }
+}
+
+/**
+ * Per-frame band placement for one range rect in one layer (§2.4, partitioned BY INPUT):
+ * - row segments: `transform` only — left segment's right edge at `clamp(rect.left, 0, W)`
+ *   (so `translate(clamp − W)` with its healed width W), right segment's left edge at
+ *   `clamp(rect.right, 0, W)`; their height (cross-axis) is written only when it changes;
+ * - column segments: the transposed twin with H = clampHeight;
+ * - intersection: range-sized (size when changed, `transform` per frame); when EXACTLY ONE
+ *   family is shown and `highlight.intersection` is off, the node lights up tinted with that
+ *   family's colour (inline `background` through the family's `--aqsp-band-*` variable) — the
+ *   sheets-enhancer extension paints one full-width band THROUGH the selection when the other
+ *   family is off, so the flanking segments alone would break the band colour at the range;
+ *   with both families on the hole is kept (extension parity);
+ * - a whole-axis range (`spansAxis` — every column of a row-header selection, or every row of
+ *   a column-header selection) omits BOTH segment families and keeps only the intersection: the
+ *   spanned-axis band would duplicate the selection, and the cross-axis band placed at the
+ *   range's extent would tint the whole viewport on the other side (the sheets-enhancer
+ *   extension draws nothing for whole-axis selections); `highlight` switches each family.
+ *   Display is written only on a change (JS-side cache).
+ * レンジ矩形 1 つの層内配置 (毎フレーム、§2.4 の入力分割):
+ * - 行セグメント: `transform` のみ — 左セグメントの右辺を `clamp(rect.left, 0, W)` へ (heal 済み幅 W で
+ *   `translate(clamp − W)`)、右セグメントの左辺を `clamp(rect.right, 0, W)` へ。高さ (交差軸) は変化時だけ。
+ * - 列セグメント: H = clampHeight の転置双子。
+ * - 交点: レンジサイズ (サイズは変化時、`transform` は毎フレーム)。**単一族のみ**表示かつ intersection
+ *   off のときはその族の色 (族の `--aqsp-band-*` 変数を参照するインライン `background`) で点灯する —
+ *   sheets-enhancer 拡張は片族 off なら選択を貫く全幅帯 1 本を描くため、両脇セグメントだけではレンジ
+ *   位置で帯色が途切れる。両族表示時は拡張同様に穴のまま。
+ * - 全軸スパンのレンジ (`spansAxis` — 行ヘッダー選択の全列 / 列ヘッダー選択の全行) は行帯 / 列帯の**両族**を
+ *   省略し交点だけ残す: 同軸の帯は選択の重複、交差軸の帯をレンジ寸法で置くと反対側の viewport 全面が染まる
+ *   (sheets-enhancer 拡張は全軸選択で何も描かない)。`highlight` が族毎に切替。display は変化時のみ (JS キャッシュ)。
+ */
+export const placeBandSegments = (nodes: BandNodes, rect: BandRect, extents: BandExtents, highlight: HighlightState, spansAxis: boolean): void => {
+    const last = nodes.last
+    // 行帯: 全軸スパンのレンジは両族とも省略 (帯は交点に吸収される — 交差軸の帯は viewport 全面を染めるため)
+    const rowShown = highlight.row && !spansAxis
+    if (rowShown !== last.rowShown) {
+        last.rowShown = rowShown
+        setShown([nodes.rowLeft, nodes.rowRight], rowShown)
+    }
+    if (rowShown) {
+        // 交差軸サイズ (行帯の高さ) は変化時だけ
+        if (rect.height !== last.rowHeight) {
+            last.rowHeight = rect.height
+            const height = `${rect.height}px`
+            nodes.rowLeft.style.height = height
+            nodes.rowRight.style.height = height
+        }
+        // 主軸は transform のみ — 内側の辺をクランプ範囲へ置く (主軸サイズは heal パスの clampWidth)
+        nodes.rowLeft.style.transform = `translate(${clampTo(rect.left, extents.clampWidth) - extents.clampWidth}px, ${rect.top}px)`
+        nodes.rowRight.style.transform = `translate(${clampTo(rect.left + rect.width, extents.clampWidth)}px, ${rect.top}px)`
+    }
+    // 列帯: 行帯と同じ全軸スパン省略
+    const colShown = highlight.column && !spansAxis
+    if (colShown !== last.colShown) {
+        last.colShown = colShown
+        setShown([nodes.colAbove, nodes.colBelow], colShown)
+    }
+    if (colShown) {
+        if (rect.width !== last.colWidth) {
+            last.colWidth = rect.width
+            const width = `${rect.width}px`
+            nodes.colAbove.style.width = width
+            nodes.colBelow.style.width = width
+        }
+        nodes.colAbove.style.transform = `translate(${rect.left}px, ${clampTo(rect.top, extents.clampHeight) - extents.clampHeight}px)`
+        nodes.colBelow.style.transform = `translate(${rect.left}px, ${clampTo(rect.top + rect.height, extents.clampHeight)}px)`
+    }
+    // 交点: レンジそのもの (サイズは変化時、transform は毎フレーム)。単一族のみ表示で intersection が
+    // off のときもその族の色で点灯する — 拡張は片族 off なら選択を貫く全幅帯 1 本を描くため、両脇
+    // セグメントだけではレンジ位置で帯色が途切れる (両族表示時は拡張同様に穴のまま)
+    const crossTint: BandKind | null = highlight.intersection ? "intersection" : rowShown !== colShown ? (rowShown ? "row" : "column") : null
+    const crossShown = crossTint !== null
+    if (crossShown !== last.crossShown) {
+        last.crossShown = crossShown
+        setShown([nodes.cross], crossShown)
+    }
+    if (crossTint !== null) {
+        // 埋め色は族の CSS 変数を参照するインライン background (パレット交換に追随)、交点表示へ戻るとき解除
+        if (crossTint !== last.crossTint) {
+            last.crossTint = crossTint
+            nodes.cross.style.background = crossTint === "intersection" ? "" : `var(--aqsp-band-${crossTint})`
+        }
+        if (rect.width !== last.crossWidth || rect.height !== last.crossHeight) {
+            last.crossWidth = rect.width
+            last.crossHeight = rect.height
+            nodes.cross.style.width = `${rect.width}px`
+            nodes.cross.style.height = `${rect.height}px`
+        }
+        nodes.cross.style.transform = `translate(${rect.left}px, ${rect.top}px)`
+    }
+}
+
+/** Hides a band group (writes only the nodes currently shown). / 帯組を消灯 (表示中のノードだけ書く)。 */
+export const hideBandNodes = (nodes: BandNodes): void => {
+    const last = nodes.last
+    if (last.rowShown) {
+        last.rowShown = false
+        setShown([nodes.rowLeft, nodes.rowRight], false)
+    }
+    if (last.colShown) {
+        last.colShown = false
+        setShown([nodes.colAbove, nodes.colBelow], false)
+    }
+    if (last.crossShown) {
+        last.crossShown = false
+        setShown([nodes.cross], false)
+    }
+}
+
+/** Detaches a band group from the DOM. / 帯組を DOM から外す。 */
+const removeBandNodes = (nodes: BandNodes): void => {
+    for (const node of bandNodeList(nodes)) {
+        node.remove()
+    }
+}
+
+/**
+ * Editing sink's top padding from the row height and the edit paint (§2.3): the free space is
+ * `rowHeight − 1 (bottom grid line) − lineBoxPx`; middle centres it (the cell's flex centring),
+ * top is 0 and bottom pushes the line box to the bottom. Never negative.
+ * 行高とエディタ塗りからシンクの上パディング (§2.3): 余白 = `行高 − 1 (下罫) − lineBoxPx`。middle は
+ * 中央 (セルの flex 中央)、top は 0、bottom は下詰め。負にはならない。
+ */
+export const sinkPaddingTop = (rowHeight: number, paint: EditPaint): number => {
+    const free = rowHeight - 1 - paint.lineBoxPx
+    if (paint.verticalAlign === "top") {
+        return 0
+    }
+    if (paint.verticalAlign === "bottom") {
+        return Math.max(0, free)
+    }
+    return Math.max(0, free / 2)
+}
+
+/** Shared empty range list (no allocation on the all-off path). / 共有の空レンジ列 (全 off 経路で確保しない)。 */
+const NO_RANGES: readonly CellRange[] = Object.freeze([])
+
+type SelectionOverlayProps = {
+    rowAxis: AxisModel
+    colAxis: AxisModel
+    handleRef: RefObject<VirtualGridHandle | null>
+    sinkRef: RefObject<HTMLTextAreaElement | null>
+    /**
+     * Imperative read of the confirmed selection (owner: Spreadsheet's selectionRef). A
+     * render-synced prop would go stale on the sheet-switch commit: the passive repaint effect
+     * runs with NEW axes before the reset re-render lands, and old-selection x new-axes hits
+     * the Fenwick out-of-bounds fail-fast inside sizeOf.
+     * 確定選択の命令読み (所有は Spreadsheet の selectionRef)。レンダー同期 prop だとシート切替
+     * コミットで stale — passive repaint がリセット再レンダーより先に新軸で走り、旧選択 × 新軸が
+     * sizeOf の Fenwick 範囲外 fail-fast を踏む。
+     */
+    getSelection: () => SelectionState
+    /** Editing state as a boolean prop (§6.7.2-4 — mind the name clash with the isEditing function seam; !editing is safe as a per-render evaluation). / 編集状態の boolean prop (関数シーム isEditing との同名衝突に注意)。 */
+    editing: boolean
+    /** Virtual-keyboard invitation (Spreadsheet owns the flag): rendered as the sink's inputmode — "text" while invited, "none" otherwise. / 仮想キーボード招待 (フラグは Spreadsheet が所有) — シンクの inputmode として描画 ("text" = 招待中 / "none")。 */
+    virtualKeyboard: boolean
+    /** Registration target for repaintOverlay (owner: Spreadsheet — the §6.9-7 repaintOverlayRef indirection). / repaintOverlay の登録先 (所有は Spreadsheet)。 */
+    repaintRef: RefObject<(() => void) | null>
+    /** Drag-rect writer registration (called via the Spreadsheet onDragFrame relay, which appends the §3.2 mode; v0.8 adds "point" for the formula-reference drag). / ドラッグ矩形 writer の登録先 (Spreadsheet の onDragFrame リレー経由 — mode は §3.2 のリレーが付加。v0.8 は参照ドラッグの "point" を追加)。 */
+    dragFrameRef: RefObject<((range: CellRange | null, mode: DragFrameMode) => void) | null>
+    /** Armed-clip reader for the marching-ants marquee (copy / cut kind + range; null hides; a `foreign` clip — a cut kept across a sheet switch, v0.8 — is never drawn: its range belongs to the other sheet). / 装填中クリップ (copy / cut の kind + range) の読み — null なら非表示。`foreign` (シート切替を跨いで保持した cut — v0.8) は描かない (レンジは別シートの座標)。 */
+    getClip: () => { kind: "copy" | "cut"; range: CellRange; foreign: boolean } | null
+    /** Composite drag probe across ALL 5 machines (§8.1 fill-handle visibility). / 全 5 機械合成のドラッグ判定 (§8.1 の可視条件)。 */
+    getIsDraggingAny: () => boolean
+    /**
+     * Fill machine's OWN drag probe (§8.1 — one composite value cannot tell the fill's own
+     * drag from other machines': the mandatory press repaint would display:none the captured
+     * handle and kill the drag via lostpointercapture).
+     * fill 機械自身のドラッグ判定 (§8.1 — 合成値 1 本では fill 自身と他機械を判別できず、
+     * 押下直後の義務 repaint が capture 中のハンドルを display:none にしてドラッグを即死させる)。
+     */
+    getIsFillDragging: () => boolean
+    /** Fill-preview writer registration (the fill machine + its autoscrollers write through this). / fill プレビュー writer の登録先。 */
+    fillFrameRef: RefObject<((range: CellRange | null) => void) | null>
+    /** Resize-guideline writer registration (useHeaderResize writes through this). / リサイズガイドライン writer の登録先。 */
+    resizeGuideFrameRef: RefObject<((guide: ResizeGuide | null) => void) | null>
+    /** Fill-handle node registration (useFillHandle wires its pointerdown here). / fill ハンドルノードの登録先 (useFillHandle が結線)。 */
+    fillHandleNodeRef: RefObject<HTMLDivElement | null>
+    /** §11 opt-out: false suppresses the handle node entirely (machine inert too). / §11 の opt-out (false はノードごと抑止)。 */
+    enableFillHandle: boolean
+    /** Frozen leading columns (v0.5 — drives the horizontal split; freshness reads still use the handle). / 先頭凍結列数 (v0.5 — 横分割の構造判定。鮮度読みはハンドル)。 */
+    frozenCols: number
+    /** Frozen leading rows (v0.6 — drives the vertical split into 2D quadrants). / 先頭凍結行数 (v0.6 — 縦分割で 2D 象限化)。 */
+    frozenRows: number
+    sinkAriaLabel: string
+    onSinkMouseDown: (event: MouseEvent) => void
+    /**
+     * v0.8 capability: the editing sink's paint (line box + vertical alignment) owned by the
+     * editor. Absent ⇒ the v0.7 13 px centred padding.
+     * v0.8 能力: エディタ所有のシンク塗り (行箱 + 垂直揃え)。未指定 ⇒ v0.7 の 13px 中央パディング。
+     */
+    editPaintRef?: RefObject<EditPaint>
+    /**
+     * v0.8 capability: highlight switches (root-owned, render-time assigned; the root repaints on
+     * change). Absent or all off ⇒ zero band nodes (v0.7 DOM identity).
+     * v0.8 能力: 強調スイッチ (root 所有・レンダー時代入、変更時は root が repaint)。未指定 / 全 off ⇒
+     * 帯ノード 0 (v0.7 の DOM 恒等)。
+     */
+    highlightRef?: RefObject<HighlightState>
+    /** v0.8 capability: identity-stable band palette written to `--aqsp-band-*` by a layout effect; the variables are removed again when the palette retires (undefined / identity change / unmount). Absent ⇒ no variable writes (CSS defaults apply — the v0.7 style attribute). / v0.8 能力: identity 安定の帯パレット (layout effect が `--aqsp-band-*` へ書き、パレットの退役 (undefined / identity 交代 / unmount) で変数を外す)。未指定 ⇒ 変数書込なし (CSS 既定 = v0.7 の style 属性)。 */
+    highlightColors?: HighlightColors
+    /** v0.8 capability: popover anchor cells to position (interactive + tip). Absent ⇒ anchors untouched. / v0.8 能力: 配置するポップオーバーアンカーのセル (interactive + tip)。未指定 ⇒ アンカーに触れない。 */
+    popoverAnchors?: RefObject<PopoverAnchorState>
+    /** Interactive anchor node (owned by the popover layer; note / comment / link / list / message). / interactive アンカーノード (ポップオーバー層所有)。 */
+    interactiveAnchorRef?: RefObject<HTMLDivElement | null>
+    /** Note-tip anchor node (owned by the popover layer). / note-tip アンカーノード (ポップオーバー層所有)。 */
+    tipAnchorRef?: RefObject<HTMLDivElement | null>
+}
+
+/** Live resize guideline descriptor (logical axis px). / リサイズガイドラインの記述子 (論理軸 px)。 */
+export type ResizeGuide = { axis: "row" | "col"; position: number }
+
+/** Resident node set of one overlay layer (v0.5 layer split; every layer owns a dedicated container). / overlay 1 層ぶんの常設ノード束 (v0.5 の層分割。全層が専用コンテナを持つ)。 */
+type LayerNodes = {
+    container: HTMLDivElement | null
+    active: HTMLDivElement | null
+    dragRect: HTMLDivElement | null
+    marquee: HTMLDivElement | null
+    fillPreview: HTMLDivElement | null
+    resizeGuide: HTMLDivElement | null
+    fillPool: HTMLElement[]
+    /** Band groups per confirmed range (tail BAND_RANGE_CAP), inserted under the fills. / 確定レンジ毎の帯組 (末尾 BAND_RANGE_CAP 件)、fill の下。 */
+    bandPool: BandNodes[]
+    /** Band group of the live drag rect (null until a drag needs one). / ライブドラッグ矩形の帯組 (必要になるまで null)。 */
+    dragBand: BandNodes | null
+    /** Last healed clamp extents of this layer's bands (-1 = never healed). / この層の帯の直近 heal 済みクランプ範囲 (-1 = 未 heal)。 */
+    bandClampWidth: number
+    bandClampHeight: number
+}
+
+/** Inline container geometry of one x-split ("" clears the property). / x 分割 1 本のコンテナインライン形状 ("" はプロパティ解除)。 */
+type XSplitStyle = { left: string; right: string; width: string }
+
+/** Inline container geometry of one y-split ("" clears the property). / y 分割 1 本のコンテナインライン形状 ("" はプロパティ解除)。 */
+type YSplitStyle = { top: string; bottom: string; height: string }
+
+/** One write-pass layer context: nodes + tree→viewport maps + clamp extents + container inline geometry on both axes (v0.6 2D quadrants). / 1 書込パスの層コンテキスト (ノード束 + 両軸の木→viewport 写像 + クランプ範囲 + コンテナのインライン形状。v0.6 の 2D 象限)。 */
+type LayerCtx = { nodes: LayerNodes; mapX: (treeX: number) => number; clampWidth: number; xStyle: XSplitStyle; mapY: (treeY: number) => number; clampHeight: number; yStyle: YSplitStyle }
+
+/** One-axis split segment (kind + tree→viewport map + clamp extent + container inline geometry). / 片軸の分割セグメント (種別 + 木→viewport 写像 + クランプ範囲 + コンテナのインライン形状)。 */
+type AxisSplit<S> = { kind: "m" | "f" | "s"; map: (tree: number) => number; clamp: number; style: S }
+
+/** Split-descriptor cache: quadrant contexts keyed on the freeze/viewport geometry (scroll-free — the split maps read the live scroll snapshot). / 分割記述子キャッシュ: 凍結 / viewport 幾何をキーにした象限コンテキスト (スクロール非依存 — 写像は生スクロール快照を読む)。 */
+type SplitCache = { frozenCols: number; frozenWidth: number; frozenRows: number; frozenHeight: number; bodyWidth: number; bodyHeight: number; ctxs: LayerCtx[] }
+
+/** Main-band container geometry per axis (no freeze — module constants so a cache rebuild allocates none). / 各軸の主帯コンテナ形状 (非凍結 — キャッシュ再構築でも確保しないモジュール定数)。 */
+const X_MAIN_STYLE: XSplitStyle = { left: "0px", right: "0px", width: "" }
+const Y_MAIN_STYLE: YSplitStyle = { top: "0px", bottom: "0px", height: "" }
+
+/** Empty resident-node set. / 空の常設ノード束。 */
+const emptyLayerNodes = (): LayerNodes => ({ container: null, active: null, dragRect: null, marquee: null, fillPreview: null, resizeGuide: null, fillPool: [], bandPool: [], dragBand: null, bandClampWidth: -1, bandClampHeight: -1 })
+
+/** All quadrant keys ever rendered (xKind + yKind; m = no freeze on that axis). / 描画され得る全象限キー (xKind + yKind、m = 当該軸非凍結)。 */
+const QUADRANT_KEYS = ["mm", "fm", "sm", "mf", "ms", "ff", "sf", "fs", "ss"] as const
+
+/** Fill-handle square size in px (§8.1). / fill ハンドルの一辺 (px)。 */
+const FILL_HANDLE_SIZE = 6
+
+/**
+ * Renders the overlay chrome (fill / active frame / drag rect / cut marquee / sink).
+ * オーバーレイ一式 (確定塗り / アクティブ枠 / ドラッグ矩形 / cut マーキー / シンク) を描画。
+ */
+export const SelectionOverlay = ({
+    rowAxis,
+    colAxis,
+    handleRef,
+    sinkRef,
+    getSelection,
+    editing,
+    virtualKeyboard,
+    repaintRef,
+    dragFrameRef,
+    getClip,
+    getIsDraggingAny,
+    getIsFillDragging,
+    fillFrameRef,
+    resizeGuideFrameRef,
+    fillHandleNodeRef,
+    enableFillHandle,
+    frozenCols,
+    frozenRows,
+    sinkAriaLabel,
+    onSinkMouseDown,
+    editPaintRef,
+    highlightRef,
+    highlightColors,
+    popoverAnchors,
+    interactiveAnchorRef,
+    tipAnchorRef,
+}: SelectionOverlayProps): ReactNode => {
+    const overlayRef = useRef<HTMLDivElement | null>(null)
+    /** Live fill-preview rect (source ∪ band) for scroll-follow repositioning (§8.2). / 生存中 fill プレビュー矩形 (スクロール追随用)。 */
+    const liveFillPreviewRef = useRef<CellRange | null>(null)
+    /** Live resize guideline for scroll-follow repositioning (§7.2). / 生存中ガイドライン (スクロール追随用)。 */
+    const liveResizeGuideRef = useRef<ResizeGuide | null>(null)
+
+    // ---- 凍結 2D 象限 (v0.6 計画 §3-4 — v0.5 の 2 層を両軸へ拡張): 各軸を凍結帯 / スクロール帯
+    //      (または非凍結の主帯) へ分割し、その**デカルト積**の象限ごとに常設ノード一式を複製する。
+    //      最大 4 象限 (コーナー / 行凍結×列スクロール / 行スクロール×列凍結 / 両スクロール)。
+    //      境界跨ぎ矩形は各象限のクリップが切る (標準の凍結ペイン技法)。全象限が専用コンテナを
+    //      持つ一様な生命構造 — JSX 分岐切替で React がコンテナごと退役させ ref detach がプールを
+    //      空にする (R1 是正: 孤児プールの幽霊塗り防止)。ノードはキー付きレジストリで索引 ----
+    const layerRegistryRef = useRef<Map<string, LayerNodes>>(new Map(QUADRANT_KEYS.map((key) => [key, emptyLayerNodes()])))
+    const nodeSetFor = useCallback((key: string): LayerNodes => {
+        const existing = layerRegistryRef.current.get(key)
+        if (existing !== undefined) {
+            return existing
+        }
+        const created = emptyLayerNodes()
+        layerRegistryRef.current.set(key, created)
+        return created
+    }, [])
+    /** Heals a container's inline geometry to fresh values (renderless resize/freeze — §7-4 の器版); fixed-key writes, no per-call pair arrays. / コンテナのインライン形状を鮮度値へヒール (固定キー書込 — 呼び毎のペア配列なし)。 */
+    const healContainer = useCallback((node: HTMLDivElement | null, xStyle: XSplitStyle, yStyle: YSplitStyle) => {
+        if (node === null) {
+            return
+        }
+        // 固定キー書込 + 同値抑止 (Object.entries のペア配列を毎 repaint 確保しない。書込パス毎の
+        // ヒールが毎フレーム setStyle を撃たない)
+        const style = node.style
+        if (style.left !== xStyle.left) {
+            style.left = xStyle.left
+        }
+        if (style.right !== xStyle.right) {
+            style.right = xStyle.right
+        }
+        if (style.width !== xStyle.width) {
+            style.width = xStyle.width
+        }
+        if (style.top !== yStyle.top) {
+            style.top = yStyle.top
+        }
+        if (style.bottom !== yStyle.bottom) {
+            style.bottom = yStyle.bottom
+        }
+        if (style.height !== yStyle.height) {
+            style.height = yStyle.height
+        }
+    }, [])
+    /**
+     * Band heal pass (§2.4): when a layer's clamp extents change (viewport / frozen geometry /
+     * layer switch) every band segment of that layer receives its main-axis size again. An empty
+     * pool (default off) touches nothing — v0.7 identity with zero new style writes.
+     * 帯の heal パス (§2.4): 層のクランプ範囲が変わったとき (viewport / 凍結幾何 / 層切替) その層の全帯
+     * セグメントへ主軸サイズを書き直す。空プール (既定 off) は何にも触れない — 新規 style 書込 0 の v0.7 恒等。
+     */
+    const healLayerBands = useCallback((nodes: LayerNodes, clampWidth: number, clampHeight: number) => {
+        // 同値抑止 (書込パス毎の heal が毎フレーム size を撃たない)
+        if (nodes.bandClampWidth === clampWidth && nodes.bandClampHeight === clampHeight) {
+            return
+        }
+        nodes.bandClampWidth = clampWidth
+        nodes.bandClampHeight = clampHeight
+        for (const group of nodes.bandPool) {
+            healBandGeometry(group, clampWidth, clampHeight)
+        }
+        if (nodes.dragBand !== null) {
+            healBandGeometry(nodes.dragBand, clampWidth, clampHeight)
+        }
+    }, [])
+    /** Live scroll snapshot the cached split maps read (`layersFor` refreshes it on every call). / キャッシュ済み分割写像が読む生スクロール快照 (`layersFor` が毎呼び更新)。 */
+    const scrollSnapshotRef = useRef({ x: 0, y: 0 })
+    /** Split-descriptor cache — invalidated by freeze / viewport geometry change, never by scroll. / 分割記述子キャッシュ — 凍結 / viewport 幾何の変化で無効化 (スクロールでは無効化しない)。 */
+    const splitCacheRef = useRef<SplitCache | null>(null)
+    /**
+     * Resolves the active quadrant layer contexts for one write pass (fresh W_F/H_F/hx/vy — §7-4).
+     * The Cartesian product of the x-split and y-split; each quadrant heals its container geometry.
+     * The descriptors are cached per freeze/viewport geometry and the maps read hx/vy through the
+     * scroll snapshot, so a steady-state scroll frame allocates nothing here.
+     * 1 書込パスぶんの象限コンテキストを解決 (§7-4 の鮮度 W_F / H_F / hx / vy)。x 分割 × y 分割の
+     * デカルト積で、各象限は自コンテナの形状をヒールする。記述子は凍結 / viewport 幾何ごとに
+     * キャッシュし、写像は hx / vy をスクロール快照経由で読む — 定常スクロールフレームはここで
+     * 何も確保しない。
+     */
+    const layersFor = useCallback(
+        (hx: number, vy: number): LayerCtx[] => {
+            const handle = handleRef.current
+            const frozen = handle?.getFrozenSize() ?? { cols: 0, width: 0, rows: 0, height: 0 }
+            const viewport = handle?.getViewportSize()
+            const bodyWidth = viewport?.width ?? -1
+            const bodyHeight = viewport?.height ?? -1
+            // スクロール快照の鮮度書き (キャッシュ済み写像の読み先 — 記述子は hx / vy 非依存)
+            const scroll = scrollSnapshotRef.current
+            scroll.x = hx
+            scroll.y = vy
+            let cache = splitCacheRef.current
+            if (cache === null || cache.frozenCols !== frozen.cols || cache.frozenWidth !== frozen.width || cache.frozenRows !== frozen.rows || cache.frozenHeight !== frozen.height || cache.bodyWidth !== bodyWidth || cache.bodyHeight !== bodyHeight) {
+                // 幾何が変わったときだけ記述子を再構築 (最熱経路の毎 repaint 閉包 / spread / 配列確保を
+                // 断つ GC 圧対策)。x 軸分割は非凍結が主帯 1 本、凍結は 凍結帯 [0, W_F) + スクロール帯
+                // [W_F, →) — y 軸も同型
+                const xSplits: AxisSplit<XSplitStyle>[] =
+                    frozen.cols <= 0
+                        ? [{ kind: "m", map: (treeX) => treeX - scroll.x, clamp: bodyWidth, style: X_MAIN_STYLE }]
+                        : [
+                              { kind: "f", map: (treeX) => treeX, clamp: frozen.width, style: { left: "0px", width: `${frozen.width}px`, right: "" } },
+                              { kind: "s", map: (treeX) => treeX - scroll.x - frozen.width, clamp: Math.max(0, bodyWidth - frozen.width), style: { left: `${frozen.width}px`, right: "0px", width: "" } },
+                          ]
+                const ySplits: AxisSplit<YSplitStyle>[] =
+                    frozen.rows <= 0
+                        ? [{ kind: "m", map: (treeY) => treeY - scroll.y, clamp: bodyHeight, style: Y_MAIN_STYLE }]
+                        : [
+                              { kind: "f", map: (treeY) => treeY, clamp: frozen.height, style: { top: "0px", height: `${frozen.height}px`, bottom: "" } },
+                              { kind: "s", map: (treeY) => treeY - scroll.y - frozen.height, clamp: Math.max(0, bodyHeight - frozen.height), style: { top: `${frozen.height}px`, bottom: "0px", height: "" } },
+                          ]
+                const ctxs: LayerCtx[] = []
+                for (const xs of xSplits) {
+                    for (const ys of ySplits) {
+                        ctxs.push({ nodes: nodeSetFor(`${xs.kind}${ys.kind}`), mapX: xs.map, clampWidth: xs.clamp, xStyle: xs.style, mapY: ys.map, clampHeight: ys.clamp, yStyle: ys.style })
+                    }
+                }
+                cache = { frozenCols: frozen.cols, frozenWidth: frozen.width, frozenRows: frozen.rows, frozenHeight: frozen.height, bodyWidth, bodyHeight, ctxs }
+                splitCacheRef.current = cache
+            }
+            for (const ctx of cache.ctxs) {
+                // ヒールは毎呼び (遅延 attach / 象限切替の新コンテナへも形状が届く — 同値抑止つき)
+                healContainer(ctx.nodes.container, ctx.xStyle, ctx.yStyle)
+                // 帯セグメントの主軸サイズはコンテナと同じ契機でヒール (§2.4 — 空プールなら無書込)
+                healLayerBands(ctx.nodes, ctx.clampWidth, ctx.clampHeight)
+            }
+            return cache.ctxs
+        },
+        [handleRef, nodeSetFor, healContainer, healLayerBands],
+    )
+    /**
+     * Stable ref-callback set for one layer (❗ identity-stable via useMemo — a per-render
+     * factory would make React detach/re-attach every render, clearing the fill pool while its
+     * DOM nodes survive and duplicating fills on the next repaint).
+     * 層 1 つぶんの安定 ref コールバック束 (❗ useMemo で identity 安定 — 毎レンダー生成だと
+     * React が毎回 detach / attach し、プールだけが空になって DOM ノードが残り、次の repaint で
+     * 塗りが二重化する)。
+     */
+    const makeLayerRefs = useCallback(
+        (key: string) => {
+            const nodes = () => nodeSetFor(key)
+            return {
+                container: (el: HTMLDivElement | null) => {
+                    const n = nodes()
+                    n.container = el
+                    if (el === null) {
+                        n.fillPool.length = 0
+                        // 帯もコンテナごと退役 (孤児プールの幽霊塗り防止 — fill プールと同型)
+                        n.bandPool.length = 0
+                        n.dragBand = null
+                        n.bandClampWidth = -1
+                        n.bandClampHeight = -1
+                    }
+                },
+                active: (el: HTMLDivElement | null) => {
+                    nodes().active = el
+                },
+                dragRect: (el: HTMLDivElement | null) => {
+                    nodes().dragRect = el
+                },
+                marquee: (el: HTMLDivElement | null) => {
+                    nodes().marquee = el
+                },
+                fillPreview: (el: HTMLDivElement | null) => {
+                    nodes().fillPreview = el
+                },
+                resizeGuide: (el: HTMLDivElement | null) => {
+                    nodes().resizeGuide = el
+                },
+            }
+        },
+        [nodeSetFor],
+    )
+    // 象限キーごとに identity 安定な ref 束を用意 (空 deps — 毎レンダー生成だと React が detach /
+    // attach してプールが空になり塗りが二重化する)。JSX は実効 F / R に応じて必要な象限だけ描く
+    const quadRefs = useMemo(() => Object.fromEntries(QUADRANT_KEYS.map((key) => [key, makeLayerRefs(key)])) as Record<string, ReturnType<typeof makeLayerRefs>>, [makeLayerRefs])
+    // render 面の実効 F / W_F (JSX 構造判定 — 機械の鮮度読みはハンドル §7-4)
+    const effectiveFrozenCols = Math.min(Math.max(0, frozenCols), colAxis.count)
+    const overlayFrozenWidth = frozenWidthOf(colAxis, effectiveFrozenCols)
+    const effectiveFrozenRows = Math.min(Math.max(0, frozenRows), rowAxis.count)
+    const overlayFrozenHeight = frozenHeightOf(rowAxis, effectiveFrozenRows)
+    // 生存中のドラッグ矩形レンジ (null = 非表示)。writeDragFrame が書き、repaintOverlay がスクロール
+    // 追随の再配置に読む — ドラッグ中ポインタ静止のままホイールすると、fill / アクティブ枠だけが
+    // onScroll repaint で動き矩形が取り残される desync の対策
+    const liveDragRangeRef = useRef<CellRange | null>(null)
+    /** Mode of the live drag rect (read by the scroll-follow repaint — bands follow add / subtract only). / ライブドラッグ矩形のモード (スクロール追随 repaint が読む — 帯は add / subtract だけ)。 */
+    const liveDragModeRef = useRef<DragFrameMode>("add")
+    const editingRef = useRef(editing)
+    editingRef.current = editing
+    /** Last written editing-attribute state (same-value setAttribute suppression). / 直近書込の編集属性状態 (同値 setAttribute 抑止)。 */
+    const lastEditingAttrRef = useRef(false)
+
+    // シンクは共有 sinkRef と wheel bridge の RefCallback の 2 消費者を持つ唯一の要素 — マージ ref
+    const bridgeRef = useWheelBridge(handleRef, { enableBridge: !editing })
+    const mergedSinkRef = useCallback(
+        (el: HTMLTextAreaElement | null) => {
+            sinkRef.current = el
+            // bridge の戻り値 (クリーンアップ) をそのまま返す — useWheelBridge の正準形 (React 19)
+            return bridgeRef(el)
+        },
+        [sinkRef, bridgeRef],
+    )
+
+    /** Raw quadrant-local edges of a range (both axes through the layer's maps). / レンジの象限局所の生の辺 (両軸とも層の写像経由)。 */
+    const layerEdgesOf = useCallback(
+        (range: CellRange, ctx: LayerCtx): { top: number; bottom: number; left: number; right: number } => ({
+            top: ctx.mapY(rowAxis.offsetOf(range.startRow)),
+            bottom: ctx.mapY(rowAxis.offsetOf(range.endRow) + rowAxis.sizeOf(range.endRow)),
+            left: ctx.mapX(colAxis.offsetOf(range.startCol)),
+            right: ctx.mapX(colAxis.offsetOf(range.endCol) + colAxis.sizeOf(range.endCol)),
+        }),
+        [rowAxis, colAxis],
+    )
+
+    /** Logical range to a clamped QUADRANT-local rect (null = fully offscreen for this quadrant). / 論理レンジ → 象限局所の矩形 (null = この象限で完全画面外)。 */
+    const rangeToLayerRect = useCallback(
+        (range: CellRange, ctx: LayerCtx): ViewportRect | null => {
+            // 両軸とも象限のクランプ範囲で判定 (v0.6 — y も x と対称に mapY / clampHeight で写す)
+            if (ctx.clampHeight <= 0 || ctx.clampWidth <= 0) {
+                return null
+            }
+            const { top, bottom, left, right } = layerEdgesOf(range, ctx)
+            // 可視域 ± 1 画面マージンでクランプ (列 / 行全選択 = 24M px 級も画面サイズの div になる)
+            const clampTop = -ctx.clampHeight * CLAMP_MARGIN_SCREENS
+            const clampBottom = ctx.clampHeight * (1 + CLAMP_MARGIN_SCREENS)
+            const clampLeft = -ctx.clampWidth * CLAMP_MARGIN_SCREENS
+            const clampRight = ctx.clampWidth * (1 + CLAMP_MARGIN_SCREENS)
+            if (bottom < clampTop || top > clampBottom || right < clampLeft || left > clampRight) {
+                return null // 完全に画面外 — DOM を触らない
+            }
+            const t = Math.max(top, clampTop)
+            const l = Math.max(left, clampLeft)
+            return { top: t, left: l, width: Math.min(right, clampRight) - l, height: Math.min(bottom, clampBottom) - t }
+        },
+        [layerEdgesOf],
+    )
+
+    /**
+     * Logical range to the band rect of a quadrant (§2.4): every edge is clamped into the ± 1
+     * screen margin but a range off-screen on ONE axis still yields a rect — its row band must
+     * keep covering the viewport (Excel keeps the row highlight when the selection scrolls out).
+     * Null only when the quadrant has no extent.
+     * 論理レンジ → 象限の帯矩形 (§2.4): 各辺を ± 1 画面マージンへクランプするが、片軸だけ画面外の
+     * レンジも矩形を返す — 行帯は viewport を覆い続けなければならない (Excel は選択が画面外へ出ても行の
+     * 強調を保つ)。null は象限に範囲が無いときだけ。
+     */
+    const rangeToBandRect = useCallback(
+        (range: CellRange, ctx: LayerCtx): ViewportRect | null => {
+            if (ctx.clampHeight <= 0 || ctx.clampWidth <= 0) {
+                return null
+            }
+            const edges = layerEdgesOf(range, ctx)
+            // 各辺を独立にクランプ (完全画面外でも幅 0 / 高さ 0 の矩形として位置は保つ)
+            const clampTop = -ctx.clampHeight * CLAMP_MARGIN_SCREENS
+            const clampBottom = ctx.clampHeight * (1 + CLAMP_MARGIN_SCREENS)
+            const clampLeft = -ctx.clampWidth * CLAMP_MARGIN_SCREENS
+            const clampRight = ctx.clampWidth * (1 + CLAMP_MARGIN_SCREENS)
+            const t = Math.min(Math.max(edges.top, clampTop), clampBottom)
+            const l = Math.min(Math.max(edges.left, clampLeft), clampRight)
+            return { top: t, left: l, width: Math.min(Math.max(edges.right, clampLeft), clampRight) - l, height: Math.min(Math.max(edges.bottom, clampTop), clampBottom) - t }
+        },
+        [layerEdgesOf],
+    )
+
+    /** Active highlight state, or null when the capability is absent / every switch is off. / 有効な強調状態 (能力なし / 全 off は null)。 */
+    const activeHighlight = useCallback((): HighlightState | null => {
+        // 能力分岐: highlightRef 未指定は v0.7 恒等 (帯なし)
+        if (highlightRef === undefined) {
+            return null
+        }
+        const highlight = highlightRef.current
+        return highlight.row || highlight.column || highlight.intersection ? highlight : null
+    }, [highlightRef])
+
+    /** Inserts a band group under the layer's fills (before the first fill, else before the active frame). / 帯組を層の fill の下へ挿入 (先頭 fill の手前、無ければアクティブ枠の手前)。 */
+    const insertBandGroup = useCallback((container: HTMLDivElement, nodes: LayerNodes, group: BandNodes) => {
+        const before = nodes.fillPool.length > 0 ? nodes.fillPool[0] : nodes.active
+        for (const node of bandNodeList(group)) {
+            container.insertBefore(node, before)
+        }
+    }, [])
+
+    /** Places one band group for a range in a layer (hidden when the quadrant has no extent). / 層内のレンジ 1 つに帯組を配置 (象限に範囲が無ければ消灯)。 */
+    const placeBandGroup = useCallback(
+        (group: BandNodes, range: CellRange, ctx: LayerCtx, highlight: HighlightState) => {
+            const rect = rangeToBandRect(range, ctx)
+            if (rect === null) {
+                hideBandNodes(group)
+                return
+            }
+            // 全列スパン (行ヘッダー選択) も全行スパン (列ヘッダー選択) も両族省略 — 交点だけ残す
+            placeBandSegments(group, rect, ctx, highlight, isWholeRows(range, colAxis.count) || isWholeCols(range, rowAxis.count))
+        },
+        [rangeToBandRect, rowAxis, colAxis],
+    )
+
+    /**
+     * Per-layer band pool sync of one repaint (§2.4): the pool shrinks to the band range count
+     * (retired groups are removed — all off ⇒ zero band nodes = the v0.7 DOM identity), the
+     * drag band is removed when highlighting is off, and each band range gets a group (created
+     * with the layer's clamp extents, inserted under the fills) placed for this frame.
+     * 1 repaint の層毎帯プール同期 (§2.4): プールは帯レンジ数へ収縮 (退役組は除去 — 全 off ⇒ 帯ノード 0
+     * = v0.7 の DOM 恒等)、強調 off ならドラッグ帯も除去、各帯レンジは組 (層のクランプ範囲で生成し fill
+     * の下へ挿入) をこのフレームぶん配置する。
+     */
+    const syncLayerBands = useCallback(
+        (ctx: LayerCtx, container: HTMLDivElement, bandRanges: readonly CellRange[], highlight: HighlightState | null) => {
+            const pool = ctx.nodes.bandPool
+            while (pool.length > bandRanges.length) {
+                const retired = pool.pop()
+                if (retired !== undefined) {
+                    removeBandNodes(retired)
+                }
+            }
+            if (highlight === null) {
+                if (ctx.nodes.dragBand !== null) {
+                    removeBandNodes(ctx.nodes.dragBand)
+                    ctx.nodes.dragBand = null
+                }
+                return
+            }
+            for (let i = 0; i < bandRanges.length; i += 1) {
+                let group = pool[i]
+                if (group === undefined) {
+                    group = createBandNodes()
+                    // 新規セグメントは追加時に層のクランプ範囲を受ける (以後は heal パスだけが書く)
+                    healBandGeometry(group, ctx.clampWidth, ctx.clampHeight)
+                    insertBandGroup(container, ctx.nodes, group)
+                    pool.push(group)
+                }
+                placeBandGroup(group, bandRanges[i], ctx, highlight)
+            }
+        },
+        [insertBandGroup, placeBandGroup],
+    )
+
+    /** Places (or hides) the live drag rect's band group in one layer. / ライブドラッグ矩形の帯組を層 1 つに配置 (または消灯)。 */
+    const placeDragBand = useCallback(
+        (ctx: LayerCtx, range: CellRange | null, highlight: HighlightState | null) => {
+            const container = ctx.nodes.container
+            if (container === null) {
+                return
+            }
+            if (range === null || highlight === null) {
+                if (ctx.nodes.dragBand !== null) {
+                    hideBandNodes(ctx.nodes.dragBand)
+                }
+                return
+            }
+            let group = ctx.nodes.dragBand
+            if (group === null) {
+                group = createBandNodes()
+                healBandGeometry(group, ctx.clampWidth, ctx.clampHeight)
+                insertBandGroup(container, ctx.nodes, group)
+                ctx.nodes.dragBand = group
+            }
+            placeBandGroup(group, range, ctx, highlight)
+        },
+        [insertBandGroup, placeBandGroup],
+    )
+
+    /** Applies a rect (or hides on null) to one resident node. / 常設ノード 1 個への矩形適用 (null は消灯)。 */
+    const applyRect = useCallback((node: HTMLDivElement | null, rect: ViewportRect | null) => {
+        if (node === null) {
+            return
+        }
+        if (rect === null) {
+            node.style.display = "none"
+            return
+        }
+        node.style.display = "block"
+        node.style.transform = `translate(${rect.left}px, ${rect.top}px)`
+        node.style.width = `${rect.width}px`
+        node.style.height = `${rect.height}px`
+    }, [])
+
+    /** Positions the resident drag-rect nodes (all quadrants) for a range at (vy, hx); add / subtract drags also carry their bands. / 常設矩形ノード (全象限) の配置。add / subtract のドラッグは帯も伴う。 */
+    const positionDragRect = useCallback(
+        (range: CellRange, vy: number, hx: number, mode: DragFrameMode) => {
+            // 参照ドラッグ (point) は選択でないため帯を描かない
+            const highlight = mode === "point" ? null : activeHighlight()
+            for (const ctx of layersFor(hx, vy)) {
+                applyRect(ctx.nodes.dragRect, rangeToLayerRect(range, ctx))
+                placeDragBand(ctx, range, highlight)
+            }
+        },
+        [rangeToLayerRect, layersFor, applyRect, activeHighlight, placeDragBand],
+    )
+
+    /** Positions the fill-preview resident nodes (all quadrants). / fill プレビュー常設ノード (全象限) の配置。 */
+    const positionFillPreview = useCallback(
+        (range: CellRange | null, vy: number, hx: number) => {
+            for (const ctx of layersFor(hx, vy)) {
+                applyRect(ctx.nodes.fillPreview, range === null ? null : rangeToLayerRect(range, ctx))
+            }
+        },
+        [rangeToLayerRect, layersFor, applyRect],
+    )
+
+    /** Positions the resize guideline nodes (all quadrants — the line is a tree boundary each quadrant maps/clips). / ガイドライン (全象限 — 線は各象限が写像 / クリップする木境界)。 */
+    const positionResizeGuide = useCallback(
+        (guide: ResizeGuide | null, vy: number, hx: number) => {
+            for (const ctx of layersFor(hx, vy)) {
+                const node = ctx.nodes.resizeGuide
+                if (node === null) {
+                    continue
+                }
+                if (guide === null) {
+                    node.style.display = "none"
+                    continue
+                }
+                node.style.display = "block"
+                if (guide.axis === "col") {
+                    node.style.transform = `translate(${ctx.mapX(guide.position)}px, 0px)`
+                    node.style.width = "1px"
+                    node.style.height = "100%"
+                } else {
+                    // 行線は各象限の mapY で写す (v0.6 — 凍結行帯では静的、スクロール帯では −vy−H_F)
+                    node.style.transform = `translate(0px, ${ctx.mapY(guide.position)}px)`
+                    node.style.width = "100%"
+                    node.style.height = "1px"
+                }
+            }
+        },
+        [layersFor],
+    )
+
+    /**
+     * Places one popover anchor node on its cell with the fill handle's frozen-partition mapping
+     * (§2.5): hidden without a cell, when the cell's origin lies beyond the viewport's right /
+     * bottom edge, or when a scroll-axis cell's origin sits under the frozen band — with no
+     * frozen tracks the band is the axis origin, so a cell scrolled past the left / top edge is
+     * hidden too (the sink's visibility rule); otherwise `transform` per frame and the cell size
+     * only when it changes (dataset signature). "Hidden" is `ANCHOR_HIDDEN_CLIP` (`clip-path`),
+     * never `display: none` / `visibility: hidden`: the anchor may hold a mounted, FOCUSED editor
+     * (the note textarea) while it hides, and un-rendering it would trigger the browser's focus
+     * fixup — the editor's focus-leave rule would then save-and-close, whereas plan §5.7-13 is
+     * hide-and-restore. A clipped anchor paints nothing and takes no hits (clip-path clips hit
+     * testing too), so it vanishes under the frozen band exactly as `display: none` did, and
+     * clearing the same property on the next visible frame brings it back with its editor,
+     * draft and focus intact. A closed anchor is additionally `inert` (PopoverLayer), so the
+     * closed-layer DOM is unchanged by this rule.
+     * ポップオーバーアンカー 1 ノードを fill ハンドルと同じ凍結分割写像でセルへ配置 (§2.5): セルなし /
+     * セル原点が viewport の右 / 下端の外 / スクロール軸のセル原点が凍結帯の下 (凍結なしなら帯 = 軸原点
+     * なので左 / 上へ出たセルも同じ) は非表示 (シンクの可視規則と同型)。それ以外は `transform` を
+     * 毎フレーム、セル寸法は変化時だけ (dataset 署名)。「非表示」は `ANCHOR_HIDDEN_CLIP` (`clip-path`)
+     * であり `display: none` / `visibility: hidden` ではない: アンカーはマウント済みで**フォーカス中**の
+     * エディタ (note の textarea) を抱えたまま隠れ得るので、描画から外すとブラウザの focus fixup が走り
+     * エディタの focus-leave 規則が保存して閉じてしまう (計画 §5.7-13 は隠して戻す)。clip した
+     * アンカーは何も描かずヒットも取らず (clip-path はヒットテストも切る) `display: none` と同じく
+     * 凍結帯の下へ消え、次の可視フレームで同じプロパティを空へ戻せばエディタ・下書き・フォーカスを
+     * 保ったまま戻る。閉じたアンカーは加えて `inert` (PopoverLayer) なので閉じた層の DOM は不変。
+     */
+    const placeAnchor = useCallback(
+        (node: HTMLDivElement | null, cell: CellCoord | null, vy: number, hx: number, frozen: { cols: number; width: number; rows: number; height: number }, bodyWidth: number, viewportH: number) => {
+            if (node === null) {
+                return
+            }
+            if (cell === null || viewportH <= 0 || bodyWidth <= 0) {
+                node.style.clipPath = ANCHOR_HIDDEN_CLIP
+                return
+            }
+            const rawTop = rowToViewportY(rowAxis, cell.row, vy, frozen.rows)
+            const rawLeft = colToViewportX(colAxis, cell.col, hx, frozen.cols)
+            // 原点が viewport の右 / 下の外、またはスクロール軸のセルが凍結帯の下 (凍結なしは左 / 上の外) ⇒ 非表示
+            const beyondViewport = rawLeft >= bodyWidth || rawTop >= viewportH
+            const underFrozenCol = cell.col >= frozen.cols && rawLeft < frozen.width
+            const underFrozenRow = cell.row >= frozen.rows && rawTop < frozen.height
+            if (beyondViewport || underFrozenCol || underFrozenRow) {
+                node.style.clipPath = ANCHOR_HIDDEN_CLIP
+                return
+            }
+            // 可視: clip を外す (display / visibility には触れない — フォーカス中のエディタを壊さない)
+            node.style.clipPath = ""
+            node.style.transform = `translate(${rawLeft}px, ${rawTop}px)`
+            // 寸法は変化時だけ (署名比較 — 毎フレームは transform のみ)
+            const width = colAxis.sizeOf(cell.col)
+            const height = rowAxis.sizeOf(cell.row)
+            const signature = `${width} ${height}`
+            if (node.dataset.aqspAnchorSig !== signature) {
+                node.dataset.aqspAnchorSig = signature
+                node.style.width = `${width}px`
+                node.style.height = `${height}px`
+            }
+        },
+        [rowAxis, colAxis],
+    )
+
+    /**
+     * Places both popover anchors for one frame (ADR-15) — a capability step: without
+     * `popoverAnchors` no anchor node is touched (the v0.7 identity); an absent anchor ref is
+     * skipped by `placeAnchor`.
+     * ポップオーバーアンカー 2 つを 1 フレームぶん配置 (ADR-15) — 能力ステップ: `popoverAnchors` 未指定
+     * ならアンカーノードに一切触れない (v0.7 恒等)、アンカー ref の欠落は `placeAnchor` が飛ばす。
+     */
+    const placePopoverAnchors = useCallback(
+        (handle: VirtualGridHandle, vy: number, hx: number) => {
+            if (popoverAnchors === undefined) {
+                return
+            }
+            const anchors = popoverAnchors.current
+            const { width: bodyWidth, height: viewportH } = handle.getViewportSize()
+            const frozen = handle.getFrozenSize()
+            placeAnchor(interactiveAnchorRef === undefined ? null : interactiveAnchorRef.current, anchors.interactive, vy, hx, frozen, bodyWidth, viewportH)
+            placeAnchor(tipAnchorRef === undefined ? null : tipAnchorRef.current, anchors.tip, vy, hx, frozen, bodyWidth, viewportH)
+        },
+        [popoverAnchors, interactiveAnchorRef, tipAnchorRef, placeAnchor],
+    )
+
+    /**
+     * The single repaint function (both paths — §6.7.2-3). No getBoundingClientRect inside:
+     * viewport metrics come from cached numbers only.
+     * 唯一の再描画関数 (両経路共有)。内部で gBCR を呼ばない (キャッシュ数値のみ)。
+     */
+    const repaintOverlay = useCallback(() => {
+        const overlay = overlayRef.current
+        const handle = handleRef.current
+        if (overlay === null || handle === null) {
+            return
+        }
+        // 両軸ともハンドルの同期読み (§7-4 — ストアに位置は存在しない)
+        const position = handle.getScrollPosition()
+        const vy = Math.max(0, position.y)
+        const hx = Math.max(0, position.x)
+        // 命令読み (props docstring 参照) — シート切替コミットでも常にリセット済みの最新確定選択
+        const state = getSelection()
+
+        // 強調帯の対象レンジ (能力なし / 全 off は空 — 確保もしない)
+        const highlight = activeHighlight()
+        const bandRanges = highlight === null ? NO_RANGES : state.ranges.slice(-BAND_RANGE_CAP)
+
+        // 確定塗り (fills) — 層ごとの常設プール (ref 配列) を使い回す (毎 repaint の DOM 生成 /
+        // クエリを避ける)。F = 0 は主プール単層で従来恒等
+        const layers = layersFor(hx, vy)
+        for (const ctx of layers) {
+            const container = ctx.nodes.container
+            if (container === null) {
+                continue
+            }
+            const fills = ctx.nodes.fillPool
+            for (let i = 0; i < Math.max(fills.length, state.ranges.length); i += 1) {
+                let node = fills[i]
+                if (node === undefined) {
+                    node = document.createElement("div")
+                    node.className = "aqsp-selection-fill"
+                    node.setAttribute("data-aqsp-fill", "")
+                    // 静的ノード群 (アクティブ枠 / ドラッグ矩形 / マーキー / シンク) の手前へ挿入 —
+                    // append だと DOM 順でシンクより上に描かれ、Phase 3 のセル面積エディタが半透明
+                    // fill の下に沈む
+                    container.insertBefore(node, ctx.nodes.active)
+                    fills.push(node)
+                }
+                const range = state.ranges[i]
+                const rect = range === undefined ? null : rangeToLayerRect(range, ctx)
+                if (rect === null) {
+                    node.style.display = "none"
+                } else {
+                    node.style.display = "block"
+                    node.style.transform = `translate(${rect.left}px, ${rect.top}px)`
+                    node.style.width = `${rect.width}px`
+                    node.style.height = `${rect.height}px`
+                }
+            }
+            // プールを生存レンジ数へ収縮 (多レンジ選択の残骸ノードを毎 repaint 走査し続けない —
+            // 最熱ループは常に live 選択規模に比例させる)
+            while (fills.length > state.ranges.length) {
+                fills.pop()?.remove()
+            }
+
+            // アクティブセル枠 (常設ノードは ref 直読み — dragRect と同じ規律)
+            applyRect(ctx.nodes.active, rangeToLayerRect(makeRange(state.active, state.active), ctx))
+
+            // 強調帯 (v0.8 §2.4): 末尾 BAND_RANGE_CAP レンジに 5 ノードずつ、fill の下。全 off は
+            // プール縮退 (ノード除去) で帯 0 = v0.7 恒等
+            syncLayerBands(ctx, container, bandRanges, highlight)
+        }
+
+        // クリップマーキー (copy / cut 装填中のみ — v0.3.2 でマーチングアンツ統一)。層ごとに配置
+        // (署名 / kind 抑止は層ノード単位 — dataset に直近値を持つ)。foreign (旧シートの cut) は
+        // 描かない — レンジは切替前の座標で、新軸では意味を持たない (v0.8 §4.2.5)
+        const armed = getClip()
+        const clip = armed === null || armed.foreign ? null : armed
+        for (const ctx of layers) {
+            const marquee = ctx.nodes.marquee
+            if (marquee === null) {
+                continue
+            }
+            const rect = clip === null ? null : rangeToLayerRect(clip.range, ctx)
+            if (rect === null) {
+                marquee.style.display = "none"
+            } else {
+                marquee.style.display = "block"
+                marquee.style.transform = `translate(${rect.left}px, ${rect.top}px)`
+                marquee.style.width = `${rect.width}px`
+                marquee.style.height = `${rect.height}px`
+                // 端クランプ (R1(H) blocking → R2(H) で漸進化): 外側 3px のアンツ帯は層の
+                // overflow: hidden に切られるため、各辺の余白ぶんだけ外へ出す (-min(3, max(0,
+                // 余白))px)。二値クランプだと閾値跨ぎで帯が 3px 跳ね、境界 3px 圏の静止位置でも
+                // 同色重なりが再発する — 漸進なら連続で、原点 (A1) は境界上に載る (Excel 同型)。
+                // 整数 floor で文字列が安定し、上・左は絶対にはみ出さない。横の余白基準は層の
+                // クランプ幅 (v0.5 — F = 0 は bodyWidth で従来恒等)。署名比較が同値 setProperty を抑止
+                // 上下 / 左右とも象限のクランプ範囲基準 (v0.6 — outBottom を viewportH でなく
+                // ctx.clampHeight へ。凍結行帯のマーキー帯が帯下限で正しく切られる。横は従来どおり)
+                const outTop = clipMarqueeOutset(rect.top)
+                const outLeft = clipMarqueeOutset(rect.left)
+                const outBottom = clipMarqueeOutset(ctx.clampHeight - (rect.top + rect.height))
+                const outRight = clipMarqueeOutset(ctx.clampWidth - (rect.left + rect.width))
+                const signature = `${outTop} ${outRight} ${outBottom} ${outLeft}`
+                if (signature !== marquee.dataset.aqspOutsetSig) {
+                    marquee.dataset.aqspOutsetSig = signature
+                    marquee.style.setProperty("--aqsp-clip-outset-top", outTop)
+                    marquee.style.setProperty("--aqsp-clip-outset-right", outRight)
+                    marquee.style.setProperty("--aqsp-clip-outset-bottom", outBottom)
+                    marquee.style.setProperty("--aqsp-clip-outset-left", outLeft)
+                }
+            }
+            // kind 属性はスクロール毎フレームの repaint で書かれる — 同値 setAttribute 抑止
+            // (v0.1 の同値再書込規律。テスト / スタイル分岐のフックで、見た目は両種同一の Excel 準拠)
+            const kind = rect === null ? null : (clip?.kind ?? null)
+            const lastKind = marquee.dataset.aqspClipKindLast ?? null
+            if (kind !== lastKind) {
+                if (kind === null) {
+                    delete marquee.dataset.aqspClipKindLast
+                    marquee.removeAttribute("data-aqsp-clip-kind")
+                } else {
+                    marquee.dataset.aqspClipKindLast = kind
+                    marquee.setAttribute("data-aqsp-clip-kind", kind)
+                }
+            }
+        }
+
+        // 生存中ドラッグ矩形のスクロール追随: ポインタ静止のままホイールすると fill / 枠だけが
+        // 動いて矩形が取り残される — writer は writeDragFrame と共有の positionDragRect 1 本
+        if (liveDragRangeRef.current !== null) {
+            positionDragRect(liveDragRangeRef.current, vy, hx, liveDragModeRef.current)
+        }
+
+        // リサイズガイドライン / fill プレビューのスクロール追随 (§7.2 / §8.2 — writer と共有の
+        // positioner 1 本)
+        if (liveResizeGuideRef.current !== null) {
+            positionResizeGuide(liveResizeGuideRef.current, vy, hx)
+        }
+        if (liveFillPreviewRef.current !== null) {
+            positionFillPreview(liveFillPreviewRef.current, vy, hx)
+        }
+
+        // fill ハンドル (§8.1)。飛行中は可視条件の適用を凍結する — エッジスクロールで隅が画面外へ
+        // 出た瞬間に capture ノードが display:none になり lostpointercapture で正当なドラッグが
+        // 死ぬ事故の遮断
+        const fillHandle = fillHandleNodeRef.current
+        if (fillHandle !== null && !getIsFillDragging()) {
+            const { width: bodyWidth, height: viewportH } = handle.getViewportSize()
+            const tail = state.ranges[state.ranges.length - 1]
+            // 単一レンジ + 非編集 + ドラッグ非飛行 (§8.1)。fill 自身の飛行はこのブロックの外側の
+            // 凍結ゲートが既に除外している — ここに来た時点で isFillDragging は常に false のため
+            // 合成値の素読みで足りる
+            const eligible = state.ranges.length === 1 && !editingRef.current && !getIsDraggingAny()
+            if (!eligible || viewportH <= 0 || bodyWidth <= 0) {
+                fillHandle.style.display = "none"
+            } else {
+                // 行 / 列とも凍結パーティション順写像 (v0.6 / v0.5 計画 §2)。スクロール軸の隅が
+                // 凍結帯の下へ潜った場合は不可視 (minLeft = W_F / minTop = H_F — 凍結軸自身の隅は
+                // 0 が下限)
+                const frozen = handle.getFrozenSize()
+                const endColIsFrozen = tail.endCol < frozen.cols
+                const endRowIsFrozen = tail.endRow < frozen.rows
+                const left = colToViewportX(colAxis, tail.endCol, hx, frozen.cols) + colAxis.sizeOf(tail.endCol)
+                const top = rowToViewportY(rowAxis, tail.endRow, vy, frozen.rows) + rowAxis.sizeOf(tail.endRow)
+                const minLeft = endColIsFrozen ? 0 : frozen.width
+                const minTop = endRowIsFrozen ? 0 : frozen.height
+                if (top <= minTop || top > viewportH || left <= minLeft || left > bodyWidth) {
+                    fillHandle.style.display = "none" // 右下隅が viewport 外 / 凍結帯の下 (§8.1)
+                } else {
+                    fillHandle.style.display = "block"
+                    fillHandle.style.transform = `translate(${left - FILL_HANDLE_SIZE + 1}px, ${top - FILL_HANDLE_SIZE + 1}px)`
+                }
+            }
+        }
+
+        // シンク位置: active セルへ追随、画面外ならビューポート内縁へクランプ (display:none 禁止 —
+        // フォーカスと IME が死ぬ)。編集中はセル面積、idle は 1px (§6.7.2-4)
+        const sink = sinkRef.current
+        if (sink !== null) {
+            const a = state.active
+            const { width: bodyWidth, height: viewportH } = handle.getViewportSize()
+            // 行 / 列とも凍結パーティション順写像 (v0.6 / v0.5 計画 §2 — 凍結軸の active は静的座標)
+            const sinkFrozen = handle.getFrozenSize()
+            const rawTop = rowToViewportY(rowAxis, a.row, vy, sinkFrozen.rows)
+            const rawLeft = colToViewportX(colAxis, a.col, hx, sinkFrozen.cols)
+            const top = viewportH > 0 ? Math.min(Math.max(rawTop, 0), Math.max(0, viewportH - 1)) : 0
+            const left = bodyWidth > 0 ? Math.min(Math.max(rawLeft, 0), Math.max(0, bodyWidth - 1)) : 0
+            sink.style.top = `${top}px`
+            sink.style.left = `${left}px`
+            if (editingRef.current) {
+                sink.style.width = `${colAxis.sizeOf(a.col)}px`
+                sink.style.height = `${rowAxis.sizeOf(a.row)}px`
+                // セル連続の縦位置: セル本文は flex 中央 = (行高 − 下罫 1 − 行箱) / 2。固定値は既定
+                // 24px でしか一致しない (R1(E) 実証 — defaultRowHeight / 行リサイズで段差)。行箱と
+                // 垂直揃えはエディタ塗り (v0.8 §2.3 — 能力なしは IDLE = 13px 中央で v0.7 恒等)
+                sink.style.paddingTop = `${sinkPaddingTop(rowAxis.sizeOf(a.row), editPaintRef === undefined ? IDLE_EDIT_PAINT : editPaintRef.current)}px`
+            } else {
+                sink.style.width = "1px"
+                sink.style.height = "1px"
+                sink.style.paddingTop = "0px"
+            }
+            // 編集セッションの可視化属性 (§6.7.2-4 補): 編集中だけシンクを可視エディタ化する
+            // (常時 opacity 0 では本文もキャレットも見えない — v0.3 要望改善)。**クランプ中は
+            // 可視化しない** — active がビューポート外へスクロールした間、内縁固定の等身大
+            // エディタが無関係なセルの上に描かれる (R1(E) 実証。Excel はセルと一緒に画面外へ)。
+            // セッションと IME は生存し、スクロールバックで再可視化される。repaint は高頻度の
+            // ため同値 setAttribute は抑止する (v0.1 の同値再書込規律)
+            // スクロール列の active が凍結帯の下へ潜った場合もエディタは降ろす (誤位置描画の
+            // 遮断 — 「画面外スクロールで降ろす」既存規律の凍結境界版)
+            // スクロール軸の active が凍結帯の下へ潜った場合もエディタを降ろす (両軸)
+            const underFrozenCol = a.col >= sinkFrozen.cols && rawLeft < sinkFrozen.width
+            const underFrozenRow = a.row >= sinkFrozen.rows && rawTop < sinkFrozen.height
+            const editorVisible = editingRef.current && rawTop === top && rawLeft === left && !underFrozenCol && !underFrozenRow
+            if (editorVisible !== lastEditingAttrRef.current) {
+                lastEditingAttrRef.current = editorVisible
+                if (editorVisible) {
+                    sink.setAttribute("data-aqsp-editing", "")
+                } else {
+                    sink.removeAttribute("data-aqsp-editing")
+                }
+            }
+        }
+
+        // ポップオーバーアンカー (v0.8 ADR-15): 能力があるときだけ 2 ノードをセルへ配置する
+        placePopoverAnchors(handle, vy, hx)
+    }, [
+        handleRef,
+        rangeToLayerRect,
+        layersFor,
+        applyRect,
+        positionDragRect,
+        positionResizeGuide,
+        positionFillPreview,
+        getClip,
+        getSelection,
+        getIsDraggingAny,
+        getIsFillDragging,
+        fillHandleNodeRef,
+        sinkRef,
+        rowAxis,
+        colAxis,
+        activeHighlight,
+        syncLayerBands,
+        editPaintRef,
+        placePopoverAnchors,
+    ])
+
+    /** Drag-rect direct writer (resident node — §6.4.3-5); mode is REQUIRED (§3.2 — a defaulted mode would let a future caller silently clear the subtract styling mid-flight); "point" paints the reference rect. / ドラッグ矩形の直書き。mode は必須引数 (§3.2 — 既定値は将来の呼び忘れを無音 clear に化けさせる)。"point" は参照矩形を描く。 */
+    const writeDragFrame = useCallback(
+        (range: CellRange | null, mode: DragFrameMode) => {
+            liveDragRangeRef.current = range
+            liveDragModeRef.current = mode
+            // 減算スタイル属性 (§3.2): null 呼びで必ず clear (消灯とスタイル残留遮断)。抑止は
+            // ノード単位の dataset (マーキーの aqspClipKindLast と同型 — R2 是正: コンポーネント
+            // 全域 ref だと層切替で再マウントした新ノードが同値スキップされ subtract 表示が落ちる)。
+            // オートスクロール tick の毎フレーム同値 setAttribute はノード単位でも抑止される
+            const effectiveMode = range === null ? "add" : mode
+            for (const ctx of layersFor(0, 0)) {
+                const modeNode = ctx.nodes.dragRect
+                if (modeNode === null) {
+                    continue
+                }
+                const lastMode = modeNode.dataset.aqspDragModeLast ?? "add"
+                if (effectiveMode !== lastMode) {
+                    modeNode.dataset.aqspDragModeLast = effectiveMode
+                    // subtract / point は属性で描き分け、add は属性なし (v0.7 恒等)
+                    if (effectiveMode === "add") {
+                        modeNode.removeAttribute("data-aqsp-drag-mode")
+                    } else {
+                        modeNode.setAttribute("data-aqsp-drag-mode", effectiveMode)
+                    }
+                }
+            }
+            const handle = handleRef.current
+            if (range === null || handle === null) {
+                for (const ctx of layersFor(0, 0)) {
+                    if (ctx.nodes.dragRect !== null) {
+                        ctx.nodes.dragRect.style.display = "none"
+                    }
+                    // ドラッグ矩形の帯も消灯 (null 呼びで必ず — 取り残し防止)
+                    placeDragBand(ctx, null, null)
+                }
+                return
+            }
+            const position = handle.getScrollPosition()
+            positionDragRect(range, Math.max(0, position.y), Math.max(0, position.x), mode)
+        },
+        [handleRef, positionDragRect, layersFor, placeDragBand],
+    )
+
+    /** Fill-preview direct writer (§8.2 — the fill machine + both fill autoscrollers write through the relay). / fill プレビューの直書き (fill 機械 + 軸別 2 スクローラーがリレー経由で書く)。 */
+    const writeFillFrame = useCallback(
+        (range: CellRange | null) => {
+            liveFillPreviewRef.current = range
+            const handle = handleRef.current
+            if (handle === null) {
+                // writeDragFrame の null 分岐と対称の消灯 (取り残しプレビューの防御 — 現状この
+                // 分岐はグリッド同時アンマウント時のみで実害なしだが、非対称は退行の温床)
+                for (const ctx of layersFor(0, 0)) {
+                    if (ctx.nodes.fillPreview !== null) {
+                        ctx.nodes.fillPreview.style.display = "none"
+                    }
+                }
+                return
+            }
+            const position = handle.getScrollPosition()
+            positionFillPreview(range, Math.max(0, position.y), Math.max(0, position.x))
+        },
+        [handleRef, positionFillPreview, layersFor],
+    )
+
+    /** Resize-guideline direct writer (§7.2 — useHeaderResize writes rAF-coalesced through the relay). / ガイドラインの直書き (useHeaderResize が rAF 合流で書く)。 */
+    const writeResizeGuide = useCallback(
+        (guide: ResizeGuide | null) => {
+            liveResizeGuideRef.current = guide
+            const handle = handleRef.current
+            if (handle === null) {
+                // writeDragFrame / writeFillFrame の null 分岐と対称の消灯 (3 writer 同型 —
+                // 到達はグリッド同時アンマウント時のみで実害なしだが、非対称は退行の温床)
+                for (const ctx of layersFor(0, 0)) {
+                    if (ctx.nodes.resizeGuide !== null) {
+                        ctx.nodes.resizeGuide.style.display = "none"
+                    }
+                }
+                return
+            }
+            const position = handle.getScrollPosition()
+            positionResizeGuide(guide, Math.max(0, position.y), Math.max(0, position.x))
+        },
+        [handleRef, positionResizeGuide, layersFor],
+    )
+
+    // 帯パレット (v0.8 §5): --aqsp-band-* は overlay ルートへ layout effect が書く唯一の書き手 —
+    // 毎フレームの repaint は決して書かない。能力なし (undefined) は書込 0 で CSS 既定のまま
+    useLayoutEffect(() => {
+        const overlay = overlayRef.current
+        if (overlay === null || highlightColors === undefined) {
+            return
+        }
+        overlay.style.setProperty("--aqsp-band-row", highlightColors.row)
+        overlay.style.setProperty("--aqsp-band-column", highlightColors.column)
+        overlay.style.setProperty("--aqsp-band-intersection", highlightColors.intersection)
+        overlay.style.setProperty("--aqsp-band-opacity", String(highlightColors.opacity))
+        // パレットの退役 (undefined へ戻る / identity 交代 / unmount) では変数を外し、style を v0.7 の形へ戻す
+        return () => {
+            overlay.style.removeProperty("--aqsp-band-row")
+            overlay.style.removeProperty("--aqsp-band-column")
+            overlay.style.removeProperty("--aqsp-band-intersection")
+            overlay.style.removeProperty("--aqsp-band-opacity")
+        }
+    }, [highlightColors])
+
+    // 登録 (所有点は Spreadsheet — §6.9-7)。React 経路の再描画 (§6.7.2-3 (a)) は分担所有:
+    // SelectionState 変化は Spreadsheet の layout effect ([selection] キー)、編集状態変化と
+    // 軸再構築 (repaintOverlay の identity 変化 = シート切替 / リサイズ) は下の effect。
+    // ここで毎レンダー repaint すると同一コミットで二重描画になるため登録のみ行う
+    useEffect(() => {
+        repaintRef.current = repaintOverlay
+        dragFrameRef.current = writeDragFrame
+        fillFrameRef.current = writeFillFrame
+        resizeGuideFrameRef.current = writeResizeGuide
+        return () => {
+            repaintRef.current = null
+            dragFrameRef.current = null
+            fillFrameRef.current = null
+            resizeGuideFrameRef.current = null
+        }
+    })
+    // editing 反転 (Phase 3 の F2 は選択不変でシンク面積だけ変わる) + 軸 / ストア identity 変化
+    // (repaintOverlay の deps) + 層分岐切替 (0 ↔ N トグル — 新コンテナは空でマウントされるため即
+    // 再塗りが必須) で描く — [selection] は Spreadsheet 側の担当。初回マウントでも走るが、その時点の
+    // グリッドは viewport 未計測 ({0,0} / range null — 計測は layout effect の setState で 1 レンダー
+    // 遅れる) で何も描かない: マウント時の A1 枠はグリッドの rAF 遅延 onScroll / onRangeChange 中継
+    // (Spreadsheet の repaintOverlay 呼び) が描く (post-B F2 実測)
+    useEffect(() => {
+        repaintOverlay()
+    }, [repaintOverlay, editing, effectiveFrozenCols, effectiveFrozenRows])
+
+    // シンクの mousedown ガード (idle の 1px 直クリックから armed 選択を守る — §4.2 ADR-4。
+    // 所有は SelectionOverlay — §6.10 の変異検証対象)
+    useEffect(() => {
+        const sink = sinkRef.current
+        if (sink === null) {
+            return
+        }
+        const handler = (event: MouseEvent) => onSinkMouseDown(event)
+        sink.addEventListener("mousedown", handler)
+        return () => sink.removeEventListener("mousedown", handler)
+    }, [sinkRef, onSinkMouseDown])
+
+    // ---- 象限 JSX の構築 (v0.6 計画 §3-4): 各軸の凍結種 × をデカルト積し、必要な象限だけ描く。
+    //      DOM 順は「後置 = 境界での描画上位」— 主 → 行凍結 → 列凍結 → コーナー の順で凍結ほど後置。
+    //      v0.5 互換の data-attr フック (main / frozen / scroll) を R = 0 の 3 象限へ温存する ----
+    const xKinds =
+        effectiveFrozenCols > 0
+            ? ([
+                  { k: "f", style: { left: 0, width: overlayFrozenWidth } },
+                  { k: "s", style: { left: overlayFrozenWidth, right: 0 } },
+              ] as const)
+            : ([{ k: "m", style: { left: 0, right: 0 } }] as const)
+    const yKinds =
+        effectiveFrozenRows > 0
+            ? ([
+                  { k: "f", style: { top: 0, height: overlayFrozenHeight } },
+                  { k: "s", style: { top: overlayFrozenHeight, bottom: 0 } },
+              ] as const)
+            : ([{ k: "m", style: { top: 0, bottom: 0 } }] as const)
+    // 描画上位の並べ替え (凍結種 f を後置): 主(m) < スクロール(s) < 凍結(f)
+    const rank = (k: string): number => (k === "m" ? 0 : k === "s" ? 1 : 2)
+    const quadrants = xKinds.flatMap((x) => yKinds.map((y) => ({ key: `${x.k}${y.k}`, style: { ...x.style, ...y.style } }))).sort((a, b) => rank(a.key[0]) + rank(a.key[1]) - (rank(b.key[0]) + rank(b.key[1])))
+    // R = 0 の 3 象限は v0.5 の data-attr を温存 (E2E / 単体フック互換)。行凍結が入る象限は
+    // 汎用 data-aqsp-overlay-quad のみ
+    const legacyAttr = (key: string): Record<string, string> => (key === "mm" ? { "data-aqsp-overlay-main": "" } : key === "fm" ? { "data-aqsp-overlay-frozen": "" } : key === "sm" ? { "data-aqsp-overlay-scroll": "" } : {})
+
+    return (
+        // 右 / 下オフセットは JSX インライン (CSS は TS 定数を読めない — SSOT は SCROLLBAR_WIDTH
+        // 1 本 §6.7.2-1)。下は v0.4 で追加: 横バー帯がグリッド内在化し、オーバーレイはセル
+        // ビューポート (バー帯を除く) だけを覆う
+        <div ref={overlayRef} className="aqsp-overlay" data-aqsp-overlay="" style={{ right: SCROLLBAR_WIDTH, bottom: SCROLLBAR_WIDTH }}>
+            {quadrants.map(({ key, style }) => {
+                const refs = quadRefs[key]
+                return (
+                    <div key={key} className="aqsp-overlay-quad" data-aqsp-overlay-quad={key} {...legacyAttr(key)} style={style} ref={refs.container}>
+                        <div className="aqsp-active-frame" data-aqsp-active="" style={{ display: "none" }} ref={refs.active} />
+                        <div className="aqsp-drag-rect" data-aqsp-drag-rect="" style={{ display: "none" }} ref={refs.dragRect} />
+                        <div className="aqsp-clip-marquee" data-aqsp-clip-marquee="" style={{ display: "none" }} ref={refs.marquee} />
+                        <div className="aqsp-autofill-preview" data-aqsp-autofill-preview="" style={{ display: "none" }} ref={refs.fillPreview} />
+                        <div className="aqsp-resize-guide" data-aqsp-resize-guide="" style={{ display: "none" }} ref={refs.resizeGuide} />
+                    </div>
+                )
+            })}
+            {/* inputMode (R4 / R5 / R7 是正): 仮想キーボード招待フラグの純粋な描画 — "none" = 非招待 (touch / ペンは
+                スクロール専用で選択も編集もしない。タップの compat mousedown 既定で root → シンクへ焦点が戻っても OSK は
+                出ない)、"text" = 招待中 (ポインタでエディタを開いた — キーボード無し端末が OSK を出せる。Enter / Tab の
+                確定では下ろさず、グリッド脱出か touch / ペン押下で下ろす)。キーボード / IME 利用者には常に "none" で
+                一度も変化しない — 変換中の属性変更 (Windows TSF が変換を強制終了する) を構造的に排除する。
+                OSK の実際の表示は UA 依存: WebKit はフォーカス済み要素の変更を再評価する、Chromium はフォーカス取得時に
+                しか評価しない。ハードウェアキーボードとデスクトップ IME は無影響 */}
+            <textarea ref={mergedSinkRef} className="aqsp-sink" aria-label={sinkAriaLabel} tabIndex={-1} defaultValue=" " inputMode={virtualKeyboard ? "text" : "none"} spellCheck={false} autoCorrect="off" autoCapitalize="off" autoComplete="off" data-aqsp-sink="" />
+            {/* pointer-events: auto の例外第 2 号 (§8.1) — シンクより後置 = 最上層。enableFillHandle=false は
+                DOM ごと抑止 (機械も不活性) */}
+            {enableFillHandle ? <div ref={fillHandleNodeRef} className="aqsp-autofill-handle" data-aqsp-autofill-handle="" style={{ display: "none" }} /> : null}
+        </div>
+    )
+}