@aiquants/spreadsheet 0.8.0

package/src/model/frozenPartition.ts

@@ -0,0 +1,100 @@
+/**
+ * @fileoverview Frozen-axis coordinate partition (v0.5 plan §2 = columns; v0.6 plan §2 = rows).
+ * The engine paints frozen leading cells at their raw tree coordinate and scroll-band cells at
+ * tree − scroll, so a viewport ↔ index mapping splits at the frozen prefix size F_px: the
+ * forward map is `i < F ? offsetOf(i) : offsetOf(i) − scroll`, the inverse map (guarded on
+ * F_px > 0) is `F_px > 0 && p < F_px ? indexAt(p) : indexAt(p + scroll)`. Pure, AXIS-NEUTRAL
+ * internals (frozenSizeOf / toViewportPos / viewportPosToIndex) with column- and row-named
+ * thin wrappers — the freshness discipline (F/scroll from the handle) stays at the call sites.
+ *
+ * 凍結軸の座標パーティション (v0.5 計画 §2 = 列、v0.6 計画 §2 = 行)。エンジンは先頭凍結セルを
+ * 木座標の生値・スクロール帯セルを 木座標 − scroll で描くため、viewport ↔ index の写像は凍結
+ * 接頭辞幅 F_px で分割される。純関数の**軸中立**内部 (frozenSizeOf / toViewportPos /
+ * viewportPosToIndex) に列 / 行の名前付き薄ラッパーを重ねる — 鮮度規律 (F / scroll はハンドル
+ * 読み) は呼び出しサイトの責務。
+ */
+
+import type { AxisModel } from "./axisModel.ts"
+
+/**
+ * Axis-neutral tree-prefix size of the frozen band (0 when frozen <= 0 or empty axis; totalSize
+ * when frozen covers every track). Both frozenWidthOf and frozenHeightOf delegate here.
+ * 軸中立の凍結帯木接頭辞サイズ (frozen ≤ 0 / 空軸は 0、全トラック凍結は totalSize)。
+ * frozenWidthOf / frozenHeightOf の共通実体。
+ */
+const frozenSizeOf = (axis: AxisModel, frozen: number): number => {
+    if (frozen <= 0 || axis.count === 0) {
+        return 0
+    }
+    return frozen >= axis.count ? axis.totalSize() : axis.offsetOf(frozen)
+}
+
+/**
+ * Axis-neutral forward map: index to viewport position. Frozen leading tracks are static; scroll
+ * tracks subtract the scroll offset.
+ * 軸中立の順写像: index → viewport 位置。先頭凍結トラックは静的、スクロールトラックは scroll を引く。
+ */
+const toViewportPos = (axis: AxisModel, index: number, scroll: number, frozen: number): number => (index < frozen ? axis.offsetOf(index) : axis.offsetOf(index) - scroll)
+
+/**
+ * Axis-neutral inverse map: viewport position to index. The frozen branch exists ONLY when
+ * F_px > 0 — below F_px it resolves at the raw tree coordinate (negative p clamps into the
+ * leading frozen track, Excel-like nearest visible); at/after F_px the scroll band continues at
+ * tree = p + scroll. At F_px = 0 every p (incl. negative) keeps the v0.4 scroll-relative form
+ * (guard prevents an unguarded p < 0 from sinking into indexAt(p) = track 0).
+ * 軸中立の逆写像: viewport 位置 → index。凍結分岐は F_px > 0 のときのみ — F_px 未満は木座標の
+ * 生値 (負 p は先頭凍結トラックへクランプ)、以上はスクロール帯 (木 = p + scroll)。F_px = 0 は
+ * 負 p も含め全域 v0.4 形 (無ガードの p < 0 → indexAt(p) = トラック 0 の吸込を防ぐ)。
+ */
+const viewportPosToIndex = (axis: AxisModel, p: number, scroll: number, frozenSize: number): number => (frozenSize > 0 && p < frozenSize ? axis.indexAt(p) : axis.indexAt(p + scroll))
+
+/**
+ * Tree-prefix width of the frozen band on this axis (0 when F <= 0; totalSize when F covers
+ * every column). The render-surface twin of the engine's getFrozenSize().width — the pair-call
+ * discipline keeps the two equal.
+ * この軸の凍結帯の木接頭辞幅 (F ≤ 0 は 0、全列凍結は totalSize)。エンジン getFrozenSize().width
+ * の render 面双子 — 対呼び出し規律が両者を一致させる。
+ */
+export const frozenWidthOf = (axis: AxisModel, frozenCols: number): number => frozenSizeOf(axis, frozenCols)
+
+/**
+ * Frozen-band tree-prefix HEIGHT H_F (row twin of frozenWidthOf — v0.6 plan §2).
+ * 凍結帯の木接頭辞高 H_F (frozenWidthOf の行双子 — v0.6 計画 §2)。
+ */
+export const frozenHeightOf = (axis: AxisModel, frozenRows: number): number => frozenSizeOf(axis, frozenRows)
+
+/**
+ * Forward map: column index to viewport x (the left edge). Frozen columns are static; scroll
+ * columns subtract hx (v0.5 plan §2).
+ * 順写像: 列 index → viewport x (左端)。凍結列は静的、スクロール列は hx を引く。
+ */
+export const colToViewportX = (axis: AxisModel, col: number, hx: number, frozenCols: number): number => toViewportPos(axis, col, hx, frozenCols)
+
+/**
+ * Forward map: row index to viewport y (the top edge). Frozen rows static; scroll rows subtract vy (v0.6 plan §2).
+ * 順写像: 行 index → viewport y (上端)。凍結行は静的、スクロール行は vy を引く (v0.6 計画 §2)。
+ */
+export const rowToViewportY = (axis: AxisModel, row: number, vy: number, frozenRows: number): number => toViewportPos(axis, row, vy, frozenRows)
+
+/**
+ * Inverse map: viewport x to column index. The frozen branch exists ONLY when W_F > 0: below
+ * W_F the frozen band resolves at the raw tree coordinate (negative px clamps into the leading
+ * frozen column — Excel-like nearest visible); at or right of W_F the scroll band continues at
+ * tree = px + hx. At W_F = 0 every px — including negative (pointer left of the cells area
+ * during a leftward drag) — keeps the v0.4 hx-relative form (R2 fix: an unguarded `px < 0`
+ * would swallow negative px into indexAt(px) → column 0, breaking the F = 0 identity).
+ * 逆写像: viewport x → 列 index。凍結分岐は W_F > 0 のときのみ存在: W_F 未満は凍結帯
+ * (木座標の生値 — 負の px は先頭凍結列へクランプ。Excel 同型の最寄り可視)、W_F 以上は
+ * スクロール帯 (木座標 = px + hx)。W_F = 0 は負の px (左ドラッグでセル領域外へ出た
+ * ポインタ) も含め全域が v0.4 の hx 相対形 (R2 是正: 無ガードの `px < 0` は負 px を
+ * indexAt(px) = 列 0 へ吸い込み、F = 0 恒等を破る)。
+ */
+export const viewportXToCol = (axis: AxisModel, px: number, hx: number, frozenWidth: number): number => viewportPosToIndex(axis, px, hx, frozenWidth)
+
+/**
+ * Inverse map: viewport y to row index (row twin of viewportXToCol — v0.6 plan §2). Guarded on
+ * H_F > 0; H_F = 0 keeps the v0.4 vy-relative form for all py including negative.
+ * 逆写像: viewport y → 行 index (viewportXToCol の行双子 — v0.6 計画 §2)。H_F > 0 ガードつき、
+ * H_F = 0 は負 py も含め v0.4 の vy 相対形。
+ */
+export const viewportYToRow = (axis: AxisModel, py: number, vy: number, frozenHeight: number): number => viewportPosToIndex(axis, py, vy, frozenHeight)

