Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

13.2 KB
Raw Blame
// PortOS lead-sheet notation — a tiny, dependency-free text format for melody +
// chords + lyrics, and the pure parser that turns it into a structured score the
// <ScoreSheet> SVG renderer draws. We render our own staff rather than pulling
// in abcjs / VexFlow / OpenSheetMusicDisplay, so this module is the single
// source of truth for "what the text means"; the renderer only does geometry.
//
// FORMAT (one worked example — "500 Miles", verse, ships as the seed score):
//
//   clef: treble        ← header lines: `key: value`, any order, before the music
//   key: C
//   time: 4/4
//   tempo: 68
//
//   | [C] E4q(If) G4q(you) G4q(miss) G4q(the) | [Am] A4h(train) G4q(I'm) E4q(on) |
//
// Music body: measures separated by `|` (a leading/trailing `|` is fine), notes
// separated by whitespace within a measure. A note token is:
//
//   [chord]  PITCH  DURATION  dots?  (lyric)
//   └ above  └ C4   └ q       └ .    └ under the note
//
//   PITCH    = letter A–G, optional accidental (# b n, or ## bb), octave digit
//              (scientific pitch: C4 = middle C). e.g. C4, F#4, Bb3, En5
//   DURATION = w h q e s t  → whole, half, quarter, eighth, sixteenth, 32nd
//   dots     = trailing `.` each adds half the value again (q. = 1.5 beats)
//   rest     = `r` + duration, e.g. rq, rh, re.   (no pitch, no lyric)
//   [chord]  = a chord symbol drawn above that note (C, Am, G7, F/A …)
//   (lyric)  = a syllable drawn under that note; use a trailing `-` to show a
//              held syllable (whis- / tle)
//
// The parser is forgiving: an unparseable token is collected into `errors` with
// its measure number and skipped, so the rest of the score still renders. Keep
// this module pure (no React, no imports) — it's unit-tested and barrelled.

// Diatonic letter → its index within an octave starting at C. Used to turn a
// pitch into a single "diatonic step" integer (C4 = 0, D4 = 1 … B4 = 6, C5 = 7),
// which is all the geometry needs: every staff line/space is one step apart.
const LETTER_INDEX = { C: 0, D: 1, E: 2, F: 3, G: 4, A: 5, B: 6 };

// Duration code → its musical properties. `beats` is the undotted value in
// quarter-note beats; `filled` picks an open vs solid notehead; `flags` is how
// many flags hang off the stem (eighth = 1, sixteenth = 2 …); whole notes are
// stemless. Dots are applied on top of `beats` (see durationBeats).
export const DURATIONS = {
  w: { code: 'w', beats: 4, filled: false, stem: false, flags: 0, label: 'whole' },
  h: { code: 'h', beats: 2, filled: false, stem: true, flags: 0, label: 'half' },
  q: { code: 'q', beats: 1, filled: true, stem: true, flags: 0, label: 'quarter' },
  e: { code: 'e', beats: 0.5, filled: true, stem: true, flags: 1, label: 'eighth' },
  s: { code: 's', beats: 0.25, filled: true, stem: true, flags: 2, label: 'sixteenth' },
  t: { code: 't', beats: 0.125, filled: true, stem: true, flags: 3, label: 'thirty-second' },
};

// Beats for a duration code with `dots` dots applied. A single dot adds half the
// value (×1.5), two dots add a half + a quarter (×1.75), etc. — the standard
// dotted-note geometric series 2 − (1/2)^dots.
export const durationBeats = (code, dots = 0) => {
  const base = DURATIONS[code]?.beats;
  if (base == null) return 0;
  return base * (2 - Math.pow(0.5, dots));
};

// Major-key signatures: tonic letter (with optional accidental) → the ordered
// accidentals it carries. We key off the bare tonic so "C", "C major", "C Major"
// and "Cmaj" all resolve. Order matters — it's the order the glyphs are drawn at
// the clef (F C G D A E B for sharps; the reverse for flats).
const SHARP_ORDER = ['F', 'C', 'G', 'D', 'A', 'E', 'B'];
const FLAT_ORDER = ['B', 'E', 'A', 'D', 'G', 'C', 'F'];
const SHARP_KEYS = { G: 1, D: 2, A: 3, E: 4, B: 5, 'F#': 6, 'C#': 7 };
const FLAT_KEYS = { F: 1, Bb: 2, Eb: 3, Ab: 4, Db: 5, Gb: 6, Cb: 7 };

// Minor tonic → its relative major (tonic + minor third up), so a minor key
// resolves through the SHARP_KEYS/FLAT_KEYS major lookup above instead of
// (incorrectly) reusing its own letter as if it were major. Covers the 15
// keys reachable through SHARP_KEYS/FLAT_KEYS + natural C/Am. Explicit modes
// (dorian, mixolydian, …) are out of scope — score those in C (all naturals)
// per the existing convention, same as the seed data does.
const MINOR_TO_MAJOR = {
  A: 'C', E: 'G', B: 'D', 'F#': 'A', 'C#': 'E', 'G#': 'B', 'D#': 'F#', 'A#': 'C#',
  D: 'F', G: 'Bb', C: 'Eb', F: 'Ab', Bb: 'Db', Eb: 'Gb', Ab: 'Cb',
};

