@ugfoundation/swaralipi-js 0.2.0 → 0.3.0

package/dist/viewer/index.d.cts

@@ -1,86 +1,81 @@
-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 glyph tables + Unicode cluster composition for the viewer.
+ * Per-language notation encoding for the viewer.
  *
- * The akarmatrik system is script-portable: Bengali and Devanagari use the
- * same letters-with-distinct-komal-forms convention (legend: কোমল র—ঋ,
- * কোমল গ—জ্ঞ, কড়ি ম—ক্ষ, কোমল ধ—দ, কোমল ন—ণ), the same আ-কার matra carrier,
- * the same reph-above for taar and understroke for mandra. `en` has no
- * native convention, so it uses S R G M P D N with CSS marks (komal
- * underline, tivra prime, octave dots) and no matra carrier.
+ * Every language renders its notation through a dedicated, purpose-built
+ * font whose glyphs ARE the akarmatrik/Bhatkhande marks — so composeCluster
+ * emits that font's ASCII encoding and the font does all the hard work
+ * (komal/tivra forms, octave reph/dots, matra). This is why the viewer no
+ * longer touches Unicode cluster composition at all: the old reph-over-
+ * vowel, hasanta-before-matra and dotted-circle hazards simply don't exist
+ * when the font supplies precomposed glyphs keyed by plain ASCII.
  *
- * Unicode hazards owned here (see composeCluster):
- *  - mandra can NEVER be a real hasanta: letter + ্ + া is an invalid
- *    cluster (virama before vowel sign → dotted circle). It is always a
- *    CSS understroke (`sw-mandra`).
- *  - ঋ/ऋ (komal re) is an independent VOWEL letter: both র্+ঋ (reph over a
- *    vowel) and ঋ+া (vowel sign on a vowel) are invalid clusters. taar-ঋ
- *    falls back to a CSS reph (`sw-reph-css`); a matra following ঋ must be
- *    emitted as a separate isolated-matra span (`matraSeparate`).
- *  - Isolated dependent signs (া, ঃ) need a base: U+00A0 NBSP is the
- *    Unicode-sanctioned placeholder base and avoids dotted circles.
+ *  - bn → NLTR's **Swarabitan** (the akarmatrik font this project decodes).
+ *    Letters s r g m p q n = স র গ ম প ধ ন (q=ধ); komal v t d u = ঋ জ্ঞ দ ণ;
+ *    tivra ma k = the authentic কড়ি-ম conjunct (ম-based — has NO Unicode
+ *    form, which is what forced this whole approach); suffix f = taar reph,
+ *    h = mandra hasanta; trailing a = the আ-কার matra carrier. See codec.ts.
+ *  - hi/en → **Ome Bhatkhande** Hindi/English (SIL OFL 1.1, © Omenad —
+ *    github.com/omenad/fonts). Same clean keymap for both: lowercase
+ *    s r g m p d n = the seven shuddha swaras, uppercase R G M D N = komal
+ *    Re/Ga, tivra Ma, komal Dha/Ni; octave suffix u/l = taar/mandra dot,
+ *    U/L = ati (two dots). Bhatkhande has no আ-কার, so no matra is appended.
+ *
+ * The font is applied by CSS keyed on `.sw-sheet`'s `lang` (see styles.ts);
+ * composeCluster only chooses the ASCII. The single residual CSS mark is the
+ * bn ati-octave extra dot (Swarabitan's f/h are single reph/hasanta only).
  */
 
-type ViewerLang = 'bn' | 'hi' | 'en';
-interface LetterForms {
-    shuddha: string;
-    /** Distinct komal glyph (bn/hi); absent for en (CSS underline instead). */
-    komal?: string;
-    /** Distinct tivra glyph (bn/hi ক্ষ/क्ष); absent for en (CSS prime). */
-    tivra?: string;
-}
-declare const LETTERS: Record<ViewerLang, Record<SvaraLetter, LetterForms>>;
+/** 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 {
-    /** আ-কার matra carrier appended to a group-final cluster ('' for en). */
-    matra: string;
     /** Melisma / no-new-attack dash before a sustained cluster. */
     hyphen: string;
     /** Lyric continuation mark shown under sustains (the source uses ৹). */
     melisma: string;
     /** ছেদ cut/articulation mark (two stacked rings, ঃ-shaped). */
     cut: string;
-    /** Real-text reph prefix for taar ('' for en → CSS dot instead). */
-    reph: 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;
     avartan: string;
     notationBy: string;
 }>;
