pepperscore 0.2.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', boolean>>;
+export type PepperScoreControls = Partial<Record<'mixer' | 'openFile' | 'drawer' | 'transport' | 'viewToggle' | 'zoom' | 'tabToggle' | 'instrumentSwitch' | 'octaveTool', boolean>>;
 export type ResolvedChrome = {
     header: boolean;
     transport: boolean;
@@ -9,6 +9,12 @@ export type ResolvedChrome = {
     mixer: boolean;
     drawer: boolean;
     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. */
@@ -21,6 +27,8 @@ 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.
+ * 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); `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

@@ -1,5 +1,10 @@
 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;
@@ -22,17 +27,35 @@ export type FileSettings = {
     scorePitch: 'written' | 'concert';
     /** Spell the transposed view in the enharmonic key (F# major shown as Gb major); optional on read, default false. */
     keyFlip: boolean;
+    /** Text add-on sizes (prefs.ts ANNOTATION_SIZES); optional on read, default 'rg' (the size every earlier record showed). */
+    namesSize: AnnotationSize;
+    chordSymbolsSize: AnnotationSize;
+    countsSize: AnnotationSize;
+    subdivisionsSize: AnnotationSize;
+    /** TAB view, tuning (open-string MIDI, low to high) and capo; always written (see `SavedSettings` for reading). */
+    tabView: TabView;
+    tabTuning: number[];
+    capo: number;
 };
+/** Settings added after version 2 shipped: a record without them (or with unusable ones) leaves the reader's own. */
+export type LateSettingKey = 'tabView' | 'tabTuning' | 'capo';
+/** Settings as read from a saved record. */
+export type SavedSettings = Omit<FileSettings, LateSettingKey> & Partial<Pick<FileSettings, LateSettingKey>>;
 /** Saved view: an absolute stave scale and the device class it was chosen on (see stave-scale.ts). */
 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 = {
@@ -40,9 +63,15 @@ export type FileState = {
     source: FileSource;
     /** Epoch ms of the last time the score was opened; the store keeps the most recent records. */
     lastOpened: number;
-    settings: FileSettings;
+    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 = {
@@ -53,9 +82,7 @@ export type FileStateV1 = {
     };
     parts: Record<string, PartState>;
 };
-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;
+export { clampBpm, MAX_BPM, MIN_BPM };
 /** The localStorage key of a v1 record; `prefix` is the reader's persist namespace (score-db keyPrefix). */
 export declare const legacyStorageKey: (hash: string, prefix?: string) => string;
 /**
@@ -80,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;
 /**
@@ -92,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/header-controls.d.ts

@@ -6,9 +6,10 @@
  * the header; `secondary` controls sit inline above MOBILE_HEADER_BREAKPOINT
  * and move into the "More controls" dropdown at or below it. PepperScore.tsx maps
  * each id to its element; every control is always rendered (`bars` is disabled outside Vertical view, `keyFlip` when the key has no enharmonic) so the
- * header footprint never depends on client-only state.
+ * header footprint never depends on client-only state. `tab` (the Notation / TAB / Both switch) is the exception: it shows only for a score with a
+ * stave that can take TAB (any pitched part).
  */
-export type HeaderControlId = 'stop' | 'play' | 'openFile' | 'bpm' | 'transpose' | 'keyFlip' | 'mode' | 'bars' | 'staveScale' | 'mixer';
+export type HeaderControlId = 'stop' | 'play' | 'openFile' | 'bpm' | 'transpose' | 'keyFlip' | 'mode' | 'tab' | 'bars' | 'staveScale' | 'mixer';
 export type HeaderControlTier = 'primary' | 'secondary';
 export type HeaderControlConfig = {
     id: HeaderControlId;
@@ -26,6 +27,9 @@ export declare const HEADER_CONTROLS: readonly [{
 }, {
     readonly id: "mode";
     readonly tier: "primary";
+}, {
+    readonly id: "tab";
+    readonly tier: "secondary";
 }, {
     readonly id: "bpm";
     readonly tier: "secondary";
@@ -50,4 +54,4 @@ export declare const MOBILE_HEADER_BREAKPOINT = 760;
 /** Stave scale (zoom) bounds shared by the header slider and pinch zoom live with the defaults in stave-scale.ts. */
 export { clampStaveScale, STAVE_SCALE_MAX, STAVE_SCALE_MIN, STAVE_SCALE_STEP } from './stave-scale';
 /** Which `controls` key shows each header control (see chrome.ts). */
-export declare const HEADER_CONTROL_GROUP: Record<HeaderControlId, 'transport' | 'viewToggle' | 'openFile' | 'zoom' | 'mixer'>;
+export declare const HEADER_CONTROL_GROUP: Record<HeaderControlId, 'transport' | 'viewToggle' | 'openFile' | 'zoom' | 'mixer' | 'tabToggle'>;

package/dist/lib/hit-test.d.ts

@@ -0,0 +1,18 @@
+/** Click hit testing over the drawn notes (pure: the boxes are measured by the caller, in client px). */
+export type HitRect = {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+    width: number;
+    height: number;
+};
+/** A drawn note or rest: its whole box (stem, flag, accidentals, dots, lyrics) and its notehead boxes (a rest: its glyph). */
+export type DrawnNote = {
+    box: HitRect;
+    heads: HitRect[];
+};
+/** The note nearest (x, y): the notehead centre nearest in x, stacked noteheads split by the nearest in y. */
+export declare function nearestNote<T extends DrawnNote>(items: T[], x: number, y: number): T | undefined;
+/** The note whose drawn box (grown by `slop` px) holds (x, y); overlapping boxes go to the nearest notehead. */
+export declare function noteInBox<T extends DrawnNote>(items: T[], x: number, y: number, slop: number): T | undefined;

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/instruments.d.ts

@@ -0,0 +1,82 @@
+import { type SoundPackName } from './assets';
+import { type AudioPlayer } from './sound-players';
+import { type SoundPlan, type SoundRequest, type SoundSource } from './sounds';
+import { type MetronomeVoice } from './metronome';
+export type InstrumentOptions = {
+    /** Root of a pepperscore-sounds-<pack> layout (relative to the page); default: the jsDelivr copy of pepperscore-sounds-<soundPack>. */
+    assetBaseUrl?: string;
+    /** Picks the default assetBaseUrl. With your own assetBaseUrl, its pack.json decides which FluidR3 sounds exist. */
+    soundPack?: SoundPackName;
+    /** Your own sounds, claimed per GM program or for the drum kit (the PepperScore `soundSources` prop). */
+    sources?: readonly SoundSource[];
+    /** Default: the page's shared AudioContext (getSharedAudio). */
+    context?: AudioContext;
+    /** Where the instrument's output goes. Default: the shared master compressor (or `context.destination` for your own context). */
+    destination?: AudioNode;
+    /** Notes to load before the promise resolves. Default: 21-108 for an instrument, none for the drum kit. */
+    notes?: number[];
+};
+/** The public view of an instrument's sound plan. */
+export type InstrumentPlan = {
+    readonly kind: SoundPlan['kind'];
+    readonly sourceId: string;
+};
+/** A loaded sound: an AudioPlayer plus its output gain (volume) and the plan it came from. */
+export type Instrument = AudioPlayer & {
+    readonly context: AudioContext;
+    /** The instrument's volume; connected to `destination`. */
+    readonly output: GainNode;
+    /** Which kind of source plays it and its id (for example `'builtin:fluidr3'`). Read-only; the plan's URLs and presets are internal. */
+    readonly plan: InstrumentPlan;
+    /** Load (decode) these notes; a note starts silently until it is loaded. Drums load TimGM6mb's kit for notes the kit lacks. */
+    loadNotes(notes: number[]): Promise<void>;
+    /** Whether a loaded player can sound this note. */
+    covers(note: number): boolean;
+};
+/** A GM program (1-128), a FluidR3 sound name (`'acoustic_grand_piano'`), or `'drums'` for the GM drum kit (`'drum-kit'`, the score part id, is accepted as an alias). */
+export type InstrumentName = number | string;
+/** The sound request for a program number, a FluidR3 name or 'drums'/'drum-kit'. */
+export declare function instrumentRequest(sound: InstrumentName): SoundRequest;
+/**
+ * Load an instrument through pepperscore's sound resolution. `start()` returns a stop function for that one note;
+ * `stop()` stops every sounding note and cancels every scheduled one. A note's `destination` is honoured by sample-pack
+ * and note-file sounds; SF2 sounds always play through `output`.
+ */
+export declare function loadInstrument(sound: InstrumentName, options?: InstrumentOptions): Promise<Instrument>;
+/** The GM drum kit (`loadInstrument('drums', options)`): Perfect Drums note files, TimGM6mb's kit for notes they lack. */
+export declare const loadDrumKit: (options?: InstrumentOptions) => Promise<Instrument>;
+export type MetronomeOptions = Omit<InstrumentOptions, 'notes'> & {
+    /** Default 'woodblock'. */
+    voice?: MetronomeVoice;
+    /** Output volume, 0-1. Default 0.5 (gentle). */
+    gain?: number;
+};
+export type Metronome = {
+    readonly voice: MetronomeVoice;
+    readonly output: GainNode;
+    /**
+     * Schedule one beat at `time` (AudioContext seconds). `beat` counts from 0 within the bar; beat 0 is accented unless
+     * `accent` says otherwise. Returns a stop function for that beat.
+     */
+    tick(options: {
+        time: number;
+        beat: number;
+        accent?: boolean;
+    }): () => void;
+    /**
+     * Resolves once the drum kit and the notes of the voice given to `createMetronome` have loaded (or failed: then the
+     * synthesized sounds keep playing). `createMetronome` itself does not wait for it.
+     */
+    readonly ready: Promise<void>;
+    /** Switch voice; resolves when the drum kit notes the voice needs have loaded. Until then the voice plays its synthesized sound. A failed load is retried by the next call. */
+    setVoice(voice: MetronomeVoice): Promise<void>;
+    /** Stop every sounding and scheduled beat. */
+    stop(): void;
+    dispose(): void;
+};
+/**
+ * A metronome on the shared AudioContext; drum voices come from the same drum kit loadDrumKit plays. Resolves at once:
+ * the drum kit (a few MB for the woodblock's TimGM6mb kit) loads in the background, and beats play the synthesized
+ * sound until it arrives (`await metronome.ready` to wait).
+ */
+export declare function createMetronome(options?: MetronomeOptions): Promise<Metronome>;

package/dist/lib/metronome.d.ts

@@ -0,0 +1,33 @@
+/**
+ * What a metronome beat sounds like, per voice (public through pepperscore/audio's createMetronome). Pure: no Web Audio
+ * and no runtime imports (validation/audio-api.mjs runs it in Node).
+ * - woodblock: GM hi wood block (76) on beat 1, low wood block (77) on the others, when the drum kit has them; else a
+ *   soft synthesized knock.
+ * - drum-machine: kick (36) on beat 1, closed hi-hat (42) on the others, from the drum kit.
+ * - click: a soft, short synthesized tick.
+ * Beat 1 (`beat` 0) is accented: a louder note, or a higher, louder synth sound.
+ */
+export type MetronomeVoice = 'woodblock' | 'drum-machine' | 'click';
+export declare const METRONOME_VOICES: readonly MetronomeVoice[];
+export type MetronomeHit = {
+    kind: 'note';
+    note: number;
+    velocity: number;
+} | {
+    kind: 'knock' | 'tick';
+    accent: boolean;
+};
+export declare const WOODBLOCK_HIGH = 76;
+export declare const WOODBLOCK_LOW = 77;
+export declare const KICK = 36;
+export declare const CLOSED_HAT = 42;
+/** Drum notes a voice plays (loaded up front); the synthesized click needs none. */
+export declare const metronomeNotes: (voice: MetronomeVoice) => number[];
+/**
+ * The hits for one beat. `beat` counts from 0 (beat 1 of the bar) and `accent` defaults to `beat === 0`. `kit` says
+ * whether the drum kit loaded and which notes it plays; without it, sample voices fall back to synthesized sounds.
+ */
+export declare function metronomeHits(voice: MetronomeVoice, beat: number, { accent, covers }?: {
+    accent?: boolean;
+    covers?: (note: number) => boolean;
+}): MetronomeHit[];