pepperscore 0.4.0 → 0.5.0

package/dist/lib/asset-fonts.d.ts

@@ -3,3 +3,7 @@
  * base instead of hardcoded CSS. Font family names are page-global, so the first instance's base wins.
  */
 export declare function ensureMusicFonts(base: string, onError?: (failed: string) => void): void;
+/** Start downloading a notation font's faces now (after ensureMusicFonts declared them), rather than on first use. */
+export declare function preloadMusicFont(font: string | undefined): void;
+/** Resolves when a notation font's faces have loaded (or failed), or after `timeoutMs`, whichever is first; never rejects. */
+export declare function musicFontsReady(font: string | undefined, timeoutMs: number): Promise<void>;

package/dist/lib/bar-items.d.ts

@@ -0,0 +1,31 @@
+import type { ChromePreset, PepperScoreControls, ResolvedChrome } from './chrome';
+import { type BarItemId, type PepperScoreSkin } from './skin.ts';
+/** Public skin ids deliberately differ from the historical private header ids. */
+export declare const BAR_HEADER_ID: {
+    readonly play: "play";
+    readonly stop: "stop";
+    readonly tempo: "bpm";
+    readonly transpose: "transpose";
+    readonly keyFlip: "keyFlip";
+    readonly bars: "bars";
+    readonly viewToggle: "mode";
+    readonly tab: "tab";
+    readonly zoom: "staveScale";
+    readonly mixer: "mixer";
+    readonly openFile: "openFile";
+    readonly instrumentSwitch: "instrumentSwitch";
+    readonly octaveTool: "octaveTool";
+    readonly options: "options";
+    readonly noteNames: "noteNames";
+    readonly counts: "counts";
+    readonly chordSymbols: "chordSymbols";
+    readonly pitchColours: "pitchColours";
+    readonly pdf: "pdf";
+};
+export declare const BAR_CONTROL_GROUP: Record<BarItemId, keyof PepperScoreControls | null>;
+/** Null retains the legacy header. An empty array explicitly requests no bar. */
+export declare function resolveBar(skin: PepperScoreSkin | undefined, preset: ChromePreset, controls?: PepperScoreControls): BarItemId[] | null;
+/** Called only by the component's development-gated effect. Resolution itself is pure. */
+export declare function warnUnknownBar(skin?: PepperScoreSkin): void;
+/** Missing bar actions, plus PDF in the default drawer. Explicit false controls stay hidden. */
+export declare function drawerExtras(bar: BarItemId[] | null, chrome: ResolvedChrome): BarItemId[];

package/dist/lib/chrome.d.ts

@@ -1,6 +1,7 @@
-/** Chrome presets (docs/specs/pepperscore-embeddable-component.md, "Chrome presets") and per-control overrides. No runtime imports. */
+import type { BarItemId } from './skin';
+/** Chrome presets (docs/specs/pepperscore-embeddable-component.md, "Chrome presets") and per-control overrides. Pure data resolution, also loaded directly by Node validation. */
 export type ChromePreset = 'full' | 'minimal' | 'none';
