@aiquants/spreadsheet 0.10.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiquants/spreadsheet",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Excel-grade spreadsheet grid for React: multi-cell selection, TSV/HTML clipboard, in-place editing on top of @aiquants/virtualscroll",
   "sideEffects": [
     "**/*.css"

package/src/Spreadsheet.tsx

@@ -73,7 +73,7 @@ import { DEFAULT_HIGHLIGHT_COLORS, type DragFrameMode, type HighlightColors, typ
 import { useFillHandle } from "./overlay/useFillHandle.ts"
 import { PopoverLayer } from "./popover/PopoverLayer.tsx"
 import { type PopoverAnchorState, type PopoverContext, type PopoverController, type PopoverKind, type PopoverOpenOptions, type PopoverOverrides, usePopovers } from "./popover/usePopovers.ts"
-import { reduceActiveCycle, reduceSelectionExtend, reduceSelectionPress, type SelectionState, selectionStateEquals } from "./selection/selectionState.ts"
+import { clampSelectionToGrid, reduceActiveCycle, reduceSelectionExtend, reduceSelectionPress, type SelectionState, selectionStateEquals } from "./selection/selectionState.ts"
 import { useAutoScroller } from "./selection/useAutoScroller.ts"
 import { type PointDragOwner, usePointDrag } from "./selection/usePointDrag.ts"
 import { useSelectionEngine } from "./selection/useSelectionEngine.ts"
@@ -217,10 +217,92 @@ export type SpreadsheetProps = {
      * 宣言の不在信号 (エンジン既定) で、本パッケージでの値フォールバックなし。
      */
     tapScrollCircleOptions?: ScrollBarTapCircleOptions
+    /**
+     * Row-axis overscan pass-through (the VirtualGrid `overscanRows` knob; LIVE prop): rows
+     * rendered beyond each vertical viewport edge. This slack is the only thing absorbing the
+     * engine's one-frame rendering-window lag during fast scrolling (the blank-band remedy).
+     * Overscan counts ROWS — hidden 0-height rows consume slots too — so the px slack per edge
+     * is overscan × row height only where rows are uniform and visible. Undefined ⇒ the engine
+     * default (3). The engine does not validate overscan (a negative value silently shrinks the
+     * rendering window), so THIS surface owns the fail-fast: a non-integer or negative value
+     * throws a RangeError at render. Cost multiplies with the column axis, and the engine
+     * TRUNCATES rather than bounds: a window beyond its per-axis row budget or its total cell
+     * cap keeps the LEADING side and drops the trailing side — the row-budget case has no
+     * callback (the engine only logs a warning), the cell-cap case (columns dropped) reports
+     * through `onRenderTruncated`. Values of
+     * hundreds of rows per side approach that budget on tall viewports; keep overscan to the
+     * slack you need.
+     * 行軸 overscan の素通し (VirtualGrid `overscanRows`。ライブ prop): 縦 viewport 端の外側へ
+     * 描画する行数。高速スクロール時の描画窓 1 フレーム遅れを吸収する唯一の余裕 (白帯対策)。
+     * overscan は**行数**で数える (非表示の 0px 行も枠を消費) ため、片端の余裕 px が overscan ×
+     * 行高になるのは行が一様に可視のときだけ。undefined はエンジン既定 (3)。エンジンは overscan を
+     * 検証しない (負値は描画窓を無言で縮める) ため fail-fast は本層所有 — 非整数・負値は render 時
+     * RangeError。費用は列軸との積で増幅し、エンジンは有界化でなく**打切り**で応じる: 軸毎の行予算
+     * や総セル上限を超えた窓は先頭側を残し末尾側を落とす — 行予算超過はコールバック無し (エンジンは
+     * warn ログのみ)、セル上限超過 (列の脱落) は `onRenderTruncated` で通知。片側数百行の値は高い viewport で予算に迫るため、必要な
+     * 余裕にとどめる。
+     */
+    overscanRows?: number
+    /**
+     * Column-axis overscan pass-through (the VirtualGrid `overscanCols` knob; LIVE prop) — the
+     * column twin of `overscanRows`, same validation contract (non-negative integer or
+     * RangeError; undefined ⇒ engine default 3).
+     * 列軸 overscan の素通し (VirtualGrid `overscanCols`。ライブ prop) — `overscanRows` の
+     * 列双子。検証契約は同文 (非負整数、それ以外 RangeError。undefined ⇒ エンジン既定 3)。
+     */
+    overscanCols?: number
+    /**
+     * Background layer rendered behind the scroll-band rows, inside the engine content element
+     * (the VirtualGrid `background` pass-through; LIVE prop). VIEWPORT-PINNED: the engine
+     * translates only its row wrapper, so this layer does NOT follow the scroll offset —
+     * periodic row ruling placed here slides against the real rows while scrolling. Suited to
+     * a static texture that reads as "content still arriving" in the overscan-exhausted band,
+     * not to row-aligned gridlines. The layer spans the full width of the scroll rows — the
+     * frozen-COLUMN region included (frozen columns live inside the scroll rows) — but not the
+     * frozen row bands. Identity-stable contract (same as `renderCell`): an inline element here
+     * pierces the GridBody memo boundary on every host re-render (the engine's render bodies
+     * re-run; cells stay memoized) — hoist the node or `useMemo` it.
+     * スクロール帯行の背後・エンジンコンテンツ要素内に描画する背景レイヤー (VirtualGrid
+     * `background` の素通し。ライブ prop)。viewport 固定: エンジンが translate するのは行
+     * ラッパーだけで、この層はスクロール量に追従しない — 周期的な行罫線を置くとスクロール中に
+     * 実際の行へ対して滑る。overscan が尽きた帯で「まだ到着中」と読める静的テクスチャ向きで、
+     * 行整合の罫線には不向き。層はスクロール行の全幅 — 凍結**列**域を含む (凍結列はスクロール行の
+     * 内側に居る) — に広がり、凍結行帯には広がらない。identity 安定契約 (`renderCell` と同じ):
+     * インライン要素はホスト再レンダー毎に GridBody の memo 境界を貫通する (エンジンの render 本体が
+     * 再実行、セルは memo 維持) — ノードは hoist するか `useMemo` で保つ。
+     */
+    background?: ReactNode
+    /**
+     * Rendering-truncation signal pass-through (the VirtualGrid `onRenderTruncated` callback):
+     * fires when the engine drops trailing columns to stay under its total cell cap
+     * (`MAX_RENDERED_CELLS`) — the cells actually rendered and the columns dropped. The engine's
+     * doctrine is that truncation is never silent; an oversized `overscanCols` × row span is the
+     * typical cause. Undefined ⇒ no callback (engine default).
+     * 描画打切り通知の素通し (VirtualGrid `onRenderTruncated`): エンジンが総セル上限
+     * (`MAX_RENDERED_CELLS`) を守るため末尾列を落としたときに、実描画セル数と脱落列数で発火する。
+     * 「打切りは無言にしない」がエンジン教義で、過大な `overscanCols` × 行スパンが典型原因。
+     * undefined = 通知なし (エンジン既定)。
+     */
+    onRenderTruncated?: (info: { renderedCells: number; droppedCols: number }) => void
     /**
      * 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).
-     * identity 安定契約 — インライン関数は memo を無効化し毎レンダー全再スライスになる。
+     * Per-cell opt-out (v0.12): returning `undefined` from one cell lands that cell on the
+     * package default rendering (value-format engine included) — "custom where needed, default
+     * elsewhere" without wrapper elements. ONLY `undefined` opts out — `null`, `false` (the
+     * `cond && <X/>` idiom) and every other ReactNode are custom output, i.e. an empty custom
+     * cell. `ctx.text` is the RAW canonical string; `ctx.displayText` (v0.12) is the value-format
+     * display — the exact string the default rendering, the AT announcement, the HTML clipboard
+     * and autofit share, so a custom cell that renders it can never drift from what gets copied.
+     * Autofit stays a whole-grid no-op while `renderCell` is set (custom DOM width is unknowable).
+     * identity 安定契約 — インライン関数は memo を無効化し毎レンダー全再スライスになる。セル単位
+     * オプトアウト (v0.12): `undefined` を返したセルはパッケージ既定描画 (値書式エンジン込み) へ
+     * 降りる — 「要る列だけカスタム、残りは既定」を器なしで構成できる。オプトアウトは
+     * `undefined` **だけ** — `null` / `false` (`cond && <X/>` 慣用) / 他の ReactNode はカスタム
+     * 出力 (= 空のカスタムセル)。`ctx.text` は素の正準文字列、`ctx.displayText` (v0.12) は値書式の
+     * 表示文字列 — 既定描画・AT 読み上げ・HTML クリップボード・autofit と同一なので、これを描く
+     * カスタムセルはコピー結果と食い違わない。autofit は `renderCell` 指定中はグリッド全体
+     * no-op のまま (カスタム DOM の幅は測れない)。
      */
     renderCell?: (ctx: RenderCellContext) => ReactNode
     /**
@@ -228,11 +310,16 @@ export type SpreadsheetProps = {
      * paste replace, Ctrl+A, ...). Never during a drag (state frozen — one fire at pointerup),
      * with ONE documented in-drag firing point: the header subtract reservation converts to a
      * real press on the first movement, firing the deferred press replace mid-drag (total fire
-     * count matches v0.1 — conversion 1 + up 1). Never for the initial A1 mount. Independent
-     * of the live region's 200ms debounce (firing point: the §6.9-1 setSelection wrapper).
+     * count matches v0.1 — conversion 1 + up 1). Never for the initial A1 mount. ONE host-driven
+     * fire point outside gestures (ADR-33): a same-adapter rowCount / colCount shrink that moved
+     * the selection fires once from a layout effect of that commit — not a user gesture.
+     * Independent of the live region's 200ms debounce (firing point: the §6.9-1 setSelection
+     * wrapper).
      * 確定 SelectionState が変わるたびに発火。ドラッグ中と初期マウントでは発火しない。明文の
      * ドラッグ中発火点が 1 つ: ヘッダー減算予約の実 press 変換 (初動 move) は遅延 press 置換を
-     * ドラッグ中に発火する (発火総数は v0.1 と同一 — 変換 1 + up 1)。
+     * ドラッグ中に発火する (発火総数は v0.1 と同一 — 変換 1 + up 1)。ジェスチャ外のホスト起点発火点が
+     * 1 つ (ADR-33): 同一 adapter の rowCount / colCount 縮小で選択が動いたとき、その commit の
+     * layout effect から 1 回発火する (ユーザー操作ではない)。
      */
     onSelectionChange?: (selection: SelectionState) => void
     /** Consumer context menu (§6.4.3-4 / §6.6.1 Shift+F10); keyboard origin carries the active cell viewport rect. / consumer コンテキストメニュー。 */
@@ -325,9 +412,11 @@ export type SpreadsheetProps = {
     enableResizeUI?: boolean
     /**
      * 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
+     * is the RAW canonical getCellText; `displayText` is the value-format display string (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". `readOnly` (v0.10) is
+     * hear "87.0%" for a cell whose raw value is "0.87". It is the same string a custom
+     * `renderCell` cell receives as `ctx.displayText` (v0.12) — what a sighted user sees unless
+     * the host deliberately renders something else. `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,
@@ -490,6 +579,25 @@ const clampZoom = (value: number): number => {
  */
 const stepZoom = (value: number, direction: 1 | -1): number => (direction > 0 ? (Math.floor(value * 10 + 1e-6) + 1) / 10 : (Math.ceil(value * 10 - 1e-6) - 1) / 10)
 
+/**
+ * Validates one overscan prop and returns it unchanged (fail-fast — the engine does NOT
+ * validate overscan: a negative value silently shrinks the rendering window past the visible
+ * band on the normal path and is clamped to 0 only on the huge-index path, so rejection is owned
+ * by this surface). Undefined is the declared absence signal (engine default) and is exempt.
+ * Throws RangeError on a non-integer or negative value (the message echoes the raw input —
+ * numbers verbatim incl. Infinity / NaN, strings quoted so a JS host passing "5" sees the quotes).
+ * overscan prop 1 つの検証 (値はそのまま返す。fail-fast — エンジンは overscan を検証しない: 負値は
+ * 通常経路で描画窓を可視帯の内側へ無言で縮め、巨大 index 経路でだけ 0 へクランプされるため、拒否は
+ * 本層所有)。undefined は宣言不在信号 (エンジン既定) で対象外。非整数・負値は RangeError (メッセージは
+ * 生の入力を映す — 数値は Infinity / NaN 込みでそのまま、文字列は引用符つき — JS ホストの "5" は引用符で映る)。
+ */
+const validateOverscan = (name: "overscanRows" | "overscanCols", value: number | undefined): number | undefined => {
+    if (value !== undefined && !(Number.isInteger(value) && value >= 0)) {
+        throw new RangeError(`[spreadsheet] ${name} must be a non-negative integer (got ${typeof value === "string" ? JSON.stringify(value) : String(value)})`)
+    }
+    return value
+}
+
 /**
  * Test-only seam props (NOT part of the public v0.1.0 contract — §8.2 counter injection).
  * テスト専用シーム props (公開 v0.1.0 契約外 — §8.2 カウンタ注入)。
@@ -508,6 +616,15 @@ type SpreadsheetTestProps = {
      * では渡さない (未指定 = 呼出しゼロ — `__onCellRender` と同じ品行)。
      */
     __onVirtualKeyboardRaise?: () => void
+    /**
+     * Test-only rendered-cell cap forwarded to the engine's `__maxRenderedCells` seam so the
+     * `onRenderTruncated` pass-through can be pinned without materializing 32,768 cells. Never
+     * passed in production (unset = the engine's MAX_RENDERED_CELLS — the `__onCellRender` conduct).
+     * テスト専用の描画セル上限 (エンジンの `__maxRenderedCells` シームへ素通し) — `onRenderTruncated`
+     * 素通しを 32,768 セルの実体化なしでピンするため。production では渡さない (未指定 = エンジンの
+     * MAX_RENDERED_CELLS — `__onCellRender` と同じ品行)。
+     */
+    __maxRenderedCells?: number
 }
 
 const DEFAULT_ROW_HEIGHT = 24
@@ -619,6 +736,10 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
         frozenTrailingColumns = 0,
         frozenTrailingRows = 0,
         tapScrollCircleOptions,
+        overscanRows,
+        overscanCols,
+        background,
+        onRenderTruncated,
         renderCell,
         onSelectionChange,
         onCellContextMenu,
@@ -660,6 +781,7 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
         className,
         __onCellRender,
         __onVirtualKeyboardRaise,
+        __maxRenderedCells,
     }: SpreadsheetProps & SpreadsheetTestProps,
     ref,
 ): ReactNode {
@@ -2347,6 +2469,68 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
         }
     }, [adapter, isEmpty, setSelection, engine, colHeaderMachine, rowHeaderMachine, headerResizeMachine, fillMachine, pointDrag, viewStore, editor.cancelEdit])
 
