JamBuddy/docs/design/one-screen.md

One Screen — the jam dashboard (task D-50)

Thesis: the page stops being a tall stack of full-width bands and becomes a viewport-fitting jam dashboard: a full-width slim loop strip (the banner minus its big now-playing chord), then LEFT (~744px) the compact instrument view, the licks strip, and a new loop-relative Related progressions card; RIGHT (~500px) the suggested-voicings rail — the design's ONE justified internal scroller (§4). The dashboard is a self-contained unit designed to fit 100vh at 1280×900; a JAM VIEW toggle in the controls bar (§1.1) locks the page to exactly that unit (and goes browser-fullscreen, best-effort) while playing. In normal mode everything that is learning or behind-the-scenes (LoopStation, Debug, Drum, Tuner, KnowledgeDock) stays below the dashboard on the ordinary page scroll; in jam view it is hidden.

User directive (2026-07-11, verbatim): "the chord view and the chord loop incl the instrument below is too big, it takes up too much space, i want you to reconsider the positioning as this main view doesnt really add value: seeing the big chord 'now playing' in big is also unnecessary as you already see that one in the chords (loop) part. the suggested progressions on the right are also almost useless. they are nice but we need to rethink them in the form of SUGGESTED VOICINGS and the progressions we add relating to the loop. i'd like to have the suggested voicings on the right side of the screen (the jam guide). … i wanna see the chords, the loop, the voicings, the progressions, the licks all on one screen, everything you need to follow the jam correctly"

Refinement (2026-07-11, verbatim): "it can still have a scroll down, but the main concept needs to be in one screen: potentially we add a fullscreen button so we can just show that when we are playing a jam. so that it fits the entire screen, everything that is learning and behind the scenes etc you can keep below/scrollable but we need one main view for live jams where we see everything at once (relating to the jam and the voicings and the licks and the chords and the loop)" — the 100vh fit is a hard design constraint for the dashboard, not an aspiration; the fullscreen button is in scope (L-50 commit 3, §6.1); internal wrap/scroll inside a panel is a last resort and every instance below is justified.

Supersedes integrated-glance.md §1's full-width-band placement (the user tested it and asked for the right column). That doc's verified geometry stays the arithmetic source here: guitar cell ~93px, piano cells 160/284px, worst piano gallery ~1,178px of cells, licks thumb card ~165px (in a 220px strip slot), cell line heights ~140px guitar / ~125–130px piano. Standing principles (user memory): scroll > click; nothing shown twice; ONE global instrument selector; the playhead highlights, never hides.

Decision authority: per the sprint header (no user gate), Muse picks the strongest option and records rejected alternatives (§9).

---

0. What exists today (read from the code)

App.jsx mount order: ProgressionBanner (~608) → instrument row (~617–629: Fretboard/BassFretboard/Piano at 70% + ProgressionSuggestions at 30%) → JamGuide full-width band (~635: GlanceRail all-expanded rows + LicksStrip) → LoopStation → Debug/Drum/Tuner collapsibles → KnowledgeDock last. The band starts ≈570px down at 1280×900 — voicings never share the screen with the instrument view, and the licks strip sits another rail-height below that. The banner burns its right 30% on a text-6xl "Now Playing" chord that duplicates both the enlarged last history chip and the highlighted loop chip. The directive kills all of that.

---

1. The grid

