vexflow 5.2.0 → 5.4.0

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.
Files changed (189) hide show
  1. package/README.md +2 -0
  2. package/build/cjs/vexflow-bravura.js +2 -2
  3. package/build/cjs/vexflow-bravura.js.map +1 -1
  4. package/build/cjs/vexflow-core.js +2 -2
  5. package/build/cjs/vexflow-core.js.map +1 -1
  6. package/build/cjs/vexflow-debug-with-tests.js +6502 -1708
  7. package/build/cjs/vexflow-debug-with-tests.js.map +1 -1
  8. package/build/cjs/vexflow-debug.js +5622 -1618
  9. package/build/cjs/vexflow-debug.js.map +1 -1
  10. package/build/cjs/vexflow.js +2 -2
  11. package/build/cjs/vexflow.js.map +1 -1
  12. package/build/esm/src/accidental.js +10 -3
  13. package/build/esm/src/alternatingtremolo.js +68 -0
  14. package/build/esm/src/annotation.js +19 -3
  15. package/build/esm/src/articulation.js +28 -6
  16. package/build/esm/src/beam.js +171 -28
  17. package/build/esm/src/bend.js +79 -23
  18. package/build/esm/src/clef.js +3 -0
  19. package/build/esm/src/continuouslayout.js +681 -0
  20. package/build/esm/src/continuousspan.js +159 -0
  21. package/build/esm/src/curve.js +48 -55
  22. package/build/esm/src/dot.js +13 -4
  23. package/build/esm/src/easyscore/composition.js +52 -2
  24. package/build/esm/src/easyscore/policies.js +39 -8
  25. package/build/esm/src/element.js +4 -0
  26. package/build/esm/src/engravinggeometry.js +157 -0
  27. package/build/esm/src/engravingprofile.js +44 -0
  28. package/build/esm/src/factory.js +31 -11
  29. package/build/esm/src/font.js +9 -1
  30. package/build/esm/src/formatter.js +9 -1
  31. package/build/esm/src/fretdiagram.js +77 -0
  32. package/build/esm/src/gracenote.js +43 -38
  33. package/build/esm/src/gracenotegroup.js +53 -56
  34. package/build/esm/src/guitargesture.js +33 -0
  35. package/build/esm/src/guitarmodifiers.js +26 -0
  36. package/build/esm/src/index.js +10 -0
  37. package/build/esm/src/instrumentprofile.js +123 -0
  38. package/build/esm/src/keysignature.js +24 -2
  39. package/build/esm/src/modifiercontext.js +11 -0
  40. package/build/esm/src/notationspelling.js +73 -0
  41. package/build/esm/src/note.js +3 -0
  42. package/build/esm/src/notehead.js +11 -6
  43. package/build/esm/src/ornament.js +43 -18
  44. package/build/esm/src/pagebreaks.js +58 -0
  45. package/build/esm/src/pedalmarking.js +39 -17
  46. package/build/esm/src/phraselayout.js +503 -0
  47. package/build/esm/src/phraseribbon.js +28 -0
  48. package/build/esm/src/proportionalformatter.js +54 -6
  49. package/build/esm/src/publication.js +402 -0
  50. package/build/esm/src/publicationview.js +114 -0
  51. package/build/esm/src/scorenavigation.js +172 -0
  52. package/build/esm/src/sheet.js +14 -2
  53. package/build/esm/src/stave.js +33 -16
  54. package/build/esm/src/stavebarline.js +5 -7
  55. package/build/esm/src/staveconnector.js +1 -0
  56. package/build/esm/src/stavehairpin.js +53 -27
  57. package/build/esm/src/stavenote.js +134 -116
  58. package/build/esm/src/stavetie.js +66 -9
  59. package/build/esm/src/stem.js +26 -11
  60. package/build/esm/src/strokes.js +4 -0
  61. package/build/esm/src/system.js +19 -4
  62. package/build/esm/src/systembreaks.js +42 -0
  63. package/build/esm/src/tabnote.js +6 -1
  64. package/build/esm/src/textbracket.js +24 -5
  65. package/build/esm/src/tickcontext.js +19 -0
  66. package/build/esm/src/timesignature.js +20 -6
  67. package/build/esm/src/tuplet.js +58 -17
  68. package/build/esm/src/version.js +3 -3
  69. package/build/esm/src/vexflow.js +20 -0
  70. package/build/esm/src/voice.js +7 -3
  71. package/build/esm/tests/bend_tests.js +14 -1
  72. package/build/esm/tests/curve_tests.js +14 -4
  73. package/build/esm/tests/demo_repertoire_tests.js +27 -0
  74. package/build/esm/tests/demos/drums.js +54 -0
  75. package/build/esm/tests/demos/electric.js +63 -0
  76. package/build/esm/tests/demos/greensleeves.js +90 -0
  77. package/build/esm/tests/demos/joy.js +61 -0
  78. package/build/esm/tests/demos/kesh.js +80 -0
  79. package/build/esm/tests/demos/prelude.js +59 -0
  80. package/build/esm/tests/demos/quartertones.js +50 -0
  81. package/build/esm/tests/demos/saints.js +65 -0
  82. package/build/esm/tests/engraving/continuous-studies.mjs +140 -0
  83. package/build/esm/tests/engraving/instrument-studies.mjs +273 -0
  84. package/build/esm/tests/engraving/phrase-studies.mjs +63 -0
  85. package/build/esm/tests/engraving/publication-studies.mjs +87 -0
  86. package/build/esm/tests/engraving/score-layout.mjs +75 -0
  87. package/build/esm/tests/engraving/score-persistence.mjs +262 -0
  88. package/build/esm/tests/engraving/specialist-studies.mjs +347 -0
  89. package/build/esm/tests/engraving/studies.mjs +367 -0
  90. package/build/esm/tests/formatter_tests.js +10 -1
  91. package/build/esm/tests/index.js +1 -0
  92. package/build/esm/tests/node/audit-dependencies-tests.mjs +42 -0
  93. package/build/esm/tests/node/continuous-score-tests.mjs +282 -0
  94. package/build/esm/tests/node/easyscore-tests.mjs +71 -0
  95. package/build/esm/tests/node/engraving-layout-tests.mjs +449 -0
  96. package/build/esm/tests/node/instrument-profile-tests.mjs +224 -0
  97. package/build/esm/tests/node/local-engraving-tests.mjs +128 -0
  98. package/build/esm/tests/node/phrase-layout-tests.mjs +281 -0
  99. package/build/esm/tests/node/proportional-spacing-tests.mjs +64 -0
  100. package/build/esm/tests/node/publication-tests.mjs +219 -0
  101. package/build/esm/tests/node/rendering-tests.mjs +6 -2
  102. package/build/esm/tests/threevoice_tests.js +11 -1
  103. package/build/esm/tests/vexflow_test_helpers.js +19 -10
  104. package/build/esm/tools/audit-dependencies.mjs +61 -0
  105. package/build/esm/tools/easyscore-structure.mjs +1 -1
  106. package/build/esm/tools/explorer/catalog/entries.mjs +2 -1
  107. package/build/esm/tools/explorer/catalog/expression.mjs +14 -9
  108. package/build/esm/tools/explorer/catalog/guitar.mjs +238 -0
  109. package/build/esm/tools/explorer/catalog/layout.mjs +8 -6
  110. package/build/esm/tools/explorer/catalog/notes.mjs +16 -14
  111. package/build/esm/tools/explorer/catalog/staves.mjs +12 -6
  112. package/build/esm/tools/explorer/catalog/strings.mjs +10 -7
  113. package/build/esm/tools/score-fixtures.mjs +23 -6
  114. package/build/types/src/accidental.d.ts +4 -0
  115. package/build/types/src/alternatingtremolo.d.ts +13 -0
  116. package/build/types/src/annotation.d.ts +9 -0
  117. package/build/types/src/articulation.d.ts +9 -1
  118. package/build/types/src/beam.d.ts +16 -0
  119. package/build/types/src/bend.d.ts +8 -0
  120. package/build/types/src/clef.d.ts +3 -0
  121. package/build/types/src/continuouslayout.d.ts +103 -0
  122. package/build/types/src/continuousspan.d.ts +60 -0
  123. package/build/types/src/curve.d.ts +20 -0
  124. package/build/types/src/dot.d.ts +5 -0
  125. package/build/types/src/easyscore/composition.d.ts +27 -0
  126. package/build/types/src/easyscore/policies.d.ts +1 -1
  127. package/build/types/src/element.d.ts +2 -0
  128. package/build/types/src/engravinggeometry.d.ts +31 -0
  129. package/build/types/src/engravingprofile.d.ts +20 -0
  130. package/build/types/src/factory.d.ts +6 -1
  131. package/build/types/src/formatter.d.ts +3 -3
  132. package/build/types/src/fretdiagram.d.ts +23 -0
  133. package/build/types/src/gracenote.d.ts +7 -0
  134. package/build/types/src/gracenotegroup.d.ts +7 -2
  135. package/build/types/src/guitargesture.d.ts +26 -0
  136. package/build/types/src/guitarmodifiers.d.ts +3 -0
  137. package/build/types/src/index.d.ts +12 -0
  138. package/build/types/src/instrumentprofile.d.ts +124 -0
  139. package/build/types/src/keysignature.d.ts +9 -0
  140. package/build/types/src/modifiercontext.d.ts +4 -0
  141. package/build/types/src/notationspelling.d.ts +25 -0
  142. package/build/types/src/note.d.ts +15 -0
  143. package/build/types/src/notehead.d.ts +5 -0
  144. package/build/types/src/ornament.d.ts +10 -1
  145. package/build/types/src/pagebreaks.d.ts +26 -0
  146. package/build/types/src/pedalmarking.d.ts +9 -0
  147. package/build/types/src/phraselayout.d.ts +87 -0
  148. package/build/types/src/phraseribbon.d.ts +7 -0
  149. package/build/types/src/proportionalformatter.d.ts +11 -2
  150. package/build/types/src/publication.d.ts +61 -0
  151. package/build/types/src/publicationview.d.ts +27 -0
  152. package/build/types/src/scorenavigation.d.ts +33 -0
  153. package/build/types/src/sheet.d.ts +5 -0
  154. package/build/types/src/stave.d.ts +13 -0
  155. package/build/types/src/stavehairpin.d.ts +18 -0
  156. package/build/types/src/stavenote.d.ts +20 -2
  157. package/build/types/src/stavetie.d.ts +9 -0
  158. package/build/types/src/stem.d.ts +10 -1
  159. package/build/types/src/system.d.ts +8 -1
  160. package/build/types/src/systembreaks.d.ts +9 -0
  161. package/build/types/src/textbracket.d.ts +7 -0
  162. package/build/types/src/tickcontext.d.ts +5 -0
  163. package/build/types/src/timesignature.d.ts +6 -0
  164. package/build/types/src/tuplet.d.ts +5 -48
  165. package/build/types/src/vexflow.d.ts +20 -0
  166. package/build/types/src/voice.d.ts +2 -0
  167. package/changelog/CHANGELOG.md +25 -0
  168. package/package.json +15 -3
  169. package/tests/all.html +277 -0
  170. package/tests/demo_petzold_tests.ts +435 -0
  171. package/tests/demos/drums.ts +55 -0
  172. package/tests/demos/drums.webp +0 -0
  173. package/tests/demos/electric.ts +70 -0
  174. package/tests/demos/electric.webp +0 -0
  175. package/tests/demos/greensleeves.ts +97 -0
  176. package/tests/demos/greensleeves.webp +0 -0
  177. package/tests/demos/joy.ts +65 -0
  178. package/tests/demos/joy.webp +0 -0
  179. package/tests/demos/kesh.ts +86 -0
  180. package/tests/demos/kesh.webp +0 -0
  181. package/tests/demos/prelude.ts +65 -0
  182. package/tests/demos/prelude.webp +0 -0
  183. package/tests/demos/quartertones.ts +51 -0
  184. package/tests/demos/quartertones.webp +0 -0
  185. package/tests/demos/saints.ts +70 -0
  186. package/tests/demos/saints.webp +0 -0
  187. package/tests/flow.html +550 -239
  188. package/tests/fonts.css +493 -0
  189. package/tests/minuet.webp +0 -0
