pepperscore 0.3.0 → 0.4.0

package/dist/instruments.d.ts

@@ -0,0 +1,2 @@
+export * from './lib/instrument-model';
+export * from './lib/range-fit-core';

package/dist/instruments.js

@@ -0,0 +1,2 @@
+import { _ as e, a as t, c as n, d as r, f as i, g as a, h as o, i as s, l as c, m as l, n as u, o as d, p as f, r as p, s as m, t as h, u as g, v as _ } from "./range-fit-core-B1rMWdI4.js";
+export { t as EMBED_INSTRUMENTS, d as INSTRUMENTS, m as INSTRUMENT_IDS, n as LEVELS, h as applyOverrides, c as instrumentFor, g as instrumentName, u as joinRuns, r as keyAlter, i as pitchMidi, p as planShifts, f as spellMidi, l as spelledSoundingMidi, s as tieChainOf, o as transposePitch, a as transposePitchSpelled, e as writtenKeyFifths, _ as writtenPitch };

package/dist/lib/chrome.d.ts

@@ -1,6 +1,6 @@
 /** Chrome presets (docs/specs/pepperscore-embeddable-component.md, "Chrome presets") and per-control overrides. No runtime imports. */
 export type ChromePreset = 'full' | 'minimal' | 'none';
-export type PepperScoreControls = Partial<Record<'mixer' | 'openFile' | 'drawer' | 'transport' | 'viewToggle' | 'zoom' | 'tabToggle', boolean>>;
+export type PepperScoreControls = Partial<Record<'mixer' | 'openFile' | 'drawer' | 'transport' | 'viewToggle' | 'zoom' | 'tabToggle' | 'instrumentSwitch' | 'octaveTool', boolean>>;
 export type ResolvedChrome = {
     header: boolean;
     transport: boolean;
@@ -11,6 +11,10 @@ export type ResolvedChrome = {
     zoom: boolean;
     /** The Notation / TAB / Both switch (shown only for a score with a stave that can take TAB). */
     tabToggle: boolean;
+    /** The instrument switcher (instrument, level and fit to range per part). */
+    instrumentSwitch: boolean;
+    /** The reader's octave tool (move notes or passages by an octave). */
+    octaveTool: boolean;
     /** The overlaid play/stop button of `minimal`. */
     compactPlay: boolean;
     /** Playhead, note highlight and follow. */
@@ -24,6 +28,7 @@ export type ResolvedChrome = {
  * `transport` covers stop, play, BPM, transpose, key flip and bars; `viewToggle` the Vertical/Endless toggle; `openFile` the
  * Open button, file input, open dialog and reopen offer; `mixer` the mixer and the part icons / instrument picker / stave
  * eyes; `zoom` the stave-scale slider, pinch zoom and the page arrows row; `drawer` the bottom drawer and its handle;
- * `tabToggle` the Notation / TAB / Both switch (header and drawer).
+ * `tabToggle` the Notation / TAB / Both switch (header and drawer); `instrumentSwitch` the instrument switcher;
+ * `octaveTool` the octave tool. Each defaults to on for `full`, off otherwise.
  */
 export declare function resolveChrome(preset?: ChromePreset, controls?: PepperScoreControls): ResolvedChrome;

package/dist/lib/file-state.d.ts

@@ -2,6 +2,9 @@ import { type InstrumentId, type Score } from './score';
 import { type DeviceClass } from './stave-scale';
 import { clampBpm, MAX_BPM, MIN_BPM, type AnnotationSize } from './prefs';
 import type { TabView } from './tab/tab-parts';
+import type { PartSound, PartSwitch } from './instrument-view';
+import type { Shift } from './range-fit-core';
+import { type RangeLevel } from './instrument-model';
 export type FileSource = {
     name: string;
     size: number;
@@ -43,11 +46,16 @@ export type ScoreView = {
     zoom: number;
     zoomDevice: DeviceClass;
 };
+/**
+ * `switch`: the reader's instrument switch of this staff part (instrument-view.ts `PartSwitch`; `octaves` by
+ * `ScoreNote.id`). Added after version 2 shipped: optional, and an unusable one is dropped (the part opens as written).
+ */
 export type PartState = {
     visible: boolean;
     instrument: InstrumentId;
     gmSoundfont?: string;
     volume?: number;
+    switch?: SavedSwitch;
 };
 /** Per-score record (schema: file-state.schema.json). Only settings and hashes, never score content. */
 export type FileState = {
@@ -58,6 +66,12 @@ export type FileState = {
     settings: SavedSettings;
     parts: Record<string, PartState>;
     view?: ScoreView;
+    /**
+     * The host's instrument settings when the record was saved (instrument-switch-state.ts `hostInstrumentKey`); a host
+     * whose settings differ on the next load applies them again over the saved switches. Added after version 2 shipped:
+     * optional, absent when the host gave none, dropped when unusable.
+     */
+    hostInstruments?: string;
 };
 /** The localStorage v1 record: zoom was a multiplier of the width fit and lived in settings. */
 export type FileStateV1 = {
@@ -93,6 +107,19 @@ export declare function fileSource(file: Pick<File, 'name' | 'size'>, bytes: Uin
 export declare const fileSourceFor: (name: string, size: number, sha256: string) => FileSource;
 /** Source identity for text without a file (the sample, pasted ABC, the musicXml prop): a hash of the text with a format prefix. */
 export declare function textSource(format: string, text: string, name: string): FileSource;
+/** A part's switch as saved in its record (`PartState.switch`); `sound` only with an `instrument`. */
+export type SavedSwitch = {
+    instrument?: InstrumentId;
+    level: RangeLevel;
+    autoRange: boolean;
+    octaves?: Record<string, Shift>;
+    sound?: PartSound;
+};
+export declare const isLevel: (value: unknown) => value is RangeLevel;
+/** A switch target: any model instrument but the drum kit (unpitched). */
+export declare const isSwitchTarget: (value: unknown) => value is InstrumentId;
+/** A part's switch as saved, or undefined for no entry. */
+export declare function savedSwitch(entry: PartSwitch | undefined): SavedSwitch | undefined;
 /** Validate a stored v1 (legacy localStorage) record for `sha256`. */
 export declare function parseLegacyFileState(raw: unknown, sha256: string): FileStateV1 | null;
 /**
@@ -105,4 +132,4 @@ export declare function migrateFileState(legacy: FileStateV1, device: DeviceClas
 export declare function parseFileState(raw: unknown, sha256: string): FileState | null;
 /** Read the legacy localStorage v1 record for a source. */
 export declare function readFileState(source: FileSource): FileStateV1 | null;
-export declare function buildFileState(source: FileSource, settings: FileSettings, score: Score, hiddenIds: string[], volumes?: Record<string, number>, view?: ScoreView, lastOpened?: number): FileState;
+export declare function buildFileState(source: FileSource, settings: FileSettings, score: Score, hiddenIds: string[], volumes?: Record<string, number>, view?: ScoreView, lastOpened?: number, switches?: Record<string, PartSwitch>, hostInstruments?: string): FileState;

package/dist/lib/instrument-model.d.ts

@@ -0,0 +1,80 @@
+/** The instrument model shared by the reader, the embeds and the editor (`pepperscore/instruments`); framework-free. */
+/** The viewer's instrument ids. */
+export declare const INSTRUMENT_IDS: readonly ["piano", "guitar", "bassguitar", "double-bass", "drum-kit", "alto-saxophone", "tenor-saxophone", "bari-saxophone", "flute", "clarinet", "trumpet", "trombone", "violin", "viola", "cello", "microphone"];
+export declare const LEVELS: readonly ["beginner", "intermediate", "advanced"];
+export type InstrumentId = typeof INSTRUMENT_IDS[number];
+export type RangeLevel = typeof LEVELS[number];
+/** An instrument a pitched part can be switched to: any but the drum kit (unpitched). */
+export type SwitchInstrumentId = Exclude<InstrumentId, 'drum-kit'>;
+export type Transposition = {
+    semitones: number;
+    diatonic: number;
+};
+export type InstrumentClef = 'treble' | 'bass' | 'alto' | 'tenor' | 'percussion' | 'treble8vb';
+export type SpelledPitch = {
+    step: 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G';
+    octave: number;
+    alter: number;
+};
+export type InstrumentInfo = {
+    id: InstrumentId;
+    label: string;
+    /** The name the editor's controls and status line use when shorter than `label` ("Alto Sax"). */
+    short?: string;
+    /** 1-based GM program (the viewer's voice program); the drum kit plays on channel 10, not a program. */
+    gmProgram: number;
+    clef: InstrumentClef;
+    /** Written minus sounding. */
+    transposition: Transposition;
+    /** Playable range per level in sounding MIDI, inclusive; absent for unpitched instruments. */
+    ranges?: Record<RangeLevel, {
+        low: number;
+        high: number;
+    }>;
+};
+/** The model's instruments by id (frozen). */
+export declare const INSTRUMENTS: Readonly<Record<InstrumentId, Readonly<InstrumentInfo>>>;
+/** The instrument's short name for controls and the status line (`short`, else `label`). */
+export declare const instrumentName: (id: InstrumentId) => string;
+/** The instrument nearest a 1-based GM program; piano when none is near. */
+export declare function instrumentFor(gmProgram: number): Readonly<InstrumentInfo>;
+/** The MIDI number of a pitch (C4 = 60). */
+export declare const pitchMidi: (p: SpelledPitch) => number;
+/** The alteration the key signature (`fifths`) gives `step`. */
+export declare function keyAlter(step: SpelledPitch['step'], fifths: number): number;
+/**
+ * The spelling of MIDI note `target`: the key signature's (`fifths`) spelling if it has one, else the
+ * natural, else a sharp going up (`direction` >= 0) or a flat going down, else the other single
+ * accidental, else a double.
+ */
+export declare function spellMidi(target: number, fifths: number, direction: number): SpelledPitch | undefined;
+/** The sounding MIDI number of a written pitch on an instrument with `transposition` (written minus sounding). */
+export declare function spelledSoundingMidi(pitch: SpelledPitch, transposition: {
+    semitones: number;
+}): number;
+/**
+ * The written pitch of sounding MIDI `soundingMidi` for an instrument with `transposition`, spelled for the
+ * written key `keyFifths`: the key's own accidentals first, then naturals, then sharps for chromatic notes in
+ * sharp keys and C major, flats in flat keys. Only `semitones` is used: a MIDI number carries no spelling to
+ * move by the diatonic interval.
+ */
+export declare function writtenPitch(soundingMidi: number, transposition: Transposition, keyFifths: number): SpelledPitch;
+/**
+ * `pitch` moved by `t`, keeping its spelling: the step moves by `diatonic` (carrying the octave) and the alter
+ * is whatever makes the MIDI number move by `semitones`. When that alter would pass a double accidental the
+ * note is respelled with `writtenPitch` for the key `keyFifths` and `respelled` is true.
+ */
+export declare function transposePitchSpelled(pitch: SpelledPitch, t: Transposition, keyFifths: number): {
+    pitch: SpelledPitch;
+    respelled: boolean;
+};
+/** `pitch` moved by `t`, keeping its spelling (see `transposePitchSpelled`; the fallback spells for C major). */
+export declare const transposePitch: (pitch: SpelledPitch, t: Transposition) => SpelledPitch;
+/**
+ * The written key (fifths) of music in concert key `concertFifths` shown with `transposition` (written minus
+ * sounding): the transposition as fifths, `(7 * semitones) mod 12` normalised to -6..6, added and wrapped
+ * back into -7..7. Alto sax (+9 semitones) is +3 fifths; a B-flat instrument +2.
+ */
+export declare function writtenKeyFifths(concertFifths: number, transposition: Transposition): number;
+/** The instruments the embeds offer, in switch order (frozen). */
+export declare const EMBED_INSTRUMENTS: readonly InstrumentId[];

package/dist/lib/instrument-switch-state.d.ts

@@ -0,0 +1,169 @@
+import { type PartState } from './file-state';
+import { type InstrumentId, type RangeLevel, type SwitchInstrumentId } from './instrument-model';
+import { type InstrumentViewResult, type PartSound, type PartSwitch } from './instrument-view';
+import type { BaseTimeline } from './playback/timeline';
+import type { Shift } from './range-fit-core';
+import { type Part, type Score } from './score';
+export declare const DEFAULT_RANGE_LEVEL: RangeLevel;
+/** The instruments a pitched part can be switched to: the model's, in its order, without the drum kit. */
+export declare const SWITCH_TARGETS: InstrumentId[];
+/** The instrument keys of `PepperScoreSettings` (prefs.ts documents them). */
+export type InstrumentSettings = {
+    instrument?: SwitchInstrumentId;
+    instruments?: Record<string, SwitchInstrumentId>;
+    rangeLevel?: RangeLevel;
+    autoRange?: boolean;
+};
+export type SwitchDefaults = {
+    level: RangeLevel;
+    autoRange: boolean;
+};
+type Switches = Record<string, PartSwitch>;
+/** Source parts in score order, numbered from 1 by the host (TAB doublings excluded), with their staff parts. */
+export declare function sourcePartsOf(score: Score): {
+    id: string;
+    parts: Part[];
+    switchable: boolean;
+}[];
+export declare const switchDefaults: (settings: InstrumentSettings) => SwitchDefaults;
+/**
+ * The parts `onReady` lists (every staff, TAB doublings excluded), each with its 1-based source part number (the
+ * `settings.instruments` key; a grand staff's staves share one) and whether the switch applies to it.
+ */
+export declare function readerPartsInfo(score: Score): {
+    id: string;
+    name: string;
+    sourcePart: number;
+    switchable: boolean;
+}[];
+/**
+ * Change one source part's switch on every staff part it has (a grand staff switches together). Choosing another
+ * instrument (or As written) drops a picked sound: the instrument's main sound plays again. Choosing the current one
+ * keeps it.
+ */
+export declare function withSourceSwitch(score: Score, switches: Switches, sourcePart: string, patch: Partial<Omit<PartSwitch, 'octaves'>>, defaults: SwitchDefaults): Switches;
+/** Set the reader's octave moves (by `ScoreNote.id`) of one staff part. */
+export declare function withOctaves(switches: Switches, partId: string, octaves: Record<string, Shift>, defaults: SwitchDefaults): Switches;
+/**
+ * Drop the reader's "keep as written" pins (an octave override of 0) that the auto-fit plan no longer overrides: after
+ * a level, instrument or fit change (or a host change) the plan of the view these switches give may not move that note
+ * any more, and a stale pin would keep its staff "non-plain" (a saved entry) and block auto-fit if the plan moves the
+ * note again later. A 0 on a note the plan still moves (8vb on an auto-raised phrase: as written) stays, as do 8va / 8vb
+ * moves. The view is the reader's: `scoreForView` at `semitones`, in the pitch view `readerPitch` gives these switches.
+ */
+export declare function withoutStalePins(score: Score, switches: Switches, view: {
+    scorePitch: 'written' | 'concert';
+    semitones: number;
+    keyFlip?: boolean;
+}, defaults: SwitchDefaults): Switches;
+/**
+ * A staff part's label: its own name and, while it is switched to another instrument, that instrument's short name
+ * (the reader shows "Piano → Guitar"). No `switched` when as written, or switched to the instrument the part already is.
+ */
+export declare function partLabel(part: Part, switches: Switches): {
+    name: string;
+    switched?: string;
+};
+/**
+ * The octave tool's selection on one staff part: `ids` (ScoreNote ids, score order, whole tie chains), the note the
+ * selection started from (`anchor`) and whether a plain click extends it to a passage (only after a single-note pick).
+ */
+export type OctaveSelection = {
+    partId: string;
+    anchor: string;
+    ids: string[];
+    extendable: boolean;
+};
+/**
+ * A click on a note with the octave tool on. A note of a switchable part selects its tie chain; with `extend`
+ * (Shift-click), or a plain click after a single-note pick in the same part, it selects every note of that part whose
+ * (measure, start) lies between the anchor and this note, in all voices, each with its tie chain. A note the tool can't
+ * move (a rest, a drum or TAB staff) keeps the selection.
+ */
+export declare function selectOctaveNote(score: Score, current: OctaveSelection | null, noteId: string, extend: boolean): OctaveSelection | null;
+/** "Select phrase": the selection widened to the auto-fit phrases (`phrasesOf`) that contain any of its notes. */
+export declare function selectOctavePhrase(score: Score, selection: OctaveSelection): OctaveSelection;
+/**
+ * 8va / 8vb on the selected notes, from where each is shown (`shifts`: auto-fit and the reader's moves): the new shift
+ * (kept within ±12) is stored as the note's override, 0 included (a note auto-fit moved goes back as written); a
+ * shift auto-fit alone gives (`planned`) needs no override and drops it.
+ */
+export declare function steppedOctaves(octaves: Record<string, Shift>, ids: string[], step: 12 | -12, shifts?: Record<string, Shift>, planned?: Record<string, Shift>): Record<string, Shift>;
+/**
+ * A Sound pick on a staff part: while the part is switched it only overrides the instrument's main sound (the switch
+ * itself is kept); undefined when the part is not switched (the pick then changes the part's own sound).
+ */
+export declare function withSound(switches: Switches, partId: string, sound: PartSound): Switches | undefined;
+/** The host's settings as switches (a score without a saved record). */
+export declare function switchesFromSettings(score: Score, settings: InstrumentSettings): Switches;
+/** A host settings change: only the changed keys are applied again (the reader's other choices stay). */
+export declare function applyHostSwitchChange(score: Score, current: Switches, previous: InstrumentSettings, next: InstrumentSettings): Switches;
+/**
+ * A fingerprint of the host's instrument settings, saved with the record (`FileState.hostInstruments`): only the usable
+ * keys, `instruments` as [key, id] pairs sorted by key. Undefined when the host gives none.
+ */
+export declare function hostInstrumentKey(settings: InstrumentSettings): string | undefined;
+/**
+ * The host's instrument settings applied again over restored switches: every switchable source part takes the host's
+ * instrument (or As written), level and fit. A part whose instrument changes loses its octave moves (and its picked
+ * sound); a part whose instrument stays keeps them.
+ */
+export declare function withHostSwitches(score: Score, switches: Switches, settings: InstrumentSettings): Switches;
+/**
+ * The switches a score opens with. Without a saved record, the host's settings. With one, its switches, unless the
+ * host's instrument settings changed since it was saved (`hostInstrumentKey` differs from `hostInstruments`): then the
+ * host's are applied again over it (`withHostSwitches`), so a teacher's new instrument reaches returning readers. A host
+ * that gives no instrument settings, or the same ones, leaves the reader's saved choices.
+ */
+export declare function switchesOnLoad(score: Score, saved: {
+    parts: Record<string, PartState>;
+    hostInstruments?: string;
+} | null, settings: InstrumentSettings): Switches;
+/**
+ * Switches restored from a saved record's parts (already validated by file-state.ts). The staves of a source part
+ * switch together, so they are normalised to its first staff with a saved switch (instrument, level, fit): a staff
+ * whose switch differs or was dropped takes it, keeping its own octave moves (and its sound when the instrument matches).
+ * A staff left as written with the defaults and no octave moves gets no entry, as `withSourceSwitch` would leave it.
+ */
+export declare function switchesFromSaved(score: Score, parts: Record<string, PartState>, defaults?: SwitchDefaults): Switches;
+/**
+ * The saved pitch view to restore. A concert-basis score used to be forced to (and saved as) concert pitch while no
+ * part was switched to a transposing instrument, so a saved 'concert' there was never the reader's choice: it opens as
+ * 'written', and a later switch to a B♭/E♭ instrument shows its written pitch.
+ */
+export declare function restoredScorePitch(score: Score, switches: Switches, saved: 'written' | 'concert'): 'written' | 'concert';
+/**
+ * The pitch view the reader shows. Verovio can only move written pitch to sounding, so a concert-basis score is shown
+ * at concert pitch, unless a part is switched to a transposing instrument (it shows its written pitch by default).
+ */
+export declare function readerPitch(score: Score, switches: Switches, preferred: 'written' | 'concert'): {
+    scorePitch: "concert" | "written";
+    concertBasis: boolean;
+    forcedConcert: boolean;
+    switchedTransposing: boolean;
+    hasTransposingParts: boolean;
+};
+/**
+ * The Pitch panel's hint for the pitch view `readerPitch` gives. In a concert-basis score the Transposing view moves
+ * only the parts switched to a transposing instrument: every other part (a transposing one included) stays at concert pitch.
+ */
+export declare function pitchHint(view: ReturnType<typeof readerPitch>): string;
+/** The switched view of `scoreForView`'s result (the switch runs last); with no switches, that result itself. */
+export declare function switchedView(viewed: Score, switches: Switches, scorePitch: 'written' | 'concert'): InstrumentViewResult;
+/** Internal highlights of a switched view, applied before the host's. */
+export declare function switchHighlights(view: InstrumentViewResult): {
+    ids: string[];
+    className: string;
+}[];
+/**
+ * The performance with the switched (or octave-moved) parts' events at the view's sounding pitch. The base timeline
+ * is the source score's, at 0 semitones (playback adds `semitones`), so every other part keeps its events as before;
+ * the view's pitches already include `semitones`, so they are taken back out here.
+ */
+export declare function switchedTimeline(base: BaseTimeline, view: InstrumentViewResult, semitones: number): BaseTimeline;
+/**
+ * Parts to play with: a part switched to an instrument plays the target's sound (the view part's), or the sound the
+ * reader picked for it while switched (`PartSwitch.sound`).
+ */
+export declare function switchedSoundParts(parts: Part[], view: InstrumentViewResult, switches: Switches): Part[];
+export {};

package/dist/lib/instrument-view.d.ts

@@ -0,0 +1,92 @@
+import { type InstrumentClef, type InstrumentId, type RangeLevel } from './instrument-model';
+import { type Shift } from './range-fit-core';
+import { type KeyMode, type Measure, type Part, type Score, type ScoreNote } from './score';
+/** The part all staves of one source part share: the MusicXML <score-part id>, or the part's own id for ABC/MIDI. */
+export declare const sourcePartOf: (part: Part) => string;
+/**
+ * The playback sound a reader picked for a switched part (the mixer's Sound grid, like `Part.instrument` and
+ * `gmSoundfont`: the GM sound's icon id and FluidR3 name; no `gmSoundfont` with `instrument: 'drum-kit'` = the kit).
+ */
+export type PartSound = {
+    instrument: InstrumentId;
+    gmSoundfont?: string;
+};
+/**
+ * A reader's switch for one staff part: `instrument` undefined = as written; `octaves` keyed by `ScoreNote.id` (a note's
+ * shift from its pitch in the view, overriding auto-fit along its tie chain; 0 keeps a note auto-fit would move);
+ * `sound` overrides the target's main sound (only while switched; cleared when the instrument changes).
+ */
+export type PartSwitch = {
+    instrument?: InstrumentId;
+    level: RangeLevel;
+    autoRange: boolean;
+    octaves: Record<string, Shift>;
+    sound?: PartSound;
+};
+/**
+ * The MEI pass's view of one switched (or octave-moved) staff: `shift` = [diatonic, semitones] from the baseline MEI
+ * (the source's written pitch, after the global interval) to the pitch shown; `octaves` keyed by MEI note id.
+ */
+export type StaffSwitch = {
+    shift: [number, number];
+    clef?: InstrumentClef;
+    octaves: Record<string, 12 | -12>;
+};
+/**
+ * What the MEI pass needs of one staff of a switched view (carried on `Score.instrumentView`): its `StaffSwitch` and,
+ * for a switched part, its keys [measure index, fifths, mode] before the global transposition (the source's written
+ * keys moved by `shift`), as `SpellingSpec` staves take them.
+ */
+export type EngravedSwitch = StaffSwitch & {
+    keys?: [number, number, KeyMode][];
+};
+export type InstrumentViewResult = {
+    score: Score;
+    /** `ScoreNote.id`s moved by an octave (auto-fit or the reader's). */
+    moved: string[];
+    /** `ScoreNote.id`s still outside the level's range (switched parts), or moved outside it (unswitched parts). */
+    outOfRange: string[];
+    /** Each moved note's octave shift (auto-fit and the reader's), and what auto-fit alone would shift (nonzero only). */
+    shifts: Record<string, Shift>;
+    planned: Record<string, Shift>;
+    /** Keyed by part id. */
+    staves: Record<string, StaffSwitch>;
+    /**
+     * TAB parts doubling a switched or octave-moved part (their frets are stale). The renderer reads the same from
+     * `score.instrumentView` (tab/tab-parts.ts `planTab`): regenerated while the part is a guitar, else hidden.
+     */
+    hiddenTab: string[];
+};
+/**
+ * Whether the switch is offered for a part: never for the drum kit or percussion, nor for TAB staves. Judged on the
+ * part as imported: a Sound pick (`withPickedSound`) changes `instrument` but never what can be switched.
+ */
+export declare const switchablePart: (part: Part) => boolean;
+/**
+ * A part playing a picked sound (the mixer's Sound grid or a saved record): its icon id, GM program and FluidR3 name,
+ * with the instrument it was imported as kept in `importedInstrument`.
+ */
+export declare const withPickedSound: (part: Part, sound: {
+    instrument: InstrumentId;
+    gmProgram?: number;
+    gmSoundfont?: string;
+}) => Part;
+export declare const pitched: (note: ScoreNote) => boolean;
+export declare const byStart: (measure: Measure) => ScoreNote[];
+/** Each pitched note's tie chain in a part, in score order (a note alone when untied). */
+export declare function tieChainsOf(part: Part): (id: string) => string[];
+/** Runs of pitched notes per voice per measure, broken at rests and after a slur end, joined across ties. */
+export declare function phrasesOf(part: Part): string[][];
+/**
+ * Switches parts of a Score view (`scoreForView`'s result) to other instruments and applies the reader's octave
+ * moves. Each part is treated on its own (a grand staff's callers set one `PartSwitch` on every staff). For every
+ * note of every part, `soundingMidi(outPart, measure, pitch, 0)` is its judged pitch (sounding, after the view's
+ * transposition) plus its octave shift: a concert view's transposing parts (already at sounding pitch) lose their
+ * transposition, switched or not. A switched part is written for the target instrument in the written view, at
+ * sounding pitch in the concert view. A target without a pitched clef or ranges (the drum kit) is treated as written.
+ *
+ * The view is the Score's own (`score.pitchView.view`); `scorePitch` only applies to a Score no view was made of.
+ * Throws when `score` already carries an instrument view: apply it once, to `scoreForView`'s result (a second pass
+ * would stack the shifts).
+ */
+export declare function applyInstrumentView(score: Score, switches: Record<string, PartSwitch>, scorePitch: 'written' | 'concert'): InstrumentViewResult;

package/dist/lib/notation/document.d.ts

@@ -1,4 +1,4 @@
-import type { Part, Score } from '../score';
+import type { Part, Score, ScoreNote } from '../score';
 import { type FeatureInventory, type SourceDiagnostic } from './musicxml-source';
 export type { SourceDiagnostic };
 export type SourceFormat = 'musicxml' | 'mxl' | 'mei' | 'abc' | 'midi' | 'sample';
@@ -32,6 +32,16 @@ export type SourceDocument = Readonly<{
     identity: SourceIdentity;
     readOriginalBytes: () => Uint8Array;
 }>;
+/**
+ * The MEI xml:id `scoreToMei` gives pitch `index` of a note (ABC, MIDI and demo scores, whose pitches carry no
+ * `sourceId`). Its continuations into later measures and the pieces of a split duration are separate MEI notes with
+ * `_cN` / `_sN` appended; `generatedPitchIdOf` maps those back to this id.
+ */
+export declare const generatedPitchId: (note: Pick<ScoreNote, "id" | "pitches">, index: number) => string;
+/** The `generatedPitchId` an MEI note of `scoreToMei` was drawn for (its `_cN` / `_sN` suffixes removed), or null. */
+export declare const generatedPitchIdOf: (meiId: string) => string | null;
+/** Whether a document's engraving MEI was generated by `scoreToMei` from the Score (not an imported MEI or MusicXML). */
+export declare const generatedEngraving: (doc: Pick<SourceDocument, "format" | "engravingFormat"> | undefined) => boolean;
 /** Deterministic MEI staffDef ID for a Score part, so views can hide staves by identity. */
 export declare const staffDefXmlId: (partId: string) => string;
 /** Source feature inventory of an XML source (MusicXML, MXL member or MEI), read with the streaming tokenizer. */

package/dist/lib/notation/mei-spelling.d.ts

@@ -9,13 +9,17 @@
  *   degrees, Fb/Cb only as passing notes in keys of 6+ flats, flats-only/sharps-only per key, no double accidentals;
  * - accidentals are re-shown or cancelled within each measure to match the new spellings (@accid / @accid.ges);
  * - chord symbols (`<harm>`) are respelled for their staff's key;
- * - percussion staves never get a key signature or key change (in every view, transposed or not).
+ * - percussion staves never get a key signature or key change (in every view, transposed or not);
+ * - an instrument-switched staff (instrument-view.ts) moves by its own `shift`, takes the target's clef (the source's
+ *   clef changes are dropped), and notes an octave move names (`octaves`) move by an octave, before accidentals are
+ *   re-evaluated.
  *
  * Keys are rewritten from a per-staff timeline (the spec's Score keys, else the MEI's): every key signature is removed
  * from the score definitions and each staff's keys are written where they start or change.
  *
  * String-level like mei-view.ts (the worker has no DOMParser); the input is Verovio's own `getMEI` output.
  */
+import type { InstrumentClef } from '../instrument-model';
 import { type KeyMode } from '../spelling';
 import { type StaffSpelling } from './respell';
 export type SpellingSpec = {
@@ -44,6 +48,10 @@ export type StaffSpec = StaffSpelling & {
      * spellings, e.g. a B♭ trumpet in Ab sounding in F# with C double sharps), the way the Score view does.
      */
     shift?: [number, number];
+    /** Octave moves of notes (instrument switch, range fit or the reader's): semitones by MEI note xml:id. */
+    octaves?: Record<string, 12 | -12>;
+    /** The staff's clef replaced by an instrument switch: set on its staff definitions, its clef changes removed. */
+    clef?: InstrumentClef;
 };
 /** Does this spec change anything for this MEI (a transposition, a flip, or a percussion staff with keys to strip)? */
 export declare function spellingNeeded(mei: string, spec: SpellingSpec | undefined): boolean;

package/dist/lib/notation/mei-tab.d.ts

@@ -33,11 +33,18 @@ export type TabSpec = {
     capo: number;
     /** Use `tab.course`/`tab.fret` already on notation notes as fixed fingerings (false when the view moved pitches). */
     fixed: boolean;
+    /** Generated staves whose `tab.course`/`tab.fret` do not apply even when `fixed` (an instrument view moved their notes). */
+    unfixed?: string[];
     /**
      * Generated staves whose notes are already at sounding pitch (the concert view of a transposing part): their
      * `trans.semi` was applied by spelling and must not be applied again.
      */
     sounding?: string[];
+    /**
+     * Generated staves of a part switched to another instrument (instrument-view.ts), by `@n`: semitones from their
+     * spelled (shown) pitch to sounding pitch, which replace `trans.semi` (a guitar in the written view: -12).
+     */
+    switched?: Record<string, number>;
     /** Imported TAB staves (no notation partner) to re-finger, by staff `@n`: the semitones their pitches move. */
     refret?: Record<string, number>;
 };

package/dist/lib/prefs.d.ts

@@ -1,5 +1,6 @@
 import type { FileSettings } from './file-state';
 import type { TabView } from './tab/tab-parts';
+import type { RangeLevel, SwitchInstrumentId } from './instrument-model';
 export declare const MIN_BPM = 30, MAX_BPM = 240;
 /** The reader's BPM control range; saved and source tempos outside it are clamped. */
 export declare const clampBpm: (bpm: number) => number;
@@ -77,6 +78,22 @@ export type PepperScoreSettings = Partial<{
     bpm: number;
     /** Spell a transposed view in the enharmonic key (F# major shown as Gb major). */
     keyFlip: boolean;
+    /**
+     * Show the first switchable part (every staff of a grand staff) as this instrument: its sound, clef, written pitch
+     * and range. Applied when the score has no saved record, like the other settings.
+     */
+    instrument: SwitchInstrumentId;
+    /**
+     * Instruments per part; wins over `instrument`. A key is either the 1-based source part number as a string
+     * (`{ '2': 'trumpet' }`: score parts in order, a grand staff counted once, a drum kit counted too; `onReady`'s
+     * `parts[].sourcePart`) or an `onReady` part id (`parts[].id`; a staff of a grand staff switches its whole part).
+     * Keys of parts that cannot be switched (`parts[].switchable` false) are ignored.
+     */
+    instruments: Record<string, SwitchInstrumentId>;
+    /** Range level the switched parts are fitted to: `'beginner'`, `'intermediate'` (default) or `'advanced'`. */
+    rangeLevel: RangeLevel;
+    /** Move phrases outside the instrument's range by an octave (default `true`). */
+    autoRange: boolean;
 }>;
 export declare function settingsToPrefs(settings?: PepperScoreSettings): Partial<Prefs>;
 export declare const viewToMode: (view: "vertical" | "endless") => Prefs["mode"];

package/dist/lib/range-fit-core.d.ts

@@ -0,0 +1,26 @@
+export type Shift = 0 | 12 | -12;
+/** One event (note or chord): its notes' judged MIDI (sounding plus interval). */
+export type FitEvent = {
+    id: string;
+    midi: number[];
+};
+/** Merges runs of event ids that a tie links (`[from, to]`), keeping the first run's position. */
+export declare function joinRuns(runs: string[][], ties: [string, string][]): string[][];
+/** The ordered chain of events the ties link around `id` (itself alone when untied), in `order` (event order) when given, else by first appearance in the ties. */
+export declare function tieChainOf(ties: [string, string][], order?: string[]): (id: string) => string[];
+export type ShiftPlan = {
+    shifts: Record<string, Shift>;
+    bothWays: string[][];
+    stillOut: string[][];
+};
+/**
+ * Plans an octave per phrase: any note below the range moves every event up, above moves it down, both
+ * leaves the phrase (listed in `bothWays`); a phrase still out after its move keeps it (listed in
+ * `stillOut`). A chord is out when any of its notes is. No range or `autoRange` off plans no shifts.
+ */
+export declare function planShifts(phrases: FitEvent[][], range: {
+    low: number;
+    high: number;
+} | undefined, autoRange: boolean): ShiftPlan;
+/** Sets single events from the user's overrides, each extended along its tie chain (the first override on a chain wins); overrides beat planned shifts. */
+export declare function applyOverrides(shifts: Record<string, Shift>, overrides: Record<string, Shift>, chainOf: (id: string) => string[]): Record<string, Shift>;

package/dist/lib/score.d.ts

@@ -1,4 +1,5 @@
 import type { SourceDocument } from './notation/document';
+import type { InstrumentId as ModelInstrumentId } from './instrument-model';
 export type Pitch = {
     step: string;
     octave: number;
@@ -112,6 +113,8 @@ export type Measure = {
 };
 export type Part = {
     id: string;
+    /** The MusicXML <score-part id> every staff of one part shares; absent for ABC/MIDI single parts (use `id`). */
+    sourcePartId?: string;
     name: string;
     clef: string;
     key?: number;
@@ -124,6 +127,11 @@ export type Part = {
     measures: Measure[];
     /** A tablature staff (MusicXML clef sign TAB), imported by Verovio as a `tab.guitar` staff. */
     tab?: boolean;
+    /**
+     * The instrument the part was imported as, kept when a reader's Sound pick (or a saved one) replaces `instrument`
+     * with the sound's icon id. What the instrument switch offers keys on it (instrument-view.ts `switchablePart`).
+     */
+    importedInstrument?: InstrumentId;
     /**
      * The part this TAB staff doubles (its notation staff). A doubling TAB part is engraved but never performed, has no
      * annotation lanes and is not listed in part controls, so the instrument shows and plays once (lib/tab/tab-parts.ts).
@@ -144,9 +152,16 @@ export type Score = {
     parts: Part[];
     /** Set on a transposed or flipped view of a score (transpose.ts `scoreForView`). */
     pitchView?: import('./transpose').PitchView;
+    /**
+     * Set on an instrument-switched view (instrument-view.ts `applyInstrumentView`): what the MEI pass needs of its
+     * switched and octave-moved staves, by part id. Dropped by `scoreForView` whenever it moves pitches.
+     */
+    instrumentView?: {
+        staves: Record<string, import('./instrument-view').EngravedSwitch>;
+    };
     document?: SourceDocument;
 };
-export type InstrumentId = 'piano' | 'guitar' | 'bassguitar' | 'double-bass' | 'drum-kit' | 'alto-saxophone' | 'tenor-saxophone' | 'bari-saxophone' | 'flute' | 'clarinet' | 'trumpet' | 'trombone' | 'violin' | 'viola' | 'cello' | 'microphone';
+export type InstrumentId = ModelInstrumentId;
 export declare const GM_FAMILIES: readonly ["Keyboard", "Guitar", "Voice", "Percussion", "Drums", "Woodwinds", "Brass", "Strings", "FX / Other"];
 export type GmFamily = typeof GM_FAMILIES[number];
 export type GmSound = {