@aiquants/spreadsheet 0.8.0 → 0.10.0

package/src/Spreadsheet.tsx

@@ -39,9 +39,10 @@
  * openPopoverRef / hideNoteTipRef / pasteRef / pendingPasteOptionsRef / ポップオーバーアンカー) を所有する。
  */
 
-import type { VirtualGridHandle, VirtualGridRange } from "@aiquants/virtualscroll"
+import type { ScrollBarTapCircleOptions, VirtualGridHandle, VirtualGridRange } from "@aiquants/virtualscroll"
 import type { ProfilerOnRenderCallback } from "react"
 import { forwardRef, type ReactNode, useCallback, useEffect, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from "react"
+import type { ClipChannel } from "./clipboard/clipPayload.ts"
 import type { PasteOptions } from "./clipboard/pasteSpecial.ts"
 import { type ClipInfo, type PasteOutcome, type PasteSheet, useClipboard } from "./clipboard/useClipboard.ts"
 import { type BorderPreset, type CommandRunner, useCommands } from "./commands/useCommands.ts"
@@ -62,7 +63,7 @@ import { type CellCoord, type CellRange, clampCoord, makeRange, rangeSize, type
 import { type CellBorder, type CellFormat, type CellFormatPatch, formatCellValue } from "./model/cellFormat.ts"
 import { type EditPaint, IDLE_EDIT_PAINT, normalizeColor, resolveEditPaint } from "./model/cellPaint.ts"
 import { buildCfIndex, type CfIndex, type CfMemo, createCfMemo, resolvePaintedFormat } from "./model/conditionalFormat.ts"
-import { type CellEdit, type EditContext, type EditRejection, type EditSource, lazyCellText, resolveCellAlign, type SpreadsheetDataAdapter } from "./model/dataAdapter.ts"
+import { type CellEdit, type EditContext, type EditRejection, type EditSource, isReadOnlyCell, lazyCellText, type ReadOnlyRejection, readOnlyDeclared, resolveCellAlign, type SpreadsheetDataAdapter } from "./model/dataAdapter.ts"
 import { type DataValidationRule, type ValidationVerdict, validateCellText } from "./model/dataValidation.ts"
 import type { ReferenceAxis } from "./model/formulaRefs.ts"
 import { colToViewportX, rowToViewportY } from "./model/frozenPartition.ts"
@@ -177,6 +178,45 @@ export type SpreadsheetProps = {
      * 位置に依らず常時可視で、可視化の縦成分は no-op。飛行中の変更は全ドラッグを取り消す。
      */
     frozenRows?: number
+    /**
+     * Freezes the LAST N columns at the right edge (v0.9 — the VirtualGrid frozenTrailingCols
+     * pass-through; LIVE prop, default 0). Validation SSOT is the engine's fail-fast contract
+     * (integer in [0, 128] — RangeError otherwise; the count clamp is leading-wins:
+     * effectiveTrailing = min(T, colCount − effectiveLeading)). Trailing columns stay visible at
+     * any horizontal scroll — with ONE registered exception: when the leading + trailing extent
+     * exceeds the viewport, occluded trailing cells cannot be scrolled into view and keyboard
+     * focus paints no visible frame (ADR-19-1). scrollToCell / ensure-visible treat a trailing
+     * target as a horizontal no-op. A mid-flight change cancels every in-flight drag without
+     * restore (the frozenColumns cancel seam).
+     * 末尾 N 列の右端凍結 (v0.9 — VirtualGrid frozenTrailingCols の素通し。ライブ prop、既定 0)。
+     * 検証 SSOT はエンジンの fail-fast 契約 ([0, 128] 整数、それ以外 RangeError。件数クランプは
+     * leading 勝ち: min(T, colCount − effectiveLeading))。末尾列は任意の横スクロールで可視 —
+     * ただし leading + trailing の extent が viewport を超える overlap では遮蔽された末尾セルを
+     * スクロールで可視化できず、キーボードフォーカスは可視フレームを描かない (ADR-19-1 の登記済み
+     * 帰結)。scrollToCell / ensure-visible は末尾ターゲットを横 no-op として扱う。飛行中の変更は
+     * 全ドラッグを復元なしで取り消す (frozenColumns と同じシーム)。
+     */
+    frozenTrailingColumns?: number
+    /**
+     * Freezes the LAST N rows at the bottom (v0.9 — the VirtualGrid frozenTrailingRows
+     * pass-through; LIVE prop, default 0 — the row twin of frozenTrailingColumns, same engine
+     * fail-fast contract and cancel seam). The typical use is a pinned totals row.
+     * 末尾 N 行の下端凍結 (v0.9 — frozenTrailingRows の素通し。ライブ prop、既定 0 —
+     * frozenTrailingColumns の行双子。エンジン契約・取消シームは同文)。典型は固定合計行。
+     */
+    frozenTrailingRows?: number
+    /**
+     * Tap-scroll circle tuning (v0.10 — the VirtualGrid `scrollBarOptions.tapScrollCircleOptions`
+     * engine-validated pass-through; LIVE prop): position and enable/disable of the touch
+     * tap-scroll circle. The engine's `resolveTapScrollCircleOptions` is the validation SSOT —
+     * undefined is the engine's declared absence signal (engine defaults), never a value
+     * fallback in this package.
+     * タップサークル調整 (v0.10 — VirtualGrid `scrollBarOptions.tapScrollCircleOptions` の
+     * エンジン検証素通し。ライブ prop): タッチのタップスクロールサークルの位置・有効 / 無効の
+     * 調整口。検証の SSOT はエンジンの `resolveTapScrollCircleOptions` — undefined はエンジン
+     * 宣言の不在信号 (エンジン既定) で、本パッケージでの値フォールバックなし。
+     */
+    tapScrollCircleOptions?: ScrollBarTapCircleOptions
     /**
      * Identity-stable contract (same as adapter): an inline arrow here defeats the CellView memo
      * and turns every host re-render into a full visible re-slice (~800 cells at 16k columns).
@@ -228,6 +268,39 @@ export type SpreadsheetProps = {
      * Escape は WCAG 2.1.2 のフォーカス脱出)。
      */
     onEditRejected?: (error: unknown, rejection: EditRejection) => void
+    /**
+     * Read-only refusal notice (v0.10): fired once per refused gesture — the adapter was never
+     * called, so this is neither an EditRejection nor an operation limit. Never fired when the
+     * adapter does not declare `isCellReadOnly`; omit for silence.
+     * 読み取り専用拒否通知 (v0.10)。拒否されたジェスチャ毎に 1 回発火 — adapter は呼ばれて
+     * いないため EditRejection でも操作上限でもない。`isCellReadOnly` 未宣言では発火せず、
+     * 省略時は通知なし。
+     */
+    onReadOnlyRejected?: (rejection: ReadOnlyRejection) => void
+    /**
+     * AT announcement text for a read-only refusal (v0.10), routed through the live region;
+     * omit for silence (no built-in strings). Inherits the announcement debounce + rAF collapse,
+     * which is what keeps autorepeat / IME refusal storms from spamming the live region.
+     * 読み取り専用拒否の AT 読み上げ文言 (v0.10) — live region 経由。省略で無音 (組み込み文言
+     * なし)。読み上げのデバウンス + rAF 合流を継承し、autorepeat / IME の拒否連打でも live
+     * region は溢れない。
+     */
+    formatReadOnlyAnnouncement?: (rejection: ReadOnlyRejection) => string
+    /**
+     * Paste outcome summary (v0.10 plan §3.1): the menu channel mirrors `paste(options)`'s
+     * resolve value 1:1 (read refusals and the write-time re-gate included); the event channel
+     * fires once per gesture that reaches the paste pipeline — the drag-freeze consumption and a
+     * null `clipboardData` stay deliberately silent, and an empty grid attaches no listener at
+     * all. Cause-specific callbacks (`onClipboardUnavailable` / `onOperationRejected` /
+     * `onReadOnlyRejected`) fire FIRST — `"rejected"` can be the trailing summary of one of
+     * them. Omit = never fired.
+     * 貼り付け結果の要約 (v0.10 計画 §3.1)。menu チャネルは `paste(options)` の resolve 値の
+     * 1:1 鏡 (読み拒否・書込時再ゲート含む)、event チャネルは貼り付けパイプラインに到達した
+     * ゲスチャ毎 1 回 — ドラッグ凍結消費と `clipboardData` null は意図的無言、空グリッドは
+     * リスナ自体が無い。原因特定系 callback が先に発火し、`"rejected"` はその後追いの要約に
+     * なり得る。省略時は発火なし。
+     */
+    onPasteResolved?: (outcome: PasteOutcome, channel: ClipChannel) => void
     /** Change notice for out-of-package writes (undo / collaboration); each increment repaints visible cells (§6.9-2). / パッケージ外経路のデータ変更通知。 */
     dataVersion?: number
     /** Operation cell-count ceiling, default 100,000 (ADR-12). / 操作セル数上限。 */
@@ -254,12 +327,19 @@ export type SpreadsheetProps = {
      * AT announcement text for the active cell; omit for silence (no built-in strings). `text`
      * is the RAW canonical getCellText; `displayText` is what a sighted user sees (the
      * getCellFormat-formatted string — equals `text` when the cell has no format), so AT can
-     * hear "87.0%" for a cell whose raw value is "0.87".
+     * hear "87.0%" for a cell whose raw value is "0.87". `readOnly` (v0.10) is
+     * declaration-gated three-valued: the key is ABSENT when the adapter does not declare
+     * `isCellReadOnly` (payload byte-identical to v0.9), `false` = declared editable, `true` =
+     * declared read-only — the navigation-time read-only channel (DOM focus stays on the sink,
+     * so `aria-readonly` is inert during Arrow navigation).
      * AT 向け読み上げ文言 (省略で無音)。`text` は素の正準 getCellText、`displayText` は目視と同じ
      * 表示文字列 (getCellFormat 整形後 — 書式なしセルでは text と同値)。素値 "0.87" の表示
-     * "87.0%" をそのまま読み上げられる。
+     * "87.0%" をそのまま読み上げられる。`readOnly` (v0.10) は宣言ゲートの 3 値: `isCellReadOnly`
+     * 未宣言はキー自体なし (payload は v0.9 とバイト同一)、`false` = 宣言済み編集可、`true` =
+     * 宣言済み読み取り専用 — 矢印航行時の読み取り専用チャネル (フォーカスはシンク常駐のため
+     * `aria-readonly` は航行中の AT に届かない)。
      */
-    formatCellAnnouncement?: (ctx: { row: number; col: number; text: string; displayText: string; columnName: string }) => string
+    formatCellAnnouncement?: (ctx: { row: number; col: number; text: string; displayText: string; columnName: string; readOnly?: boolean }) => string
     /** AT announcement for the selection extent ("A1 to C3, 3 rows 3 cols"); omit for silence. / AT 向け選択範囲読み上げ。 */
     formatSelectionAnnouncement?: (ctx: { range: CellRange; anchor: CellCoord; active: CellCoord; rangeRowCount: number; rangeColCount: number; rangeCount: number }) => string
     /**
@@ -417,6 +497,17 @@ const stepZoom = (value: number, direction: 1 | -1): number => (direction > 0 ?
 type SpreadsheetTestProps = {
     /** Test-only CellView re-render counter; never passed in production. / テスト専用カウンタ。 */
     __onCellRender?: ProfilerOnRenderCallback
+    /**
+     * Test-only virtual-keyboard raise spy (v0.10 plan §6.4 / RC-G2t): called synchronously by
+     * the single `raiseVirtualKeyboard` funnel, so spy count ≡ raise executions — a React-batched
+     * raise-then-lower mutates no DOM (`inputmode` observer-blind) yet still counts. Never
+     * passed in production (zero calls when unset — the `__onCellRender` conduct).
+     * テスト専用の仮想キーボード招待スパイ (v0.10 計画 §6.4 / RC-G2t)。単一漏斗
+     * `raiseVirtualKeyboard` が同期で呼ぶため、計数 ≡ raise 実行 — React バッチの
+     * raise-then-lower は DOM 無変異 (`inputmode` の観測は盲目) でも計数には映る。production
+     * では渡さない (未指定 = 呼出しゼロ — `__onCellRender` と同じ品行)。
+     */
+    __onVirtualKeyboardRaise?: () => void
 }
 
 const DEFAULT_ROW_HEIGHT = 24
@@ -525,6 +616,9 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
         defaultColumnWidth = DEFAULT_COLUMN_WIDTH,
         frozenColumns = 0,
         frozenRows = 0,
+        frozenTrailingColumns = 0,
+        frozenTrailingRows = 0,
+        tapScrollCircleOptions,
         renderCell,
         onSelectionChange,
         onCellContextMenu,
@@ -533,6 +627,8 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
         onCopyMultiRange,
         onOperationRejected,
         onEditRejected,
+        onReadOnlyRejected,
+        formatReadOnlyAnnouncement,
         dataVersion,
         maxOperationCells = DEFAULT_MAX_OPERATION_CELLS,
         enableFillHandle = true,
@@ -555,6 +651,7 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
         onValidationRejected,
         onPasteSpecialRequest,
         onClipboardUnavailable,
+        onPasteResolved,
         now = Date.now,
         zoom,
         defaultZoom,
@@ -562,6 +659,7 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
         testId,
         className,
         __onCellRender,
+        __onVirtualKeyboardRaise,
     }: SpreadsheetProps & SpreadsheetTestProps,
     ref,
 ): ReactNode {
@@ -747,6 +845,16 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
     const windowOriginYRef = useRef(0)
     const colTrackRef = useRef<HTMLDivElement | null>(null)
     const windowOriginXRef = useRef(0)
+    // ヘッダー帯要素 (選択機械 / オートスクローラーの結線先 — 従来はオートスクローラー節で宣言)
+    const colHeaderRef = useRef<HTMLDivElement | null>(null)
+    const rowHeaderRef = useRef<HTMLDivElement | null>(null)
+    // ヘッダー分割線セグメントのマウント時キャッシュ (v0.9 §2.4 / §4.9 census #12/#13):
+    // ヘッダー再描画は同期横パス上の毎通知呼びのため、querySelector 走査ではなく JSX ref で
+    // 装着済みノードを直読みする (存在は件数駆動 render 双子 — アンマウントで React が null へ戻す)
+    const dividerXLeadingRef = useRef<HTMLDivElement | null>(null)
+    const dividerXTrailingRef = useRef<HTMLDivElement | null>(null)
+    const dividerYLeadingRef = useRef<HTMLDivElement | null>(null)
+    const dividerYTrailingRef = useRef<HTMLDivElement | null>(null)
     const liveRegionRef = useRef<HTMLDivElement | null>(null)
 
     // ---- 選択状態 (React state + 命令読み ref — §6.9-1) ----
@@ -873,11 +981,42 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
     }, [])
 
     /**
-     * Repaints ONLY the row-header track residual transform. Callers: onScroll, resizeRow, and
+     * Equality-suppressed display heal of one header divider segment (v0.9 §4.9 census #12/#13):
+     * visibility = band TREE px > 0; existence is the header's count-driven render twin and the
+     * geometry stays clip-owned, so this display flip is the ONLY divider write the header
+     * repaint path ever makes. The segment arrives through the mount-cached JSX ref (never a
+     * per-notification querySelector traversal — the synchronous horizontal pass must not pay
+     * a selector scan, least of all a guaranteed miss at F = T = 0). A same-value pass writes
+     * nothing — the §5.7 zero-write invariant observes both header repaint writers.
+     * ヘッダー分割線セグメント 1 つの等値抑制 display heal (v0.9 §4.9 census #12/#13)。可視 =
+     * 帯 TREE px > 0。存在はヘッダーの件数駆動 render 双子、幾何はクリップ所有のままで、ヘッダー
+     * 再描画が分割線へ行う書込はこの display フリップだけ。セグメントはマウント時キャッシュの
+     * JSX ref 経由 (毎通知の querySelector 走査は同期横パスに載せない — F = T = 0 では全走査
+     * ミスが保証される)。同値パスは無書込 — §5.7 のゼロ書込不変量が両書き手を観測する。
+     */
+    const healHeaderDivider = useCallback((segment: HTMLElement | null, shown: boolean) => {
+        // 件数 0 の家族はセグメント未マウント (ref は null) — 無仕事で戻る
+        if (segment === null) {
+            return
+        }
+        const next = shown ? "" : "none"
+        // 等値抑制 — 定常スクロール wheel 窓中の分割線 style 書込 = 0 の不変量 (§2.4 / §5.7)
+        if (segment.style.display !== next) {
+            segment.style.display = next
+        }
+    }, [])
+
+    /**
+     * Repaints the row-header track residual transform. Callers: onScroll, resizeRow, and
      * RowHeader's layout effect. vy comes from the grid handle (the truth — §7-4; the v0.6 −H_F
-     * frozen-band term makes this the exact twin of repaintColHeaders).
-     * 行 track の残差 transform のみを書く命令再描画。vy はグリッドハンドル (§7-4 の真実) から読む
-     * (v0.6 の −H_F 凍結帯項で repaintColHeaders の完全双子)。
+     * frozen-band term makes this the exact twin of repaintColHeaders). v0.9 adds the
+     * equality-suppressed display heal of the two y header divider segments (§4.9 census #12 —
+     * NO geometry write: the scroll-clip insets are the registered calc() forms that re-resolve
+     * through 100% by themselves).
+     * 行 track の残差 transform を書く命令再描画。vy はグリッドハンドル (§7-4 の真実) から読む
+     * (v0.6 の −H_F 凍結帯項で repaintColHeaders の完全双子)。v0.9 で y ヘッダー分割線 2 セグメント
+     * の等値抑制 display heal を追加 (§4.9 census #12 — 幾何書込なし: scroll クリップのインセットは
+     * 登記 calc() 形が 100% 再解決で自癒する)。
      */
     const repaintHeaders = useCallback(() => {
         const track = rowTrackRef.current
@@ -888,14 +1027,27 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
             const frozenHeight = handleRef.current?.getFrozenSize().height ?? 0
             track.style.transform = `translateY(${windowOriginYRef.current - vy - frozenHeight}px)`
         }
-    }, [])
+        // v0.9 (§4.9 census #12): y ヘッダー分割線の可視 heal — 可視 = 帯 TREE px > 0 (H_F / H_T の
+        // ハンドルフィールド)。ハンドル未装着は無書込 (JSX 初期状態のまま = 件数 render が真実)。
+        // 両セグメント未マウント (R = T = 0) は getFrozenSize 読みごと省く — 同期横パスの無仕事保証
+        const handle = handleRef.current
+        if (handle !== null && (dividerYLeadingRef.current !== null || dividerYTrailingRef.current !== null)) {
+            const frozen = handle.getFrozenSize()
+            healHeaderDivider(dividerYLeadingRef.current, frozen.height > 0)
+            healHeaderDivider(dividerYTrailingRef.current, frozen.trailingHeight > 0)
+        }
+    }, [healHeaderDivider])
 
     /**
-     * Repaints ONLY the column-header track residual transform (§7-5 — the row repaintHeaders
+     * Repaints the column-header track residual transform (§7-5 — the row repaintHeaders
      * twin; the v0.3 --aqsp-hx CSS variable is retired). hx comes from the grid handle (the
-     * truth — §7-4). Callers: onScroll, resize tails, and ColumnHeader's layout effect.
-     * 列 track の残差 transform のみを書く命令再描画 (§7-5 — 行 repaintHeaders の双子。v0.3 の
-     * --aqsp-hx CSS 変数は退役)。hx はグリッドハンドル (§7-4 の真実) から読む。
+     * truth — §7-4). Callers: onScroll, resize tails, and ColumnHeader's layout effect. v0.9
+     * adds the equality-suppressed display heal of the two x header divider segments (§4.9
+     * census #13 — NO geometry write, the exact twin of repaintHeaders).
+     * 列 track の残差 transform を書く命令再描画 (§7-5 — 行 repaintHeaders の双子。v0.3 の
+     * --aqsp-hx CSS 変数は退役)。hx はグリッドハンドル (§7-4 の真実) から読む。v0.9 で x ヘッダー
+     * 分割線 2 セグメントの等値抑制 display heal を追加 (§4.9 census #13 — 幾何書込なし、
+     * repaintHeaders の完全双子)。
      */
     const repaintColHeaders = useCallback(() => {
         const track = colTrackRef.current
@@ -906,7 +1058,61 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
             const frozenWidth = handleRef.current?.getFrozenSize().width ?? 0
             track.style.transform = `translateX(${windowOriginXRef.current - hx - frozenWidth}px)`
         }
-    }, [])
+        // v0.9 (§4.9 census #13): x ヘッダー分割線の可視 heal (W_F / W_T の TREE px 駆動 — 行と同文。
+        // 両セグメント未マウント (F = T = 0) は getFrozenSize 読みごと省く)
+        const handle = handleRef.current
+        if (handle !== null && (dividerXLeadingRef.current !== null || dividerXTrailingRef.current !== null)) {
+            const frozen = handle.getFrozenSize()
+            healHeaderDivider(dividerXLeadingRef.current, frozen.width > 0)
+            healHeaderDivider(dividerXTrailingRef.current, frozen.trailingWidth > 0)
+        }
+    }, [healHeaderDivider])
+
+    // ---- 分割線可視の post-commit heal (v0.9 §2.4 / §2.7) ----
+    const dividerHealRafRef = useRef<number | null>(null)
+    /**
+     * Schedules ONE post-commit divider-visibility heal after a track-resize seam (v0.9 §2.7 —
+     * "T_px = 0 ⇒ no divider" must hold without an interposed scroll). The seam's synchronous
+     * repaint reads the engine's render-captured getFrozenSize (a registered per-render mapping)
+     * BEFORE the engine has re-rendered the new track size, so the divider display would
+     * otherwise lag one geometry transition until the next write pass. One coalesced rAF
+     * re-runs the three imperative writers from the committed getFrozenSize; the equality
+     * suppression keeps this a zero-write pass unless a visibility flip is actually due, and
+     * the F = T = 0 configuration schedules nothing (v0.8 identity — no reservation either).
+     * トラックリサイズシーム後の分割線可視 post-commit heal を 1 回予約 (v0.9 §2.7 —
+     * 「T_px = 0 ⇒ 分割線なし」はスクロール介在なしで成立が要件)。シームの同期 repaint は
+     * エンジンの render 捕捉 getFrozenSize (登記済み毎レンダー写像) をエンジン再レンダー**前**に
+     * 読むため、放置すると分割線 display が次の書込パスまで 1 遷移遅れる。合流 rAF 1 回で
+     * commit 済み getFrozenSize から命令書き手 3 つを再実行 — 等値抑制によりフリップ不要なら
+     * 無書込パス、F = T = 0 構成は予約ごと省く (v0.8 恒等)。
+     */
+    const scheduleDividerHeal = useCallback(() => {
+        // 分割線セグメントが 1 本も存在しない構成 (F = T = 0) は heal 対象なし — 予約も残さない
+        if (dividerXLeadingRef.current === null && dividerXTrailingRef.current === null && dividerYLeadingRef.current === null && dividerYTrailingRef.current === null) {
+            return
+        }
+        // 合流 (バッチリサイズの多発呼びでも 1 フレーム 1 heal)
+        if (dividerHealRafRef.current !== null) {
+            return
+        }
+        dividerHealRafRef.current = requestAnimationFrame(() => {
+            dividerHealRafRef.current = null
+            // ヘッダー 2 面 + overlay (胴体セグメントは layersFor が同パスで heal する) — commit 済み
+            // getFrozenSize からの再実行。残差 transform / 幾何は同値再書込 (エンジンが既に確定済み)
+            repaintHeaders()
+            repaintColHeaders()
+            repaintOverlay()
+        })
+    }, [repaintHeaders, repaintColHeaders, repaintOverlay])
+    // アンマウント時に予約中の heal rAF を回収 (本パッケージの全タイマ / rAF 回収規律)
+    useEffect(
+        () => () => {
+            if (dividerHealRafRef.current !== null) {
+                cancelAnimationFrame(dividerHealRafRef.current)
+            }
+        },
+        [],
+    )
 
     // ensureCellVisible: §6.6.3 の自前 nearest (1 回構築して keyboard / Shift+F10 へ配布 — §6.9-7)。
     // 軸 identity が変わったら作り直す (クロージャが旧軸を掴む stale を防ぐ)
