@aiquants/spreadsheet 0.8.0

package/src/header/ColumnHeader.tsx

@@ -0,0 +1,167 @@
+/**
+ * @fileoverview Column header band (viewStore subscription #2). Since v0.4 it mirrors the
+ * RowHeader scheme exactly (§7-5 of the VirtualGrid design plan): renders only the rendering
+ * column range (overscan-inclusive, fed by VirtualGrid's onRangeChange via setColRange) with
+ * WINDOW-ORIGIN-RELATIVE coordinates; the track's residual translate is owned EXCLUSIVELY by
+ * the imperative repaintColHeaders path (commit gate — the layout effect publishes the new
+ * origin pre-paint). The v0.3 --aqsp-hx CSS variable and useColumnWindow are deleted: raw
+ * axis-origin lefts would desync from the grid's anchored cells at depth (the 2^25 wall).
+ * v0.5 adds the two-band frozen structure (plan §3-2): static frozen labels [0, F) at direct
+ * offsetOf lefts, plus a static clip (left = W_F) that hosts the existing scroll track with
+ * a floor-clamped enumeration (max(colStart, F)); F = 0 renders the v0.4-identical DOM.
+ *
+ * 列ヘッダー帯 (viewStore 購読 2)。v0.4 から RowHeader 方式の完全対称 (§7-5): VirtualGrid の
+ * onRangeChange (setColRange) が供給する描画列レンジのみを**窓原点相対**の小座標で描画し、
+ * track の残差 translate は命令パス (repaintColHeaders) の専有物 — layout effect が新原点を
+ * paint 前に公開する (commit ゲート)。v0.3 の --aqsp-hx CSS 変数と useColumnWindow は削除:
+ * 軸原点の生 left は深部でアンカー済みセルと desync する (2^25 壁)。v0.5 で 2 帯凍結構造を追加
+ * (計画 §3-2): 静的凍結ラベル [0, F) は offsetOf 直接値、スクロール track は静的クリップ
+ * (left = W_F) 内で床クランプ列挙 (max(colStart, F)) — F = 0 は v0.4 恒等 DOM。
+ *
+ * 逸脱 (ADR-9): ヘッダー帯の contextmenu は非対応 — ネイティブメニューへ素通しし、
+ * 列選択も onCellContextMenu も発火しない (§6.8-3。README 逸脱表に記載)。
+ */
+
+import { useWheelBridge, type VirtualGridHandle } from "@aiquants/virtualscroll"
+import { type ReactNode, type RefObject, useCallback, useLayoutEffect, useSyncExternalStore } from "react"
+import { type AxisModel, visibleIndicesInRange } from "../model/axisModel.ts"
+import type { CellRange } from "../model/cellCoord.ts"
+import { frozenWidthOf } from "../model/frozenPartition.ts"
+import type { ViewStore } from "../model/viewStore.ts"
+import { columnIndexToName } from "./columnName.ts"
+import { buildResizeStrips } from "./resizeStrips.ts"
+
+type ColumnHeaderProps = {
+    viewStore: ViewStore
+    colAxis: AxisModel
+    /** Frozen leading columns (v0.5 — mirrors the grid's engine-validated value; render-surface W_F derives from colAxis). / 先頭凍結列数 (v0.5 — エンジン検証値の写像。render 面の W_F は colAxis から導出)。 */
+    frozenCols: number
+    /** Wheel-bridge target (§6.8-1 — the grid handle satisfies WheelBridgeTarget). / ホイール橋渡し先 (グリッドハンドルがブリッジ契約適合)。 */
+    handleRef: RefObject<VirtualGridHandle | null>
+    /** Band element registration for the header selection machine (§6.8-1). / 選択機械の帯登録先。 */
+    bandRef: RefObject<HTMLDivElement | null>
+    /** Registration target for the track element (repaintColHeaders writes here — owner: Spreadsheet §6.9-7). / track 要素の登録先。 */
+    colTrackRef: RefObject<HTMLDivElement | null>
+    /** Shared ref of the window-origin absolute offset (§7-5 ordering contract — the row windowOriginYRef twin). / 窓原点の共有 ref (行側 windowOriginYRef の双子)。 */
+    windowOriginXRef: RefObject<number>
+    /** Imperative repaint invoked pre-paint from the layout effect (§7-5 commit gate). / paint 前の命令再描画 (§7-5 commit ゲート)。 */
+    repaintColHeaders: () => void
+    /** Selected-column emphasis source (data-aqsp-in-selection — §6.8-4; frozen at press during drags = known trait). / 選択中列の強調用 (ドラッグ中は押下時のまま凍結 = 既知特性)。 */
+    selectionRanges: readonly CellRange[]
+    /** §11 opt-out: false suppresses strip/marker DOM entirely (§7.1). / §11 の opt-out (false は DOM 生成ごと抑止)。 */
+    enableResizeUI: boolean
+}
+
+/**
+ * Renders the visible column-name cells for the rendering window. Header is a visual aid
+ * OUTSIDE role="grid" (§10) and therefore aria-hidden.
+ * 描画ウィンドウの可視列名セルを描画。role="grid" 外の視覚補助のため aria-hidden。
+ */
+export const ColumnHeader = ({ viewStore, colAxis, frozenCols, handleRef, bandRef, colTrackRef, windowOriginXRef, repaintColHeaders, selectionRanges, enableResizeUI }: ColumnHeaderProps): ReactNode => {
+    const bridgeRef = useWheelBridge(handleRef)
+    // 帯要素は選択機械 (bandRef) と wheel bridge の 2 消費者を持つ — マージ ref で合成
+    const mergedBandRef = useCallback(
+        (el: HTMLDivElement | null) => {
+            bandRef.current = el
+            // bridge の戻り値 (クリーンアップ) をそのまま返す — useWheelBridge の正準形 (React 19)
+            return bridgeRef(el)
+        },
+        [bandRef, bridgeRef],
+    )
+
+    /** String snapshot for uSES bail (colRange + colVersion). / bail 判定用スナップショット。 */
+    const getSnapshot = useCallback(() => {
+        const { colStart, colEnd, colVersion } = viewStore.get()
+        return `${colStart}:${colEnd}:${colVersion}`
+    }, [viewStore])
+    const subscribe = useCallback((listener: () => void) => viewStore.subscribeCoalesced(listener), [viewStore])
+    useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
+    const { colStart, colEnd } = viewStore.get()
+
+    // windowOriginX = offsetOf(colStart)。React が新ウィンドウのラベルを配置し終えた後にだけ
+    // 命令パスへ見せる (§7-5 順序契約 — 行側 §6.8-2 (a) の双子): commit 後の layout effect で
+    // 共有 ref を更新し、同じ effect 内で repaintColHeaders を即時呼びして新原点の残差 transform
+    // を paint 前に書く。adapter 縮小直後の stale range クランプは多層防御 (FenwickMapTree も
+    // 内部で index をクランプするため単独では等価 — 行側と同文の契約明示)
+    const windowOriginX = colAxis.count === 0 ? 0 : colAxis.offsetOf(Math.min(colStart, colAxis.count - 1))
+    useLayoutEffect(() => {
+        windowOriginXRef.current = windowOriginX
+        repaintColHeaders()
+    }, [windowOriginX, windowOriginXRef, repaintColHeaders])
+
+    /** Whether the column intersects a selection range (§6.8-4 emphasis). / 列が選択レンジに含まれるか (§6.8-4 の強調)。 */
+    const isInSelection = (col: number): boolean => selectionRanges.some((r) => col >= r.startCol && col <= r.endCol)
+
+    // 凍結帯 (v0.5 計画 §3-2): 実効 F はエンジンの動的クランプの写像、W_F は colAxis から導出
+    // (対呼び出し規律によりエンジン getFrozenSize().width と常に一致する render 面双子)
+    const effectiveFrozenCols = Math.min(Math.max(0, frozenCols), colAxis.count)
+    const frozenWidth = frozenWidthOf(colAxis, effectiveFrozenCols)
+    // 凍結ラベルは静的 subtree — 木絶対 left の直接値 (W_F ≤ viewport で LayoutUnit 安全)
+    const frozenVisibleCols = effectiveFrozenCols > 0 ? visibleIndicesInRange(colAxis, 0, effectiveFrozenCols - 1) : []
+
+    // §5.4: Fenwick ジャンプ列挙 — 幅 0 列はヘッダーセル DOM を生成しない。配置は窓原点相対
+    // (生 offset は深部グリッドで数百万 px になり LayoutUnit 壁を踏む — §7-5)。スクロール側は
+    // 凍結列を再出現させない床クランプ (エンジン §8-a と同文 — 空窓 start > end は空列挙)
+    const visibleCols = visibleIndicesInRange(colAxis, Math.max(colStart, effectiveFrozenCols), Math.min(colEnd, Math.max(0, colAxis.count - 1)))
+    const cells: ReactNode[] = []
+    for (const col of visibleCols) {
+        cells.push(
+            <div key={col} className="aqsp-col-header-cell" data-col={col} data-aqsp-in-selection={isInSelection(col) ? "" : undefined} style={{ left: colAxis.offsetOf(col) - windowOriginX, width: colAxis.sizeOf(col) }}>
+                {columnIndexToName(col)}
+            </div>,
+        )
+    }
+
+    // §7.1: ストリップ / マーカーは track の末尾 (ヘッダーセル群の後方兄弟 — DOM 順で上層)。
+    // 位置は窓原点相対 (ラベルと同一規律)。リスナーは持たない (帯の wire-once capture が
+    // closest() でディスパッチ — useHeaderResize)
+    const rawStrips = enableResizeUI ? buildResizeStrips(colAxis, visibleCols) : null
+    // 凍結境界の重複 unhide 遮断 (R3 是正): スクロール側先頭マーカーの復元対象が凍結列
+    // (index < F) かつ凍結帯が実在 (W_F > 0 — 帯側の分割マーカーが同じランを覆う) なら落とす。
+    // 全凍結列非表示 (W_F = 0) は帯側が何も描けないため、スクロール側が唯一の復元導線として残る
+    const strips = rawStrips === null ? null : rawStrips.filter((strip) => !(strip.kind === "unhide" && strip.index < effectiveFrozenCols && frozenWidth > 0))
+
+    // 凍結帯のストリップ (リサイズ / unhide) — 静的配置 (木絶対 left 直接値)
+    const frozenStrips = enableResizeUI && effectiveFrozenCols > 0 ? buildResizeStrips(colAxis, frozenVisibleCols) : null
+    const track = (
+        <div ref={colTrackRef} className="aqsp-col-header-track">
+            {cells}
+            {strips?.map((strip) =>
+                strip.kind === "resize" ? (
+                    <div key={`r${strip.index}`} className="aqsp-col-resize-strip" data-aqsp-col-resize={strip.index} style={{ left: strip.start - windowOriginX, width: strip.length }} />
+                ) : (
+                    <div key={`u${strip.index}`} className="aqsp-unhide-marker" data-aqsp-unhide={strip.index} style={{ left: strip.start - windowOriginX, width: strip.length }} />
+                ),
+            )}
+        </div>
+    )
+    return (
+        <div ref={mergedBandRef} className="aqsp-col-header" aria-hidden="true" data-aqsp-col-header="">
+            {/* track transform は repaintColHeaders (命令パス) の専有物 — React は書かない (§7-5)。
+                pointerdown (フォーカス回収 + 選択機械) は useHeaderSelection が帯へ結線する (§6.8-1)。
+                v0.5: F > 0 はスクロール track を静的クリップ (left = W_F) で包み、凍結ラベルを
+                帯直下の静的 subtree に置く (エンジン §8-b/c のヘッダー同文。F = 0 は従来 DOM 恒等) */}
+            {effectiveFrozenCols === 0 ? (
+                track
+            ) : (
+                <>
+                    {frozenVisibleCols.map((col) => (
+                        <div key={col} className="aqsp-col-header-cell" data-col={col} data-aqsp-frozen-header="" data-aqsp-in-selection={isInSelection(col) ? "" : undefined} style={{ left: colAxis.offsetOf(col), width: colAxis.sizeOf(col) }}>
+                            {columnIndexToName(col)}
+                        </div>
+                    ))}
+                    {frozenStrips?.map((strip) =>
+                        strip.kind === "resize" ? (
+                            <div key={`fr${strip.index}`} className="aqsp-col-resize-strip" data-aqsp-col-resize={strip.index} style={{ left: strip.start, width: strip.length }} />
+                        ) : (
+                            <div key={`fu${strip.index}`} className="aqsp-unhide-marker" data-aqsp-unhide={strip.index} style={{ left: strip.start, width: strip.length }} />
+                        ),
+                    )}
+                    <div className="aqsp-col-header-scroll" data-aqsp-col-header-scroll="" style={{ left: frozenWidth }}>
+                        {track}
+                    </div>
+                </>
+            )}
+        </div>
+    )
+}

