Practice Studio — execution document (module contracts)

Builders: read PRD.md first. Each builder owns the files listed under its lane and must not edit other lanes' files. Everything is vanilla JS ES modules (type="module"), no bundler, no TypeScript, no npm deps at runtime. Target browser: Chrome on Android (foldable), tested headless at 960×704 CSS px, DPR 2.25.

Root: /Users/byronarnao/practice-studio/app/

app/
  index.html  manifest.json  sw.js  css/app.css
  js/main.js            router + app state + screen mounting      (lane 1)
  js/store.js           localStorage/IndexedDB helpers + progress  (lane 1)
  js/calibration.js     pxPerMm, card check, screen E              (lane 1)
  js/instruments.js     scale lengths, tunings, nut widths, fretMm (lane 1)
  js/session.js         guided daily session, spaced repetition   (lane 1)
  js/screens/home.js    screen: session home + posture card        (lane 1)
  js/screens/calibrate.js                                           (lane 1)
  js/chords.js          chord dictionary + voicings + tiers        (lane 2)
  js/songs.js           30-song catalog (ChordPro strings) + index (lane 2)
  js/chordpro.js        ChordPro parser + transpose/capo/simplify  (lane 2)
  js/strum.js           strumming/LH pattern library               (lane 2)
  js/fretboard.js       1:1 neck renderer + touch mapping + drills (lane 3)
  js/screens/guitar.js  screen A                                   (lane 3)
  js/screens/uke.js     screen C                                   (lane 3)
  js/piano.js           keyboard renderer, modes, MIDI             (lane 4)
  js/screens/piano.js   screen B                                   (lane 4)
  js/audio.js           AudioContext, metronome, synths            (lane 5)
  js/listen.js          mic: YIN tuner, chroma verify, onsets      (lane 5)
  js/recorder.js        MediaRecorder + IndexedDB takes            (lane 5)
  js/player.js          song player engine (loop/tempo/count-in)   (lane 5)
  js/screens/songs.js   screen D                                   (lane 5)
  js/screens/record.js                                              (lane 5)
  tests/*.spec.cjs      Playwright (each lane adds its own file)

Shared conventions

Lane 1 — shell, calibration, instruments, session (owner: builder-1)

// instruments.js
export const GUITAR_SCALES = { fender: 648, gibson: 628, classical: 650 };
export const UKE_SCALES = { soprano: 346, concert: 381, tenor: 432 };
export const INSTRUMENTS = {
  guitar: { strings: ['E2','A2','D3','G3','B3','E4'], nutMm: 43, w12Mm: 52, scaleMm: 648 },
  uke:    { strings: ['G4','C4','E4','A4'], nutMm: 35, w12Mm: 42, scaleMm: 381, lowG: false },
  piano:  { whiteKeyMm: 23.5, blackKeyMm: 13.7, whiteKeyLenMm: 150, blackKeyLenMm: 95 }
};
export function fretMm(scaleMm, n)            // n=0 → 0
export function fretsThatFit(scaleMm, widthMm, marginMm=6)
export function noteToMidi('E2') / midiToNote(40) / pc(midi)
export function getInstrument(kind)           // merged with saved user overrides (scale length, tuning, lowG, lefty)
export function setInstrument(kind, patch)
// calibration.js
export const calib = {
  pxPerMm(),            // calibrated or estimate
  isCalibrated(),
  estimate(),           // screen.width*DPR/204.8 → css px/mm
  set(pxPerMm), nudge(deltaPct),
  key()                 // `${screen.width}x${screen.height}@${DPR}`
};
// store.js
export const store = { get(k, def), set(k, v), idb: { put(storeName, obj), all(storeName), del(storeName, id) } };
export const progress = {
  chord(name, inst) → { shapeKnown, masteredCount, bestChangeMs, lastAt },
  markShape(name, inst, landingMs), markMastered(name, inst, changeMs),
  song(id) → { lastPlayedAt, intervalDays, ease, timesPlayed }, markSongPlayed(id, quality 0..5),
  dueSongs(today), minutes(dateStr), addMinutes(dateStr, n)
};
// session.js
export function buildSession(inst, { minutes = 20 })  // → [{ step:'warmup'|'changes'|'song'|'review', title, detail, songId?, chordPair?, seconds }]
export function weakestPair(inst)                  // from progress

Screens: home.js (session steps list, start/next/done with timers, posture card modal, today's minutes), calibrate.js (mockup E exactly, plus a touch test panel: shows count/size of current touches, flags palm (radius > 25 mm) and reports max simultaneous touches). main.js builds the top bar (Practice Studio · tabs · status pill) and mounts screens; registers sw.js; index.html includes manifest.json, viewport meta, fullscreen+landscape request on first tap.

Lane 2 — chords, songs, ChordPro, strum (owner: builder-2)

// chords.js
export const TIERS = { guitar: [[...],[...],[...],[...]], uke: [...], piano: [...] };   // from PRD §5.2
export function parseChord('F#m7/A') → { root: 6, quality: 'm7', bass: 9|null, name }
export function chordPitchClasses('Am') → [9,0,4]
export function voicings('G', 'guitar') → [{ frets:[3,2,0,0,0,3], fingers:[2,1,0,0,0,3], base:1, barre:null|{fret,from,to}, easy:true, name:'open G' }, ...]  // frets: low→high string, -1 = mute, 0 = open
export function voicings('C', 'uke') → same shape, 4 strings low G → A
export function voicings('C', 'piano') → [{ rh:[60,64,67], rhFingers:[1,3,5], lh:[48], lhFingers:[5], inversion:0, name:'root' }, {inversion:1,...}, ...]
export function easiest(name, inst) ; export function simplify(name, inst) → alternative easy chord name or null (e.g. F → Fmaj7 guitar)
export function transposeName('Am', +2) → 'Bm'
export function generateVoicing(name, inst)  // fallback for uncurated: ≤4-fret span, prefer open strings
// chordpro.js
export function parse(text) → { meta:{title,artist,key,tempo,time,strum,tier,capo,lyrics:true|false,source}, sections:[{name, lines:[{ parts:[{chord|null, text}] , bars?}]}], chords:[unique names in order] }
export function transposeSong(song, semis), capoSong(song, fret), simplifySong(song, inst)
export function toText(song)
// songs.js
export const SONGS = [ { id:'amazing-grace', text: `{title: Amazing Grace}...` }, ... ]  // 30 from PRD §5.3; PD songs with full lyrics (verse 1–2 at least); modern songs have {lyrics: false} and sections with chord bars only, e.g. "[G] . . . [Em] . . . [C] . . . [D] . . ."
export function byId(id), list({ inst, tier }) → sorted so each song adds ≤1 new chord over the previous set
export function newChordsFor(song, knownChords)
// strum.js
export const PATTERNS = { 'd-du-udu': { name:'D–DU–UDU', time:'4/4', beats:8 (eighths), hits:[1,0,1,1,0,1,1,1], dirs:['D',null,'D','U',null,'U','D','U'] }, 'd-d-du':{...}, 'boom-chick':{...}, 'island':{...}, 'waltz-3':{...}, 'six-eight':{...}, 'travis':{...} , piano: 'lh-whole','lh-broken','lh-alberti' }
export function expectedOnsets(patternId, bpm, bars) → [ms...]

Tests: every song parses; every chord in every song has ≥1 voicing on guitar, uke, piano; list() ordering adds ≤1 new chord per step (allow ≤2 for the Am songs); transpose round-trips.

Lane 3 — fretboard + guitar/uke screens (owner: builder-3)

// fretboard.js
export class Fretboard {
  constructor(canvas, { inst: 'guitar'|'uke', ctx })
  setWindow(firstFret)         // snaps so no wire within ±4 mm of folds; shows up to fretsThatFit
  setChord(voicing | null)     // targets with finger numbers, open/mute marks at nut
  setOrientation('tab'|'player') ; setLefty(bool)
  on('touch', ({ placed:[{string,fret}], missing, wrong, landingMs }) => {})
  startDrill({ pair:['G','C'], seconds:60 }) → emits 'change' { ms, count } and 'done' { best, avg, count }
  hit(x, y) → { string, fret } | null      // pure mapping for tests
}

Rules: palm = touch.radiusX||radiusY > 25 mm·pxPerMm or > 10 touches → ignore; barre = ≥3 touches on the same fret cluster within 150 ms → one barre target; target zone = the 60 % of the fret space nearest the fret wire. Landing time = first valid touch → all targets satisfied. Draw with canvas at DPR; wood gradient, wires, inlays at 3/5/7/9/12(double), string gauges, fret numbers, scale label "1:1 · 648 mm · frets 0–6". Screens guitar.js (mockup A) and uke.js (mockup C) include: now-chord panel with placed/total bar, change drill panel (landing time, best/avg/count, last-12 bars), now/next chord boxes (SVG chord diagram component chordDiagram(voicing, inst, {size}) exported from fretboard.js for reuse), bottom controls (fret window ◀▶, drill pair picker, Listen toggle, Sound, Lefty, Tab/Player view, Chord list, 60 s drill), listening panel (uses ctx.listen if present; degrade gracefully if not). Tests: hit() mapping at calibrated px/mm for G chord points; fold snapping; palm ignored.

Lane 4 — piano (owner: builder-4)

// piano.js
export class Piano {
  constructor(canvas, { ctx })
  setMode('playable'|'overview'|'oneToOne')  // 2 oct 14.6 mm / 88 keys view-only / 23.5 mm keys
  setRange(lowMidi)                          // pan; minimap drag
  setChord(pianoVoicing|null)                // LH blue, RH orange, finger numbers
  highlight(midi[], color)                   // MIDI input
  on('note', ({ midi, on }) => {})           // touch → note (playable + oneToOne only)
  hit(x, y) → midi | null
}
export const midiIn = { request() → Promise<bool>, on('note', ({midi,on,vel}) => {}), connected() }

Screen piano.js (mockup B): minimap of 88 keys with draggable range box, key-size segmented control, chord name + "LH 5-3-1 · RH 1-3-5", inversion buttons (root/1st/2nd) and a voice-leading view (shows C → G/B → Am as adjacent highlighted shapes), song strip (chords only, uses ctx.player if present), MIDI connect button + status, starter pieces list (Ode to Joy, When the Saints, Amazing Grace lead-sheet, Jingle Bells, Minuet in G, Bach Prelude C) as simple note lists with falling-notes view at slow tempo graded from MIDI. Audio via ctx.audio.noteOn(midi)/noteOff(midi) if present. Tests: key geometry (white 23.5 mm at 1:1, 14.6 mm playable), hit mapping C4/C#4, mode switching, virtual MIDI note highlights.

Lane 5 — audio, listen, recorder, player, songs/record screens (owner: builder-5)

// audio.js
export const audio = { ctx() /*lazy AudioContext*/, resume(), noteOn(midi, {inst:'piano'|'pluck', vel}), noteOff(midi), strum(midis[], {dir}), metronome: { start(bpm, beatsPerBar, {countIn:1, onBeat(beatIdx, barIdx, time)}), stop(), setBpm(b), running }, click(accent) }
// listen.js
export const listen = { start() → Promise (getUserMedia, 48k, analyser), stop(), running,
  onPitch(cb({ hz, midi, cents, clarity }))      // YIN, 2048 window, 20 Hz hop
  onChroma(cb(chroma[12]))                        // from FFT magnitude binned to pitch classes
  verifyChord(name|pitchClasses, { windowMs:600 }) → Promise<{ pass, heard:[pc], missing:[pc], extra:[pc], score }>
  onOnset(cb(timeMs))                             // spectral flux, adaptive threshold
  gradeStrum(expectedOnsetsMs, onsetsMs) → { hits, early, late, missed, score 0..1 }
  changeTimer(fromChord, toChord) → Promise<{ ms }>   // time between verified `from` and verified `to`
}
// pure helpers for tests: yin(float32, sr) → hz ; chromaFrom(magnitudes, sr, N) → chroma ; detectOnsets(frames) 
// recorder.js
export const recorder = { start({ songId }) , stop() → Promise<take{id,songId,at,blob,durationMs}>, list(), play(id), del(id) }
// player.js
export class Player { load(song /* parsed ChordPro */), setInst(inst), setTempoPct(50..100), setLoop(startBar, endBar|null), play({countIn:true}), pause(), stop(), on('bar'|'chord'|'beat'|'line', cb), current() → { bar, beat, chord, next, line } }