@@ -961,6 +1167,28 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
         [],
     )
 
+    /**
+     * The single read-only refusal funnel (v0.10 plan §6.4 — the SSOT of RC-ANN / RC-B): every
+     * gate (G1..G16) delivers its rejection here, which relays the callback AND the announcement
+     * (`formatReadOnlyAnnouncement` → `announce()` — the debounce is inherited). Both props
+     * omitted = silence = byte-identical; the read-only refusal never rides `onEditRejected` /
+     * `onOperationRejected` (channel purity).
+     * 読み取り専用拒否の単一漏斗 (v0.10 計画 §6.4 — RC-ANN / RC-B の SSOT)。全ゲート (G1..G16)
+     * の拒否はここへ集まり、callback と読み上げ (`formatReadOnlyAnnouncement` → `announce()` —
+     * デバウンス継承) の両方を運ぶ。両 prop 省略 = 無音 = バイト恒等。読み取り専用拒否を
+     * `onEditRejected` / `onOperationRejected` へ流用しない (チャネル純度)。
+     */
+    const rejectReadOnly = useCallback(
+        (rejection: ReadOnlyRejection) => {
+            onReadOnlyRejected?.(rejection)
+            // 読み上げは prop 宣言時だけ (省略 = 無音 — 組み込み文言なしの家訓)
+            if (formatReadOnlyAnnouncement !== undefined) {
+                announce(formatReadOnlyAnnouncement(rejection))
+            }
+        },
+        [onReadOnlyRejected, formatReadOnlyAnnouncement, announce],
+    )
+
     /** The 3-tier announcement rule (§6.9-9, evaluated top-down). / 3 段機械判定 (上から順)。 */
     const evaluateAnnouncement = useCallback(
         (prev: SelectionState, next: SelectionState) => {
@@ -978,7 +1206,18 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
                     const raw = adapter.getCellText(a.row, a.col)
                     // displayText は目視と同一の整形後文字列 (塗り書式 = base ⊕ CF — getCellFormat 未宣言は raw と同値)
                     const painted = adapter.getCellFormat === undefined ? undefined : paintedFormatOf(a.row, a.col, () => raw)
-                    announce(formatCellAnnouncement({ row: a.row, col: a.col, text: raw, displayText: formatCellValue(raw, painted === undefined ? undefined : painted.value), columnName: columnIndexToName(a.col) }))
+                    // S2 (v0.10 §6.4): readOnly キーは宣言ゲート — isCellReadOnly 未宣言はキー自体を出さず
+                    // payload は v0.9 とバイト同一、宣言時は正負両真理のライブ回答 (RC-S2)
+                    announce(
+                        formatCellAnnouncement({
+                            row: a.row,
+                            col: a.col,
+                            text: raw,
+                            displayText: formatCellValue(raw, painted === undefined ? undefined : painted.value),
+                            columnName: columnIndexToName(a.col),
+                            ...(readOnlyDeclared(adapter) ? { readOnly: isReadOnlyCell(adapter, a.row, a.col) } : {}),
+                        }),
+                    )
                 }
             }
             // (1) 単一 1×1 レンジ → セル読み上げ (素のクリック / 矢印移動)
