pepperscore 0.1.1 → 0.3.0

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', boolean>>;
 export type ResolvedChrome = {
     header: boolean;
     transport: boolean;
@@ -9,6 +9,8 @@ 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 overlaid play/stop button of `minimal`. */
     compactPlay: boolean;
     /** Playhead, note highlight and follow. */
@@ -21,6 +23,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.
+ * 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).
  */
 export declare function resolveChrome(preset?: ChromePreset, controls?: PepperScoreControls): ResolvedChrome;

package/dist/lib/clock.d.ts

@@ -0,0 +1,13 @@
+/** A host-owned clock that drives the playhead (the `clock` prop). Types only: no runtime imports. */
+export type ClockEvent = {
+    type: 'play' | 'pause' | 'seek' | 'rate';
+    time: number;
+};
+export type ExternalClock = {
+    /** Current time in seconds from the start of the score (score beat 0, the pickup's first beat when there is one). May be negative during a count-in. */
+    now(): number;
+    /** Whether the clock is running; the playhead updates every animation frame while it is. */
+    readonly playing: boolean;
+    /** Called on play, pause, seek and rate changes; returns an unsubscribe function. */
+    subscribe(listener: (event: ClockEvent) => void): () => void;
+};

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

@@ -1,5 +1,7 @@
 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';
 export type FileSource = {
     name: string;
     size: number;
@@ -22,7 +24,20 @@ 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;
@@ -40,7 +55,7 @@ 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;
 };
@@ -53,9 +68,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;
 /**

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/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[];

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

@@ -0,0 +1,51 @@
+/**
+ * Guitar TAB staves for the engraving view (docs/specs/guitar-tab.md, "Generation"). String-level like mei-view.ts:
+ * the Verovio worker has no DOMParser and the input is Verovio's own `getMEI` output, already spelled and transposed,
+ * so frets follow the pitches the reader shows.
+ *
+ * For every notation staff `n` in `TabSpec.generate`, a `tab.guitar` staff `100 + n` is added right after it (its
+ * staffDef after the notation staffDef, its staff after the notation staff in every measure). Each layer is cloned:
+ * a note or chord becomes a `tabGrp` (same duration) with a `tabDurSym` and one `note tab.course tab.fret` per pitch;
+ * beams, tuplets and rests are kept; grace notes, lyrics, clefs and everything else are dropped. IDs get a `-tab`
+ * suffix (`${note}-tabn` for the TAB note of a single note, whose `tabGrp` takes `${note}-tab`), so the reader finds
+ * the TAB event of a Score note by its source ID. Tie continuations keep their rhythm (the `tabGrp` and its stem) and
+ * show no fret: their TAB note, on the string of the note they continue, is invisible. Measure and beat repeats are
+ * copied, so the repeat sign shows on the TAB staff too.
+ *
+ * Frets come from the fingering solver (tab/fret-assign.ts), run over each staff's whole document in time order (all
+ * layers) so it sees the passage, not one measure. `tab.course`/`tab.fret` already on notation notes (MusicXML
+ * `<technical>` string/fret) are fixed constraints. `retarget` moves staff-bound text (chord symbols, tempo,
+ * directions, fermatas) of a notation staff that the view hides onto its TAB staff; an event attached to a note
+ * (`startid`) is attached to that note's TAB event.
+ *
+ * `refret` re-fingers imported TAB staves that double no notation staff (a TAB-only score) when the view transposes:
+ * their notes' sounding pitches (the staff's `<tuning>` plus fret) move by the given semitones and are solved again.
+ */
+import { type FretPos } from '../tab/fret-assign';
+export type TabSpec = {
+    /** Notation staff numbers (`@n`) that get a generated TAB staff `100 + n`. */
+    generate: string[];
+    /** Staff-bound control events of a hidden notation staff move to this TAB staff (`n` → TAB `n`). */
+    retarget: Record<string, string>;
+    /** Open-string MIDI pitches, low to high. */
+    tuning: number[];
+    /** Capo fret; frets are relative to it. */
+    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 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[];
+    /** Imported TAB staves (no notation partner) to re-finger, by staff `@n`: the semitones their pitches move. */
+    refret?: Record<string, number>;
+};
+/** Fingerings by notation note `xml:id`, kept across chunk documents so a note keeps its fret wherever it is drawn. */
+export type FretMemory = Map<string, FretPos>;
+/**
+ * Add the TAB staves of `spec` to `mei`, re-finger its `refret` staves and retarget hidden staves' control events.
+ * `memory` (optional) keeps fingerings by note ID across calls: a remembered note is fixed for the solver and new
+ * results are added to it.
+ */
+export declare function injectTab(mei: string, spec: TabSpec, memory?: FretMemory): string;

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