+    // ---- 行数 / 列数の縮小 (同一 adapter — 絞り込み / カテゴリ / 期間の変更で明細が減る) は保持中の
+    //      座標を新グリッドへ畳む (ADR-33) ----
+    // 旧座標のレンジ / セッション / アンカー / クリップは新軸で範囲外になり得て、repaintOverlay の
+    // sizeOf が例外を投げる (Fenwick は範囲外 index で fail-fast — 測る側は緩めない)。シート切替と違い
+    // 座標系は同一グリッドなので全リセットではなく**クランプ**: 範囲内に残る選択 / セッション /
+    // ポップオーバーは保持し、範囲外に出たものだけ端へ畳む (選択) か取り消す (セッション / ポップオーバー /
+    // 自シートのクリップ)。成長 (行が増える) は座標を無効化しないので何もしない。同一性切替の effect より
+    // 後に置き、エッジ ref に adapter を同乗させて「同一 adapter の縮小」だけを見る (切替は前段が A1 へ
+    // 全リセット済み)。順序: **選択の畳込みを最初に**置く — 畳んだ選択は旧軸でも新軸でも範囲内なので、
+    // 以降の取消 / 閉鎖 / 破棄が同期 repaint を呼んでも (現配線では repaintOverlay は passive effect 側の
+    // 旧クロージャ = 旧軸、将来 layout effect 化しても新軸) どちらのクロージャでも安全 — 切替 effect の
+    // 「防御的順序」を一段強めた形
+    const prevCountsRef = useRef({ adapter, rows: rowAxis.count, cols: colAxis.count })
+    const { getSessionCell, cancelEdit: cancelEditSession } = editor
+    useLayoutEffect(() => {
+        const prev = prevCountsRef.current
+        const rows = rowAxis.count
+        const cols = colAxis.count
+        prevCountsRef.current = { adapter, rows, cols }
+        if (prev.adapter !== adapter || (rows >= prev.rows && cols >= prev.cols)) {
+            return
+        }
+        if (isEmpty) {
+            // 空グリッドへの縮小: 0 行に A1 は存在せず、通知も読み上げも rearm も流さない (切替と同文)
+            selectionRef.current = INITIAL_SELECTION
+            setSelectionState(INITIAL_SELECTION)
+        } else {
+            // 選択は端へ畳む — 範囲外が無ければ同一 object が返り、ラッパーの Object.is bail で通知なし
+            setSelection(clampSelectionToGrid(selectionRef.current, rows, cols))
+        }
+        // 飛行中ドラッグは復元なしで取り消す (各機械の dragBeforeRef は旧グリッド座標 — 切替シームと同文)
+        engine.cancelDrag()
+        colHeaderMachine.cancelDrag()
+        rowHeaderMachine.cancelDrag()
+        headerResizeMachine.cancelDrag()
+        fillMachine.cancelDrag()
+        pointDrag.cancelDrag()
+        const outside = (cell: CellCoord): boolean => isEmpty || cell.row >= rows || cell.col >= cols
+        // 範囲外セルの編集セッションは値破棄で終了 (commit すると消えた行へ誤書込) — 範囲内は保持
+        const sessionCell = getSessionCell()
+        if (sessionCell !== null && outside(sessionCell)) {
+            cancelEditSession()
+        }
+        // ポップオーバーはアンカーが範囲外のものだけ畳む (repaintOverlay がアンカーを測る)
+        const anchors = popoverAnchorsRef.current
+        if (anchors.tip !== null && outside(anchors.tip)) {
+            popoversRef.current?.hideTip()
+        }
+        if (anchors.interactive !== null && outside(anchors.interactive)) {
+            // ホスト起点の閉鎖: フォーカスがグリッド外 (絞り込みの入力欄など) にある間は奪わない — 通常の
+            // 閉鎖 (Escape / ボタン) と違い、ユーザーの打鍵先がここで変わってはならない
+            const focusInsideGrid = rootRef.current?.contains(document.activeElement) === true
+            popoversRef.current?.close({ restoreFocus: focusInsideGrid })
+        }
+        // 自シートのクリップは範囲外なら破棄 (元セルが消えた cut / copy — マーキーも範囲外を描かない)。
+        // foreign (別アダプタのレンジ) は別座標系なので触れない
+        const clip = getClip()
+        if (clip !== null && !clip.foreign && outside({ row: clip.range.endRow, col: clip.range.endCol })) {
+            discardClip()
+        }
+    }, [adapter, rowAxis.count, colAxis.count, isEmpty, setSelection, engine, colHeaderMachine, rowHeaderMachine, headerResizeMachine, fillMachine, pointDrag, getSessionCell, cancelEditSession, getClip, discardClip])
+
     // ---- 凍結列数の変化 (v0.5 ライブ prop) は飛行中ジェスチャを復元なしで取り消す ----
     // 押下時の grab オフセット / アンカーは旧パーティション座標系で確立済み — 変更後の鮮度
     // ヒットテスト (新座標系) と混ざると、ユーザーが狙っていないセルへ fill が確定し得る