@@ -1092,14 +1331,37 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
     //      OnTextInputTypeChanged で進行中の変換を強制終了する: 未編集 → IME 1 文字 → Enter が
     //      落ちた利用者報告の根因 — セッション基準の切替は compositionstart の中で属性を変えていた)
     const [virtualKeyboard, setVirtualKeyboard] = useState(false)
+    /**
+     * The ONE invitation-raising funnel (v0.10 plan §6.4 / RC-G2t): `setVirtualKeyboard(true)`
+     * has exactly this production site, so the test seam's spy count ≡ raise executions by
+     * construction — a React-batched raise-then-lower mutates no DOM yet still counts. The two
+     * LOWERING sites (`onRootBlur`, the non-mouse root-capture pointerdown) call
+     * `setVirtualKeyboard(false)` directly. The uniqueness invariant is machine-sealed by the
+     * side-(iv) census of `readOnlyCensus.spec.ts` (a second raise site cannot land silently).
+     * 招待 raise の単一漏斗 (v0.10 計画 §6.4 / RC-G2t)。`setVirtualKeyboard(true)` の production
+     * 出現はここだけ — テストシームのスパイ計数 ≡ raise 実行が構成的に成立し、React バッチの
+     * raise-then-lower も DOM 無変異のまま計数に映る。下ろし 2 サイト (`onRootBlur` / 非 mouse の
+     * root capture pointerdown) は `setVirtualKeyboard(false)` を直呼びのまま。単一性の不変条件は
+     * `readOnlyCensus.spec.ts` の側 (iv) census が機械封印 (第 2 raise サイトは無音で着地できない)。
+     */
+    const raiseVirtualKeyboard = useCallback(() => {
+        __onVirtualKeyboardRaise?.()
+        setVirtualKeyboard(true)
+    }, [__onVirtualKeyboardRaise])
     const onRequestEdit = useCallback(
-        (_cell: CellCoord, caretIndex?: number) => {
-            // ポインタで開くエディタだけが仮想キーボードを招待する (キーボード無し端末で開ける唯一の経路)。
-            // 変換は進行中でない (dblclick 押下面が先に requestCommit 済み) — 属性変更は安全
-            setVirtualKeyboard(true)
+        (cell: CellCoord, caretIndex?: number) => {
+            // G2 (v0.10 §6.4 / 設計 ADR-29 v3.1 — 招待前置が規範): raise は startEdit より先に走る
+            // ため、読み取り専用セルでは招待自体をスキップする。G1 だけでは OSK が拒否より先に
+            // 上がってしまう (キーボード無し端末のフラッシュ)。skip でも startEdit は呼ぶ —
+            // 拒否発火サイトは G1 の 1 箇所 (SSOT)。能力未宣言は従来どおり無条件 raise (バイト恒等)
+            if (!isReadOnlyCell(adapter, cell.row, cell.col)) {
+                // ポインタで開くエディタだけが仮想キーボードを招待する (キーボード無し端末で開ける唯一の経路)。
+                // 変換は進行中でない (dblclick 押下面が先に requestCommit 済み) — 属性変更は安全
+                raiseVirtualKeyboard()
+            }
             startEdit("edit", caretIndex)
         },
-        [startEdit],
+        [adapter, raiseVirtualKeyboard, startEdit],
     )
     const getClipRef = useRef<(() => ClipInfo | null) | null>(null)
     const getClip = useCallback(() => getClipRef.current?.() ?? null, [])
@@ -1265,6 +1527,9 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
                 viewStore.bumpColVersion()
                 repaintColHeaders()
                 repaintOverlay()
+                // 同期 repaint はエンジン再レンダー前の stale getFrozenSize — 分割線可視は
+                // post-commit heal が commit 済み値で整合させる (§2.7 — スクロール介在なし)
+                scheduleDividerHeal()
                 return
             }
             for (const entry of entries) {
@@ -1276,8 +1541,10 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
             viewStore.bumpRowGeometry()
             repaintHeaders()
             repaintOverlay()
+            // 行側も同文 (H_F / H_T の分割線可視は commit 済み値で heal — §2.7)
+            scheduleDividerHeal()
         },
