refactor!: rename slot → cell throughout the codebase

Eliminates the collision between grigson's "beat slot" concept and the
Web Components slot="" attribute. "Cell" also reinforces the CSS Grid
metaphor in the HTML renderer.

Breaking changes:
- Types: ChordSlot→ChordCell, DotSlot→DotCell, BeatSlot→BeatCell,
  AnnotatedChordSlot→AnnotatedChordCell, AnalysedBeatSlot→AnalysedBeatCell,
  SlotLayout→CellLayout
- Properties: Bar.slots→Bar.cells, TonalityHintItem.beforeSlotIndex→beforeCellIndex,
  BarLayout.cells, CellLayout.sourceCellIdx, ZoneSpec.cellIndices
- CSS part names: part="slot"→part="cell", part="slot bar-start"→part="cell bar-start"
- Grammar rules: BeatSlotList→BeatCellList, BeatSlotItem→BeatCellItem, BeatSlot→BeatCell
- Tree-sitter: beat_slot→beat_cell
- Diagnostic messages: "slot(s)"→"cell(s)"

Author: nelstrom

packages/grigson-grille-harmonique-renderer/src/patterns.ts

@@ -9,8 +9,8 @@ export function detectPattern(bar: Bar, activeTSig: TimeSignature): BarPattern {
     );
   }
 
-  const chordCount = bar.slots.filter((s) => s.type === 'chord').length;
-  const hasDots = bar.slots.some((s) => s.type === 'dot');
+  const chordCount = bar.cells.filter((s) => s.type === 'chord').length;
+  const hasDots = bar.cells.some((s) => s.type === 'dot');
   const isEvenDivision = 4 % chordCount === 0;
   const rawBeatsPerChord = isEvenDivision ? 4 / chordCount : 1;
 