@@ -2577,6 +2761,10 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
                         frozenTrailingColumns={frozenTrailingColumns}
                         frozenTrailingRows={frozenTrailingRows}
                         tapScrollCircleOptions={tapScrollCircleOptions}
+                        overscanRows={validateOverscan("overscanRows", overscanRows)}
+                        overscanCols={validateOverscan("overscanCols", overscanCols)}
+                        background={background}
+                        onRenderTruncated={onRenderTruncated}
                         renderCell={renderCell}
                         onScroll={onScroll}
                         onRangeChange={onRangeChange}
@@ -2585,6 +2773,7 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
                         requestCommit={requestCommit}
                         testId={testId ? `${testId}-vs` : undefined}
                         __onCellRender={__onCellRender}
+                        __maxRenderedCells={__maxRenderedCells}
                         cfIndexRef={cfIndexRef}
                         cfMemoRef={cfMemoRef}
                         isPointing={isPointing}

package/src/editor/useCellEditor.ts

@@ -180,6 +180,8 @@ export type CellEditor = PointingSeams & {
     insertAtCaret: (text: string) => void
     /** The session's live text, or null when idle (editing-column fillSelection). / セッションの現在文字列 (idle は null — 編集列の fillSelection)。 */
     getSessionText: () => string | null
+    /** The session's cell, or null when idle — the count-shrink clamp cancels a session whose cell left the grid. / セッションのセル (idle は null) — 行数 / 列数縮小の畳込みが、グリッドから消えたセルのセッションを取り消す判定に使う。 */
+    getSessionCell: () => CellCoord | null
     /** Recomputes and re-applies the edit paint after an editing-column format toggle, then repaints the overlay. / 編集列の書式トグル後に塗りを再計算・再適用し overlay を再描画。 */
     refreshPaint: () => void
     /** React state mirror for the overlay's editing prop (§6.7.2-4). / overlay の editing prop 用ミラー。 */
@@ -655,6 +657,8 @@ export const useCellEditor = (params: UseCellEditorParams): CellEditor => {
         return sessionRef.current === null || sink === null ? null : sink.value
     }, [])
 