-export type PepperScoreControls = Partial<Record<'mixer' | 'openFile' | 'drawer' | 'transport' | 'viewToggle' | 'zoom' | 'tabToggle' | 'instrumentSwitch' | 'octaveTool', boolean>>;
+export type PepperScoreControls = Partial<Record<'mixer' | 'openFile' | 'drawer' | 'transport' | 'viewToggle' | 'zoom' | 'tabToggle' | 'instrumentSwitch' | 'octaveTool' | 'pdf', boolean>>;
 export type ResolvedChrome = {
     header: boolean;
     transport: boolean;
@@ -15,6 +16,7 @@ export type ResolvedChrome = {
     instrumentSwitch: boolean;
     /** The reader's octave tool (move notes or passages by an octave). */
     octaveTool: boolean;
+    pdf: boolean;
     /** The overlaid play/stop button of `minimal`. */
     compactPlay: boolean;
     /** Playhead, note highlight and follow. */
@@ -29,6 +31,6 @@ export type ResolvedChrome = {
  * Open button, file input, open dialog and reopen offer; `mixer` the mixer and the part icons / instrument picker / stave
  * eyes; `zoom` the stave-scale slider, pinch zoom and the page arrows row; `drawer` the bottom drawer and its handle;
  * `tabToggle` the Notation / TAB / Both switch (header and drawer); `instrumentSwitch` the instrument switcher;
- * `octaveTool` the octave tool. Each defaults to on for `full`, off otherwise.
+ * `octaveTool` the octave tool; `pdf` the export button and overlay. Each defaults to on for `full`, off otherwise.
  */
-export declare function resolveChrome(preset?: ChromePreset, controls?: PepperScoreControls): ResolvedChrome;
+export declare function resolveChrome(preset?: ChromePreset, controls?: PepperScoreControls, bar?: BarItemId[] | null, renderableBar?: BarItemId[] | null | undefined): ResolvedChrome;

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

@@ -15,6 +15,7 @@ export type FileSettings = {
     mode: 'portrait' | 'landscape';
     notationFont: 'Bravura' | 'Petaluma';
     barsPerLine: 'auto' | number;
+    pitchColours?: boolean;
     overlap: number;
     names: boolean;
     chordSymbols: boolean;

package/dist/lib/header-controls.d.ts

@@ -9,7 +9,7 @@
  * 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' | 'tab' | 'bars' | 'staveScale' | 'mixer';
+export type HeaderControlId = 'stop' | 'play' | 'openFile' | 'bpm' | 'transpose' | 'keyFlip' | 'mode' | 'tab' | 'bars' | 'staveScale' | 'mixer' | 'noteNames' | 'counts' | 'chordSymbols' | 'options' | 'instrumentSwitch' | 'octaveTool' | 'pitchColours' | 'pdf';
 export type HeaderControlTier = 'primary' | 'secondary';
 export type HeaderControlConfig = {
     id: HeaderControlId;
@@ -54,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' | 'tabToggle'>;
+export declare const HEADER_CONTROL_GROUP: Partial<Record<HeaderControlId, 'transport' | 'viewToggle' | 'openFile' | 'zoom' | 'mixer' | 'tabToggle'>>;

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

@@ -22,13 +22,18 @@
  * 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';
+import type { StringFingering } from '../tab/strings/solver';
 export type TabSpec = {
     /** Notation staff numbers (`@n`) that get a generated TAB staff `100 + n`. */
     generate: string[];
+    /** Approved fretless charts by notation staff. Custom tuning/capo do not apply. */
+    fingers?: Record<string, 'violin' | 'cello'>;
     /** 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[];
+    /** Per notation staff tuning; overrides the global fallback. Physical string order, bottom to top. */
+    tunings?: Record<string, 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). */
@@ -49,7 +54,9 @@ export type TabSpec = {
     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>;
+export type FretMemory = Map<string, FretPos & {
+    finger?: StringFingering;
+}>;
 /**
  * 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

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

@@ -49,6 +49,8 @@ export declare function scanBaseline(mei: string): BaselineInfo;
 export type ViewSpec = {
     /** Insert a page break before every `breakEvery`-th measure (0: none). Existing sb/pb are always removed. */
     breakEvery: number;
+    /** Explicit zero-based system starts; replaces breakEvery, including when empty. */
+    breakBefore?: number[];
     /** Staff numbers (`@n`) to remove, with their staff-bound control events and spans into removed content. */
     hiddenStaves: string[];
     /** Keep `<harm>` chord symbols. */

package/dist/lib/notation/musicxml-octave-clef.d.ts

@@ -0,0 +1,5 @@
+/** Normalize matching octave-clef / octave-transpose encodings to sounding octaves.
+ * Only the import copy changes. Keep chromatic/diatonic transposition, IDs, and all other source markup.
+ * Capture one attributes/note subtree at a time; workers need no DOM or whole-document tree.
+ */
+export declare function normalizeOctaveClefs(text: string): string;

package/dist/lib/pdf/annotations.d.ts

@@ -0,0 +1,12 @@
+import { type PitchColourPaint } from '../pitch-colours';
+import type { Score, ScoreNote } from '../score';
+import { type AnnotationSettings } from '../render';
+/** Attach to the DOM before calling: SVG matrices and glyph boxes require a rendered tree. */
+export declare function annotatePage(svg: SVGSVGElement, score: Score, settings: AnnotationSettings, font?: string, aliases?: ReadonlyMap<string, ScoreNote>, tabStaves?: ReadonlySet<string>): void;
+/** svg2pdf ignores paint-order: retain identical text geometry in each explicit pass. */
+export declare function materializePaint(svg: SVGSVGElement, page: {
+    width: number;
+    height: number;
+}, textWidth: (element: SVGElement, size: number) => number): void;
+/** Inline vector paint: export pages have no reader CSS or host variables. */
+export declare function paintPitchColours(svg: SVGSVGElement, score: Score, paint: PitchColourPaint, tabStaves?: ReadonlySet<string>): void;

package/dist/lib/pdf/compose.d.ts

@@ -0,0 +1,8 @@
+import { type PaperId } from './paper';
+type ComposeOptions = {
+    paper: PaperId;
+    title?: string;
+};
+/** Vector pages in exact physical dimensions. Import this module dynamically from the export UI. */
+export declare function composePdf(pages: string[], opts: ComposeOptions, signal: AbortSignal): Promise<Blob>;
+export {};

package/dist/lib/pdf/engrave.d.ts

@@ -0,0 +1,29 @@
+import type { ViewSpec } from '../notation/mei-view';
+import type { VerovioFiles } from '../verovio-protocol';
+import type { PaperId } from './paper';
+/** A snapshot of source notation and the same view plan used by the reader. */
+export type PageInput = {
+    data: string;
+    view?: ViewSpec;
+};
+export type PageOptions = {
+    paper: PaperId;
+    maxBars: number;
+    font?: string;
+    files?: VerovioFiles;
+    spacingStaff?: number;
+    annotationRoom?: number;
+    headingMm?: number;
+};
+export type LineInfo = {
+    start: number;
+    count: number;
+    width: number;
+};
+export type PagesResult = {
+    pages: string[];
+    lines: LineInfo[];
+    shrunk: boolean;
+};
+/** Dynamically import this module on first PDF use. Each call owns and releases its own WASM worker. */
+export declare function engravePages(input: PageInput, opts: PageOptions, signal: AbortSignal): Promise<PagesResult>;

package/dist/lib/pdf/export.d.ts

@@ -0,0 +1,19 @@
+import type { Score, ScoreNote } from '../score';
+import { type AnnotationSettings } from '../render';
+import type { PitchColourPaint } from '../pitch-colours';
+import { type PageInput, type PageOptions } from './engrave';
+/** Immutable Save snapshot: score is already the reader's instrument/transposition view;
+ * input.view is its planStaves view (including hidden staves, spelling and TAB).
+ * No reader channel or live DOM is used. T3 imports only this module, dynamically.
+ */
+export type ExportRequest = {
+    input: PageInput;
+    options: PageOptions;
+    score: Score;
+    annotations?: AnnotationSettings;
+    pitchColours?: PitchColourPaint;
+    visiblePartIds?: string[];
+    tabAliases?: ReadonlyMap<string, ScoreNote>;
+    tabStaves?: ReadonlySet<string>;
+};
+export declare function exportScore(request: ExportRequest, signal: AbortSignal): Promise<Blob>;

package/dist/lib/pdf/fit.d.ts

@@ -0,0 +1,2 @@
+/** Greedy zero-based line starts, including 0 for a non-empty score. Oversize bars stand alone. */
+export declare function breakLines(barWidths: number[], capacity: number, maxBars: number): number[];

package/dist/lib/pdf/fonts.d.ts

@@ -0,0 +1,3 @@
+import type { jsPDF } from 'jspdf';
+/** TrueType copies of the same OFL Poppins faces as the reader. Loaded only during export. */
+export declare function embedFonts(pdf: jsPDF, signal: AbortSignal): Promise<FontFace[]>;

package/dist/lib/pdf/normalize.d.ts

@@ -0,0 +1,7 @@
+/** Replace nested viewports by their browser-resolved parent-space matrices.
+ * svg2pdf otherwise applies Verovio's definition-scale viewBox twice.
+ * Capture all matrices before changing the tree; outer page units remain intact.
+ */
+export declare function flattenViewports(svg: SVGSVGElement): void;
+/** Ordinary text and music glyphs have different fonts, even within one chord label. */
+export declare function normalizeText(svg: SVGSVGElement): void;

package/dist/lib/pdf/paper.d.ts

@@ -0,0 +1,32 @@
+/** Portrait dimensions in millimetres; shared by engraving and PDF composition. */
+export declare const PAPER_SIZES: {
+    readonly a4: {
+        readonly width: 210;
+        readonly height: 297;
+    };
+    readonly a3: {
+        readonly width: 297;
+        readonly height: 420;
+    };
+    readonly letter: {
+        readonly width: 215.9;
+        readonly height: 279.4;
+    };
+    readonly legal: {
+        readonly width: 215.9;
+        readonly height: 355.6;
+    };
+};
+export type PaperId = keyof typeof PAPER_SIZES;
+/** Five-line stave height, independent of screen zoom and paper size. */
+export declare const STAVE_MM = 6.5;
+export declare const MM_PER_UNIT: number;
+export declare const MARGIN_MM = 12;
+/** The exact integer geometry sent to Verovio, including the tall-system fallback. */
+export declare function pageGeometry(paper: PaperId, naturalHeight: number, overhead?: number): {
+    pageWidth: number;
+    pageHeight: number;
+    margin: number;
+    scale: number;
+    capacity: number;
+};

package/dist/lib/pitch-colours.d.ts

@@ -0,0 +1,16 @@
+import type { ScoreNote, Part } from './score';
+import type { PitchClass, PitchPalette } from './skin';
+export declare const PITCH_CLASSES: readonly PitchClass[];
+export declare const pitchClassOf: (midi: number) => PitchClass;
+export declare const pitchVariable: (pitch: PitchClass) => string;
+export declare function pitchColourStyle(palette?: PitchPalette): Record<string, string>;
+/** Verovio preserves source note order inside chords; prefer exact identity where present. */
+export declare function tagPitchColours(element: Element, event: ScoreNote, part: Pick<Part, 'clef'>, tabStaves?: ReadonlySet<string>): void;
+/** Save-time drawing snapshot, resolved in the same root as the screen's noteheads. */
+export type PitchColourPaint = {
+    palette: PitchPalette;
+    outline: string;
+    strokeWidth: string;
+};
+/** Requires the active player root (palette supplied and pitch-colour pref on). */
+export declare function resolvePitchColours(root: HTMLElement): PitchColourPaint;

package/dist/lib/prefs.d.ts

@@ -1,4 +1,5 @@
 import type { FileSettings } from './file-state';
+import type { TabInstruments } from './tab/string-instruments';
 import type { TabView } from './tab/tab-parts';
 import type { RangeLevel, SwitchInstrumentId } from './instrument-model';
 export declare const MIN_BPM = 30, MAX_BPM = 240;
@@ -42,12 +43,14 @@ export type PepperScoreAnnotationSizes = Partial<Record<AnnotationKey, Annotatio
 /** 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;
+    pdfPaper: 'a4' | 'a3' | 'letter' | 'legal';
 };
 export declare const defaults: Prefs;
 /** Saved global prefs, repaired. Zoom is per score (score-db), so a legacy global zoom is ignored. */
 export declare function sanitizeSavedPrefs(raw: unknown): Prefs;
 /** Initial reader settings a host passes as `settings` (spec names). Changing a key in the prop re-applies that key. */
 export type PepperScoreSettings = Partial<{
+    pitchColours: boolean;
     noteNames: boolean;
     chordSymbols: boolean;
     inferChords: boolean;
@@ -68,9 +71,11 @@ export type PepperScoreSettings = Partial<{
      * 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'`. */
+    /** Which staves fretted string 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]). */
+    /** TAB identity by onReady part id; "none" suppresses TAB. Does not change playback. */
+    tabInstruments: TabInstruments;
+    /** Open-string MIDI in physical bottom-to-top string order (re-entrant allowed). Overrides generated parts with the same string count; other parts keep instrument defaults. */
     tabTuning: number[];
     /** Capo fret 0-12 of generated TAB; frets are relative to it. */
     capo: number;

package/dist/lib/render.d.ts

@@ -133,6 +133,11 @@ export declare const systemMinimumWidth: (bars: number, barFloor: number) => num
  * (the gutter never shrinks with the staff), so a bisection finds it. Deterministic, render-free, rounded down to 0.001.
  */
 export declare function barFitZoom(viewportWidth: number, bars: number, barFloor: number, gutterAt?: (zoom: number) => number): number;
+/**
+ * Bounding box of an element in the outer SVG's user (viewBox) coordinates. `rootInverse` is the outer SVG's inverted
+ * screen matrix, when the caller measures many elements of one SVG without layout changes in between.
+ */
+export declare function annotationBox(element: Element, svg: SVGSVGElement, rootInverse?: DOMMatrix | null): DOMRect;
 /**
  * Map Score parts to Verovio staff numbers. Verovio gives a single-staff
  * MusicXML part's staffDef the part ID, while a multi-staff part's staffGrp
@@ -159,6 +164,52 @@ export declare function planStaves(info: BaselineInfo, score: Score, hiddenIds:
     staffCount: number;
     tabAlias: Map<string, ScoreNote>;
 };
+export type AnnotationSettings = {
+    showNames?: boolean;
+    showCounts?: boolean;
+    subdivisions?: boolean;
+    showChordSymbols?: boolean;
+    inferChordSymbols?: boolean;
+    scale?: AnnotationScale;
+};
+export declare function annotationLayout(parts: Part[], settings: AnnotationSettings): {
+    nameScale: number;
+    chordScale: number;
+    beatScale: number;
+    offbeatScale: number;
+    countScale: number;
+    nameRows: number;
+    laneRows: number;
+    nameRow: number;
+    countRow: number;
+    lanesHeight: number;
+    laneHeight: number;
+    spacingStaff: number;
+    harmSize: number | undefined;
+};
+/** Shared screen/PDF drawing. Coordinates are outer SVG units, independent of its pixel size. */
+export declare function drawEventAnnotations(layer: Element, score: Score, part: Part, measure: Part['measures'][number], event: ScoreNote, x: number, band: {
+    top: number;
+    laneTop: number;
+}, settings: AnnotationSettings, layout: ReturnType<typeof annotationLayout>): void;
+/**
+ * Resolve the rendered event for a model note; a chord wins over any one of its noteheads. A note whose notation
+ * staff is hidden (TAB view) resolves to its generated TAB event (`${id}-tab`, notation/mei-tab.ts).
+ */
+export declare function findAnnotationNote(byId: Map<string, Element>, score: Score, event: ScoreNote): Element | undefined;
+/** Allowlist sanitizer: only static SVG drawing elements, local references and inert styles survive. */
+export declare function sanitizeSvg(doc: XMLDocument): SVGSVGElement;
+type StaffBand = {
+    top: number;
+    bottom: number;
+    center: number;
+    laneTop: number;
+    lines: boolean;
+    /** A six-line TAB staff (its lines are drawn in segments around the fret numbers). */
+    tab?: boolean;
+};
+/** Staff bands and below-staff annotation lanes shared by reader systems and PDF systems. */
+export declare function annotationBands(system: Element, boxOf: (element: Element) => DOMRect, tabStaves: ReadonlySet<string>, withLanes: boolean): Map<string, StaffBand>;
 /**
  * Render from the original engraving document through the locally bundled WASM worker.
  *
@@ -167,3 +218,4 @@ export declare function planStaves(info: BaselineInfo, score: Score, hiddenIds:
  * small first-measures document, so the first paint does not wait for the whole score's layout.
  */
 export declare function renderScore(container: HTMLElement, score: Score, mode: 'portrait' | 'landscape', showNames: boolean, showCounts: boolean, subdivisions: boolean, barsPerLine: 'auto' | number, showChordSymbols: boolean, inferChordSymbols: boolean, availableHeight?: number, zoom?: number | 'fit', firstSystemGutter?: number, options?: RenderOptions): Promise<RenderResult>;
+export {};

package/dist/lib/score.d.ts

@@ -92,6 +92,12 @@ export type MeasureNavigation = {
     barlines?: BarlineNavigation[];
 };
 export type Measure = {
+    keyChanges?: {
+        start: number;
+        key: number;
+        keyMode?: KeyMode;
+    }[];
+    rightBarline?: 'end' | 'dbl';
     index: number;
     beats: number;
     notes: ScoreNote[];

package/dist/lib/skin.d.ts

@@ -0,0 +1,25 @@
+/** Public role names. Each CSS use keeps its original colour as its fallback. */
+export declare const THEME_TOKENS: readonly ["accent", "accentHover", "accentWash", "accentWashStrong", "backdrop", "border", "borderMuted", "danger", "focusRing", "onAccent", "playback", "shadow", "surface", "surfaceRaised", "text", "textFaint", "textMuted", "textSecondary", "warning"];
+export type ThemeToken = typeof THEME_TOKENS[number];
+export declare const BAR_ITEM_IDS: readonly ["play", "stop", "tempo", "transpose", "keyFlip", "bars", "viewToggle", "tab", "zoom", "mixer", "openFile", "instrumentSwitch", "octaveTool", "options", "noteNames", "counts", "chordSymbols", "pitchColours", "pdf"];
+export type BarItemId = typeof BAR_ITEM_IDS[number];
+export type PitchClass = 'C' | 'C#' | 'D' | 'D#' | 'E' | 'F' | 'F#' | 'G' | 'G#' | 'A' | 'A#' | 'B';
+export type PitchPalette = Record<PitchClass, string>;
+export declare const CRF_PITCH_COLOURS: PitchPalette;
+export type PepperScoreSkin = {
+    theme?: Partial<Record<ThemeToken, string>>;
+    pitchColours?: PitchPalette;
+    bar?: BarItemId[];
+};
+/** Overrides may replace individual palette entries; a skin itself has a complete palette. */
+type SkinOverride = Omit<PepperScoreSkin, 'pitchColours'> & {
+    pitchColours?: Partial<PitchPalette>;
+};
+export declare function mergeSkins(base: PepperScoreSkin, ...overrides: SkinOverride[]): PepperScoreSkin;
+export declare function tokenVariable(token: ThemeToken): string;
+export declare function skinStyle(skin?: PepperScoreSkin): Record<string, string>;
+/** Sort maps, preserve array order. Inline object literals are safe memo inputs. */
+export declare function skinKey(skin?: PepperScoreSkin): string;
+/** Called after mounting, only in development: resolve host var() values in their real scope. */
+export declare function warnInvalidTheme(root: HTMLElement, skin?: PepperScoreSkin): void;
+export {};

package/dist/lib/tab/string-instruments.d.ts

@@ -0,0 +1,65 @@
+import { type Part, type Score } from '../score';
+/** TAB instrument identity is independent of the playback sound (ukuleles use nylon guitar). */
+export declare const STRING_INSTRUMENTS: {
+    readonly guitar: {
+        readonly kind: "fretted";
+        readonly tuning: readonly [40, 45, 50, 55, 59, 64];
+    };
+    readonly bass4: {
+        readonly kind: "fretted";
+        readonly tuning: readonly [28, 33, 38, 43];
+    };
+    readonly bass5: {
+        readonly kind: "fretted";
+        readonly tuning: readonly [23, 28, 33, 38, 43];
+    };
+    readonly 'ukulele-soprano': {
+        readonly kind: "fretted";
+        readonly tuning: readonly [67, 60, 64, 69];
+    };
+    readonly 'ukulele-tenor': {
+        readonly kind: "fretted";
+        readonly tuning: readonly [67, 60, 64, 69];
+    };
+    readonly 'ukulele-baritone': {
+        readonly kind: "fretted";
+        readonly tuning: readonly [50, 55, 59, 64];
+    };
+    readonly 'ukulele-bass': {
+        readonly kind: "fretted";
+        readonly tuning: readonly [28, 33, 38, 43];
+    };
+    readonly violin: {
+        readonly kind: "finger";
+        readonly tuning: readonly [55, 62, 69, 76];
+    };
+    readonly viola: {
+        readonly kind: "unsupported";
+        readonly tuning: readonly [48, 55, 62, 69];
+    };
+    readonly cello: {
+        readonly kind: "finger";
+        readonly tuning: readonly [36, 43, 50, 57];
+    };
+    readonly 'double-bass': {
+        readonly kind: "unsupported";
+        readonly tuning: readonly [28, 33, 38, 43];
+    };
+};
+export type TabInstrument = keyof typeof STRING_INSTRUMENTS;
+export type TabInstruments = Record<string, TabInstrument | 'none'>;
+export declare const validTabInstrument: (id: unknown) => id is TabInstrument;
+/** Render metadata travels with the score through the existing render/PDF planning paths. */
+export type TabScore = Score & {
+    tabSettings?: {
+        instruments?: TabInstruments;
+        tuning?: number[];
+    };
+};
+export declare function withTabSettings(score: Score, instruments?: TabInstruments, tuning?: number[]): TabScore;
+/** Switched target ids are exact; source programs gate name-based classification before a switch. */
+export declare function stringInstrument(part: Part, override?: TabInstrument | 'none', switched?: boolean): TabInstrument | undefined;
+/** Overrides use the exact part id reported by onReady; unknown keys/values are ignored. */
+export declare function instrumentFor(score: TabScore, part: Part, switched?: boolean): "guitar" | "double-bass" | "violin" | "viola" | "cello" | "bass4" | "bass5" | "ukulele-soprano" | "ukulele-tenor" | "ukulele-baritone" | "ukulele-bass" | undefined;
+/** Name-only voices are explicit; ambiguous bass needs choir context without guitar/drum evidence. */
+export declare function resolveChoirNames(score: Score): Score;

package/dist/lib/tab/strings/charts.d.ts

@@ -0,0 +1,29 @@
+/** Fretless chart data; violin and cello are integrated in the reader.
+ * Source: ~/violintab/src/lib/tab/instruments.ts (violin/cello).
+ * Strings run high → low; MIDI values are SOUNDING pitches, including bass.
+ */
+export type StringInstrumentId = 'violin' | 'viola' | 'cello' | 'double-bass';
+export type FingerRow = readonly [number, number, number, number];
+export interface StringChart {
+    readonly id: StringInstrumentId;
+    readonly provenance: 'ported' | 'derived';
+    readonly source: string;
+    readonly strings: readonly string[];
+    readonly openMidi: readonly number[];
+    /** One position map per string, high → low. */
+    readonly fingers: readonly Readonly<Record<number, FingerRow>>[];
+}
+export declare const VIOLIN: StringChart;
+/** Davidoff positions: there is NO 2½. Correct source keys
+ * 2.5/3/3.5/4 → 3/3.5/4/4.5, preserving every source pitch.
+ */
+export declare const CELLO_POSITIONS: readonly [0.5, 1, 1.5, 2, 3, 3.5, 4, 4.5];
+export declare const CELLO: StringChart;
+/** Provisional analogies, NOT independently verified pedagogical charts.
+ * Viola: transpose violin down a fifth. Bass: reuse cello finger offsets on
+ * fourths tuning (not a claim about Simandl/1-2-4 or thumb technique).
+ * A teacher must approve/replace these before production integration.
+ */
+export declare const VIOLA: StringChart;
+export declare const DOUBLE_BASS: StringChart;
+export declare const STRING_CHARTS: Readonly<Record<StringInstrumentId, StringChart>>;

package/dist/lib/tab/strings/phrase.d.ts

@@ -0,0 +1,14 @@
+import type { StringChart } from './charts';
+import { type PitchSpelling, type StringFingering } from './solver';
+export interface FingerNote {
+    id: string;
+    onset: number;
+    duration: number;
+    midi: number | null;
+    spelling?: PitchSpelling;
+    tieStop?: boolean;
+    fixed?: StringFingering;
+}
+/** Solve simultaneous voices together, keeping sounding strings occupied and a common hand position.
+ * Unsupported events stay unlabelled rather than inventing a pitch or an impossible double stop. */
+export declare function solveFingerPhrase(chart: StringChart, notes: FingerNote[]): Map<string, StringFingering>;

package/dist/lib/tab/strings/solver.d.ts

@@ -0,0 +1,29 @@
+import type { StringChart } from './charts';
+export type FingerModifier = '' | 'L' | 'H';
+/** Written pitch class; a mismatched hint is ignored, never changes MIDI. */
+export interface PitchSpelling {
+    step: 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G';
+    alter: -2 | -1 | 0 | 1 | 2;
+}
+export interface StringFingering {
+    /** 1 = highest string; position 0 denotes an open string, no hand position. */
+    string: number;
+    position: number;
+    finger: number;
+    modifier: FingerModifier;
+}
+/** Reverse lookup, useful for fixtures and future fixed-fingering constraints.
+ * Open strings require canonical position 0 and no modifier.
+ */
+export declare function fingeringPitch(chart: StringChart, note: StringFingering): number | null;
+/** Exact-pitch choices, opens first. Cello/bass prefer plain fingers anywhere
+ * over extensions, then I before half position, then higher positions.
+ * Violin/viola prefer lower positions, then plain fingers. Modified ties use
+ * the matching spelling: raised (including double sharps) → H, otherwise L.
+ * Without a valid hint, C#/D#/G# prefer H (high 3 rather than low 4);
+ * other pitch classes prefer L, preserving low 2 and the flat-note default.
+ * No octave fold, phrase continuity, double-stop or ringing-string solve.
+ */
+export declare function fingeringCandidates(chart: StringChart, midi: number, spelling?: PitchSpelling): StringFingering[];
+/** Null means outside the supported chart range, never silently transposed. */
+export declare function solveStringPitch(chart: StringChart, midi: number, spelling?: PitchSpelling): StringFingering | null;

package/dist/lib/tab/strings/svg.d.ts

@@ -0,0 +1,3 @@
+/** Verovio preserves note @type as an SVG class, including after getMEI/loadData.
+ * Change only that note's numeric text; never rely on chord ordering or a font's pixel size. */
+export declare function substituteFingerLabels(svg: string): string;

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

@@ -17,12 +17,9 @@ export declare const soundingKeyOf: (part: Part, measure: Measure, note: ScoreNo
  * 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).
+ * Fretted and approved violin/cello notation parts take generated TAB. Authored imported TAB remains usable; there is no pitched-part fallback.
+ * Instrument switches use the new instrument identity instead of the original name.
  */
 export declare function tabParts(score: Score): Part[];
 /** Whether the Notation / TAB / Both switch has anything to switch. */

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

@@ -60,7 +60,7 @@ export type VerovioFiles = {
     module: string;
     toolkit: string;
 };
-/** Sent once by the runtime right after it starts a worker, before any request. */
+/** Sent once by the runtime right after it starts a worker, before any request; the worker then starts loading Verovio. */
 export type VerovioConfigure = {
     kind: 'configure';
     files: VerovioFiles;

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

@@ -32,6 +32,18 @@ export declare function verovioFilesAt(base: string, page?: string): VerovioFile
  * a restart); a blank `base` changes nothing.
  */
 export declare function setVerovioBaseUrl(base: string | undefined): void;
+/**
+ * Start the shared Verovio worker now and have it fetch, compile and instantiate Verovio, so the first engraving does
+ * not wait for that after the score's import. Readers call it on mount when they have a score to show; the worker
+ * still goes when the last reader channel closes. Uses the current `setVerovioBaseUrl` (set it first).
+ */
+export declare function warmVerovio(): void;
+/**
+ * Start loading Verovio before any reader mounts (for example from a page script, before React hydrates), so the
+ * first score engraves sooner. `base` is the same directory as PepperScoreProps.verovioBaseUrl (pass the same value);
+ * omitted, the copy shipped with pepperscore loads. Safe to call more than once and on the server (it does nothing).
+ */
+export declare function preloadVerovio(base?: string): 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;