@pepperhorn/chordl-guitar 0.2.0 → 0.3.1

package/README.md

@@ -0,0 +1,82 @@
+# Guitar voicing generation and review
+
+`guitarPositionFor(spelledChord, options?)` first validates chords-db positions,
+then tries the regular power-chord shape, then ranks an exhaustive playable
+candidate set. `generateGuitarVoicings(notes, options?)` exposes that ranked set.
+
+```ts
+const position = guitarPositionFor(
+  { root: "A", pitchClasses: ["A", "C#", "Eb", "G", "Bb", "F#"] },
+  { level: 3 },
+);
+// A13(b9,b5): a rootless grip can retain 3, b5, b7, b9, 13.
+// position.review.reasons includes "omits:1" and "rootless".
+```
+
+The default teaching level is **2**. Levels 0–2 always retain the root. At
+level 3, the root may be omitted from chords with six or more required tones,
+from five-tone upper chords over a slash bass (including the formerly missing
+Ab9/Eb), or from any five-tone chord with an explicit `{ comping: true }`.
+A rootless grip must put a third/seventh lowest or sound the written slash bass
+lowest. A rooted grip still puts the root/written slash bass lowest. A slash
+bass equal to the root cannot be omitted. `rootless` and `omitted` disclose
+root omissions; a renderer should explain “root left out; the bass player has
+it”. Thirds, sevenths and named alterations are preserved in dense chords.
+
+Natural 9 remains required under #11 alone. It is optional under a natural 11
+or 13. These are spelling-aware rules: #11 differs from b5 even when the pitch
+classes coincide.
+
+Ranking penalizes register-dependent low seconds/thirds and minor ninths,
+inner-string basses, wide finger reaches, long barres, high positions (convex
+cost above fret 9), and opens under a high hand. Five-tone and larger chords
+have no six-string bonus. These costs rank compromises; they do not certify
+playability for a particular hand or enforce the future level-specific tiers.
+The top tension need not be the highest voice.
+
+Every returned position, including validated library shapes, carries `review`:
+
+- `origin`: `chords-db`, `template:power-chord`, or `search`.
+- `level`: requested teaching level, default 2.
+- `reasons`: omission, register, dissonance, hand geometry and rejected-library
+  reason codes (`ReasonCode` is exported). Empty means no measured warning.
+- `confidence`: deterministic attention heuristic in 0–1, **not a probability**
+  or teacher approval. Unflagged search starts at 0.88, library/template at 0.98.
+- `needsReview`: `reasons.length > 0 || confidence < 0.8`.
+- `reviewKey`: stable chord-constraint/level/absolute-grip/fingering identity.
+  Group by this key to review enharmonic twins once (Bb9/C# and Bb9/Db, for
+  example). Different fingerings or levels remain separate review items.
+
+The key deduplicates review work without requiring a catalogue slug or a
+stateful registry, and without marking otherwise clean twins as warnings.
+The root's pitch class and each tone's degree/role remain in the key; merely sharing
+an unordered pitch set does not conflate different bass or omission policies.
+A non-chord bass is distinct from a seventh (which may double), even if both
+spellings produce the same pitch set. No template origin is claimed for brute-force search results.
+
+This package supplies metadata. Card/manifest consumers must forward it and
+pass the teaching level; existing card rendering is unchanged.
+
+## Reproduce the independent-oracle comparison
+
+From the repository root, with the existing review outputs available:
+
+```sh
+node_modules/.bin/tsx packages/chordl-guitar/scripts/compare-voicings.mts \
+  --plain /path/to/plain/verdicts.json \
+  --slash /path/to/slash/verdicts.json \
+  --missing /path/to/missing38.json \
+  --out /path/to/generator-comparison \
+  --baseline-ref d307e3b378c6864cd61fc39f6571cf0ee1a81586
+```
+
+Both versions regenerate all 3,157 oracle rows. The script refuses baseline
+shape/fingering mismatches, validates new pitch coverage, reports changed
+`replace` and `accept` rows separately, counts all 38 recoveries, and writes
+review distributions, raw JSON and an HTML contact sheet. Comparison uses
+explicit level 3; the default remains root-preserving level 2. Original verdicts
+judge the old shapes: a changed `accept` is a regression watch item, and a
+changed `replace` still needs a teacher's playing/listening check.
+
+Package checks: `pnpm --filter @pepperhorn/chordl-guitar test:run` and
+`pnpm --filter @pepperhorn/chordl-guitar build`.