package/src/header/RowHeader.tsx

@@ -0,0 +1,144 @@
+/**
+ * @fileoverview Row header band (viewStore subscription #3). Renders only the rendering-range
+ * rows (overscan-inclusive) with window-origin-relative coordinates; the track's residual
+ * translate is owned EXCLUSIVELY by the imperative repaintHeaders path (§6.8-2).
+ *
+ * 行ヘッダー帯 (viewStore 購読 3)。描画レンジ (オーバースキャン込み) の行のみを
+ * ウィンドウ原点基準の小座標で描画。track の残差 translate は命令パス (repaintHeaders) の
+ * 専有物 — React レンダーは書かない (§6.8-2 の二重書き手禁止)。
+ */
+
+import { useWheelBridge, type VirtualGridHandle } from "@aiquants/virtualscroll"
+import { type ReactNode, type RefObject, useCallback, useLayoutEffect, useSyncExternalStore } from "react"
+import { type AxisModel, visibleIndicesInRange } from "../model/axisModel.ts"
+import type { CellRange } from "../model/cellCoord.ts"
+import { frozenHeightOf } from "../model/frozenPartition.ts"
+import { SCROLLBAR_WIDTH, type ViewStore } from "../model/viewStore.ts"
+import { buildResizeStrips } from "./resizeStrips.ts"
+
+type RowHeaderProps = {
+    viewStore: ViewStore
+    rowAxis: AxisModel
+    handleRef: RefObject<VirtualGridHandle | null>
+    /** Band element registration for the header selection machine (§6.8-2). / 選択機械の帯登録先。 */
+    bandRef: RefObject<HTMLDivElement | null>
+    /** Selected-row emphasis source (§6.8-4; frozen at press during drags = known trait). / 選択中行の強調用 (ドラッグ中は押下時のまま凍結 = 既知特性)。 */
+    selectionRanges: readonly CellRange[]
+    /** Registration target for the track element (repaintHeaders writes here — owner: Spreadsheet §6.9-7). / track 要素の登録先。 */
+    rowTrackRef: RefObject<HTMLDivElement | null>
+    /** Shared ref of the window-origin absolute offset (§6.8-2 ordering contract). / ウィンドウ原点の共有 ref。 */
+    windowOriginYRef: RefObject<number>
+    /** Imperative repaint invoked pre-paint from the layout effect (§6.8-2 (a)). / paint 前の命令再描画。 */
+    repaintHeaders: () => void
+    /** §11 opt-out: false suppresses strip/marker DOM entirely (§7.1). / §11 の opt-out (false は DOM 生成ごと抑止)。 */
+    enableResizeUI: boolean
+    /** Frozen leading rows (v0.6 — drives the two-band split; the ColumnHeader two-band transpose). / 先頭凍結行数 (v0.6 — 2 帯分割の構造判定。ColumnHeader 2 帯の転置)。 */
+    frozenRows: number
+}
+
+/**
+ * Renders row-number labels for the rendering window.
+ * 描画ウィンドウの行番号ラベルを描画 (1 始まり表示)。
+ */
+export const RowHeader = ({ viewStore, rowAxis, handleRef, bandRef, selectionRanges, rowTrackRef, windowOriginYRef, repaintHeaders, enableResizeUI, frozenRows }: RowHeaderProps): ReactNode => {
+    const bridgeRef = useWheelBridge(handleRef)
+    // 帯要素は選択機械 (bandRef) と wheel bridge の 2 消費者 — マージ ref で合成
+    const mergedBandRef = useCallback(
+        (el: HTMLDivElement | null) => {
+            bandRef.current = el
+            // bridge の戻り値 (クリーンアップ) をそのまま返す — useWheelBridge の正準形 (React 19)
+            return bridgeRef(el)
+        },
+        [bandRef, bridgeRef],
+    )
+
+    /** Whether the row intersects a selection range (§6.8-4). / 行が選択レンジに含まれるか。 */
+    const isInSelection = (row: number): boolean => selectionRanges.some((r) => row >= r.startRow && row <= r.endRow)
+
+    /** String snapshot for uSES bail (rowRange + rowGeomVersion). / bail 判定用スナップショット。 */
+    const getSnapshot = useCallback(() => {
+        const { rowStart, rowEnd, rowGeomVersion } = viewStore.get()
+        return `${rowStart}:${rowEnd}:${rowGeomVersion}`
+    }, [viewStore])
+    const subscribe = useCallback((listener: () => void) => viewStore.subscribeCoalesced(listener), [viewStore])
+    useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
+    const { rowStart, rowEnd } = viewStore.get()
+
+    // windowOriginY = offsetOf(rowStart)。React が新ウィンドウのラベルを配置し終えた後にだけ
+    // 命令パスへ見せる (§6.8-2 順序契約 (a)): commit 後の layout effect で共有 ref を更新し、
+    // 同じ effect 内で repaintHeaders を即時呼びして新原点の残差 transform を paint 前に書く
+    // §6.8-2 の式 (offsetOf(rowStart) 素通し) への意図的ガード: adapter 縮小直後は store の
+    // rowRange が旧 count 基準で stale になり得る (onRangeChange の再配送は rAF 遅れ)。
+    // クランプは多層防御 (FenwickMapTree も内部で index をクランプするため単独では等価 —
+    // 範囲外読みの契約をこの層でも明示する)
+    const windowOriginY = rowAxis.count === 0 ? 0 : rowAxis.offsetOf(Math.min(rowStart, rowAxis.count - 1))
+    useLayoutEffect(() => {
+        windowOriginYRef.current = windowOriginY
+        repaintHeaders()
+    }, [windowOriginY, windowOriginYRef, repaintHeaders])
+
+    // 凍結帯 (v0.6 計画 §3-2 — ColumnHeader 2 帯の転置): 実効 R / H_F を rowAxis から導出
+    const effectiveFrozenRows = Math.min(Math.max(0, frozenRows), rowAxis.count)
+    const frozenHeight = frozenHeightOf(rowAxis, effectiveFrozenRows)
+    // 凍結ラベルは静的 subtree — 木絶対 top の直接値 (H_F ≤ viewport で LayoutUnit 安全)
+    const frozenVisibleRows = effectiveFrozenRows > 0 ? visibleIndicesInRange(rowAxis, 0, effectiveFrozenRows - 1) : []
+
+    // スクロールラベルは床クランプ max(rowStart, R) — 凍結行を再出現させない (空窓 start > end は空列挙)
+    const visibleRows = visibleIndicesInRange(rowAxis, Math.max(rowStart, effectiveFrozenRows), Math.min(rowEnd, Math.max(0, rowAxis.count - 1)))
+    const labels: ReactNode[] = []
+    for (const row of visibleRows) {
+        labels.push(
+            <div key={row} className="aqsp-row-header-cell" data-row={row} data-aqsp-in-selection={isInSelection(row) ? "" : undefined} style={{ top: rowAxis.offsetOf(row) - windowOriginY, height: rowAxis.sizeOf(row) }}>
+                {row + 1}
+            </div>,
+        )
+    }
+    // §7.1: ストリップ / マーカーは track 末尾の後方兄弟。凍結境界の重複 unhide 遮断 (R3 是正の縦版)
+    const rawStrips = enableResizeUI ? buildResizeStrips(rowAxis, visibleRows) : null
+    const strips = rawStrips === null ? null : rawStrips.filter((strip) => !(strip.kind === "unhide" && strip.index < effectiveFrozenRows && frozenHeight > 0))
+    // 凍結帯のストリップ (静的配置 — 木絶対 top 直接値)
+    const frozenStrips = enableResizeUI && effectiveFrozenRows > 0 ? buildResizeStrips(rowAxis, frozenVisibleRows) : null
+    const track = (
+        <div ref={rowTrackRef} className="aqsp-row-header-track">
+            {labels}
+            {strips?.map((strip) =>
+                strip.kind === "resize" ? (
+                    <div key={`r${strip.index}`} className="aqsp-row-resize-strip" data-aqsp-row-resize={strip.index} style={{ top: strip.start - windowOriginY, height: strip.length }} />
+                ) : (
+                    <div key={`u${strip.index}`} className="aqsp-unhide-marker" data-aqsp-unhide={strip.index} style={{ top: strip.start - windowOriginY, height: strip.length }} />
+                ),
+            )}
+        </div>
+    )
+
+    // margin-bottom はグリッド内在の横バー帯ぶんの切り上げ — CSS は TS 定数を読めないため
+    // インライン指定 (SCROLLBAR_WIDTH の単一 SSOT — SelectionOverlay の right / bottom と同方式)
+    return (
+        <div ref={mergedBandRef} className="aqsp-row-header" aria-hidden="true" data-aqsp-row-header="" style={{ marginBottom: SCROLLBAR_WIDTH }}>
+            {/* track transform は repaintHeaders (命令パス) の専有物 — React は書かない (§6.8-2 (b))。
+                v0.6: R > 0 はスクロール track を静的クリップ (top = H_F) で包み、凍結ラベルを帯直下の
+                静的 subtree に置く (ColumnHeader の 2 帯を転置。R = 0 は従来 DOM 恒等) */}
+            {effectiveFrozenRows === 0 ? (
+                track
+            ) : (
+                <>
+                    {frozenVisibleRows.map((row) => (
+                        <div key={row} className="aqsp-row-header-cell" data-row={row} data-aqsp-frozen-row-header="" data-aqsp-in-selection={isInSelection(row) ? "" : undefined} style={{ top: rowAxis.offsetOf(row), height: rowAxis.sizeOf(row) }}>
+                            {row + 1}
+                        </div>
+                    ))}
+                    {frozenStrips?.map((strip) =>
+                        strip.kind === "resize" ? (
+                            <div key={`fr${strip.index}`} className="aqsp-row-resize-strip" data-aqsp-row-resize={strip.index} style={{ top: strip.start, height: strip.length }} />
+                        ) : (
+                            <div key={`fu${strip.index}`} className="aqsp-unhide-marker" data-aqsp-unhide={strip.index} style={{ top: strip.start, height: strip.length }} />
+                        ),
+                    )}
+                    <div className="aqsp-row-header-scroll" data-aqsp-row-header-scroll="" style={{ top: frozenHeight }}>
+                        {track}
+                    </div>
+                </>
+            )}
+        </div>
+    )
+}