// Matches a minor qualifier immediately following the tonic: `m`, `min`, or
// `minor` (case-insensitive), optionally preceded by whitespace. The trailing
// `\b` is what keeps this from misfiring on "major"/"maj" — after matching the
// bare `m`, the next character in "major" is the word-char `a`, so there's no
// word boundary and the whole match fails, leaving the tonic to resolve as
// major (unchanged default behavior).
const MINOR_QUALIFIER = /^\s*m(?:in(?:or)?)?\b/i;

// Resolve a key string ("C major", "Eb", "D minor", "F# minor", "Bbm") to a
// key-signature descriptor. We read the tonic (letter + optional single
// accidental) plus an optional minor qualifier right after it; a minor tonic
// is mapped to its relative major before the lookup, so the signature matches
// the actual key rather than the parallel major. Unknown → C (no accidentals).
export const keySignature = (keyName) => {
  const raw = keyName || '';
  const m = /^\s*([A-Ga-g])([#b]?)/.exec(raw);
  let tonic = m ? `${m[1].toUpperCase()}${m[2]}` : 'C';
  if (m && MINOR_QUALIFIER.test(raw.slice(m[0].length)) && MINOR_TO_MAJOR[tonic]) {
    tonic = MINOR_TO_MAJOR[tonic];
  }
  if (SHARP_KEYS[tonic]) {
    const count = SHARP_KEYS[tonic];
    return { type: 'sharp', count, letters: SHARP_ORDER.slice(0, count) };
  }
  if (FLAT_KEYS[tonic]) {
    const count = FLAT_KEYS[tonic];
    return { type: 'flat', count, letters: FLAT_ORDER.slice(0, count) };
  }
  return { type: 'none', count: 0, letters: [] };
};

// Diatonic step for a letter+octave (C4 = 0). Ignores accidentals — they shift
// pitch chromatically but a sharp/flat note still sits on its letter's line.
export const diatonicStep = (letter, octave) => {
  const idx = LETTER_INDEX[String(letter || '').toUpperCase()];
  if (idx == null || !Number.isFinite(octave)) return null;
  return (octave - 4) * 7 + idx;
};

// Parse a bare pitch (no duration), e.g. "F#4" → { letter, accidental, octave,
// step }. Accidental is normalized to '', '#', '##', 'b', 'bb', or 'n'. Returns
// null for anything that isn't a pitch (callers treat null as "not a note").
export const parsePitch = (str) => {
  const m = /^([A-Ga-g])(#{1,2}|b{1,2}|n)?(-?\d)$/.exec(String(str || '').trim());
  if (!m) return null;
  const letter = m[1].toUpperCase();
  const accidental = m[2] || '';
  const octave = Number(m[3]);
  return { letter, accidental, octave, step: diatonicStep(letter, octave) };
};

// Default headers — every field has a sane fallback so a score with no header
// block still renders (treble, C major, 4/4).
const DEFAULT_HEADER = { clef: 'treble', key: 'C', beats: 4, beatValue: 4, tempo: null };

const parseTimeSignature = (raw) => {
  const m = /^\s*(\d{1,2})\s*\/\s*(\d{1,2})\s*$/.exec(raw || '');
  if (!m) return null;
  const beats = Number(m[1]);
  const beatValue = Number(m[2]);
  if (!beats || !beatValue) return null;
  return { beats, beatValue };
};

// One token → a note/rest object, or { error } if it doesn't parse. Grammar:
//   [chord]? (r | PITCH) DURATION dots? (lyric)?
const TOKEN_RE = /^(?:\[([^\]]*)\])?(r|[A-Ga-g](?:#{1,2}|b{1,2}|n)?-?\d)([whqest])(\.*)(?:\((.*)\))?$/;

const parseToken = (token, start = null) => {
  const m = TOKEN_RE.exec(token);
  if (!m) return { error: `unrecognized token "${token}"` };
  const [, chord, core, durCode, dotStr, lyric] = m;
  const tokenSource = Number.isInteger(start)
    ? {
        raw: token,
        start,
        end: start + token.length,
        pitchStart: start + (chord == null ? 0 : token.indexOf(']') + 1),
        pitchEnd: start + (chord == null ? 0 : token.indexOf(']') + 1) + core.length,
      }
    : { raw: token };
  const dots = dotStr ? dotStr.length : 0;
  // Carry the static duration properties (filled / stem / flags) the renderer
  // needs alongside the per-token dots/beats, so a duration object is fully
  // self-describing — a quarter note knows it's solid-with-stem, not just "1 beat".
  const base = DURATIONS[durCode];
  const duration = { code: durCode, dots, beats: durationBeats(durCode, dots), filled: base.filled, stem: base.stem, flags: base.flags };
  if (core === 'r') {
    return { rest: true, duration, chord: chord || '', ...tokenSource };
  }
  const pitch = parsePitch(core);
  if (!pitch) return { error: `bad pitch in "${token}"` };
  return {
    rest: false,
    pitch,
    step: pitch.step,
    duration,
    chord: chord || '',
    lyric: lyric || '',
    ...tokenSource,
  };
};

// Parse a full score string into { clef, key, keySig, time, tempo, measures,
// errors }. `measures` is an array of { notes, beats } where `beats` is the
// summed duration (handy for the renderer to flag incomplete bars, and for
// tests). Always returns a usable object — never throws.
export const parseScore = (text) => {
  const source = String(text || '');
  const header = { ...DEFAULT_HEADER };
  const errors = [];
  const bodyLines = [];

  let lineStart = 0;
  for (const rawLine of source.split(/\r?\n/)) {
    const rawEnd = lineStart + rawLine.length;
    const newlineLength = source.startsWith('\r\n', rawEnd) ? 2 : (source[rawEnd] === '\n' ? 1 : 0);
    const nextLineStart = rawEnd + newlineLength;
    const line = rawLine.trim();
    if (!line) {
      lineStart = nextLineStart;
      continue;
    }
    // A header line is `key: value` and contains no `|` (music) and no note
    // tokens. We detect it by the leading `word:` shape before any `|`.
    const headerMatch = /^([A-Za-z]+)\s*:\s*(.+)$/.exec(line);
    if (headerMatch && !line.includes('|')) {
      const field = headerMatch[1].toLowerCase();
      const value = headerMatch[2].trim();
      if (field === 'clef') header.clef = /^bass$/i.test(value) ? 'bass' : 'treble';
      else if (field === 'key') header.key = value;
      else if (field === 'tempo') { const t = Number(value); if (Number.isFinite(t)) header.tempo = t; }
      else if (field === 'time') {
        const ts = parseTimeSignature(value);
        if (ts) { header.beats = ts.beats; header.beatValue = ts.beatValue; }
        else errors.push(`bad time signature "${value}"`);
      }
      lineStart = nextLineStart;
      continue;
    }
    bodyLines.push({ rawLine, start: lineStart });
    lineStart = nextLineStart;
  }

  // Scan the original source instead of joining/reflowing the body. Each parsed
  // note carries offsets back into `source`, so a caller can surgically replace
  // its pitch while preserving every other byte (including line breaks).
  const measures = [];
  let notes = [];
  let pendingChord = '';
  let segmentHasToken = false;
  const finishMeasure = () => {
    if (!segmentHasToken) return;
    const beats = notes.reduce((sum, n) => sum + (n.duration?.beats || 0), 0);
    measures.push({ notes, beats });
    notes = [];
    pendingChord = '';
    segmentHasToken = false;
  };

  for (const { rawLine, start } of bodyLines) {
    for (const match of rawLine.matchAll(/\||[^\s|]+/g)) {
      const token = match[0];
      if (token === '|') {
        finishMeasure();
        continue;
      }
      segmentHasToken = true;
      const bare = /^\[([^\]]*)\]$/.exec(token);
      if (bare) {
        pendingChord = bare[1];
        continue;
      }
      const parsed = parseToken(token, start + match.index);
      if (parsed.error) {
        errors.push(`measure ${measures.length + 1}: ${parsed.error}`);
        continue;
      }
      if (pendingChord && !parsed.chord) parsed.chord = pendingChord;
      pendingChord = '';
      notes.push(parsed);
    }
  }
  finishMeasure();

  return {
    clef: header.clef,
    key: header.key,
    keySig: keySignature(header.key),
    time: { beats: header.beats, beatValue: header.beatValue },
    tempo: header.tempo,
    measures,
    errors,
  };
};

// Replace only the pitch characters inside one parsed note token. Source spans
// are validated against the current text so a stale note object cannot rewrite
// a different score after the editor changes.
export const replaceNotePitch = (text, note, newPitch) => {
  const source = String(text || '');
  const replacement = parsePitch(newPitch);
  if (!note || note.rest || !replacement) throw new Error('A pitched note and valid replacement pitch are required');
  if (!Number.isInteger(note.start) || !Number.isInteger(note.end)
    || !Number.isInteger(note.pitchStart) || !Number.isInteger(note.pitchEnd)
    || source.slice(note.start, note.end) !== note.raw) {
    throw new Error('The note source span is stale or invalid');
  }
  const pitchText = `${replacement.letter}${replacement.accidental}${replacement.octave}`;
  return source.slice(0, note.pitchStart) + pitchText + source.slice(note.pitchEnd);
};

// True when the text contains at least one parseable note — lets the UI decide
// whether to show the staff or an empty-state hint without rendering first.
export const scoreHasMusic = (text) => parseScore(text).measures.some((m) => m.notes.length > 0);