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)
calib.pxPerMm() at draw time. Canvas is sized to devicePixelRatio.main.js exports bus (new EventTarget()), state (plain object), and emit(name, detail). Screens are modules exporting mount(el, ctx) and unmount(). ctx = { state, bus, emit, calib, audio, listen, store }.#/home #/calibrate #/guitar #/uke #/piano #/songs #/songs/<id> #/record.ps.calib, ps.instruments, ps.progress, ps.settings. Recordings in IndexedDB db ps, store takes.C, Am, G7, Fmaj7, Dsus4, C/E (slash = bass note), F#m, Bb. Use #/b ASCII in data; render ♯/♭.0..11 with C=0. MIDI note numbers for pitches.css/app.css as custom properties: --bg --panel --line --text --dim --acc(#ff9d3c) --ok(#3ddc84) --blue(#5aa9ff) --red(#ff5a5a). Dark only. Font: system sans. Match the mockups at https://practice-plan.arnao.ai/mockups/ (screens A–E) — same layout and labels.// 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.
// 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.
// 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.
// 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.
// 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.
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.
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.