@aiquants/spreadsheet 0.8.0

package/src/model/formulaRefs.ts

@@ -0,0 +1,984 @@
+/**
+ * @fileoverview Formula reference engine (v0.8 §2.8): a hand-rolled A1 / R1C1 scanner and the
+ * pure transforms built on it — shifting on paste, the R1C1 relative form carried by the clip
+ * payload, the F4 anchor cycle, reference text for pointing insertion, and the pointing
+ * predicate (§2.7 / design v5). Pure, React-free and TOTAL fail-soft like cellFormat.ts: text
+ * that is not a formula or not a reference passes through verbatim; the only throws are
+ * RangeErrors on invalid consumer input (non-integer deltas / origins / coordinates, a
+ * non-positive memo limit — fail-fast on the API surface, never a silent substitution).
+ *
+ * Grammar (charCode loop, ≤ 1 µs per typical formula, no regex in the hot path):
+ * - cell `$?LETTERS$?DIGITS` (row ≥ 1; ≤ 11 letters / ≤ 15 digits so every index stays a safe
+ *   integer — columns beyond XFD are accepted, the grid bounds the axis, not Excel), range
+ *   `cell:cell`, whole column `$?LETTERS:$?LETTERS`, whole row `$?DIGITS:$?DIGITS`;
+ * - a sheet qualifier is kept VERBATIM and never interpreted (`Sheet1!`, `'Sheet 1'!` with
+ *   `''` escape, 3-D `Sheet1:Sheet3!`, unquoted non-ASCII names);
+ * - string literals (`"…"` with `""` escape) are opaque; a word followed by `(` is a function
+ *   call (`LOG10(` is never the cell `LOG10`); a word continuing into `_ . [ $` or a non-ASCII
+ *   code unit is a name (`A1_x`, `Table1[Col]`); a bracket run is opaque like a string literal
+ *   (structured references `Table1[Q1]` / `[@Col]`, nesting, `'` escaping the next char, an
+ *   unterminated run swallows the rest) — Excel / Sheets never rewrite text inside `[...]`, so
+ *   its contents are never handed to either grammar; `#REF!` stays `#REF!`;
+ * - R1C1 in the Google Sheets spelling: `R[-1]C[0]` relative (a zero offset is spelled
+ *   `[0]`), `R3C2` absolute (1-based), mixed `R2C[7]`, whole axis `C[-6]` / `R[2]`; bare
+ *   `R` / `C` are accepted on input as offset 0. As in Excel, names that spell a valid R1C1
+ *   reference (`R`, `C`, `RC`, `R1C1`) are reserved — the round trip cannot tell them apart.
+ *
+ * Memoisation guidance: every transform re-scans its input; a caller that sees the same
+ * formula text many times (a 100k-cell paste of ≤ 100 distinct formulas) owns ONE bounded
+ * `Map<string, …>` built with {@link createFormulaMemo} (`createFormulaMemo(tokenizeFormula)`
+ * is the tokenizer cache). {@link fromR1C1} carries its own R1C1 parse memo, so the paste path
+ * meets the §5.6 budget without caller cooperation.
+ *
+ * 数式参照エンジン (v0.8 §2.8): 手書き A1 / R1C1 スキャナと、その上の純変換 — 貼り付け時の
+ * シフト、クリップが運ぶ R1C1 相対形、F4 アンカー循環、ポインティング挿入文字列、ポインティング
+ * 述語 (§2.7 / 設計 v5)。cellFormat.ts と同じく純関数・React 非依存・全経路 fail-soft (数式で
+ * ない / 参照でない文字列は素通し)。throw は不正な consumer 入力 (非整数の差分 / 原点 / 座標、
+ * 非正のメモ上限) の RangeError のみ (API 面の fail-fast — 黙った値代替はしない)。
+ * 文法: セル `$?英字$?数字` (行 ≥ 1、英字 ≤ 11 / 数字 ≤ 15 で全索引が安全整数、XFD 超の列も
+ * 受理)、レンジ、全列 / 全行、シート修飾子は**原文のまま**保持、文字列リテラルは不透過、`(`
+ * が続く語は関数、`_ . [ $` や非 ASCII に続く語は名前、角括弧の連なり (構造化参照 `Table1[Q1]` /
+ * `[@Col]`、入れ子可、`'` は次の 1 文字を脱出、未終端は末尾まで) は文字列リテラル同様不透過で
+ * 中身は決して走査しない (Excel / Sheets は `[...]` 内を書き換えない)。R1C1 は Google Sheets 綴り (相対 0 も
+ * `[0]`、絶対は 1 始まり、素の `R` / `C` は入力時のみ差分 0 として受理)。Excel 同様、R1C1
+ * 参照と同綴りの名前 (`R` / `C` / `RC` / `R1C1`) は予約 — 往復で区別できない。
+ * メモ指針: 各変換は毎回走査する。同じ数式文字列を何度も見る呼び出し側 (≤ 100 種の数式の
+ * 10 万セル貼り付け) は {@link createFormulaMemo} で上限つき `Map<string, …>` を 1 つ持つ
+ * (`createFormulaMemo(tokenizeFormula)` がトークナイザキャッシュ)。{@link fromR1C1} は
+ * 自前の R1C1 解析メモを持ち、貼り付け経路は呼び出し側の協力なしに §5.6 予算を満たす。
+ */
+
+import type { CellCoord, CellRange } from "./cellCoord.ts"
+
+/** One end of a cell range (0-based, per-axis `$` anchors). / レンジの片端 (0 始まり・軸毎の `$` アンカー)。 */
+export type ReferenceCell = { row: number; col: number; absRow: boolean; absCol: boolean }
+
+/** One end of a whole-column reference. / 全列参照の片端。 */
+export type ReferenceColumn = { col: number; abs: boolean }
+
+/** One end of a whole-row reference. / 全行参照の片端。 */
+export type ReferenceRow = { row: number; abs: boolean }
+
+/**
+ * A scanned A1 reference. Indices are 0-based grid coordinates; `sheet` is the verbatim
+ * qualifier text before `!` (quotes included) when the reference is sheet-qualified. Whole-axis
+ * kinds always carry both ends (`A:A` has `start.col === end.col`).
+ * 走査済み A1 参照。索引は 0 始まりのグリッド座標、`sheet` はシート修飾時の `!` 前の原文
+ * (クオート込み)。全軸種は常に両端を持つ (`A:A` は `start.col === end.col`)。
+ */
+export type ReferenceToken =
+    | { kind: "cell"; row: number; col: number; absRow: boolean; absCol: boolean; sheet?: string }
+    | { kind: "range"; start: ReferenceCell; end: ReferenceCell; sheet?: string }
+    | { kind: "column"; start: ReferenceColumn; end: ReferenceColumn; sheet?: string }
+    | { kind: "row"; start: ReferenceRow; end: ReferenceRow; sheet?: string }
+
+/** A reference with its `[start, end)` character span in the formula (sheet part included). / 数式内の文字区間 `[start, end)` つき参照 (シート部を含む)。 */
+export type ReferenceSpan = { start: number; end: number; token: ReferenceToken }
+
+/** Which axis a pointing insertion spans (cell / drag rectangle, column headers, row headers). / ポインティング挿入が張る軸 (セル / ドラッグ矩形、列ヘッダー、行ヘッダー)。 */
+export type ReferenceAxis = "cells" | "columns" | "rows"
+
+/** Where a pointed reference goes: inserted at the caret, or replacing the token under it. / 指した参照の行き先: キャレット位置へ挿入、またはキャレット下トークンの置換。 */
+export type PointingTarget = { insertAt: number } | { replace: [number, number] }
+
+/** The Excel reference error every out-of-grid shift collapses to. / グリッド外へのシフトが必ず畳まれる Excel の参照エラー。 */
+const REF_ERROR = "#REF!"
+
+/** Column-letter bound: 26^11 < 2^53, so any accepted column index is a safe integer. / 列英字の上限 (26^11 < 2^53 — 受理した列索引は必ず安全整数)。 */
+const MAX_COLUMN_LETTERS = 11
+
+/** Digit bound for row / R1C1 indices: 10^15 < 2^53. / 行 / R1C1 索引の桁上限 (10^15 < 2^53)。 */
+const MAX_INDEX_DIGITS = 15
+
+/** Memo overflow guard (the plan's memo ceiling); the map is cleared, never evicted one by one. / メモ安全弁 (計画のメモ上限)。個別追い出しはせず全消去。 */
+const FORMULA_MEMO_LIMIT = 4096
+
+// 走査で比較する ASCII コード (charCodeAt ループ — 正規表現は熱経路に置かない)
+const CODE_BANG = 33
+const CODE_QUOTE = 34
+const CODE_DOLLAR = 36
+const CODE_AMPERSAND = 38
+const CODE_APOSTROPHE = 39
+const CODE_LPAREN = 40
+const CODE_ASTERISK = 42
+const CODE_PLUS = 43
+const CODE_COMMA = 44
+const CODE_MINUS = 45
+const CODE_DOT = 46
+const CODE_SLASH = 47
+const CODE_COLON = 58
+const CODE_SEMICOLON = 59
+const CODE_LT = 60
+const CODE_EQUALS = 61
+const CODE_GT = 62
+const CODE_UPPER_C = 67
+const CODE_UPPER_R = 82
+const CODE_LBRACKET = 91
+const CODE_RBRACKET = 93
+const CODE_CARET = 94
+const CODE_UNDERSCORE = 95
+
+/** ASCII letter test. / ASCII 英字判定。 */
+const isLetter = (code: number): boolean => (code >= 65 && code <= 90) || (code >= 97 && code <= 122)
+
+/** ASCII digit test. / ASCII 数字判定。 */
+const isDigit = (code: number): boolean => code >= 48 && code <= 57
+
+/**
+ * Identifier continuation: letters, digits, `_`, `.`, `$` and every non-ASCII code unit — the
+ * characters a name, number literal or unquoted sheet name is made of.
+ * 識別子の継続文字: 英数字・`_`・`.`・`$`・全非 ASCII — 名前 / 数値リテラル / 非クオートの
+ * シート名を構成する文字。
+ */
+const isIdentifierChar = (code: number): boolean => isLetter(code) || isDigit(code) || code === CODE_UNDERSCORE || code === CODE_DOT || code === CODE_DOLLAR || code >= 0x80
+
+/** JavaScript `\s` membership (the `\s*` of the pointing trigger, hand-rolled). / JavaScript の `\s` 判定 (ポインティング契機の `\s*` を手書き)。 */
+const isSpace = (code: number): boolean => code === 32 || (code >= 9 && code <= 13) || code === 0xa0 || code === 0x1680 || (code >= 0x2000 && code <= 0x200a) || code === 0x2028 || code === 0x2029 || code === 0x202f || code === 0x205f || code === 0x3000 || code === 0xfeff
+
+/** Membership in the pointing trigger set `[=(,;+\-*\/^&<>:]` (§2.7). / ポインティング契機集合 `[=(,;+\-*\/^&<>:]` の判定 (§2.7)。 */
+const isTrigger = (code: number): boolean =>
+    code === CODE_EQUALS ||
+    code === CODE_LPAREN ||
+    code === CODE_COMMA ||
+    code === CODE_SEMICOLON ||
+    code === CODE_PLUS ||
+    code === CODE_MINUS ||
+    code === CODE_ASTERISK ||
+    code === CODE_SLASH ||
+    code === CODE_CARET ||
+    code === CODE_AMPERSAND ||
+    code === CODE_LT ||
+    code === CODE_GT ||
+    code === CODE_COLON
+
+/**
+ * Whether a reference candidate ending at `pos` is delimited — i.e. not the prefix of a longer
+ * name (`A1_x`), a function call (`LOG10(`), a sheet qualifier (`Sheet1!`) or a structured
+ * reference (`Table1[`).
+ * `pos` で終わる参照候補が区切られているか — より長い名前 (`A1_x`) / 関数呼出 (`LOG10(`) /
+ * シート修飾子 (`Sheet1!`) / 構造化参照 (`Table1[`) の接頭辞でないこと。
+ */
+const isDelimited = (text: string, pos: number): boolean => {
+    if (pos >= text.length) {
+        return true
+    }
+    const code = text.charCodeAt(pos)
+    return !(isIdentifierChar(code) || code === CODE_LPAREN || code === CODE_BANG || code === CODE_LBRACKET)
+}
+
+/** Index just past the identifier run starting at `from` (`from` itself when none). / `from` から始まる識別子連なりの直後 (無ければ `from`)。 */
+const skipIdentifier = (text: string, from: number): number => {
+    let i = from
+    while (i < text.length && isIdentifierChar(text.charCodeAt(i))) {
+        i += 1
+    }
+    return i
+}
+
+/**
+ * Index just past a quoted run opened at `from` (`"…"` or `'…'`, doubled quote = escape);
+ * `text.length` when unterminated.
+ * `from` で開くクオート区間 (`"…"` / `'…'`、二重クオートはエスケープ) の直後。未終端なら
+ * `text.length`。
+ */
+const skipQuoted = (text: string, from: number, quote: number): number => {
+    let i = from + 1
+    while (i < text.length) {
+        if (text.charCodeAt(i) === quote) {
+            // 二重クオートはエスケープ — 区間を閉じない
+            if (text.charCodeAt(i + 1) === quote) {
+                i += 2
+                continue
+            }
+            return i + 1
+        }
+        i += 1
+    }
+    return text.length
+}
+
+/**
+ * Index just past the structured-reference bracket run opened at `from` (`[` on entry): tracks
+ * nesting depth (`Table1[[#Totals],[Q1]]`) and honours the `'` escape of structured references
+ * (`'[ '] '' '#` — the `'` makes the next code unit literal); `text.length` when unterminated
+ * (the run is opaque to the end, like an unterminated string literal).
+ * `from` (`[` の位置) で開く構造化参照の角括弧連なりの直後。入れ子深度を追跡し
+ * (`Table1[[#Totals],[Q1]]`)、構造化参照の `'` 脱出 (`'[ '] '' '#` — `'` は次の 1 文字を素通し)
+ * を尊重。未終端なら `text.length` (未終端リテラルと同じく末尾まで不透過)。
+ */
+const skipBrackets = (text: string, from: number): number => {
+    let depth = 0
+    let i = from
+    while (i < text.length) {
+        const code = text.charCodeAt(i)
+        if (code === CODE_APOSTROPHE) {
+            // 構造化参照の脱出: ' は直後の 1 文字を字義どおりにする ('[ '] '' '#)
+            i += 2
+            continue
+        }
+        if (code === CODE_LBRACKET) {
+            depth += 1
+        } else if (code === CODE_RBRACKET) {
+            depth -= 1
+            if (depth === 0) {
+                return i + 1
+            }
+        }
+        i += 1
+    }
+    return text.length
+}
+
+/** A parsed reference plus the index just past it. / 解析済み参照と直後の索引。 */
+type Parsed<T> = { end: number; token: T }
+
+/** A positional grammar: parse one reference at `from` or report null (no boundary policing). / 位置文法: `from` の参照を 1 つ解析するか null (境界判定は含まない)。 */
+type ParseAt<T> = (text: string, from: number) => Parsed<T> | null
+
+/** A span of any token flavour (A1 or R1C1). / 任意トークン種 (A1 / R1C1) の区間。 */
+type Span<T> = { start: number; end: number; token: T }
+
+/**
+ * Parses the reference after the `!` at `bang` and records it with the verbatim sheet part
+ * `text[sheetStart, bang)`; returns the resume index (past the reference, or past the `!`).
+ * `bang` の `!` 直後の参照を解析し、原文のシート部 `text[sheetStart, bang)` を付けて記録。
+ * 再開位置 (参照の直後、無ければ `!` の直後) を返す。
+ */
+const scanQualified = <T extends { sheet?: string }>(text: string, sheetStart: number, bang: number, parseAt: ParseAt<T>, spans: Span<T>[]): number => {
+    const parsed = parseAt(text, bang + 1)
+    if (parsed !== null && isDelimited(text, parsed.end)) {
+        spans.push({ start: sheetStart, end: parsed.end, token: { ...parsed.token, sheet: text.slice(sheetStart, bang) } })
+        return parsed.end
+    }
+    return bang + 1
+}
+
+/**
+ * The shared scanner: walks the text once, skipping string literals and structured-reference
+ * bracket runs (both opaque), resolving sheet qualifiers (quoted, unquoted, 3-D) and handing
+ * each word start to the positional grammar. A name followed by `[` (`Table1[Q1]`) lands the
+ * resume index on the `[`, so the bracket branch below covers named and bare (`[@Col]`) runs
+ * alike; a valid R1C1 axis (`R[-1]`) never reaches it — `parseAt` consumes those brackets.
+ * 共通スキャナ: 文字列リテラルと構造化参照の角括弧連なり (どちらも不透過) を飛ばし、シート
+ * 修飾子 (クオート / 非クオート / 3-D) を解決し、各語頭を位置文法へ渡す 1 パス走査。`[` が続く
+ * 名前 (`Table1[Q1]`) は再開位置が `[` に着地するため、下の角括弧分岐が名前つき / 裸
+ * (`[@Col]`) の両形を覆う。正しい R1C1 軸 (`R[-1]`) の括弧は `parseAt` が消費し、ここへ来ない。
+ */
+const scan = <T extends { sheet?: string }>(text: string, parseAt: ParseAt<T>): Span<T>[] => {
+    const spans: Span<T>[] = []
+    const n = text.length
+    let i = 0
+    while (i < n) {
+        const code = text.charCodeAt(i)
+        if (code === CODE_QUOTE) {
+            // 文字列リテラルは不透過
+            i = skipQuoted(text, i, CODE_QUOTE)
+            continue
+        }
+        if (code === CODE_APOSTROPHE) {
+            // クオート付きシート名 — 直後が `!` のときだけ参照が続く
+            const close = skipQuoted(text, i, CODE_APOSTROPHE)
+            i = text.charCodeAt(close) === CODE_BANG ? scanQualified(text, i, close, parseAt, spans) : close
+            continue
+        }
+        if (code === CODE_LBRACKET) {
+            // 構造化参照の角括弧連なりは不透過 — Excel / Sheets は [...] 内を書き換えないため、中身 (Q1 等) を文法へ渡すと列名を壊す
+            i = skipBrackets(text, i)
+            continue
+        }
+        if (!isIdentifierChar(code)) {
+            i += 1
+            continue
+        }
+        const parsed = parseAt(text, i)
+        if (parsed !== null && isDelimited(text, parsed.end)) {
+            spans.push({ start: i, end: parsed.end, token: parsed.token })
+            i = parsed.end
+            continue
+        }
+        // 名前 / 関数名 / 数値リテラル / 非クオートのシート名: 識別子の連なりを読み飛ばす
+        let j = skipIdentifier(text, i)
+        // 3-D シート `Sheet1:Sheet3!` — `:` + 識別子 + `!` の形だけ修飾子へ取り込む
+        if (text.charCodeAt(j) === CODE_COLON) {
+            const k = skipIdentifier(text, j + 1)
+            if (k > j + 1 && text.charCodeAt(k) === CODE_BANG) {
+                j = k
+            }
+        }
+        i = text.charCodeAt(j) === CODE_BANG ? scanQualified(text, i, j, parseAt, spans) : j
+    }
+    return spans
+}
+
+/** A parsed `$?LETTERS` column part (0-based index). / 解析済み `$?英字` 列部 (0 始まり索引)。 */
+type ColumnPart = { end: number; col: number; abs: boolean }
+
+/** Reads `$?LETTERS` at `from` (≤ 11 letters, case-insensitive) or null. / `from` の `$?英字` (≤ 11 字・大小無視) を読むか null。 */
+const readColumnPart = (text: string, from: number): ColumnPart | null => {
+    let i = from
+    const abs = text.charCodeAt(i) === CODE_DOLLAR
+    if (abs) {
+        i += 1
+    }
+    let col = 0
+    let letters = 0
+    while (i < text.length) {
+        const code = text.charCodeAt(i)
+        if (!isLetter(code)) {
+            break
+        }
+        letters += 1
+        if (letters > MAX_COLUMN_LETTERS) {
+            return null
+        }
+        // 下位 5 ビットが A=1 … Z=26 (大小文字共通) — 26 進の桁上げ
+        col = col * 26 + (code & 0x1f)
+        i += 1
+    }
+    return letters === 0 ? null : { end: i, col: col - 1, abs }
+}
+
+/** A digit run's value and the index just past it. / 数字連なりの値と直後の索引。 */
+type Digits = { end: number; value: number }
+
+/** Reads a digit run at `from` (1-15 digits, so the value is a safe integer) or null. / `from` の数字連なり (1〜15 桁 — 値は安全整数) を読むか null。 */
+const readDigits = (text: string, from: number): Digits | null => {
+    let i = from
+    let value = 0
+    while (i < text.length) {
+        const code = text.charCodeAt(i)
+        if (!isDigit(code)) {
+            break
+        }
+        // 16 桁目で拒否 — 安全整数を超える索引は文法水準で遮断する
+        if (i - from >= MAX_INDEX_DIGITS) {
+            return null
+        }
+        value = value * 10 + (code - 48)
+        i += 1
+    }
+    return i === from ? null : { end: i, value }
+}
+
+/** A parsed `$?DIGITS` index part (0-based). / 解析済み `$?数字` 索引部 (0 始まり)。 */
+type IndexPart = { end: number; index: number; abs: boolean }
+
+/** Reads `$?DIGITS` at `from` (value ≥ 1 — `A0` is a name, not a cell) or null. / `from` の `$?数字` (値 ≥ 1 — `A0` はセルでなく名前) を読むか null。 */
+const readIndexPart = (text: string, from: number): IndexPart | null => {
+    const abs = text.charCodeAt(from) === CODE_DOLLAR
+    const digits = readDigits(text, abs ? from + 1 : from)
+    return digits === null || digits.value === 0 ? null : { end: digits.end, index: digits.value - 1, abs }
+}
+
+/**
+ * The A1 positional grammar: cell (`:` cell)? | column `:` column | row `:` row. A cell whose
+ * `:` is not followed by a cell yields the cell alone (`A1:B` → `A1`).
+ * A1 位置文法: セル (`:` セル)? | 列 `:` 列 | 行 `:` 行。`:` の後にセルが続かないセルは
+ * セル単独 (`A1:B` → `A1`)。
+ */
+const parseA1At: ParseAt<ReferenceToken> = (text, from) => {
+    const colA = readColumnPart(text, from)
+    if (colA !== null) {
+        const rowA = readIndexPart(text, colA.end)
+        if (rowA !== null) {
+            // セル — `:` セル が続けばレンジ
+            if (text.charCodeAt(rowA.end) === CODE_COLON) {
+                const colB = readColumnPart(text, rowA.end + 1)
+                if (colB !== null) {
+                    const rowB = readIndexPart(text, colB.end)
+                    if (rowB !== null) {
+                        return {
+                            end: rowB.end,
+                            token: { kind: "range", start: { row: rowA.index, col: colA.col, absRow: rowA.abs, absCol: colA.abs }, end: { row: rowB.index, col: colB.col, absRow: rowB.abs, absCol: colB.abs } },
+                        }
+                    }
+                }
+            }
+            return { end: rowA.end, token: { kind: "cell", row: rowA.index, col: colA.col, absRow: rowA.abs, absCol: colA.abs } }
+        }
+        // 英字のみ — `:` 英字 が続くときだけ全列
+        if (text.charCodeAt(colA.end) === CODE_COLON) {
+            const colB = readColumnPart(text, colA.end + 1)
+            if (colB !== null) {
+                return { end: colB.end, token: { kind: "column", start: { col: colA.col, abs: colA.abs }, end: { col: colB.col, abs: colB.abs } } }
+            }
+        }
+        return null
+    }
+    // 数字始まり — `:` 数字 が続くときだけ全行
+    const rowA = readIndexPart(text, from)
+    if (rowA !== null && text.charCodeAt(rowA.end) === CODE_COLON) {
+        const rowB = readIndexPart(text, rowA.end + 1)
+        if (rowB !== null) {
+            return { end: rowB.end, token: { kind: "row", start: { row: rowA.index, abs: rowA.abs }, end: { row: rowB.index, abs: rowB.abs } } }
+        }
+    }
+    return null
+}
+
+/**
+ * Scans the A1 references of a formula in order (string literals opaque, function names and
+ * names skipped, sheet qualifiers kept verbatim). A pure scanner: it does not police the
+ * leading `=` — the transforms and predicates do.
+ * 数式の A1 参照を出現順に走査 (文字列リテラル不透過、関数名 / 名前は読み飛ばし、シート修飾子は
+ * 原文保持)。純粋なスキャナで先頭 `=` は検査しない — それは変換と述語の責務。
+ */
+export const tokenizeFormula = (formula: string): readonly ReferenceSpan[] => scan(formula, parseA1At)
+
+/**
+ * Bounded per-string memo factory — the "Map<string, T> per caller" of §2.8. Wrap any pure
+ * per-formula computation (`createFormulaMemo(tokenizeFormula)` is the tokenizer cache); a hit
+ * returns the identical value, the map is cleared when `limit` entries are reached.
+ * `compute` must not return `undefined` (that is the miss sentinel). A non-positive or
+ * non-integer limit is a RangeError.
+ * 上限つき文字列メモのファクトリ — §2.8 の「呼び出し側毎の Map<string, T>」。数式単位の純計算を
+ * 包む (`createFormulaMemo(tokenizeFormula)` がトークナイザキャッシュ)。ヒットは同一値を返し、
+ * `limit` 件に達したら全消去。`compute` は `undefined` を返してはならない (ミス番兵)。非正 /
+ * 非整数の上限は RangeError。
+ */
+export const createFormulaMemo = <T>(compute: (formula: string) => T, limit: number = FORMULA_MEMO_LIMIT): ((formula: string) => T) => {
+    if (!Number.isInteger(limit) || limit <= 0) {
+        throw new RangeError(`[spreadsheet] createFormulaMemo requires a positive integer limit, received ${limit}`)
+    }
+    const cache = new Map<string, T>()
+    return (formula) => {
+        const hit = cache.get(formula)
+        if (hit !== undefined) {
+            return hit
+        }
+        // 上限到達で全消去 (語彙は貼り付け単位で有限 — 個別追い出しの帳簿を持たない)
+        if (cache.size >= limit) {
+            cache.clear()
+        }
+        const value = compute(formula)
+        cache.set(formula, value)
+        return value
+    }
+}
+
+/** Column index → letters (0 → A, 25 → Z, 26 → AA, unbounded). / 列索引 → 英字 (0 → A、25 → Z、26 → AA、上限なし)。 */
+const columnName = (col: number): string => {
+    let n = col + 1
+    let name = ""
+    while (n > 0) {
+        const rem = (n - 1) % 26
+        name = String.fromCharCode(65 + rem) + name
+        n = Math.floor((n - 1) / 26)
+    }
+    return name
+}
+
+/** `$?LETTERS$?DIGITS` of one range end. / レンジ片端の `$?英字$?数字`。 */
+const cellText = (cell: ReferenceCell): string => `${cell.absCol ? "$" : ""}${columnName(cell.col)}${cell.absRow ? "$" : ""}${cell.row + 1}`
+
+/** Verbatim sheet qualifier plus `!`, or empty. / 原文シート修飾子 + `!`、無ければ空。 */
+const sheetPrefix = (token: { sheet?: string }): string => (token.sheet === undefined ? "" : `${token.sheet}!`)
+
+/** Serialises a token back to A1 text (uppercase letters, sheet part verbatim). / トークンを A1 文字列へ直列化 (英字は大文字、シート部は原文)。 */
+export const formatReference = (token: ReferenceToken): string => {
+    const prefix = sheetPrefix(token)
+    switch (token.kind) {
+        case "cell":
+            return `${prefix}${cellText(token)}`
+        case "range":
+            return `${prefix}${cellText(token.start)}:${cellText(token.end)}`
+        case "column":
+            return `${prefix}${token.start.abs ? "$" : ""}${columnName(token.start.col)}:${token.end.abs ? "$" : ""}${columnName(token.end.col)}`
+        case "row":
+            return `${prefix}${token.start.abs ? "$" : ""}${token.start.row + 1}:${token.end.abs ? "$" : ""}${token.end.row + 1}`
+    }
+}
+
+/** Fail-fast guard for a grid index handed in by a consumer. / consumer から渡されたグリッド索引の fail-fast ガード。 */
+const assertGridIndex = (value: number, what: string): void => {
+    if (!Number.isInteger(value) || value < 0) {
+        throw new RangeError(`[spreadsheet] ${what} must be a non-negative integer, received ${value}`)
+    }
+}
+
+/**
+ * The relative reference text pointing inserts for a cell / rectangle (`A1`, `A1:B2`), a column
+ * band (`A:A`, `A:C`) or a row band (`1:1`, `2:5`). A 1×1 rectangle under `"cells"` is a cell.
+ * Non-integer / negative coordinates are a RangeError.
+ * ポインティングがセル / 矩形 (`A1`, `A1:B2`)・列帯 (`A:A`, `A:C`)・行帯 (`1:1`, `2:5`) に
+ * 挿入する相対参照文字列。`"cells"` の 1×1 矩形はセル。非整数 / 負の座標は RangeError。
+ */
+export const formatRangeReference = (target: CellCoord | CellRange, axis: ReferenceAxis): string => {
+    const range: CellRange = "startRow" in target ? target : { startRow: target.row, startCol: target.col, endRow: target.row, endCol: target.col }
+    assertGridIndex(range.startRow, "formatRangeReference startRow")
+    assertGridIndex(range.startCol, "formatRangeReference startCol")
+    assertGridIndex(range.endRow, "formatRangeReference endRow")
+    assertGridIndex(range.endCol, "formatRangeReference endCol")
+    switch (axis) {
+        case "columns":
+            return formatReference({ kind: "column", start: { col: range.startCol, abs: false }, end: { col: range.endCol, abs: false } })
+        case "rows":
+            return formatReference({ kind: "row", start: { row: range.startRow, abs: false }, end: { row: range.endRow, abs: false } })
+        case "cells":
+            if (range.startRow === range.endRow && range.startCol === range.endCol) {
+                return formatReference({ kind: "cell", row: range.startRow, col: range.startCol, absRow: false, absCol: false })
+            }
+            return formatReference({
+                kind: "range",
+                start: { row: range.startRow, col: range.startCol, absRow: false, absCol: false },
+                end: { row: range.endRow, col: range.endCol, absRow: false, absCol: false },
+            })
+    }
+}
+
+/**
+ * Rebuilds a formula with every span replaced by `render(span)` (`null` = `#REF!` behind the
+ * verbatim sheet part). No spans ⇒ the SAME string instance (identity for the untouched case).
+ * 各区間を `render(span)` で置換して数式を再構築 (`null` = 原文シート部つきの `#REF!`)。
+ * 区間なしなら**同一**文字列インスタンス (無変更ケースの恒等)。
+ */
+const rewrite = <T extends { sheet?: string }>(formula: string, spans: readonly Span<T>[], render: (token: T) => string | null): string => {
+    if (spans.length === 0) {
+        return formula
+    }
+    let out = ""
+    let last = 0
+    for (const span of spans) {
+        const text = render(span.token)
+        out += formula.slice(last, span.start) + (text === null ? `${sheetPrefix(span.token)}${REF_ERROR}` : text)
+        last = span.end
+    }
+    return out + formula.slice(last)
+}
+
+/** Whether the text is a formula (leading `=`). / 数式 (先頭 `=`) か。 */
+const isFormula = (text: string): boolean => text.charCodeAt(0) === CODE_EQUALS
+
+/** Shifts one range end's relative parts; null when an index leaves the grid. / レンジ片端の相対部をシフト。索引がグリッド外へ出れば null。 */
+const shiftCell = (cell: ReferenceCell, dRow: number, dCol: number): ReferenceCell | null => {
+    const row = cell.absRow ? cell.row : cell.row + dRow
+    const col = cell.absCol ? cell.col : cell.col + dCol
+    return row < 0 || col < 0 ? null : { row, col, absRow: cell.absRow, absCol: cell.absCol }
+}
+
+/** Shifts one token's relative parts; null when any index leaves the grid (⇒ `#REF!`). / トークンの相対部をシフト。索引がグリッド外へ出れば null (⇒ `#REF!`)。 */
+const shiftToken = (token: ReferenceToken, dRow: number, dCol: number): ReferenceToken | null => {
+    switch (token.kind) {
+        case "cell": {
+            const cell = shiftCell(token, dRow, dCol)
+            return cell === null ? null : { ...token, ...cell }
+        }
+        case "range": {
+            const start = shiftCell(token.start, dRow, dCol)
+            const end = shiftCell(token.end, dRow, dCol)
+            return start === null || end === null ? null : { ...token, start, end }
+        }
+        case "column": {
+            const start = token.start.abs ? token.start.col : token.start.col + dCol
+            const end = token.end.abs ? token.end.col : token.end.col + dCol
+            return start < 0 || end < 0 ? null : { ...token, start: { col: start, abs: token.start.abs }, end: { col: end, abs: token.end.abs } }
+        }
+        case "row": {
+            const start = token.start.abs ? token.start.row : token.start.row + dRow
+            const end = token.end.abs ? token.end.row : token.end.row + dRow
+            return start < 0 || end < 0 ? null : { ...token, start: { row: start, abs: token.start.abs }, end: { row: end, abs: token.end.abs } }
+        }
+    }
+}
+
+/**
+ * Shifts the relative parts of every reference by (dRow, dCol) — the paste-offset transform.
+ * Absolute (`$`) parts stay; a reference shifted below row / column 0 becomes `#REF!` (behind
+ * its verbatim sheet part). Non-formula text and reference-free formulas return the same
+ * string instance. Non-integer deltas are a RangeError.
+ * 全参照の相対部を (dRow, dCol) だけシフト — 貼り付けオフセット変換。絶対 (`$`) 部は不変、
+ * 行 / 列 0 未満へ出た参照は (原文シート部つきの) `#REF!`。非数式・参照なし数式は同一文字列
+ * インスタンス。非整数の差分は RangeError。
+ */
+export const shiftFormula = (formula: string, dRow: number, dCol: number): string => {
+    if (!(Number.isInteger(dRow) && Number.isInteger(dCol))) {
+        throw new RangeError(`[spreadsheet] shiftFormula requires integer deltas, received ${dRow}, ${dCol}`)
+    }
+    if (!isFormula(formula)) {
+        return formula
+    }
+    return rewrite(formula, tokenizeFormula(formula), (token) => {
+        const shifted = shiftToken(token, dRow, dCol)
+        return shifted === null ? null : formatReference(shifted)
+    })
+}
+
+/** Fail-fast guard for an origin coordinate. / 原点座標の fail-fast ガード。 */
+const assertOrigin = (origin: CellCoord, what: string): void => {
+    assertGridIndex(origin.row, `${what} origin.row`)
+    assertGridIndex(origin.col, `${what} origin.col`)
+}
+
+/** One R1C1 axis text: absolute `R3` (1-based) or relative `R[-1]` (zero spelled `[0]`). / R1C1 の軸文字列: 絶対 `R3` (1 始まり) か相対 `R[-1]` (0 も `[0]`)。 */
+const r1c1Axis = (letter: string, index: number, abs: boolean, originIndex: number): string => (abs ? `${letter}${index + 1}` : `${letter}[${index - originIndex}]`)
+
+/** One R1C1 range end (row then column). / R1C1 レンジ片端 (行、列の順)。 */
+const r1c1Cell = (cell: ReferenceCell, origin: CellCoord): string => `${r1c1Axis("R", cell.row, cell.absRow, origin.row)}${r1c1Axis("C", cell.col, cell.absCol, origin.col)}`
+
+/** Serialises an A1 token in R1C1 relative to `origin`. / A1 トークンを `origin` 基準の R1C1 へ直列化。 */
+const formatR1C1 = (token: ReferenceToken, origin: CellCoord): string => {
+    const prefix = sheetPrefix(token)
+    switch (token.kind) {
+        case "cell":
+            return `${prefix}${r1c1Cell(token, origin)}`
+        case "range":
+            return `${prefix}${r1c1Cell(token.start, origin)}:${r1c1Cell(token.end, origin)}`
+        case "column":
+            return `${prefix}${r1c1Axis("C", token.start.col, token.start.abs, origin.col)}:${r1c1Axis("C", token.end.col, token.end.abs, origin.col)}`
+        case "row":
+            return `${prefix}${r1c1Axis("R", token.start.row, token.start.abs, origin.row)}:${r1c1Axis("R", token.end.row, token.end.abs, origin.row)}`
+    }
+}
+
+/**
+ * Converts a formula to R1C1 relative to `origin` (Google Sheets spelling) — the form the clip
+ * payload carries so a paste at any target resolves with {@link fromR1C1}. Non-formula text
+ * and reference-free formulas return the same string instance; an invalid origin is a
+ * RangeError.
+ * 数式を `origin` 基準の R1C1 (Google Sheets 綴り) へ変換 — クリップが運び、任意の貼り付け先で
+ * {@link fromR1C1} が解決する形。非数式・参照なし数式は同一文字列インスタンス、不正な原点は
+ * RangeError。
+ */
+export const toR1C1 = (formula: string, origin: CellCoord): string => {
+    assertOrigin(origin, "toR1C1")
+    if (!isFormula(formula)) {
+        return formula
+    }
+    return rewrite(formula, tokenizeFormula(formula), (token) => formatR1C1(token, origin))
+}
+
+/** One R1C1 axis: relative offset (`[n]`) or absolute 1-based index. / R1C1 の 1 軸: 相対差分 (`[n]`) か絶対 1 始まり索引。 */
+type R1C1Axis = { rel: boolean; n: number }
+
+/** Both axes of one R1C1 cell end (`R…C…`). / R1C1 セル片端 (`R…C…`) の両軸。 */
+type R1C1Cell = { row: R1C1Axis; col: R1C1Axis }
+
+/**
+ * One parsed R1C1 end with the index just past it: `R…C…` (cell), `R…` alone (row) or `C…`
+ * alone (column).
+ * 解析済み R1C1 片端と直後の索引: `R…C…` (セル)、`R…` 単独 (行)、`C…` 単独 (列)。
+ */
+type R1C1End = { end: number } & ({ shape: "cell"; cell: R1C1Cell } | { shape: "row"; row: R1C1Axis } | { shape: "column"; col: R1C1Axis })
+
+/**
+ * A parsed R1C1 reference: a start end and, for a range, a second end of the same shape
+ * (`null` = single). / 解析済み R1C1 参照: 始端と、レンジなら同形の終端 (`null` = 単独)。
+ */
+type R1C1Token = { shape: "cell"; start: R1C1Cell; end: R1C1Cell | null; sheet?: string } | { shape: "row"; start: R1C1Axis; end: R1C1Axis | null; sheet?: string } | { shape: "column"; start: R1C1Axis; end: R1C1Axis | null; sheet?: string }
+
+/**
+ * Reads one axis part `R` / `C` at `from`: `[n]` / `[-n]` relative (≤ 15 digits), digits
+ * absolute (≥ 1), or bare (relative 0). Case-insensitive letter; null on mismatch / malformed
+ * (`R0`, `R[+1]`, `R[]`, `R[1`).
+ * `from` の軸部 `R` / `C` を読む: `[n]` / `[-n]` 相対 (≤ 15 桁)、数字は絶対 (≥ 1)、素の字は
+ * 相対 0。字は大小無視、不一致 / 不正形 (`R0` / `R[+1]` / `R[]` / `R[1`) は null。
+ */
+const readR1C1Axis = (text: string, from: number, letter: number): { end: number; axis: R1C1Axis } | null => {
+    const code = text.charCodeAt(from)
+    if (code !== letter && code !== letter + 32) {
+        return null
+    }
+    const i = from + 1
+    if (text.charCodeAt(i) === CODE_LBRACKET) {
+        // 相対 `[±n]` — 符号は `-` のみ、閉じ `]` 必須
+        const negative = text.charCodeAt(i + 1) === CODE_MINUS
+        const digits = readDigits(text, negative ? i + 2 : i + 1)
+        if (digits === null || text.charCodeAt(digits.end) !== CODE_RBRACKET) {
+            return null
+        }
+        return { end: digits.end + 1, axis: { rel: true, n: negative ? -digits.value : digits.value } }
+    }
+    const digits = readDigits(text, i)
+    if (digits === null) {
+        // 数字なし = 素の字 (相対 0)
+        return { end: i, axis: { rel: true, n: 0 } }
+    }
+    // 絶対 `n` は 1 始まり — `R0` は不正形
+    return digits.value === 0 ? null : { end: digits.end, axis: { rel: false, n: digits.value } }
+}
+
+/** Reads one R1C1 end (`R…C…`, `R…` or `C…`) at `from` or null. / `from` の R1C1 片端 (`R…C…` / `R…` / `C…`) を読むか null。 */
+const readR1C1End = (text: string, from: number): R1C1End | null => {
+    const row = readR1C1Axis(text, from, CODE_UPPER_R)
+    const col = readR1C1Axis(text, row === null ? from : row.end, CODE_UPPER_C)
+    if (row !== null && col !== null) {
+        return { end: col.end, shape: "cell", cell: { row: row.axis, col: col.axis } }
+    }
+    if (row !== null) {
+        return { end: row.end, shape: "row", row: row.axis }
+    }
+    return col === null ? null : { end: col.end, shape: "column", col: col.axis }
+}
+
+/** The single-end token of one parsed end. / 解析済み片端 1 つの単独トークン。 */
+const singleR1C1 = (first: R1C1End): R1C1Token => {
+    switch (first.shape) {
+        case "cell":
+            return { shape: "cell", start: first.cell, end: null }
+        case "row":
+            return { shape: "row", start: first.row, end: null }
+        case "column":
+            return { shape: "column", start: first.col, end: null }
+    }
+}
+
+/** The range token of two ends of the same shape; null when the shapes differ (`R1C1:R1`). / 同形の両端によるレンジトークン。形が異なれば null (`R1C1:R1`)。 */
+const rangeR1C1 = (first: R1C1End, second: R1C1End): R1C1Token | null => {
+    if (first.shape === "cell" && second.shape === "cell") {
+        return { shape: "cell", start: first.cell, end: second.cell }
+    }
+    if (first.shape === "row" && second.shape === "row") {
+        return { shape: "row", start: first.row, end: second.row }
+    }
+    if (first.shape === "column" && second.shape === "column") {
+        return { shape: "column", start: first.col, end: second.col }
+    }
+    return null
+}
+
+/** The R1C1 positional grammar: end (`:` end of the same shape)?. / R1C1 位置文法: 片端 (`:` 同形の片端)?。 */
+const parseR1C1At: ParseAt<R1C1Token> = (text, from) => {
+    const first = readR1C1End(text, from)
+    if (first === null) {
+        return null
+    }
+    if (text.charCodeAt(first.end) === CODE_COLON) {
+        const second = readR1C1End(text, first.end + 1)
+        if (second !== null) {
+            const range = rangeR1C1(first, second)
+            if (range !== null) {
+                return { end: second.end, token: range }
+            }
+        }
+    }
+    return { end: first.end, token: singleR1C1(first) }
+}
+
+/** R1C1 tokenizations performed so far — the paste memo's misses (see `r1c1TokenizeCount`). / これまでの R1C1 トークナイズ回数 — 貼り付けメモのミス数 (`r1c1TokenizeCount` 参照)。 */
+let r1c1Tokenizations = 0
+
+/** Scans the R1C1 references of a string (same skipping rules as the A1 scanner) and counts the scan. / 文字列の R1C1 参照を走査し (読み飛ばし規則は A1 スキャナと同一)、走査を数える。 */
+const tokenizeR1C1 = (r1c1: string): readonly Span<R1C1Token>[] => {
+    r1c1Tokenizations += 1
+    return scan(r1c1, parseR1C1At)
+}
+
+/** Paste-path memo: one R1C1 parse per distinct string (§2.8 "R1C1 文字列毎に memo"). / 貼り付け経路のメモ: 相異なる文字列毎に 1 回の R1C1 解析 (§2.8)。 */
+const memoizedR1C1 = createFormulaMemo(tokenizeR1C1)
+
+/**
+ * Diagnostic seam (barrel-private): the number of R1C1 tokenizations {@link fromR1C1} has run
+ * since module load — a memo hit adds nothing, so a 20,000-formula paste over 100 distinct
+ * strings raises it by exactly 100. The paste budget spec pins the memo wiring on this count
+ * (structural gate) instead of on a wall clock.
+ * 診断シーム (バレル非公開): モジュール読込以降に {@link fromR1C1} が走らせた R1C1 トークナイズ
+ * 回数 — メモのヒットは増やさないので、異なり 100 本の数式 20,000 個の貼り付けはちょうど 100
+ * 増える。貼り付け予算 spec はメモの結線を壁時計でなくこの回数で封印する (構造ゲート)。
+ */
+export const r1c1TokenizeCount = (): number => r1c1Tokenizations
+
+/** Resolves one R1C1 axis to a 0-based grid index (may be negative ⇒ `#REF!`). / R1C1 の 1 軸を 0 始まりのグリッド索引へ解決 (負なら `#REF!`)。 */
+const resolveAxis = (axis: R1C1Axis, originIndex: number): number => (axis.rel ? originIndex + axis.n : axis.n - 1)
+
+/** Resolves one R1C1 cell end to a range end; null when off-grid. / R1C1 セル片端をレンジ片端へ解決。グリッド外なら null。 */
+const resolveCell = (cell: R1C1Cell, origin: CellCoord): ReferenceCell | null => {
+    const row = resolveAxis(cell.row, origin.row)
+    const col = resolveAxis(cell.col, origin.col)
+    return row < 0 || col < 0 ? null : { row, col, absRow: !cell.row.rel, absCol: !cell.col.rel }
+}
+
+/**
+ * Resolves a parsed R1C1 token to an A1 token at `origin`; null when any index is off-grid. A
+ * single-end whole axis (`R[1]`) resolves to both ends of the A1 form (`2:2`).
+ * 解析済み R1C1 トークンを `origin` で A1 トークンへ解決。索引がグリッド外なら null。単独片端の
+ * 全軸 (`R[1]`) は A1 形の両端 (`2:2`) へ解決。
+ */
+const resolveR1C1 = (token: R1C1Token, origin: CellCoord): ReferenceToken | null => {
+    const sheet = token.sheet === undefined ? {} : { sheet: token.sheet }
+    switch (token.shape) {
+        case "cell": {
+            const start = resolveCell(token.start, origin)
+            if (start === null) {
+                return null
+            }
+            if (token.end === null) {
+                return { kind: "cell", ...start, ...sheet }
+            }
+            const end = resolveCell(token.end, origin)
+            return end === null ? null : { kind: "range", start, end, ...sheet }
+        }
+        case "row": {
+            const endAxis = token.end === null ? token.start : token.end
+            const start = resolveAxis(token.start, origin.row)
+            const end = resolveAxis(endAxis, origin.row)
+            return start < 0 || end < 0 ? null : { kind: "row", start: { row: start, abs: !token.start.rel }, end: { row: end, abs: !endAxis.rel }, ...sheet }
+        }
+        case "column": {
+            const endAxis = token.end === null ? token.start : token.end
+            const start = resolveAxis(token.start, origin.col)
+            const end = resolveAxis(endAxis, origin.col)
+            return start < 0 || end < 0 ? null : { kind: "column", start: { col: start, abs: !token.start.rel }, end: { col: end, abs: !endAxis.rel }, ...sheet }
+        }
+    }
+}
+
+/**
+ * Resolves an R1C1 formula to A1 at `origin` — the paste side of {@link toR1C1}. A relative
+ * offset landing below row / column 0 becomes `#REF!` (behind its verbatim sheet part); text
+ * the R1C1 grammar rejects (`R0C1`, `R[+1]`, `R[1`) stays verbatim. Parsed forms are memoised
+ * per distinct string, so a 100k-cell paste of ≤ 100 distinct formulas parses ≤ 100 times.
+ * Non-formula text returns the same string instance; an invalid origin is a RangeError.
+ * R1C1 数式を `origin` で A1 へ解決 — {@link toR1C1} の貼り付け側。行 / 列 0 未満へ落ちる相対
+ * 差分は (原文シート部つきの) `#REF!`、R1C1 文法が拒む文字列 (`R0C1` / `R[+1]` / `R[1`) は
+ * 原文のまま。解析形は相異なる文字列毎にメモされ、≤ 100 種の数式の 10 万セル貼り付けは解析
+ * ≤ 100 回。非数式は同一文字列インスタンス、不正な原点は RangeError。
+ */
+export const fromR1C1 = (r1c1: string, origin: CellCoord): string => {
+    assertOrigin(origin, "fromR1C1")
+    if (!isFormula(r1c1)) {
+        return r1c1
+    }
+    return rewrite(r1c1, memoizedR1C1(r1c1), (token) => {
+        const resolved = resolveR1C1(token, origin)
+        return resolved === null ? null : formatReference(resolved)
+    })
+}
+
+/**
+ * Next anchor state in Excel's F4 order: A1 → $A$1 → A$1 → $A1 → A1, keyed on (absCol, absRow).
+ * Excel の F4 順の次アンカー状態: A1 → $A$1 → A$1 → $A1 → A1 ((absCol, absRow) で決定)。
+ */
+const nextAnchor = (absCol: boolean, absRow: boolean): { absCol: boolean; absRow: boolean } => {
+    if (!(absCol || absRow)) {
+        return { absCol: true, absRow: true }
+    }
+    if (absCol && absRow) {
+        return { absCol: false, absRow: true }
+    }
+    if (!absCol && absRow) {
+        return { absCol: true, absRow: false }
+    }
+    return { absCol: false, absRow: false }
+}
+
+/**
+ * F4 cycle on one token: cells follow A1 → $A$1 → A$1 → $A1; a range moves BOTH ends to the
+ * state after its start end (mixed ends converge); whole columns / rows toggle `$` on both ends
+ * from the start end. The sheet part is preserved.
+ * 1 トークンの F4 循環: セルは A1 → $A$1 → A$1 → $A1、レンジは始端の次状態を**両端**に適用
+ * (不揃いの両端は収束)、全列 / 全行は始端基準で両端の `$` をトグル。シート部は保持。
+ */
+export const cycleAnchor = (token: ReferenceToken): ReferenceToken => {
+    switch (token.kind) {
+        case "cell":
+            return { ...token, ...nextAnchor(token.absCol, token.absRow) }
+        case "range": {
+            const next = nextAnchor(token.start.absCol, token.start.absRow)
+            return { ...token, start: { ...token.start, ...next }, end: { ...token.end, ...next } }
+        }
+        case "column": {
+            const abs = !token.start.abs
+            return { ...token, start: { col: token.start.col, abs }, end: { col: token.end.col, abs } }
+        }
+        case "row": {
+            const abs = !token.start.abs
+            return { ...token, start: { row: token.start.row, abs }, end: { row: token.end.row, abs } }
+        }
+    }
+}
+
+/** Whether `caret` is a valid caret position inside a formula body (past the `=`). / `caret` が数式本体 (`=` より後) の妥当なキャレット位置か。 */
+const isFormulaCaret = (value: string, caret: number): boolean => isFormula(value) && Number.isInteger(caret) && caret >= 1 && caret <= value.length
+
+/**
+ * The reference whose span contains the caret (`start ≤ caret ≤ end`, both edges inclusive so
+ * F4 works right after typing a reference) — the F4 target. Null outside a formula, for a
+ * caret outside `[1, length]` (a DOM-sourced value — fail-soft, not a throw), or when no
+ * reference is under the caret.
+ * キャレットを区間に含む参照 (`start ≤ caret ≤ end`、参照直後でも F4 が効くよう両端含む) —
+ * F4 の対象。数式外・`[1, length]` 外のキャレット (DOM 由来の値 — throw でなく fail-soft)・
+ * 参照下でない場合は null。
+ */
+export const findReferenceAt = (value: string, caret: number): ReferenceSpan | null => {
+    if (!isFormulaCaret(value, caret)) {
+        return null
+    }
+    for (const span of tokenizeFormula(value)) {
+        if (span.start <= caret && caret <= span.end) {
+            return span
+        }
+    }
+    return null
+}
+
+/**
+ * The composed F4 operation: cycles the reference under the caret and returns the new text
+ * with the caret placed right after the rewritten reference; null when there is nothing to
+ * cycle (the keystroke falls through).
+ * 合成された F4 操作: キャレット下の参照を循環させ、書き換えた参照の直後にキャレットを置いた
+ * 新テキストを返す。循環対象が無ければ null (キーは素通し)。
+ */
+export const cycleAnchorAt = (text: string, caret: number): { text: string; caret: number } | null => {
+    const span = findReferenceAt(text, caret)
+    if (span === null) {
+        return null
+    }
+    const replaced = formatReference(cycleAnchor(span.token))
+    return { text: `${text.slice(0, span.start)}${replaced}${text.slice(span.end)}`, caret: span.start + replaced.length }
+}
+
+/**
+ * Whether the prefix `value[0, end)` — with string literals opaque — ends in a pointing trigger
+ * followed by optional whitespace (`/[=(,;+\-*\/^&<>:]\s*$/`). A prefix ending inside a
+ * string literal never triggers.
+ * 接頭辞 `value[0, end)` (文字列リテラルは不透過) がポインティング契機 + 任意の空白で終わるか
+ * (`/[=(,;+\-*\/^&<>:]\s*$/`)。文字列リテラルの内側で終わる接頭辞は決して契機にならない。
+ */
+const endsWithTrigger = (value: string, end: number): boolean => {
+    let lastSignificant = -1
+    let i = 0
+    while (i < end) {
+        const code = value.charCodeAt(i)
+        if (code === CODE_QUOTE) {
+            // リテラルは 1 個の不透過な有意文字として扱う (閉じ位置が接頭辞外なら内側で終了)
+            const close = skipQuoted(value, i, CODE_QUOTE)
+            if (close > end) {
+                return false
+            }
+            lastSignificant = CODE_QUOTE
+            i = close
+            continue
+        }
+        if (!isSpace(code)) {
+            lastSignificant = code
+        }
+        i += 1
+    }
+    return isTrigger(lastSignificant)
+}
+
+/**
+ * The pointing predicate (§2.7 / design v5): for a formula value and caret, where a pointed
+ * reference goes. `{ replace: [start, end] }` when the caret sits on a reference that follows
+ * a trigger (`=A1|` → replace `A1`), `{ insertAt: caret }` when the prefix ends in a trigger
+ * plus optional whitespace (`=SUM(|`), otherwise null — a printable character or a string
+ * literal therefore closes pointing by construction. Pure and stateless: evaluate it at every
+ * decision point instead of caching a flag. A caret outside `[1, length]` is null (fail-soft).
+ * ポインティング述語 (§2.7 / 設計 v5): 数式値とキャレットから、指した参照の行き先。契機に続く
+ * 参照上にキャレットがあれば `{ replace: [start, end] }` (`=A1|` → `A1` を置換)、接頭辞が
+ * 契機 + 任意の空白で終われば `{ insertAt: caret }` (`=SUM(|`)、それ以外は null — 印字文字や
+ * 文字列リテラルは構造的にポインティングを閉じる。純粋・無状態: フラグを持たず判断点毎に評価。
+ * `[1, length]` 外のキャレットは null (fail-soft)。
+ */
+export const isPointingPrefix = (value: string, caret: number): PointingTarget | null => {
+    if (!isFormulaCaret(value, caret)) {
+        return null
+    }
+    for (const span of tokenizeFormula(value)) {
+        if (span.start <= caret && caret <= span.end) {
+            // 契機に続くトークンだけが置換対象 (`=SUM(A1 B1|` の B1 は空白交差 — 対象外)
+            return endsWithTrigger(value, span.start) ? { replace: [span.start, span.end] } : null
+        }
+    }
+    return endsWithTrigger(value, caret) ? { insertAt: caret } : null
+}