# Related progressions — same-style-first (D-72)

Concept doc for **L-72**. Design-only; no code here. Scope is one bounded edit to
`src/components/RelatedProgressions.jsx` (match.js untouched — see §6).

## The user's ask (2026-07-13, verbatim intent)

> "for the related progressions this is good also, but i would also want
> bridge/chorus/modifications in the same style … say i select jam roulette with
> blues, then i want for that progression other options and not necessarily go
> into other styles."

**Chosen scope:** reuse the KB's *existing* same-style progressions. No computed
modifications, no new authored content, no new KB fields. When a style is active
(rolled via Jam Roulette **or** live-detected), the panel leads with the OTHER
progressions of that same style, reframed as variations/sections to try — instead
of jumping to other styles.

The component today already computes a match, ranks every *other* KB progression
by musical proximity, and prints a flat cross-style list. This doc changes only
**how the list is partitioned, floored, ordered, and labelled** once a style is
known. When no style is known, behaviour is unchanged.

---

## 1. How the active style is known — reuse the component's own match

`rankRelatedProgressions(loop)` already calls
`matchLoopToProgression(loop, index)`, whose result is
`{ matched, id, style, rotation, progression }`. **`match.style` IS the active
style** — for both entry points:

- **Jam Roulette:** `rollJam` seeds `detectedProgression = seedableLoop(prog, key)`
  (the collapsed canonical form). The L-60 collapsed-form index makes the
  component re-match that loop back to the rolled progression → `match.style ==
  the rolled style`, `match.id == the rolled progression's id`. That id is already
  excluded from `entries` (the `prog.id === match.id` guard), so the surviving
  same-style progressions are exactly "other options for the style I rolled."
- **Live detection:** the detected repeating loop is what App passes as
  `loop={detectedProgression}`; the same match resolves the live style/id.

**Recommendation — use the internally-computed `match.style`; do NOT add a prop.**
Naming it explicitly: inside `rankRelatedProgressions`, after the existing
`const match = matchLoopToProgression(...)`, take

```
const activeStyle = match.matched ? match.style : null
```

Rejected: threading a `matchedStyle` prop down from App (roulette knows it via
`lastRolledStyleRef`; live detection could expose its own match). It duplicates
state that the component already derives identically from the same `loop`, and
introduces a divergence risk (App's match vs the component's match drifting).
The single source of truth is the loop → its match. Keep it in one place.

**No-match fallback.** When `match.matched === false` (the loop matches no KB
progression — an off-book jam), `activeStyle` is `null`; the panel renders exactly
today's cross-style list (flat, floor `RELATED_SCORE_FLOOR`, existing
annotations). Nothing about the current behaviour changes when no style is locked.

---

## 2. Same-style-first presentation — two sections

When `activeStyle != null`, partition the scored candidates by
`entry.style === activeStyle`:

**Primary — "Try these in {styleLabel}"** (same-style siblings).
All same-style progressions except the one being played, in scorer order (§4),
capped at `RELATED_MAX_ENTRIES` (5). The score floor is **relaxed to 0 for this
section** — a sibling of your own style is never "junk"; it is exactly the "other
options" the user asked for. Styles hold ≤7 progressions, so this shows all of
them (blues → 4 siblings).

**Secondary — "Same changes, other styles"** (cross-style), demoted, small.
Only progressions whose canonical changes are *identical* to the loop
(`sameChanges === true`), capped at **2**, floor kept. This preserves a genuinely
valuable, rare relative — "this exact turnaround also lives in jazz and gospel" —
without "going into other styles" for merely-similar material. If none qualify,
the section is omitted entirely.

