Support $-locked references: relative, mixed and absolute

The engine already anticipated $A1/A$1/$A$1 in its grammar comment, but the
lexer had no rule for '$' at all -- any formula using it failed to parse.

- lexer.ts: '$' is now a valid word character, so "$A$1" tokenizes as one
  IDENT, same as any other bare word (the lexer still doesn't interpret it,
  per its "dumb lexer" design -- the parser/evaluator stay untouched, since
  evaluation is purely positional and $ has no effect on a value).
- refs.ts: parseA1()/toA1() now carry colAbs/rowAbs through the $ markers
  (backward compatible -- existing {col,row} destructuring is unaffected).
  Added cycleReferenceLock() for Excel/Numbers-style F4: relative ->
  absolute -> row-locked -> col-locked -> relative, toggling whichever
  reference sits at the caret (and the correct side of an A1:B2 range).
- document.ts: shiftFormula() now honors the lock on copy (a locked axis
  stays exactly as typed) but not on cut (a moved cell's reference follows
  it regardless of $, since cut relocates the cell itself rather than
  filling a relative offset).
- TableGrid.vue's inline cell editor and FormulaBar.vue both wire up F4 via
  the shared cycleReferenceLock() helper.
- Tests: lexer/parser coverage for $ tokenizing/parsing, a new refs.spec.ts
  for parseA1/toA1 round-tripping and the F4 cycle (incl. range side-
  picking), and document.spec.ts cases for locked-axis copy vs. cut.
- README.md / src/engine/README.md: documented the $ semantics, F4, and
  corrected a couple of now-stale claims (test count, "$ is ignored, there's
  no copy/fill", "active cell is always the last-clicked one").

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

src/engine/refs.ts

@@ -6,7 +6,9 @@
  * (A=0, B=1, ..., Z=25, AA=26, ...).
  */
 
-const CELL_RE = /^\$?([A-Za-z]{1,3})\$?([0-9]{1,7})$/;
+import { tokenize, type Token } from './lexer';
+
+const CELL_RE = /^(\$?)([A-Za-z]{1,3})(\$?)([0-9]{1,7})$/;
 
 /** "A" -> 0, "B" -> 1, "Z" -> 25, "AA" -> 26 ... */
 export function colToNumber(letters: string): number {
@@ -35,16 +37,62 @@ export function looksLikeCell(text: string): boolean {
   return CELL_RE.test(text);
 }
 
-/** Parse "A1" -> { col: 0, row: 0 }. Throws for malformed input. */
-export function parseA1(text: string): { col: number; row: number } {
+/**
+ * Parse "A1" / "$A1" / "A$1" / "$A$1" -> 0-based coords plus which axes are
+ * `$`-locked (absolute). A locked axis is exempt from the reference shift a
+ * copy/fill applies (see `shiftFormula` in the store); an unlocked one is
+ * "relative" and always shifts with it. Throws for malformed input.
+ */
+export function parseA1(
+  text: string,
+): { col: number; row: number; colAbs: boolean; rowAbs: boolean } {
   const m = CELL_RE.exec(text);
   if (!m) throw new Error(`Bad cell reference: ${text}`);
-  return { col: colToNumber(m[1]), row: Number(m[2]) - 1 };
+  return { col: colToNumber(m[2]), row: Number(m[4]) - 1, colAbs: m[1] === '$', rowAbs: m[3] === '$' };
 }
 
-/** Build "A1" from 0-based coordinates. */
-export function toA1(col: number, row: number): string {
-  return `${numberToCol(col)}${row + 1}`;
+/** Build "A1" from 0-based coordinates; `colAbs`/`rowAbs` add the `$` lock markers. */
+export function toA1(col: number, row: number, colAbs = false, rowAbs = false): string {
+  return `${colAbs ? '$' : ''}${numberToCol(col)}${rowAbs ? '$' : ''}${row + 1}`;
+}
+
+/**
+ * Excel/Numbers-style F4: cycle the cell reference at/adjacent to `caret` (a
+ * 0-based offset into `formula`, which must start with "=") through
+ * relative -> absolute -> row-locked -> column-locked -> relative. Returns
+ * the rewritten formula and a caret placed after the toggled reference, or
+ * `null` when there's no reference at the caret to toggle.
+ */
+export function cycleReferenceLock(
+  formula: string,
+  caret: number,
+): { text: string; caret: number } | null {
+  if (!formula.startsWith('=')) return null;
+  const body = formula.slice(1);
+  const at = caret - 1;
+  let toks: Token[];
+  try {
+    toks = tokenize(body);
+  } catch {
+    return null;
+  }
+  const tok = toks.find(
+    (t) => t.type === 'IDENT' && looksLikeCell(t.value) && at >= t.pos && at <= t.pos + t.value.length,
+  );
+  if (!tok) return null;
+  const { col, row, colAbs, rowAbs } = parseA1(tok.value);
+  const [nColAbs, nRowAbs] = nextLock(colAbs, rowAbs);
+  const next = toA1(col, row, nColAbs, nRowAbs);
+  const text = '=' + body.slice(0, tok.pos) + next + body.slice(tok.pos + tok.value.length);
+  return { text, caret: 1 + tok.pos + next.length };
+}
+
+/** A1 -> $A$1 -> A$1 -> $A1 -> A1 -> ... (the classic F4 cycle). */
+function nextLock(colAbs: boolean, rowAbs: boolean): [boolean, boolean] {
+  if (!colAbs && !rowAbs) return [true, true];
+  if (colAbs && rowAbs) return [false, true];
+  if (!colAbs && rowAbs) return [true, false];
+  return [false, false]; // colAbs && !rowAbs
 }
 
 /**