+    const getSessionCell = useCallback((): CellCoord | null => (sessionRef.current === null ? null : sessionRef.current.cell), [])
+
     const refreshPaint = useCallback((): void => {
         const p = paramsRef.current
         const session = sessionRef.current
@@ -749,9 +753,10 @@ export const useCellEditor = (params: UseCellEditorParams): CellEditor => {
             cycleAnchorAtCaret,
             insertAtCaret,
             getSessionText,
+            getSessionCell,
             refreshPaint,
             editing,
         }),
-        [requestCommit, cancelEdit, startEdit, getPointing, togglePointingArm, getReferenceCursor, insertReference, captureSink, restoreSink, cycleAnchorAtCaret, insertAtCaret, getSessionText, refreshPaint, editing],
+        [requestCommit, cancelEdit, startEdit, getPointing, togglePointingArm, getReferenceCursor, insertReference, captureSink, restoreSink, cycleAnchorAtCaret, insertAtCaret, getSessionText, getSessionCell, refreshPaint, editing],
     )
 }

package/src/grid/CellView.tsx

@@ -13,15 +13,27 @@
 
 import { memo, type ProfilerOnRenderCallback, type ReactNode, useEffect, useRef } from "react"
 
-/** Public custom cell renderer context (ADR-8). / 公開セルレンダラーの ctx (ADR-8)。 */
-export type RenderCellContext = { row: number; col: number; text: string }
+/**
+ * Public custom cell renderer context (ADR-8). `text` is the RAW canonical `getCellText`
+ * string; `displayText` (v0.12) is the value-format display string — the exact string the
+ * default rendering, the AT announcement, the HTML clipboard and autofit all share (equals
+ * `text` when the format capability is absent). A custom cell that should look like the
+ * default renders `displayText`.
+ * 公開セルレンダラーの ctx (ADR-8)。`text` は素の正準 `getCellText` 文字列。`displayText`
+ * (v0.12) は値書式の表示文字列 — 既定描画・AT 読み上げ・HTML クリップボード・autofit が共有
+ * する同一文字列 (書式能力なしは `text` と同値)。既定と同じ見た目にしたいカスタムセルは
+ * `displayText` を描く。
+ */
+export type RenderCellContext = { row: number; col: number; text: string; displayText: string }
 
 type CellViewProps = {
     row: number
     col: number
     /** Canonical text the grid's getCell reads from adapter.getCellText (updated by re-slice). / グリッドの getCell が adapter.getCellText から読む正準文字列。 */
     text: string
-    /** The public cell renderer (ADR-8); this is its execution point. / 公開レンダラーの実行点。 */
+    /** Value-format display string (equals `text` without the format capability) — the default rendering and the opt-out landing. / 値書式の表示文字列 (書式能力なしは `text` と同値) — 既定描画とオプトアウトの着地。 */
+    display: string
+    /** The public cell renderer (ADR-8); this is its execution point. ONLY an `undefined` return is the per-cell opt-out (v0.12) — `null` / `false` / any other ReactNode is custom output (an empty custom cell). / 公開レンダラーの実行点。セル単位オプトアウト (v0.12) は `undefined` 返し**だけ** — `null` / `false` / 他の ReactNode はカスタム出力 (空のカスタムセル)。 */
     renderCell?: (ctx: RenderCellContext) => ReactNode
     /** Test-only re-render counter injection point (§8.2); undefined in production. / テスト専用注入点。 */
     __onCellRender?: ProfilerOnRenderCallback
@@ -31,7 +43,7 @@ type CellViewProps = {
  * Renders one cell's content (memo target — no own positioned element since v0.4).
  * セル 1 枚の中身を描画 (memo 対象 — v0.4 から自前の配置要素は持たない)。
  */
-const CellViewInner = ({ row, col, text, renderCell, __onCellRender }: CellViewProps): ReactNode => {
+const CellViewInner = ({ row, col, text, display, renderCell, __onCellRender }: CellViewProps): ReactNode => {
     // テスト専用カウンタ: Profiler ノードの常設を避けるコスト取引 — 代わりに常設の passive
     // effect 1 本が毎 commit 走る (注入なしなら本体は即 no-op)。フックは条件分岐できないため
     // この登録コスト自体は受容する (初回 = mount、以後 = update)
@@ -41,7 +53,12 @@ const CellViewInner = ({ row, col, text, renderCell, __onCellRender }: CellViewP
         mountedRef.current = true
         __onCellRender?.(`cell-${row}-${col}`, phase, 0, 0, 0, 0)
     })
-    return renderCell ? renderCell({ row, col, text }) : text
+    if (renderCell !== undefined) {
+        const custom = renderCell({ row, col, text, displayText: display })
+        // undefined はセル単位オプトアウト (v0.12) — 既定描画 (値書式込み) へ降りる。「空を描く」の明示は null
+        return custom === undefined ? display : custom
+    }
+    return display
 }
 
 /**

package/src/grid/GridBody.tsx

@@ -59,7 +59,7 @@ import { normalizeAdapterHyperlink } from "../model/cellAnnotations.ts"
 import { alignToJustify, type CellAlign, type CellValueFormat, formatCellValue } from "../model/cellFormat.ts"
 import { type CellPaint, resolveCellPaint } from "../model/cellPaint.ts"
 import { type CfIndex, type CfMemo, createCfMemo, resolvePaintedFormat } from "../model/conditionalFormat.ts"
-import { isReadOnlyCell, lazyCellText, resolveCellAlign, type SpreadsheetDataAdapter } from "../model/dataAdapter.ts"
+import { isReadOnlyCell, lazyCellText, resolveCellAlign, resolveCellAttributes, type SpreadsheetDataAdapter } from "../model/dataAdapter.ts"
 import { isVisiblyInvalid } from "../model/dataValidation.ts"
 import { SCROLLBAR_WIDTH, type ViewStore } from "../model/viewStore.ts"
 import { CellView, type RenderCellContext } from "./CellView.tsx"
@@ -291,6 +291,8 @@ type GridBodyProps = {
     testId?: string
     /** Test-only CellView re-render counter seam (§8.2). / テスト専用の再レンダー計数シーム。 */
     __onCellRender?: ProfilerOnRenderCallback
+    /** Test-only rendered-cell cap (engine `__maxRenderedCells` seam pass-through); undefined in production. / テスト専用の描画セル上限 (エンジン `__maxRenderedCells` シームの素通し)。production では undefined。 */
+    __maxRenderedCells?: number
     /**
      * v0.8 capability (with `cfMemoRef`): the root-built conditional-format index, rebuilt per
      * (rules identity, renderVersion) and read fresh at every slice. Absent ⇒ the painted format
@@ -318,6 +320,24 @@ type GridBodyProps = {
      * キー同乗のままエンジン宣言の不在信号 (エンジン既定) — この層での値フォールバックなし。
      */
     tapScrollCircleOptions?: ScrollBarTapCircleOptions
+    /**
+     * Row-axis overscan (the engine `overscanRows` pass-through; the Spreadsheet surface owns
+     * the fail-fast validation — the engine clamps silently). Undefined ⇒ engine default (3).
+     * 行軸 overscan (エンジン `overscanRows` の素通し。fail-fast 検証は Spreadsheet 面所有 —
+     * エンジンは無言クランプ)。undefined ⇒ エンジン既定 (3)。
+     */
+    overscanRows?: number
+    /** Column-axis overscan — the column twin of `overscanRows`, same contract. / 列軸 overscan — `overscanRows` の列双子 (同契約)。 */
+    overscanCols?: number
+    /**
+     * Background layer behind the scroll-band rows (the engine `background` pass-through;
+     * viewport-pinned — the engine translates only its row wrapper).
+     * スクロール帯行背後の背景レイヤー (エンジン `background` の素通し。viewport 固定 —
+     * エンジンが translate するのは行ラッパーのみ)。
+     */
+    background?: ReactNode
+    /** Rendering-truncation signal (engine `onRenderTruncated` pass-through — trailing columns dropped under the cell cap). / 描画打切り通知 (エンジン `onRenderTruncated` の素通し — セル上限下の末尾列脱落)。 */
+    onRenderTruncated?: (info: { renderedCells: number; droppedCols: number }) => void
 }
 
 /**
@@ -344,10 +364,15 @@ const GridBodyInner = ({
     requestCommit,
     testId,
     __onCellRender,
+    __maxRenderedCells,
     cfIndexRef,
     cfMemoRef,
     isPointing,
     tapScrollCircleOptions,
+    overscanRows,
+    overscanCols,
+    background,
+    onRenderTruncated,
 }: GridBodyProps): ReactNode => {
     const internalBodyRef = useRef<HTMLDivElement | null>(null)
     // 外部 ref (エンジン結線用) と内部 ref の合成
@@ -408,6 +433,11 @@ const GridBodyInner = ({
                 // 宣言ホストは塗りセル毎 1 述語読み (ADR-31 の登記コスト)
                 ...(isReadOnlyCell(adapter, row, col) ? { "aria-readonly": "true", "data-aqsp-readonly": "" } : {}),
             }
+            // v0.12 ホスト属性の継ぎ目: resolveCellAttributes が予約キー (data-aqsp* / data-row /
+            // data-col) と非 data-* を fail-fast 済みなのでパッケージ属性と衝突しない。未宣言は
+            // O(1) null = v0.11 のセル DOM とバイト同一
+            const hostAttrs = resolveCellAttributes(adapter, row, col)
+            const stamped = hostAttrs === null ? base : { ...base, ...hostAttrs }
             const rich = resolveRichCellProps(adapter, rowAxis, colAxis, cf, row, col)
             // 掛け金は毎セル更新 (v0.1 恒等の null でも座標を進める — children が消費するのは書式能力下だけ)
             const latch = displayLatchRef.current
@@ -415,9 +445,9 @@ const GridBodyInner = ({
             latch.col = col
             latch.value = rich === null ? undefined : rich.value
             if (rich === null) {
-                return base as HTMLAttributes<HTMLDivElement>
+                return stamped as HTMLAttributes<HTMLDivElement>
             }
-            return (rich.style === null ? { ...base, ...rich.attrs } : { ...base, ...rich.attrs, style: rich.style }) as HTMLAttributes<HTMLDivElement>
+            return (rich.style === null ? { ...stamped, ...rich.attrs } : { ...stamped, ...rich.attrs, style: rich.style }) as HTMLAttributes<HTMLDivElement>
         },
         [adapter, rowAxis, colAxis, cf],
     )
@@ -444,15 +474,17 @@ const GridBodyInner = ({
         (text: string, row: number, col: number): ReactNode => {
             // renderVersion は識別子として参照する (identity-bust — 値そのものは使わない)
             void renderVersion
-            // v0.7 表示形式: renderCell 指定時は素の text を素通し (escape hatch・組み込み値書式に優先)、
-            // 未指定時のみ値書式を表示文字列へ適用 (編集 / コピーは素の値のまま)。値書式は直前の
-            // getCellProps が掛け金へ置いた塗り書式の value (= base の value — CF 語彙に value は無い) で、
-            // アダプタは再読しない (書式能力なしは掛け金にも触れない v0.7 恒等)
+            // v0.7 表示形式 / v0.12 オプトアウト: 値書式は renderCell の有無に依らず書式能力下で
+            // 常に解決する — カスタムセルは ctx.displayText として受け取り (読み上げ / クリップ
+            // ボード / autofit と同一文字列)、undefined 返しのオプトアウトセルは既定描画がこれを
+            // 描く。値は直前の getCellProps が掛け金へ置いた塗り書式の value (= base の value —
+            // CF 語彙に value は無い) で、アダプタは再読しない (書式能力なしは掛け金にも触れない
+            // v0.7 恒等)
             let display = text
-            if (renderCell === undefined && adapter.getCellFormat !== undefined) {
+            if (adapter.getCellFormat !== undefined) {
                 display = formatCellValue(text, takeLatchedValue(displayLatchRef.current, row, col))
             }
-            return <CellView row={row} col={col} text={display} renderCell={renderCell} __onCellRender={__onCellRender} />
+            return <CellView row={row} col={col} text={text} display={display} renderCell={renderCell} __onCellRender={__onCellRender} />
         },
         [renderVersion, renderCell, __onCellRender, adapter],
     )
@@ -517,6 +549,11 @@ const GridBodyInner = ({
                 contentProps={contentProps}
                 behaviorOptions={behaviorOptions}
                 scrollBarOptions={scrollBarOptions}
+                overscanRows={overscanRows}
+                overscanCols={overscanCols}
+                background={background}
+                onRenderTruncated={onRenderTruncated}
+                __maxRenderedCells={__maxRenderedCells}
                 callbackThrottleMs={0}
                 onScroll={onScroll}
                 onRangeChange={onRangeChange}

package/src/index.ts

@@ -36,7 +36,7 @@
  * (分冊 00 §5.2)。
  */
 
-// 統合タップサークル (エンジン v3.6.0 — ADR-33 縮小形): tapScrollCircleOptions prop (v0.10 H2) と
+// 統合タップサークル (エンジン v3.6.0 — エンジン ADR-33 縮小形): tapScrollCircleOptions prop (v0.10 H2) と
 // renderVisual をエンジン直接依存なしで型付ける型のみ再 export。値面 (tapScrollCircleSampleVisual) は
 // 意図的に非再 export — エンジン所有のまま
 export type { ScrollBarTapCircleOptions, TapScrollCircleRenderProps } from "@aiquants/virtualscroll"

package/src/keyboard/useGridKeyboard.ts

@@ -66,7 +66,7 @@ import { type RefObject, useEffect, useRef } from "react"
 import type { PasteOptions } from "../clipboard/pasteSpecial.ts"
 import type { PointingSeams } from "../editor/useCellEditor.ts"
 import { type AxisModel, nextVisibleIndex } from "../model/axisModel.ts"
-import { type CellCoord, type CellRange, countRangeCells, enumerateRangeCells, makeRange, type SpreadsheetDirection, type SpreadsheetOperation } from "../model/cellCoord.ts"
+import { type CellCoord, type CellRange, clampCoord, countRangeCells, enumerateRangeCells, makeRange, type SpreadsheetDirection, type SpreadsheetOperation } from "../model/cellCoord.ts"
 import { aspectCapabilities, type CellEdit, type EditRejection, type ReadOnlyRejection, rangesContainReadOnly, type SpreadsheetDataAdapter } from "../model/dataAdapter.ts"
 import { colToViewportX, rowToViewportY } from "../model/frozenPartition.ts"
 import { reduceActiveCycle, type SelectionState } from "../selection/selectionState.ts"
@@ -450,16 +450,21 @@ export const useGridKeyboard = (params: UseGridKeyboardParams): void => {
                         const reference = pointing.getReferenceCursor()
                         if (reference !== null) {
                             event.preventDefault()
+                            // トークン由来の座標は生存セッションが行数 / 列数の縮小 (ADR-33) を跨いだあと範囲外
+                            // になり得る (手打ち "=A999" も同じ) — moveActive の入力 clamp と同じ規律で消費点に
+                            // 畳んでから歩く (軸の範囲外読みは Fenwick が fail-fast する)
+                            const cursor = clampCoord(reference.cursor, p.rowAxis.count, p.colAxis.count)
+                            const origin = clampCoord(reference.origin, p.rowAxis.count, p.colAxis.count)
                             // Ctrl はデータ端 (idle の Ctrl+Arrow と同じ導出)、素は可視 1 歩。active は動かさない
-                            const next = ctrl ? dataEdgeTarget(reference.cursor, direction) : arrowStep(reference.cursor, direction)
+                            const next = ctrl ? dataEdgeTarget(cursor, direction) : arrowStep(cursor, direction)
                             p.ensureCellVisible(next)
                             // Shift はトークン起点とのレンジへ置換、素はカーソル単独
-                            pointing.insertReference(event.shiftKey ? makeRange(reference.origin, next) : next, reference.axis)
+                            pointing.insertReference(event.shiftKey ? makeRange(origin, next) : next, reference.axis)
                             // 指し先の参照矩形 (§2.7): 挿入したトークンと同じ範囲を "point" 矩形で描く
                             // (Excel / Sheets のキーボード指し枠)。帯参照 (A:C / 2:5) は軸全域へ展開 —
                             // トークンの意味する範囲そのもの。能力分岐: writer 未配線 = 矩形なし (参照書換のみ)
                             if (p.onPointFrame !== undefined) {
-                                const rect = event.shiftKey ? makeRange(reference.origin, next) : makeRange(next, next)
+                                const rect = event.shiftKey ? makeRange(origin, next) : makeRange(next, next)
                                 p.onPointFrame(
                                     reference.axis === "columns"
                                         ? makeRange({ row: 0, col: rect.startCol }, { row: p.rowAxis.count - 1, col: rect.endCol })