package/src/header/columnName.ts

@@ -0,0 +1,31 @@
+/**
+ * @fileoverview Excel-style column name conversion (bijective base-26).
+ * Excel 形式の列名変換 (全単射 26 進)。
+ */
+
+/** Column index (0-based) to Excel-style name (0 → A, 26 → AA, 16383 → XFD). / 列 index → 列名。 */
+export const columnIndexToName = (index: number): string => {
+    if (!(Number.isInteger(index) && index >= 0)) {
+        throw new RangeError(`[spreadsheet] columnIndexToName requires a non-negative integer, received ${index}`)
+    }
+    let name = ""
+    let n = index
+    // 全単射 26 進: 各桁は 1..26 (0 が無い) ため、剰余の後に 1 引いてから桁送りする
+    while (n >= 0) {
+        name = String.fromCharCode(65 + (n % 26)) + name
+        n = Math.trunc(n / 26) - 1
+    }
+    return name
+}
+
+/** Excel-style name to column index (inverse). / 列名 → 列 index (逆変換)。 */
+export const columnNameToIndex = (name: string): number => {
+    if (!/^[A-Z]+$/.test(name)) {
+        throw new RangeError(`[spreadsheet] columnNameToIndex requires /^[A-Z]+$/, received "${name}"`)
+    }
+    let index = 0
+    for (const ch of name) {
+        index = index * 26 + (ch.charCodeAt(0) - 64)
+    }
+    return index - 1
+}