@@ -19,9 +19,9 @@ export function detectPattern(bar: Bar, activeTSig: TimeSignature): BarPattern {
     (!hasDots ||
       (() => {
         for (let i = 0; i < 4; i++) {
-          const slot = bar.slots[i];
+          const cell = bar.cells[i];
           const expectChord = i % rawBeatsPerChord === 0;
-          const isChord = slot !== undefined && slot.type === 'chord';
+          const isChord = cell !== undefined && cell.type === 'chord';
           if (expectChord !== isChord) return false;
         }
         return true;
@@ -37,8 +37,8 @@ export function detectPattern(bar: Bar, activeTSig: TimeSignature): BarPattern {
   // Normalize to 4 positions: 'C' for chord, '.' for dot/implicit
   const positions: string[] = [];
   for (let i = 0; i < 4; i++) {
-    const slot = bar.slots[i];
-    positions.push(slot !== undefined && slot.type === 'chord' ? 'C' : '.');
+    const cell = bar.cells[i];
+    positions.push(cell !== undefined && cell.type === 'chord' ? 'C' : '.');
   }
   const pattern = positions.join('');
 
@@ -58,6 +58,6 @@ export function detectPattern(bar: Bar, activeTSig: TimeSignature): BarPattern {
     case 'CCCC':
       return '1+1+1+1';
     default:
-      throw new Error(`Unsupported bar slot pattern: ${pattern}`);
+      throw new Error(`Unsupported bar cell pattern: ${pattern}`);
   }
 }

packages/grigson-grille-harmonique-renderer/src/render.test.ts

@@ -10,13 +10,13 @@ import render from './render.js';
 const SIG_44: TimeSignature = { numerator: 4, denominator: 4 };
 const SIG_34: TimeSignature = { numerator: 3, denominator: 4 };
 
-function chord(root: string): Bar['slots'][number] {
+function chord(root: string): Bar['cells'][number] {
   return { type: 'chord', chord: { type: 'chord', root, quality: 'major' } };
 }
-const dot = (): Bar['slots'][number] => ({ type: 'dot' });
+const dot = (): Bar['cells'][number] => ({ type: 'dot' });
 
-function bar(...slots: Bar['slots']): Bar {
-  return { type: 'bar', slots, closeBarline: { kind: 'single' } };
+function bar(...cells: Bar['cells']): Bar {
+  return { type: 'bar', cells, closeBarline: { kind: 'single' } };
 }
 
 function simpleSong(bars: Bar[]): Song {
@@ -86,8 +86,8 @@ describe('detectPattern', () => {
     expect(() => detectPattern(bar(chord('C')), SIG_34)).toThrow('4/4');
   });
 
-  it('throws for unsupported slot pattern', () => {
-    // .C.. — dot-first slot pattern has no valid mapping
+  it('throws for unsupported cell pattern', () => {
+    // .C.. — dot-first cell pattern has no valid mapping
     expect(() => detectPattern(bar(dot(), chord('G'), dot(), dot()), SIG_44)).toThrow();
   });
 });

packages/grigson-grille-harmonique-renderer/src/render.ts

@@ -1,4 +1,4 @@
-import type { Song, Bar, Chord, TimeSignature, Section, Row, ChordSlot } from 'grigson';
+import type { Song, Bar, Chord, TimeSignature, Section, Row, ChordCell } from 'grigson';
 import {
   reflowSong,
   resolvePreset,
@@ -79,11 +79,11 @@ function ariaLabel(chord: Chord, beats: number, isWhole: boolean): string {
 // Simile detection
 // ---------------------------------------------------------------------------
 
-function slotsEqual(a: Bar, b: Bar): boolean {
-  if (a.slots.length !== b.slots.length) return false;
-  for (let i = 0; i < a.slots.length; i++) {
-    const sa = a.slots[i];
-    const sb = b.slots[i];
+function cellsEqual(a: Bar, b: Bar): boolean {
+  if (a.cells.length !== b.cells.length) return false;
+  for (let i = 0; i < a.cells.length; i++) {
+    const sa = a.cells[i];
+    const sb = b.cells[i];
     if (sa.type !== sb.type) return false;
     if (sa.type === 'chord' && sb.type === 'chord') {
       if (sa.chord.root !== sb.chord.root) return false;
@@ -112,9 +112,9 @@ function rowsOfSection(section: Section): Row[] {
 interface ZoneSpec {
   lineParts: string[];
   chordParts: string[];
-  // Maps each chordParts entry to a chord slot index. Defaults to [0,1,2,...].
-  // Allows a slot to be rendered in multiple positions (e.g. 1+2+1 duplicates the middle chord into N and S).
-  slotIndices?: number[];
+  // Maps each chordParts entry to a chord cell index. Defaults to [0,1,2,...].
+  // Allows a cell to be rendered in multiple positions (e.g. 1+2+1 duplicates the middle chord into N and S).
+  cellIndices?: number[];
 }
 
 const PATTERN_ZONES: Record<BarPattern, ZoneSpec> = {
@@ -144,7 +144,7 @@ const PATTERN_ZONES: Record<BarPattern, ZoneSpec> = {
     // Beat order: W | N+S | E. Rendered as four quadrants with the spanning chord duplicated into N and S.
     lineParts: ['line line-diag', 'line line-anti'],
     chordParts: ['chord chord-left', 'chord chord-top', 'chord chord-bottom', 'chord chord-right'],
-    slotIndices: [0, 1, 1, 2],
+    cellIndices: [0, 1, 1, 2],
   },
   '1+1+2': {
     // Beat order: W (left) | N (top) | S+E (br). "/" splits W+N from S+E; "\" half splits W from N.
@@ -180,7 +180,7 @@ function renderBar(
   mode: 'unicode' | 'ascii',
   prevBar: Bar | null,
 ): string {
-  const isSimile = prevBar !== null && slotsEqual(bar, prevBar);
+  const isSimile = prevBar !== null && cellsEqual(bar, prevBar);
 
   if (isSimile) {
     return `<div part="bar bar-simile"><span part="chord chord-simile" aria-label="repeat bar">%</span></div>`;
@@ -189,20 +189,20 @@ function renderBar(
   const pattern = detectPattern(bar, activeTSig);
   const spec = PATTERN_ZONES[pattern];
   const beats = PATTERN_BEATS[pattern];
-  const chordSlots = bar.slots.filter((s): s is ChordSlot => s.type === 'chord');
+  const chordCells = bar.cells.filter((s): s is ChordCell => s.type === 'chord');
 
   const zones = spec.lineParts.map((p) => `<div part="${p}"></div>`).join('');
 
   const chords = spec.chordParts
     .map((chordPart, i) => {
-      const slotIdx = spec.slotIndices ? spec.slotIndices[i] : i;
-      const slot = chordSlots[slotIdx ?? i];
-      if (!slot) return '';
-      const slotBeats = beats[i] ?? 1;
-      const isWhole = slotBeats === 4;
-      const label = ariaLabel(slot.chord, slotBeats, isWhole);
-      const html = renderChordHtml(slot.chord, preset, mode);
-      const hasBass = slot.chord.bass != null;
+      const cellIdx = spec.cellIndices ? spec.cellIndices[i] : i;
+      const cell = chordCells[cellIdx ?? i];
+      if (!cell) return '';
+      const cellBeats = beats[i] ?? 1;
+      const isWhole = cellBeats === 4;
+      const label = ariaLabel(cell.chord, cellBeats, isWhole);
+      const html = renderChordHtml(cell.chord, preset, mode);
+      const hasBass = cell.chord.bass != null;
       const partStr = hasBass ? `${chordPart} chord-slash` : chordPart;
       return `<span part="${partStr}" aria-label="${label}">${html}</span>`;
     })

packages/grigson/documentation/README.md

@@ -14,7 +14,7 @@ Grigson source files use the `.chart` extension.
 - **Plain text that resembles output.** The pipe character `|` represents a bar line. Time signatures look like time signatures. Chord names are written as you would write them on a lead sheet.
 - **Left-aligned, ragged right.** Unlike some chord chart tools that stretch rows to fill the page width, grigson renders rows at their natural width. A bar with four beats takes up twice as much space as a bar with two beats. The space a passage occupies on the page reflects how long it lasts in time.
 - **Explicit row layout.** Each line in the source becomes a row in the output. You control the layout by how you arrange your source text.
-- **Simple rhythm.** Grigson does not use a rhythm staff or per-chord duration notation. Rhythmic information is conveyed through beat-slot notation (see below).
+- **Simple rhythm.** Grigson does not use a rhythm staff or per-chord duration notation. Rhythmic information is conveyed through beat-cell notation (see below).
 - **Key per section.** Songs that modulate between sections (e.g. verse in Eb, chorus in Ab) can specify a key for each section independently.
 
 ---
@@ -244,13 +244,13 @@ Hints are separated from the beat grid. The `Bar` type has an optional `tonality
 
 ```typescript
 interface TonalityHintItem {
-  beforeSlotIndex: number; // hint applies from this beat-slot index onward within the bar
+  beforeCellIndex: number; // hint applies from this beat-cell index onward within the bar
   key: string;             // e.g. "Ab major", "D dorian"; "" = reset to home
   loc?: SourceRange;
 }
 ```
 
-Tonality hints do not occupy a beat slot — they are a side channel on `Bar`. The `slots` array contains only `ChordSlot` and `DotSlot` entries, as before.
+Tonality hints do not occupy a beat cell — they are a side channel on `Bar`. The `cells` array contains only `ChordCell` and `DotCell` entries, as before.
 
 ---
 
@@ -357,7 +357,7 @@ To use the extension during development, open the `packages/vscode-extension` di
 
 ## What Grigson Does Not Support (by design)
 
-- **Rhythm notation.** There is no staff, no note durations on individual chords, no ties or triplets beyond what beat-slot notation can express.
+- **Rhythm notation.** There is no staff, no note durations on individual chords, no ties or triplets beyond what beat-cell notation can express.
 - **Navigation signs.** Coda, Segno, Da Capo, Dal Segno, and Fine are not supported in v1. Use repeat barlines and volta brackets instead, or write the song out in full.
 - **Lyrics.** Grigson is a chord chart tool, not a lead sheet tool.
 - **Auto-reflow.** Row layout is always controlled explicitly by the source text.

packages/grigson/documentation/cli.md

@@ -351,11 +351,11 @@ The error points to the exact position in the input (`line:character`).
 
 #### Semantic warning — beat balance
 
-Parse errors catch syntax problems; semantic warnings catch musical logic errors that the parser accepts. A bar with dot slots must have exactly as many slots as the time signature's numerator:
+Parse errors catch syntax problems; semantic warnings catch musical logic errors that the parser accepts. A bar with dot cells must have exactly as many cells as the time signature's numerator:
 
 ```sh
 $ echo '| (4/4) C . . G . |' | grigson validate
-<stdin>:1:3: warning: Bar has 5 slots but time signature is 4/4 (expected 4)
+<stdin>:1:3: warning: Bar has 5 cells but time signature is 4/4 (expected 4)
 $ echo $?
 1
 ```
@@ -368,7 +368,7 @@ $ echo $?
 
 ```sh
 $ echo '| C | Am | F | G |' | grigson-html-renderer
-<div part="song" style="--beat-cols: 16; --min-beat-width: 1.00em"><div part="song-grid"><section part="section" style="display: contents"><div part="row" style="grid-column: 1 / 34"><span part="barline barline-single barline-position-start" aria-hidden="true" style="grid-column: 1">…</span><span part="slot bar-start" style="grid-column: 2 / span 7"><span part="chord" aria-label="C, whole bar"><span part="chord-root" aria-hidden="true">C</span></span></span>…</div></section></div></div>
+<div part="song" style="--beat-cols: 16; --min-beat-width: 1.00em"><div part="song-grid"><section part="section" style="display: contents"><div part="row" style="grid-column: 1 / 34"><span part="barline barline-single barline-position-start" aria-hidden="true" style="grid-column: 1">…</span><span part="cell bar-start" style="grid-column: 2 / span 7"><span part="chord" aria-label="C, whole bar"><span part="chord-root" aria-hidden="true">C</span></span></span>…</div></section></div></div>
 ```
 
 The output is unstyled markup. It can be piped into a file and served alongside the grigson stylesheet, or it can be passed through a normalise/transpose step first:

packages/grigson/documentation/harmonic-analysis.md

@@ -178,11 +178,11 @@ interface AnnotatedChordSlot {
   loc?: SourceRange;
 }
 
-type AnalysedBeatSlot = AnnotatedChordSlot | DotSlot;
+type AnalysedBeatCell = AnnotatedChordCell | DotCell;
 
 interface AnalysedBar {
   type: 'bar';
-  slots: AnalysedBeatSlot[];
+  cells: AnalysedBeatCell[];
   timeSignature?: TimeSignature;
   tonalityHints?: TonalityHintItem[];
   closeBarline: Barline;
@@ -227,12 +227,12 @@ interface AnalysedSong {
 
 ### Tonality hints
 
-Tonality hints appear as `TonalityHintItem` entries on `Bar.tonalityHints`. The `beforeSlotIndex` field records which chord slot in the bar the hint precedes, enabling correct key-region splitting.
+Tonality hints appear as `TonalityHintItem` entries on `Bar.tonalityHints`. The `beforeCellIndex` field records which chord cell in the bar the hint precedes, enabling correct key-region splitting.
 
 ```
 {Ab major} C Am | F G
  ↑
- hint before slot 0 → C and Am analysed in Ab major
+ hint before cell 0 → C and Am analysed in Ab major
  F and G (next bar, no hint) → same Ab major region continues
 ```
 

packages/grigson/documentation/renderer.md

@@ -98,15 +98,15 @@ The renderer produces a hierarchy of elements, each with a `part` attribute:
 
         <!-- bar 1: 4/4, 2 chords → 2 beats each -->
         <!-- time-sig shown because bar.timeSignature is set on this bar -->
-        <span part="slot" style="grid-column: 2 / span 2">
+        <span part="cell" style="grid-column: 2 / span 2">
           <span part="time-sig">
             <!-- Math Bold digits: U+1D7D2 = 𝟒, rendered via GrigsonTimeSig @font-face -->
             <span part="time-sig-num">𝟒</span>
             <span part="time-sig-den">𝟒</span>
           </span>
           <span part="chord"><span part="chord-root">C</span></span>
         </span>
-        <span part="slot" style="grid-column: 4 / span 2">
+        <span part="cell" style="grid-column: 4 / span 2">
           <span part="chord">
             <span part="chord-root">A<span part="chord-accidental" data-glyph="unicode">♭</span></span>
             <span part="chord-quality">m</span>
@@ -140,7 +140,7 @@ The `song-grid` element defines a CSS Grid whose column count equals the longest
 </span>
 ```
 
-#### Dot slot (beat continuation)
+#### Dot cell (beat continuation)
 
 ```html
 <span part="dot" style="grid-column: 5 / span 1">/</span>
@@ -175,7 +175,7 @@ The `song-grid` element defines a CSS Grid whose column count equals the longest
 | `barline-endRepeat`            | —           | End-repeat barline `:\|\|`                                                                                         |
 | `barline-endRepeatStartRepeat` | —           | Turn-around barline `:\|\|:`                                                                                       |
 | `barline-repeat-count`         | `<span>`    | Repeat count label, e.g. "×3", inside an end-repeat barline                                                        |
-| `slot`                         | `<span>`    | One chord slot; carries `grid-column` positioning                                                                  |
+| `cell`                         | `<span>`    | One chord cell; carries `grid-column` positioning                                                                  |
 | `dot`                          | `<span>`    | A beat-continuation dot rendered as `/`                                                                            |
 | `simile`                       | `<span>`    | Single-bar repeat mark (SMuFL U+E1E7 from Bravura); spans the full bar width                                       |
 | `time-sig`                     | `<span>`    | Time signature stacked fraction; uses the `GrigsonTimeSig` @font-face for digit glyphs                             |
@@ -909,7 +909,7 @@ class MyRenderer {
     //   section.label  — e.g. "Verse", or null if unlabelled
     //   section.rows   — array of Row objects
     //     row.bars     — array of Bar objects
-    //       bar.slots           — array of BeatSlot (ChordSlot | DotSlot)
+    //       bar.cells           — array of BeatCell (ChordCell | DotCell)
     //       bar.timeSignature   — { numerator, denominator } or undefined
   }
 }

packages/grigson/documentation/source-locations.md

@@ -46,7 +46,7 @@ const bar = song.sections[0].rows[0].bars[0];
 console.log(bar.loc);
 // { start: { line: 0, character: 2 }, end: { line: 0, character: 6 } }
 
-console.log(bar.slots[0].loc);
+console.log(bar.cells[0].loc);
 // { start: { line: 0, character: 2 }, end: { line: 0, character: 4 } }
 ```
 

packages/grigson/documentation/testing.md

@@ -49,7 +49,7 @@ The parser is the highest-value layer to test. Tests cover each grammar rule in
 expect(parseChord('Cm7')).toEqual({ root: 'C', quality: 'minor', extensions: ['7'] });
 expect(parseChord('F#/A#')).toEqual({ root: 'F#', quality: 'major', bass: 'A#' });
 
-// Beat slot notation
+// Beat cell notation
 expect(parseBar('C . . G')).toEqual([
   { type: 'chord', value: 'C', beats: 3 },
   { type: 'chord', value: 'G', beats: 1 },