**Recommendation: ship both sections (option b).** It honours "not necessarily go
into other styles" (same-style leads and dominates the panel) while not hiding an
exact-match cousin elsewhere. Dropping the secondary later is a one-line change
(don't render it) if the user wants pure same-style — noted as the toggle.

Rejected: a hard same-style-only filter that *never* shows cross-style. It throws
away the exact-match cousin (musically the most useful cross-style pointer we
have) and would also have to special-case the no-match path. Kept only as the
one-line fallback if the user insists on zero cross-style.

---

## 3. The reframe — "bridge/chorus/modifications" with NO new content

Same-style siblings must read as *sections/variations to try*, not a flat list.
We label each with a short **role phrase** derived only from data already in the
KB — comparing the sibling to the active (matched) progression. Fields used:
`mode`, `bars` (summed = the form length), `qualities` (the colour set),
`name`, `level`. No new fields.

`siblingRole(sibling, active)` → a short phrase or `null`, first rule that fires:

1. **mode differs** → `"{mode} version"` — minor→`"minor version"`,
   major→`"major version"`, else the mode name (`"dorian version"`, …).
2. **same mode, fewer total bars** → `"shorter form"`.
3. **same mode, more total bars** → `"extended form"`.
4. **same mode & length, a quality the active lacks** → `"reharmonized"`.
5. **otherwise** → `null` (honest: just the name + level badge, no role line).

The active progression's `mode`/`bars` come from looking the raw KB entry up by
`match.id` in `kbRegistry[activeStyle].progressions` (avoids any collapsed-
projection subtlety; the raw entry is authoritative).

### Concrete — active = blues **Standard 12-bar** (major, 12 bars)

| sibling | mode | bars | role phrase | reads as |
|---|---|---|---|---|
| Quick-change 12-bar | major | 12 | `null` | name + `foundation` (name already says "quick-change") |
| 8-bar blues | major | 8 | **shorter form** | "the compact take" |
| Minor blues | minor | 12 | **minor version** | "the minor cousin" |
| Turnaround cycle | major | 4 | **shorter form** | name already says "Turnaround cycle" |

Every phrase is honest and re-derivable from `mode`/`bars`/`qualities`. Where no
character is derivable (Quick-change: same mode, same length, same all-dom7 colour
set) we print **nothing** beyond the name and level badge — the name carries it.
The two "shorter form"s are fine: their *names* (`8-bar blues`, `Turnaround
cycle`) already distinguish them, and the scorer orders them by proximity (§4).

This is where the "bridge/chorus/modification" feel comes from: the KB already
holds the minor version, the short form, the turnaround, the quick-change — we are
just *reframing existing siblings* with a one-line role, not synthesising sections.

---

## 4. Ranking within same-style — keep the scorer order

The existing scorer still runs over every candidate. Within the same-style group
the `+40 SCORE_SAME_STYLE` term is constant, so it cancels — ordering is driven by
`same changes (+100)` → `shared transitions` → `Jaccard` → `− length`, i.e.
**musical proximity to the loop you're playing.** That is more useful mid-jam than
alphabetical, so:

**Recommendation: keep the scorer sort within same-style. Do NOT re-sort by
level/name.** The closest variation to what your hands are already doing surfaces
first. The only change is relaxing the floor to 0 for this section (§2) so no
sibling is silently dropped for being "only" a distant relative — the user
explicitly wants *all* the style's options.

---

## 5. Edge / empty states

- **Style with only 1 progression** (0 same-style siblings after excluding the
  played one). No current style hits this (all have ≥5), but handle it: render an
  honest primary line — *"You're on the only {styleLabel} loop in the songbook."* —
  then fall through to the cross-style secondary (kept at floor). Never pad.
- **Secondary empty** (no exact cross-style cousin) → omit the secondary section
  silently; the primary stands alone.
- **No match at all** (`activeStyle == null`) → today's single flat list, unchanged.
- **Instrument-agnostic — confirmed.** `RelatedProgressions` reads only
  `progressions` (`degrees`/`qualities`/`rn`/`level`/`name`/`mode`/`bars`), never
  the `instruments` cells. It behaves identically under guitar / piano / bass; the
  global instrument selector does not touch it.

---

## 6. L-72 change list (RelatedProgressions.jsx only)

`match.js` needs **no change** — `matchLoopToProgression` already returns
`{ style, id, progression }`. Reuse it.

In `rankRelatedProgressions`:
1. After computing `match`, derive `const activeStyle = match.matched ? match.style
   : null` and look up the raw active progression (`kbRegistry[activeStyle]
   ?.progressions.find(p => p.id === match.id)`) for its `mode` + summed `bars`.
2. Keep the existing scoring loop. Change the floor test: skip the
   `score < RELATED_SCORE_FLOOR → continue` **only when** `style === activeStyle`
   (same-style siblings bypass the floor); cross-style keeps the floor.
3. Add a `siblingRole(sibling, active)` helper (§3) and attach `role` to each
   same-style entry; leave cross-style entries' existing `annotation` intact.
4. Partition the sorted entries into `primary` (`style === activeStyle`, cap 5)
   and `secondary` (`style !== activeStyle && sameChanges`, cap 2). Return
   `{ match, activeStyle, activeStyleLabel, primary, secondary }`. Keep
   `entries` (= `primary.concat(secondary)`) on the return so any existing
   `entries[0]` / `entries.length` reads still resolve during the transition.
   When `activeStyle == null`, return today's shape (`primary = entries`,
   `secondary = []`) so the render path collapses to the current flat list.

In the render:
5. Two `<section>`-internal blocks: primary headed *"Try these in
   {activeStyleLabel}"*, secondary headed *"Same changes, elsewhere"* (rendered
   only when non-empty). Same-style rows swap the `annotation` line for the `role`
   phrase (omit the line when `role == null`). Reuse the existing `LevelBadge` /
   `ChordChain` — no new tokens, no new colours (all within `bg-panel` /
   `border-border` / `text-gray-*` / `text-amber`, already in use).

**Smoke pins (C-50, `scripts/smoke.mjs` §8) will shift — re-derive, coordinate
with C-70:**
- Pin (a) collapsed 12-bar in A: top stays **blues/blues-8bar, score 92**
  (blues is now the active style; 8-bar is a same-style sibling; the +40 is still
  in its score, order unchanged). Its **annotation label changes** from
  `'shares I7→V7'` to the role `'shorter form'` — the assertion must be re-pinned.
- Pin (b) ii–V–I in C: top stays **jazz/jazz-251-minor, score 156** (same-style,
  same changes). Its label changes from `'same changes'` to the role
  `'minor version'` (mode differs) — re-pin.
- Scores and top ids are stable; only the annotation strings and the return shape
  move. Add coverage for the primary/secondary split and the no-match fallback.

### Rejected alternatives (recap)
- **Computed modifications** (synthesise a bridge/chorus by transposing or
  reharmonising) — rejected per the user's explicit choice to reuse existing KB
  content; also risks inventing non-idiomatic changes we can't vouch for.
- **Hard same-style-only, no cross-style ever** — rejected: loses the exact-match
  cousin in another style and complicates the no-match path. Retained only as the
  one-line "drop the secondary" toggle if the user later wants zero cross-style.
- **An explicit `matchedStyle` prop from App** — rejected as redundant (§1): the
  component derives the same style from the same loop; a prop only adds a
  divergence surface.