@@ -8,6 +8,7 @@
  * makes the engraving view (breaks, hidden staves, chord symbols) inside the worker.
  */
 import type { SpellingSpec } from './mei-spelling';
+import type { TabSpec } from './mei-tab';
 /** An attribute's raw (still escaped) value from a tag's attribute text; IDs, numbers and staff lists need no unescaping. */
 export declare function attributeOf(attributes: string, name: string): string | null;
 export type Visitor = (tag: {
@@ -52,12 +53,19 @@ export type ViewSpec = {
     hiddenStaves: string[];
     /** Keep `<harm>` chord symbols. */
     chordSymbols: boolean;
+    /** Chord symbol text size in percent (the reader's annotation size); omitted or 100 leaves `<harm>` as encoded. */
+    harmSize?: number;
     /**
      * Transposition, key flip and spelling (mei-spelling.ts), applied to the baseline before the view is built. The
      * worker transposes with Verovio's `transpose` / `transposeToSoundingPitch` and respells; the view itself is then
      * loaded untransposed.
      */
     spelling?: SpellingSpec;
+    /**
+     * Guitar TAB staves to add after spelling (notation/mei-tab.ts), and staff-bound text to move onto them. Hidden
+     * notation staves (TAB view) and unused imported TAB staves are in `hiddenStaves`.
+     */
+    tab?: TabSpec;
 };
 /**
  * The reader's engraving view of a baseline: no header, labels or encoded breaks; a page break every `breakEvery`

package/dist/lib/playback/clock-time.d.ts

@@ -0,0 +1,20 @@
+import type { PerformanceTimeline } from './timeline';
+export type ClockTimeline = Pick<PerformanceTimeline, 'events' | 'positions' | 'initialBpm'>;
+export type NoteOnset = {
+    noteId: string;
+    midi: number;
+    measureIndex: number;
+    occurrence: number;
+    seconds: number;
+};
+/** Playback seconds per timeline unit at `bpm`; an invalid BPM plays at the score's opening tempo (same rule as playbackScale). */
+export declare function scoreSecondsScale(timeline: Pick<PerformanceTimeline, 'initialBpm'>, bpm: number): number;
+/**
+ * Note onsets in seconds at the score's own tempo map: the times clock mode maps `clock.now()` against. One entry per
+ * performed pitch (repeats included), in performed order. Seconds count from score beat 0, a pickup's first beat.
+ */
+export declare function noteOnsetSeconds(timeline: Pick<PerformanceTimeline, 'events' | 'initialBpm'>): NoteOnset[];
+/** Playback seconds (at `bpm`) where a written note sounds, at its performed occurrence nearest `nearSeconds`; null for a rest or unknown note. */
+export declare function noteSeekSeconds(timeline: ClockTimeline, noteId: string, nearSeconds: number, bpm: number): number | null;
+/** Playback seconds (at `bpm`) where a measure's performed occurrence nearest `nearSeconds` starts; null if it is never performed. */
+export declare function measureSeekSeconds(timeline: ClockTimeline, measureIndex: number, nearSeconds: number, bpm: number): number | null;

package/dist/lib/playback/timeline.d.ts

@@ -104,7 +104,10 @@ export type BaseTimelineOptions = {
     roadmap?: Roadmap;
     /** Note marks and pedals already read from the source (for example by the import worker). */
     marks?: PlaybackMarks;
-    /** Parts to perform; all parts of the score by default. Tempo, fermatas and dynamics always come from the whole score. */
+    /**
+     * Parts to perform; all parts of the score by default. Tempo, fermatas and dynamics always come from the whole score.
+     * A TAB staff that doubles a notation part (`tabOf`) is never performed, so the instrument sounds once.
+     */
     parts?: Part[];
 };
 /** Build the BPM-independent performance of `full` (see BaseTimeline). */

package/dist/lib/prefs.d.ts

@@ -1,9 +1,43 @@
 import type { FileSettings } from './file-state';
+import type { TabView } from './tab/tab-parts';
+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 declare const TAB_VIEW_NAMES: readonly TabView[];
+/** Standard guitar tuning EADGBE as open-string MIDI, low to high (tab/fret-assign.ts STANDARD_TUNING). */
+export declare const STANDARD_TAB_TUNING: readonly number[];
+export declare const MAX_CAPO = 12;
+export declare const validTabView: (view: unknown) => view is TabView;
+export declare const MIN_TAB_STRINGS = 4, MAX_TAB_STRINGS = 8;
+/** A usable TAB tuning: 4 to 8 open strings (bass to extended-range guitar), MIDI 0-127. */
+export declare const validTabTuning: (tuning: unknown) => tuning is number[];
+export declare const validCapo: (capo: unknown) => capo is number;
+/** A capo as a whole fret 0-12 (fractions round; anything not a number is no capo). */
+export declare const clampCapo: (capo: unknown) => number;
 /** Explicit bars per line (`barsPerLine`) range; Auto is capped separately (render.ts AUTO_BAR_CAP). */
 export declare const BARS_PER_LINE_MIN = 1;
 export declare const BARS_PER_LINE_MAX = 8;
 /** Round and clamp an explicit bar count into range. */
 export declare const clampBarsPerLine: (value: number) => number;
+/** Text add-on size steps, smallest first. `rg` (regular) is the default and draws today's size. */
+export declare const ANNOTATION_SIZES: readonly ["xs", "sm", "md", "rg", "lg", "xl"];
+export type AnnotationSize = typeof ANNOTATION_SIZES[number];
+/** Font scale of each step relative to `rg`; lanes, offsets and bar widths scale with it (render.ts). */
+export declare const ANNOTATION_SCALE: Record<AnnotationSize, number>;
+export declare const isAnnotationSize: (value: unknown) => value is AnnotationSize;
+/** The text add-ons that take a size (`settings.annotationSizes` keys); inferred chord symbols use `chordSymbols`. */
+export type AnnotationKey = 'noteNames' | 'chordSymbols' | 'beatCounts' | 'subdivisions';
+/** The `Prefs` / `FileSettings` key holding each add-on's size. */
+export declare const ANNOTATION_SIZE_PREFS: {
+    readonly noteNames: "namesSize";
+    readonly chordSymbols: "chordSymbolsSize";
+    readonly beatCounts: "countsSize";
+    readonly subdivisions: "subdivisionsSize";
+};
+export type AnnotationSizePref = typeof ANNOTATION_SIZE_PREFS[AnnotationKey];
+export declare const ANNOTATION_SIZE_PREF_KEYS: AnnotationSizePref[];
+/** Host sizes per add-on (`settings.annotationSizes`); omitted add-ons keep their current size. */
+export type PepperScoreAnnotationSizes = Partial<Record<AnnotationKey, AnnotationSize>>;
 /** Reader settings; `zoom` is the score's explicit stave scale, or null for the device default (see stave-scale.ts). */
 export type Prefs = FileSettings & {
     zoom: number | null;
@@ -27,6 +61,22 @@ export type PepperScoreSettings = Partial<{
     semitones: number;
     concert: boolean;
     overlap: number;
+    /**
+     * Text size of each add-on: `'xs' | 'sm' | 'md' | 'rg' | 'lg' | 'xl'` (`'rg'`, regular, is the default). Keys:
+     * `noteNames`, `chordSymbols` (source and inferred), `beatCounts` (on-beat counts) and `subdivisions` (the e/&/a
+     * counts between beats). Only the add-ons given are applied; unknown sizes are ignored.
+     */
+    annotationSizes: PepperScoreAnnotationSizes;
+    /** Which staves guitar parts show: `'notation'` (default), `'tab'` or `'both'`. */
+    tabView: TabView;
+    /** Open-string MIDI pitches of generated TAB, low to high (default EADGBE, [40, 45, 50, 55, 59, 64]). */
+    tabTuning: number[];
+    /** Capo fret 0-12 of generated TAB; frets are relative to it. */
+    capo: number;
+    /** Initial tempo, 30-240 BPM (a score's own tempo otherwise). */
+    bpm: number;
+    /** Spell a transposed view in the enharmonic key (F# major shown as Gb major). */
+    keyFlip: boolean;
 }>;
 export declare function settingsToPrefs(settings?: PepperScoreSettings): Partial<Prefs>;
 export declare const viewToMode: (view: "vertical" | "endless") => Prefs["mode"];

package/dist/lib/render.d.ts

@@ -1,5 +1,6 @@
-import type { Score } from './score';
+import type { Part, Score, ScoreNote } from './score';
 import type { BaselineInfo } from './notation/mei-view';
+import { type TabView } from './tab/tab-parts';
 export type NotePoint = {
     id: string;
     measure: number;
@@ -87,6 +88,24 @@ export type RenderOptions = {
     fitFloor?: number;
     /** Draw the system holding this Score measure before resolving (a zoom anchor), besides those in view. */
     focusMeasure?: number;
+    /**
+     * Font scale of each text add-on (1, the default, is the regular size; prefs.ts ANNOTATION_SCALE). Lane rows, label
+     * offsets and the room kept above the staff grow with it (bar layout and stave scale do not); source chord symbols are scaled
+     * by Verovio (MEI `<rend fontsize>`), so it spaces them itself.
+     */
+    annotationScale?: AnnotationScale;
+    /** Guitar TAB (docs/specs/guitar-tab.md): which staves guitar parts show, and the tuning and capo of generated TAB. */
+    tab?: {
+        view: TabView;
+        tuning?: number[];
+        capo?: number;
+    };
+};
+export type AnnotationScale = {
+    names?: number;
+    chordSymbols?: number;
+    counts?: number;
+    subdivisions?: number;
 };
 /**
  * Scores up to this many staff-measures (visible staves x measures) draw every system before the first paint, as
@@ -124,6 +143,22 @@ export declare function staffNumbers(info: BaselineInfo, score: Score): {
     byPart: Map<string, string>;
     engraved: string[];
 };
+/**
+ * The staves a view engraves: Score parts to staff numbers, the visible parts (a TAB staff that doubles a notation
+ * part is never a part of its own: it shows with its partner), the staves to hide, the spelling plan and the guitar
+ * TAB plan (tab/tab-parts.ts). Shared with validation/tab-harness.ts.
+ */
+export declare function planStaves(info: BaselineInfo, score: Score, hiddenIds: ReadonlySet<string>, tab?: RenderOptions['tab']): {
+    staffOf: Map<string, string>;
+    visibleParts: Part[];
+    hiddenStaves: string[];
+    spelling: import("./notation/mei-spelling").SpellingSpec;
+    tabView: TabView;
+    tabPlan: import("./tab/tab-parts").TabPlan;
+    tabStaves: Set<string>;
+    staffCount: number;
+    tabAlias: Map<string, ScoreNote>;
+};
 /**
  * Render from the original engraving document through the locally bundled WASM worker.
  *

package/dist/lib/score.d.ts

@@ -122,6 +122,13 @@ export type Part = {
     pitchBasis?: 'written' | 'concert';
     transposition?: Transposition;
     measures: Measure[];
+    /** A tablature staff (MusicXML clef sign TAB), imported by Verovio as a `tab.guitar` staff. */
+    tab?: boolean;
+    /**
+     * 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).
+     */
+    tabOf?: string;
 };
 export type Score = {
     title: string;

package/dist/lib/sound-players.d.ts

@@ -1,6 +1,10 @@
 import type { SoundPlan } from './sounds';
+/** One sound source's player (public through pepperscore/audio). */
 export type AudioPlayer = {
-    fallback?: boolean;
+    /**
+     * Play MIDI `note` at `time` (AudioContext seconds) for `duration` seconds at `velocity` (0-127). Returns a function
+     * that stops (or, if it has not started yet, cancels) that one note.
+     */
     start(options: {
         note: number;
         time: number;
@@ -8,9 +12,13 @@ export type AudioPlayer = {
         velocity: number;
         destination?: AudioNode;
     }): () => void;
+    /** Stop every sounding note and cancel every scheduled one. */
     stop(): void;
+    /** Stop and release the player's buffers and nodes. */
     dispose(): void;
+    /** Load (decode) these notes before they are started. */
     loadNotes?(notes: number[]): Promise<void>;
+    /** Whether the player has a sound for this note. */
     covers?(note: number): boolean;
 };
 /** The players for one plan (sf2 players are bound to `destination`, a part's track gain). */

package/dist/lib/tab/fret-assign.d.ts

@@ -0,0 +1,53 @@
+export declare const STANDARD_TUNING: number[];
+export interface FretPos {
+    string: number;
+    fret: number;
+}
+/** A fixed fingering, or a string only (a circled string number: the solver picks the fret on that string). */
+export interface FretFixed {
+    string: number;
+    fret?: number;
+}
+export interface FretEvent {
+    onset: number;
+    durations: number[];
+    pitches: number[];
+    fixed?: (FretFixed | undefined)[];
+}
+export interface FretOptions {
+    tuning?: number[];
+    capo?: number;
+    maxFret?: number;
+    octaveFold?: boolean;
+}
+export type FretResult = (FretPos & {
+    shifted?: number;
+}) | {
+    unplayable: true;
+};
+export declare function assignFrets(events: FretEvent[], options?: FretOptions): FretResult[][];
+/** One written note of a staff (any voice or layer): onset and duration in quarter notes, sounding MIDI pitch. */
+export interface FretNote {
+    onset: number;
+    duration: number;
+    pitch: number | null;
+    tieStart?: boolean;
+    tieStop?: boolean;
+    fixed?: FretFixed;
+}
+/** Per written note: its fingering (a tie continuation gets the fingering of the note it continues). */
+export interface FretNoteResult {
+    result?: FretResult;
+    continuation: boolean;
+}
+/**
+ * Finger the notes of one staff, every voice together. Shared by the reader (mei-tab.ts) and the bake
+ * (scripts/tab-bake.mjs) so both give the same fingerings for the same notes.
+ * - Notes starting together are one event, whatever their voice: they sound at once, so they need different strings.
+ * - A unison (the same pitch starting together in two voices) is one string: one solver note, ringing as long as the
+ *   longest of them (ties included); every written note of it gets that fingering.
+ * - A tie continuation (`tieStop` with a tie open on its pitch) is not fingered again: it extends the note it continues
+ *   and takes its fingering. With nothing open (a chunk starting mid-tie) it is fingered as a note.
+ * - Notes without a pitch get no result. The input order only breaks ties between equal onsets.
+ */
+export declare function assignNoteFrets(notes: FretNote[], options?: FretOptions): FretNoteResult[];

package/dist/lib/tab/tab-parts.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Which staves show guitar TAB (docs/specs/guitar-tab.md, "Which staves get TAB"). Main-thread only: the reader
+ * decides from its Score which notation staves get a generated TAB staff, which imported TAB staves show, and what is
+ * hidden; the Verovio worker then injects the TAB staves (notation/mei-tab.ts).
+ */
+import type { Measure, Part, Score, ScoreNote } from '../score';
+import type { TabSpec } from '../notation/mei-tab';
+import type { PartState } from '../file-state';
+export type TabView = 'notation' | 'tab' | 'both';
+/** A generated TAB staff's number: 100 + its notation staff's number. */
+export declare const tabStaffNumber: (n: string) => string;
+/** A note's onset and sounding pitches as one key (`measure:start:midis`, or `r` for a rest). */
+export declare const soundingKeyOf: (part: Part, measure: Measure, note: ScoreNote) => string;
+/**
+ * Flag TAB parts (`tab`) and link each to the notation part it doubles (`tabOf`): a sibling staff of the same
+ * MusicXML part, or else the nearest pitched part before it with (nearly) the same notes. A TAB part that doubles
+ * nothing (a TAB-only score) stays a normal, performed part. Mutates and returns `score`.
+ */
+export declare function linkTabParts(score: Score): Score;
+/** A guitar part: GM programs 25-32 (1-based; nylon to guitar harmonics), the guitar sound, or "guitar" in its name. */
+export declare const isGuitarPart: (part: Part) => boolean;
+/** Notation parts that take TAB: every guitar part (and every part an imported TAB doubles), else the first pitched part. */
+export declare function tabParts(score: Score): Part[];
+/** Whether the Notation / TAB / Both switch has anything to switch. */
+export declare const canShowTab: (score: Score) => boolean;
+export type TabPlan = {
+    /** For the worker; absent when nothing is injected or retargeted. */
+    spec?: TabSpec;
+    /** Staff numbers hidden by the view (notation staves in TAB view, imported TAB staves when unused). */
+    hidden: string[];
+    /** Staff numbers the view adds or shows that are not in the baseline's staffDefs (generated TAB staves). */
+    added: string[];
+    /** The staff a notation part is read from in this view (its TAB staff in TAB view); defaults to its own. */
+    display: Map<string, string>;
+    /** Imported TAB part shown for a notation part (highlights map the notation part's notes onto it). */
+    importedFor: Map<string, Part>;
+};
+/**
+ * The reader parts a saved record hides (`parts`: saved part states by ID). Only parts the reader lists can be hidden:
+ * a TAB part that doubles a guitar never is (an older reader listed it), and a guitar whose notation was hidden while
+ * its TAB part showed stays shown (the guitar was being read from its TAB).
+ */
+export declare function hiddenReaderParts(score: Score, parts: Record<string, PartState | undefined>): string[];
+/**
+ * Plan a view: `staffOf` maps parts to baseline staff numbers, `hiddenIds` are parts the reader hid, `stale` is true
+ * when the view moves sounding pitches (transposition: imported `tab.fret`s no longer match, so imported TAB is replaced
+ * by generated TAB and a TAB-only staff is re-fingered). A concert view moves written notes to the pitches they already
+ * sound, so it never makes TAB stale. `sounding` lists staves whose spelled notes are at sounding pitch (their
+ * `trans.semi` no longer applies).
+ */
+export declare function planTab(score: Score, staffOf: Map<string, string>, view: TabView, options: {
+    tuning: number[];
+    capo: number;
+    stale: boolean;
+    semitones?: number;
+    sounding?: string[];
+    hiddenIds?: Set<string>;
+}): TabPlan;