feat(jamguide): RoadmapTrack — improv highway with guide tones, VL rails, playhead (task D-01)
Horizontal stations (loop chords), 3rd/7th guide-tone lane (honest 5th fallback for triads), solo-scale label, voice-leading rails (7->3) between stations + wrap-around, playhead + beat grid, lookahead glow on NEXT. Pure component off props + theory.js. Critic PASS. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
vadimwit
@@ -0,0 +1,339 @@
|
|||||||
|
import { NOTES, CHORD_TYPES, guideTones, voiceLeadingPairs, soloScale } from '../lib/theory'
|
||||||
|
|
||||||
|
// ─── RoadmapTrack (D-01) ──────────────────────────────────────────────────────
|
||||||
|
//
|
||||||
|
// The heart of the "Roadmap" Jam Guide concept (docs/design/jam-guide-concept-c.md):
|
||||||
|
// the live loop rendered as a horizontal improv highway. Each KB progression
|
||||||
|
// station carries a chord name + Roman numeral + solo-scale label, a guide-tone
|
||||||
|
// lane (3rd/7th dots), and voice-leading rails drawn *between* adjacent stations
|
||||||
|
// (the 7→3 falls-a-half-step thread). A playhead + beat grid sit underneath; the
|
||||||
|
// station at `position` is "now", the next gets a subtle lookahead glow.
|
||||||
|
//
|
||||||
|
// Pure / presentational: no audio, no data fetching. Everything derives from
|
||||||
|
// props + theory.js. Default-exported. Luthier (D-02) wires it into JamGuide.jsx.
|
||||||
|
//
|
||||||
|
// Prop contract (honoured exactly — other agents build against it):
|
||||||
|
// progression KB progression object { id, name, rn, degrees, qualities, bars, mode, ... }
|
||||||
|
// keyRoot tonic pitch class 0–11
|
||||||
|
// keyMode 'major' | 'minor'
|
||||||
|
// position index of the current station (playhead); -1 if none
|
||||||
|
// bpm optional, for the beat grid; tolerate undefined
|
||||||
|
|
||||||
|
// Pitch class → note name. Sharps via NOTES (the app's canonical spelling, and
|
||||||
|
// what Fretboard.jsx uses); kept to one source so the roadmap matches the neck.
|
||||||
|
const pcName = pc => NOTES[((pc % 12) + 12) % 12]
|
||||||
|
|
||||||
|
// Build the full display chord name from a pitch class + a CHORD_TYPES quality
|
||||||
|
// key (e.g. 7 + 'dom7' → "G7", 2 + 'min7' → "Dm7"). Falls back to a bare major
|
||||||
|
// triad spelling if the quality is unknown, so the panel never renders blank.
|
||||||
|
const chordName = (rootPc, quality) =>
|
||||||
|
pcName(rootPc) + (CHORD_TYPES[quality]?.suffix ?? '')
|
||||||
|
|
||||||
|
// A readable mode word for the SCALE lane: theory.js returns snake_case names
|
||||||
|
// ('phrygian_dominant'); the design wants "G mixolydian".
|
||||||
|
const prettyScale = (rootPc, quality, keyMode) => {
|
||||||
|
const { name } = soloScale(quality, keyMode)
|
||||||
|
return `${pcName(rootPc)} ${name.replace(/_/g, ' ')}`
|
||||||
|
}
|
||||||
|
|
||||||
|
// ─── Layout constants (px in the SVG-free flex layout) ────────────────────────
|
||||||
|
const STATION_MIN_W = 168 // each station's min width; loops longer than the
|
||||||
|
// viewport scroll horizontally (12-bar blues etc.)
|
||||||
|
const RAIL_W = 34 // width of the gap a voice-leading rail bridges
|
||||||
|
const RAIL_H = 40 // rail SVG height
|
||||||
|
|
||||||
|
// Render the small arrow rail between two stations. `pair` is one entry from
|
||||||
|
// voiceLeadingPairs: { from, to, semitones }. We emphasise the half-step motion
|
||||||
|
// — a 0-semitone move is a held common tone ("holds"), ±1 a half-step, ±2 a
|
||||||
|
// whole step. Drawn in accent purple to match the guide-tone dots it connects.
|
||||||
|
function Rail({ pair }) {
|
||||||
|
if (!pair) return null
|
||||||
|
const { from, to, semitones } = pair
|
||||||
|
const held = semitones === 0
|
||||||
|
const dir = semitones < 0 ? 'down' : semitones > 0 ? 'up' : 'hold'
|
||||||
|
const label = held
|
||||||
|
? `${pcName(from)} holds`
|
||||||
|
: `${pcName(from)}→${pcName(to)}` // C→B
|
||||||
|
const motion = held
|
||||||
|
? 'common tone'
|
||||||
|
: `${Math.abs(semitones) === 1 ? '½' : Math.abs(semitones)} step ${dir === 'down' ? 'down' : 'up'}`
|
||||||
|
|
||||||
|
return (
|
||||||
|
<div
|
||||||
|
className="flex shrink-0 flex-col items-center justify-center select-none"
|
||||||
|
style={{ width: RAIL_W }}
|
||||||
|
aria-hidden="true"
|
||||||
|
>
|
||||||
|
<svg width={RAIL_W} height={RAIL_H} viewBox={`0 0 ${RAIL_W} ${RAIL_H}`}>
|
||||||
|
{/* the rail line */}
|
||||||
|
<line
|
||||||
|
x1={2} y1={RAIL_H / 2} x2={RAIL_W - 8} y2={RAIL_H / 2}
|
||||||
|
stroke="#a855f7" strokeWidth={held ? 1.5 : 2}
|
||||||
|
strokeDasharray={held ? '3 3' : undefined}
|
||||||
|
/>
|
||||||
|
{/* arrowhead (omitted for a held common tone) */}
|
||||||
|
{!held && (
|
||||||
|
<path
|
||||||
|
d={`M ${RAIL_W - 8} ${RAIL_H / 2 - 4} L ${RAIL_W - 2} ${RAIL_H / 2} L ${RAIL_W - 8} ${RAIL_H / 2 + 4} Z`}
|
||||||
|
fill="#a855f7"
|
||||||
|
/>
|
||||||
|
)}
|
||||||
|
</svg>
|
||||||
|
<span className="mt-0.5 text-[10px] font-semibold leading-none text-accent">{label}</span>
|
||||||
|
<span className="text-[9px] leading-tight text-gray-400">{motion}</span>
|
||||||
|
</div>
|
||||||
|
)
|
||||||
|
}
|
||||||
|
|
||||||
|
// A single guide-tone dot with its honest label. `kind` is '3rd' / '7th' / '5th'.
|
||||||
|
function GuideDot({ pc, kind, filled }) {
|
||||||
|
return (
|
||||||
|
<div className="flex flex-col items-center gap-0.5">
|
||||||
|
<span
|
||||||
|
className="flex h-6 w-6 items-center justify-center rounded-full text-[10px] font-bold"
|
||||||
|
style={
|
||||||
|
filled
|
||||||
|
? { backgroundColor: '#a855f7', color: '#fff' } // 3rd: solid accent
|
||||||
|
: { border: '2px solid #a855f7', color: '#d8b4fe' } // 7th: hollow accent
|
||||||
|
}
|
||||||
|
>
|
||||||
|
{pcName(pc)}
|
||||||
|
</span>
|
||||||
|
<span className="text-[9px] font-medium uppercase tracking-wide text-gray-400">{kind}</span>
|
||||||
|
</div>
|
||||||
|
)
|
||||||
|
}
|
||||||
|
|
||||||
|
// A single station on the highway.
|
||||||
|
function Station({
|
||||||
|
index, rootPc, quality, rn, scaleLabel, isNow, isNext, width,
|
||||||
|
}) {
|
||||||
|
const g = guideTones(rootPc, quality)
|
||||||
|
// hasSeventh:false → label the fallback honestly ("5th"), never call a 5th a 7th.
|
||||||
|
const seventhKind = g.hasSeventh ? '7th' : '5th'
|
||||||
|
|
||||||
|
// Tier the dimming exactly like ProgressionBanner: "now" is full accent, the
|
||||||
|
// lookahead "next" is a softer glow, everything else recedes — but never below
|
||||||
|
// a legibility floor (AA contrast on bg-panel).
|
||||||
|
const stateClass = isNow
|
||||||
|
? 'border-accent bg-accent/10 ring-2 ring-accent'
|
||||||
|
: isNext
|
||||||
|
? 'border-accent/50 bg-accent/5'
|
||||||
|
: 'border-border bg-surface'
|
||||||
|
const opacity = isNow ? 1 : isNext ? 0.92 : 0.7
|
||||||
|
|
||||||
|
return (
|
||||||
|
<div
|
||||||
|
role="listitem"
|
||||||
|
tabIndex={0}
|
||||||
|
aria-current={isNow ? 'true' : undefined}
|
||||||
|
aria-label={
|
||||||
|
`Station ${index + 1}: ${chordName(rootPc, quality)}, ${rn}, ` +
|
||||||
|
`solo scale ${scaleLabel}, third ${pcName(g.third)}, ` +
|
||||||
|
`${seventhKind} ${pcName(g.seventh)}${isNow ? ', now playing' : ''}${isNext ? ', up next' : ''}`
|
||||||
|
}
|
||||||
|
className={
|
||||||
|
`flex shrink-0 flex-col gap-2 rounded-xl border p-3 outline-none transition ` +
|
||||||
|
`focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-1 ` +
|
||||||
|
`focus-visible:ring-offset-surface ${stateClass}`
|
||||||
|
}
|
||||||
|
style={{ minWidth: width, opacity }}
|
||||||
|
>
|
||||||
|
{/* Header: chord name + Roman numeral, with the lookahead flag */}
|
||||||
|
<div className="flex items-baseline justify-between gap-2">
|
||||||
|
<div className="flex items-baseline gap-2">
|
||||||
|
<span className="text-lg font-bold leading-none text-gray-100">
|
||||||
|
{chordName(rootPc, quality)}
|
||||||
|
</span>
|
||||||
|
<span className="text-xs font-medium text-gray-400">{rn}</span>
|
||||||
|
</div>
|
||||||
|
{isNow && (
|
||||||
|
<span className="rounded bg-accent px-1.5 py-0.5 text-[9px] font-bold uppercase tracking-wider text-white">
|
||||||
|
now
|
||||||
|
</span>
|
||||||
|
)}
|
||||||
|
{isNext && (
|
||||||
|
<span className="rounded border border-accent/60 px-1.5 py-0.5 text-[9px] font-semibold uppercase tracking-wider text-accent">
|
||||||
|
next
|
||||||
|
</span>
|
||||||
|
)}
|
||||||
|
</div>
|
||||||
|
|
||||||
|
{/* SCALE lane: the scale to blow over (muted, per the design) */}
|
||||||
|
<div className="text-xs text-gray-400">
|
||||||
|
<span className="text-[9px] uppercase tracking-widest text-gray-500">solo </span>
|
||||||
|
{scaleLabel}
|
||||||
|
</div>
|
||||||
|
|
||||||
|
{/* TARGET lane: the 3rd & 7th guide-tone dots */}
|
||||||
|
<div className="mt-1 flex items-start gap-4 border-t border-border pt-2">
|
||||||
|
<span className="mt-1 text-[9px] uppercase tracking-widest text-gray-500">aim</span>
|
||||||
|
<GuideDot pc={g.third} kind="3rd" filled />
|
||||||
|
<GuideDot pc={g.seventh} kind={seventhKind} filled={false} />
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
)
|
||||||
|
}
|
||||||
|
|
||||||
|
// The playhead + beat grid under the whole track. Total beats = Σ bars × 4.
|
||||||
|
// The current beat is the start of the active station (coarse, chord-accurate —
|
||||||
|
// matches ProgressionBanner; fine beat interpolation is a later D-02 polish).
|
||||||
|
function BeatGrid({ bars, position, bpm }) {
|
||||||
|
const beatsPerStation = bars.map(b => (b || 1) * 4)
|
||||||
|
const totalBeats = beatsPerStation.reduce((s, n) => s + n, 0)
|
||||||
|
// first beat index of each station
|
||||||
|
const stationStart = []
|
||||||
|
let acc = 0
|
||||||
|
for (const n of beatsPerStation) { stationStart.push(acc); acc += n }
|
||||||
|
const nowBeat = position >= 0 && position < stationStart.length ? stationStart[position] : -1
|
||||||
|
const pct = nowBeat >= 0 && totalBeats > 0 ? (nowBeat + 0.5) / totalBeats : 0
|
||||||
|
|
||||||
|
return (
|
||||||
|
<div className="mt-3">
|
||||||
|
{/* playhead track */}
|
||||||
|
<div
|
||||||
|
className="relative h-1.5 w-full rounded-full bg-border"
|
||||||
|
role="progressbar"
|
||||||
|
aria-valuemin={0}
|
||||||
|
aria-valuemax={totalBeats}
|
||||||
|
aria-valuenow={Math.max(0, nowBeat)}
|
||||||
|
aria-valuetext={
|
||||||
|
nowBeat >= 0 ? `Beat ${nowBeat + 1} of ${totalBeats}` : 'Loop not playing'
|
||||||
|
}
|
||||||
|
>
|
||||||
|
<div
|
||||||
|
className="absolute top-0 h-1.5 rounded-full bg-accent/60"
|
||||||
|
style={{ width: `${Math.max(0, pct * 100)}%` }}
|
||||||
|
/>
|
||||||
|
{nowBeat >= 0 && (
|
||||||
|
<div
|
||||||
|
className="absolute -top-1 h-3.5 w-3.5 -translate-x-1/2 rounded-full border-2 border-surface bg-accent"
|
||||||
|
style={{ left: `${pct * 100}%` }}
|
||||||
|
/>
|
||||||
|
)}
|
||||||
|
</div>
|
||||||
|
|
||||||
|
{/* beat cells */}
|
||||||
|
<div className="mt-1 flex w-full gap-px" aria-hidden="true">
|
||||||
|
{Array.from({ length: totalBeats }, (_, i) => {
|
||||||
|
const isNow = i === nowBeat
|
||||||
|
// downbeat (beat 1 of a bar) gets a brighter tick
|
||||||
|
const isDownbeat = i % 4 === 0
|
||||||
|
return (
|
||||||
|
<div
|
||||||
|
key={i}
|
||||||
|
className="h-2 flex-1 rounded-sm"
|
||||||
|
style={{
|
||||||
|
backgroundColor: isNow ? '#a855f7' : isDownbeat ? '#2a2a2a' : '#1a1a1a',
|
||||||
|
opacity: isNow ? 1 : isDownbeat ? 1 : 0.7,
|
||||||
|
}}
|
||||||
|
/>
|
||||||
|
)
|
||||||
|
})}
|
||||||
|
</div>
|
||||||
|
|
||||||
|
{bpm ? (
|
||||||
|
<p className="mt-1 text-right text-[10px] text-gray-500">~{Math.round(bpm)} BPM</p>
|
||||||
|
) : null}
|
||||||
|
</div>
|
||||||
|
)
|
||||||
|
}
|
||||||
|
|
||||||
|
export default function RoadmapTrack({
|
||||||
|
progression,
|
||||||
|
keyRoot = 0,
|
||||||
|
keyMode = 'major',
|
||||||
|
position = -1,
|
||||||
|
bpm,
|
||||||
|
}) {
|
||||||
|
// Tolerate a missing / malformed progression — the panel is never empty-crashed.
|
||||||
|
if (!progression || !Array.isArray(progression.degrees) || progression.degrees.length === 0) {
|
||||||
|
return (
|
||||||
|
<div className="rounded-2xl border border-border bg-panel p-4 text-sm text-gray-500">
|
||||||
|
No loop to map yet — play a progression.
|
||||||
|
</div>
|
||||||
|
)
|
||||||
|
}
|
||||||
|
|
||||||
|
const { degrees, qualities = [], rn = [], bars = [], name, id } = progression
|
||||||
|
const n = degrees.length
|
||||||
|
|
||||||
|
// Resolve each station to an absolute chord in the current key.
|
||||||
|
const stations = degrees.map((deg, i) => {
|
||||||
|
const rootPc = (((keyRoot + deg) % 12) + 12) % 12
|
||||||
|
const quality = qualities[i] ?? 'maj'
|
||||||
|
return {
|
||||||
|
rootPc,
|
||||||
|
quality,
|
||||||
|
rn: rn[i] ?? '',
|
||||||
|
scaleLabel: prettyScale(rootPc, quality, keyMode),
|
||||||
|
bars: bars[i] ?? 1,
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
// Voice-leading rails between adjacent stations, plus a wrap-around rail from
|
||||||
|
// the last station back to the first (the loop is a wheel — a nice touch the
|
||||||
|
// design calls for: "B holds → next loop"). Index i = rail leaving station i.
|
||||||
|
const rails = stations.map((s, i) => {
|
||||||
|
const next = stations[(i + 1) % n]
|
||||||
|
return voiceLeadingPairs(
|
||||||
|
{ root: s.rootPc, quality: s.quality },
|
||||||
|
{ root: next.rootPc, quality: next.quality },
|
||||||
|
)[0] ?? null // the headline rail is the 7→3 (voiceLeadingPairs lists 7th first)
|
||||||
|
})
|
||||||
|
|
||||||
|
const nextPos = position >= 0 ? (position + 1) % n : -1
|
||||||
|
|
||||||
|
return (
|
||||||
|
<section
|
||||||
|
className="rounded-2xl border border-border bg-panel p-4"
|
||||||
|
aria-label={`Roadmap for ${name ?? id ?? 'loop'}`}
|
||||||
|
>
|
||||||
|
{/* Header strip: loop name + station chord summary */}
|
||||||
|
<header className="mb-3 flex flex-wrap items-baseline gap-x-3 gap-y-1">
|
||||||
|
<h3 className="text-sm font-semibold uppercase tracking-widest text-gray-300">
|
||||||
|
{name ?? 'Loop'}
|
||||||
|
</h3>
|
||||||
|
<span className="text-xs text-gray-500">
|
||||||
|
{stations.map(s => chordName(s.rootPc, s.quality)).join(' → ')}
|
||||||
|
</span>
|
||||||
|
</header>
|
||||||
|
|
||||||
|
{/* The highway: stations interleaved with voice-leading rails. Scrolls
|
||||||
|
horizontally when the loop is longer than the viewport. */}
|
||||||
|
<div className="overflow-x-auto pb-1">
|
||||||
|
<div role="list" aria-label="Loop stations" className="flex min-w-min items-stretch">
|
||||||
|
{stations.map((s, i) => (
|
||||||
|
<div key={i} className="flex items-center">
|
||||||
|
<Station
|
||||||
|
index={i}
|
||||||
|
rootPc={s.rootPc}
|
||||||
|
quality={s.quality}
|
||||||
|
rn={s.rn}
|
||||||
|
scaleLabel={s.scaleLabel}
|
||||||
|
isNow={i === position}
|
||||||
|
isNext={i === nextPos}
|
||||||
|
width={STATION_MIN_W}
|
||||||
|
/>
|
||||||
|
{/* rail to the next station (inter-station rails only; the
|
||||||
|
wrap-around rail is drawn separately after the last station) */}
|
||||||
|
{i < n - 1 && <Rail pair={rails[i]} />}
|
||||||
|
</div>
|
||||||
|
))}
|
||||||
|
{/* wrap-around rail back to station 1, rendered after the last station */}
|
||||||
|
{n > 1 && (
|
||||||
|
<div className="flex items-center" aria-hidden="true">
|
||||||
|
<Rail pair={rails[n - 1]} />
|
||||||
|
<span className="ml-0.5 text-[9px] uppercase tracking-wider text-gray-500">
|
||||||
|
loop
|
||||||
|
</span>
|
||||||
|
</div>
|
||||||
|
)}
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
{/* Playhead + beat grid */}
|
||||||
|
<BeatGrid bars={stations.map(s => s.bars)} position={position} bpm={bpm} />
|
||||||
|
</section>
|
||||||
|
)
|
||||||
|
}
|
||||||
Reference in New Issue
Block a user