-        [rowAxis, colAxis, viewStore, repaintColHeaders, repaintHeaders, repaintOverlay],
+        [rowAxis, colAxis, viewStore, repaintColHeaders, repaintHeaders, repaintOverlay, scheduleDividerHeal],
     )
 
     /** Pointer contextmenu relay to onCellContextMenu (§6.4.3-4 sole channel). / pointer 起点の横流し。 */
@@ -1290,8 +1557,6 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
 
     // ---- オートスクローラー 3 種 (セル both / 列ヘッダー x / 行ヘッダー y — §6.4.4 / §6.8) ----
     const cellAutoScroller = useAutoScroller({ handleRef, rowAxis, colAxis, bodyRef, onDragFrame, axis: "both", zoomRef })
-    const colHeaderRef = useRef<HTMLDivElement | null>(null)
-    const rowHeaderRef = useRef<HTMLDivElement | null>(null)
     const colAutoScroller = useAutoScroller({ handleRef, rowAxis, colAxis, bodyRef, onDragFrame, axis: "x", zoomRef })
     const rowAutoScroller = useAutoScroller({ handleRef, rowAxis, colAxis, bodyRef, onDragFrame, axis: "y", zoomRef })
     // fill 専用の軸別 2 インスタンス (§8.2 — writer も axis も構築時固定。v0.3 のボックス方式では