Assumed usable content box at a 1280×900 window: ~1,256 × ~836px (Electron title bar ~32px eats into the 900; App's p-3 eats 24px each axis — heights below are estimates, cell geometry is verified).

┌──────────────────────────────────────────────────────────────┐  ─┐
│ header (~52)                                                  │   │
│ controls bar — instrument · key lock · ⛶ JAM VIEW (~52)       │   │
│ SLIM LOOP STRIP — key · history · ♻ loop chips (~76)          │   │ the
├───────────────────────────────────────┬──────────────────────┤   │ dashboard
│ LEFT  ~744px (flex-1)                 │ RIGHT 500px,          │   │ = 100vh
│                                       │ own scroll (§4)       │   │ in jam
│  compact instrument view   (~240)     │                       │   │ view
│  licks strip               (~190)     │  SUGGESTED VOICINGS   │   │
│  related progressions      (~200)     │  rail — GlanceRail /  │   │
│                                       │  BassGuideRows rows   │   │
├───────────────────────────────────────┴──────────────────────┤  ─┘
│ LoopStation · Behind the Scenes · Rhythm · Tuner · Knowledge  │  normal mode
│ (the learning / behind-the-scenes area — page scroll)         │  only; hidden
└──────────────────────────────────────────────────────────────┘  in JAM VIEW

• The slim strip stays full width (not inside the left column): it is the status line for the whole dashboard — the rail's playhead and the strip's active loop chip are the same "now", and a full-width one-liner costs only ~76px. (Putting it inside the left column would buy the rail ~88px of first-paint height; the rail is internally scrollable anyway, and a ~450px-content strip floating in a 744px column looks broken. Not worth it.)
• Grid: flex gap-3 items-start → left flex-1 min-w-0, right w-[500px] shrink-0, active at xl: (≥1280); below that the columns stack (§7). 500px is the top of the licensed 420–520 range because piano cells need it (§4): at 500 the row interior is ~456px, which fits a 284px two-octave cell plus a 160px one-octave cell per line (by ~4px — D-51 hardens the margin, §4); at 420 every two-octave cell rides alone.
• The rail is height-bounded: xl:max-h-[calc(100vh-1.5rem)] xl:overflow-y-auto — and NOT sticky. (sticky top-3 here would be inert: inside the flex row the rail is the tallest item, so its containing block equals its own height and there is zero travel to pin against — specifying it would be a lie in class form.) What the bound actually buys, honestly: the rail is the one unbounded surface (§4 math — a jazz piano loop is ~3,000px of rows). (a) Unbounded, it stretches the document to ~3,000px+, pushing the below-grid region (LoopStation, the whole learning area) thousands of pixels down instead of one flick below the dashboard. (b) The bound is exactly what jam view swaps to h-full — an unbounded rail can never fit h-screen (§1.1). The rail's depth scrolls within its column; the left column stays whole; at rest the rail shows ~644px (the grid height). D-40 Rejected E (internal scroller) was rejected for the full-width band, where it capped visible rows below 4 and nested a scrollbar inside the page's only axis; in a two-column dashboard, bounding the one unbounded column is what makes the dashboard a fixed-height unit — the rejection does not carry over. No auto-scroll in this sprint (§4).

Vertical budget, normal mode at rest: 836 − 52 (header) − 52 (controls) − 88 (strip + gap) ≈ 644px for the grid. Left stack ≈ 240 + 190 + ~200 + 24 gaps ≈ 654px — everything on screen except the last ~10–20px of the related progressions card at exactly 900px window height; a micro-flick shows it. In normal mode that residue is acceptable (the page scrolls anyway); in jam view it is not — §1.1 makes the fit exact by construction, with the related card as the left column's flex absorber.

1.1 Jam view — the one-screen lock + fullscreen toggle

The refinement's "fullscreen button". Mechanism chosen: one button, two layers on one state.

• Layer 1 — CSS jam view (the guarantee). App gains a jamView boolean (pure UI-state — nowhere near the audio callbacks/refs). When true:
  • the page root becomes h-screen overflow-hidden flex flex-col (normal mode: today's min-h-screen flow);
  • everything below the dashboard is not rendered — LoopStation, Behind the Scenes, Rhythm Analyser, Tuner, KnowledgeDock (conditional mount, not hidden, so collapsed-state chrome can't leak height). Header, controls bar, strip, grid remain — Stop/Start, the instrument selector, and the key lock are jam-relevant chrome;
  • the grid gets flex-1 min-h-0; the rail wrapper swaps its normal-mode xl:max-h-[calc(100vh-1.5rem)] bound for h-full overflow-y-auto (the column IS the viewport remainder, so the viewport-calc bound gives way to the exact column height);
  • the left column becomes flex flex-col min-h-0: instrument view and licks strip fixed-height, the related progressions card flex-1 min-h-0 overflow-y-auto — the one flex absorber that soaks up the ±20px between window sizes. Internal scroll here is the licensed last resort and only engages below ~950px-tall windowed viewports (numbers below).
• Layer 2 — browser fullscreen (the enhancement, best-effort). The same toggle calls document.documentElement.requestFullscreen() on enter and document.exitFullscreen() on exit. Both return Promises — a bare try/catch does not swallow the rejection; the calls must be .catch(() => {}) (or awaited inside try/catch). Electron grants it (plain renderer, no IPC needed); if a browser build ever refuses, jam view still works at layer 1. Fullscreen reclaims the ~32px title bar (and any taskbar), which is exactly what turns "fits minus 20px" into "fits clean" at 900-high screens.
• The button lives at the right end of the controls bar (the global, always-visible chrome — same reasoning as the instrument selector): ⛶ Jam view / ✕ Exit , aria-pressed, min-32px target, focus-visible:ring-2 ring-accent, tokens only.
• Exit paths, all restoring normal flow: the button; Escape (a keydown listener active only while jamView — needed because layer 1 can exist without layer 2); and the native fullscreen Esc, synced via a fullscreenchange listener (leaving fullscreen by any means switches jamView off — one state, never half-exited). Entering does NOT auto-start listening; leaving does NOT stop it — the toggle is layout-only.

Jam-view budget (the hard numbers). Grid height = viewport − p-3 (24) − header 52 − controls 52 − strip + gap 88:

Viewport	Grid (= rail height)	Left: fixed 454 (instrument 240 + licks 190 + gaps) → related card gets	Verdict
1280×900 window (layer 1 only, content ~836)	644px	~190px → heading + ~2.8 of 3 entries	fits; the card's last entry may shave ~20px — its internal scroll absorbs it
1280×900 screen, true fullscreen (content ~876)	684px	~230px → 3 entries fully clear, ~20px spare	fits clean — the ~20px story is gone
1280×960+ screen, true fullscreen (content ≥936)	≥744px	≥290px → up to 5 entries	fits with room

The rail's depth still exceeds any of these for piano loops (§4 table — a 4-chord jazz loop is ~2,600–3,000px of rows). That is the one place "see everything at once" and "every voicing, all levels, zero clicks" (D-30) mathematically collide; the cell strategy compresses first (recommended cell leads; the 284+160 pair-fit halves mixed-station heights, §4) and the remainder falls to the rail's contained scroll — the justified internal scroller. All four bounded surfaces (strip, instrument, licks, progressions) fit whole; guitar and bass rails fit ~2.5–3 of 4 rows with the "now" row highlighted wherever it sits.

1.2 The slim loop strip — banner inventory

What ProgressionBanner renders today, and its disposition:

Banner element today	Disposition
Key chip (root text-2xl accent + mode + confidence %)	Survives — leftmost, unchanged
Chord history (last 8, age-faded, tap → ChordDetailModal; current chip enlarged text-3xl + amber rn + pop-in animation)	Survives, capped to last 5 — the enlarged current chip IS the now-playing display now; the pop-in animation moves with it
Loop row (♻ + chips, chord + rn, active chip accent-glow via findLoopPosition, "→ loop" tail)	Survives, promoted onto the same row as key + history (divider between)
hidden lg:block divider + right 30% column: "NOW PLAYING" label, text-6xl amber chord, rn, "tap for voicings"	GONE. The user's words: the loop chips already carry it. The tap-for-voicings affordance is not lost — every chip already opens ChordDetailModal, and the rail shows the loop's voicings permanently
Empty states ("Detecting key…", "Start listening…", "Play a chord")	First two survive; "Play a chord" dies with its column

One row: key chip (~90px) + 5 history chips (~230px) + divider + up to 8 loop chips (~320px) + tail ≈ ~720px — fits 1,256 with room; 12-chord loops (12-bar blues) wrap the loop chips to a second line (strip ~104px, still fine). Strip chrome trim (part of the slimming): p-4 → p-2 and drop the history wrapper's pb-1 — the enlarged current chip (text-3xl + rn + chip padding) is ~58px tall on its own, so with p-4 the strip lands at ~92–96px; the trim is what makes the ~76px figure true. Goes in L-50 commit 1 with the column removal (§6.1). Duplication audit: the current chord appears twice (last history chip + active loop chip) — pre-existing, and the user's directive explicitly endorses the loop chip as the "now"; the big third copy is what dies.

---

2. Compact instrument view — the mechanism

Chosen: a compact prop on Fretboard / Piano / BassFretboard = trimmed card chrome + a natural-width cap on the SVG. No fret reduction, no transform scaling.

• Natural-width cap: each SVG keeps width:100% but gains max-width: <its viewBox width>px (Fretboard 674px, Piano 562px), i.e. it never renders above scale 1.0. In the 744px left column (≈718px card interior with the compact p-3) the fretboard sits at its designed 1.0 scale → SVG height 186px (today at 70% of 1,256 it renders at ~1.23 scale ≈ 229px + fat chrome ≈ 320px card). Piano: 150px SVG.
• Trimmed chrome: p-6 → p-3, heading mb-4 → mb-2, and the legend row (chord tone / pentatonic / scale dots) merges onto the heading line (right-aligned) instead of a separate mt-3 row. Card totals: fretboard ≈ 240px (was ~320), piano ≈ 205px.
• Legibility, honestly: at scale 1.0 the fretboard is at its designed size — 20px note dots, 9px note labels, 10px string/fret labels, exactly what ChordDiagram-era eyes were tuned on; nothing shrinks below today's rendering (today it renders larger than designed, which is part of "too big"). The compact card is smaller because the chrome and the over-scale go, not because the notes do. Below ~700px column width the SVG scales down with the column; at 0.9 scale (≈606px) labels are ~8px — the floor I'd defend. The narrow plan (§7) gives the view the full window width anyway, so the sub-1.0 zone only exists between ~1280 and ~1140px windows if the grid breakpoint were lower — hence xl: for the grid, not lg:.
• Rejected mechanisms: fewer frets (0–7) kills position playing above the 7th fret — soloists live there; CSS transform: scale() blurs text and shrinks hit targets — dishonest compactness; hard height cap with letterboxing wastes the saved space as empty gutters.

---

3. What's removed / moved (full inventory)

Surface	Disposition
Big "Now Playing" chord (banner right 30% + divider)	Removed (§1.2)
ProgressionSuggestions	Unmounted; file kept in place (EducationPanel/RoadmapTrack precedent — joins the retire-then-delete backlog item). Its job splits in two per the directive: "what to play on these chords" → the voicings rail; "where these changes can go" → RelatedProgressions (§5). Its generic genre/mood table and circle-of-fifths padding retire with it
The 70/30 instrument row	Dissolved — the instrument view becomes the left column's first block; the 30% slot's replacement is the rail column
JamGuide band (rail + licks, full width)	Recomposed — JamGuide stops rendering a band and renders the grid's jam surfaces: rail into the right column, LicksStrip + a related-progressions slot into the left (§6, component boundary)
LicksStrip	Stays module-local in JamGuide.jsx — no file move. It renders from JamGuide's match/context memos (activeStyle, contextStation); extracting it to its own file buys nothing and forces prop plumbing for the token-boundary context sort. It just mounts in the left column now
LoopStation	Below the grid, first — and hidden in jam view. Recorded call: the user's enumeration of the live-jam view is "the jam and the voicings and the licks and the chords and the loop", where "the loop" is the chord loop (the strip's ♻ chips), not the audio looper. LoopStation is a performance tool, but it is not on the list — it goes below with the learning surfaces, first in line because it feeds the detected loop. If the user misses it mid-jam, admitting it into jam view is a one-line conditional — the reversal path is cheap and noted in §9
Behind the Scenes / Rhythm Analyser / Tuner collapsibles	Below LoopStation, unchanged
KnowledgeDock	Last, unchanged — browse & study stays below the fold
ChordDetailModal, AudioCapture, all src/lib/** audio/theory	Zero changes

In normal mode everything below the grid remains exactly what the refinement asks for — the learning / behind-the-scenes area on the ordinary page scroll ("everything that is learning and behind the scenes etc you can keep below/scrollable"). In jam view this whole region is hidden (§1.1) — the dashboard is the entire page.

---

4. The rail at column width (~500px shell, ~456px row interior)

Row interior arithmetic: 500 − rail section p-3 + border (~26) − row p-2 + border (~18) ≈ 456px for header + cells. The inherited 93/160/284 figures are already box values — integrated-glance's own verified sums prove it (4×284 + gaps + chrome ≈ 1,178 with no extra per-cell padding), so nothing gets padding added on top below. Cell strategy: recommended-first, gallery wrapped below — all cells always rendered, zero clicks (D-30's "all at once" directive stands; only the geometry adapts).

• The recommended cell leads and reads as the answer. The station's own voicing (guitar: KB play shape badged "play"; piano: the authored/threaded voicing with its honest label) keeps its accent-bordered figure and is always the first cell — at column width it is frequently alone on line one, which makes prominence free. D-51 may add nothing more than a slightly stronger figure treatment (accent/60 border → accent) — no size difference, no new colour.
• Guitar: cells ~93px (box) → 4 per line (4×93 + 3×8 gaps = 396 ≤ 456 — fits with ~60px to spare, not borderline; a 5th cell at 497 does not). Typical station = play cell + 3–6 placeable shapes = 4–7 cells → 1–2 cell lines (~140px each). Header content (chord + rn + now/next + solo label + aim dots + transition chip ≈ 540px of inline content) wraps to 2 lines ≈ 50px — fine, it already flex-wraps. Row ≈ 206–350px.
• Piano: one-octave cells ~160px (box) → 2 per line (328 ≤ 456); two-octave cells ~284px (box) → alone or, critically, paired with a one-octave cell: 284 + 160 + 8 = 452 ≤ 456 — the mixed pair FITS today, by ~4px. That 4px is real but fragile (a longer label, a scrollbar gutter, a browser rounding step could break it), so D-51's cell padding/gap shave is margin-hardening for an already-passing fit, not a rescue — the pairing is the difference between 5 and 3 cell lines on mixed stations. Worst station (root above D with a true 7th — all five cells two-octave, per the D-40 corrected math; 2×284 + 8 = 576 > 456 so they never pair with each other): 5 cell lines ≈ 650 + header ≈ ~700px per row. Best (roots C–D / triads): 3 lines ≈ ~490px.
• Bass: BassGuideRows text rows (~70px) or BassPatternCard rows — narrow by construction; the column fits them with no adaptation beyond wrap, which it inherits.
• Wrap, never horizontal scroll — unchanged invariant. The only permitted horizontal scroller stays VoicingBrowser's per-cell guard around MiniPiano thumbs on sub-320px pathologies.

The honest vertical budget

Scenario	Full rail height	Visible: normal rest (~644px) / jam view fullscreen (~684px)
4-chord loop, guitar	≈ 4×~275 avg + chrome ≈ ~1,150px	~2.3 / ~2.5 rows
4-chord loop, piano (jazz flagship, mostly worst-case rows)	≈ ~2,600–3,000px	~1 / ~1.1 rows
8–12 chord loop (12-bar)	guitar ~2,300 / piano ~5,000+	scroll; the strip's loop chips always carry the position

What "one screen" honestly means: all five surfaces are simultaneously present at 1280×900 (whole, in jam view — §1.1) — but the rail's depth is a scroll, contained in its column: it is the one panel whose content is unbounded by construction (every voicing of every loop chord, D-30's "all at once"), so it is the design's justified last-resort internal scroller; the cell strategy above compresses first. A 4-chord guitar loop is ~1.4 rail-screenfuls; a 4-chord jazz piano loop is ~3.5. The playhead highlight travels whether or not the row is in the scroller's window; the strip up top always shows where you are. No auto-scroll in D-51 — same reasoning as D-40 §4, plus: contained auto-follow is now technically safe (the scroller is no longer the document, so it can't yank the page), so I flag it to Maestro as an optional 1-point follow-up after the user has felt the manual version — auto-motion during a jam is exactly the "it changes while I play" complaint in a new hat, so it must be user-pulled, not designer-pushed.

Flag (not in scope): a root-aligned MiniPiano crop would turn most two-octave piano cells into one-octave ones (~160px), roughly halving piano rail heights. It reopens D-24's C-aligned-crop decision and MiniPiano is frozen this sprint — Maestro may file it as a D-52 candidate.

---

5. Related progressions — the spec for L-51

What it is: 3–5 KB progressions genuinely related to the detected loop, replacing ProgressionSuggestions' generic genre table. KB-sourced only (kb[style].progressions — id, name, rn, degrees, qualities, level, songs), loop-relative by construction.

Ranking (computable today, no new theory)

Inputs: detectedProgression (chord-name strings), the KB registry, and matchLoopToProgression's result. Reuse src/lib/match.js machinery — loopToDegrees and canonicalDegrees are currently module-private and must become additive exports (L-51 lock addition; no behaviour change), next to the already-exported matchLoopToProgression/buildLoopIndex.

1. loopDeg = loopToDegrees(loop); bail to empty state if null. loopCanon = canonicalDegrees(loopDeg). match = matchLoopToProgression(…) (the component computes its own — see §6's parallelism note).

2. Build the loop's transition set T(loop): for each i (wrap-around), the triple (Δ = (deg[i+1]−deg[i]) mod 12, q[i], q[i+1]) with qualities from the chord-name suffixes (unmappable suffix → wildcard: match on Δ alone). Same for every KB progression from its degrees/qualities.

   Collapse first — mandatory. The live detectedProgression is a collapsed form (detection never commits the same chord twice in a row), while KB degrees are raw, bar-per-bar — blues-12bar is [0,0,0,0,5,5,0,0,7,5,0,7]. Compared raw, the +100 same-canonical-shape term would NEVER fire for the ~10 collapse-affected KB progressions — silently killing the flagship "this 12-bar IS their 12-bar" relation (it degrades, never misfires, which is why it would go unnoticed). So: before canonicalDegrees(p.degrees) AND before building T(p), collapse consecutive equal (degree, quality) pairs in p (also with the wrap-around pair). This additionally removes the harmless-but-deflating Δ=0 self-transitions from T(p). Alternative once D-62's fix (a) lands collapsed-form indexing in match.js: consume that shared collapsed form instead of collapsing locally — coordinate via the §9 match.js shared-file note.

3. Score every KB progression p with p.id !== match.id:

   • +100 if canonicalDegrees(p.degrees) === loopCanon — the same changes in another style/length ("this turnaround IS jazz's I–vi–ii–V");
   • +40 if p.style === match.style (0 when nothing matched — the ranking still works loop-relative off the raw degrees);
   • +12 per shared transition (distinct triples in T(loop) ∩ T(p)), capped at 36 — this is what finds "shares the ii→V" honestly;
   • + up to 16 for rebased degree-set overlap (Jaccard × 16);
   • −1 per chord of length difference (tie-break toward similar-size loops).

4. Floor 24 (at least a shared transition + some overlap, or same-style + substance) — never pad with junk; fewer honest entries beat five stretches. Sort desc (stable by style, id), take max 5; the dashboard budget guarantees 3 visible (§1.1) — the card is the left column's flex absorber, so entries 4–5 show on tall viewports and scroll within the card on tight ones.

Per-entry render (~56px each)

• Line 1: name (gray-100 semibold) · style label (gray-500) · level chip (ExplorePanel's LevelBadge language — untagged counts foundation) · annotation (gray-500, [10px]): same changes when the +100 fired, else shares {rn_a}→{rn_b} naming p's rn at the top shared transition, else same style.
• Line 2: the chord chain realized in the current key — rootPc = (keyRoot + degree) mod 12 + CHORD_TYPES[quality].suffix (the stationVoicings formula), rendered as tappable chips with rn beneath (banner-chip visual language, smaller); 12-bar chains truncate to the first 8 + "…". Tap a chord → onChordClick → ChordDetailModal — the existing per-chord pattern (ExploreSection does exactly this); no new modal, no dock deep-link API invented for v1.

Empty states (honest)

• No loop detected → one-liner (~40px, dashed border): "Loop a progression — related changes from the songbook land here."
• Loop but nothing ≥ floor → "Nothing in the songbook genuinely relates to this loop yet." (never pad).
• Loop unmatched but candidates score (shape/transition terms only) → render normally; the annotation still explains why each entry is there.

---

6. Component boundary + migration order (green at every commit)

Boundary call: JamGuide (default export) is promoted from "band" to jam-grid owner: it renders the two-column flex region and takes two JSX slot props from App — mainView (the instrument view — App keeps choosing Fretboard/BassFretboard/Piano; JamGuide never imports them) and relatedSlot (RelatedProgressions, mounted by App). Left column = mainView + LicksStrip + relatedSlot; right column = the height-bounded scroller wrapping GlanceRail / BassGuideRows / the heard-live fallback. Rationale: the match / stationVoicings / canonicalPos / focus machinery stays in ONE component with no context and no logic lifted into App (the 🚨 App.jsx contract); the slots keep App as pure mounts. RelatedProgressions computes its own match (memoized on the loop key — matchLoopToProgression over a module-level index is trivially cheap); this small duplicate computation is what makes L-51's files disjoint from D-51's (they can run in parallel) and keeps the component pure/prop-driven: { loop, keyInfo, onChordClick }.

Sequenced: L-50 → (D-51 ‖ L-51) → C-50. Critic gates each.

6.1 L-50 (Luthier) — the dashboard restructure

Files (re-lock at promotion): src/App.jsx (layout/mounts only, 🚨 audio contract grep-gated), src/components/ProgressionBanner.jsx, src/components/JamGuide.jsx, src/components/Fretboard.jsx, src/components/Piano.jsx, src/components/BassFretboard.jsx (compact prop — mechanical chrome trim + max-width cap per §2; D-51 polishes visuals if needed). Not touched: ProgressionSuggestions.jsx (unmounted, not edited), GlanceRail.jsx, VoicingBrowser.jsx, all src/lib/**.

1. Commit 1 — slim strip. ProgressionBanner: delete the right 30% column + divider + its currentRN/big-chord code path; merge key + history + loop onto one row; HISTORY_SHOWN 8 → 5; chrome trim p-4 → p-2 + drop the history wrapper's pb-1 (what makes the ~76px strip true, §1.2). Standalone green.
2. Commit 2 — the grid (atomic). These land together or the page has a hole: App replaces the 70/30 row + band with the xl: two-column grid; ProgressionSuggestions unmounted (import + mount deleted); JamGuide gains mainView/relatedSlot props and renders left/right columns, rail wrapped in the height-bounded scroller (xl:max-h-[calc(100vh-1.5rem)] xl:overflow-y-auto — no sticky, §1); instrument views gain compact and App passes it; App passes relatedSlot={null} (slot renders nothing until L-51). Green; contract grep clean.
3. Commit 3 — jam view (§1.1). App: jamView UI-state + the controls-bar ⛶ Jam view toggle button; page root h-screen overflow-hidden flex flex-col + grid flex-1 min-h-0 + left-column flex layout while active; below-dashboard region conditionally unmounted; JamGuide's rail wrapper accepts a fill (or jamView) prop switching the max-h bound → h-full overflow-y-auto; best-effort requestFullscreen()/exitFullscreen() with .catch(() => {}) (they return Promises — a bare try/catch does not swallow the rejection) + fullscreenchange sync + Escape keydown (active only while jamView). 🚨 Pure layout/UI-state — zero contact with audio callbacks, refs, or AudioCapture props; the toggle never starts/stops listening. Standalone green on top of commit 2.

6.2 D-51 (Muse) — rail at column width

Files: src/components/GlanceRail.jsx, src/components/VoicingBrowser.jsx (dense-path spacing only). Recommended-cell prominence; cell padding/gap shave as margin-hardening for the ~4px-tight 284+160 piano pair fit (§4 — it passes today; the shave makes it robust to label length / scrollbar gutters / rounding); header wrap tuning at ~456px; verify wrap-never-scroll, playhead highlight, AA contrast + focus rings; eyeball 1280×900, 1440×900, ~640px stacked; recompute §4's table against the built thing. No auto-scroll introduced.

6.3 L-51 (Luthier) — RelatedProgressions

Files: src/components/RelatedProgressions.jsx (new), src/lib/match.js (additive exports only: loopToDegrees, canonicalDegrees — flag the shared-file lock to Maestro at promotion), src/App.jsx (one-line: pass relatedSlot={<RelatedProgressions …/>}). Ranking per §5, exported from the component file for smoke coverage; honest empty states; build + smoke green. Disjoint from D-51 (App.jsx/match.js vs GlanceRail/VoicingBrowser) → may run in parallel after L-50.

---

7. Narrow plan (< xl, and the ~640px check)

Columns stack in the jam-following order: loop strip → instrument view → voicings rail → licks strip → related progressions — i.e. the right column tucks between mainView and LicksStrip, matching the user's list order. Implementation: the rail block is simply the second child inside the stacked flow below xl (JamGuide reorders its own children with responsive classes or conditional order — no duplicate mounts). The rail unbounds below xl (the max-h/overflow classes are xl:-prefixed) and lays out at natural height in page flow — a nested scroller inside a scrolling page is a trap on touch. Cell wrap at ~576px interior: guitar 5/line, piano cells pair (a 284px two-octave + a 160px one-octave = 452, or two two-octaves at the 576 boundary) — the same margin-hardened pairing D-51 verified for the bounded column (§4), with more room here, not the "cells ride alone" of the narrower bounded width. The instrument selector never moves: it lives in the controls bar, global, above everything at every width.

Jam view below xl: the toggle still works — below-dashboard surfaces hide and fullscreen still fires — but the stacked dashboard is taller than any narrow viewport, so the page keeps scrolling (h-screen overflow-hidden applies only at xl:+ alongside the grid). One-screen is a two-column promise; jam view narrows honestly to "distraction-free" rather than pretending the geometry works.

---

8. Rejected alternatives

Rejected A — keep the rail as the full-width band and put licks + progressions in the right column instead. The rail is the surface the directive names for the right side ("i'd like to have the suggested voicings on the right side of the screen (the jam guide)") — and the math agrees: full width doesn't make the rail shorter in any useful way (rows are height-bound by cell-line count, and at 1,240px most piano galleries fit one line, but the band still starts below the instrument view and pushes licks/progressions off screen — today's exact failure). Licks and progressions are short; they fit under the instrument view; the tall thing is what needs the dedicated column.

Rejected B — one-screen by truncation: show only the recommended voicing per station, gallery behind a tap. Fits 4 stations in ~640px with zero scroll — and violates three standing calls at once: scroll > click, D-30's "all at once" gallery directive, and the learning value the user praised ("potentially learn new ways to play it while you are playing"). The gallery stays; its depth becomes a contained scroll, not a click.

Rejected C — rail in the LEFT column, detection surfaces right. Reading order puts the primary, continuously-tracked surfaces (strip, instrument view) top-left where Western eyes rest; the rail is a reference you glance at. Also geometric: the instrument view wants the wide column (674px natural fretboard width > 500px rail), and swapped columns would force the fretboard to ~0.68 scale — sub-legible labels.

Rejected D — compact the instrument view via CSS transform: scale() or a reduced fret range. Covered in §2: transform blurs text and shrinks targets; frets 0–7 amputates upper-position play. The natural-width cap + chrome trim achieves the same ~80px saving honestly.

Rejected E — page-flow rail (no height bound, no contained scroll). The "pure" reading of the no-nested-scrollbar taste rule — and it structurally fails the refinement: an unbounded rail stretches the document to the rail's full height (a jazz piano loop ≈ ~3,000px+), so the below-grid region — LoopStation and the whole learning area — lands thousands of pixels down instead of one flick below the dashboard; and in jam view an unbounded rail can never fit h-screen, so the 100vh hard constraint is unmeetable without the bound anyway. (The left column's five surfaces sit at the top either way — the cost is the document's length and the jam-view fit, not their co-presence.) Below xl this rejection inverts — §7 — because stacked layouts have no second column to preserve.

---

9. Out of scope / flags for Maestro

• Contained auto-follow inside the rail scroller — now technically safe, deliberately deferred; user-pulled follow-up only (§4).
• LoopStation in jam view — excluded per the user's own enumeration (§3 recorded call); if missed mid-jam, admitting it is a one-line conditional. User-pulled follow-up only.
• Root-aligned MiniPiano crop (halves piano rail height) — reopens D-24; D-52 candidate (§4).
• src/lib/match.js additive exports in L-51 — shared-file lock note at promotion (§6.3). Same coordination point covers D-62: if its fix (a) lands collapsed-form indexing in match.js first, L-51's ranking consumes that shared collapsed form instead of collapsing locally (§5).
• Retire-then-delete backlog grows by ProgressionSuggestions.jsx (unmounted L-50) alongside RoadmapTrack/CurrentJamPanel/EducationPanel.
• KnowledgeDock deep-link ("open Explore at style X") — not invented for v1; RelatedProgressions taps go per-chord to ChordDetailModal (§5).
• No new tokens, no new colours, no dependencies, no KB/theory/audio changes anywhere in this design. Geometry figures verified per integrated-glance.md; module heights are estimates and D-51/C-50 re-measure the built thing.