#Tonality System

The tonality system manages daily key/scale selection and progressive unlocking of tonalities as the player advances.

Source files: src/lib/tonality/tonality.ts, src/lib/tonality/scale-compatibility.ts

#Concepts

A tonality is a combination of a key (pitch class) and a scale type (e.g., "D Dorian", "Bb Blues"). Practice sessions focus on a single tonality per day — all licks are transposed to the day's key.

#Progressive Unlocking

Tonalities unlock based on the player's proficiency levels, with keys and scale types unlocking independently.

#Key Unlock Order (Circle of Fifths)

#Scale Type Unlock Order

#Cross-Product

Available tonalities = unlocked keys × unlocked scale types. Initially, the player has 3 tonalities (C Major Pentatonic, C Major, C Blues). As they build proficiency, the combinatorial space grows quickly.

#Daily Tonality Selection

The daily tonality is selected deterministically from the set of unlocked tonalities using an FNV-1a hash of the date string. This ensures:

• Same tonality all day for a given player
• Different tonality each day (assuming > 1 unlocked)
• Even distribution across unlocked tonalities over time
• Deterministic — no server state needed

hash = fnv1a(dateString)  // e.g., "2026-03-19"
index = hash % unlockedTonalities.length
dailyTonality = unlockedTonalities[index]

#Settings Override

Players can override the daily tonality in Practice Settings:

• Key selector: Circle-of-fifths layout. Locked keys shown disabled with lock icon and proficiency requirements tooltip.
• Scale type selector: Locked scales shown similarly.
• Reset to daily: Button to restore automatic selection.

The override persists to localStorage via the settings state module (tonalityOverride: Tonality | null).

#Integration with Practice

The practice page derives the active tonality from either the override or the daily pick:

const activeTonality = settings.tonalityOverride ?? getDailyTonality(today, unlockContext)

All licks in a session are transposed to activeTonality.key using transposeLickForTonality(). When the tonality changes (e.g., override selected), the current phrase is re-transposed via a $derived.

The practice page also displays the note count for the active scale (e.g., "5 notes" for pentatonic, "7 notes" for major) to help beginners understand what scale they're working with.

#Scale-Aware Lick Filtering

Source file: src/lib/tonality/scale-compatibility.ts

Not all licks are appropriate for every scale type. A 7-note major lick that gets snapped down to 5 notes sounds awkward in a pentatonic session. The scale compatibility system filters licks by their native scale before presenting them to the player.

#Design Decision

Pentatonic and blues scales are treated as first-class scales, not subsets of major. A pentatonic lick CAN appear in a major session (since pentatonic pitch classes are a subset of major), but a 7-note major lick should NOT appear in a pentatonic session.

#Compatibility Rules

The rules are based on pitch-class subset relationships:

For multi-chord progression categories (ii-V-I-major, ii-V-I-minor, turnarounds, rhythm-changes), compatibility is broader because the lick uses parent-key transposition:

#Resolution Order

getCompatibleScaleTypes(lick) resolves compatibility in this order:

1. If lick.source === 'user' → compatible with all ScaleTypes (user-recorded licks always pass)
2. Check lick.category for progression categories → use category-level mapping
3. Inspect lick.harmony[0]?.scaleId → use scale-level mapping
4. Fallback → compatible with all ScaleTypes (safe for unknown licks)

#Fallback Behavior

If scale filtering leaves fewer than 3 licks at the player's difficulty level, the practice page widens to all licks at that difficulty level. This prevents empty sessions for rare scale type / difficulty level combinations.

#API

#Types

interface Tonality {
  key: PitchClass;
  scaleType: string;  // e.g., 'major', 'blues', 'dorian'
}

#Functions

#Scale Compatibility Functions (scale-compatibility.ts)