@@ -1455,6 +1720,8 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
         commitEdits,
         maxOperationCells,
         onOperationRejected,
+        // v0.10: G7 の拒否漏斗 (§6.4)
+        rejectReadOnly,
         writeFillPreview: onFillFrame,
         repaintOverlay,
         xAutoScroller: fillXAutoScroller,
@@ -1545,6 +1812,8 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
         rearmSink,
         discardClip,
         isDragging: isAnyDragging,
+        // v0.10: G1 / G16 の拒否漏斗 (callback + 読み上げの SSOT — §6.4)
+        rejectReadOnly,
         // Excel 同様、編集中もセルの水平揃えを保つ (数値セルは右揃えのまま編集)。getCellFormat 未宣言は
         // null = v0.1 恒等 (textarea の text-align を触らない)。宣言時は塗り書式 (base ⊕ CF) で判定し
         // text は遅延 1 回読み (v0.8 §4.2.13)
@@ -1606,6 +1875,9 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
         onClipChange,
         onClipboardUnavailable,
         onEditRejected,
+        // v0.10: G4 / G5 / G6a / G6b の拒否漏斗 (§6.4) + 貼り付け結果の要約 (§3.1)
+        rejectReadOnly,
+        onPasteResolved,
     })
     getClipRef.current = clipboard.getClip
     discardClipRef.current = clipboard.discardClip