@@ -0,0 +1,124 @@
1
+ import { Fraction } from './fraction';
2
+ import { GuitarStroke, TimedStringBend } from './guitargesture';
3
+ import { NotationIdentity } from './note';
4
+ import { StaveNoteStruct } from './stavenote';
5
+ import { TabNoteStruct } from './tabnote';
6
+ /** A written position uses VexFlow note lines (1 = bottom line, 5 = top on a five-line staff). */
7
+ export interface PercussionInstrument {
8
+ id: string;
9
+ label: string;
10
+ line: number;
11
+ head?: 'normal' | 'cross' | 'circle-cross' | 'triangle';
12
+ stem: 'up' | 'down';
13
+ }
14
+ /** A custom kit and its legend share the same named entries. No playback pitches are inferred. */
15
+ export declare class PercussionMap {
16
+ static readonly kit: readonly PercussionInstrument[];
17
+ readonly instruments: readonly PercussionInstrument[];
18
+ constructor(entries?: readonly PercussionInstrument[]);
19
+ /** The first instrument supplies the default stem. Callers can override it for another voice. */
20
+ note(ids: readonly string[], duration: string, stem?: 'up' | 'down'): StaveNoteStruct;
21
+ }
22
+ /** Paired notation uses written open-string pitches and fret numbers relative to the capo. */
23
+ export declare class FrettedInstrument {
24
+ readonly capo: number;
25
+ private readonly tuning;
26
+ constructor(tuning?: string, capo?: number);
27
+ /** Expand an ordered rasgueado into ordinary paired attacks. Offsets are exact whole-note fractions from its start. */
28
+ rasgueado(positions: readonly {
29
+ str: number;
30
+ fret: number;
31
+ }[], strokes: readonly (GuitarStroke & {
32
+ duration: string;
33
+ })[]): {
34
+ offset: Fraction;
35
+ note: {
36
+ notation: NotationIdentity[];
37
+ musicFont?: string;
38
+ engraving?: import("./engravingprofile").EngravingProfile;
39
+ stemDirection?: number;
40
+ autoStem?: boolean;
41
+ strokePx?: number;
42
+ octaveShift?: number;
43
+ clef?: string;
44
+ keys?: string[];
45
+ duration: string;
46
+ line?: number;
47
+ dots?: number;
48
+ type?: string;
49
+ alignCenter?: boolean;
50
+ durationOverride?: Fraction;
51
+ };
52
+ tab: {
53
+ notation: NotationIdentity[];
54
+ positions: import("./tabnote").TabNotePosition[];
55
+ musicFont?: string;
56
+ engraving?: import("./engravingprofile").EngravingProfile;
57
+ stemDirection?: number;
58
+ autoStem?: boolean;
59
+ strokePx?: number;
60
+ octaveShift?: number;
61
+ clef?: string;
62
+ keys?: string[];
63
+ duration: string;
64
+ line?: number;
65
+ dots?: number;
66
+ type?: string;
67
+ alignCenter?: boolean;
68
+ durationOverride?: Fraction;
69
+ };
70
+ }[];
71
+ /** Attach a bend envelope to one played string. Both views retain its semantics and TAB draws the contour. */
72
+ bentAttack(positions: readonly {
73
+ str: number;
74
+ fret: number;
75
+ }[], duration: string, spec: TimedStringBend): {
76
+ note: {
77
+ notation: NotationIdentity[];
78
+ musicFont?: string;
79
+ engraving?: import("./engravingprofile").EngravingProfile;
80
+ stemDirection?: number;
81
+ autoStem?: boolean;
82
+ strokePx?: number;
83
+ octaveShift?: number;
84
+ clef?: string;
85
+ keys?: string[];
86
+ duration: string;
87
+ line?: number;
88
+ dots?: number;
89
+ type?: string;
90
+ alignCenter?: boolean;
91
+ durationOverride?: Fraction;
92
+ };
93
+ tab: {
94
+ notation: NotationIdentity[];
95
+ positions: import("./tabnote").TabNotePosition[];
96
+ musicFont?: string;
97
+ engraving?: import("./engravingprofile").EngravingProfile;
98
+ stemDirection?: number;
99
+ autoStem?: boolean;
100
+ strokePx?: number;
101
+ octaveShift?: number;
102
+ clef?: string;
103
+ keys?: string[];
104
+ duration: string;
105
+ line?: number;
106
+ dots?: number;
107
+ type?: string;
108
+ alignCenter?: boolean;
109
+ durationOverride?: Fraction;
110
+ };
111
+ };
112
+ /** Build independent standard and tab descriptions for the same attack. */
113
+ attack(positions: readonly ({
114
+ str: number;
115
+ fret: number;
116
+ } | {
117
+ str: number;
118
+ fret: 'X';
119
+ displayKey: string;
120
+ })[], duration: string): {
121
+ note: StaveNoteStruct;
122
+ tab: TabNoteStruct;
123
+ };
124
+ }
@@ -3,6 +3,12 @@ import { Stave } from './stave';
3
3
  import { StaveModifier } from './stavemodifier';
