songsheet 7.5.0 → 7.7.0

package/index.d.ts

@@ -7,6 +7,8 @@ export interface Chord {
   push?: boolean
   stop?: boolean
   splitMeasure?: Chord[]
+  splitOpen?: boolean
+  splitClose?: boolean
 }
 
 export interface PositionedChord extends Chord {
@@ -67,6 +69,7 @@ export interface PlaybackChord {
   push?: boolean
   stop?: boolean
   markerIndex?: number
+  splitIndex?: number
   beatStart: number
   durationInBeats: number
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "songsheet",
-  "version": "7.5.0",
+  "version": "7.7.0",
   "description": "A songsheet interpreter",
   "type": "module",
   "exports": "./index.js",

package/src/lexer.js

@@ -62,13 +62,50 @@ const DECORATOR_STOP_CHARS = new Set(['>', ']', '!'])
  *
  * A chord line must contain at least one chord, and every non-whitespace
  * token must parse as a valid chord, decorator, or `|`.
+ *
+ * Options:
+ *   continueSplit: true — line is a continuation of a cross-line split measure.
+ *     Pre-scans for chords before `]`, emits SPLIT_CLOSE, then continues normal scanning.
  */
-export function scanChordLine(line) {
+export function scanChordLine(line, options = {}) {
   if (!line || line.trim().length === 0) return null
 
   const tokens = []
   let i = 0
 
+  // When continueSplit is set, we expect chords followed by `]` at the start of the line
+  if (options.continueSplit) {
+    const closeChords = []
+    // scan for chords before `]`
+    while (i < line.length && line[i] !== ']') {
+      if (line[i] === ' ' || line[i] === '\t') { i++; continue }
+      const result = parseChordAt(line, i, DECORATOR_STOP_CHARS)
+      if (!result) return null // non-chord content before ] means not a valid continuation
+      closeChords.push(result.token)
+      i = result.end
+    }
+    if (i >= line.length || line[i] !== ']') return null // no ] found
+    if (closeChords.length === 0) return null // must have at least one chord
+    const column = closeChords[0].column
+    i++ // consume ]
+    // next char must be whitespace, end-of-line, or |
+    if (i < line.length && line[i] !== ' ' && line[i] !== '\t' && line[i] !== '|') {
+      return null
+    }
+    tokens.push({
+      type: 'SPLIT_CLOSE',
+      column,
+      rawTokens: closeChords,
+      chords: closeChords.map(c => {
+        const sc = { root: c.root, type: c.quality }
+        if (c.bass) sc.bass = c.bass
+        if (c.nashville) sc.nashville = true
+        return sc
+      }),
+    })
+    // continue scanning the rest of the line normally
+  }
+
   while (i < line.length) {
     // skip whitespace
     if (line[i] === ' ' || line[i] === '\t') {
@@ -125,6 +162,7 @@ export function scanChordLine(line) {
 
     // split measure: [chord chord ...]
     if (line[i] === '[') {
+      const openColumn = column
       i++ // consume [
       const chords = []
       while (i < line.length && line[i] !== ']') {
@@ -134,7 +172,27 @@ export function scanChordLine(line) {
         chords.push(result.token)
         i = result.end
       }
-      if (i >= line.length || line[i] !== ']') return null
+      if (i >= line.length) {
+        // No ] found — this is a cross-line split open
+        if (chords.length < 1) return null // need at least 1 chord after [
+        const first = chords[0]
+        const token = {
+          type: 'SPLIT_OPEN',
+          column: openColumn,
+          root: first.root,
+          quality: first.quality,
+          chords: chords.map(c => {
+            const sc = { root: c.root, type: c.quality }
+            if (c.bass) sc.bass = c.bass
+            if (c.nashville) sc.nashville = true
+            return sc
+          }),
+        }
+        if (first.bass) token.bass = first.bass
+        if (first.nashville) token.nashville = true
+        tokens.push(token)
+        continue
+      }
       i++ // consume ]
       if (chords.length < 2) return null
       // next char must be whitespace, end-of-line, or |
@@ -145,7 +203,7 @@ export function scanChordLine(line) {
       const first = chords[0]
       const token = {
         type: 'CHORD',
-        column,
+        column: openColumn,
         root: first.root,
         quality: first.quality,
         splitMeasure: chords.map(c => {

package/src/parser.js

@@ -15,6 +15,8 @@ function tokenToChord(token) {
   if (token.push) chord.push = true
   if (token.stop) chord.stop = true
   if (token.splitMeasure) chord.splitMeasure = token.splitMeasure
+  if (token.splitOpen) chord.splitOpen = true
+  if (token.splitClose) chord.splitClose = true
   return chord
 }
 
@@ -262,41 +264,177 @@ function parseChordLyricBlock(text) {
   const allLyrics = []
   let i = 0
   let lastChord = null
+  let pendingSplit = null // tracks cross-line split measure state
 
   while (i < rawLines.length) {
     const line = rawLines[i]
+
+    // If we have a pending split open, try to parse this line with continueSplit first
+    if (pendingSplit) {
+      const contTokens = scanChordLine(line, { continueSplit: true })
+      if (contTokens) {
+        // Found the SPLIT_CLOSE — merge with the open chords
+        const closeToken = contTokens.find(t => t.type === 'SPLIT_CLOSE')
+        if (closeToken) {
+          const allSplitChords = [...pendingSplit.openChords, ...closeToken.chords]
+          // Update the chord on the earlier line: add splitMeasure + splitOpen flag
+          const earlierChord = pendingSplit.lineData.chords[pendingSplit.chordIndex]
+          earlierChord.splitMeasure = allSplitChords
+          earlierChord.splitOpen = true
+          // Also update the allChords entry
+          const allChordsEntry = allChords[pendingSplit.allChordsIndex]
+          if (allChordsEntry) {
+            allChordsEntry.splitMeasure = allSplitChords
+            allChordsEntry.splitOpen = true
+          }
+
+          // Build chords for this continuation line:
+          // - close chords get splitClose flag + the shared splitMeasure
+          // - remaining chords after ] are normal
+          const closeChordPositioned = []
+          for (const rawTok of closeToken.rawTokens) {
+            const chord = tokenToPositionedChord(rawTok)
+            chord.splitClose = true
+            chord.splitMeasure = allSplitChords
+            closeChordPositioned.push(chord)
+          }
+          const restChords = contTokens.filter(t => t.type === 'CHORD').map(t => tokenToPositionedChord(t))
+          const lineChords = [...closeChordPositioned, ...restChords]
+
+          // Build barLines for this line
+          const sortedTokens = [...contTokens].sort((a, b) => a.column - b.column)
+          let currentChord = lastChord
+          const barLines = []
+          for (const tok of sortedTokens) {
+            if (tok.type === 'CHORD') {
+              currentChord = tokenToChord(tok)
+            } else if (tok.type === 'SPLIT_CLOSE') {
+              // Update currentChord to the last close chord
+              const lastClose = closeToken.chords[closeToken.chords.length - 1]
+              currentChord = { root: lastClose.root, type: lastClose.type }
+              if (lastClose.bass) currentChord.bass = lastClose.bass
+              if (lastClose.nashville) currentChord.nashville = true
+            } else if (tok.type === 'BAR_LINE') {
+              const bar = { column: tok.column }
+              if (currentChord) bar.chord = currentChord
+              barLines.push(bar)
+            }
+          }
+          if (currentChord) lastChord = currentChord
+
+          pendingSplit = null
+          i++
+
+          // Find the paired lyric line
+          let lyricLine = ''
+          if (i < rawLines.length) {
+            const nextIsChord = scanChordLine(rawLines[i])
+            if (!nextIsChord) {
+              lyricLine = rawLines[i]
+              i++
+            }
+          }
+
+          // Add close chords + rest chords to allChords
+          allChords.push(...lineChords.map(c => {
+            const ch = { root: c.root, type: c.type }
+            if (c.bass) ch.bass = c.bass
+            if (c.nashville) ch.nashville = true
+            if (c.diamond) ch.diamond = true
+            if (c.push) ch.push = true
+            if (c.stop) ch.stop = true
+            if (c.splitMeasure) ch.splitMeasure = c.splitMeasure
+            if (c.splitClose) ch.splitClose = true
+            return ch
+          }))
+          if (lyricLine) allLyrics.push(lyricLine)
+
+          // Build alignment tokens from the close chord raw tokens + rest tokens
+          const alignTokens = [
+            ...closeToken.rawTokens,
+            ...contTokens.filter(t => t.type !== 'SPLIT_CLOSE'),
+          ]
+
+          lines.push({
+            chords: lineChords,
+            barLines,
+            lyrics: lyricLine,
+            characters: buildCharacterAlignment(alignTokens, lyricLine),
+          })
+          continue
+        }
+      }
+      // If continueSplit didn't match, this line is a lyric line between split lines
+      // (fall through to normal handling below)
+    }
+
     const tokens = scanChordLine(line)
 
     if (tokens) {
-      // This is a chord line — next non-chord line is its paired lyric
-      const chordTokens = tokens
-      const chords = tokens.filter(t => t.type === 'CHORD').map(t => tokenToPositionedChord(t))
+      // Check for SPLIT_OPEN token (cross-line split)
+      const splitOpenToken = tokens.find(t => t.type === 'SPLIT_OPEN')
+
+      // This is a chord line
+      // For alignment, use all tokens except SPLIT_OPEN (which becomes a regular chord)
+      const chordTokens = []
+      const chords = []
+      for (const t of tokens) {
+        if (t.type === 'CHORD') {
+          chords.push(tokenToPositionedChord(t))
+          chordTokens.push(t)
+        } else if (t.type === 'SPLIT_OPEN') {
+          // Add the first chord of the split as a positioned chord at the [ column
+          const first = t.chords[0]
+          const chord = { root: first.root, type: first.type, column: t.column }
+          if (first.bass) chord.bass = first.bass
+          if (first.nashville) chord.nashville = true
+          // splitOpen flag — splitMeasure will be set when we find the SPLIT_CLOSE
+          chord.splitOpen = true
+          chords.push(chord)
+          // For alignment, create a synthetic CHORD token
+          chordTokens.push({ type: 'CHORD', column: t.column, root: first.root, quality: first.type })
+        } else {
+          chordTokens.push(t)
+        }
+      }
 
       // Build barLines as objects with chord context
-      // Sort all tokens by column, walk left-to-right tracking currentChord
       const sortedTokens = [...tokens].sort((a, b) => a.column - b.column)
       let currentChord = lastChord
       const barLines = []
       for (const tok of sortedTokens) {
-        if (tok.type === 'CHORD') {
-          currentChord = tokenToChord(tok)
+        if (tok.type === 'CHORD' || tok.type === 'SPLIT_OPEN') {
+          if (tok.type === 'CHORD') {
+            currentChord = tokenToChord(tok)
+          } else {
+            const first = tok.chords[0]
+            currentChord = { root: first.root, type: first.type }
+            if (first.bass) currentChord.bass = first.bass
+            if (first.nashville) currentChord.nashville = true
+          }
         } else if (tok.type === 'BAR_LINE') {
           const bar = { column: tok.column }
           if (currentChord) bar.chord = currentChord
           barLines.push(bar)
         }
       }
-      // Update lastChord for the next line
       if (currentChord) lastChord = currentChord
 
       i++
       // Find the paired lyric line (next line that isn't a chord line)
       let lyricLine = ''
-      if (i < rawLines.length && !isChordLine(rawLines[i])) {
-        lyricLine = rawLines[i]
-        i++
+      if (i < rawLines.length) {
+        const nextIsChord = scanChordLine(rawLines[i])
+        if (!nextIsChord) {
+          // Also check if it's a split continuation line — don't consume as lyrics
+          if (!splitOpenToken || !scanChordLine(rawLines[i], { continueSplit: true })) {
+            lyricLine = rawLines[i]
+            i++
+          }
+        }
       }
 
+      const allChordsStartIndex = allChords.length
       allChords.push(...chords.map(c => {
         const ch = { root: c.root, type: c.type }
         if (c.bass) ch.bass = c.bass
@@ -305,16 +443,30 @@ function parseChordLyricBlock(text) {
         if (c.push) ch.push = true
         if (c.stop) ch.stop = true
         if (c.splitMeasure) ch.splitMeasure = c.splitMeasure
+        if (c.splitOpen) ch.splitOpen = true
+        if (c.splitClose) ch.splitClose = true
         return ch
       }))
       if (lyricLine) allLyrics.push(lyricLine)
 
-      lines.push({
+      const lineData = {
         chords,
         barLines,
         lyrics: lyricLine,
         characters: buildCharacterAlignment(chordTokens, lyricLine),
-      })
+      }
+      lines.push(lineData)
+
+      // If we found a SPLIT_OPEN, set up pendingSplit for cross-line merging
+      if (splitOpenToken) {
+        const splitChordIndex = chords.length - 1
+        pendingSplit = {
+          lineData,
+          chordIndex: splitChordIndex,
+          allChordsIndex: allChordsStartIndex + splitChordIndex,
+          openChords: splitOpenToken.chords,
+        }
+      }
     } else {
       // Lyric-only line (no chord line above it)
       if (line.trim().length > 0) {

package/src/playback.js

@@ -4,7 +4,7 @@
  */
 function expandChord(chord, markerIndex) {
   if (chord.splitMeasure && chord.splitMeasure.length > 0) {
-    return chord.splitMeasure.map(sc => {
+    return chord.splitMeasure.map((sc, index) => {
       const pc = { root: sc.root, type: sc.type }
       if (sc.bass) pc.bass = sc.bass
       if (sc.nashville) pc.nashville = true
@@ -12,6 +12,7 @@ function expandChord(chord, markerIndex) {
       if (sc.push) pc.push = true
       if (sc.stop) pc.stop = true
       if (markerIndex !== undefined) pc.markerIndex = markerIndex
+      pc.splitIndex = index
       return pc
     })
   }
@@ -84,6 +85,8 @@ export function buildPlaybackTimeline(structure, timeSignature) {
         for (let mi = 0; mi < markers.length; mi++) {
           const m = markers[mi]
           if (m.type === 'chord') {
+            // splitClose chords are already accounted for by the open chord's splitMeasure
+            if (m.chord.splitClose) continue
             lastExpanded = expandChord(m.chord, mi)
             measures.push(buildMeasure(lastExpanded, measureIndex, si, li, ts))
             measureIndex++

package/test/lexer.test.js

@@ -130,6 +130,65 @@ describe('scanChordLine slash chords', () => {
   })
 })
 
+describe('scanChordLine split measures', () => {
+  it('parses same-line split measure [G C]', () => {
+    const tokens = scanChordLine('[G C]')
+    expect(tokens).not.toBeNull()
+    expect(tokens.length).toBe(1)
+    expect(tokens[0].type).toBe('CHORD')
+    expect(tokens[0].splitMeasure).toEqual([
+      { root: 'G', type: '' },
+      { root: 'C', type: '' },
+    ])
+  })
+
+  it('parses cross-line split open: [F at end of line', () => {
+    const tokens = scanChordLine('G                               [F')
+    expect(tokens).not.toBeNull()
+    expect(tokens.length).toBe(2)
+    expect(tokens[0]).toMatchObject({ type: 'CHORD', root: 'G' })
+    expect(tokens[1].type).toBe('SPLIT_OPEN')
+    expect(tokens[1].chords).toEqual([{ root: 'F', type: '' }])
+  })
+
+  it('parses cross-line split close with continueSplit', () => {
+    const tokens = scanChordLine('               C]                G', { continueSplit: true })
+    expect(tokens).not.toBeNull()
+    const closeToken = tokens.find(t => t.type === 'SPLIT_CLOSE')
+    expect(closeToken).toBeDefined()
+    expect(closeToken.chords).toEqual([{ root: 'C', type: '' }])
+    // Rest of line parsed normally
+    const chordTokens = tokens.filter(t => t.type === 'CHORD')
+    expect(chordTokens.length).toBe(1)
+    expect(chordTokens[0].root).toBe('G')
+  })
+
+  it('returns null for continueSplit when no ] found', () => {
+    const tokens = scanChordLine('C G', { continueSplit: true })
+    expect(tokens).toBeNull()
+  })
+
+  it('returns null for continueSplit on a lyric line', () => {
+    const tokens = scanChordLine('Blue mountain road', { continueSplit: true })
+    expect(tokens).toBeNull()
+  })
+
+  it('parses split open with multiple chords: [F C', () => {
+    const tokens = scanChordLine('[F C')
+    expect(tokens).not.toBeNull()
+    expect(tokens[0].type).toBe('SPLIT_OPEN')
+    expect(tokens[0].chords).toEqual([
+      { root: 'F', type: '' },
+      { root: 'C', type: '' },
+    ])
+  })
+
+  it('returns null for [ with no chords', () => {
+    const tokens = scanChordLine('[')
+    expect(tokens).toBeNull()
+  })
+})
+
 describe('lexExpression', () => {
   it('tokenizes simple chord list', () => {
     const tokens = lexExpression('D G D A')

package/test/parser.test.js

@@ -302,6 +302,76 @@ describe('time signature parsing', () => {
   })
 })
 
+describe('cross-line split measure parsing', () => {
+  it('parses cross-line split with chords on separate lines at original columns', () => {
+    const song = parse(
+      'TEST - AUTHOR\n\n' +
+      'G                               [F\n' +
+      ' Blue mountain road, North Carolina,\n' +
+      '               C]                G\n' +
+      " I've been to Asheville once before"
+    )
+    const lines = song.structure[0].lines
+    // Line 0: G at col 0, F at col 32 with splitOpen + splitMeasure
+    expect(lines[0].chords.length).toBe(2)
+    expect(lines[0].chords[0].root).toBe('G')
+    expect(lines[0].chords[0].column).toBe(0)
+    expect(lines[0].chords[1].root).toBe('F')
+    expect(lines[0].chords[1].column).toBe(32)
+    expect(lines[0].chords[1].splitOpen).toBe(true)
+    expect(lines[0].chords[1].splitMeasure).toEqual([
+      { root: 'F', type: '' },
+      { root: 'C', type: '' },
+    ])
+    expect(lines[0].lyrics).toBe(' Blue mountain road, North Carolina,')
+
+    // Line 1: C at col 15 with splitClose, G at col 33
+    expect(lines[1].chords.length).toBe(2)
+    expect(lines[1].chords[0].root).toBe('C')
+    expect(lines[1].chords[0].column).toBe(15)
+    expect(lines[1].chords[0].splitClose).toBe(true)
+    expect(lines[1].chords[1].root).toBe('G')
+    expect(lines[1].chords[1].column).toBe(33)
+    expect(lines[1].lyrics).toBe(" I've been to Asheville once before")
+  })
+
+  it('pairs lyrics correctly with cross-line split', () => {
+    const song = parse(
+      'TEST - AUTHOR\n\n' +
+      'G                               [F\n' +
+      ' Blue mountain road\n' +
+      '               C]                G\n' +
+      ' Asheville town'
+    )
+    const lines = song.structure[0].lines
+    expect(lines[0].lyrics).toBe(' Blue mountain road')
+    expect(lines[1].lyrics).toBe(' Asheville town')
+  })
+
+  it('includes split chords in section allChords with flags', () => {
+    const song = parse(
+      'TEST - AUTHOR\n\n' +
+      'G [F\n' +
+      ' Lyrics one\n' +
+      'C] D\n' +
+      ' Lyrics two'
+    )
+    const chords = song.structure[0].chords
+    // G, F (splitOpen), C (splitClose), D
+    expect(chords.length).toBe(4)
+    expect(chords[0].root).toBe('G')
+    expect(chords[1].root).toBe('F')
+    expect(chords[1].splitOpen).toBe(true)
+    expect(chords[1].splitMeasure).toEqual([
+      { root: 'F', type: '' },
+      { root: 'C', type: '' },
+    ])
+    expect(chords[2].root).toBe('C')
+    expect(chords[2].splitClose).toBe(true)
+    expect(chords[3].root).toBe('D')
+  })
+})
+
 describe('bar line parsing', () => {
   it('parses bar lines in chord lines', () => {
     const song = parse('TEST SONG - AUTHOR\n\n| G | C | D |\nSome lyrics here')