package/src/header/resizeGates.ts

@@ -0,0 +1,146 @@
+/**
+ * @fileoverview Resize entry gates (v0.8 §4.1.14) — the three gates that every track-size
+ * batch passes before the resizeTracks seam, extracted from useHeaderResize
+ * (applyEntries / collectTargets) so the header drag, the paste-special dimensions path and
+ * the hide / unhide commands share ONE decision. Order: (1) the ADR-12 track-count gate on
+ * the RAW entry count (before materializing — duplicates counted as-is, conservative; rows
+ * get a 10x lower ceiling than columns, §13 budget row (f)); (2) one rounding pass with the
+ * axis.resize fail-fast pulled forward (non-finite / negative sizes throw RangeError here so a
+ * batch never half-applies), each size clamped to MAX_TRACK_SIZE_PX (fail-soft — hostile pasted
+ * sizes cannot wedge the non-undoable grid geometry) and duplicate indices folded to their last
+ * size; (3) the §7.2
+ * post-application zero-guard (the pressed track — or the first entry — clamps to 1 px when
+ * the whole axis would go invisible); (4) the §5.4(b) row-axis hidden-total gate, counted on
+ * the clamped entries. Pure: reads the axis model, never writes it.
+ *
+ * リサイズ entry ゲート (v0.8 §4.1.14) — resizeTracks シームに入る全トラック寸法バッチが通る
+ * 3 ゲート。useHeaderResize (applyEntries / collectTargets) から抽出し、ヘッダードラッグ・
+ * 貼り付け寸法・hide / unhide コマンドが単一判定を共有する。順序: (1) ADR-12 のトラック数
+ * ゲートは生 entry 数で実体化前に判定 (重複は重複のまま数える保守側、行は列の 1/10 上限 —
+ * §13 予算行 (f))、(2) 丸めは 1 度だけ + axis.resize の fail-fast 先取り (非有限 / 負サイズは
+ * ここで RangeError — バッチの部分適用を作らない) + 各サイズを MAX_TRACK_SIZE_PX へクランプ
+ * (fail-soft — 敵対的貼り付け寸法が非 undo の格子幾何を破壊しない) + 同一 index は後勝ちで
+ * 畳む、(3) §7.2 の
+ * 適用後 0 化ガード (全可視消滅なら押下トラック — 無ければ先頭 entry — を 1px へクランプ)、
+ * (4) §5.4(b) の行軸非表示総数ゲートはクランプ後の entries で数える。純関数 — 軸モデルは
+ * 読むだけで書かない。
+ */
+
+import type { AxisModel } from "../model/axisModel.ts"
+
+/** Row-axis hidden-track ceiling for UI-driven hides (§5.4(b) — the virtualscroll 2000-item window cutoff bound). / UI 経由の行非表示総数上限 (§5.4(b))。 */
+export const ROW_HIDDEN_LIMIT = 1_000
+
+/**
+ * Upper track-size bound (logical px) for every gated batch and for the size trust boundaries
+ * (wire validator, HTML reader, copy writer). Generously above Excel's native caps (255-char
+ * column ≈ 1,790 px, 409-pt row ≈ 545 px), yet small enough that a hostile pasted size can
+ * never wedge the grid geometry — sizes are non-undoable (ADR-16), so an unbounded width
+ * (e.g. 1e24 px) would leave every column to its right unreachable with no in-UI recovery.
+ * 全ゲート通過バッチと寸法の信頼境界 (wire 検証器・HTML reader・copy writer) が共有する
+ * トラック寸法上限 (論理 px)。Excel の原生上限 (255 文字列幅 ≈ 1,790 px、409pt 行高 ≈ 545 px)
+ * を大きく上回りつつ、敵対的貼り付け寸法による格子幾何の破壊 (寸法は非 undo — ADR-16) を
+ * 防げる小ささに設定。
+ */
+export const MAX_TRACK_SIZE_PX = 10_000
+
+/**
+ * Row fan-out limit divisor (§13 budget row (f) DESIGN RETURN, measured): updateItemSize
+ * carries a per-call content-size/anchor compensation that cannot be batched away — a
+ * 20k-row batch measured 339ms median (over the 300ms budget), so row fan-outs get a 10x
+ * lower ceiling than columns (default 100k/10 = 10k rows ≈ 170ms class).
+ * 行ファンアウト上限の除数 (§13 予算行 (f) の設計返却 — 実測起点)。updateItemSize の per-call
+ * 補償はバッチ化で消せず、2 万行で中央値 339ms (予算 300ms 超過)。行は列の 1/10 上限
+ * (既定 10 万 / 10 = 1 万行 ≈ 170ms 級)。
+ */
+export const ROW_FANOUT_DIVISOR = 10
+
+/** One track-size entry of a resize batch (size in logical px, 0 = hidden). / リサイズバッチの 1 entry (論理 px、0 = 非表示)。 */
+export type ResizeEntry = { index: number; size: number }
+
+/**
+ * Gate parameters: the ADR-12 operation ceiling, the row hidden-total ceiling and which axis
+ * the batch targets (rows get the fan-out divisor and the hidden-total gate).
+ * ゲートのパラメータ: ADR-12 の操作上限、行非表示総数上限、対象軸 (行はファンアウト除数と
+ * 非表示総数ゲートの対象)。
+ */
+export type ResizeGateLimits = { maxOperationCells: number; rowHiddenLimit: number; axisKind: "row" | "col" }
+
+/**
+ * Gate outcome: the rounded, de-duplicated, zero-guarded entries ready for resizeTracks, or a
+ * rejection carrying the onOperationRejected reason and count ("limit" = raw entry count,
+ * "bounds" = the would-be hidden-row total).
+ * ゲート結果: resizeTracks へ渡せる丸め済み・重複畳み済み・0 化ガード済み entries、または
+ * onOperationRejected 用の理由と件数 ("limit" = 生 entry 数、"bounds" = 適用後の非表示行総数)。
+ */
+export type ResizeGateResult = { ok: true; entries: readonly ResizeEntry[] } | { ok: false; reason: "limit" | "bounds"; count: number }
+
+/**
+ * Sums the hidden-state transitions of a batch against the axis' stored sizes (+1 per
+ * visible→hidden, -1 per hidden→visible — implicit unhide, Excel-compatible). Compared on
+ * ROUNDED sizes, matching what resizeTracks / axis.resize will store.
+ * バッチの非表示遷移差分を格納サイズと突き合わせて合計 (可視→非表示 +1、非表示→可視 -1 —
+ * 暗黙再表示)。resizeTracks / axis.resize の格納値と一致させるため丸め後サイズで比較。
+ */
+const deltaHidden = (axis: AxisModel, entries: readonly ResizeEntry[]): number =>
+    entries.reduce((sum, entry) => {
+        const wasHidden = axis.sizeOf(entry.index) === 0
+        const willHide = entry.size === 0
+        return sum + (willHide && !wasHidden ? 1 : 0) - (!willHide && wasHidden ? 1 : 0)
+    }, 0)
+
+/**
+ * Runs a resize batch through the three gates (count → zero-guard → row hidden-total) and
+ * returns the entries to hand to resizeTracks, or the rejection. Empty batches are a no-op
+ * (`ok` with no entries — nothing to gate, and the zero-guard must not read a first entry).
+ * Non-finite / negative sizes throw RangeError before anything is materialized (fail-fast on
+ * the raw value, so -0.3 is rejected even though it would round to 0); finite sizes above
+ * MAX_TRACK_SIZE_PX clamp to it (fail-soft — the paste path carries untrusted sizes). Indices
+ * are not range-checked — same contract as resizeTracks / axis.resize.
+ * リサイズバッチを 3 ゲート (件数 → 0 化ガード → 行非表示総数) に通し、resizeTracks へ渡す
+ * entries か拒否を返す。空バッチは no-op (entries 無しの `ok` — 判定対象が無く、0 化ガードが
+ * 先頭 entry を読んではならない)。非有限 / 負サイズは実体化前に RangeError (丸め前の生値で
+ * fail-fast — -0.3 は 0 に丸まるが拒否)、有限の上限超は MAX_TRACK_SIZE_PX へクランプ (fail-soft —
+ * 貼り付け経路は外来寸法を運ぶ)。index の範囲検査は行わない (resizeTracks / axis.resize と
+ * 同じ契約)。
+ */
+export const gateResizeEntries = (axis: AxisModel, entries: readonly ResizeEntry[], pressedIndex: number | null, limits: ResizeGateLimits): ResizeGateResult => {
+    // 空バッチは no-op (resizeTracks も空で早期 return — ゲートの判定対象が無い)
+    if (entries.length === 0) {
+        return { ok: true, entries: [] }
+    }
+    // ゲート 1 (ADR-12): 実体化前の保守カウント (重複 index は重複のまま数え、上限判定を保守側に倒す —
+    // collectTargets と同じ流儀)。行軸は (f) の設計返却で 1/10 上限 (updateItemSize の per-call 補償コスト)
+    const limit = limits.axisKind === "row" ? Math.floor(limits.maxOperationCells / ROW_FANOUT_DIVISOR) : limits.maxOperationCells
+    if (entries.length > limit) {
+        return { ok: false, reason: "limit", count: entries.length }
+    }
+    // 丸めは 1 度だけ (resizeTracks / axis.resize の格納と一致させる)。検証は丸め前の生値で
+    // axis.resize と同じ条件 (先取りしてバッチの部分適用を作らない)。同一 index は後勝ちで畳む
+    const sizeByIndex = new Map<number, number>()
+    for (const entry of entries) {
+        if (!(Number.isFinite(entry.size) && entry.size >= 0)) {
+            throw new RangeError(`[spreadsheet] gateResizeEntries requires a finite size >= 0, received ${entry.size} at index ${entry.index}`)
+        }
+        // 上限は fail-soft のクランプ (RangeError でない): 貼り付け寸法は外来信頼境界由来で、
+        // 寸法は非 undo の幾何 (ADR-16) — 1e24 px を通すと右側全列が到達不能のまま復旧手段が無い
+        sizeByIndex.set(entry.index, Math.min(Math.round(entry.size), MAX_TRACK_SIZE_PX))
+    }
+    let gated: ResizeEntry[] = [...sizeByIndex].map(([index, size]) => ({ index, size }))
+    // ゲート 2 (§7.2): 0 化ガードの一般形 — press 時本数でなく適用後の可視本数で判定 (Ctrl+A 後の
+    // 全列ファンアウト 0 化がガードを素通りする穴の閉塞)。押下トラックのみ最小 1px でクランプ
+    const visibleAfter = axis.count - axis.hiddenCount() - deltaHidden(axis, gated)
+    if (visibleAfter === 0) {
+        // 押下トラックが無い経路 (unhide 復元など) は先頭 entry をクランプ対象にする
+        const clampIndex = pressedIndex === null ? gated[0].index : pressedIndex
+        gated = gated.map((entry) => (entry.index === clampIndex ? { index: entry.index, size: 1 } : entry))
+    }
+    // ゲート 3 (§5.4(b)): 行非表示の軸総数ゲート — 行軸専用、暗黙再表示込み・クランプ後の適用後判定
+    if (limits.axisKind === "row") {
+        const hiddenAfter = axis.hiddenCount() + deltaHidden(axis, gated)
+        if (hiddenAfter > limits.rowHiddenLimit) {
+            return { ok: false, reason: "bounds", count: hiddenAfter }
+        }
+    }
+    return { ok: true, entries: gated }
+}