package/src/model/labels.ts

@@ -0,0 +1,228 @@
+/**
+ * @fileoverview UI label vocabulary (v0.8 §1.6 / §4.1.17) — the ONE label bag of the package.
+ * The v0.7 `sinkAriaLabel` / `rootAriaLabel` props are folded into it (clean cut-over: no alias
+ * props remain), joined by the popover / indicator strings of the rich-cell UI. Pure, React-free.
+ *
+ * Contract (each clause is pinned by labels.spec.ts):
+ * - `SpreadsheetLabels` is the closed key set; `DEFAULT_LABELS` supplies an English default for
+ *   every key. Count-aware keys are typed `string | ((n: number) => string)`.
+ * - `resolveLabels(overrides)` is the single fold point: a key takes its override when the
+ *   override is not `undefined` and the default otherwise (exactly the destructuring-default
+ *   semantics the two folded props had in v0.7), then `assertLabels` runs on the result.
+ *   `undefined` overrides resolve to `DEFAULT_LABELS` by identity.
+ * - `assertLabels`: `sinkAriaLabel` MUST be a string mentioning "Escape" (WCAG 2.1.2 escape-method
+ *   advisement, spec 00 §10-4) — otherwise a RangeError, thrown at mount by the root.
+ * - `resolveLabel(labels, key, n)` is the single read point: a function-valued label receives `n`
+ *   (omitting `n` for a function value is a RangeError — never a silent 0), a string is returned
+ *   as-is (`n` ignored, so a consumer may override a count key with a plain string).
+ *
+ * UI ラベル語彙 (v0.8 §1.6 / §4.1.17) — パッケージ唯一のラベル集合。v0.7 の `sinkAriaLabel` /
+ * `rootAriaLabel` prop を畳み込み (クリーンカットオーバー: 別名 prop は残さない)、リッチセル UI の
+ * ポップオーバー / インジケータ文言を加える。純関数・React 非依存。
+ * 契約: `SpreadsheetLabels` は閉じたキー集合、`DEFAULT_LABELS` は全キーの英語既定、件数キーは
+ * `string | ((n: number) => string)`。`resolveLabels` が唯一の畳込み点 (undefined でない override を
+ * 採用、それ以外は既定 — 畳み込んだ 2 prop が v0.7 で持っていた分割代入既定と同じ意味論。
+ * override 未指定は `DEFAULT_LABELS` を identity で返却) で、続けて `assertLabels`
+ * (`sinkAriaLabel` は "Escape" を含む文字列であること — spec 00 §10-4、違反はマウント時 RangeError)。
+ * `resolveLabel` が唯一の読み出し点 (関数値は n 必須 — 省略は RangeError、文字列はそのまま)。
+ */
+
+/**
+ * The closed label vocabulary. Every key has a default in DEFAULT_LABELS; consumers override any
+ * subset through the `labels` prop (SpreadsheetLabelOverrides).
+ * 閉じたラベル語彙。全キーが DEFAULT_LABELS に既定を持ち、消費者は `labels` prop で任意の部分集合を上書き。
+ */
+export type SpreadsheetLabels = {
+    /** Accessible name of the sink (grid input receptor); MUST mention "Escape" (spec 00 §10-4). / シンクのアクセシブルネーム ("Escape" 必須)。 */
+    sinkAriaLabel: string
+    /** Accessible name of the root role="group" landing point. / root 着地点のアクセシブルネーム。 */
+    rootAriaLabel: string
+    /** Note popover heading. / ノートポップオーバーの見出し。 */
+    noteTitle: string
+    /** Note popover save button. / ノートの保存ボタン。 */
+    noteSave: string
+    /** Note popover hint in the normal state (Escape saves and closes). / 通常状態のノートヒント。 */
+    noteEscapeHint: string
+    /** Note popover hint in the rejected state (Ctrl+Enter retries, Escape closes without saving). / 拒否状態のノートヒント。 */
+    noteRejectedHint: string
+    /** Comment popover heading. / コメントポップオーバーの見出し。 */
+    commentTitle: string
+    /** Comment reply field label. / 返信入力欄のラベル。 */
+    commentReply: string
+    /** Comment post button. / コメント投稿ボタン。 */
+    commentPost: string
+    /** Comment count text; a function receives the thread length. / コメント件数 (関数はスレッド長を受け取る)。 */
+    commentCount: string | ((n: number) => string)
+    /** Link popover heading. / リンクポップオーバーの見出し。 */
+    linkTitle: string
+    /** Link popover display-text field label. / リンク表示文字列の入力欄ラベル。 */
+    linkTextField: string
+    /** Link popover URL field label. / リンク URL の入力欄ラベル。 */
+    linkUrlField: string
+    /** Link popover open button (only when onHyperlinkOpen is declared). / リンクを開くボタン。 */
+    linkOpen: string
+    /** Link popover save button. / リンクの保存ボタン。 */
+    linkSave: string
+    /** Validation-list popover heading. / 検証リストポップオーバーの見出し。 */
+    listTitle: string
+    /** Validation-list popover text when no option matches. / 候補なしの表示。 */
+    listEmpty: string
+    /** Validation-list popover overflow row (options beyond the render cap); a function receives the hidden-option count. / 検証リストの上限超過行 (描画上限を超えた候補) — 関数は非表示件数を受け取る。 */
+    listMore: string | ((n: number) => string)
+    /** Message popover heading. / メッセージポップオーバーの見出し。 */
+    messageTitle: string
+    /** Message shown when a strict validation rule rejects the typed value. / 厳格検証で拒否されたときの文言。 */
+    validationRejected: string
+    /** Close button of every popover. / ポップオーバー共通の閉じるボタン。 */
+    popoverClose: string
+    /** Accessible label of the note indicator on a cell. / ノートインジケータのラベル。 */
+    indicatorNote: string
+    /** Accessible label of the comment indicator on a cell. / コメントインジケータのラベル。 */
+    indicatorComment: string
+    /** Accessible label of the invalid-value indicator on a cell. / 無効値インジケータのラベル。 */
+    indicatorInvalid: string
+}
+
+/**
+ * The `labels` prop shape: any subset of SpreadsheetLabels (an omitted or `undefined` key keeps
+ * the default). Keys are closed to SpreadsheetLabels.
+ * `labels` prop の形: SpreadsheetLabels の任意の部分集合 (省略 / undefined は既定のまま)。キーは
+ * SpreadsheetLabels に閉じる。
+ */
+export type SpreadsheetLabelOverrides = { readonly [K in keyof SpreadsheetLabels]?: SpreadsheetLabels[K] }
+
+/**
+ * Every label key, in declaration order — the iteration source of the fold and the census list
+ * for docs / tests. Compile-time proof below that it covers EVERY SpreadsheetLabels key.
+ * 全ラベルキー (宣言順) — 畳込みの走査元と docs / テストの census 表。直下で全キー網羅を型水準で証明。
+ */
+export const LABEL_KEYS = [
+    "sinkAriaLabel",
+    "rootAriaLabel",
+    "noteTitle",
+    "noteSave",
+    "noteEscapeHint",
+    "noteRejectedHint",
+    "commentTitle",
+    "commentReply",
+    "commentPost",
+    "commentCount",
+    "linkTitle",
+    "linkTextField",
+    "linkUrlField",
+    "linkOpen",
+    "linkSave",
+    "listTitle",
+    "listEmpty",
+    "listMore",
+    "messageTitle",
+    "validationRejected",
+    "popoverClose",
+    "indicatorNote",
+    "indicatorComment",
+    "indicatorInvalid",
+] as const satisfies readonly (keyof SpreadsheetLabels)[]
+
+/** Compile-time proof that LABEL_KEYS lists EVERY SpreadsheetLabels key (a key added to the type but not to the list would never be folded). / LABEL_KEYS が SpreadsheetLabels の全キーを網羅することの型水準の証明 (型に増えたキーが表に無いと畳込みから漏れる)。 */
+const labelKeysCoverEveryKey: [Exclude<keyof SpreadsheetLabels, (typeof LABEL_KEYS)[number]>] extends [never] ? true : never = true
+void labelKeysCoverEveryKey
+
+/**
+ * English defaults for every key. `sinkAriaLabel` / `rootAriaLabel` are byte-identical to the
+ * v0.7 prop defaults (the fold is DOM-identical); `noteEscapeHint` = "Escape saves and closes";
+ * `commentCount` and `listMore` pluralise ("1 comment" / "n comments", "1 more value" / "n more values"). Frozen.
+ * 全キーの英語既定。`sinkAriaLabel` / `rootAriaLabel` は v0.7 の prop 既定と byte 同一 (畳込みは
+ * DOM 恒等)、`noteEscapeHint` = "Escape saves and closes"、`commentCount` / `listMore` は単複を区別。凍結済み。
+ */
+export const DEFAULT_LABELS: SpreadsheetLabels = Object.freeze({
+    sinkAriaLabel: "Spreadsheet grid. Press Escape to move focus out of the grid.",
+    rootAriaLabel: "Spreadsheet",
+    noteTitle: "Note",
+    noteSave: "Save",
+    noteEscapeHint: "Escape saves and closes",
+    noteRejectedHint: "The note was rejected. Press Ctrl+Enter to retry or Escape to close without saving",
+    commentTitle: "Comments",
+    commentReply: "Reply",
+    commentPost: "Post",
+    commentCount: (n: number): string => (n === 1 ? "1 comment" : `${n} comments`),
+    linkTitle: "Link",
+    linkTextField: "Text",
+    linkUrlField: "URL",
+    linkOpen: "Open",
+    linkSave: "Save",
+    listTitle: "Choose a value",
+    listEmpty: "No matching values",
+    listMore: (n: number): string => (n === 1 ? "1 more value — keep typing to narrow" : `${n} more values — keep typing to narrow`),
+    messageTitle: "Data validation",
+    validationRejected: "The value does not satisfy this cell's validation rule",
+    popoverClose: "Close",
+    indicatorNote: "Has a note",
+    indicatorComment: "Has comments",
+    indicatorInvalid: "Invalid value",
+})
+
+/**
+ * Mount-time check of a resolved label bag: `sinkAriaLabel` must be a string that mentions
+ * "Escape" (case-sensitive — the WCAG 2.1.2 escape-method advisement of spec 00 §10-4). Anything
+ * else is a consumer configuration error ⇒ RangeError (fail-fast, never silently repaired).
+ * 解決済みラベル集合のマウント時検証: `sinkAriaLabel` は "Escape" を含む文字列であること
+ * (大文字小文字を区別 — spec 00 §10-4 の WCAG 2.1.2 脱出告知)。それ以外は消費者の設定誤りとして
+ * RangeError (fail-fast、黙って修復しない)。
+ */
+export const assertLabels = (labels: SpreadsheetLabels): void => {
+    const sink = labels.sinkAriaLabel
+    // 文字列以外 (JS 呼び手) と Escape 告知の欠落は同じ設定誤り
+    if (typeof sink !== "string" || !sink.includes("Escape")) {
+        throw new RangeError(`[spreadsheet] labels.sinkAriaLabel must be a string mentioning "Escape" (WCAG 2.1.2 escape advisement, spec 00 §10-4); got ${JSON.stringify(sink)}`)
+    }
+}
+
+/** Writes one resolved label; generic so the union-typed key of the fold loop type-checks against the per-key value type. / 解決済みラベルを 1 件書く (畳込みループの union キーをキー毎の値型と突き合わせるための総称関数)。 */
+const putLabel = <K extends keyof SpreadsheetLabels>(target: SpreadsheetLabels, key: K, value: SpreadsheetLabels[K]): void => {
+    target[key] = value
+}
+
+/**
+ * The single fold point of the `labels` prop: every key takes the override when it is not
+ * `undefined`, the default otherwise (destructuring-default semantics of the folded v0.7 props);
+ * the result is validated by assertLabels and frozen. `undefined` overrides return DEFAULT_LABELS
+ * by identity. Inputs are never mutated.
+ * `labels` prop の唯一の畳込み点: 各キーは override が undefined でなければ override、さもなくば
+ * 既定 (畳み込んだ v0.7 prop の分割代入既定の意味論)。結果は assertLabels で検証し凍結。override
+ * 未指定は DEFAULT_LABELS を identity で返す。入力は変更しない。
+ */
+export const resolveLabels = (overrides: SpreadsheetLabelOverrides | undefined): SpreadsheetLabels => {
+    // override なしは既定そのもの (identity 安定 — 消費者の useMemo 再計算でも同一 object)
+    if (overrides === undefined) {
+        return DEFAULT_LABELS
+    }
+    const resolved: SpreadsheetLabels = { ...DEFAULT_LABELS }
+    // 明示 undefined は「未指定」= 既定のまま (分割代入既定と同じ)
+    for (const key of LABEL_KEYS) {
+        const value = overrides[key]
+        if (value !== undefined) {
+            putLabel(resolved, key, value)
+        }
+    }
+    assertLabels(resolved)
+    return Object.freeze(resolved)
+}
+
+/**
+ * The single read point: resolves one label to its display string. A function-valued label is
+ * called with `n` (a missing `n` is a caller bug ⇒ RangeError — no silent 0); a string label is
+ * returned as-is and ignores `n`.
+ * 唯一の読み出し点: ラベル 1 件を表示文字列へ解決。関数値は n で呼ぶ (n 省略は呼び手バグとして
+ * RangeError — 黙って 0 にしない)、文字列値はそのまま (n は無視)。
+ */
+export const resolveLabel = (labels: SpreadsheetLabels, key: keyof SpreadsheetLabels, n?: number): string => {
+    const value = labels[key]
+    // 関数値だけが件数を要する
+    if (typeof value === "function") {
+        if (n === undefined) {
+            throw new RangeError(`[spreadsheet] labels.${key} is count-aware; resolveLabel needs n`)
+        }
+        return value(n)
+    }
+    return value
+}

