@ugfoundation/swaralipi-js 0.2.1 → 0.3.0

package/dist/viewer/index.d.cts

@@ -1,5 +1,8 @@
-import { O as Octave, a as SvaraLetter, N as Note, S as Swaralipi } from '../schema-D3wyNRqM.cjs';
+import { O as Octave, a as SvaraLetter, N as Note, M as Meta, S as Swaralipi } from '../schema-D3wyNRqM.cjs';
+import { S as Schedule, P as PlayEvent, c as DrumVoice } from '../schedule-DhO_Xzz4.cjs';
 import 'zod';
+import 'tone';
+import '../taals-FmEulsjY.cjs';
 
 /**
  * Per-language notation encoding for the viewer.
@@ -28,9 +31,12 @@ import 'zod';
  * bn ati-octave extra dot (Swarabitan's f/h are single reph/hasanta only).
  */
 
-type ViewerLang = 'bn' | 'hi' | 'en';
+/** Akarmatrik/Bhatkhande grid languages, rendered synchronously by renderToHtml. */
+type GridLang = 'bn' | 'hi' | 'en';
+/** All viewer languages. `staff` = Western staff notation (async, via abcjs). */
+type ViewerLang = GridLang | 'staff';
 /** Digits 0-9 in the target script (beat labels, avartan). */