package/src/header/resizeStrips.ts

@@ -0,0 +1,79 @@
+/**
+ * @fileoverview Pure geometry for the §7.1 resize strips and unhide markers. Strips are
+ * hit-test/visual DOM ONLY (no listeners — the band's wire-once capture listener dispatches
+ * via closest()). Boundary rules: a normal track (width >= 12) gets a 6px strip INSIDE its
+ * right/bottom boundary; a boundary followed by a hidden run splits the same 6px into
+ * 3px resize + 3px unhide (structural exclusivity — no closest() priority problem); a
+ * degenerate track (width < 12) gets a boundary-anchored 3px strip overhanging the neighbor
+ * (the affordance never disappears — §7.1 recovery guarantee). A leading hidden run gets a
+ * 3px unhide marker on the first visible track's leading edge. Unhide markers are emitted
+ * AFTER all resize strips so DOM order stacks them on top (degenerate priority rule).
+ *
+ * §7.1 のリサイズストリップ / unhide マーカーの純幾何。ストリップは視覚とヒット判定のための
+ * DOM のみ (リスナーなし — 帯の wire-once capture リスナーが closest() でディスパッチ)。通常
+ * トラック (幅 ≥ 12) は境界の内側 6px、非表示ラン境界は同じ 6px を 3px リサイズ + 3px unhide
+ * に分割 (構造的排他)、縮退トラック (幅 < 12) は境界アンカー 3px の隣接 overhang (アフォー
+ * ダンスは消えない — 復旧保証)。先頭非表示ランは最初の可視トラックの先頭端 3px。unhide は
+ * リサイズ全件の後に出力し DOM 順で上層に積む (縮退時のマーカー優先則)。
+ */
+
+import { type AxisModel, nextVisibleIndex } from "../model/axisModel.ts"
+
+/** Full strip width in px on a normal boundary. / 通常境界のストリップ全幅 (px)。 */
+const STRIP_FULL = 6
+/** Half width for split / degenerate boundaries. / 分割 / 縮退境界の半幅 (px)。 */
+const STRIP_HALF = 3
+
+/** One strip/marker: `start`/`length` in logical axis px. / ストリップ 1 本 (論理軸 px)。 */
+export type ResizeStripDescriptor = {
+    kind: "resize" | "unhide"
+    /** resize: the track whose boundary this is; unhide: the boundary-nearest hidden track to restore. / resize は境界の持ち主トラック、unhide は境界に最も近い復元対象の非表示トラック。 */
+    index: number
+    start: number
+    length: number
+}
+
+/**
+ * Builds the strip/marker descriptors for the visible tracks of one window. `visible` comes
+ * from visibleIndicesInRange; hidden-run detection uses the AXIS-wide next visible track (a
+ * window-final track's run may extend beyond the window).
+ * 1 ウィンドウの可視トラック群からストリップ / マーカー記述子を構築。非表示ラン判定は軸全体の
+ * 次可視 (窓末尾トラックのランは窓外へ続き得る) で行う。
+ */
+export const buildResizeStrips = (axis: AxisModel, visible: readonly number[]): ResizeStripDescriptor[] => {
+    const strips: ResizeStripDescriptor[] = []
+    const markers: ResizeStripDescriptor[] = []
+    if (visible.length === 0) {
+        return strips
+    }
+    // 先頭マーカー: 窓先頭トラックの直前トラックが**実際に非表示**の場合のみ (R1(B) 実証欠陥の
+    // 閉塞 — `first > 0` 単独は「スクロールで窓が進んだ」と「先頭ランが隠れている」を混同し、
+    // 全可視軸のスクロール窓に可視トラック宛の偽 unhide マーカーを毎窓生成していた)。軸判定に
+    // より index 0 を含むラン (「列 A を再表示できない」古典問題) と窓境界を跨ぐランの両方を
+    // 正しく覆う。復元対象は境界に近い側 = ランの末尾 index
+    const first = visible[0]
+    if (first > 0 && axis.sizeOf(first - 1) === 0) {
+        markers.push({ kind: "unhide", index: first - 1, start: axis.offsetOf(first), length: STRIP_HALF })
+    }
+
+    for (const track of visible) {
+        const size = axis.sizeOf(track)
+        const boundary = axis.offsetOf(track) + size
+        // 非表示ラン判定は軸全体で行う (窓内の隣接可視だけを見ると窓末尾のランを見落とす)
+        const next = nextVisibleIndex(axis, track, 1)
+        const hiddenAfter = track < axis.count - 1 && (next === null || next > track + 1)
+        if (hiddenAfter) {
+            // 3px/3px 分割 (両機能の恒久排他)。復元対象は境界に近い側 = ランの先頭 index
+            strips.push({ kind: "resize", index: track, start: boundary - STRIP_FULL, length: STRIP_HALF })
+            markers.push({ kind: "unhide", index: track + 1, start: boundary - STRIP_HALF, length: STRIP_HALF })
+        } else if (size >= 2 * STRIP_FULL) {
+            // 通常トラック: 境界の内側 6px (隣接セル先頭の押下は選択のまま — §10 逸脱)
+            strips.push({ kind: "resize", index: track, start: boundary - STRIP_FULL, length: STRIP_FULL })
+        } else {
+            // 縮退トラック: 境界アンカー 3px (自トラックに収まらない分は隣へ overhang — 復旧保証)
+            strips.push({ kind: "resize", index: track, start: boundary - STRIP_HALF, length: STRIP_HALF })
+        }
+    }
+    // マーカーを後置 — DOM 順の後勝ち積層で復元アフォーダンスを上層へ (縮退時の優先則)
+    return [...strips, ...markers]
+}