guidex 0.4.0 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -22,7 +22,8 @@ var FAMILIES = {
22
22
  modifyDown: "ø",
23
23
  modifyNatural: "“",
24
24
  cephalicus: "§",
25
- connectOneDown: "Þ"
25
+ connectOneDown: "Þ",
26
+ connectTwoDown: "Ô"
26
27
  },
27
28
  "1": {
28
29
  virga: "q",
@@ -1426,6 +1427,198 @@ function fontStringsToVerify(styleSet, textPx) {
1426
1427
  return styleSet.verifiedFonts.map((f) => `${f.weight} ${textPx}px ${f.family}`);
1427
1428
  }
1428
1429
  //#endregion
1430
+ //#region src/recitationSegments.ts
1431
+ /** The reciting pitch of a note group: one reciting glyph, or one plain
1432
+ * note that has one, optionally after one accidental sign; null for any
1433
+ * other group. */
1434
+ function recitationPitch(notes) {
1435
+ const sign = notes.length === 2 && isModifierGlyph(notes[0]) ? notes[0] : "";
1436
+ const ch = notes.slice(sign.length);
1437
+ if (ch.length !== 1) return null;
1438
+ const family = baseOf(ch);
1439
+ if (family?.role === "longa") return {
1440
+ sign,
1441
+ plain: family.base,
1442
+ glyph: ch,
1443
+ written: "glyph"
1444
+ };
1445
+ const glyph = toLonga(ch);
1446
+ return glyph ? {
1447
+ sign,
1448
+ plain: ch,
1449
+ glyph,
1450
+ written: "plain"
1451
+ } : null;
1452
+ }
1453
+ /** The notes a group renders with in a mode. */
1454
+ function notesInMode(notes, mode) {
1455
+ const pitch = recitationPitch(notes);
1456
+ if (!pitch || mode === "written") return notes;
1457
+ return pitch.sign + (mode === "recite" ? pitch.glyph : pitch.plain);
1458
+ }
1459
+ /** What a mode renders, in written terms: 'recite' or 'plain'. */
1460
+ function shownAs(notes, mode) {
1461
+ if (mode !== "written") return mode;
1462
+ return recitationPitch(notes)?.written === "glyph" ? "recite" : "plain";
1463
+ }
1464
+ /** The decisions' view of a script: its syllables, and where a clef or key
1465
+ * statement stands (a run never continues across one). */
1466
+ function runSyllables(underlays) {
1467
+ const syllables = [];
1468
+ const pitchBreaks = /* @__PURE__ */ new Set();
1469
+ (underlays[0] ?? []).forEach((tok, k) => {
1470
+ if (tok.kind === "clef" || tok.kind === "key") pitchBreaks.add(syllables.length);
1471
+ if (tok.kind !== "syllable") return;
1472
+ const counted = underlays.some((u) => {
1473
+ const own = u[k];
1474
+ return own?.kind === "syllable" && !own.held && !own.empty;
1475
+ });
1476
+ syllables.push({
1477
+ notes: tok.notes,
1478
+ counted
1479
+ });
1480
+ });
1481
+ return {
1482
+ syllables,
1483
+ pitchBreaks
1484
+ };
1485
+ }
1486
+ /** Whether a syllable can join a recitation run under the options. */
1487
+ function isMember(syl, options) {
1488
+ const pitch = recitationPitch(syl.notes);
1489
+ if (!pitch) return false;
1490
+ return pitch.written === "glyph" || options.plainRunsToRecitation;
1491
+ }
1492
+ /** The run key of a member: its pitch, glyph and plain note alike. */
1493
+ function runKey(notes) {
1494
+ const pitch = recitationPitch(notes);
1495
+ return pitch.sign + pitch.plain;
1496
+ }
1497
+ /**
1498
+ * The mode each member is first laid out in: a recitation when its run in
1499
+ * the script counts 3 or more syllables (so the line segments are counted
1500
+ * with the recitation's widths), else as written (a run of 2 or fewer can
1501
+ * only ever need its pair converted).
1502
+ */
1503
+ function trialModes(syllables, pitchBreaks, options) {
1504
+ const modes = /* @__PURE__ */ new Map();
1505
+ let k = 0;
1506
+ while (k < syllables.length) {
1507
+ if (!isMember(syllables[k], options)) {
1508
+ k++;
1509
+ continue;
1510
+ }
1511
+ const key = runKey(syllables[k].notes);
1512
+ let end = k;
1513
+ let count = 0;
1514
+ while (end < syllables.length && isMember(syllables[end], options) && runKey(syllables[end].notes) === key && (end === k || !pitchBreaks.has(end))) {
1515
+ if (syllables[end].counted) count++;
1516
+ end++;
1517
+ }
1518
+ for (let j = k; j < end; j++) modes.set(j, count >= 3 ? "recite" : "written");
1519
+ k = end;
1520
+ }
1521
+ return modes;
1522
+ }
1523
+ /** Whether a script has anything for the decisions to do. */
1524
+ function hasCandidates(syllables, options) {
1525
+ if (!options.twoSyllableRecitationsToPlain && !options.plainRunsToRecitation) return false;
1526
+ return syllables.some((s) => isMember(s, options));
1527
+ }
1528
+ /** The line segments of a pass: consecutive members on the same line with
1529
+ * the same placed pitch. */
1530
+ function segmentsOf(syllables, placedNotes, sylLines, options) {
1531
+ const segments = [];
1532
+ let current;
1533
+ let currentKey = "";
1534
+ let currentLine = -1;
1535
+ syllables.forEach((syl, k) => {
1536
+ const placed = placedNotes[k];
1537
+ const line = sylLines[k];
1538
+ if (!(isMember(syl, options) && placed !== void 0 && line !== void 0 && recitationPitch(placed) !== null)) {
1539
+ current = void 0;
1540
+ return;
1541
+ }
1542
+ const key = runKey(placed);
1543
+ if (!current || key !== currentKey || line !== currentLine) {
1544
+ current = {
1545
+ members: [],
1546
+ count: 0
1547
+ };
1548
+ segments.push(current);
1549
+ currentKey = key;
1550
+ currentLine = line;
1551
+ }
1552
+ current.members.push(k);
1553
+ if (syl.counted) current.count++;
1554
+ });
1555
+ return segments;
1556
+ }
1557
+ function initialState() {
1558
+ return {
1559
+ decided: /* @__PURE__ */ new Map(),
1560
+ breakBefore: /* @__PURE__ */ new Set(),
1561
+ pending: null
1562
+ };
1563
+ }
1564
+ /** The mode each member renders with in the next pass. */
1565
+ function passModes(trial, state) {
1566
+ const modes = new Map(trial);
1567
+ for (const [k, mode] of state.decided) modes.set(k, mode);
1568
+ return modes;
1569
+ }
1570
+ /**
1571
+ * One step of the decisions over a laid-out pass, from the left: checks the
1572
+ * segment changed in the previous step, then decides segments in order while
1573
+ * the pass already rendered them as decided, and stops at the first one
1574
+ * whose decision changes what the pass rendered. Returns whether another
1575
+ * pass is needed.
1576
+ *
1577
+ * Every pass lays the score out left to right, so a decision only moves
1578
+ * what comes after it: the segments decided before it stay where they
1579
+ * were. A segment is counted on the line the pass put it on, and a change
1580
+ * keeps it there: one that opened its line still opens it (as plain notes
1581
+ * it might fit the line before), and a member that no longer fits its line
1582
+ * in the new form (a pair turned plain is wider than its recitation) opens
1583
+ * the next one and is decided again there, the members before it keeping
1584
+ * their written form.
1585
+ */
1586
+ function decideStep(syllables, placedNotes, sylLines, modes, state, options) {
1587
+ if (state.pending) {
1588
+ const { members, line } = state.pending;
1589
+ state.pending = null;
1590
+ const moved = members.findIndex((k) => sylLines[k] !== line);
1591
+ if (moved >= 0) {
1592
+ members.forEach((k, j) => {
1593
+ if (j < moved) state.decided.set(k, "written");
1594
+ else state.decided.delete(k);
1595
+ });
1596
+ state.breakBefore.add(members[moved]);
1597
+ return true;
1598
+ }
1599
+ }
1600
+ for (const segment of segmentsOf(syllables, placedNotes, sylLines, options)) {
1601
+ if (segment.members.every((k) => state.decided.has(k))) continue;
1602
+ const target = segment.count >= 3 ? "recite" : segment.count === 2 && options.twoSyllableRecitationsToPlain ? "plain" : "written";
1603
+ const changes = segment.members.some((k) => {
1604
+ const notes = syllables[k].notes;
1605
+ return shownAs(notes, modes.get(k) ?? "written") !== shownAs(notes, target);
1606
+ });
1607
+ for (const k of segment.members) state.decided.set(k, target);
1608
+ if (changes) {
1609
+ const first = segment.members[0];
1610
+ const line = sylLines[first];
1611
+ if (first > 0 && (sylLines[first - 1] ?? -1) < line) state.breakBefore.add(first);
1612
+ state.pending = {
1613
+ members: segment.members,
1614
+ line
1615
+ };
1616
+ return true;
1617
+ }
1618
+ }
1619
+ return false;
1620
+ }
1621
+ //#endregion
1429
1622
  //#region src/chantLayout.ts
1430
1623
  /**
1431
1624
  * Special reciting notes: when such a note stands alone in a note group it
@@ -1618,12 +1811,51 @@ function silent(tok) {
1618
1811
  * fonts cannot be loaded.
1619
1812
  */
1620
1813
  async function layoutScore(source, options = {}) {
1814
+ const recitation = {
1815
+ twoSyllableRecitationsToPlain: options.twoSyllableRecitationsToPlain ?? true,
1816
+ plainRunsToRecitation: options.plainRunsToRecitation ?? false
1817
+ };
1818
+ const { syllables, pitchBreaks } = runSyllables(underlayTokens(source));
1819
+ if (!hasCandidates(syllables, recitation)) return (await layoutKept(source, options, NO_RECITATION)).result;
1820
+ const trial = trialModes(syllables, pitchBreaks, recitation);
1821
+ const state = initialState();
1822
+ for (let step = 0;; step++) {
1823
+ const modes = passModes(trial, state);
1824
+ const pass = await layoutKept(source, options, {
1825
+ notes: notesOverrides(syllables.map((s) => s.notes), modes),
1826
+ breakBefore: state.breakBefore
1827
+ });
1828
+ if (step > 4 * syllables.length + 8 || !decideStep(syllables, pass.placedNotes, pass.sylLines, modes, state, recitation)) return pass.result;
1829
+ }
1830
+ }
1831
+ /** The notes each syllable renders with under the recitation modes, where
1832
+ * they differ from the written ones. */
1833
+ function notesOverrides(written, modes) {
1834
+ const notes = /* @__PURE__ */ new Map();
1835
+ for (const [k, mode] of modes) {
1836
+ const shown = notesInMode(written[k], mode);
1837
+ if (shown !== written[k]) notes.set(k, shown);
1838
+ }
1839
+ return notes;
1840
+ }
1841
+ var NO_RECITATION = {
1842
+ notes: /* @__PURE__ */ new Map(),
1843
+ breakBefore: /* @__PURE__ */ new Set()
1844
+ };
1845
+ /** One layout with its `(@keep)` runs settled: a run is only known to fit
1846
+ * once it is placed, pads and group splits included, so a run that ends up
1847
+ * split is retried with a break before it. One wider than a fresh line
1848
+ * stops counting: a flat run wraps where it stood, and a run with inner
1849
+ * runs dissolves into them but keeps its break, so the boundary between
1850
+ * pairs still wins over the one between verses. Runs number in opening
1851
+ * order, so the lowest split is the leftmost and outermost. */
1852
+ async function layoutKept(source, options, recitation) {
1621
1853
  const breakBefore = /* @__PURE__ */ new Set();
1622
1854
  const wraps = /* @__PURE__ */ new Set();
1623
1855
  for (;;) {
1624
- const { result, splitRuns } = await layoutPass(source, options, breakBefore);
1625
- const open = splitRuns.filter((r) => !wraps.has(r.run));
1626
- if (open.length === 0) return result;
1856
+ const pass = await layoutPass(source, options, breakBefore, recitation);
1857
+ const open = pass.splitRuns.filter((r) => !wraps.has(r.run));
1858
+ if (open.length === 0) return pass;
1627
1859
  const split = open.reduce((a, b) => b.run < a.run ? b : a);
1628
1860
  if (breakBefore.has(split.run) || split.atLineStart) {
1629
1861
  wraps.add(split.run);
@@ -1634,8 +1866,9 @@ async function layoutScore(source, options = {}) {
1634
1866
  }
1635
1867
  /** One pass of `layoutScore`: `breakBefore` lists the `(@keep)` runs (by
1636
1868
  * position in the script) that open a fresh line; `splitRuns` reports the
1637
- * ones that crossed a line break. */
1638
- async function layoutPass(source, options, breakBefore) {
1869
+ * ones that crossed a line break. `recitation` carries the recitation
1870
+ * segments' forms and breaks (issue #21). */
1871
+ async function layoutPass(source, options, breakBefore, recitation = NO_RECITATION) {
1639
1872
  const { style: styleName = "BNS", marks, bold = false, textPx = 18, notesPx = textPx * 2, maxWidthPx = Infinity, junctionDashes = 3, staffFill = "all-but-last", staffFillSnapPx = 0 } = options;
1640
1873
  if (!STAFF_FILLS.includes(staffFill)) throw new Error(`Unknown staffFill: "${staffFill}"`);
1641
1874
  if (!(staffFillSnapPx >= 0 && Number.isFinite(staffFillSnapPx))) throw new Error(`staffFillSnapPx must be zero or more: ${staffFillSnapPx}`);
@@ -1748,11 +1981,12 @@ async function layoutPass(source, options, breakBefore) {
1748
1981
  if (tightDepth === 0) tightGroupPlaced = false;
1749
1982
  }
1750
1983
  } else {
1984
+ const i = sylIndex++;
1751
1985
  const item = {
1752
1986
  kind: "syl",
1753
1987
  syl: tok,
1754
- i: sylIndex++,
1755
- notes: tok.notes,
1988
+ i,
1989
+ notes: recitation.notes.get(i) ?? tok.notes,
1756
1990
  inserted: [],
1757
1991
  first: true,
1758
1992
  lastSeg: true,
@@ -1849,8 +2083,15 @@ async function layoutPass(source, options, breakBefore) {
1849
2083
  const run = keepStack.pop();
1850
2084
  if (run && lines.length - 1 > run.line) splitRuns.push(run);
1851
2085
  };
2086
+ const sylLines = [];
2087
+ let placedSyl = -1;
2088
+ const notePlacedLine = () => {
2089
+ if (placedSyl >= 0) sylLines[placedSyl] = lines.length - 1;
2090
+ placedSyl = -1;
2091
+ };
1852
2092
  let idx = 0;
1853
2093
  while (idx < items.length) {
2094
+ notePlacedLine();
1854
2095
  const item = items[idx];
1855
2096
  if (item.kind === "break") {
1856
2097
  if (line.texts.some((x) => x.segments.length > 0) || tracks.some((t) => t.pending.length > 0)) {
@@ -1909,6 +2150,11 @@ async function layoutPass(source, options, breakBefore) {
1909
2150
  }
1910
2151
  const syl = item.syl;
1911
2152
  const i = item.i;
2153
+ if (item.first) placedSyl = i;
2154
+ if (item.first && recitation.breakBefore.has(i) && (line.texts.some((x) => x.segments.length > 0) || tracks.some((t) => t.pending.length > 0))) {
2155
+ flushPending(false);
2156
+ forceBreak = true;
2157
+ }
1912
2158
  if (forceBreak) {
1913
2159
  startLine();
1914
2160
  forceBreak = false;
@@ -2051,38 +2297,48 @@ async function layoutPass(source, options, breakBefore) {
2051
2297
  };
2052
2298
  };
2053
2299
  let placed = place();
2054
- for (;;) {
2055
- const notesOver = measure(notesSoFar + junctionPrefix + item.notes, notesFont) > maxWidthPx;
2056
- const textOver = voiced.some((s) => placed.textStartOf(s.textWidth) + s.textWidth + (s.own.wordEnd ? 0 : hyphenOf(s.own.hyphen).width) > maxWidthPx);
2057
- if (!notesOver && !textOver) break;
2058
- if (notesOver) {
2059
- const cut = findBreakCut(item.notes, maxWidthPx, (prefix) => measure(notesSoFar + junctionPrefix + prefix, notesFont));
2060
- if (cut >= 0 && cut + 1 < item.notes.length) {
2061
- const rest = applyBreakCut(item, cut);
2062
- queueContinuation(item, idx, rest);
2063
- parts = splitNoteMarkers(item.notes);
2064
- placed = place();
2065
- break;
2066
- }
2067
- }
2068
- if (line.notesParts.length === 0 && tracks.every((t) => t.cursor === 0)) {
2300
+ const uncut = {
2301
+ notes: item.notes,
2302
+ inserted: item.inserted,
2303
+ lastSeg: item.lastSeg,
2304
+ forceBreak,
2305
+ items: items.length
2306
+ };
2307
+ const fit = () => {
2308
+ for (;;) {
2309
+ const notesOver = measure(notesSoFar + junctionPrefix + item.notes, notesFont) > maxWidthPx;
2310
+ const textOver = voiced.some((s) => placed.textStartOf(s.textWidth) + s.textWidth + (s.own.wordEnd ? 0 : hyphenOf(s.own.hyphen).width) > maxWidthPx);
2311
+ if (!notesOver && !textOver) break;
2069
2312
  if (notesOver) {
2070
- const cut = findBreakCut(item.notes, maxWidthPx, (prefix) => measure(notesSoFar + prefix, notesFont));
2313
+ const cut = findBreakCut(item.notes, maxWidthPx, (prefix) => measure(notesSoFar + junctionPrefix + prefix, notesFont));
2071
2314
  if (cut >= 0 && cut + 1 < item.notes.length) {
2072
2315
  const rest = applyBreakCut(item, cut);
2073
- item.notes = item.notes.slice(0, cut);
2074
2316
  queueContinuation(item, idx, rest);
2075
2317
  parts = splitNoteMarkers(item.notes);
2076
2318
  placed = place();
2319
+ break;
2077
2320
  }
2078
2321
  }
2079
- break;
2322
+ if (line.notesParts.length === 0 && tracks.every((t) => t.cursor === 0)) {
2323
+ if (notesOver) {
2324
+ const cut = findBreakCut(item.notes, maxWidthPx, (prefix) => measure(notesSoFar + prefix, notesFont));
2325
+ if (cut >= 0 && cut + 1 < item.notes.length) {
2326
+ const rest = applyBreakCut(item, cut);
2327
+ item.notes = item.notes.slice(0, cut);
2328
+ queueContinuation(item, idx, rest);
2329
+ parts = splitNoteMarkers(item.notes);
2330
+ placed = place();
2331
+ }
2332
+ }
2333
+ break;
2334
+ }
2335
+ startLine();
2336
+ junctionPrefix = "";
2337
+ parts = splitNoteMarkers(item.notes);
2338
+ placed = place();
2080
2339
  }
2081
- startLine();
2082
- junctionPrefix = "";
2083
- parts = splitNoteMarkers(item.notes);
2084
- placed = place();
2085
- }
2340
+ };
2341
+ fit();
2086
2342
  const decide = (s) => {
2087
2343
  const { t, textWidth } = s;
2088
2344
  const { contentWidth } = placed;
@@ -2174,10 +2430,19 @@ async function layoutPass(source, options, breakBefore) {
2174
2430
  if (line.notesParts.length > 0 && (measure(notesSoFar + junctionPrefix + "-".repeat(padDashes) + item.notes, notesFont) > maxWidthPx || voiced.some((s, v) => {
2175
2431
  return Math.max(placements[v].textStart, s.t.cursor + s.pendingTotal) + s.textWidth + (s.own.wordEnd ? 0 : hyphenOf(s.own.hyphen).width) > maxWidthPx;
2176
2432
  }))) {
2433
+ const recut = items.length > uncut.items;
2434
+ if (recut) {
2435
+ items.splice(idx + 1, items.length - uncut.items);
2436
+ item.notes = uncut.notes;
2437
+ item.inserted = uncut.inserted;
2438
+ item.lastSeg = uncut.lastSeg;
2439
+ forceBreak = uncut.forceBreak;
2440
+ }
2177
2441
  startLine();
2178
2442
  junctionPrefix = "";
2179
2443
  parts = splitNoteMarkers(item.notes);
2180
2444
  placed = place();
2445
+ if (recut) fit();
2181
2446
  settle();
2182
2447
  }
2183
2448
  }
@@ -2271,6 +2536,7 @@ async function layoutPass(source, options, breakBefore) {
2271
2536
  if (!item.lastSeg) forceBreak = true;
2272
2537
  idx++;
2273
2538
  }
2539
+ notePlacedLine();
2274
2540
  flushPending(true);
2275
2541
  while (keepStack.length > 0) closeKeepRun();
2276
2542
  tracks.forEach((t, u) => {
@@ -2342,8 +2608,10 @@ async function layoutPass(source, options, breakBefore) {
2342
2608
  starTarget,
2343
2609
  starWidth
2344
2610
  },
2345
- splitRuns
2611
+ splitRuns,
2612
+ placedNotes,
2613
+ sylLines
2346
2614
  };
2347
2615
  }
2348
2616
  //#endregion
2349
- export { CLEF_GLYPHS as A, toConnectDown as B, scriptSyllables as C, resolveSpans as D, unescape as E, isModifierGlyph as F, variantOf as G, toSmallHead as H, modifyDown as I, modifyNatural as L, baseOf as M, gClefPitchOf as N, SCORE_MARKERS as O, isClefGlyph as P, modifyUp as R, runProperties as S, syllableText as T, toSmallPoint as U, toLonga as V, toVirga as W, GuidoScript as _, DEFAULT_STYLE_SET as a, isC4ClefGroup as b, defineStyleSet as c, measurementFont as d, resolveMarks as f, unknownMarks as g, styleSetOf as h, measure as i, STAFF as j, splitNoteMarkers as k, inlineStylesFor as l, resolveTextRuns as m, SPECIAL_NOTES as n, SMALL_CAP_SCALE as o, resolveSyllableParts as p, layoutScore as r, STYLE_SETS as s, NOTE_MODIFIERS as t, kindOf as u, chantText as v, statementSource as w, isStatementGroup as x, escape as y, toCephalicus as z };
2617
+ export { CLEF_GLYPHS as A, toCephalicus as B, scriptSyllables as C, resolveSpans as D, unescape as E, isModifierGlyph as F, toVirga as G, toLonga as H, modifyDown as I, variantOf as K, modifyNatural as L, baseOf as M, gClefPitchOf as N, SCORE_MARKERS as O, isClefGlyph as P, modifyUp as R, runProperties as S, syllableText as T, toSmallHead as U, toConnectDown as V, toSmallPoint as W, GuidoScript as _, DEFAULT_STYLE_SET as a, isC4ClefGroup as b, defineStyleSet as c, measurementFont as d, resolveMarks as f, unknownMarks as g, styleSetOf as h, measure as i, STAFF as j, splitNoteMarkers as k, inlineStylesFor as l, resolveTextRuns as m, SPECIAL_NOTES as n, SMALL_CAP_SCALE as o, resolveSyllableParts as p, layoutScore as r, STYLE_SETS as s, NOTE_MODIFIERS as t, kindOf as u, chantText as v, statementSource as w, isStatementGroup as x, escape as y, pitchLetterOf as z };
@@ -1,6 +1,7 @@
1
1
  import { GuidoScript } from './guidoScript';
2
2
  import { SCORE_MARKERS } from './noteGroups';
3
3
  import { StyleSet, MarkDefinitions, StyleSetName, SyllablePart } from './guidoStyles';
4
+ import { RecitationOptions } from './recitationSegments';
4
5
  export { SCORE_MARKERS };
5
6
  /**
6
7
  * Special reciting notes: when such a note stands alone in a note group it
@@ -31,7 +32,7 @@ export type StaffFill = 'all-but-last' | 'none' | 'all' | 'longest';
31
32
  export declare const STAFF_FILLS: readonly StaffFill[];
32
33
  /** Options for one layout pass. All fields optional; defaults reproduce the
33
34
  * original Book Antiqua look (style set BNS). */
34
- export interface LayoutOptions {
35
+ export interface LayoutOptions extends RecitationOptions {
35
36
  /** Named style set (default: BNS) */
36
37
  style?: StyleSetName;
37
38
  /** Marks this score adds to its style set's */
@@ -0,0 +1,130 @@
1
+ /** How the staff is drawn: by the font (Guido HU's own lines, the default)
2
+ * or as elements behind the staffless font. */
3
+ export type StaffMode = 'font' | 'drawn';
4
+ /** A staff line color: any CSS color (alpha included), or one for the light
5
+ * and one for the dark color scheme. */
6
+ export type StaffColor = string | {
7
+ readonly light: string;
8
+ readonly dark?: string;
9
+ };
10
+ export type PitchLetter = 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g';
11
+ /** The drawn staff's options (render, embed and React). */
12
+ export interface DrawnStaffOptions {
13
+ /** How the staff is drawn (default `font`); every option below needs `drawn` */
14
+ staff?: StaffMode;
15
+ /** The fewest lines to draw, 1–5 (default 5). The lines sit where the
16
+ * score's notes and clefs need them, and more are drawn when a note
17
+ * would otherwise need a ledger line (or a clef has no line to sit on). */
18
+ staffLines?: number;
19
+ /** Every drawn line's color (default: the notes' text color) */
20
+ staffColor?: StaffColor;
21
+ /** Colors by position, bottom line first; wins over `staffColor` */
22
+ staffLineColors?: readonly (StaffColor | null | undefined)[];
23
+ /** Colors by the pitch a line carries under the clef in effect (the
24
+ * historical red F and yellow C lines); wins over the others */
25
+ staffPitchColors?: Readonly<Partial<Record<PitchLetter, StaffColor>>>;
26
+ /** Every drawn line's thickness as a multiple of the font's (default 1).
27
+ * The weights multiply: all × by position × clef line. */
28
+ staffWeight?: number;
29
+ /** Thickness multipliers by position, bottom line first (default 1) */
30
+ staffLineWeights?: readonly (number | null | undefined)[];
31
+ /** Thickness multiplier of the line the clef in effect sits on, which
32
+ * follows inline clef changes (default 1): above 1, the clef's line
33
+ * stands out from the others */
34
+ staffClefLineWeight?: number;
35
+ /** Run every drawn line past the score: `start` is where the lines begin
36
+ * and `end` where they end, in px from the notes line's left edge (a
37
+ * negative `start` reaches left of it). A line already longer keeps its
38
+ * own ends. Nothing is resized: the lines just overflow the score (and
39
+ * its container), so the host decides how far, e.g. to the screen's
40
+ * edges, and whether a scrolling ancestor clips them. */
41
+ staffOverflow?: StaffOverflow;
42
+ /** Snap the lines to device pixels after a render (default true) */
43
+ staffSnap?: boolean;
44
+ }
45
+ /** How far the drawn lines run past the score (`DrawnStaffOptions.staffOverflow`). */
46
+ export interface StaffOverflow {
47
+ start?: number;
48
+ end?: number;
49
+ }
50
+ /** The staffless font's family, as the notes line's font stack names it. */
51
+ export declare const STAFFLESS_FONT_FAMILY = "'Guidohu Staffless'";
52
+ export declare const STAFF_LINE_COUNT: number;
53
+ /** The drawn lines, as line indices (0 = bottom) `lo`…`hi`. */
54
+ export interface StaffLineRange {
55
+ lo: number;
56
+ hi: number;
57
+ }
58
+ /**
59
+ * The lines to draw for a score: the lowest run of at least `fewest` lines
60
+ * that carries every note and clef without a ledger line. A note on a line
61
+ * needs that line; a note in a space needs a line next to it (a space just
62
+ * outside the outermost line is fine); a clef needs its line. A note beyond
63
+ * the five lines brings its ledger lines with the glyph, so the staff then
64
+ * runs to the outermost line. When the notes need more lines than `fewest`,
65
+ * more are drawn.
66
+ */
67
+ export declare function chooseStaffLines(lines: readonly {
68
+ clefPrefix: string;
69
+ notesParts: readonly string[];
70
+ }[], fewest?: number): StaffLineRange;
71
+ /** The color a line takes under `clef` (a clef glyph), or undefined for
72
+ * the default (the notes' text color). */
73
+ export declare function staffLineColor(index: number, clef: string, options: DrawnStaffOptions): StaffColor | undefined;
74
+ /** A line's thickness multiplier under `clef`: all lines × its position ×
75
+ * the clef's own line. */
76
+ export declare function staffLineWeight(index: number, clef: string, options: DrawnStaffOptions): number;
77
+ /** One stretch of a drawn line, in px from the notes line's start. */
78
+ export interface StaffSpan {
79
+ line: number;
80
+ left: number;
81
+ right: number;
82
+ color: StaffColor | undefined;
83
+ /** Thickness multiplier (1 = the font's line) */
84
+ weight: number;
85
+ }
86
+ /**
87
+ * The drawn line stretches of one notes line: `text` as the notes line holds
88
+ * it (clef prefix and notes), plus the break marker `*` when it stands
89
+ * `breakMarkerLeftPx` past the text. Each line index in `range` is one span
90
+ * per run of glyphs with the same color and weight, which change at an
91
+ * inline clef.
92
+ */
93
+ export declare function staffSpans(text: string, notesPx: number, range: StaffLineRange, options?: DrawnStaffOptions, breakMarkerLeftPx?: number): StaffSpan[];
94
+ /**
95
+ * The drawn staff of one notes line: a zero-size anchor on the baseline at
96
+ * the line's start, holding one absolutely placed span per stretch. Heights
97
+ * and offsets are in em of the notes font, so the lines sit right without
98
+ * measuring; `snapStaff` then aligns them to device pixels. A weighted line
99
+ * grows from the font line's centre. The spans sit at `z-index: -1`, so the
100
+ * notes paint over them once the notes line is its own stacking context
101
+ * (`isolation: isolate`, which GuidoRender sets).
102
+ */
103
+ export declare function staffLayer(spans: readonly StaffSpan[]): HTMLSpanElement;
104
+ /**
105
+ * Aligns every drawn staff line under `root` to device pixels: each line's
106
+ * thickness is rounded to whole device pixels (at least one) and its edges
107
+ * land on pixel boundaries, so every line draws as one even, sharp stroke.
108
+ * Needs `root` in the document; call it again after the score moves by a
109
+ * fraction of a pixel (a render calls it, and so does the embed's resize
110
+ * re-render).
111
+ */
112
+ export declare function snapStaff(root: ParentNode): void;
113
+ /**
114
+ * A staff color written as text (data attributes, settings): one CSS color,
115
+ * or `light|dark`. Empty → undefined; an invalid color warns and gives
116
+ * undefined.
117
+ */
118
+ export declare function parseStaffColor(text: string | undefined, label?: string): StaffColor | undefined;
119
+ /** Colors by position as text: up to five colors (`light|dark` each),
120
+ * bottom line first, separated by `;` (an empty entry keeps the default). */
121
+ export declare function parseStaffLineColors(text: string | undefined): (StaffColor | undefined)[] | undefined;
122
+ /** Colors by pitch as text: `c: gold; f: #d40000|#ff6060`. */
123
+ export declare function parseStaffPitchColors(text: string | undefined): Partial<Record<PitchLetter, StaffColor>> | undefined;
124
+ /** A weight written as text: a positive number, else undefined (warns). */
125
+ export declare function parseStaffWeight(text: string | undefined, label?: string): number | undefined;
126
+ /** Weights by position as text: up to five numbers, bottom line first,
127
+ * separated by `;` (an empty entry keeps 1). */
128
+ export declare function parseStaffLineWeights(text: string | undefined): (number | undefined)[] | undefined;
129
+ /** The text form of a staff color (`light|dark`), the inverse of `parseStaffColor`. */
130
+ export declare function formatStaffColor(color: StaffColor | undefined): string;
@@ -1,6 +1,7 @@
1
1
  import { StaffFill } from './chantLayout';
2
2
  import { StyleSetName } from './guidoStyles';
3
3
  import { SpacerChar } from './wordExport';
4
+ import { StaffMode } from './drawnStaff';
4
5
  /** Versioned localStorage key; an unknown version is ignored wholesale. */
5
6
  export declare const EDITOR_STORAGE_KEY = "guidex.editor.v1";
6
7
  export declare const EDITOR_SCHEMA_VERSION = 1;
@@ -24,6 +25,11 @@ export declare const JUNCTION_DASHES_MIN = 1;
24
25
  export declare const JUNCTION_DASHES_MAX = 8;
25
26
  export declare const STAFF_FILL_SNAP_MIN = 0;
26
27
  export declare const STAFF_FILL_SNAP_MAX = 60;
28
+ export declare const STAFF_LINES_MIN = 1;
29
+ export declare const STAFF_LINES_MAX = 5;
30
+ /** The staff weight sliders' range (a multiple of the font's line). */
31
+ export declare const STAFF_WEIGHT_MIN = 0.5;
32
+ export declare const STAFF_WEIGHT_MAX = 4;
27
33
  export declare const TRANSPOSE_MIN = -6;
28
34
  export declare const TRANSPOSE_MAX = 6;
29
35
  /** The destination Word text size default (notes ride at twice it) and the
@@ -63,6 +69,25 @@ export interface EditorSettings {
63
69
  staffFill: StaffFill;
64
70
  /** With `longest`: the distance from the max width that snaps to it. */
65
71
  staffFillSnapPx: number;
72
+ /** Two-syllable recitations as plain notes (issue #21). */
73
+ twoSyllableRecitationsToPlain: boolean;
74
+ /** Three or more plain notes on a line as a recitation (issue #21). */
75
+ plainRunsToRecitation: boolean;
76
+ /** The drawn staff: mode, fewest lines and its colors as text
77
+ * (`light|dark` colors, `;`-separated lists — the embed's attribute syntax). */
78
+ staff: StaffMode;
79
+ staffLines: number;
80
+ staffColor: string;
81
+ staffLineColors: string;
82
+ staffPitchColors: string;
83
+ /** Line thickness multipliers: all lines, by position (`;` list), and
84
+ * the clef's own line. */
85
+ staffWeight: number;
86
+ staffLineWeights: string;
87
+ staffClefLineWeight: number;
88
+ /** The preview's drawn lines run to the screen's edges (a page
89
+ * setting: not part of a saved chant or a share link). */
90
+ staffToEdges: boolean;
66
91
  customColors: boolean;
67
92
  colorFg: string;
68
93
  colorAccent: string;
@@ -158,6 +183,16 @@ export interface ChantPrefs {
158
183
  junctionDashes: number;
159
184
  staffFill: StaffFill;
160
185
  staffFillSnapPx: number;
186
+ twoSyllableRecitationsToPlain: boolean;
187
+ plainRunsToRecitation: boolean;
188
+ staff: StaffMode;
189
+ staffLines: number;
190
+ staffColor: string;
191
+ staffLineColors: string;
192
+ staffPitchColors: string;
193
+ staffWeight: number;
194
+ staffLineWeights: string;
195
+ staffClefLineWeight: number;
161
196
  transpose: number;
162
197
  }
163
198
  export interface SavedChant {
@@ -1,5 +1,6 @@
1
1
  import { EmptySlots, StanzaStack, StanzaWarning } from '../stanzas';
2
2
  import { MarkWarning } from '../chantMarkup';
3
+ import { DrawnStaffOptions } from '../drawnStaff';
3
4
  import { SpanProblem } from '../textMarkup';
4
5
  import { StaffFill } from '../chantLayout';
5
6
  import { MarkDefinitions, StyleSetName } from '../guidoStyles';
@@ -11,7 +12,7 @@ export declare const version: string;
11
12
  * (`overflow-x: auto` to scroll, `hidden` to clip). */
12
13
  export type MaxWidth = number | 'auto';
13
14
  /** Site-wide defaults, settable through `GuidexEmbed.init`. */
14
- export interface EmbedOptions {
15
+ export interface EmbedOptions extends DrawnStaffOptions {
15
16
  /** Selector for target elements (default '.guidex-script, .guido-script') */
16
17
  selector?: string;
17
18
  maxWidth?: MaxWidth;
@@ -27,6 +28,14 @@ export interface EmbedOptions {
27
28
  /** With `staffFill: 'longest'`: the distance from the available width
28
29
  * within which every line runs to it instead (default 0) */
29
30
  staffFillSnapPx?: number;
31
+ /** Render a recitation that covers exactly 2 syllables on a line as
32
+ * plain notes of the same pitch (default true, issue #21;
33
+ * `data-two-syllable-recitations-to-plain`) */
34
+ twoSyllableRecitationsToPlain?: boolean;
35
+ /** Render 3 or more syllables on one plain note with a reciting glyph
36
+ * (`1`–`9`, `ö`, `ü`) on a line as a recitation (default false;
37
+ * `data-plain-runs-to-recitation`) */
38
+ plainRunsToRecitation?: boolean;
30
39
  transpose?: number;
31
40
  /** The stanza sung under the notes (1-based; 1 is the script's own
32
41
  * text, 2… its `(@stanza …)` statements or the `stanzas` option). */
@@ -1,4 +1,4 @@
1
- import { a as dispose, c as renderScore, i as scoreSvg, l as version, n as downloadScoreSvg, o as init, r as scorePngBlob, s as renderAll, t as downloadScorePng } from "../scoreImage-Dz3c55Zi.js";
1
+ import { a as dispose, c as renderScore, i as scoreSvg, l as version, n as downloadScoreSvg, o as init, r as scorePngBlob, s as renderAll, t as downloadScorePng } from "../scoreImage-DUxsPIm0.js";
2
2
  //#region src/embed/index.ts
3
3
  if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", () => init(), { once: true });
4
4
  else init();