@@ -1635,25 +1907,31 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
         onHyperlinkOpen,
         anchors: popoverAnchorsRef,
         repaintOverlay,
+        // v0.10: G14a / G14b / G14c の拒否漏斗 (§6.4)
+        rejectReadOnly,
     })
     popoversRef.current = popovers
     openPopoverRef.current = popovers.open
     hideNoteTipRef.current = popovers.hideTip
 
     // ---- コマンド実行 (v0.8 §4.1.13 / ADR-17) ----
-    /** The active cell's viewport rect in visual px — the keyboard-origin cellRect recipe (onCellContextMenu twin) for onPasteSpecialRequest. / active セルの視覚 px 矩形 (keyboard 起点 cellRect のレシピ — onCellContextMenu と同式)。 */
+    /** The active cell's viewport rect in visual px via the three-way forward map (v0.9 §4.9 census #11 — the keyboard-origin cellRect recipe, onCellContextMenu twin) for onPasteSpecialRequest. / active セルの視覚 px 矩形 — 3 分岐順写像 (v0.9 §4.9 census #11。keyboard 起点 cellRect のレシピ、onCellContextMenu と同式)。 */
     const keyboardCellRect = useCallback(() => {
         const active = selectionRef.current.active
         // 画面外座標へメニューを出さない (§6.6.1) — 可視化してからハンドルの同期読み (§7-4)
         ensureCellVisible(active)
         const handle = handleRef.current
         const position = handle === null ? { x: 0, y: 0 } : handle.getScrollPosition()
-        const frozen = handle === null ? { rows: 0, cols: 0 } : handle.getFrozenSize()
+        // 帯件数と extent も同じ判断で読む (v0.9 計画 §4.9、census #11 — AxisForwardCtx はこの場で
+        // インライン構築、§2.1 規則 1)。detached ハンドルは件数 0 / extent 0 の縮退 (末尾分岐不活性 = v0.8 恒等)
+        const frozen = handle === null ? { rows: 0, cols: 0, trailingRows: 0, trailingCols: 0 } : handle.getFrozenSize()
+        const viewport = handle === null ? { width: 0, height: 0 } : handle.getViewportSize()
         // 両軸とも番兵クランプ (detached の {-1, -1} を座標へ流さない)、ズーム境界で視覚 px へ
         const z = zoomRef.current
         return {
-            top: rowToViewportY(rowAxis, active.row, Math.max(0, position.y), frozen.rows) * z,
-            left: colToViewportX(colAxis, active.col, Math.max(0, position.x), frozen.cols) * z,
+            // 行 / 列とも凍結パーティション 3 分岐順写像 (末尾は extent アンカー — v0.9 §2.1)。×zoom は写像後 (契約不変)
+            top: rowToViewportY(rowAxis, active.row, { scroll: Math.max(0, position.y), frozenCount: frozen.rows, trailingCount: frozen.trailingRows, extent: viewport.height }) * z,
+            left: colToViewportX(colAxis, active.col, { scroll: Math.max(0, position.x), frozenCount: frozen.cols, trailingCount: frozen.trailingCols, extent: viewport.width }) * z,
             width: colAxis.sizeOf(active.col) * z,
             height: rowAxis.sizeOf(active.row) * z,
         }
@@ -1690,6 +1968,8 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
         announce,
         formatCommandAnnouncement,
         keyboardCellRect,
+        // v0.10: G8–G13 / G15 の拒否漏斗 (§6.4)
+        rejectReadOnly,
     })
     commandsRef.current = commands
     executeCommandRef.current = commands.executeCommand
