@aiquants/spreadsheet 0.11.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiquants/spreadsheet",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Excel-grade spreadsheet grid for React: multi-cell selection, TSV/HTML clipboard, in-place editing on top of @aiquants/virtualscroll",
   "sideEffects": [
     "**/*.css"
@@ -34,12 +34,12 @@
     "LICENSE.md"
   ],
   "peerDependencies": {
-    "@aiquants/virtualscroll": "^3.6.1",
+    "@aiquants/virtualscroll": "^3.7.0",
     "react": "^19.2.7",
     "react-dom": "^19.2.7"
   },
   "devDependencies": {
-    "@aiquants/virtualscroll": "3.6.1",
+    "@aiquants/virtualscroll": "3.7.0",
     "@playwright/test": "^1.59.1",
     "@tailwindcss/cli": "^4.1.18",
     "@testing-library/jest-dom": "^6.9.1",

package/src/Spreadsheet.tsx

@@ -27,6 +27,10 @@
  * clipboard / keyboard (executeCommandRef / openPopoverRef / hideNoteTipRef / pasteRef /
  * pendingPasteOptionsRef / popover anchors).
  *
+ * UI chrome locale: the `locale` prop is resolved once (`resolveVirtualScrollLocale` — undefined ⇒
+ * "en", unknown ⇒ RangeError at render) and drives the label catalog, the built-in validation
+ * messages and — through a value-stable engine subset — the grid scrollbars.
+ *
  * v0.8 (計画 §4.2.13 — フック順は設計 v5): 軸モデル → viewStore → ズーム → オートスクローラー
  * 6 台 (6 台目は参照ドラッグ用) → 選択エンジン → ヘッダー機械 ×2 → ヘッダーリサイズ → fill →
  * 参照ドラッグ (usePointDrag) → 合成ドラッグ面 (isDraggingAny / abortDragAny / "point" 込みの
@@ -37,9 +41,13 @@
  * ポインティングの ref 辺 (editor → engine / ヘッダー / 参照ドラッグ / body / コーナー / ズーム死空間)、
  * コマンド / ポップオーバー / クリップボード / キーボード間の ref 辺 (executeCommandRef /
  * openPopoverRef / hideNoteTipRef / pasteRef / pendingPasteOptionsRef / ポップオーバーアンカー) を所有する。
+ *
+ * UI クロームロケール: `locale` prop を 1 回だけ解決し (`resolveVirtualScrollLocale` — undefined は
+ * "en"、未知は render 中 RangeError)、ラベルカタログ・組み込み検証メッセージ・値安定なエンジン部分集合
+ * 経由のグリッドスクロールバーを駆動する。
  */
 
-import type { ScrollBarTapCircleOptions, VirtualGridHandle, VirtualGridRange } from "@aiquants/virtualscroll"
+import { resolveVirtualScrollLocale, type ScrollBarTapCircleOptions, VIRTUAL_SCROLL_LABEL_KEYS, type VirtualGridHandle, type VirtualGridRange, type VirtualScrollLabels } 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"
@@ -67,13 +75,13 @@ import { type CellEdit, type EditContext, type EditRejection, type EditSource, i
 import { type DataValidationRule, type ValidationVerdict, validateCellText } from "./model/dataValidation.ts"
 import type { ReferenceAxis } from "./model/formulaRefs.ts"
 import { colToViewportX, rowToViewportY } from "./model/frozenPartition.ts"
-import { resolveLabels, type SpreadsheetLabelOverrides } from "./model/labels.ts"
+import { pickEngineLabels, resolveLabels, type SpreadsheetLabelOverrides, type SpreadsheetLocale } from "./model/labels.ts"
 import { createViewStore, type ViewStore } from "./model/viewStore.ts"
 import { DEFAULT_HIGHLIGHT_COLORS, type DragFrameMode, type HighlightColors, type HighlightState, type ResizeGuide, SelectionOverlay } from "./overlay/SelectionOverlay.tsx"
 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"
@@ -220,16 +228,27 @@ export type SpreadsheetProps = {
     /**
      * 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 —
-     * the slack in px is overscan × row height per edge). Undefined ⇒ the engine default (3).
-     * The engine clamps invalid values silently, so THIS surface owns the fail-fast: a
-     * non-integer or negative value throws a RangeError at render. Cost multiplies with the
-     * column axis (bounded by the engine cell cap).
+     * 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 フレーム遅れを吸収する唯一の余裕 (白帯対策 —
-     * 余裕 px は片端あたり overscan × 行高)。undefined はエンジン既定 (3)。エンジンは不正値を
-     * 無言クランプするため fail-fast は本層所有 — 非整数・負値は render 時 RangeError。費用は
-     * 列軸との積で増幅 (エンジンのセル上限で有界)。
+     * 描画する行数。高速スクロール時の描画窓 1 フレーム遅れを吸収する唯一の余裕 (白帯対策)。
+     * overscan は**行数**で数える (非表示の 0px 行も枠を消費) ため、片端の余裕 px が overscan ×
+     * 行高になるのは行が一様に可視のときだけ。undefined はエンジン既定 (3)。エンジンは overscan を
+     * 検証しない (負値は描画窓を無言で縮める) ため fail-fast は本層所有 — 非整数・負値は render 時
+     * RangeError。費用は列軸との積で増幅し、エンジンは有界化でなく**打切り**で応じる: 軸毎の行予算
+     * や総セル上限を超えた窓は先頭側を残し末尾側を落とす — 行予算超過はコールバック無し (エンジンは
+     * warn ログのみ)、セル上限超過 (列の脱落) は `onRenderTruncated` で通知。片側数百行の値は高い viewport で予算に迫るため、必要な
+     * 余裕にとどめる。
      */
     overscanRows?: number
     /**
@@ -246,18 +265,52 @@ export type SpreadsheetProps = {
      * 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.
+     * 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
     /**
@@ -265,11 +318,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 コンテキストメニュー。 */
@@ -362,9 +420,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,
@@ -385,14 +445,30 @@ export type SpreadsheetProps = {
      * コマンドの AT 通知 (opt-in、v0.8 §1.9)。`state` はトグル後状態 (非トグルは null)。live region へ。
      */
     formatCommandAnnouncement?: (ctx: { command: SpreadsheetCommand; state: boolean | null }) => string
+    /**
+     * UI chrome language ("en" | "ja"; default "en"): selects the label catalog, the built-in
+     * data-validation messages, and is forwarded to the grid scrollbars (arrow labels,
+     * scroll-to-edge pills, "No items"). An unsupported value throws a RangeError during render —
+     * there is no language negotiation: hosts map `navigator.language` themselves. Unrelated to
+     * `formats.locale`, which is the BCP-47 value-formatting locale ("ja-JP" is NOT a valid value
+     * here).
+     * UI クローム言語 ("en" | "ja"、既定 "en"): ラベルカタログと組み込みデータ検証メッセージを選び、
+     * グリッドのスクロールバー (矢印ラベル・端スクロールピル・"No items") へ素通し。非対応値は render 中
+     * RangeError — 言語ネゴシエーションなし (`navigator.language` の写像はホスト側)。値書式の BCP-47
+     * ロケールである `formats.locale` とは無関係 ("ja-JP" はここでは不正値)。
+     */
+    locale?: SpreadsheetLocale
     /**
      * UI label vocabulary (v0.8 §1.6) — folds the former `sinkAriaLabel` / `rootAriaLabel` props
-     * (clean cut-over). An omitted or explicitly `undefined` key keeps the English default. The
-     * resolved `sinkAriaLabel` MUST mention "Escape" (WCAG 2.1.2 escape advisement, §10-4) — a
-     * RangeError is thrown during render otherwise.
+     * (clean cut-over). 28 keys = the 7 engine chrome keys (scrollUp / scrollDown / scrollLeft /
+     * scrollRight / scrollToTop / scrollToBottom / noItems) + 21 own keys. An omitted prop or an
+     * explicitly `undefined` key keeps the value of the `locale` catalog. An unknown key or an
+     * empty / blank value throws a RangeError during render, and the resolved `sinkAriaLabel` MUST
+     * mention "Escape" (WCAG 2.1.2 escape advisement, §10-4).
      * UI ラベル語彙 (v0.8 §1.6) — 旧 sinkAriaLabel / rootAriaLabel prop を畳込み (クリーンカットオーバー)。
-     * 省略 / 明示 undefined は英語既定。解決後の sinkAriaLabel は "Escape" を含むこと (違反は render 中
-     * RangeError — §10-4)。
+     * 28 キー = エンジンクローム 7 キー (scrollUp / scrollDown / scrollLeft / scrollRight / scrollToTop /
+     * scrollToBottom / noItems) + 固有 21 キー。prop 省略 / 明示 undefined のキーは `locale` のカタログ値。
+     * 未知キー・空 / 空白値は render 中 RangeError、解決後の sinkAriaLabel は "Escape" を含むこと (§10-4)。
      */
     labels?: SpreadsheetLabelOverrides
     /**
@@ -453,7 +529,7 @@ export type SpreadsheetProps = {
     onClipChange?: (clip: ClipInfo | null) => void
     /** Hyperlink navigation seam (Alt+Enter, the link popover's Open button, and Ctrl / Meta+click on a link cell — spec 08 §11 D-53) — undeclared ⇒ no navigation, no Open button, no pointer gesture. / ハイパーリンク遷移シーム (Alt+Enter / Open ボタン / リンクセルへの Ctrl / Meta+クリック — 分冊 08 §11 D-53)。未宣言 = 遷移なし・Open ボタンなし・ポインタジェスチャなし。 */
     onHyperlinkOpen?: (url: string, cell: CellCoord) => void
-    /** Strict validation rejection notice (v0.8 §1.9) — the commit never reaches the adapter; the message popover shows the rejection. / strict 検証拒否の通知 (commit はアダプタへ届かず、message ポップオーバーが拒否を示す)。 */
+    /** Strict validation rejection notice (v0.8 §1.9) — the commit never reaches the adapter; the message popover shows the rejection. `message` is `rule.errorMessage` when declared, otherwise the built-in message in the active `locale`. / strict 検証拒否の通知 (commit はアダプタへ届かず、message ポップオーバーが拒否を示す)。`message` は `rule.errorMessage` 宣言時はそれ、未宣言なら現在の `locale` の組み込みメッセージ。 */
     onValidationRejected?: (ctx: { cell: CellCoord; rule: DataValidationRule; text: string; message: string }) => void
     /** Ctrl+Alt+V request with the active cell's viewport rect (visual px, keyboard-origin shape of onCellContextMenu); undeclared ⇒ `paste({ mode: "formats" })`. / Ctrl+Alt+V の要求通知 (未宣言なら書式のみ貼り付け)。 */
     onPasteSpecialRequest?: (origin: { kind: "keyboard"; cellRect: { top: number; left: number; width: number; height: number } }) => void
@@ -510,21 +586,6 @@ const ZOOM_MAX = 4
  * fail-fast — Math.min/max は NaN を素通しし、全 ÷z 境界の汚染と同値バウンド無効化 (NaN 同士は
  * 不一致) による onZoomChange(NaN) 連射を招くため。
  */
-/**
- * Validates one overscan prop and returns it unchanged (fail-fast — the engine clamps invalid
- * overscan silently, 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.
- * overscan prop 1 つの検証 (値はそのまま返す。fail-fast — エンジンは不正 overscan を無言
- * クランプするため拒否は本層所有)。undefined は宣言不在信号 (エンジン既定) で対象外。非整数・
- * 負値は RangeError。
- */
-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 ${value})`)
-    }
-    return value
-}
-
 const clampZoom = (value: number): number => {
     if (!Number.isFinite(value)) {
         throw new RangeError(`[spreadsheet] zoom must be a finite number (got ${value})`)
@@ -542,6 +603,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 カウンタ注入)。
@@ -560,6 +640,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
@@ -650,6 +739,28 @@ const requirePasteSheet = (sheet: PasteSheet | undefined): PasteSheet => {
     return sheet
 }
 
+/**
+ * Keeps the previous engine label object while all 7 strings are value-equal, so the object handed
+ * to the memoized GridBody changes identity only when a string changes (a host passing an inline
+ * `labels={{…}}` must not re-render the grid body on every shell render).
+ * 7 文字列がすべて値等価の間は前回のエンジンラベル object を保持 — memo 化された GridBody へ渡す
+ * object の identity は文字列が変わった時だけ変わる (インライン `labels={{…}}` のホストでも shell
+ * 再レンダー毎に本体を再描画させない)。
+ *
+ * @param next - The engine labels resolved in this render / 今回の render で解決したエンジンラベル
+ * @returns `next`, or the previous object when every key is value-equal / `next`、全キー値等価なら前回の object
+ */
+const useValueStableScrollLabels = (next: VirtualScrollLabels): VirtualScrollLabels => {
+    const stableRef = useRef<VirtualScrollLabels | null>(null)
+    const previous = stableRef.current
+    if (previous !== null && VIRTUAL_SCROLL_LABEL_KEYS.every((key) => previous[key] === next[key])) {
+        return previous
+    }
+    // レンダー時代入: 値等価比較の基準だけを保持し、副作用は持たない (破棄された render でも比較結果は同じ)
+    stableRef.current = next
+    return next
+}
+
 /** Initial A1 selection. / 初期 A1 選択。 */
 const INITIAL_SELECTION: SelectionState = {
     ranges: [makeRange({ row: 0, col: 0 }, { row: 0, col: 0 })],
@@ -674,6 +785,7 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
         overscanRows,
         overscanCols,
         background,
+        onRenderTruncated,
         renderCell,
         onSelectionChange,
         onCellContextMenu,
@@ -691,6 +803,7 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
         formatCellAnnouncement,
         formatSelectionAnnouncement,
         formatCommandAnnouncement,
+        locale,
         labels,
         shortcuts,
         colors,
@@ -715,6 +828,7 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
         className,
         __onCellRender,
         __onVirtualKeyboardRaise,
+        __maxRenderedCells,
     }: SpreadsheetProps & SpreadsheetTestProps,
     ref,
 ): ReactNode {
@@ -730,8 +844,12 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
     const viewStore = viewStoreRef.current
 
     // ---- prop 時検証 (v0.8 §4.2.13 — clampZoom と同じく render 中に RangeError を投げる) ----
+    // 非対応ロケールはここで render 中 RangeError — 以降の検証メッセージ / GridBody は解決済み値だけを受ける
+    const uiLocale = resolveVirtualScrollLocale(locale)
     // ラベルの畳込み: resolveLabels が Escape 告知 (§10-4) を検証する (RC22)
-    const resolvedLabels = useMemo(() => resolveLabels(labels), [labels])
+    const resolvedLabels = useMemo(() => resolveLabels(locale, labels), [locale, labels])
+    // GridBody は memo 境界 — インライン labels で毎回新 object になっても 7 文字列が同じなら identity を保つ
+    const scrollLabels = useValueStableScrollLabels(pickEngineLabels(resolvedLabels))
     // コマンド表: validateShortcuts の 5 条件 (+ 未知キー) は consumer の設定誤り — render 中に表面化
     const commandTable = useMemo(() => validateShortcuts(shortcuts), [shortcuts])
     // カスタム色スロット (各軸ちょうど 5 本の #rrggbb)
@@ -1830,10 +1948,12 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
      * The validation gate (v0.8 §4.2.6 / 分冊 08 §4.2), shared by the editor's changed commit and
      * the editing-column `fillSelection` (which runs it per target cell): no rule / non-strict ⇒
      * ok (the cell keeps its invalid mark); only a strict rejection stops the commit and reports
-     * through `onValidationRejected` + the `message` popover (`rejected`).
+     * through `onValidationRejected` + the `message` popover (`rejected`). The verdict message is
+     * `rule.errorMessage` when declared, otherwise the built-in message in the resolved UI locale.
      * 検証ゲート (v0.8 §4.2.6 / 分冊 08 §4.2) — エディタの変更ある確定と編集列 fillSelection (対象セル毎)
      * が共有。規則なし / 非 strict は受理 (セルは不正表示のまま)、strict の拒否だけが commit を止めて
-     * onValidationRejected + message ポップオーバー (rejected) を出す。
+     * onValidationRejected + message ポップオーバー (rejected) を出す。判定メッセージは `rule.errorMessage`
+     * 宣言時はそれ、未宣言なら解決済み UI ロケールの組み込みメッセージ。
      */
     const validateCommit = useCallback(
         (cell: CellCoord, text: string): ValidationVerdict => {
@@ -1842,7 +1962,7 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
                 return OK_VERDICT
             }
             const evaluateFormula = adapter.evaluateFormula
-            const verdict = validateCellText(rule, text, evaluateFormula === undefined ? undefined : (formula) => evaluateFormula(formula, cell))
+            const verdict = validateCellText(rule, text, uiLocale, evaluateFormula === undefined ? undefined : (formula) => evaluateFormula(formula, cell))
             if (verdict.ok || rule.strict !== true) {
                 return OK_VERDICT
             }
@@ -1853,7 +1973,7 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
             }
             return verdict
         },
-        [adapter, onValidationRejected],
+        [adapter, onValidationRejected, uiLocale],
     )
     const editor = useCellEditor({
         enabled: !isEmpty,
@@ -2402,6 +2522,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 が確定し得る
@@ -2635,6 +2817,7 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
                         overscanRows={validateOverscan("overscanRows", overscanRows)}
                         overscanCols={validateOverscan("overscanCols", overscanCols)}
                         background={background}
+                        onRenderTruncated={onRenderTruncated}
                         renderCell={renderCell}
                         onScroll={onScroll}
                         onRangeChange={onRangeChange}
@@ -2643,9 +2826,12 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
                         requestCommit={requestCommit}
                         testId={testId ? `${testId}-vs` : undefined}
                         __onCellRender={__onCellRender}
+                        __maxRenderedCells={__maxRenderedCells}
                         cfIndexRef={cfIndexRef}
                         cfMemoRef={cfMemoRef}
                         isPointing={isPointing}
+                        locale={uiLocale}
+                        scrollLabels={scrollLabels}
                     />
                     <SelectionOverlay
                         rowAxis={rowAxis}

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
 }
 
 /**