-declare const DIGITS: Record<ViewerLang, string>;
+declare const DIGITS: Record<GridLang, string>;
 interface LangMarks {
     /** Melisma / no-new-attack dash before a sustained cluster. */
     hyphen: string;
@@ -39,9 +45,9 @@ interface LangMarks {
     /** ছেদ cut/articulation mark (two stacked rings, ঃ-shaped). */
     cut: string;
 }
-declare const MARKS: Record<ViewerLang, LangMarks>;
+declare const MARKS: Record<GridLang, LangMarks>;
 /** Header labels (NLTR prints নাম / তাল / আবর্তন …). */
-declare const LABELS: Record<ViewerLang, {
+declare const LABELS: Record<GridLang, {
     title: string;
     taal: string;
     raag: string;
@@ -60,7 +66,7 @@ interface ComposeOptions {
     octave: Octave;
     /** Append the আ-কার matra carrier (bn group-final notes only). */
     withMatra: boolean;
-    lang: ViewerLang;
+    lang: GridLang;
 }
 /**
  * Compose one svara into its notation-font ASCII. bn = Swarabitan
@@ -69,7 +75,7 @@ interface ComposeOptions {
  */
 declare function composeCluster(letter: SvaraLetter, opts: ComposeOptions): Cluster;
 /** Map ASCII digits in `s` to the target script's digits. */
-declare function localizeDigits(s: string, lang: ViewerLang): string;
+declare function localizeDigits(s: string, lang: GridLang): string;
 
 /**
  * Pure spec-JSON → HTML renderer. No DOM, no side effects: usable for SSR
@@ -141,6 +147,13 @@ interface Arc {
  * A row with fill segments but no ends at all renders one straight line.
  */
 declare function resolveArcs(cells: Cell[], noteCount: number): Arc[];
+/**
+ * The নাম / তাল / রাগ / আবর্তন / স্বরলিপিকার header block, shared by the
+ * akarmatrik grid and the staff view so both show the same metadata (localized
+ * labels; values injected pre-localized by the consumer). Exported so the
+ * staff renderer can reuse the exact markup + styling.
+ */
+declare function renderMetaHeader(meta: Meta, lang: GridLang, tr?: (s: string) => string): string;
 /** Render a complete swaralipi document to an HTML string. Pair with
  * SWARALIPI_CSS (shadow DOM does this automatically; SSR consumers emit a
  * `<style>` themselves). All source text is HTML-escaped. */
@@ -182,7 +195,130 @@ declare const SWARALIPI_CSS: string;
  *  - rows are un-clipped (no scrollbar on paper) and kept whole across page
  *    breaks; part headings stay with their first row.
  */
-declare const SWARALIPI_PRINT_CSS = "\n@page { margin: 16mm; }\n@media print {\n  .sw-sheet { -webkit-print-color-adjust: exact; print-color-adjust: exact; color: #000; }\n  .sw-row { overflow: visible !important; break-inside: avoid; page-break-inside: avoid; }\n  .sw-part { break-inside: auto; }\n  .sw-part-name, .sw-header { break-after: avoid-page; page-break-after: avoid; }\n  .sw-hl { background: none !important; }\n}\n";
+declare const SWARALIPI_PRINT_CSS = "\n@page { margin: 16mm; }\n@media print {\n  .sw-sheet, .sw-staff { -webkit-print-color-adjust: exact; print-color-adjust: exact; color: #000; }\n  .sw-row { overflow: visible !important; break-inside: avoid; page-break-inside: avoid; }\n  .sw-part { break-inside: auto; }\n  .sw-part-name, .sw-header { break-after: avoid-page; page-break-after: avoid; }\n  .sw-hl { background: none !important; }\n  /* Keep each engraved staff system whole across a page break (the abcjs line\n     is a <div> wrapping the <svg>, so the break rule must sit on the div). */\n  .sw-staff-lines > div { break-inside: avoid; page-break-inside: avoid; }\n  .sw-staff-meta { break-after: avoid-page; page-break-after: avoid; }\n}\n";
+/** Staff-notation (abcjs) wrapper chrome: instrument/tempo header + a fluid
+ * SVG. The engraving itself is drawn by abcjs; this only frames it. */
+declare const SWARALIPI_STAFF_CSS = "\n.sw-staff { color: currentColor; }\n.sw-staff-meta { display: flex; gap: 1.25em; align-items: baseline; margin: 0 0 .5em; font-size: .95em; opacity: .85; }\n.sw-staff-instrument { font-weight: 600; }\n.sw-staff-drums { opacity: .75; }\n.sw-staff-tempo { font-variant-numeric: tabular-nums; }\n/* abcjs (oneSvgPerLine) wraps the music into one <div><svg> per system; stack\n   them as short, swaralipi-style lines. abcjs sets a fixed pixel height +\n   overflow:hidden on each wrapper div \u2014 neutralise it so the viewBox'd SVG can\n   scale to the container (and to the print page) instead of being clipped. */\n.sw-staff-lines > div { margin: 0 0 .35em; height: auto !important; overflow: visible !important; }\n/* Fill up to the engraved (staffwidth) size \u2014 shrink to fit a narrow container,\n   but never stretch past natural width (abcToSvg pins per-SVG max-width in px),\n   else a short last system balloons. */\n.sw-staff-lines svg { display: block; width: 100%; height: auto; }\n.sw-staff-missing { padding: 1em; border: 1px dashed currentColor; border-radius: 6px; opacity: .8; font-size: .9em; }\n.sw-staff-title { font-size: 1.15em; font-weight: 700; }\n.sw-staff-subtitle { opacity: .8; font-size: .95em; margin-top: .15em; }\n";
+
+/**
+ * Staff (Western) notation — a 4th "language" for the viewer.
+ *
+ * Staff notation IS the melody voice drawn as a Western score, so it reuses
+ * the player's pure `buildSchedule` (the same (midi, beat, durationBeats, kan)
+ * the MIDI export writes) and turns it into an **ABC notation** string, which
+ * `abcjs` (MIT, zero-dep) engraves to SVG. abcjs is loaded through a *dynamic*
+ * `import('abcjs')` — an optional peer dep, exactly like tone/lamejs — so the
+ * viewer bundle keeps its bare-load guarantee and only consumers who want staff
+ * notation install it. Without it, `renderStaffHtml` returns a graceful notice.
+ *
+ * Scope (matches the player/MIDI): a single treble-clef melody line. The chosen
+ * instrument is a header label, not a clef change (the line is monophonic and
+ * treble covers piano + violin range with ledger lines). Microtones render as
+ * their komal approximation — the same documented limitation as playback, since
+ * abcjs has no sub-komal glyph.
+ */
+
+interface StaffOptions {
+    /** Tonic (Sa). Accepts `C`, `C#`, `cs`… Default: `meta.tonic`, else `C`. */
+    tonic?: string;
+    /** Octave of madhyam Sa (C4 = MIDI 60). Default 4. */
+    baseOctave?: number;
+    /** Tempo written into the score (Q:) and shown as a header. Default `meta.bpm`, else 90. */
+    bpm?: number;
+    /** Instrument name shown above the staff (label only — clef stays treble). */
+    instrument?: string;
+    /** Show the নাম/তাল/আবর্তন/স্বরলিপিকার header block. Default true. */
+    showHeader?: boolean;
+    /** Language for the header **labels** (values are injected pre-localized by
+     * the consumer). Default `en` — staff is the Western view. */
+    headerLang?: GridLang;
+    /** Transliterate header values (title/taal/notator) — same fn as the grid. */
+    transliterate?: (bengaliText: string) => string;
+    /** Include the `w:` lyric line under each staff. Default true. */
+    lyrics?: boolean;
+    /** Matra per bar (one তাল cycle). Default `meta.taal.numBeats`, else 4. */
+    beatsPerBar?: number;
+    /** Target line width in px passed to abcjs (music wraps within it). Default 680. */
+    staffwidth?: number;
+    /** Preferred bars per wrapped line (swaralipi-short systems). Default 4. */
+    measuresPerLine?: number;
+    /** abcjs `scale`. Default 1. */
+    scale?: number;
+    /** Add a second percussion staff below the melody, sequencing a Western
+     * drumset (kick/snare/hi-hat) to the taal's sam/tali/khaali structure —
+     * the same pattern `SwaralipiPlayer`'s `rhythm: 'drums'` plays, engraved via
+     * abcjs `%%percmap`. Default false (the score stays a single staff). Taal:
+     * `meta.taal`, else a plain 4-beat cycle (matches `beatsPerBar`'s fallback). */
+    drums?: boolean;
+}
+/**
+ * MIDI number → ABC pitch token. ABC's octave anchor is fixed by the standard:
+ * middle C (MIDI 60, C4) is uppercase `C`; lowercase `c` = C5; a comma drops an
+ * octave (`C,` = C3), an apostrophe raises one (`c'` = C6). Sharps carry a `^`.
+ */
+declare function midiToAbc(midi: number): string;
+/**
+ * ABC duration suffix for a beat length, where the unit note (`L:`) is one
+ * matra = a quarter note. Whole numbers append the multiplier (`2`, `3`);
+ * simple fractions use `/n` (`/2` = eighth); anything else falls back to the
+ * nearest 1/4-matra count of `/4` units so odd durations still sum correctly.
+ */
+declare function abcDuration(beats: number): string;
+/**
+ * Build a complete ABC tune string from a schedule. Pure and dependency-free
+ * (the testable seam). Rests advance time as `z`; melody notes carry duration;
+ * lyrics become a `w:` line aligned to the notes.
+ *
+ * Bar lines are inserted every `beatsPerBar` matra (= one তাল cycle, so an ABC
+ * measure is one আবর্তন). This is what lets abcjs **wrap into short systems** —
+ * it only breaks lines at bar lines. `M:` is set to match so the notes-per-bar
+ * check-out. The tempo (`Q:`) rides the header.
+ *
+ * `drums`, if given, is the taal's per-beat `drumPattern()` — a second
+ * `V:2 clef=perc` percussion staff is added below the melody, cycling that
+ * pattern one quarter-note per matra with `%%percmap` GM drum sounds (see
+ * `buildDrumVoice`). Both voices share the same bar grid, so they wrap and
+ * align together.
+ */
+declare function buildAbc(schedule: Schedule, lyricOf: (ev: PlayEvent) => string | undefined, opts: {
+    bpm: number;
+    lyrics: boolean;
+    beatsPerBar: number;
+    drums?: DrumVoice[];
+}): string;
+/** Build the ABC tune string for a whole document (schedule + lyrics + tempo).
+ * The measure length is one তাল cycle (`meta.taal.numBeats`), falling back to 4.
+ * `opts.drums` adds the percussion staff (see `buildAbc`). */
+declare function docToAbc(doc: Swaralipi, opts?: StaffOptions): string;
+/**
+ * Render an ABC tune string to engraved HTML using abcjs. Requires a DOM
+ * (`document`) — abcjs measures glyphs and draws into an element; call it in a
+ * browser, in a print iframe, or under jsdom (tests stub `getBBox`). abcjs is
+ * dynamically imported so it is never bundled or loaded unless staff notation
+ * is actually used.
+ *
+ * The music is **wrapped into short systems** (a few bars per line, each its
+ * own SVG-in-DIV) — matching how আকারমাত্রিক swaralipi is laid out in stacked
+ * rows rather than one long staff. Returns the full multi-line markup (all
+ * line DIVs), or a notice string if abcjs is not installed.
+ *
+ * `notePaths`, if given, is the `part.row.note` highlight path for each ABC
+ * melody note/rest token in schedule order (see `eventPaths`). The melody is
+ * voice 0; abcjs emits its `.abcjs-v0.abcjs-note`/`.abcjs-rest` elements in
+ * document order = that same order, so painting `notePaths[i]` onto the i-th
+ * melody element gives every engraved note the same `data-note` attribute the
+ * grid languages use — playback highlighting works identically for staff. (We
+ * key off voice + document order, NOT `data-index`: with a drum voice abcjs
+ * numbers each line/voice block separately, so data-index isn't global order.)
+ */
+declare function abcToSvg(abc: string, opts?: StaffOptions, notePaths?: string[]): Promise<string>;
+/**
+ * Full doc → staff-notation HTML fragment: the shared নাম/তাল/আবর্তন/স্বরলিপিকার
+ * header (same block as the akarmatrik grid, so the staff shows the identical
+ * metadata) + an instrument label + the wrapped Western systems. Styled by
+ * SWARALIPI_CSS + SWARALIPI_STAFF_CSS. Async because abcjs is dynamic-imported.
+ */
+declare function renderStaffHtml(doc: Swaralipi, opts?: StaffOptions): Promise<string>;
 
 /**
  * Print / "Save as PDF" support.
@@ -192,16 +328,24 @@ declare const SWARALIPI_PRINT_CSS = "\n@page { margin: 16mm; }\n@media print {\n
  * matra) and the CSS-drawn marks (octave dots, slur arcs, danda strokes) that
  * the viewer renders on screen. Rasterizers (html2canvas) and PDF-primitive
  * libraries (jsPDF/pdfmake) have no Indic shaping and drop pseudo-element
- * marks, so we deliberately avoid them.
+ * marks, so we deliberately avoid them. Staff notation (lang `staff`) is drawn
+ * by abcjs to SVG, which the same print engine engraves faithfully.
  *
  * `renderPrintDocument` builds a self-contained HTML page from the pure
  * `renderToHtml` + `SWARALIPI_CSS` (so it sidesteps the shadow-DOM "print drops
  * encapsulated styles" gotcha); `printSwaralipi` prints it via a hidden iframe.
  * Both reuse the same renderer as the viewer, so the PDF matches the screen.
+ *
+ * Every printed page also carries a light diagonal watermark and a notator
+ * credit footer — both defaulted for gitabitan.io but overridable by consumers.
  */
 
-interface PrintOptions {
-    /** Notation + UI language. Default `bn`. */
+/** Default diagonal page watermark (empty string disables it). */
+declare const DEFAULT_WATERMARK = "www.gitabitan.io";
+/** Default notator credit printed in the footer. */
+declare const DEFAULT_NOTATOR = "gitabitan.io Team";
+interface PrintOptions extends StaffOptions {
+    /** Notation + UI language. `staff` = Western staff notation. Default `bn`. */
     lang?: ViewerLang;
     /** Render the নাম/তাল header block. Default true. */
     showHeader?: boolean;
@@ -210,20 +354,33 @@ interface PrintOptions {
     /** Document `<title>` — the browser's default "Save as PDF" filename.
      * Defaults to the document's `meta.title`. */
     title?: string;
+    /** Diagonal full-page watermark. Default `www.gitabitan.io`; '' to disable. */
+    watermark?: string;
+    /** Notator credited in the footer. Default `gitabitan.io Team`; '' to disable.
+     * A document's `meta.notationBy` takes precedence when present. */
+    notator?: string;
 }
 /**
- * Build a complete, standalone HTML document for printing a swaralipi sheet:
- * the rendered notation plus `SWARALIPI_CSS` and the print stylesheet, on a
- * white page. Usable for a hidden-iframe print, a new browser tab, or
- * server-side headless-Chrome PDF generation.
+ * Build a complete, standalone HTML document for printing an akarmatrik
+ * (bn/hi/en) swaralipi sheet, with watermark + notator footer. Usable for a
+ * hidden-iframe print, a new browser tab, or server-side headless-Chrome PDF.
+ *
+ * For `lang: 'staff'` this renders the grid instead (staff engraving is async
+ * — use `renderStaffPrintDocument` or `printSwaralipi`, which handle it).
  */
 declare function renderPrintDocument(doc: Swaralipi, opts?: PrintOptions): string;
+/**
+ * Async variant that engraves staff notation (abcjs) into the print page. Falls
+ * back to the grid document for non-staff langs. Returns a self-contained HTML
+ * string (for headless-Chrome PDF or a print iframe).
+ */
+declare function renderStaffPrintDocument(doc: Swaralipi, opts?: PrintOptions): Promise<string>;
 /**
  * Open the browser print dialog for a swaralipi document (the user picks a
  * printer or "Save as PDF"). Renders into an off-screen iframe so it prints
  * only the sheet — independent of the host page's chrome and CSS — then cleans
- * up. Browser-only; throws in a non-DOM environment (use renderPrintDocument
- * for SSR / headless-Chrome instead).
+ * up. Browser-only; throws in a non-DOM environment (use renderPrintDocument /
+ * renderStaffPrintDocument for SSR / headless-Chrome instead).
  */
 declare function printSwaralipi(doc: Swaralipi, opts?: PrintOptions): void;
 
@@ -252,6 +409,8 @@ interface SwaralipiSheetElement extends HTMLElement {
     clearHighlights(): void;
     /** Open the print dialog (→ "Save as PDF") for the current document. */
     print(options?: PrintOptions): void;
+    /** Options for the `staff` language (instrument label, tonic, bpm…). */
+    staffOptions: StaffOptions;
 }
 /**
  * Register `<swaralipi-sheet>` (or a custom tag name). Idempotent. Throws
@@ -276,4 +435,4 @@ type Transliterator = (bengaliText: string) => string;
  */
 declare function loadLyricTransliterator(lang: ViewerLang): Promise<Transliterator | undefined>;
 
-export { type Arc, type Cell, type Cluster, type ComposeOptions, DIGITS, LABELS, MARKS, NOTATION_FONT_URLS, type PrintOptions, type RenderOptions, SWARALIPI_CSS, SWARALIPI_PRINT_CSS, type SwaralipiSheetElement, type Transliterator, type ViewerLang, composeCluster, defineSwaralipiSheet, groupRowIntoCells, loadLyricTransliterator, localizeDigits, printSwaralipi, renderPrintDocument, renderToHtml, resolveArcs };
+export { type Arc, type Cell, type Cluster, type ComposeOptions, DEFAULT_NOTATOR, DEFAULT_WATERMARK, DIGITS, type GridLang, LABELS, MARKS, NOTATION_FONT_URLS, type PrintOptions, type RenderOptions, SWARALIPI_CSS, SWARALIPI_PRINT_CSS, SWARALIPI_STAFF_CSS, type StaffOptions, type SwaralipiSheetElement, type Transliterator, type ViewerLang, abcDuration, abcToSvg, buildAbc, composeCluster, defineSwaralipiSheet, docToAbc, groupRowIntoCells, loadLyricTransliterator, localizeDigits, midiToAbc, printSwaralipi, renderMetaHeader, renderPrintDocument, renderStaffHtml, renderStaffPrintDocument, renderToHtml, resolveArcs };

package/dist/viewer/index.d.ts

@@ -1,5 +1,8 @@
-import { O as Octave, a as SvaraLetter, N as Note, S as Swaralipi } from '../schema-D3wyNRqM.js';
+import { O as Octave, a as SvaraLetter, N as Note, M as Meta, S as Swaralipi } from '../schema-D3wyNRqM.js';
+import { S as Schedule, P as PlayEvent, c as DrumVoice } from '../schedule-PTHUONrA.js';
 import 'zod';
+import 'tone';
+import '../taals-FmEulsjY.js';
 
 /**
  * Per-language notation encoding for the viewer.
@@ -28,9 +31,12 @@ import 'zod';
  * bn ati-octave extra dot (Swarabitan's f/h are single reph/hasanta only).
  */
 
-type ViewerLang = 'bn' | 'hi' | 'en';
+/** Akarmatrik/Bhatkhande grid languages, rendered synchronously by renderToHtml. */
+type GridLang = 'bn' | 'hi' | 'en';
+/** All viewer languages. `staff` = Western staff notation (async, via abcjs). */
+type ViewerLang = GridLang | 'staff';
 /** Digits 0-9 in the target script (beat labels, avartan). */
-declare const DIGITS: Record<ViewerLang, string>;
+declare const DIGITS: Record<GridLang, string>;
 interface LangMarks {
     /** Melisma / no-new-attack dash before a sustained cluster. */
     hyphen: string;
@@ -39,9 +45,9 @@ interface LangMarks {
     /** ছেদ cut/articulation mark (two stacked rings, ঃ-shaped). */
     cut: string;
 }
-declare const MARKS: Record<ViewerLang, LangMarks>;
+declare const MARKS: Record<GridLang, LangMarks>;
 /** Header labels (NLTR prints নাম / তাল / আবর্তন …). */
-declare const LABELS: Record<ViewerLang, {
+declare const LABELS: Record<GridLang, {
     title: string;
     taal: string;
     raag: string;
@@ -60,7 +66,7 @@ interface ComposeOptions {
     octave: Octave;
     /** Append the আ-কার matra carrier (bn group-final notes only). */
     withMatra: boolean;
-    lang: ViewerLang;
+    lang: GridLang;
 }
 /**
  * Compose one svara into its notation-font ASCII. bn = Swarabitan
@@ -69,7 +75,7 @@ interface ComposeOptions {
  */
 declare function composeCluster(letter: SvaraLetter, opts: ComposeOptions): Cluster;
 /** Map ASCII digits in `s` to the target script's digits. */
-declare function localizeDigits(s: string, lang: ViewerLang): string;
+declare function localizeDigits(s: string, lang: GridLang): string;
 
 /**
  * Pure spec-JSON → HTML renderer. No DOM, no side effects: usable for SSR
@@ -141,6 +147,13 @@ interface Arc {
  * A row with fill segments but no ends at all renders one straight line.
  */
 declare function resolveArcs(cells: Cell[], noteCount: number): Arc[];
+/**
+ * The নাম / তাল / রাগ / আবর্তন / স্বরলিপিকার header block, shared by the
+ * akarmatrik grid and the staff view so both show the same metadata (localized
+ * labels; values injected pre-localized by the consumer). Exported so the
+ * staff renderer can reuse the exact markup + styling.
+ */
+declare function renderMetaHeader(meta: Meta, lang: GridLang, tr?: (s: string) => string): string;
 /** Render a complete swaralipi document to an HTML string. Pair with
  * SWARALIPI_CSS (shadow DOM does this automatically; SSR consumers emit a
  * `<style>` themselves). All source text is HTML-escaped. */
@@ -182,7 +195,130 @@ declare const SWARALIPI_CSS: string;
  *  - rows are un-clipped (no scrollbar on paper) and kept whole across page
  *    breaks; part headings stay with their first row.
  */
-declare const SWARALIPI_PRINT_CSS = "\n@page { margin: 16mm; }\n@media print {\n  .sw-sheet { -webkit-print-color-adjust: exact; print-color-adjust: exact; color: #000; }\n  .sw-row { overflow: visible !important; break-inside: avoid; page-break-inside: avoid; }\n  .sw-part { break-inside: auto; }\n  .sw-part-name, .sw-header { break-after: avoid-page; page-break-after: avoid; }\n  .sw-hl { background: none !important; }\n}\n";
+declare const SWARALIPI_PRINT_CSS = "\n@page { margin: 16mm; }\n@media print {\n  .sw-sheet, .sw-staff { -webkit-print-color-adjust: exact; print-color-adjust: exact; color: #000; }\n  .sw-row { overflow: visible !important; break-inside: avoid; page-break-inside: avoid; }\n  .sw-part { break-inside: auto; }\n  .sw-part-name, .sw-header { break-after: avoid-page; page-break-after: avoid; }\n  .sw-hl { background: none !important; }\n  /* Keep each engraved staff system whole across a page break (the abcjs line\n     is a <div> wrapping the <svg>, so the break rule must sit on the div). */\n  .sw-staff-lines > div { break-inside: avoid; page-break-inside: avoid; }\n  .sw-staff-meta { break-after: avoid-page; page-break-after: avoid; }\n}\n";
+/** Staff-notation (abcjs) wrapper chrome: instrument/tempo header + a fluid
+ * SVG. The engraving itself is drawn by abcjs; this only frames it. */
+declare const SWARALIPI_STAFF_CSS = "\n.sw-staff { color: currentColor; }\n.sw-staff-meta { display: flex; gap: 1.25em; align-items: baseline; margin: 0 0 .5em; font-size: .95em; opacity: .85; }\n.sw-staff-instrument { font-weight: 600; }\n.sw-staff-drums { opacity: .75; }\n.sw-staff-tempo { font-variant-numeric: tabular-nums; }\n/* abcjs (oneSvgPerLine) wraps the music into one <div><svg> per system; stack\n   them as short, swaralipi-style lines. abcjs sets a fixed pixel height +\n   overflow:hidden on each wrapper div \u2014 neutralise it so the viewBox'd SVG can\n   scale to the container (and to the print page) instead of being clipped. */\n.sw-staff-lines > div { margin: 0 0 .35em; height: auto !important; overflow: visible !important; }\n/* Fill up to the engraved (staffwidth) size \u2014 shrink to fit a narrow container,\n   but never stretch past natural width (abcToSvg pins per-SVG max-width in px),\n   else a short last system balloons. */\n.sw-staff-lines svg { display: block; width: 100%; height: auto; }\n.sw-staff-missing { padding: 1em; border: 1px dashed currentColor; border-radius: 6px; opacity: .8; font-size: .9em; }\n.sw-staff-title { font-size: 1.15em; font-weight: 700; }\n.sw-staff-subtitle { opacity: .8; font-size: .95em; margin-top: .15em; }\n";
+
+/**
+ * Staff (Western) notation — a 4th "language" for the viewer.
+ *
+ * Staff notation IS the melody voice drawn as a Western score, so it reuses
+ * the player's pure `buildSchedule` (the same (midi, beat, durationBeats, kan)
+ * the MIDI export writes) and turns it into an **ABC notation** string, which
+ * `abcjs` (MIT, zero-dep) engraves to SVG. abcjs is loaded through a *dynamic*
+ * `import('abcjs')` — an optional peer dep, exactly like tone/lamejs — so the
+ * viewer bundle keeps its bare-load guarantee and only consumers who want staff
+ * notation install it. Without it, `renderStaffHtml` returns a graceful notice.
+ *
+ * Scope (matches the player/MIDI): a single treble-clef melody line. The chosen
+ * instrument is a header label, not a clef change (the line is monophonic and
+ * treble covers piano + violin range with ledger lines). Microtones render as
+ * their komal approximation — the same documented limitation as playback, since
+ * abcjs has no sub-komal glyph.
+ */
+
+interface StaffOptions {
+    /** Tonic (Sa). Accepts `C`, `C#`, `cs`… Default: `meta.tonic`, else `C`. */
+    tonic?: string;
+    /** Octave of madhyam Sa (C4 = MIDI 60). Default 4. */
+    baseOctave?: number;
+    /** Tempo written into the score (Q:) and shown as a header. Default `meta.bpm`, else 90. */
+    bpm?: number;
+    /** Instrument name shown above the staff (label only — clef stays treble). */
+    instrument?: string;
+    /** Show the নাম/তাল/আবর্তন/স্বরলিপিকার header block. Default true. */
+    showHeader?: boolean;
+    /** Language for the header **labels** (values are injected pre-localized by
+     * the consumer). Default `en` — staff is the Western view. */
+    headerLang?: GridLang;
+    /** Transliterate header values (title/taal/notator) — same fn as the grid. */
+    transliterate?: (bengaliText: string) => string;
+    /** Include the `w:` lyric line under each staff. Default true. */
+    lyrics?: boolean;
+    /** Matra per bar (one তাল cycle). Default `meta.taal.numBeats`, else 4. */
+    beatsPerBar?: number;
+    /** Target line width in px passed to abcjs (music wraps within it). Default 680. */
+    staffwidth?: number;
+    /** Preferred bars per wrapped line (swaralipi-short systems). Default 4. */
+    measuresPerLine?: number;
+    /** abcjs `scale`. Default 1. */
+    scale?: number;
+    /** Add a second percussion staff below the melody, sequencing a Western
+     * drumset (kick/snare/hi-hat) to the taal's sam/tali/khaali structure —
+     * the same pattern `SwaralipiPlayer`'s `rhythm: 'drums'` plays, engraved via
+     * abcjs `%%percmap`. Default false (the score stays a single staff). Taal:
+     * `meta.taal`, else a plain 4-beat cycle (matches `beatsPerBar`'s fallback). */
+    drums?: boolean;
+}
+/**
+ * MIDI number → ABC pitch token. ABC's octave anchor is fixed by the standard:
+ * middle C (MIDI 60, C4) is uppercase `C`; lowercase `c` = C5; a comma drops an
+ * octave (`C,` = C3), an apostrophe raises one (`c'` = C6). Sharps carry a `^`.
+ */
+declare function midiToAbc(midi: number): string;
+/**
+ * ABC duration suffix for a beat length, where the unit note (`L:`) is one
+ * matra = a quarter note. Whole numbers append the multiplier (`2`, `3`);
+ * simple fractions use `/n` (`/2` = eighth); anything else falls back to the
+ * nearest 1/4-matra count of `/4` units so odd durations still sum correctly.
+ */
+declare function abcDuration(beats: number): string;
+/**
+ * Build a complete ABC tune string from a schedule. Pure and dependency-free
+ * (the testable seam). Rests advance time as `z`; melody notes carry duration;
+ * lyrics become a `w:` line aligned to the notes.
+ *
+ * Bar lines are inserted every `beatsPerBar` matra (= one তাল cycle, so an ABC
+ * measure is one আবর্তন). This is what lets abcjs **wrap into short systems** —
+ * it only breaks lines at bar lines. `M:` is set to match so the notes-per-bar
+ * check-out. The tempo (`Q:`) rides the header.
+ *
+ * `drums`, if given, is the taal's per-beat `drumPattern()` — a second
+ * `V:2 clef=perc` percussion staff is added below the melody, cycling that
+ * pattern one quarter-note per matra with `%%percmap` GM drum sounds (see
+ * `buildDrumVoice`). Both voices share the same bar grid, so they wrap and
+ * align together.
+ */
+declare function buildAbc(schedule: Schedule, lyricOf: (ev: PlayEvent) => string | undefined, opts: {
+    bpm: number;
+    lyrics: boolean;
+    beatsPerBar: number;
+    drums?: DrumVoice[];
+}): string;
+/** Build the ABC tune string for a whole document (schedule + lyrics + tempo).
+ * The measure length is one তাল cycle (`meta.taal.numBeats`), falling back to 4.
+ * `opts.drums` adds the percussion staff (see `buildAbc`). */
+declare function docToAbc(doc: Swaralipi, opts?: StaffOptions): string;
+/**
+ * Render an ABC tune string to engraved HTML using abcjs. Requires a DOM
+ * (`document`) — abcjs measures glyphs and draws into an element; call it in a
+ * browser, in a print iframe, or under jsdom (tests stub `getBBox`). abcjs is
+ * dynamically imported so it is never bundled or loaded unless staff notation
+ * is actually used.
+ *
+ * The music is **wrapped into short systems** (a few bars per line, each its
+ * own SVG-in-DIV) — matching how আকারমাত্রিক swaralipi is laid out in stacked
+ * rows rather than one long staff. Returns the full multi-line markup (all
+ * line DIVs), or a notice string if abcjs is not installed.
+ *
+ * `notePaths`, if given, is the `part.row.note` highlight path for each ABC
+ * melody note/rest token in schedule order (see `eventPaths`). The melody is
+ * voice 0; abcjs emits its `.abcjs-v0.abcjs-note`/`.abcjs-rest` elements in
+ * document order = that same order, so painting `notePaths[i]` onto the i-th
+ * melody element gives every engraved note the same `data-note` attribute the
+ * grid languages use — playback highlighting works identically for staff. (We
+ * key off voice + document order, NOT `data-index`: with a drum voice abcjs
+ * numbers each line/voice block separately, so data-index isn't global order.)
+ */
+declare function abcToSvg(abc: string, opts?: StaffOptions, notePaths?: string[]): Promise<string>;
+/**
+ * Full doc → staff-notation HTML fragment: the shared নাম/তাল/আবর্তন/স্বরলিপিকার
+ * header (same block as the akarmatrik grid, so the staff shows the identical
+ * metadata) + an instrument label + the wrapped Western systems. Styled by
+ * SWARALIPI_CSS + SWARALIPI_STAFF_CSS. Async because abcjs is dynamic-imported.
+ */
+declare function renderStaffHtml(doc: Swaralipi, opts?: StaffOptions): Promise<string>;
 
 /**
  * Print / "Save as PDF" support.
@@ -192,16 +328,24 @@ declare const SWARALIPI_PRINT_CSS = "\n@page { margin: 16mm; }\n@media print {\n
  * matra) and the CSS-drawn marks (octave dots, slur arcs, danda strokes) that
  * the viewer renders on screen. Rasterizers (html2canvas) and PDF-primitive
  * libraries (jsPDF/pdfmake) have no Indic shaping and drop pseudo-element
- * marks, so we deliberately avoid them.
+ * marks, so we deliberately avoid them. Staff notation (lang `staff`) is drawn
+ * by abcjs to SVG, which the same print engine engraves faithfully.
  *
  * `renderPrintDocument` builds a self-contained HTML page from the pure
  * `renderToHtml` + `SWARALIPI_CSS` (so it sidesteps the shadow-DOM "print drops
  * encapsulated styles" gotcha); `printSwaralipi` prints it via a hidden iframe.
  * Both reuse the same renderer as the viewer, so the PDF matches the screen.
+ *
+ * Every printed page also carries a light diagonal watermark and a notator
+ * credit footer — both defaulted for gitabitan.io but overridable by consumers.
  */
 
-interface PrintOptions {
-    /** Notation + UI language. Default `bn`. */
+/** Default diagonal page watermark (empty string disables it). */
+declare const DEFAULT_WATERMARK = "www.gitabitan.io";
+/** Default notator credit printed in the footer. */
+declare const DEFAULT_NOTATOR = "gitabitan.io Team";
+interface PrintOptions extends StaffOptions {
+    /** Notation + UI language. `staff` = Western staff notation. Default `bn`. */
     lang?: ViewerLang;
     /** Render the নাম/তাল header block. Default true. */
     showHeader?: boolean;
@@ -210,20 +354,33 @@ interface PrintOptions {
     /** Document `<title>` — the browser's default "Save as PDF" filename.
      * Defaults to the document's `meta.title`. */
     title?: string;
+    /** Diagonal full-page watermark. Default `www.gitabitan.io`; '' to disable. */
+    watermark?: string;
+    /** Notator credited in the footer. Default `gitabitan.io Team`; '' to disable.
+     * A document's `meta.notationBy` takes precedence when present. */
+    notator?: string;
 }
 /**
- * Build a complete, standalone HTML document for printing a swaralipi sheet:
- * the rendered notation plus `SWARALIPI_CSS` and the print stylesheet, on a
- * white page. Usable for a hidden-iframe print, a new browser tab, or
- * server-side headless-Chrome PDF generation.
+ * Build a complete, standalone HTML document for printing an akarmatrik
+ * (bn/hi/en) swaralipi sheet, with watermark + notator footer. Usable for a
+ * hidden-iframe print, a new browser tab, or server-side headless-Chrome PDF.
+ *
+ * For `lang: 'staff'` this renders the grid instead (staff engraving is async
+ * — use `renderStaffPrintDocument` or `printSwaralipi`, which handle it).
  */
 declare function renderPrintDocument(doc: Swaralipi, opts?: PrintOptions): string;
+/**
+ * Async variant that engraves staff notation (abcjs) into the print page. Falls
+ * back to the grid document for non-staff langs. Returns a self-contained HTML
+ * string (for headless-Chrome PDF or a print iframe).
+ */
+declare function renderStaffPrintDocument(doc: Swaralipi, opts?: PrintOptions): Promise<string>;
 /**
  * Open the browser print dialog for a swaralipi document (the user picks a
  * printer or "Save as PDF"). Renders into an off-screen iframe so it prints
  * only the sheet — independent of the host page's chrome and CSS — then cleans
- * up. Browser-only; throws in a non-DOM environment (use renderPrintDocument
- * for SSR / headless-Chrome instead).
+ * up. Browser-only; throws in a non-DOM environment (use renderPrintDocument /
+ * renderStaffPrintDocument for SSR / headless-Chrome instead).
  */
 declare function printSwaralipi(doc: Swaralipi, opts?: PrintOptions): void;
 
@@ -252,6 +409,8 @@ interface SwaralipiSheetElement extends HTMLElement {
     clearHighlights(): void;
     /** Open the print dialog (→ "Save as PDF") for the current document. */
     print(options?: PrintOptions): void;
+    /** Options for the `staff` language (instrument label, tonic, bpm…). */
+    staffOptions: StaffOptions;
 }
 /**
  * Register `<swaralipi-sheet>` (or a custom tag name). Idempotent. Throws
@@ -276,4 +435,4 @@ type Transliterator = (bengaliText: string) => string;
  */
 declare function loadLyricTransliterator(lang: ViewerLang): Promise<Transliterator | undefined>;
 
-export { type Arc, type Cell, type Cluster, type ComposeOptions, DIGITS, LABELS, MARKS, NOTATION_FONT_URLS, type PrintOptions, type RenderOptions, SWARALIPI_CSS, SWARALIPI_PRINT_CSS, type SwaralipiSheetElement, type Transliterator, type ViewerLang, composeCluster, defineSwaralipiSheet, groupRowIntoCells, loadLyricTransliterator, localizeDigits, printSwaralipi, renderPrintDocument, renderToHtml, resolveArcs };
+export { type Arc, type Cell, type Cluster, type ComposeOptions, DEFAULT_NOTATOR, DEFAULT_WATERMARK, DIGITS, type GridLang, LABELS, MARKS, NOTATION_FONT_URLS, type PrintOptions, type RenderOptions, SWARALIPI_CSS, SWARALIPI_PRINT_CSS, SWARALIPI_STAFF_CSS, type StaffOptions, type SwaralipiSheetElement, type Transliterator, type ViewerLang, abcDuration, abcToSvg, buildAbc, composeCluster, defineSwaralipiSheet, docToAbc, groupRowIntoCells, loadLyricTransliterator, localizeDigits, midiToAbc, printSwaralipi, renderMetaHeader, renderPrintDocument, renderStaffHtml, renderStaffPrintDocument, renderToHtml, resolveArcs };