@@ -1724,6 +2004,8 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
         commitEdits,
         maxOperationCells,
         onOperationRejected,
+        // v0.10: G3 (Delete / Backspace) の拒否漏斗 (§6.4)
+        rejectReadOnly,
         getClip,
         discardClip,
         isDragging: isDraggingAny,
@@ -2072,12 +2354,18 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
     // 同じ stale 座標遮断だが、座標系は同一グリッドのため選択と編集セッションは保持する
     const prevFrozenColsRef = useRef(frozenColumns)
     const prevFrozenRowsRef = useRef(frozenRows)
+    // v0.9 (§4.9 census #21 — FZ46 教訓): 末尾 2 props も同じ取消 OR に参加する (4 props の
+    // どれかの変化 = 旧 3 分岐パーティションの押下時アンカーが全て陳腐化する)
+    const prevTrailingColsRef = useRef(frozenTrailingColumns)
+    const prevTrailingRowsRef = useRef(frozenTrailingRows)
     useLayoutEffect(() => {
-        // 列 / 行いずれの凍結変更も飛行中ドラッグを復元なしで取り消す (R2 是正の縦拡張 —
-        // 押下時アンカーは旧パーティション座標系。混成ヒットで誤 fill 確定を防ぐ)
-        if (prevFrozenColsRef.current !== frozenColumns || prevFrozenRowsRef.current !== frozenRows) {
+        // 列 / 行・先頭 / 末尾いずれの凍結変更も飛行中ドラッグを復元なしで取り消す (R2 是正の縦拡張 +
+        // v0.9 の末尾拡張 — 押下時アンカーは旧パーティション座標系。混成ヒットで誤 fill 確定を防ぐ)
+        if (prevFrozenColsRef.current !== frozenColumns || prevFrozenRowsRef.current !== frozenRows || prevTrailingColsRef.current !== frozenTrailingColumns || prevTrailingRowsRef.current !== frozenTrailingRows) {
             prevFrozenColsRef.current = frozenColumns
             prevFrozenRowsRef.current = frozenRows
+            prevTrailingColsRef.current = frozenTrailingColumns
+            prevTrailingRowsRef.current = frozenTrailingRows
             engine.cancelDrag()
             colHeaderMachine.cancelDrag()
             rowHeaderMachine.cancelDrag()
@@ -2088,7 +2376,19 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
             // (cancelDrag は abortDrag と違いシンク断面を復元しない)
             pointDrag.cancelDrag()
         }
-    }, [frozenColumns, frozenRows, engine, colHeaderMachine, rowHeaderMachine, headerResizeMachine, fillMachine, pointDrag])
+    }, [frozenColumns, frozenRows, frozenTrailingColumns, frozenTrailingRows, engine, colHeaderMachine, rowHeaderMachine, headerResizeMachine, fillMachine, pointDrag])
+
+    // ---- 凍結 props フリップの分割線可視整合 (v0.9 §2.4 / §2.7) ----
+    // フリップの同一 commit 内でエンジンは新 props で render 済み (毎レンダー写像の getFrozenSize は
+    // layout effect 時点で確定値)。非表示トラックを含む帯へのフリップ (例: 全 track 幅 0 の列を F = 1 で
+    // 凍結) では新規マウントの分割線セグメントが JSX 初期 display "" のまま px = 0 になるため、
+    // paint 前にここで heal する — スクロール介在なしで「px = 0 ⇒ 分割線なし」を成立させる (§2.7)。
+    // F = T = 0 では両ヘッダー書き手が getFrozenSize 読みごと省き、残差 transform の同値再書込のみ
+    useLayoutEffect(() => {
+        repaintHeaders()
+        repaintColHeaders()
+        repaintOverlay()
+    }, [frozenColumns, frozenRows, frozenTrailingColumns, frozenTrailingRows, repaintHeaders, repaintColHeaders, repaintOverlay])
 
     // ---- dataVersion (外部書込通知 §6.9-2 (b) — Undo / 協調編集) もクリップの破棄条件 ----
     // adapter 外で値が書き戻ると cut 時行列のまま照合が通り、古い指紋の move が外部値を "" で