-/** A composed notation cluster: text plus the CSS classes for marks the
- * text itself cannot carry (mandra understroke, ati dots, en komal/tivra,
- * CSS-reph fallback). */
+/** A composed notation cluster: the font's ASCII text plus any residual CSS
+ * classes the font itself cannot express (only the bn ati-octave dot). */
 interface Cluster {
     text: string;
     classes: string[];
-    /** Set when the matra could not join the cluster (ঋ/ऋ, or en where the
-     * carrier doesn't exist) and must be emitted as an isolated-matra span. */
-    matraSeparate: boolean;
 }
 interface ComposeOptions {
     komal?: boolean;
     tivra?: boolean;
     octave: Octave;
-    /** Append the আ-কার matra carrier (group-final notes only). */
+    /** Append the আ-কার matra carrier (bn group-final notes only). */
     withMatra: boolean;
-    lang: ViewerLang;
+    lang: GridLang;
 }
 /**
- * Compose one svara cluster. The single place that knows Unicode
- * composition order: reph? + base + matra?, with the ঋ/mandra/en fallbacks
- * documented in the file header.
+ * Compose one svara into its notation-font ASCII. bn = Swarabitan
+ * (letter + f/h octave + a matra); hi/en = Ome Bhatkhande (case-encoded
+ * letter + u/l/U/L octave, no matra). The font renders the actual glyph.
  */
 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
@@ -97,8 +92,8 @@ declare function localizeDigits(s: string, lang: ViewerLang): string;
  * Rendering is spec-driven (semantics, not `raw`): grouping derives from
  * `durationMatra` accumulation so hand-authored documents without `raw`
  * render identically. `raw` is consulted only for (a) raw-only fallback