package/src/model/viewStore.ts

@@ -0,0 +1,124 @@
+/**
+ * @fileoverview Tiny external store for the scroll view state. Scroll positions change every
+ * frame, so they must NOT live in React state of the root — and since v0.4 they do not live
+ * here either: the VirtualGrid handle is the SINGLE truth for both axes (`getScrollPosition()`
+ * / `getViewportSize()` — synchronous ref reads), and this store carries only the values React
+ * leaves need for re-render loops: the row/column RENDERING ranges (RowHeader / ColumnHeader
+ * placement) and the geometry/edit versions (re-slice levers). vy remains here solely as the
+ * rAF-notified mirror the row-side leaves subscribe to; there is deliberately NO hx and NO
+ * bodyWidth field (the v0.3 sync-hx SSOT is retired — §7-4 of the VirtualGrid design plan:
+ * freshness reads belong to the handle, and a store copy would be a second source of truth).
+ *
+ * スクロール視点の極小外部ストア。毎フレーム変わる値を root の state に置けないのは従来どおり
+ * だが、v0.4 からは**本ストアにも置かない**: 両軸の位置は VirtualGrid ハンドル
+ * (`getScrollPosition()` / `getViewportSize()` — 同期 ref 読み) が単一の真実で、ここは React の
+ * 葉が再レンダーに必要とする値だけを運ぶ — 行 / 列の描画レンジ (RowHeader / ColumnHeader の
+ * 配置) と幾何 / 編集 version (再スライスのレバー)。vy は行側の葉が購読する rAF 通知写像として
+ * のみ残る。hx / bodyWidth フィールドは**意図的に存在しない** (v0.3 の同期 hx SSOT は退役 —
+ * 設計計画 §7-4: 鮮度読みはハンドルへ、ストア複製は第 2 の真実になる)。
+ */
+
+/** Snapshot of the scroll view state. / スクロール視点状態のスナップショット。 */
+export type ViewState = {
+    /** rAF-notified mirror of the vertical position (leaves only; freshness reads use the handle). / 縦位置の rAF 通知写像 (葉専用 — 鮮度読みはハンドル)。 */
+    vy: number
+    rowStart: number
+    rowEnd: number
+    /** Rendering column range from VirtualGrid's onRangeChange (overscan-inclusive; ColumnHeader source — the §7-5 re-render loop). / VirtualGrid onRangeChange 由来の描画列レンジ (ColumnHeader の再レンダー源 — §7-5)。 */
+    colStart: number
+    colEnd: number
+    colVersion: number
+    rowGeomVersion: number
+    editVersion: number
+}
+
+/** The store contract. / ストア契約。 */
+export type ViewStore = {
+    get: () => ViewState
+    setVy: (vy: number) => void
+    /** Rendering row range from onRangeChange (overscan-inclusive; RowHeader source). / onRangeChange 由来の描画行レンジ。 */
+    setRowRange: (start: number, end: number) => void
+    /** Rendering column range from onRangeChange (overscan-inclusive; ColumnHeader source — row-symmetric §7-5). / onRangeChange 由来の描画列レンジ (行側 setRowRange の完全対称)。 */
+    setColRange: (start: number, end: number) => void
+    /** Bumped by resizeColumn to re-render the column header (cells re-slice via the grid's own width epoch). / 列幅変更 (resizeColumn) の列ヘッダー再レンダー通知 (セル再スライスはグリッド側の幅エポックが担う)。 */
+    bumpColVersion: () => void
+    /** Bumped by resizeRow to re-place row labels. / 行ジオメトリ変更のヘッダー再配置通知。 */
+    bumpRowGeometry: () => void
+    /** Bumped after each successful applyEdits (internal half of renderVersion). / applyEdits 成功の再描画通知。 */
+    bumpEdit: () => void
+    /**
+     * The ONLY subscription form: all changes coalesce inside one frame into a single rAF
+     * notification. getSnapshot always reads the synchronous latest value, so delivery timing
+     * never harms correctness. A separate synchronous subscribe deliberately does not exist
+     * (the v0.3 bodyWidth sync-notify exception retired with the field — width now lives in
+     * the VirtualGrid viewport and its ResizeObserver drives React directly).
+     * 唯一の購読形式。全変更はフレーム内 rAF 量子化で 1 通知に合流する。getSnapshot は常に同期
+     * 最新値を読むため配送タイミングは正しさを害さない。同期購読は意図的に存在しない (v0.3 の
+     * bodyWidth 同期通知例外はフィールドごと退役 — 幅は VirtualGrid ビューポートが所有)。
+     */
+    subscribeCoalesced: (listener: () => void) => () => void
+}
+
+/** Vertical scrollbar width in px (SSOT — §6.9-3; also the grid's horizontal bar height). / 縦バー幅 px (SSOT — 横バー高も同値)。 */
+export const SCROLLBAR_WIDTH = 12
+
+/** Creates a view store instance. / viewStore インスタンスを構築。 */
+export const createViewStore = (): ViewStore => {
+    let state: ViewState = { vy: 0, rowStart: 0, rowEnd: 0, colStart: 0, colEnd: 0, colVersion: 0, rowGeomVersion: 0, editVersion: 0 }
+    const listeners = new Set<() => void>()
+    let rafId: number | null = null
+    const flush = () => {
+        // 共有 rAF 1 本で全リスナーへ通知。bail はリスナー側 (useSyncExternalStore の
+        // スナップショット比較) が担うため、ここでは無差別に呼んでよい
+        rafId = null
+        for (const listener of [...listeners]) {
+            listener()
+        }
+    }
+    const schedule = () => {
+        // 購読者ゼロなら予約しない (unmount 後の set が rAF をリークしない — 単体テスト (c))
+        if (listeners.size === 0) {
+            return
+        }
+        // フレーム内の何度目の変更でも予約は 1 本 — これが量子化の本体
+        if (rafId === null) {
+            rafId = requestAnimationFrame(flush)
+        }
+    }
+    const set = (partial: Partial<ViewState>) => {
+        state = { ...state, ...partial }
+        schedule()
+    }
+    return {
+        get: () => state,
+        setVy: (vy) => {
+            if (vy !== state.vy) {
+                set({ vy })
+            }
+        },
+        setRowRange: (rowStart, rowEnd) => {
+            if (rowStart !== state.rowStart || rowEnd !== state.rowEnd) {
+                set({ rowStart, rowEnd })
+            }
+        },
+        setColRange: (colStart, colEnd) => {
+            if (colStart !== state.colStart || colEnd !== state.colEnd) {
+                set({ colStart, colEnd })
+            }
+        },
+        bumpColVersion: () => set({ colVersion: state.colVersion + 1 }),
+        bumpRowGeometry: () => set({ rowGeomVersion: state.rowGeomVersion + 1 }),
+        bumpEdit: () => set({ editVersion: state.editVersion + 1 }),
+        subscribeCoalesced: (listener) => {
+            listeners.add(listener)
+            return () => {
+                listeners.delete(listener)
+                if (listeners.size === 0 && rafId !== null) {
+                    // 全購読解除で保留 rAF を回収 (unmount 後の宙吊り通知を残さない)
+                    cancelAnimationFrame(rafId)
+                    rafId = null
+                }
+            }
+        },
+    }
+}