@@ -2129,6 +2429,8 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
                 // §6.8-2 の順序契約の設計内猶予。自己修復するため実害なし)
                 repaintHeaders()
                 repaintOverlay()
+                // 分割線可視は commit 済み getFrozenSize の post-commit heal で整合 (§2.7)
+                scheduleDividerHeal()
             },
             resizeColumn: (col: number, widthPx: number) => {
                 // 対呼び出し (§3.8): colAxis (SSOT) を先に更新し、グリッドの幅木へ通知する。
@@ -2141,6 +2443,8 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
                 viewStore.bumpColVersion()
                 repaintColHeaders()
                 repaintOverlay()
+                // 分割線可視は commit 済み getFrozenSize の post-commit heal で整合 (§2.7)
+                scheduleDividerHeal()
             },
             scrollToCell: (cell: CellCoord, options?: ScrollToCellOptions) => {
                 // エンジンのセル狙いジャンプへ素通し (§7-4 の真実。選択は変えない — 純 viewport 移動)。
@@ -2175,7 +2479,7 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
                 openPopoverRef.current(kind)
             },
         }),
-        [rowAxis, colAxis, viewStore, repaintColHeaders, repaintHeaders, repaintOverlay, focusSink, isEditing, rearmSink, adapter, paintedFormatOf, startEdit, requireCommands],
+        [rowAxis, colAxis, viewStore, repaintColHeaders, repaintHeaders, repaintOverlay, scheduleDividerHeal, focusSink, isEditing, rearmSink, adapter, paintedFormatOf, startEdit, requireCommands],
     )
 
     // ---- 空グリッド分岐 (§6.9-1: フックの後・結線の前) ----
@@ -2184,7 +2488,8 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
     }
 
     // live region は読み上げ prop のどれか 1 つでも宣言されたときだけ描く (コマンド通知も同じ領域へ)
-    const hasAnnouncement = formatCellAnnouncement !== undefined || formatSelectionAnnouncement !== undefined || formatCommandAnnouncement !== undefined
+    // v0.10: formatReadOnlyAnnouncement も live region の存在条件 (拒否読み上げは announce() 経由 — §6.4)
+    const hasAnnouncement = formatCellAnnouncement !== undefined || formatSelectionAnnouncement !== undefined || formatCommandAnnouncement !== undefined || formatReadOnlyAnnouncement !== undefined
 
     return (
         // biome-ignore lint/a11y/useSemanticElements: fieldset はフォーム意味論であり不適。role="group" は Escape 脱出の着地点に現在地名を与えるための選択 (§6.9-7 / §10-4)
@@ -2231,6 +2536,7 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
                     viewStore={viewStore}
                     colAxis={colAxis}
                     frozenCols={frozenColumns}
+                    frozenTrailingCols={frozenTrailingColumns}
                     handleRef={handleRef}
                     bandRef={colHeaderRef}
                     colTrackRef={colTrackRef}
@@ -2238,6 +2544,8 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
                     repaintColHeaders={repaintColHeaders}
                     selectionRanges={selection.ranges}
                     enableResizeUI={enableResizeUI}
+                    dividerLeadingRef={dividerXLeadingRef}
+                    dividerTrailingRef={dividerXTrailingRef}
                 />
                 <RowHeader
                     viewStore={viewStore}
@@ -2250,6 +2558,9 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
                     repaintHeaders={repaintHeaders}
                     enableResizeUI={enableResizeUI}
                     frozenRows={frozenRows}
+                    frozenTrailingRows={frozenTrailingRows}
+                    dividerLeadingRef={dividerYLeadingRef}
+                    dividerTrailingRef={dividerYTrailingRef}
                 />
                 <div className="aqsp-body-stack" data-aqsp-body-stack="">
                     <GridBody
@@ -2263,6 +2574,9 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
                         defaultColumnWidth={defaultColumnWidth}
                         frozenColumns={frozenColumns}
                         frozenRows={frozenRows}
+                        frozenTrailingColumns={frozenTrailingColumns}
+                        frozenTrailingRows={frozenTrailingRows}
+                        tapScrollCircleOptions={tapScrollCircleOptions}
                         renderCell={renderCell}
                         onScroll={onScroll}
                         onRangeChange={onRangeChange}
@@ -2294,6 +2608,8 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
                         enableFillHandle={enableFillHandle}
                         frozenCols={frozenColumns}
                         frozenRows={frozenRows}
+                        trailingCols={frozenTrailingColumns}
+                        trailingRows={frozenTrailingRows}
                         sinkAriaLabel={resolvedLabels.sinkAriaLabel}
                         onSinkMouseDown={onSinkMouseDown}
                         editPaintRef={editPaintRef}