- * notes (never dropped — dimmed monospace), (b) the ছেদ cut mark and beat
- * labels, whose grammar lives in raw (see src/convert/codec.ts).
+ * notes (never dropped — dimmed, in Swarabitan when loaded), (b) the ছেদ
+ * cut mark and beat labels, whose grammar lives in raw (see codec.ts).
  */
 
 interface RenderOptions {
@@ -152,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. */
@@ -170,12 +172,17 @@ declare function renderToHtml(doc: Swaralipi, opts?: RenderOptions): string;
  *   --sw-rule       header rule / muted line color
  *
  * All ink uses `currentColor`, so the sheet follows the host's text color
- * (dark mode included). Octave marks that Unicode cannot express in a valid
- * cluster (mandra understroke, ati dots, ঋ-reph, en octave dots) are drawn
- * with positioned pseudo-elements; offsets are em-based and tuned against
- * the NLTR reference rendering of song 4270.
+ * (dark mode included). The only octave mark drawn as a pseudo-element is
+ * the bn ati-octave extra dot (Swarabitan's f/h glyphs are a single
+ * reph/hasanta); everything else is a real glyph in the notation font.
  */
-declare const SWARALIPI_CSS = "\n.sw-sheet {\n  font-family: var(--sw-font, 'Noto Sans Bengali', 'Kohinoor Bangla', 'Bangla Sangam MN', 'Nirmala UI', 'Noto Sans Devanagari', sans-serif);\n  font-size: var(--sw-size, 1.125rem);\n  line-height: 1.5;\n}\n\n/* ---- header ---- */\n.sw-header {\n  margin: 0 0 0.75em;\n  padding: 0 0 0.5em;\n  border-bottom: 1px solid var(--sw-rule, rgba(128, 128, 128, 0.35));\n  font-size: 0.95em;\n}\n.sw-meta-row { display: flex; gap: 0.3em; }\n.sw-meta-label { font-weight: 600; min-width: 4.5em; }\n.sw-meta-label::after { content: ':'; font-weight: 400; margin-left: 0.15em; }\n\n.sw-part-name { font-size: 0.85em; font-weight: 600; margin: 1em 0 0.2em; opacity: 0.85; }\n\n/* ---- row grid: above / notation / below(arcs) / lyric ---- */\n.sw-row {\n  display: flex;\n  align-items: flex-start;\n  overflow-x: auto;\n  padding: 0.4em 0;\n}\n.sw-label { flex: none; margin-right: 0.8em; font-weight: 600; }\n.sw-grid {\n  display: grid;\n  grid-template-rows: auto auto auto auto;\n  grid-auto-columns: max-content;\n  align-items: end;\n}\n.sw-above   { grid-row: 1; font-size: 0.62em; justify-self: start; white-space: nowrap; padding-left: 0.2em; }\n.sw-n       { grid-row: 2; white-space: nowrap; }\n.sw-arc,\n.sw-below   { grid-row: 3; }\n.sw-lyr     { grid-row: 4; white-space: nowrap; padding-top: 0.3em; }\n.sw-below   { font-size: 0.62em; justify-self: start; white-space: nowrap; padding-left: 0.2em; }\n\n/* inter-cell gap as padding on each cell's first notation item, so arcs\n * and above-spans crossing cells stay continuous */\n.sw-cs { padding-left: var(--sw-cell-gap, 0.55em); }\n\n/* ---- notation clusters & marks ---- */\n.sw-cl { position: relative; display: inline-block; }\n\n/* mandra: hasanta-shaped understroke (a real \u09CD before \u09BE is invalid Unicode) */\n.sw-mandra::after {\n  content: '';\n  position: absolute;\n  left: 0.1em;\n  bottom: -0.08em;\n  width: 0.45em;\n  height: 0.09em;\n  background: currentColor;\n  transform: rotate(-32deg);\n}\n/* ati-mandra: an extra dot below */\n.sw-ati-mandra::before {\n  content: '';\n  position: absolute;\n  left: 0.25em;\n  bottom: -0.35em;\n  width: 0.16em;\n  height: 0.16em;\n  border-radius: 50%;\n  background: currentColor;\n}\n/* ati-taar (reph already in the text): an extra dot above */\n.sw-ati-taar::before {\n  content: '';\n  position: absolute;\n  left: 0.25em;\n  top: -0.3em;\n  width: 0.16em;\n  height: 0.16em;\n  border-radius: 50%;\n  background: currentColor;\n}\n/* CSS reph fallback for vowel letters \u098B/\u090B that reject a real reph */\n.sw-reph-css::before {\n  content: '';\n  position: absolute;\n  top: -0.12em;\n  left: 0.12em;\n  width: 0.3em;\n  height: 0.3em;\n  border: 0.09em solid currentColor;\n  border-right: none;\n  border-bottom: none;\n  border-top-left-radius: 0.3em;\n}\n/* en octave dots (Bhatkhande-style) */\n.sw-dot-above::before,\n.sw-dot-below::before {\n  content: '';\n  position: absolute;\n  left: 50%;\n  margin-left: -0.07em;\n  width: 0.14em;\n  height: 0.14em;\n  border-radius: 50%;\n  background: currentColor;\n}\n.sw-dot-above::before { top: -0.25em; }\n.sw-dot-below::before { bottom: -0.2em; }\n.sw-ati-taar.sw-dot-above::before,\n.sw-ati-mandra.sw-dot-below::before { box-shadow: 0.24em 0 0 currentColor; margin-left: -0.19em; }\n/* en accidentals (bn/hi use distinct letters instead) */\n.sw-komal { text-decoration: underline; text-underline-offset: 0.18em; }\n.sw-tivra::after { content: '\\2032'; font-size: 0.7em; vertical-align: super; }\n\n/* kan grace: small raised cluster left of the main note */\n.sw-kan {\n  position: relative;\n  display: inline-block;\n  font-size: 0.58em;\n  vertical-align: 0.75em;\n  margin-right: 0.08em;\n}\n\n.sw-hy { padding-right: 0.02em; }\n.sw-iso { display: inline-block; margin-left: -0.18em; }\n.sw-cut { font-size: 0.8em; display: inline-block; margin-left: -0.15em; }\n.sw-br { opacity: 0.8; padding: 0 0.06em; }\n.sw-micro { font-size: 0.6em; vertical-align: super; opacity: 0.8; }\n\n/* raw fallback: never dropped, visibly non-notation */\n.sw-raw {\n  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;\n  font-size: 0.72em;\n  opacity: 0.55;\n}\n\n/* ---- bars: dari (thin) and danda strokes, notation-row height ---- */\n/* horizontal gap before a bar comes from its own .sw-cs padding-left \u2014\n * never reset it with a padding shorthand here */\n.sw-bar {\n  grid-row: 2;\n  align-self: stretch;\n  display: inline-flex;\n  align-items: stretch;\n  gap: 0.16em;\n  padding-right: 0.1em;\n}\n.sw-bar i { display: inline-block; width: 0.14em; min-height: 1.25em; background: currentColor; }\n.sw-bar--dari i { width: 0.05em; opacity: 0.9; }\n.sw-bar--quad i:nth-child(3) { margin-left: 0.18em; }\n.sw-above .sw-bar, .sw-below .sw-bar { display: inline-flex; vertical-align: baseline; }\n.sw-above .sw-bar i, .sw-below .sw-bar i { min-height: 1em; }\n\n/* ---- under-arcs (slurs decoded from w/x segments and meend) ---- */\n.sw-arc {\n  align-self: start;\n  height: 0.4em;\n  margin: 0.05em 0.25em 0;\n  border: 0.09em solid currentColor;\n  border-top: none;\n  border-bottom-left-radius: 0.6em;\n  border-bottom-right-radius: 0.6em;\n  opacity: 0.85;\n}\n.sw-arc--openl { border-left: none; border-bottom-left-radius: 0; }\n.sw-arc--openr { border-right: none; border-bottom-right-radius: 0; }\n.sw-arc--line { border-left: none; border-right: none; border-radius: 0; height: 0.22em; }\n\n/* ---- annotation content ---- */\n.sw-beat { position: relative; display: inline-block; padding: 0 0.1em; }\n.sw-sam::after {\n  content: '';\n  position: absolute;\n  top: -0.45em;\n  left: 50%;\n  width: 0.1em;\n  height: 0.4em;\n  background: currentColor;\n  transform: rotate(14deg);\n}\n.sw-stop i {\n  display: inline-block;\n  width: 0.07em;\n  height: 1em;\n  margin: 0 0.07em;\n  background: currentColor;\n  vertical-align: text-bottom;\n}\n\n/* ---- player sync (P2.3) ---- */\n.sw-hl { background: var(--sw-hl, rgba(255, 196, 64, 0.45)); border-radius: 0.15em; }\n\n/* ---- element error box ---- */\n.sw-error {\n  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;\n  font-size: 0.85em;\n  padding: 0.6em 0.8em;\n  border: 1px solid rgba(200, 64, 64, 0.6);\n  border-radius: 0.3em;\n  color: #b33;\n  background: rgba(200, 64, 64, 0.08);\n}\n";
+/** Notation fonts, self-hosted on the project CDN (CORS-enabled), keyed by
+ * the CSS `font-family` this stylesheet uses. bn = NLTR's Swarabitan; hi/en
+ * = Ome Bhatkhande (SIL OFL 1.1, © Omenad — github.com/omenad/fonts).
+ * Self-hosters: declare your own \`@font-face\` for any of these families
+ * before this stylesheet / before defineSwaralipiSheet() and it wins. */
+declare const NOTATION_FONT_URLS: Record<string, string>;
+declare const SWARALIPI_CSS: string;
 /**
  * Print stylesheet — pair with `SWARALIPI_CSS` (renderPrintDocument injects
  * both). Gated on `@media print`, so it also works if a consumer drops it into
@@ -188,7 +195,130 @@ declare const SWARALIPI_CSS = "\n.sw-sheet {\n  font-family: var(--sw-font, 'Not
  *  - 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.
@@ -198,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;
@@ -216,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;
 
@@ -258,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
@@ -282,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, LETTERS, MARKS, 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 };