pepperscore 0.2.0 → 0.4.0

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

@@ -0,0 +1,58 @@
+/**
+ * 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 `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>;
+};
+/** 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/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,44 @@
 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;
+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 +62,38 @@ 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;
+    /**
+     * 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/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

@@ -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;
@@ -122,6 +125,18 @@ 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 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).
+     */
+    tabOf?: string;
 };
 export type Score = {
     title: string;
@@ -137,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 = {

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,64 @@
+/**
+ * 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. A part switched to another instrument (instrument-view.ts) takes TAB only if its new instrument is a guitar
+ * (its name and its imported TAB no longer count).
+ */
+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. A part of the Score's instrument view (switched or octave-moved,
+ * `score.instrumentView`) makes its own TAB stale: generated (its fingerings not fixed) while it is a guitar, else
+ * none (it is no longer a TAB part, and its imported TAB staff is hidden). `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;

package/dist/lib/transpose.d.ts

@@ -28,8 +28,9 @@ export declare function viewProfile(part: Part, view: ScorePitchView): SpellingP
  */
 export declare function scoreForView(score: Score, view: ScorePitchView, semitones: number, flip?: boolean): Score;
 /**
- * The worker's spelling plan for a Score view (`scoreForView`'s result) with its staff numbers: the same interval,
- * flip, per-staff profiles and moved staves, and which staves are percussion (never given a key signature).
+ * The worker's spelling plan for a Score view (`scoreForView`'s result, optionally instrument-switched by
+ * `applyInstrumentView`) with its staff numbers: the same interval, flip, per-staff profiles and moved staves, which
+ * staves are percussion (never given a key signature), and the switched staves' shift, clef and octave moves.
  */
 export declare function spellingSpecFor(score: Score, staffOf: Map<string, string>): SpellingSpec;
 /** The key of a measure in a (view) Score, for app-side pitch text such as inferred chord symbols. */

package/dist/lib/verovio-protocol.d.ts

@@ -50,6 +50,21 @@ export type VerovioRequest = {
     chunkBudget: number;
     simulateOom?: boolean;
 });
+/**
+ * Where the worker imports Verovio from: upstream's own, unmodified ES modules, loaded at runtime so they stay a
+ * separately replaceable library (LGPL-3.0-or-later). `module` is the Emscripten module (npm verovio's
+ * dist/verovio-module.mjs, default export: an async factory of the WASM module); `toolkit` is the JavaScript toolkit
+ * (dist/verovio.mjs, exports `VerovioToolkit` and `enableLogToBuffer`). Absolute URLs.
+ */
+export type VerovioFiles = {
+    module: string;
+    toolkit: string;
+};
+/** Sent once by the runtime right after it starts a worker, before any request. */
+export type VerovioConfigure = {
+    kind: 'configure';
+    files: VerovioFiles;
+};
 export type VerovioReply = {
     id: number;
     value?: unknown;

package/dist/lib/verovio-runtime.d.ts

@@ -1,5 +1,5 @@
 import type { SourceDocument } from './notation/document';
-import type { BaselineInfo, PagesResult, ProbeResult, VerovioReply, ViewSpec } from './verovio-protocol';
+import type { BaselineInfo, PagesResult, ProbeResult, VerovioFiles, VerovioReply, ViewSpec } from './verovio-protocol';
 /** A worker failure; `code` says why (see VerovioReply). */
 export declare class VerovioError extends Error {
     readonly code?: VerovioReply['code'];
@@ -24,6 +24,14 @@ export declare const chunkSettings: () => {
  * threshold) on a fresh worker. The caller then opens or draws the score again. Returns the new budget.
  */
 export declare function reduceChunkSize(): number;
+/** The Verovio files under a directory laid out like the verovio npm package's dist/; a relative URL resolves against the page. */
+export declare function verovioFilesAt(base: string, page?: string): VerovioFiles;
+/**
+ * Load Verovio from `base` (see PepperScoreProps.verovioBaseUrl) instead of the shipped copy. Every reader on the page
+ * shares one worker, so this applies to all of them, from the next time the worker starts (the first engraving, or
+ * a restart); a blank `base` changes nothing.
+ */
+export declare function setVerovioBaseUrl(base: string | undefined): void;
 export declare function verovioRevision(document: SourceDocument): number;
 /** A reader mounted: a channel of its own, so its imports and renders never supersede another reader's. */
 export declare function openVerovioChannel(): number;