4
4
  export declare class KeySignature extends StaveModifier {
5
5
  static get CATEGORY(): string;
6
+ /** Explicit positions are already in the target clef, from the top staff line down. */
7
+ private ordered?;
8
+ setOrdered(entries: readonly {
9
+ type: string;
10
+ line: number;
11
+ }[]): this;
6
12
  protected paddingForced: boolean;
7
13
  protected formatted?: boolean;
8
14
  protected clefOverride?: string;
@@ -49,5 +55,8 @@ export declare class KeySignature extends StaveModifier {
49
55
  * If no stave is set, a dummy stave is created.
50
56
  */
51
57
  format(): void;
58
+ private formattedStaveY?;
59
+ /** Refresh the accidental origins after moving a staff and return each positioned glyph. */
60
+ getInkParts(): BoundingBox[];
52
61
  draw(): void;
53
62
  }
@@ -45,6 +45,10 @@ export declare class ModifierContext {
45
45
  getRightShift(): number;
46
46
  /** Ties clear nearby modifiers, but must not start beyond a lyric's text box. */
47
47
  getRightShiftForTie(): number;
48
+ private measuredTopLines;
49
+ private measuredBottomLines;
50
+ /** Keep the line allowance for other marks when using actual annotation ink bounds. */
51
+ getUnmeasuredTextLines(above: boolean): number;
48
52
  getState(): ModifierContextState;
49
53
  getMetrics(): ModifierContextMetrics;
50
54
  preFormat(): void;
@@ -0,0 +1,25 @@
1
+ /** One printable segment. tieNext joins a pitched continuation across a requested boundary. */
2
+ export interface RhythmSegment {
3
+ start: number;
4
+ duration: string;
5
+ dots: number;
6
+ tieNext: boolean;
7
+ }
8
+ export declare class NotationSpelling {
9
+ /** Transpose by both chromatic semitones and diatonic steps, e.g. +2/+1 for B-flat clarinet. */
10
+ static transpose(key: string, semitones: number, steps: number): string;
11
+ /** Preserve the mode while spelling the transposed tonic. Reject unavailable standard signatures. */
12
+ static transposeKey(key: string, semitones: number, steps: number): string;
13
+ /** Spell on a 1/64-note grid. Cuts are absolute barlines or group boundaries supplied by the caller. */
14
+ static rhythm(start: number, length: number, cuts?: readonly number[], rest?: boolean): RhythmSegment[];
15
+ }
16
+ /** Accidental memory for a single staff and bar. A signature maps a letter to a written sign in every octave. */
17
+ export declare class WrittenAccidentalState {
18
+ private readonly seen;
19
+ private readonly signature;
20
+ constructor(signature?: Readonly<Record<string, string>>);
21
+ /** Start a new bar in the same signature. Construct a new state on a signature change. */
22
+ reset(): void;
23
+ /** Return the sign to print. Cautionaries print on request even when the sign is already in force. */
24
+ sign(key: string, sign: string, cautionary?: boolean): string | undefined;
25
+ }
@@ -1,6 +1,7 @@
1
1
  import { Beam } from './beam';
2
2
  import { BoundingBox } from './boundingbox';
3
3
  import { Fraction } from './fraction';
4
+ import { GuitarStroke, TimedStringBend } from './guitargesture';
4
5
  import { Modifier } from './modifier';
5
6
  import { RenderContext } from './rendercontext';
6
7
  import { Stave } from './stave';
@@ -51,7 +52,19 @@ export interface ParsedNote {
51
52
  dots: number;
52
53
  ticks: number;
53
54
  }
55
+ /** Stable score identities for instruments and playing instructions. Display positions can differ from pitches. */
56
+ export interface NotationIdentity {
57
+ kind: 'unpitched' | 'technique' | 'harmony' | 'tuning' | 'tremolo' | 'accidental';
58
+ id: string;
59
+ label: string;
60
+ /** Physical guitar actions survive reflow, navigation and publication metadata. */
61
+ stroke?: GuitarStroke;
62
+ bend?: TimedStringBend;
63
+ /** Head or string position in the source chord, counted from zero. */
64
+ index?: number;
65
+ }
54
66
  export interface NoteStruct {
67
+ notation?: readonly NotationIdentity[];
55
68
  /** Array of pitches, e.g: `['c/4', 'e/4', 'g/4']` */
56
69
  keys?: string[];
57
70
  /** The time length (e.g., `q` for quarter, `h` for half, `8` for eighth etc.). */
@@ -80,6 +93,8 @@ export declare abstract class Note extends Tickable {
80
93
  static plotMetrics(ctx: RenderContext, note: Tickable, yPos: number): void;
81
94
  protected static parseDuration(durationString?: string): NoteDuration | undefined;
82
95
  protected static parseNoteStruct(noteStruct: NoteStruct): ParsedNote | undefined;
96
+ /** Source identities survive native drawing, Canvas inspection and print export. */
97
+ readonly notation: readonly NotationIdentity[];
83
98
  glyphProps: GlyphProps;
84
99
  keys: string[];
85
100
  keyProps: KeyProps[];
@@ -8,6 +8,8 @@ export interface NoteHeadStruct extends NoteStruct {
8
8
  customGlyphCode?: string;
9
9
  stemDirection?: number;
10
10
  displaced?: boolean;
11
+ /** Column counted outward from the normal stem-side head. */
12
+ displacementColumn?: number;
11
13
  noteType?: string;
12
14
  x?: number;
13
15
  y?: number;
@@ -25,6 +27,7 @@ export declare class NoteHead extends Note {
25
27
  static get CATEGORY(): string;
26
28
  protected customGlyph: boolean;
27
29
  protected displaced: boolean;
30
+ private readonly displacementColumn;
28
31
  protected stemDirection: number;
29
32
  protected line: number;
30
33
  protected index?: number;
@@ -41,6 +44,8 @@ export declare class NoteHead extends Note {
41
44
  setLine(line: number): this;
42
45
  /** Get the canvas `x` coordinate position of the notehead. */
43
46
  getAbsoluteX(): number;
47
+ /** Offset shared by drawing, head geometry and ledger lines. */
48
+ getDisplacementX(): number;
44
49
  /** Set notehead to a provided `stave`. */
45
50
  setStave(stave: Stave): this;
46
51
  /** Pre-render formatting. */
@@ -1,3 +1,4 @@
1
+ import { BoundingBox } from './boundingbox';
1
2
  import { Element } from './element';
2
3
  import { Modifier } from './modifier';
3
4
  import { ModifierContextState } from './modifiercontext';
@@ -18,6 +19,8 @@ export declare class Ornament extends Modifier {
18
19
  protected ornamentAlignWithNoteHead: string[] | boolean;
19
20
  protected type: string;
20
21
  protected delayed: boolean;
22
+ /** Side spacing is recomputed per format and is independent of authored shifts. */
23
+ private sideOffset;
21
24
  protected adjustForStemDirection: boolean;
22
25
  renderOptions: {
23
26
  accidentalUpperPadding: number;
@@ -66,6 +69,12 @@ export declare class Ornament extends Modifier {
66
69
  setUpperAccidental(accid: string): this;
67
70
  /** Set the lower accidental for the ornament. */
68
71
  setLowerAccidental(accid: string): this;
69
- /** Render ornament in position next to note. */
72
+ private layoutShiftY;
73
+ /** Move the whole ornament and its auxiliary signs together. */
74
+ setLayoutShiftY(y: number): void;
75
+ /** Recompute delayed and auxiliary positions against the current tick contexts. */
76
+ private positionElements;
77
+ /** Include both auxiliary signs in the measured ornament. */
78
+ getBoundingBox(): BoundingBox;
70
79
  draw(): void;
71
80
  }
@@ -0,0 +1,26 @@
1
+ export interface PrintableSystem {
2
+ measures: number[];
3
+ height: number;
4
+ restAtEnd: boolean;
5
+ }
6
+ export interface PageConstraints {
7
+ firstHeight: number;
8
+ laterHeight: number;
9
+ gap: number;
10
+ maxExtraGap: number;
11
+ justifyLast: boolean;
12
+ part: boolean;
13
+ forceBefore: ReadonlySet<number>;
14
+ preferAfter: ReadonlySet<number>;
15
+ forbidAfter: ReadonlySet<number>;
16
+ }
17
+ /** System indices and offsets from the top of the page's music area. */
18
+ export interface PageBreak {
19
+ first: number;
20
+ end: number;
21
+ offsets: number[];
22
+ overflow: number;
23
+ forbiddenTurn: boolean;
24
+ }
25
+ /** Minimize forbidden turns, then pages, then turn difficulty and unused space. */
26
+ export declare function paginate(systems: PrintableSystem[], rules: PageConstraints): PageBreak[];
@@ -1,3 +1,4 @@
1
+ import { BoundingBox } from './boundingbox';
1
2
  import { Element } from './element';
2
3
  import { Stave } from './stave';
3
4
  import { StaveNote } from './stavenote';
@@ -52,6 +53,14 @@ export declare class PedalMarking extends Element {
52
53
  setCustomText(depress: string, release?: string): this;
53
54
  /** Set the staff line to render the markings on. */
54
55
  setLine(line: number): this;
56
+ /** Ordered press, change and release anchors. Repeated notes represent a pedal change. */
57
+ getNotes(): readonly StaveNote[];
58
+ private layoutBaseline?;
59
+ /** A single-stave phrase may supply the pedal baseline after arranging the surrounding lanes. */
60
+ setLayoutBaseline(y?: number): void;
61
+ private releaseX;
62
+ /** Enclose actual pedal text, changes, end hooks and bracket stroke. */
63
+ getBoundingBox(): BoundingBox;
55
64
  /** Compute a baseline below annotations in participating voices on this stave. */
56
65
  getYForStave(stave: Stave): number;
57
66
  /** Draw the bracket based pedal markings. */
@@ -0,0 +1,87 @@
1
+ import { Annotation } from './annotation';
2
+ import { Articulation } from './articulation';
3
+ import { BoundingBox } from './boundingbox';
4
+ import { Curve } from './curve';
5
+ import { Element } from './element';
6
+ import { Ornament } from './ornament';
7
+ import { PedalMarking } from './pedalmarking';
8
+ import { RenderContext } from './rendercontext';
9
+ import { Stave } from './stave';
10
+ import { StaveHairpin } from './stavehairpin';
11
+ import { StaveNote } from './stavenote';
12
+ import { StaveTie } from './stavetie';
13
+ import { TextBracket } from './textbracket';
14
+ import { Voice } from './voice';
15
+ /** A syllable owns one event. Hyphens lead to the next syllable; extenders end on a named event. */
16
+ export interface PhraseSyllable {
17
+ note: StaveNote;
18
+ text: string;
19
+ hyphenAfter?: boolean;
20
+ extendTo?: StaveNote;
21
+ }
22
+ export type PhraseMark = Annotation | StaveHairpin | PedalMarking | TextBracket;
23
+ export interface PhraseLaneOptions {
24
+ side?: 'above' | 'below';
25
+ /** Pin the common baseline in staff spaces from the top line, positive downward. */
26
+ baselineSpaces?: number;
27
+ }
28
+ export interface PhraseDiagnostic {
29
+ code: 'PinnedCollision' | 'UnresolvedCollision' | 'CrossingSpans' | 'UnsupportedGeometry' | 'UnsupportedScript' | 'InvalidAnchor' | 'IterationLimit' | 'InsufficientLyricSpace';
30
+ sources: string[];
31
+ }
32
+ type Route = Curve | StaveTie;
33
+ type LocalMark = Articulation | Ornament;
34
+ /** Opt-in system-local layout. Register native spans and outside marks before formatting. */
35
+ export declare class PhraseLayout {
36
+ readonly diagnostics: PhraseDiagnostic[];
37
+ private lanes;
38
+ private routes;
39
+ private fixed;
40
+ private pins;
41
+ private managed;
42
+ private restLines;
43
+ private obstacles;
44
+ private connectors;
45
+ private messages;
46
+ private iterationLimit;
47
+ private lockedStaves;
48
+ bounds?: BoundingBox;
49
+ passes: number;
50
+ /** Include a native span or additional positioned obstacle, e.g. a tuplet on a second voice. */
51
+ addObstacle(stave: Stave, owner: Element): this;
52
+ /** Keep authored rest lines, mark placement or curve controls. Report any unresolved collision. */
53
+ pin(owner: LocalMark | StaveNote | Route): this;
54
+ /** Preserve the configured distance above this stave. */
55
+ lockStaffGap(stave: Stave): this;
56
+ /** Bound the number of staff-spacing and cross-staff beam refits. */
57
+ setPassLimit(limit: number): this;
58
+ /** Fit ties before slurs. Explicit control points remain authoritative. */
59
+ route(span: Route): this;
60
+ /** One lane aligns dynamics with wedges, or places a pedal or ottava outside earlier lanes. */
61
+ addLane(stave: Stave, marks: PhraseMark[], options?: PhraseLaneOptions): this;
62
+ /** Each whole syllable uses native text shaping and participates in ModifierContext horizontal spacing. */
63
+ addVerse(stave: Stave, syllables: PhraseSyllable[], options?: PhraseLaneOptions): Annotation[];
64
+ /** Restore derived rest positions before native formatting; preserve subsequent authored edits. */
65
+ resetPlacement(): void;
66
+ private report;
67
+ private addParts;
68
+ private measure;
69
+ /** Collect native ink once per owner. Bare staff lines constrain outside lanes but permit notes and curves. */
70
+ private collect;
71
+ private hits;
72
+ private placeRest;
73
+ private placeAttachment;
74
+ /** Inner spans reserve their ribbons first. Ties use modest quadratic lifts, slurs a wider cubic search. */
75
+ private placeRoutes;
76
+ /** Reject detached, reversed and foreign anchors before asking a mark for drawing coordinates. */
77
+ private validLane;
78
+ private lyricLines;
79
+ private placeLane;
80
+ /** Refit from the native staff positions on every format, never from the previous solution. */
81
+ format(staves: Stave[], voices: Voice[]): void;
82
+ /** Staff-space placement in renderer coordinates. The result is a snapshot after format. */
83
+ getLyricConnectors(): BoundingBox[];
84
+ /** Draw only lyric connectors; notes and registered marks retain their native rendering ownership. */
85
+ draw(context: RenderContext): void;
86
+ }
87
+ export {};
@@ -0,0 +1,7 @@
1
+ import { BoundingBox } from './boundingbox';
2
+ export interface RibbonPoint {
3
+ x: number;
4
+ y: number;
5
+ }
6
+ /** Both boundaries run from the first attachment to the last. Never sample past a thin obstacle. */
7
+ export declare function ribbonParts(upper: RibbonPoint[], lower: RibbonPoint[], padding?: number): BoundingBox[];
@@ -6,6 +6,10 @@ export interface ProportionalSpacing {
6
6
  /** Omit to fit the available width, or choose the minimum scale when no width is supplied. */
7
7
  pixelsPerQuarter?: number;
8
8
  }
9
+ /** Optical spacing reserves measured ink first and distributes spare width by square-root duration. */
10
+ export type MeasuredSpacing = ProportionalSpacing | {
11
+ mode: 'optical';
12
+ };
9
13
  /** Build a common rational timeline without advancing time for clefs or barlines. */
10
14
  export declare class ProportionalFormatter {
11
15
  readonly contexts: AlignmentTickContexts;
@@ -23,8 +27,13 @@ export declare class ProportionalFormatter {
23
27
  private measure;
24
28
  /** Compute one scale and validate it before changing any anchor positions. */
25
29
  private dimensions;
30
+ /** Find the earliest legal anchor at each onset. A wide mark still occupies
31
+ * its stave while other staves advance. Extra width can only enlarge gaps. */
32
+ private opticalLayout;
26
33
  /** Minimum total width for autoWidth, honoring a supplied exact scale. */
27
- minimumWidth(spacing: ProportionalSpacing): number;
34
+ minimumWidth(spacing: MeasuredSpacing): number;
35
+ /** Convert a single exact time scale into the same placement data as optical spacing. */
36
+ private proportionalLayout;
28
37
  /** Place anchors and prefixes, retaining the established centering exception for measure rests. */
29
- format(spacing: ProportionalSpacing, width: number): number;
38
+ format(spacing: MeasuredSpacing, width: number): number;
30
39
  }
@@ -0,0 +1,61 @@
1
+ import type { EasyScoreCompositionSpec } from './easyscore';
2
+ import { PublicationView } from './publicationview';
3
+ import type { SVGFont } from './svgexport';
4
+ export type { PublicationRegion, PublicationView } from './publicationview';
5
+ /** Paper, staff height (four spaces), margins, and inter-system gaps are measured in millimeters. */
6
+ export interface PublicationOptions extends PublicationView {
7
+ paper?: 'A4' | 'Letter' | {
8
+ width: number;
9
+ height: number;
10
+ };
11
+ staffSize?: number;
12
+ margins?: Partial<Record<'top' | 'right' | 'bottom' | 'left', number>>;
13
+ title?: string;
14
+ subtitle?: string;
15
+ header?: string;
16
+ footer?: string;
17
+ pageNumbers?: boolean;
18
+ systemGap?: number;
19
+ maxExtraGap?: number;
20
+ justifyLast?: boolean;
21
+ }
22
+ export interface PublicationDiagnostic {
23
+ code: 'PageOverflow' | 'SystemOverflow' | 'TextOverflow' | 'ForbiddenTurn' | 'ExcludedAnchor' | 'Engraving';
24
+ measures: number[];
25
+ detail: string;
26
+ page?: number;
27
+ }
28
+ export interface PublicationPage {
29
+ svg: SVGSVGElement;
30
+ number: number;
31
+ systems: {
32
+ measures: number[];
33
+ x: number;
34
+ y: number;
35
+ width: number;
36
+ height: number;
37
+ }[];
38
+ }
39
+ /** Public result uses the same SVGs for display, serialization and browser print/PDF. */
40
+ export declare class PublicationResult {
41
+ readonly pages: PublicationPage[];
42
+ readonly diagnostics: PublicationDiagnostic[];
43
+ readonly paper: {
44
+ width: number;
45
+ height: number;
46
+ };
47
+ constructor(pages: PublicationPage[], diagnostics: PublicationDiagnostic[], paper: {
48
+ width: number;
49
+ height: number;
50
+ });
51
+ /** Supply outline fonts for a portable standalone SVG, with per-page semantic metadata retained. */
52
+ toSVG(pageNumber: number, fonts?: SVGFont[]): string;
53
+ /** A separate print document avoids inheriting the application's styles and external font dependencies. */
54
+ toPrintHTML(fonts: SVGFont[]): string;
55
+ }
56
+ /** Attach one physical SVG per page. Render again with different options to build an independent part. */
57
+ export declare class Publication {
58
+ private readonly source;
59
+ constructor(source: EasyScoreCompositionSpec);
60
+ render(target: HTMLElement, options?: PublicationOptions): PublicationResult;
61
+ }
@@ -0,0 +1,27 @@
1
+ import type { EasyScoreComposition, EasyScoreCompositionSpec, EasyScoreStaveSpec } from './easyscore';
2
+ /** A small written-pitch reference staff over one source measure. Cues do not change the player's rest. */
3
+ export interface PublicationRegion {
4
+ kind: 'cue' | 'ossia';
5
+ staff: string;
6
+ measure: number;
7
+ label: string;
8
+ scale?: number;
9
+ }
10
+ /** All measure references are one-based. A page turn follows its named measure. */
11
+ export interface PublicationView {
12
+ staves?: readonly string[];
13
+ systemBreaks?: readonly number[];
14
+ pageBreaks?: readonly number[];
15
+ preferredTurns?: readonly number[];
16
+ forbiddenTurns?: readonly number[];
17
+ regions?: readonly PublicationRegion[];
18
+ }
19
+ export declare function invalidPage(message: string): never;
20
+ /** Validate view references before a new rendering replaces an existing one. */
21
+ export declare function checkView(source: EasyScoreCompositionSpec, view: PublicationView): void;
22
+ /** Track only declared IDs for relationships. The score's native lookup also handles IDs in EasyScore strings. */
23
+ export declare function projectScore(source: EasyScoreCompositionSpec, view: PublicationView, width: number, reference?: EasyScoreComposition, omitted?: (id: string, measures: number[]) => void): EasyScoreCompositionSpec;
24
+ /** Carry written clef, key and meter into a one-measure inset, including preceding inline changes. */
25
+ export declare function insetStaff(staff: EasyScoreStaveSpec, measure: number): EasyScoreStaveSpec;
26
+ /** Conservative playable turn: every timed event in every performing voice is a rest in the preceding measure. */
27
+ export declare function restingMeasure(score: EasyScoreComposition, number: number): boolean;
@@ -0,0 +1,33 @@
1
+ import { Bounds } from './boundingbox';
2
+ import type { EasyScoreComposition, EasyScoreStaveSpec } from './easyscore/composition';
3
+ import { GeometryDiagnostic } from './engravinggeometry';
4
+ /** Rational times are in whole notes. Measure and voice numbers start at one. */
5
+ export interface ScoreReadingEvent {
6
+ id: string;
7
+ source?: string;
8
+ staff: string;
9
+ measure: number;
10
+ voice: number;
11
+ onset: string;
12
+ duration: string;
13
+ label: string;
14
+ }
15
+ /** Layout coordinates belong to one snapshot. A wrapped relationship can have several regions. */
16
+ export interface ScoreHitRegion extends Bounds {
17
+ id: string;
18
+ kind: 'event' | 'span';
19
+ source?: string;
20
+ /** Targeted strings for a technique span. */
21
+ strings?: readonly number[];
22
+ /** Row index of a continuous span fragment, counted from zero. */
23
+ row?: number;
24
+ }
25
+ /** Build after layout; rebuild after reflow and retain selection by authored ID across snapshots. */
26
+ export declare class ScoreNavigation {
27
+ readonly events: readonly ScoreReadingEvent[];
28
+ readonly regions: readonly ScoreHitRegion[];
29
+ readonly diagnostics: readonly GeometryDiagnostic[];
30
+ constructor(score: EasyScoreComposition, staves: readonly Pick<EasyScoreStaveSpec, 'id' | 'name'>[], sources?: Readonly<Record<string, string>>);
31
+ /** Points use score coordinates. Event targets precede spanners; prefer the smallest overlapping target. */
32
+ hitTest(x: number, y: number): ScoreHitRegion | undefined;
33
+ }
@@ -1,3 +1,4 @@
1
+ import type { ContinuousLayout } from './continuouslayout';
1
2
  import { Factory } from './factory';
2
3
  import { System, SystemOptions } from './system';
3
4
  /** Dimensions are in rendering units (normally pixels). */
@@ -23,6 +24,10 @@ export interface SheetRow {
23
24
  /** Arrange measure-sized Systems left to right, wrapping at a requested width. */
24
25
  export declare class Sheet {
25
26
  private options;
27
+ private continuous?;
28
+ /** Composition installs a score-aware layout while retaining the native sheet resize and draw API. */
29
+ setContinuousLayout(layout: ContinuousLayout): this;
30
+ getContinuousLayout(): ContinuousLayout | undefined;
26
31
  private systems;
27
32
  private rows;
28
33
  constructor(options: SheetOptions);
@@ -9,6 +9,11 @@ export interface StaveLineConfig {
9
9
  export interface StaveOptions {
10
10
  /** Musical state when a repeated clef glyph is intentionally omitted. */
11
11
  clef?: string;
12
+ /** Optional barline endpoints, in staff spaces down from the top line. */
13
+ barlineSpan?: {
14
+ top: number;
15
+ bottom: number;
16
+ } | null;
12
17
  bottomTextPosition?: number;
13
18
  lineConfig?: StaveLineConfig[];
14
19
  spaceBelowStaffLn?: number;
@@ -28,6 +33,9 @@ export declare class Stave extends Element {
28
33
  protected clef: string;
29
34
  protected endClef?: string;
30
35
  protected formatted: boolean;
36
+ private boundaryModifiers;
37
+ /** Replace only the derived row-start and courtesy signs on a responsive sheet. */
38
+ setBoundaryModifiers(modifiers: StaveModifier[]): void;
31
39
  protected measure: number;
32
40
  protected bounds: Bounds;
33
41
  protected readonly modifiers: StaveModifier[];
@@ -48,6 +56,11 @@ export declare class Stave extends Element {
48
56
  getTieEndX(): number;
49
57
  getNumLines(): number;
50
58
  setNumLines(n: number): this;
59
+ /** Written extent of barlines, including shortened bars on a one-line percussion stave. */
60
+ getBarlineBounds(): {
61
+ topY: number;
62
+ botY: number;
63
+ };
51
64
  getTopLineTopY(): number;
52
65
  getBottomLineBottomY(): number;
53
66
  setX(x: number): this;
@@ -1,3 +1,4 @@
1
+ import { BoundingBox } from './boundingbox';
1
2
  import { Element } from './element';
2
3
  import { Note } from './note';
3
4
  import { RenderContext } from './rendercontext';
@@ -45,6 +46,23 @@ export declare class StaveHairpin extends Element {
45
46
  * @param {!Object} notes The start and end notes.
46
47
  */
47
48
  setNotes(notes: Record<string, Note>): this;
49
+ /** Both endpoints are required for a complete wedge on a single system. */
50
+ getNotes(): readonly (Note | undefined)[];
51
+ private layoutBaseline?;
52
+ private layoutLeft;
53
+ private layoutRight;
54
+ /** A phrase baseline passes through the middle of the wedge; trims clear adjacent dynamics. */
55
+ setLayoutBaseline(y?: number, left?: number, right?: number): void;
56
+ private parameters;
57
+ private edges;
58
+ /** Signed endpoint order is available to diagnose a wedge squeezed between two dynamics. */
59
+ getLayoutEdges(): {
60
+ top: number;
61
+ left: number;
62
+ right: number;
63
+ height: number;
64
+ };
65
+ getBoundingBox(): BoundingBox;
48
66
  renderHairpin(params: {
49
67
  firstX: number;
50
68
  lastX: number;