package/dist/chordLookup.d.ts

@@ -1,5 +1,6 @@
 import type { Chord } from "svguitar";
 import type { ChordsDbPosition, InstrumentId } from "./instruments.js";
+import type { ExperienceLevel } from "./experience.js";
 export interface GuitarChordResult {
     /** The chord label as given. */
     label: string;
@@ -8,6 +9,8 @@ export interface GuitarChordResult {
     positions: ChordsDbPosition[];
     /** svguitar Chord objects, one per position, ready to render. */
     shapes: Chord[];
+    /** How hard each shape is to play, parallel to `positions`/`shapes`. */
+    levels: ExperienceLevel[];
 }
 /**
  * Look up all stored shapes for a chord label. Returns null when the chord or

package/dist/chordLookup.js

@@ -21,8 +21,11 @@ import guitarDb from "./generated/guitar.slim.json" with { type: "json" };
 import ukuleleDb from "./generated/ukulele.slim.json" with { type: "json" };
 import { INSTRUMENTS, dbPositionToChord, } from "./instruments.js";
 import { rootPitchClass } from "./pitch.js";
+import { splitLabel, toDbSuffix } from "./chordNames.js";
 import { powerChordPosition } from "./powerChords.js";
-import { GUITAR_TOP3_PRESETS } from "./staticPresets.js";
+import { findTop3Preset } from "./staticPresets.js";
+import { positionFacts } from "./voicingFacts.js";
+import { levelForFacts } from "./experience.js";
 const GUITAR_DB = guitarDb;
 const UKULELE_DB = ukuleleDb;
 // chords-db ships guitar and ukulele voicing libraries.
@@ -51,43 +54,6 @@ const ROOT_TO_DB_KEYS = {
     "A#": ["Bb", "Asharp"], Bb: ["Bb", "Asharp"],
     B: ["B"], Cb: ["B"],
 };
-// chordl suffix → chords-db suffix. Most match verbatim; only the triads and a
-// couple of aliases need translating.
-function toDbSuffix(suffix) {
-    const s = suffix.trim();
-    if (s === "" || s === "maj" || s === "M")
-        return "major";
-    if (s === "m" || s === "min" || s === "-")
-        return "minor";
-    if (s === "min7")
-        return "m7";
-    if (s === "M7")
-        return "maj7";
-    if (s === "°")
-        return "dim";
-    if (s === "°7")
-        return "dim7";
-    if (s === "ø" || s === "ø7")
-        return "m7b5";
-    // chords-db spells the 6/9 voicings without the slash.
-    if (s === "6/9")
-        return "69";
-    if (s === "m6/9")
-        return "m69";
-    // Bare "sus" (and "7sus") carry no extension number; sus4 is the convention.
-    if (s === "sus")
-        return "sus4";
-    if (s === "7sus")
-        return "7sus4";
-    return s; // m7, maj7, 7, dim7, sus4, 6, 9, 11, 13, m7b5, ... match verbatim
-}
-function splitLabel(label) {
-    const m = label.trim().match(/^([A-Ga-g][#b]?)(.*)$/);
-    if (!m)
-        return null;
-    const root = m[1].charAt(0).toUpperCase() + m[1].slice(1);
-    return { root, suffix: m[2] };
-}
 function findEntry(db, label) {
     const parsed = splitLabel(label);
     if (!parsed)
@@ -126,24 +92,15 @@ function powerChordPositions(label) {
         .filter((p) => p !== null);
 }
 // ── Top-3-string presets ────────────────────────────────────────────────────
-/**
- * The preset table spells qualities in words where chords-db uses symbols, so a
- * chordl label has to be translated before lookup. Only the suffixes the table
- * actually carries are mapped; anything else finds nothing, which is correct —
- * falling back to a six-string shape under a three-string label would be a lie.
- */
-function toPresetSuffix(suffix) {
-    const s = suffix.trim();
-    if (s === "")
-        return "major";
-    if (s === "m" || s === "min")
-        return "minor";
-    return s; // 7, m7, maj7 match the table verbatim
-}
 /**
  * Presets are authored as svguitar shapes, but callers expect chords-db-style
  * positions (that is what carries `baseFret` for the "fret N" caption). Convert
  * back: svguitar numbers strings high-to-low from 1, positions run low-to-high.
+ *
+ * The window is already decided — `toPreset` put it on `chord.position`, so
+ * every consumer of the preset table sees the same one — and `chord` frets are
+ * relative to it, which is exactly what `baseFret` means. So there is nothing to
+ * recompute here, only to rename.
  */
 function presetToPosition(preset) {
     const frets = new Array(6).fill(-1);
@@ -161,16 +118,19 @@ function presetToPosition(preset) {
         const n = Number(label);
         fingers[idx] = Number.isFinite(n) ? n : 0;
     }
-    // Every preset is written in absolute frets from the nut, all within reach of
-    // first position, so the diagram window always starts at the nut.
-    return { frets, fingers, baseFret: 1, barres: [] };
+    return { frets, fingers, baseFret: preset.chord.position ?? 1, barres: [] };
 }
+/**
+ * The table resolves both halves of the label itself — root by pitch class, and
+ * suffix through the same `toDbSuffix` the six-string path uses — so there is
+ * nothing to translate here beyond finding where the root stops.
+ *
+ * A miss still returns null. Falling back to a six-string shape under a
+ * three-string label would be a lie.
+ */
 function findPreset(label) {
     const parsed = splitLabel(label);
-    if (!parsed)
-        return null;
-    const suffix = toPresetSuffix(parsed.suffix);
-    return (GUITAR_TOP3_PRESETS.find((p) => p.key === parsed.root && p.suffix === suffix) ?? null);
+    return parsed ? findTop3Preset(parsed.root, parsed.suffix) : null;
 }
 /**
  * Look up all stored shapes for a chord label. Returns null when the chord or
@@ -180,19 +140,26 @@ export function lookupGuitarChord(label, instrument = "guitar") {
     const strings = INSTRUMENTS[instrument]?.strings;
     if (strings == null)
         return null;
-    const toResult = (positions) => positions.length === 0
+    const openMidi = INSTRUMENTS[instrument].openMidi;
+    const rootPc = rootPitchClass(label);
+    // chords-db and generated positions have no stored level: derive it from the
+    // same facts levelForFacts always ranks on.
+    const derivedLevels = (positions) => positions.map((pos) => levelForFacts(positionFacts(pos, openMidi, rootPc)));
+    const toResult = (positions, levels = derivedLevels(positions)) => positions.length === 0
         ? null
         : {
             label,
             instrument,
             positions,
             shapes: positions.map((pos) => dbPositionToChord(pos, strings, label)),
+            levels,
         };
     // 1. Hand-authored beats generated: the preset table is the only source of
-    //    three-string voicings, and it does not fall back to chords-db.
+    //    three-string voicings, and it does not fall back to chords-db. Its
+    //    level is precomputed and stored on the preset — see src/experience.ts.
     if (instrument === "guitar-top3") {
         const preset = findPreset(label);
-        return preset ? toResult([presetToPosition(preset)]) : null;
+        return preset ? toResult([presetToPosition(preset)], [preset.level]) : null;
     }
     // 2. chords-db, for the instruments that ship a library.
     const db = dbFor(instrument);

package/dist/chordLookup.js.map

@@ -1 +1 @@
-{"version":3,"file":"chordLookup.js","sourceRoot":"","sources":["../src/chordLookup.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"chordLookup.js","sourceRoot":"","sources":["../src/chordLookup.ts"],"names":[],"mappings":"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"}

package/dist/chordNames.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Chord-label spelling, resolved once for every lookup path.
+ *
+ * A user types `Db`, `C#`, `Cø`, `CM7`, `Csus`; chords-db stores `Csharp`,
+ * `m7b5`, `maj7`, `sus4`. Both the six-string library and the top-3 table need
+ * the same translation, and two copies of it drift — the top-3 path used to
+ * carry a three-line version of `toDbSuffix` that knew only `""`, `m` and `min`,
+ * which left the generated table addressable for a fraction of what it holds.
+ *
+ * Roots are resolved by pitch class rather than by spelling wherever the target
+ * is keyed that way; `rootPitchClass` in pitch.ts is the one parser for that.
+ * This module carries what pitch classes cannot express: where the suffix ends
+ * and, for chords-db, which of its inconsistent root spellings to try.
+ */
+/**
+ * chordl suffix → chords-db suffix. Most match verbatim; only the triads and a
+ * handful of aliases need translating.
+ */
+export declare function toDbSuffix(suffix: string): string;
+/** Split a label into its root spelling and everything after it. */
+export declare function splitLabel(label: string): {
+    root: string;
+    suffix: string;
+} | null;

package/dist/chordNames.js

@@ -0,0 +1,55 @@
+/**
+ * Chord-label spelling, resolved once for every lookup path.
+ *
+ * A user types `Db`, `C#`, `Cø`, `CM7`, `Csus`; chords-db stores `Csharp`,
+ * `m7b5`, `maj7`, `sus4`. Both the six-string library and the top-3 table need
+ * the same translation, and two copies of it drift — the top-3 path used to
+ * carry a three-line version of `toDbSuffix` that knew only `""`, `m` and `min`,
+ * which left the generated table addressable for a fraction of what it holds.
+ *
+ * Roots are resolved by pitch class rather than by spelling wherever the target
+ * is keyed that way; `rootPitchClass` in pitch.ts is the one parser for that.
+ * This module carries what pitch classes cannot express: where the suffix ends
+ * and, for chords-db, which of its inconsistent root spellings to try.
+ */
+/**
+ * chordl suffix → chords-db suffix. Most match verbatim; only the triads and a
+ * handful of aliases need translating.
+ */
+export function toDbSuffix(suffix) {
+    const s = suffix.trim();
+    if (s === "" || s === "maj" || s === "M")
+        return "major";
+    if (s === "m" || s === "min" || s === "-")
+        return "minor";
+    if (s === "min7")
+        return "m7";
+    if (s === "M7")
+        return "maj7";
+    if (s === "°")
+        return "dim";
+    if (s === "°7")
+        return "dim7";
+    if (s === "ø" || s === "ø7")
+        return "m7b5";
+    // chords-db spells the 6/9 voicings without the slash.
+    if (s === "6/9")
+        return "69";
+    if (s === "m6/9")
+        return "m69";
+    // Bare "sus" (and "7sus") carry no extension number; sus4 is the convention.
+    if (s === "sus")
+        return "sus4";
+    if (s === "7sus")
+        return "7sus4";
+    return s; // m7, maj7, 7, dim7, sus4, 6, 9, 11, 13, m7b5, ... match verbatim
+}
+/** Split a label into its root spelling and everything after it. */
+export function splitLabel(label) {
+    const m = label.trim().match(/^([A-Ga-g][#b]?)(.*)$/);
+    if (!m)
+        return null;
+    const root = m[1].charAt(0).toUpperCase() + m[1].slice(1);
+    return { root, suffix: m[2] };
+}
+//# sourceMappingURL=chordNames.js.map

package/dist/chordNames.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chordNames.js","sourceRoot":"","sources":["../src/chordNames.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,MAAc;IACvC,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;IACxB,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,GAAG;QAAE,OAAO,OAAO,CAAC;IACzD,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,GAAG;QAAE,OAAO,OAAO,CAAC;IAC1D,IAAI,CAAC,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IAC9B,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAC9B,IAAI,CAAC,KAAK,GAAG;QAAE,OAAO,KAAK,CAAC;IAC5B,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAC9B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAC3C,uDAAuD;IACvD,IAAI,CAAC,KAAK,KAAK;QAAE,OAAO,IAAI,CAAC;IAC7B,IAAI,CAAC,KAAK,MAAM;QAAE,OAAO,KAAK,CAAC;IAC/B,6EAA6E;IAC7E,IAAI,CAAC,KAAK,KAAK;QAAE,OAAO,MAAM,CAAC;IAC/B,IAAI,CAAC,KAAK,MAAM;QAAE,OAAO,OAAO,CAAC;IACjC,OAAO,CAAC,CAAC,CAAC,kEAAkE;AAC9E,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,MAAM,CAAC,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAAC;IACtD,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC1D,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAChC,CAAC"}

package/dist/experience.d.ts

@@ -0,0 +1,129 @@
+/**
+ * How hard a shape is to play, as three rungs a learner moves through.
+ *
+ * Derived from the facts, never stored: a level that can be hand-edited drifts
+ * from the shape it describes. `ShapeClass` in voicingSelect.ts filters on the
+ * same facts; this ranks on them. They are deliberately separate — a filter
+ * answers "show me the open ones", a rank answers "can I play this yet".
+ */
+import type { ChordsDbPosition } from "./instruments.js";
+import type { PositionFacts } from "./voicingFacts.js";
+import type { ShapeClass } from "./voicingSelect.js";
+export type ExperienceLevel = "beginner" | "emerging" | "established";
+/** Easiest first, so `indexOf` gives the rung number and +1 widens. */
+export declare const EXPERIENCE_LADDER: ExperienceLevel[];
+/**
+ * An open shape is barre-free and at the nut — nothing to hold down across
+ * strings and no hand position to find. Barre-free but moved up the neck is
+ * the next step. A barre is the rung most beginners stall on, so it anchors
+ * the top.
+ */
+export declare function levelForFacts(facts: PositionFacts): ExperienceLevel;
+/**
+ * Rank a three-string shape. `PositionFacts` cannot: it assumes six strings
+ * and real barres, and a top-3 shape has neither.
+ *
+ * The axes are the ones the generator already ranks candidates by — stretch,
+ * finger count, open strings, distance from the nut. A shape a learner can
+ * play without moving out of first position is the dividing line, because
+ * finding a hand position is the skill that separates the first two rungs.
+ *
+ * Accepts either of two representations of the same shape, and returns the
+ * same level for both:
+ *
+ *   - absolute frets measured from the nut, with `position` pinned at 1 —
+ *     what the generated table stores (`Top3GeneratedEntry.frets`);
+ *   - window-relative frets paired with the diagram's real `position` —
+ *     what `staticPresets.top3Window()` produces for rendering.
+ *
+ * They agree because the function only ever compares
+ * `position - 1 + max(fretted)` to the nut: sliding a window down by
+ * `position - 1` and adding it back is the same transform run forward and
+ * back, so the recovered highest fret — and therefore the level — is
+ * identical either way. A caller holding a rendered preset (windowed frets
+ * plus its real position) can pass those straight in rather than
+ * reconstructing absolute frets by hand, which is exactly the arithmetic that
+ * has produced off-diagram bugs elsewhere in this codebase.
+ */
+export declare function levelForTop3(frets: number[], position: number): ExperienceLevel;
+export interface ExperienceQuery {
+    level: ExperienceLevel;
+    /**
+     * Optional refinement within the level. Default "any".
+     *
+     * Published API, kept for when the level control gains a paired shape-class
+     * control — deliberately not wired into any UI yet (the only level control
+     * shipped so far is `dev/App.tsx`'s radio group; `GuitarChordPanel` draws
+     * no control of its own). Under cumulative level matching it now genuinely
+     * refines at the `emerging` and `established` rungs (it can drop shapes
+     * those levels would otherwise include), so do not delete this as dead —
+     * only its UI is deferred, not the mechanism.
+     */
+    shapeClass?: ShapeClass;
+}
+export interface ExperienceSelection {
+    /** Indices into the input array, in input order. Never empty when input is non-empty. */
+    indices: number[];
+    /** The level actually served — differs from the request when it widened. */
+    level: ExperienceLevel;
+    /** True when the shape-class refinement had to be dropped to find anything. */
+    droppedShapeClass: boolean;
+    /** The level originally asked for, when it had to widen. Absent otherwise. */
+    widenedFrom?: ExperienceLevel;
+}
+/**
+ * Filter by level, refine by shape class, and relax rather than show nothing.
+ *
+ * Level matching is CUMULATIVE, not exclusive: `query.level` answers "can I
+ * play this yet", so a level matches every shape ranked at or below it on
+ * `EXPERIENCE_LADDER` — `established` matches everything, `emerging` matches
+ * beginner + emerging, `beginner` matches only beginner (there is nothing
+ * below it to include). An established player can certainly play an open C;
+ * excluding the open shape from an "established" query was the bug, not a
+ * feature.
+ *
+ * Emptiness is still possible at the bottom rung: 220 of 529 chords have no
+ * open shape at all and 88 have only barre shapes, so a beginner filter finds
+ * nothing for nearly half the corpus. Returning an empty frame there would
+ * punish exactly the learner the filter is for, so relaxation still widens
+ * one rung at a time rather than giving up.
+ *
+ * Relaxation order is deliberate. The refinement goes first because the level
+ * is what the user asked for and the shape class only narrows it; widening the
+ * level changes the answer to the question they asked.
+ *
+ * @param levels - Optional, parallel to `facts`. When an entry is present it
+ *   is used verbatim instead of `levelForFacts(facts[i])`. This is for
+ *   shapes whose facts cannot support the six-string derivation — top-3
+ *   presets never carry barres, so `levelForFacts` can never call one
+ *   "established" even when its authoritative, stored level (`levelForTop3`)
+ *   says otherwise. Shape-class matching still reads `facts[i]` either way:
+ *   only the level lookup is overridable. Missing entries (a shorter array,
+ *   or `undefined` at an index) fall back to the derived level. Prefer
+ *   `selectForResult` when a `GuitarChordResult` (or equivalent
+ *   positions+levels pair) is in hand — it threads this argument for you so a
+ *   caller cannot forget it and silently reintroduce derived-only ranking.
+ */
+export declare function selectForExperience(facts: PositionFacts[], query: ExperienceQuery, levels?: ExperienceLevel[]): ExperienceSelection;
+/**
+ * `selectForExperience`, but for a `GuitarChordResult` (or any duck-typed
+ * `{ positions, levels }` pair) instead of a bare facts array.
+ *
+ * `selectForExperience`'s third argument is what stops top-3 shapes being
+ * mis-ranked: the six-string derivation (`levelForFacts`) is structurally
+ * unable to call a top-3 shape "established" because top-3 positions never
+ * carry barres, so a caller that forgets to pass `levels` silently gets a
+ * shape re-ranked one or more rungs too easy. Threading it by hand is exactly
+ * the kind of thing a future caller forgets, so this wrapper does it for you:
+ * it derives `facts` from `result.positions` and always passes
+ * `result.levels` through, leaving nowhere for the argument to get dropped.
+ *
+ * Prefer this whenever a full result (not just bare facts) is in hand. The
+ * bare-facts form of `selectForExperience` stays published for callers that
+ * only ever have `PositionFacts[]` — most tests, and anything working one
+ * level below a `GuitarChordResult`.
+ */
+export declare function selectForResult(result: {
+    positions: ChordsDbPosition[];
+    levels: ExperienceLevel[];
+}, openMidi: number[], rootPc: number | null, query: ExperienceQuery): ExperienceSelection;

package/dist/experience.js

@@ -0,0 +1,164 @@
+import { positionFacts } from "./voicingFacts.js";
+import { matchesShapeClass } from "./voicingSelect.js";
+/** Easiest first, so `indexOf` gives the rung number and +1 widens. */
+export const EXPERIENCE_LADDER = [
+    "beginner",
+    "emerging",
+    "established",
+];
+/**
+ * An open shape is barre-free and at the nut — nothing to hold down across
+ * strings and no hand position to find. Barre-free but moved up the neck is
+ * the next step. A barre is the rung most beginners stall on, so it anchors
+ * the top.
+ */
+export function levelForFacts(facts) {
+    if (facts.isOpenShape)
+        return "beginner";
+    if (!facts.hasBarre)
+        return "emerging";
+    return "established";
+}
+/**
+ * Rank a three-string shape. `PositionFacts` cannot: it assumes six strings
+ * and real barres, and a top-3 shape has neither.
+ *
+ * The axes are the ones the generator already ranks candidates by — stretch,
+ * finger count, open strings, distance from the nut. A shape a learner can
+ * play without moving out of first position is the dividing line, because
+ * finding a hand position is the skill that separates the first two rungs.
+ *
+ * Accepts either of two representations of the same shape, and returns the
+ * same level for both:
+ *
+ *   - absolute frets measured from the nut, with `position` pinned at 1 —
+ *     what the generated table stores (`Top3GeneratedEntry.frets`);
+ *   - window-relative frets paired with the diagram's real `position` —
+ *     what `staticPresets.top3Window()` produces for rendering.
+ *
+ * They agree because the function only ever compares
+ * `position - 1 + max(fretted)` to the nut: sliding a window down by
+ * `position - 1` and adding it back is the same transform run forward and
+ * back, so the recovered highest fret — and therefore the level — is
+ * identical either way. A caller holding a rendered preset (windowed frets
+ * plus its real position) can pass those straight in rather than
+ * reconstructing absolute frets by hand, which is exactly the arithmetic that
+ * has produced off-diagram bugs elsewhere in this codebase.
+ */
+export function levelForTop3(frets, position) {
+    const fretted = frets.filter((f) => f > 0);
+    const opens = frets.filter((f) => f === 0).length;
+    const span = fretted.length ? Math.max(...fretted) - Math.min(...fretted) : 0;
+    const highest = position - 1 + (fretted.length ? Math.max(...fretted) : 0);
+    // Away from the nut is established regardless of how few fingers it takes:
+    // the hand has to be placed before it can be shaped.
+    if (position > 1 || highest > 4)
+        return "established";
+    // At the nut: open strings or at most two fingers, with no stretch.
+    if (span <= 1 && (opens > 0 || fretted.length <= 2))
+        return "beginner";
+    return "emerging";
+}
+/**
+ * Filter by level, refine by shape class, and relax rather than show nothing.
+ *
+ * Level matching is CUMULATIVE, not exclusive: `query.level` answers "can I
+ * play this yet", so a level matches every shape ranked at or below it on
+ * `EXPERIENCE_LADDER` — `established` matches everything, `emerging` matches
+ * beginner + emerging, `beginner` matches only beginner (there is nothing
+ * below it to include). An established player can certainly play an open C;
+ * excluding the open shape from an "established" query was the bug, not a
+ * feature.
+ *
+ * Emptiness is still possible at the bottom rung: 220 of 529 chords have no
+ * open shape at all and 88 have only barre shapes, so a beginner filter finds
+ * nothing for nearly half the corpus. Returning an empty frame there would
+ * punish exactly the learner the filter is for, so relaxation still widens
+ * one rung at a time rather than giving up.
+ *
+ * Relaxation order is deliberate. The refinement goes first because the level
+ * is what the user asked for and the shape class only narrows it; widening the
+ * level changes the answer to the question they asked.
+ *
+ * @param levels - Optional, parallel to `facts`. When an entry is present it
+ *   is used verbatim instead of `levelForFacts(facts[i])`. This is for
+ *   shapes whose facts cannot support the six-string derivation — top-3
+ *   presets never carry barres, so `levelForFacts` can never call one
+ *   "established" even when its authoritative, stored level (`levelForTop3`)
+ *   says otherwise. Shape-class matching still reads `facts[i]` either way:
+ *   only the level lookup is overridable. Missing entries (a shorter array,
+ *   or `undefined` at an index) fall back to the derived level. Prefer
+ *   `selectForResult` when a `GuitarChordResult` (or equivalent
+ *   positions+levels pair) is in hand — it threads this argument for you so a
+ *   caller cannot forget it and silently reintroduce derived-only ranking.
+ */
+export function selectForExperience(facts, query, levels) {
+    if (facts.length === 0) {
+        return { indices: [], level: query.level, droppedShapeClass: false };
+    }
+    const cls = query.shapeClass ?? "any";
+    const levelOf = (i) => levels?.[i] ?? levelForFacts(facts[i]);
+    const rank = (level) => EXPERIENCE_LADDER.indexOf(level);
+    // Cumulative: everything ranked at or below `level` counts as a match.
+    const at = (level, withClass) => facts
+        .map((f, i) => i)
+        .filter((i) => rank(levelOf(i)) <= rank(level) &&
+        (!withClass || matchesShapeClass(facts[i], cls)));
+    // 1. level + refinement
+    const exact = at(query.level, true);
+    if (exact.length > 0) {
+        return { indices: exact, level: query.level, droppedShapeClass: false };
+    }
+    // 2. drop the refinement, same level
+    const noClass = at(query.level, false);
+    if (noClass.length > 0) {
+        return { indices: noClass, level: query.level, droppedShapeClass: cls !== "any" };
+    }
+    // 3. widen the level, one rung at a time, refinement already gone. This
+    // loop always returns before exhausting the ladder: matching is cumulative
+    // (step 2 above), so `at("established", false)` — the last rung — matches
+    // every index whenever `facts` is non-empty, which the guard at the top of
+    // this function guarantees. A fourth "take everything" fallback after this
+    // loop used to exist for the case where even that failed; it was dead code
+    // that could never run, and it lied about `level` when it did (claiming to
+    // serve `query.level` while actually serving every shape). Deleted rather
+    // than kept honest, because there is nothing truthful left for it to say —
+    // the loop already covers the one case it was for.
+    const start = EXPERIENCE_LADDER.indexOf(query.level);
+    for (let i = start + 1; i < EXPERIENCE_LADDER.length; i++) {
+        const wider = at(EXPERIENCE_LADDER[i], false);
+        if (wider.length > 0) {
+            return {
+                indices: wider,
+                level: EXPERIENCE_LADDER[i],
+                droppedShapeClass: cls !== "any",
+                widenedFrom: query.level,
+            };
+        }
+    }
+    throw new Error("selectForExperience: unreachable — cumulative matching guarantees the " +
+        "widening loop returns by \"established\" whenever facts is non-empty");
+}
+/**
+ * `selectForExperience`, but for a `GuitarChordResult` (or any duck-typed
+ * `{ positions, levels }` pair) instead of a bare facts array.
+ *
+ * `selectForExperience`'s third argument is what stops top-3 shapes being
+ * mis-ranked: the six-string derivation (`levelForFacts`) is structurally
+ * unable to call a top-3 shape "established" because top-3 positions never
+ * carry barres, so a caller that forgets to pass `levels` silently gets a
+ * shape re-ranked one or more rungs too easy. Threading it by hand is exactly
+ * the kind of thing a future caller forgets, so this wrapper does it for you:
+ * it derives `facts` from `result.positions` and always passes
+ * `result.levels` through, leaving nowhere for the argument to get dropped.
+ *
+ * Prefer this whenever a full result (not just bare facts) is in hand. The
+ * bare-facts form of `selectForExperience` stays published for callers that
+ * only ever have `PositionFacts[]` — most tests, and anything working one
+ * level below a `GuitarChordResult`.
+ */
+export function selectForResult(result, openMidi, rootPc, query) {
+    const facts = result.positions.map((pos) => positionFacts(pos, openMidi, rootPc));
+    return selectForExperience(facts, query, result.levels);
+}
+//# sourceMappingURL=experience.js.map