tonal-guitar 0.3.0 → 0.4.0

package/README.md

@@ -137,7 +137,7 @@ fretboard(STANDARD, [0, 4]); // every note on strings 0-5, frets 0-4
 
 ### Shape Registry
 
-Built-in shapes are registered at import time: CAGED scale shapes (5), CAGED chord shapes (5), 3NPS patterns (7), pentatonic boxes (5) -- plus (v0.2.0) 5 minor CAGED scale shapes and 5 minor pentatonic boxes, derived from the major-frame shapes via `relabelShape`. See [Minor-Quality Entries](#minor-quality-entries) below.
+Built-in shapes are registered at import time: CAGED scale shapes (5), CAGED chord shapes (5), 3NPS patterns (7), pentatonic boxes (5) -- plus (v0.2.0) 5 minor CAGED scale shapes and 5 minor pentatonic boxes, derived from the major-frame shapes via `relabelShape`, and 5 minor + 5 major blues boxes, derived via `addPassingTone`. See [Minor-Quality Entries](#minor-quality-entries) and [Blues Boxes](#blues-boxes) below.
 
 #### `get(name: string) => ScaleShape | undefined`
 
@@ -292,6 +292,40 @@ buildFrettedScale(get("G Shape"), "C").notes;
 buildFrettedScale(get("Em Shape"), "A").notes; // same {string, fret} pairs, A=1P, C=3m
 ```
 
+### Blues Boxes
+
+#### `addPassingTone(shape: ScaleShape, tone: string, options?: PassingToneOptions) => ScaleShape | undefined`
+
+Adds a chromatic passing tone to any scale shape -- e.g. the b5 (`"5d"`) that turns a minor pentatonic box into a minor blues box, the b3 (`"3m"`) that turns a major pentatonic box into a major blues box, or a `"7M"` on a mixolydian shape for bebop dominant.
+
+Placement rule: the tone goes on the same string, one fret above every note a semitone below it (the b5 sits right above each 4P). Tones inside the shape's existing pitch range are always kept, even if they need a one-fret stretch; a tone that would become the shape's new highest note is kept only if it fits within the existing fret span. Fret geometry is evaluated in `options.tuning` (default `STANDARD`). Returns `undefined` for an invalid tone, a shape that doesn't build, or when nothing can be placed (no semitone-below neighbor, or the pitch is already present).
+
+```js
+import { addPassingTone, get } from "tonal-guitar";
+
+const blues = addPassingTone(get("Em Shape"), "5d", { name: "Em Blues", quality: "minor-blues" });
+
+interface PassingToneOptions {
+  name?: string;         // override the result name (default: shape.name)
+  quality?: string;      // value written to result.quality
+  parentShape?: string;  // value written to result.parentShape (default: shape.name)
+  tuning?: string[];     // tuning for the stretch rule (default: STANDARD)
+}
+```
+
+Registered blues boxes (all `system: "pentatonic"`, box numbers shared with the pentatonic boxes):
+
+| Registered name | Derived from | `quality` | b5 frets in A minor blues |
+| --- | --- | --- | --- |
+| `"Blues Box 1 Minor"` | `"Pentatonic Box 1 Minor"` + `5d` | `"minor-blues"` | A:6, G:8 |
+| `"Blues Box 2 Minor"` | `"Pentatonic Box 2 Minor"` + `5d` | `"minor-blues"` | low E:11, G:8 |
+| `"Blues Box 3 Minor"` | `"Pentatonic Box 3 Minor"` + `5d` | `"minor-blues"` | low E:11, D:13, high E:11 |
+| `"Blues Box 4 Minor"` | `"Pentatonic Box 4 Minor"` + `5d` | `"minor-blues"` | D:13, B:16 |
+| `"Blues Box 5 Minor"` | `"Pentatonic Box 5 Minor"` + `5d` | `"minor-blues"` | A:6, B:4 |
+| `"Blues Box N Major"` | `"Blues Box N Minor"` relabeled | `"major-blues"` | same frets (C major blues = A minor blues) |
+
+They work with Tonal's scale names: `buildFromScale(get("Blues Box 1 Minor"), "E blues")` (`"blues"` is Tonal's alias for `"minor blues"`), `modeShapes("A blues")`, `isShapeCompatible(shape, "C major blues")`, and `relatedScales` (minor blues ↔ relative major blues).
+
 ### Pattern Generators
 
 All generators return `number[]` degree sequences.

package/dist/index.d.mts

@@ -80,9 +80,8 @@ interface Barre {
  * IS a `ScaleShape` (it only narrows `chordType` to required and adds a few
  * arpeggio-specific fields), so `buildFrettedScale`, `walkShape`,
  * `inferShapeContext` and `checkScaleBuildLoss` all work unchanged on it
- * with no code changes in this feature. No seed data ships for this
- * interface yet — see the `arpeggioShapes` registry (later group) for where
- * it starts getting populated.
+ * with no code changes in this feature. Built-in seeds live in
+ * `data/caged-arpeggios.ts` (registered into `arpeggioShapes`).
  */
 interface ArpeggioShape extends ScaleShape {
     chordType: string;
@@ -131,9 +130,13 @@ declare function playedStringSet(shape: ChordShape): number[];
  */
 declare function impliedStringSet(shape: ChordShape): number[];
 /**
- * The grip base fret for a set of per-string frets: the minimum *fretted*
- * (non-null, non-zero) fret, or `0` when there are no fretted strings (all
- * open/muted). Open strings (`0`) never set the grip base — see D-010.
+ * The grip base fret for a set of per-string frets: the minimum *played*
+ * (non-null) fret, open strings (`0`) included, or `0` when every string is
+ * muted. Including open strings is what makes the base root-invariant
+ * (D-010 as amended by CR-002 / #192): a shape whose root string lands on
+ * the nut at one root (E Shape at E, A Form at A, ...) keeps the same
+ * base-relative geometry as at every other root, so a `Barre.fret` offset
+ * resolves correctly everywhere.
  */
 declare function gripBaseFret(frets: (number | null)[]): number;
 /**
@@ -446,7 +449,7 @@ declare function autoFingering(shape: Omit<ChordShape, "fingers" | "barres">, ro
     barres: Barre[];
 };
 
-declare const VERSION = "0.3.0";
+declare const VERSION = "0.4.0";
 
 /**
  * Shape visual/quality audit checks.
@@ -641,9 +644,9 @@ declare function checkTuningMismatch(shape: ChordShape, tuning?: string[]): Shap
  * Flags a `Barre.fret` that cannot be a valid grip-base offset (D-010):
  *
  * 1. `fret < 0` — an offset is never negative.
- * 2. `fret > span` — `span` is the shape's own fretted span (same
- *    `checkFretSpan` computation: max − min over non-null, non-open built
- *    frets), and an offset can never exceed the span it's measured within.
+ * 2. `fret > span` — `span` is the range the offset is measured within:
+ *    the highest played built fret minus the grip base (`gripBaseFret`,
+ *    open strings included), so an offset can never exceed it.
  * 3. For `baseFret`-carrying shapes with a resolvable grip root (see
  *    `chordShapeGeometry`): `fret` equals the ABSOLUTE fret the source
  *    diagram implies for the barre's strings (`sourceFrets[barre.fromString]`)
@@ -656,6 +659,14 @@ declare function checkTuningMismatch(shape: ChordShape, tuning?: string[]): Shap
  *    `extended-chords.ts`, `caged-chords*.ts`) have since had their own
  *    pre-D-010 absolute barre frets migrated to grip-base offsets too
  *    (CR-001).
+ * 4. The offset resolves (`absoluteBarreFret(barre, gripBase)`) to a fret
+ *    that doesn't match the grip: a string under the barre carrying the
+ *    barre's finger sits at a different fret, or a played string under the
+ *    barre sits below it. This is the root-invariance gate (CR-002 / #192):
+ *    because built grips transpose rigidly and the grip base includes open
+ *    strings, an offset that passes here at one root passes at every root —
+ *    so it also catches offsets still measured from the old open-string-
+ *    excluding base.
  *
  * `root`/`tuning`/`prebuilt` mirror `checkFretSpan`'s signature so
  * `auditChordShape` can thread its single hoisted `applyChordShape` build in
@@ -1289,10 +1300,13 @@ declare function scoreShapeMatch(probe: InferenceProbe, _shape: ScaleShape, root
 /**
  * Shape relabeling: rewrite a ScaleShape's per-string interval labels into
  * a different (rotation-compatible) interval frame, e.g. turning a
- * major-frame CAGED shape into its natural-minor labeling.
+ * major-frame CAGED shape into its natural-minor labeling — and
+ * passing-tone augmentation (`addPassingTone`), e.g. adding the b5 that
+ * turns a minor pentatonic box into a blues box.
  *
- * Pure tier — MAY import `@tonaljs/interval` (required peer, already used
- * by build.ts) and `./shape` (types only). MUST NOT import
+ * Required-peer tier — MAY import `@tonaljs/interval`, `./build` (for
+ * `addPassingTone`'s fret geometry), `./tuning`, and `./shape` (types
+ * only). MUST NOT import
  * `@tonaljs/scale`/`@tonaljs/chord`/`@tonaljs/key` or `./integration`, so
  * `src/data/*` can call this at import time with zero optional peers.
  */
@@ -1314,6 +1328,31 @@ interface RelabelOptions {
  * convention, cf. `src/build.ts:188,192`) when no valid relabeling exists.
  */
 declare function relabelShape(shape: ScaleShape, targetIntervals: string[], options?: RelabelOptions): ScaleShape | undefined;
+interface PassingToneOptions extends RelabelOptions {
+    tuning?: string[];
+}
+/**
+ * Add a chromatic passing tone to a shape, e.g. the b5 (`"5d"`) that turns
+ * a minor pentatonic box into a minor blues box, or the b3 (`"3m"`) that
+ * turns a major pentatonic box into a major blues box.
+ *
+ * Placement rule: `tone` is inserted on the same string, one fret above
+ * every note whose chroma is a semitone below `tone` (the b5 sits right
+ * above each 4P). Every inserted tone that lands inside the shape's
+ * existing pitch range is kept, even when it needs a one-fret stretch past
+ * the shape's fret span. A tone that would become the shape's new highest
+ * note is kept only when it fits inside the existing fret span — edge
+ * tones are never added at the cost of a stretch.
+ *
+ * Fret geometry comes from building the shape (at root C) in
+ * `options.tuning`. Interval labels, `rootString`, and `span` are otherwise
+ * unchanged; `name`/`quality`/`parentShape` follow `relabelShape`'s option
+ * semantics (`parentShape` defaults to the input shape's name).
+ *
+ * Returns `undefined` for an invalid `tone`, a shape that does not build,
+ * or when no passing tone can be placed.
+ */
+declare function addPassingTone(shape: ScaleShape, tone: string, options?: PassingToneOptions): ScaleShape | undefined;
 
 /**
  * Tonal integration: connects guitar shapes to Scale, Chord, Mode, Key, and Pcset.
@@ -1818,4 +1857,4 @@ declare const SEQ_UP_DOWN: number[];
 declare const SEQ_TRIAD_CLIMB: number[];
 declare const SEQ_1357_DESC: number[];
 
-export { ASCENDING_THIRDS, type AddChange, type AlphaTexOptions, type ArpeggioResolution, type ArpeggioShape, type ArpeggioSlot, type ArpeggioTier, type AsciiTabOptions, type AuditSeverity, type Barre, CHECK_BARRE_FRET_ORIGIN, CHECK_BUILD_LOSS, CHECK_CHORD_TONES_ONLY, CHECK_CONTAINS_CHORD_GRIP, CHECK_COVERS_CHORD, CHECK_FINGERING_COMPLETE, CHECK_FINGER_ZERO_ON_MOVABLE, CHECK_FRET_SPAN, CHECK_GEOMETRY_MISMATCH, CHECK_IDENTIFY_MISMATCH, CHECK_METADATA_COMPLETENESS, CHECK_NAME_UNIQUE, CHECK_OVERRIDES_TARGET, CHECK_POSITION_SPAN, CHECK_REPEATED_FINGER_NO_BARRE, CHECK_STRINGSET_MISMATCH, CHECK_TUNING_MISMATCH, CHORD_SCALE_RULE, CHORD_SCALE_RULE_VERSION, type CagedPosition, type ChainDirection, type Changeset, type ChangesetChange, type ChangesetKind, type ChordGeometryDetails, type ChordScaleEntry, type ChordShape, type ChordShapeAuditResult, type ConnectSequencesInput, type ConnectSequencesResult, type ConnectorOptions, type ConnectorStrategy, type ContainingScale, DADGAD, DEFAULT_SCALE_CORPUS, DESCENDING_THIRDS, DROP_D, type Fingering, type FretboardPosition, type FrettedNote, type FrettedScale, type InferenceCandidate, type InferenceInput, type InferenceOptions, type InferenceProbe, type KeyAnalysis, NoFrettedScale, OPEN_G, type RelabelOptions, type RemoveChange, SEQ_1234_GROUP, SEQ_1235, SEQ_1357_DESC, SEQ_TRIAD_CLIMB, SEQ_UP_DOWN, SHELL_DICTIONARY, STANDARD, STANDARD_7, STANDARD_8, type ScaleShape, type ScalesContainingChordOptions, type ScalesContainingChordResult, type ScoreBreakdown, type SequenceOptions, type ShapeAuditIssue, type ShapeAuditOptions, type UpdateChange, VERSION, type VoicingFamily, type VoicingPatternDictionary, type WalkOptions, type WalkShapeOptions, absoluteBarreFret, add, all, analyzeInKey, applyChordShape, applySequence, arpeggioFor, arpeggioFromScale, arpeggioFromShape, arpeggioShapes, arpeggioSlotKey, ascendingIntervals, ascendingLinear, auditAllShapes, auditAllShapesIntegration, auditArpeggioShape, auditArpeggioShapeIntegration, auditChordShape, auditChordShapeFull, auditChordShapeIntegration, auditScaleShape, autoFingering, buildFrettedScale, buildFromScale, checkBarreFretOrigin, checkChordBuildLoss, checkChordMetadataCompleteness, checkChordTonesOnly, checkContainsChordGrip, checkCoversChord, checkFingerZeroOnMovable, checkFingeringComplete, checkFretSpan, checkGeometryMismatch, checkIdentifyMismatch, checkNameUnique, checkOverridesTarget, checkPositionSpan, checkRepeatedFingerNoBarre, checkScaleBuildLoss, checkScaleMetadataCompleteness, checkStringsetMismatch, checkTuningMismatch, chordShapeGeometry, chordShapes, connectSequences, descendingIntervals, descendingLinear, displayRootFor, exportIdentifierFor, filterChordTones, findFretInPosition, findNearestFret, findNote, flattenSequence, formatChordFrets, fourths, fretFor, fretboard, get, gripBaseFret, grouping, identifyChord, impliedStringSet, inferShapeContext, isMovable, isShapeCompatible, modeShapes, names, noteAt, parentBoxForChordShape, parseChordFrets, parseScalePattern, playedStringSet, relabelShape, relabelShapeToScale, relatedScales, remove, removeAll, resolveArpeggioForSlot, scaleTypeForChordType, scalesContainingChord, scoreShapeMatch, sixths, slotForChordShape, sourceGripBaseFret, thirds, toAlphaTeX, toAsciiTab, visibleArpeggios, walkPattern, walkShape, walkShapeIntervals, walkShapeMotif };
+export { ASCENDING_THIRDS, type AddChange, type AlphaTexOptions, type ArpeggioResolution, type ArpeggioShape, type ArpeggioSlot, type ArpeggioTier, type AsciiTabOptions, type AuditSeverity, type Barre, CHECK_BARRE_FRET_ORIGIN, CHECK_BUILD_LOSS, CHECK_CHORD_TONES_ONLY, CHECK_CONTAINS_CHORD_GRIP, CHECK_COVERS_CHORD, CHECK_FINGERING_COMPLETE, CHECK_FINGER_ZERO_ON_MOVABLE, CHECK_FRET_SPAN, CHECK_GEOMETRY_MISMATCH, CHECK_IDENTIFY_MISMATCH, CHECK_METADATA_COMPLETENESS, CHECK_NAME_UNIQUE, CHECK_OVERRIDES_TARGET, CHECK_POSITION_SPAN, CHECK_REPEATED_FINGER_NO_BARRE, CHECK_STRINGSET_MISMATCH, CHECK_TUNING_MISMATCH, CHORD_SCALE_RULE, CHORD_SCALE_RULE_VERSION, type CagedPosition, type ChainDirection, type Changeset, type ChangesetChange, type ChangesetKind, type ChordGeometryDetails, type ChordScaleEntry, type ChordShape, type ChordShapeAuditResult, type ConnectSequencesInput, type ConnectSequencesResult, type ConnectorOptions, type ConnectorStrategy, type ContainingScale, DADGAD, DEFAULT_SCALE_CORPUS, DESCENDING_THIRDS, DROP_D, type Fingering, type FretboardPosition, type FrettedNote, type FrettedScale, type InferenceCandidate, type InferenceInput, type InferenceOptions, type InferenceProbe, type KeyAnalysis, NoFrettedScale, OPEN_G, type PassingToneOptions, type RelabelOptions, type RemoveChange, SEQ_1234_GROUP, SEQ_1235, SEQ_1357_DESC, SEQ_TRIAD_CLIMB, SEQ_UP_DOWN, SHELL_DICTIONARY, STANDARD, STANDARD_7, STANDARD_8, type ScaleShape, type ScalesContainingChordOptions, type ScalesContainingChordResult, type ScoreBreakdown, type SequenceOptions, type ShapeAuditIssue, type ShapeAuditOptions, type UpdateChange, VERSION, type VoicingFamily, type VoicingPatternDictionary, type WalkOptions, type WalkShapeOptions, absoluteBarreFret, add, addPassingTone, all, analyzeInKey, applyChordShape, applySequence, arpeggioFor, arpeggioFromScale, arpeggioFromShape, arpeggioShapes, arpeggioSlotKey, ascendingIntervals, ascendingLinear, auditAllShapes, auditAllShapesIntegration, auditArpeggioShape, auditArpeggioShapeIntegration, auditChordShape, auditChordShapeFull, auditChordShapeIntegration, auditScaleShape, autoFingering, buildFrettedScale, buildFromScale, checkBarreFretOrigin, checkChordBuildLoss, checkChordMetadataCompleteness, checkChordTonesOnly, checkContainsChordGrip, checkCoversChord, checkFingerZeroOnMovable, checkFingeringComplete, checkFretSpan, checkGeometryMismatch, checkIdentifyMismatch, checkNameUnique, checkOverridesTarget, checkPositionSpan, checkRepeatedFingerNoBarre, checkScaleBuildLoss, checkScaleMetadataCompleteness, checkStringsetMismatch, checkTuningMismatch, chordShapeGeometry, chordShapes, connectSequences, descendingIntervals, descendingLinear, displayRootFor, exportIdentifierFor, filterChordTones, findFretInPosition, findNearestFret, findNote, flattenSequence, formatChordFrets, fourths, fretFor, fretboard, get, gripBaseFret, grouping, identifyChord, impliedStringSet, inferShapeContext, isMovable, isShapeCompatible, modeShapes, names, noteAt, parentBoxForChordShape, parseChordFrets, parseScalePattern, playedStringSet, relabelShape, relabelShapeToScale, relatedScales, remove, removeAll, resolveArpeggioForSlot, scaleTypeForChordType, scalesContainingChord, scoreShapeMatch, sixths, slotForChordShape, sourceGripBaseFret, thirds, toAlphaTeX, toAsciiTab, visibleArpeggios, walkPattern, walkShape, walkShapeIntervals, walkShapeMotif };

package/dist/index.d.ts

@@ -80,9 +80,8 @@ interface Barre {
  * IS a `ScaleShape` (it only narrows `chordType` to required and adds a few
  * arpeggio-specific fields), so `buildFrettedScale`, `walkShape`,
  * `inferShapeContext` and `checkScaleBuildLoss` all work unchanged on it
- * with no code changes in this feature. No seed data ships for this
- * interface yet — see the `arpeggioShapes` registry (later group) for where
- * it starts getting populated.
+ * with no code changes in this feature. Built-in seeds live in
+ * `data/caged-arpeggios.ts` (registered into `arpeggioShapes`).
  */
 interface ArpeggioShape extends ScaleShape {
     chordType: string;
@@ -131,9 +130,13 @@ declare function playedStringSet(shape: ChordShape): number[];
  */
 declare function impliedStringSet(shape: ChordShape): number[];
 /**
- * The grip base fret for a set of per-string frets: the minimum *fretted*
- * (non-null, non-zero) fret, or `0` when there are no fretted strings (all
- * open/muted). Open strings (`0`) never set the grip base — see D-010.
+ * The grip base fret for a set of per-string frets: the minimum *played*
+ * (non-null) fret, open strings (`0`) included, or `0` when every string is
+ * muted. Including open strings is what makes the base root-invariant
+ * (D-010 as amended by CR-002 / #192): a shape whose root string lands on
+ * the nut at one root (E Shape at E, A Form at A, ...) keeps the same
+ * base-relative geometry as at every other root, so a `Barre.fret` offset
+ * resolves correctly everywhere.
  */
 declare function gripBaseFret(frets: (number | null)[]): number;
 /**
@@ -446,7 +449,7 @@ declare function autoFingering(shape: Omit<ChordShape, "fingers" | "barres">, ro
     barres: Barre[];
 };
 
-declare const VERSION = "0.3.0";
+declare const VERSION = "0.4.0";
 
 /**
  * Shape visual/quality audit checks.
@@ -641,9 +644,9 @@ declare function checkTuningMismatch(shape: ChordShape, tuning?: string[]): Shap
  * Flags a `Barre.fret` that cannot be a valid grip-base offset (D-010):
  *
  * 1. `fret < 0` — an offset is never negative.
- * 2. `fret > span` — `span` is the shape's own fretted span (same
- *    `checkFretSpan` computation: max − min over non-null, non-open built
- *    frets), and an offset can never exceed the span it's measured within.
+ * 2. `fret > span` — `span` is the range the offset is measured within:
+ *    the highest played built fret minus the grip base (`gripBaseFret`,
+ *    open strings included), so an offset can never exceed it.
  * 3. For `baseFret`-carrying shapes with a resolvable grip root (see
  *    `chordShapeGeometry`): `fret` equals the ABSOLUTE fret the source
  *    diagram implies for the barre's strings (`sourceFrets[barre.fromString]`)
@@ -656,6 +659,14 @@ declare function checkTuningMismatch(shape: ChordShape, tuning?: string[]): Shap
  *    `extended-chords.ts`, `caged-chords*.ts`) have since had their own
  *    pre-D-010 absolute barre frets migrated to grip-base offsets too
  *    (CR-001).
+ * 4. The offset resolves (`absoluteBarreFret(barre, gripBase)`) to a fret
+ *    that doesn't match the grip: a string under the barre carrying the
+ *    barre's finger sits at a different fret, or a played string under the
+ *    barre sits below it. This is the root-invariance gate (CR-002 / #192):
+ *    because built grips transpose rigidly and the grip base includes open
+ *    strings, an offset that passes here at one root passes at every root —
+ *    so it also catches offsets still measured from the old open-string-
+ *    excluding base.
  *
  * `root`/`tuning`/`prebuilt` mirror `checkFretSpan`'s signature so
  * `auditChordShape` can thread its single hoisted `applyChordShape` build in
@@ -1289,10 +1300,13 @@ declare function scoreShapeMatch(probe: InferenceProbe, _shape: ScaleShape, root
 /**
  * Shape relabeling: rewrite a ScaleShape's per-string interval labels into
  * a different (rotation-compatible) interval frame, e.g. turning a
- * major-frame CAGED shape into its natural-minor labeling.
+ * major-frame CAGED shape into its natural-minor labeling — and
+ * passing-tone augmentation (`addPassingTone`), e.g. adding the b5 that
+ * turns a minor pentatonic box into a blues box.
  *
- * Pure tier — MAY import `@tonaljs/interval` (required peer, already used
- * by build.ts) and `./shape` (types only). MUST NOT import
+ * Required-peer tier — MAY import `@tonaljs/interval`, `./build` (for
+ * `addPassingTone`'s fret geometry), `./tuning`, and `./shape` (types
+ * only). MUST NOT import
  * `@tonaljs/scale`/`@tonaljs/chord`/`@tonaljs/key` or `./integration`, so
  * `src/data/*` can call this at import time with zero optional peers.
  */
@@ -1314,6 +1328,31 @@ interface RelabelOptions {
  * convention, cf. `src/build.ts:188,192`) when no valid relabeling exists.
  */
 declare function relabelShape(shape: ScaleShape, targetIntervals: string[], options?: RelabelOptions): ScaleShape | undefined;
+interface PassingToneOptions extends RelabelOptions {
+    tuning?: string[];
+}
+/**
+ * Add a chromatic passing tone to a shape, e.g. the b5 (`"5d"`) that turns
+ * a minor pentatonic box into a minor blues box, or the b3 (`"3m"`) that
+ * turns a major pentatonic box into a major blues box.
+ *
+ * Placement rule: `tone` is inserted on the same string, one fret above
+ * every note whose chroma is a semitone below `tone` (the b5 sits right
+ * above each 4P). Every inserted tone that lands inside the shape's
+ * existing pitch range is kept, even when it needs a one-fret stretch past
+ * the shape's fret span. A tone that would become the shape's new highest
+ * note is kept only when it fits inside the existing fret span — edge
+ * tones are never added at the cost of a stretch.
+ *
+ * Fret geometry comes from building the shape (at root C) in
+ * `options.tuning`. Interval labels, `rootString`, and `span` are otherwise
+ * unchanged; `name`/`quality`/`parentShape` follow `relabelShape`'s option
+ * semantics (`parentShape` defaults to the input shape's name).
+ *
+ * Returns `undefined` for an invalid `tone`, a shape that does not build,
+ * or when no passing tone can be placed.
+ */
+declare function addPassingTone(shape: ScaleShape, tone: string, options?: PassingToneOptions): ScaleShape | undefined;
 
 /**
  * Tonal integration: connects guitar shapes to Scale, Chord, Mode, Key, and Pcset.
@@ -1818,4 +1857,4 @@ declare const SEQ_UP_DOWN: number[];
 declare const SEQ_TRIAD_CLIMB: number[];
 declare const SEQ_1357_DESC: number[];
 
-export { ASCENDING_THIRDS, type AddChange, type AlphaTexOptions, type ArpeggioResolution, type ArpeggioShape, type ArpeggioSlot, type ArpeggioTier, type AsciiTabOptions, type AuditSeverity, type Barre, CHECK_BARRE_FRET_ORIGIN, CHECK_BUILD_LOSS, CHECK_CHORD_TONES_ONLY, CHECK_CONTAINS_CHORD_GRIP, CHECK_COVERS_CHORD, CHECK_FINGERING_COMPLETE, CHECK_FINGER_ZERO_ON_MOVABLE, CHECK_FRET_SPAN, CHECK_GEOMETRY_MISMATCH, CHECK_IDENTIFY_MISMATCH, CHECK_METADATA_COMPLETENESS, CHECK_NAME_UNIQUE, CHECK_OVERRIDES_TARGET, CHECK_POSITION_SPAN, CHECK_REPEATED_FINGER_NO_BARRE, CHECK_STRINGSET_MISMATCH, CHECK_TUNING_MISMATCH, CHORD_SCALE_RULE, CHORD_SCALE_RULE_VERSION, type CagedPosition, type ChainDirection, type Changeset, type ChangesetChange, type ChangesetKind, type ChordGeometryDetails, type ChordScaleEntry, type ChordShape, type ChordShapeAuditResult, type ConnectSequencesInput, type ConnectSequencesResult, type ConnectorOptions, type ConnectorStrategy, type ContainingScale, DADGAD, DEFAULT_SCALE_CORPUS, DESCENDING_THIRDS, DROP_D, type Fingering, type FretboardPosition, type FrettedNote, type FrettedScale, type InferenceCandidate, type InferenceInput, type InferenceOptions, type InferenceProbe, type KeyAnalysis, NoFrettedScale, OPEN_G, type RelabelOptions, type RemoveChange, SEQ_1234_GROUP, SEQ_1235, SEQ_1357_DESC, SEQ_TRIAD_CLIMB, SEQ_UP_DOWN, SHELL_DICTIONARY, STANDARD, STANDARD_7, STANDARD_8, type ScaleShape, type ScalesContainingChordOptions, type ScalesContainingChordResult, type ScoreBreakdown, type SequenceOptions, type ShapeAuditIssue, type ShapeAuditOptions, type UpdateChange, VERSION, type VoicingFamily, type VoicingPatternDictionary, type WalkOptions, type WalkShapeOptions, absoluteBarreFret, add, all, analyzeInKey, applyChordShape, applySequence, arpeggioFor, arpeggioFromScale, arpeggioFromShape, arpeggioShapes, arpeggioSlotKey, ascendingIntervals, ascendingLinear, auditAllShapes, auditAllShapesIntegration, auditArpeggioShape, auditArpeggioShapeIntegration, auditChordShape, auditChordShapeFull, auditChordShapeIntegration, auditScaleShape, autoFingering, buildFrettedScale, buildFromScale, checkBarreFretOrigin, checkChordBuildLoss, checkChordMetadataCompleteness, checkChordTonesOnly, checkContainsChordGrip, checkCoversChord, checkFingerZeroOnMovable, checkFingeringComplete, checkFretSpan, checkGeometryMismatch, checkIdentifyMismatch, checkNameUnique, checkOverridesTarget, checkPositionSpan, checkRepeatedFingerNoBarre, checkScaleBuildLoss, checkScaleMetadataCompleteness, checkStringsetMismatch, checkTuningMismatch, chordShapeGeometry, chordShapes, connectSequences, descendingIntervals, descendingLinear, displayRootFor, exportIdentifierFor, filterChordTones, findFretInPosition, findNearestFret, findNote, flattenSequence, formatChordFrets, fourths, fretFor, fretboard, get, gripBaseFret, grouping, identifyChord, impliedStringSet, inferShapeContext, isMovable, isShapeCompatible, modeShapes, names, noteAt, parentBoxForChordShape, parseChordFrets, parseScalePattern, playedStringSet, relabelShape, relabelShapeToScale, relatedScales, remove, removeAll, resolveArpeggioForSlot, scaleTypeForChordType, scalesContainingChord, scoreShapeMatch, sixths, slotForChordShape, sourceGripBaseFret, thirds, toAlphaTeX, toAsciiTab, visibleArpeggios, walkPattern, walkShape, walkShapeIntervals, walkShapeMotif };
+export { ASCENDING_THIRDS, type AddChange, type AlphaTexOptions, type ArpeggioResolution, type ArpeggioShape, type ArpeggioSlot, type ArpeggioTier, type AsciiTabOptions, type AuditSeverity, type Barre, CHECK_BARRE_FRET_ORIGIN, CHECK_BUILD_LOSS, CHECK_CHORD_TONES_ONLY, CHECK_CONTAINS_CHORD_GRIP, CHECK_COVERS_CHORD, CHECK_FINGERING_COMPLETE, CHECK_FINGER_ZERO_ON_MOVABLE, CHECK_FRET_SPAN, CHECK_GEOMETRY_MISMATCH, CHECK_IDENTIFY_MISMATCH, CHECK_METADATA_COMPLETENESS, CHECK_NAME_UNIQUE, CHECK_OVERRIDES_TARGET, CHECK_POSITION_SPAN, CHECK_REPEATED_FINGER_NO_BARRE, CHECK_STRINGSET_MISMATCH, CHECK_TUNING_MISMATCH, CHORD_SCALE_RULE, CHORD_SCALE_RULE_VERSION, type CagedPosition, type ChainDirection, type Changeset, type ChangesetChange, type ChangesetKind, type ChordGeometryDetails, type ChordScaleEntry, type ChordShape, type ChordShapeAuditResult, type ConnectSequencesInput, type ConnectSequencesResult, type ConnectorOptions, type ConnectorStrategy, type ContainingScale, DADGAD, DEFAULT_SCALE_CORPUS, DESCENDING_THIRDS, DROP_D, type Fingering, type FretboardPosition, type FrettedNote, type FrettedScale, type InferenceCandidate, type InferenceInput, type InferenceOptions, type InferenceProbe, type KeyAnalysis, NoFrettedScale, OPEN_G, type PassingToneOptions, type RelabelOptions, type RemoveChange, SEQ_1234_GROUP, SEQ_1235, SEQ_1357_DESC, SEQ_TRIAD_CLIMB, SEQ_UP_DOWN, SHELL_DICTIONARY, STANDARD, STANDARD_7, STANDARD_8, type ScaleShape, type ScalesContainingChordOptions, type ScalesContainingChordResult, type ScoreBreakdown, type SequenceOptions, type ShapeAuditIssue, type ShapeAuditOptions, type UpdateChange, VERSION, type VoicingFamily, type VoicingPatternDictionary, type WalkOptions, type WalkShapeOptions, absoluteBarreFret, add, addPassingTone, all, analyzeInKey, applyChordShape, applySequence, arpeggioFor, arpeggioFromScale, arpeggioFromShape, arpeggioShapes, arpeggioSlotKey, ascendingIntervals, ascendingLinear, auditAllShapes, auditAllShapesIntegration, auditArpeggioShape, auditArpeggioShapeIntegration, auditChordShape, auditChordShapeFull, auditChordShapeIntegration, auditScaleShape, autoFingering, buildFrettedScale, buildFromScale, checkBarreFretOrigin, checkChordBuildLoss, checkChordMetadataCompleteness, checkChordTonesOnly, checkContainsChordGrip, checkCoversChord, checkFingerZeroOnMovable, checkFingeringComplete, checkFretSpan, checkGeometryMismatch, checkIdentifyMismatch, checkNameUnique, checkOverridesTarget, checkPositionSpan, checkRepeatedFingerNoBarre, checkScaleBuildLoss, checkScaleMetadataCompleteness, checkStringsetMismatch, checkTuningMismatch, chordShapeGeometry, chordShapes, connectSequences, descendingIntervals, descendingLinear, displayRootFor, exportIdentifierFor, filterChordTones, findFretInPosition, findNearestFret, findNote, flattenSequence, formatChordFrets, fourths, fretFor, fretboard, get, gripBaseFret, grouping, identifyChord, impliedStringSet, inferShapeContext, isMovable, isShapeCompatible, modeShapes, names, noteAt, parentBoxForChordShape, parseChordFrets, parseScalePattern, playedStringSet, relabelShape, relabelShapeToScale, relatedScales, remove, removeAll, resolveArpeggioForSlot, scaleTypeForChordType, scalesContainingChord, scoreShapeMatch, sixths, slotForChordShape, sourceGripBaseFret, thirds, toAlphaTeX, toAsciiTab, visibleArpeggios, walkPattern, walkShape, walkShapeIntervals, walkShapeMotif };