Screens: songs.js (mockup D: library list grouped Classics / Popular (chords only) / My imports, with "new chords for you: +1 Em" badges; song view with chords above lyrics, current line/chord glow, now/next chord boxes (reuse chordDiagram from fretboard.js), instrument picker, key/transpose/capo/simplify with graduation nudge, section loop by tapping two bars, tempo 50–100 %, count-in, metronome, strum pattern bar (from strum.js) with live onset dots when listening, "Record this take", "Fingers on the 1:1 neck ▸" link to guitar/uke screen with that chord, paste-import box) and record.js (takes list, play, delete, minutes/day chart). Tests: YIN on 440 Hz sine → 440 ±1; chroma of synthetic C-E-G passes C, fails Am; onsets on synthetic clicks within ±20 ms; player loop/count-in bar sequencing with a fake clock.

Integration (after lanes): Byron's Claude session

Wire main.js imports, run all tests/*.spec.cjs with Playwright (/Users/byronarnao/node_modules/playwright, Chrome at /Applications/Google Chrome.app/Contents/MacOS/Google Chrome, viewport 960×704, DPR 2.25), fix seams, screenshot every screen, deploy to music.arnao.ai via ~/.claude/skills/vercel-deploy/deploy.sh.

Test harness convention

tests/_harness.cjs (lane 1 provides): const { withPage } = require('./_harness.cjs'); withPage(async (page) => { await page.goto(BASE + '#/guitar'); ... }) — serves app/ on a local port with python3 -m http.server or node static server, sets viewport 960×704 @ 2.25, grants mic permission with fake device (--use-fake-device-for-media-stream --use-fake-ui-for-media-stream). Each spec exits non-zero on failure and prints PASS n/n.