vexflow 5.1.2 → 5.2.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 (89) hide show
  1. package/README.md +7 -6
  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 +2633 -415
  7. package/build/cjs/vexflow-debug-with-tests.js.map +1 -1
  8. package/build/cjs/vexflow-debug.js +2478 -382
  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 +3 -0
  13. package/build/esm/src/articulation.js +27 -14
  14. package/build/esm/src/beam.js +12 -2
  15. package/build/esm/src/clef.js +3 -0
  16. package/build/esm/src/clefnote.js +5 -1
  17. package/build/esm/src/dot.js +1 -1
  18. package/build/esm/src/easyscore/composition.js +297 -0
  19. package/build/esm/src/easyscore/elementindex.js +81 -0
  20. package/build/esm/src/easyscore/elements.js +324 -0
  21. package/build/esm/src/easyscore/policies.js +69 -0
  22. package/build/esm/src/easyscore/rhythm.js +42 -0
  23. package/build/esm/src/easyscore.js +448 -26
  24. package/build/esm/src/element.js +13 -2
  25. package/build/esm/src/factory.js +256 -60
  26. package/build/esm/src/formatter.js +32 -4
  27. package/build/esm/src/keysignature.js +9 -1
  28. package/build/esm/src/keysignote.js +2 -2
  29. package/build/esm/src/note.js +5 -0
  30. package/build/esm/src/parenthesis.js +1 -1
  31. package/build/esm/src/parser.js +6 -1
  32. package/build/esm/src/proportionalformatter.js +186 -0
  33. package/build/esm/src/registry.js +27 -0
  34. package/build/esm/src/sheet.js +20 -3
  35. package/build/esm/src/stave.js +9 -2
  36. package/build/esm/src/stavenote.js +12 -12
  37. package/build/esm/src/stemmablenote.js +6 -1
  38. package/build/esm/src/tickable.js +5 -0
  39. package/build/esm/src/tuplet.js +3 -2
  40. package/build/esm/src/version.js +3 -3
  41. package/build/esm/src/vexflow.js +2 -1
  42. package/build/esm/tests/beam_tests.js +35 -0
  43. package/build/esm/tests/easyscore_tests.js +40 -0
  44. package/build/esm/tests/easyscore_types.js +65 -0
  45. package/build/esm/tests/formatter_tests.js +41 -0
  46. package/build/esm/tests/node/easyscore-rendering-tests.mjs +332 -0
  47. package/build/esm/tests/node/easyscore-tests.mjs +953 -0
  48. package/build/esm/tests/node/proportional-spacing-tests.mjs +214 -0
  49. package/build/esm/tools/easyscore-api-audit.mjs +58 -0
  50. package/build/esm/tools/easyscore-composition.mjs +62 -0
  51. package/build/esm/tools/easyscore-example.mjs +16 -0
  52. package/build/esm/tools/easyscore-families.mjs +61 -0
  53. package/build/esm/tools/easyscore-references-example.mjs +26 -0
  54. package/build/esm/tools/easyscore-rhythm.mjs +58 -0
  55. package/build/esm/tools/easyscore-structure.mjs +88 -0
  56. package/build/esm/tools/explorer/catalog/entries.mjs +6 -0
  57. package/build/esm/tools/explorer/catalog/expression.mjs +68 -0
  58. package/build/esm/tools/explorer/catalog/helpers.mjs +29 -0
  59. package/build/esm/tools/explorer/catalog/layout.mjs +109 -0
  60. package/build/esm/tools/explorer/catalog/notes.mjs +61 -0
  61. package/build/esm/tools/explorer/catalog/staves.mjs +85 -0
  62. package/build/esm/tools/explorer/catalog/strings.mjs +25 -0
  63. package/build/esm/tools/explorer/catalog.mjs +14 -0
  64. package/build/types/src/accidental.d.ts +2 -0
  65. package/build/types/src/articulation.d.ts +6 -0
  66. package/build/types/src/beam.d.ts +2 -0
  67. package/build/types/src/clef.d.ts +2 -0
  68. package/build/types/src/easyscore/composition.d.ts +107 -0
  69. package/build/types/src/easyscore/elementindex.d.ts +30 -0
  70. package/build/types/src/easyscore/elements.d.ts +156 -0
  71. package/build/types/src/easyscore/policies.d.ts +12 -0
  72. package/build/types/src/easyscore/rhythm.d.ts +9 -0
  73. package/build/types/src/easyscore.d.ts +153 -11
  74. package/build/types/src/element.d.ts +5 -1
  75. package/build/types/src/factory.d.ts +91 -8
  76. package/build/types/src/formatter.d.ts +7 -1
  77. package/build/types/src/keysignature.d.ts +3 -0
  78. package/build/types/src/keysignote.d.ts +1 -1
  79. package/build/types/src/note.d.ts +2 -0
  80. package/build/types/src/parser.d.ts +5 -0
  81. package/build/types/src/proportionalformatter.d.ts +30 -0
  82. package/build/types/src/registry.d.ts +4 -0
  83. package/build/types/src/stave.d.ts +2 -0
  84. package/build/types/src/stavenote.d.ts +1 -1
  85. package/build/types/src/stemmablenote.d.ts +6 -1
  86. package/build/types/src/tickable.d.ts +2 -0
  87. package/build/types/src/vexflow.d.ts +2 -1
  88. package/changelog/CHANGELOG.md +35 -0
  89. package/package.json +7 -2
@@ -0,0 +1,156 @@
1
+ import { Articulation } from '../articulation';
2
+ import type { Element } from '../element';
3
+ import type { Factory } from '../factory';
4
+ import { Note } from '../note';
5
+ import { StaveNote, StaveNoteStruct } from '../stavenote';
6
+ import { StemmableNote } from '../stemmablenote';
7
+ import { TabNote, TabNoteStruct } from '../tabnote';
8
+ import type { TupletOptions } from '../tuplet';
9
+ /** Tab relationships narrow native note endpoints while preserving partial spans and chord indexes. */
10
+ export interface EasyScoreTabSpan extends Omit<Parameters<Factory['TabTie']>[0], 'firstNote' | 'lastNote'> {
11
+ firstNote?: TabNote | null;
12
+ lastNote?: TabNote | null;
13
+ }
14
+ /** Internal bridge avoids a runtime import cycle back to the facade. */
15
+ export interface EasyScoreElementHost {
16
+ factory: () => Factory;
17
+ manage: <T extends Element>(construct: () => T) => T;
18
+ owned: (element: Element) => void;
19
+ checkIndex: (note: Note, index: number) => void;
20
+ noteDefaults: () => Partial<StaveNoteStruct>;
21
+ beamStems: (notes: StemmableNote[]) => boolean;
22
+ }
23
+ /** Explicit methods keep native constructor signatures visible in editor completion. */
24
+ export declare class EasyScoreElements {
25
+ private host;
26
+ constructor(host: EasyScoreElementHost);
27
+ private get factory();
28
+ /** Construct a native Stave; attach staff modifiers with attachToStave(). */
29
+ stave(...args: Parameters<Factory['Stave']>): import("..").Stave;
30
+ /** Construct a native TabStave; attach staff modifiers with attachToStave(). */
31
+ tabStave(...args: Parameters<Factory['TabStave']>): import("..").TabStave;
32
+ /** Construct a native GlyphNote; attach staff modifiers with attachToStave(). */
33
+ glyphNote(...args: Parameters<Factory['GlyphNote']>): import("..").GlyphNote;
34
+ /** Construct a native RepeatNote; attach staff modifiers with attachToStave(). */
35
+ repeatNote(...args: Parameters<Factory['RepeatNote']>): import("..").RepeatNote;
36
+ /** Construct a native BarNote; attach staff modifiers with attachToStave(). */
37
+ barNote(...args: Parameters<Factory['BarNote']>): import("..").BarNote;
38
+ /** Construct a native ClefNote; attach staff modifiers with attachToStave(). */
39
+ clefNote(...args: Parameters<Factory['ClefNote']>): import("..").ClefNote;
40
+ /** Construct a native KeySigNote; attach staff modifiers with attachToStave(). */
41
+ keySigNote(...args: Parameters<Factory['KeySigNote']>): import("..").KeySigNote;
42
+ /** Construct a native TimeSigNote; attach staff modifiers with attachToStave(). */
43
+ timeSigNote(...args: Parameters<Factory['TimeSigNote']>): import("..").TimeSigNote;
44
+ /** Construct a native Clef; attach staff modifiers with attachToStave(). */
45
+ clef(...args: Parameters<Factory['Clef']>): import("..").Clef;
46
+ /** Construct a native KeySignature; attach staff modifiers with attachToStave(). */
47
+ keySignature(...args: Parameters<Factory['KeySignature']>): import("..").KeySignature;
48
+ /** Construct a native TimeSignature; attach staff modifiers with attachToStave(). */
49
+ timeSignature(...args: Parameters<Factory['TimeSignature']>): import("..").TimeSignature;
50
+ /** Construct a native Barline; attach staff modifiers with attachToStave(). */
51
+ barline(...args: Parameters<Factory['Barline']>): import("..").Barline;
52
+ /** Construct a native Repetition; attach staff modifiers with attachToStave(). */
53
+ repetition(...args: Parameters<Factory['Repetition']>): import("..").Repetition;
54
+ /** Construct a native Volta; attach staff modifiers with attachToStave(). */
55
+ volta(...args: Parameters<Factory['Volta']>): import("..").Volta;
56
+ /** Construct a native StaveSection; attach staff modifiers with attachToStave(). */
57
+ section(...args: Parameters<Factory['StaveSection']>): import("..").StaveSection;
58
+ /** Construct a native StaveTempo; attach staff modifiers with attachToStave(). */
59
+ tempo(...args: Parameters<Factory['StaveTempo']>): import("..").StaveTempo;
60
+ /** Construct a native StaveText; attach staff modifiers with attachToStave(). */
61
+ staveText(...args: Parameters<Factory['StaveText']>): import("..").StaveText;
62
+ /** Preserve native fret text and arbitrary string counts; reject invalid positions early. */
63
+ private tabPositions;
64
+ /** Construct tablature with all native note fields. */
65
+ tabNote(options: TabNoteStruct, drawStem?: boolean): TabNote;
66
+ /** Grace tablature shares the same group ownership as pitched grace notes. */
67
+ graceTabNote(options: TabNoteStruct): import("..").GraceTabNote;
68
+ /** Preserve the complete native bend phrase, including custom widths. */
69
+ bend(...args: Parameters<Factory['Bend']>): import("..").Bend;
70
+ /** Validate tab endpoint types and head indexes before native span construction. */
71
+ private tabEndpoints;
72
+ /** Tab ties support native hammer-on/pull-off text and explicit partial endpoints. */
73
+ tabTie(...args: [notes: EasyScoreTabSpan, text?: string]): import("..").TabTie;
74
+ /** A partial slide needs an explicit direction; there are not two frets to compare. */
75
+ tabSlide(...args: [notes: EasyScoreTabSpan, direction?: number]): import("..").TabSlide;
76
+ /** Connect owned staves without introducing another layout owner. */
77
+ connector(params: Parameters<Factory['StaveConnector']>[0]): import("..").StaveConnector;
78
+ /** Multi-measure rests are standalone drawables; set their stave explicitly. */
79
+ multiMeasureRest(params: Parameters<Factory['MultiMeasureRest']>[0]): import("..").MultiMeasureRest;
80
+ /** Typed notes inherit score clef/stem defaults; explicit native fields win. */
81
+ note(options: StaveNoteStruct): StaveNote;
82
+ /** Construct a native Annotation; its options and setters remain available. */
83
+ annotation(...args: Parameters<Factory['Annotation']>): import("..").Annotation;
84
+ /** Construct a native GhostNote; its options and setters remain available. */
85
+ ghostNote(...args: Parameters<Factory['GhostNote']>): import("..").GhostNote;
86
+ /** Construct a native GraceNote; its options and setters remain available. */
87
+ graceNote(options: Parameters<Factory['GraceNote']>[0]): import("..").GraceNote;
88
+ /** Construct a native Accidental; its options and setters remain available. */
89
+ accidental(...args: Parameters<Factory['Accidental']>): import("..").Accidental;
90
+ /** Construct a native Articulation; its options and setters remain available. */
91
+ articulation(options?: Parameters<Factory['Articulation']>[0]): Articulation;
92
+ /** Construct a native Ornament; its options and setters remain available. */
93
+ ornament(...args: Parameters<Factory['Ornament']>): import("..").Ornament;
94
+ /** Construct a native Dot; its options and setters remain available. */
95
+ dot(...args: Parameters<Factory['Dot']>): import("..").Dot;
96
+ /** Construct a native Parenthesis; its options and setters remain available. */
97
+ parenthesis(...args: Parameters<Factory['Parenthesis']>): import("..").Parenthesis;
98
+ /** Construct a native Stroke; its options and setters remain available. */
99
+ stroke(...args: Parameters<Factory['Stroke']>): import("..").Stroke;
100
+ /** Construct a native Tremolo; its options and setters remain available. */
101
+ tremolo(...args: Parameters<Factory['Tremolo']>): import("..").Tremolo;
102
+ /** Construct a native Vibrato; its options and setters remain available. */
103
+ vibrato(...args: Parameters<Factory['Vibrato']>): import("..").Vibrato;
104
+ /** Construct a native ChordSymbol; its options and setters remain available. */
105
+ chordSymbol(...args: Parameters<Factory['ChordSymbol']>): import("..").ChordSymbol;
106
+ /** Construct a native TextNote; its options and setters remain available. */
107
+ textNote(...args: Parameters<Factory['TextNote']>): import("..").TextNote;
108
+ /** Construct a native Fingering; its options and setters remain available. */
109
+ fingering(...args: Parameters<Factory['Fingering']>): import("..").FretHandFinger;
110
+ /** Construct a native StringNumber; its options and setters remain available. */
111
+ stringNumber(...args: Parameters<Factory['StringNumber']>): import("..").StringNumber;
112
+ /** Grace children are owned by one modifier and are removed from the standalone draw queue. */
113
+ graceNoteGroup(options: Parameters<Factory['GraceNoteGroup']>[0]): import("..").GraceNoteGroup;
114
+ /** Group inline notation or other subnotes before inserting the parent into a voice. */
115
+ noteSubGroup(options: {
116
+ notes: Note[];
117
+ }): import("..").NoteSubGroup;
118
+ /** Ties validate ownership and chord-head indexes before construction. */
119
+ tie(options: Parameters<Factory['StaveTie']>[0]): import("..").StaveTie;
120
+ /** Validate complete or explicitly partial spans before native constructors run. */
121
+ private endpoints;
122
+ /** Return a beam handle while preserving EasyScore's automatic/explicit stem policy. */
123
+ beam(params: Parameters<Factory['Beam']>[0]): import("..").Beam;
124
+ /** Reject non-integer and out-of-range note indices before native mutation. */
125
+ private noteIndex;
126
+ /** Tuplets change rational timing before voice insertion. Nested tuplets retain native behavior. */
127
+ tuplet(params: {
128
+ notes: Note[];
129
+ options?: TupletOptions;
130
+ }): import("../tuplet").Tuplet;
131
+ /** Native curves support explicit partial spans at stave boundaries. */
132
+ curve(params: {
133
+ from?: Note;
134
+ to?: Note;
135
+ options?: Parameters<Factory['Curve']>[0]['options'];
136
+ }): import("..").Curve;
137
+ /** Hairpins require two endpoints; native render offsets remain editable. */
138
+ hairpin(params: Parameters<Factory['StaveHairpin']>[0]): import("..").StaveHairpin;
139
+ /** Lines require two staff-note endpoints and matched chord-head indexes. */
140
+ line(params: Parameters<Factory['StaveLine']>[0]): import("..").StaveLine;
141
+ /** Text brackets have two complete endpoints; use explicit segments at row breaks. */
142
+ textBracket(params: Parameters<Factory['TextBracket']>[0]): import("..").TextBracket;
143
+ /** Vibrato brackets accept native partial endpoints. */
144
+ vibratoBracket(params: Parameters<Factory['VibratoBracket']>[0]): import("..").VibratoBracket;
145
+ /** Pedal points are explicit ordered staff-note events, including repeated depress/release points. */
146
+ pedalMarking(params: {
147
+ notes: StaveNote[];
148
+ options?: {
149
+ style: 'text' | 'bracket' | 'mixed';
150
+ };
151
+ }): import("..").PedalMarking;
152
+ /** Timed dynamics retain all native text-note fields. */
153
+ textDynamics(params?: Parameters<Factory['TextDynamics']>[0]): import("..").TextDynamics;
154
+ /** Timed crescendo notes expose their native direction and height setters. */
155
+ crescendo(...args: Parameters<Factory['Crescendo']>): import("..").Crescendo;
156
+ }
@@ -0,0 +1,12 @@
1
+ import { Accidental } from '../accidental';
2
+ import type { EasyScore } from '../easyscore';
3
+ import { Fraction } from '../fraction';
4
+ import { Stave } from '../stave';
5
+ import { Voice } from '../voice';
6
+ /** Inline signature changes use exact tick onsets shared by all voices on a stave. */
7
+ export interface KeyChange {
8
+ at: Fraction;
9
+ key: string;
10
+ }
11
+ /** Each onset is evaluated against one prior state, so voice ordering cannot change accidental output. */
12
+ export declare function applyCompositionAccidentals(score: EasyScore, voices: Voice[], key: string, changes: KeyChange[], generated: Set<Accidental>, stave: Stave): void;
@@ -0,0 +1,9 @@
1
+ import { Beam } from '../beam';
2
+ import type { EasyScore } from '../easyscore';
3
+ import { StemmableNote } from '../stemmablenote';
4
+ /** Native grouping/render options, with the same stem override used by EasyScore.beam(). */
5
+ export type EasyScoreAutoBeamOptions = Omit<NonNullable<Parameters<typeof Beam.generateBeams>[1]>, 'stemPolicy'> & {
6
+ autoStem?: boolean;
7
+ };
8
+ /** Validate every setting before native grouping mutates existing notes or tuplets. */
9
+ export declare function autoBeam(score: EasyScore, notes: StemmableNote[], options: EasyScoreAutoBeamOptions): Beam[];
@@ -1,12 +1,29 @@
1
1
  import { Accidental } from './accidental';
2
2
  import { PartialBeamDirection } from './beam';
3
- import { Factory } from './factory';
3
+ import { EasyScoreComposition, EasyScoreCompositionSpec } from './easyscore/composition';
4
+ import { EasyScoreSource } from './easyscore/elementindex';
5
+ import { EasyScoreElements } from './easyscore/elements';
6
+ import { EasyScoreAutoBeamOptions } from './easyscore/rhythm';
7
+ import { Element, ElementStyle } from './element';
8
+ import { Factory, FactoryElementRole, FactoryOptions } from './factory';
9
+ import { Modifier } from './modifier';
4
10
  import { Note } from './note';
5
11
  import { Grammar, Match, Parser, Result, Rule, RuleFunction } from './parser';
6
12
  import { RenderContext } from './rendercontext';
13
+ import { Sheet, SheetOptions } from './sheet';
14
+ import { Stave } from './stave';
15
+ import { StaveModifier } from './stavemodifier';
16
+ import { StaveNoteStruct } from './stavenote';
7
17
  import { StemmableNote } from './stemmablenote';
18
+ import { System, SystemOptions } from './system';
19
+ import { Tickable } from './tickable';
8
20
  import { TupletOptions } from './tuplet';
9
- import { Voice } from './voice';
21
+ import { RuntimeError } from './util';
22
+ import { Voice, VoiceMode, VoiceTime } from './voice';
23
+ export type { EasyScoreComposition, EasyScoreCompositionDiagnostic, EasyScoreCompositionSpec, EasyScoreContent, EasyScoreMeasureSpec, EasyScoreSpanSpec, EasyScoreStaffState, EasyScoreStaveSpec, EasyScoreVoiceSpec, } from './easyscore/composition';
24
+ export type { EasyScoreSource } from './easyscore/elementindex';
25
+ export type { EasyScoreTabSpan } from './easyscore/elements';
26
+ export type { EasyScoreAutoBeamOptions } from './easyscore/rhythm';
10
27
  export type CommitHook = (obj: any, note: StemmableNote, builder: Builder) => void;
11
28
  export declare class EasyScoreGrammar implements Grammar {
12
29
  builder: Builder;
@@ -55,6 +72,8 @@ export interface NotePiece {
55
72
  octave?: string;
56
73
  }
57
74
  export declare class Piece {
75
+ /** Range of this piece in the most recently parsed input. */
76
+ source?: EasyScoreSourceSpan;
58
77
  chord: NotePiece[];
59
78
  duration: string;
60
79
  dots: number;
@@ -69,6 +88,16 @@ export interface BuilderElements {
69
88
  accidentals: (Accidental | undefined)[][];
70
89
  }
71
90
  export interface BuilderOptions extends Record<string, any> {
91
+ /** Native note options. String notation still supplies keys, duration, dots, and type. */
92
+ octaveShift?: StaveNoteStruct['octaveShift'];
93
+ strokePx?: StaveNoteStruct['strokePx'];
94
+ alignCenter?: StaveNoteStruct['alignCenter'];
95
+ line?: StaveNoteStruct['line'];
96
+ durationOverride?: StaveNoteStruct['durationOverride'];
97
+ id?: string;
98
+ class?: string;
99
+ articulations?: string;
100
+ fingerings?: string;
72
101
  stem?: string;
73
102
  clef?: string;
74
103
  /** Initial duration for notes that omit one. Defaults to an eighth note. */
@@ -80,8 +109,10 @@ export declare class Builder {
80
109
  options: BuilderOptions;
81
110
  piece: Piece;
82
111
  commitHooks: CommitHook[];
112
+ /** @internal EasyScore observes completed pieces after application hooks have run. */
113
+ onNote?: (note: StemmableNote, source?: EasyScoreSourceSpan) => void;
83
114
  rollingDuration: string;
84
- constructor(factory: Factory);
115
+ constructor(factory?: Factory);
85
116
  reset(options?: BuilderOptions): void;
86
117
  getFactory(): Factory;
87
118
  getElements(): BuilderElements;
@@ -94,17 +125,65 @@ export declare class Builder {
94
125
  addNote(key?: string, accid?: string | null, octave?: string): void;
95
126
  addSingleNote(key: string, accid?: string | null, octave?: string): void;
96
127
  addChord(notes: Match[]): void;
97
- commitPiece(): void;
128
+ commitPiece(source?: EasyScoreSourceSpan): void;
129
+ }
130
+ /** Zero-based, end-exclusive source range. */
131
+ export interface EasyScoreSourceSpan {
132
+ start: number;
133
+ end: number;
134
+ }
135
+ /** Editor-friendly error. Line and column are one-based. */
136
+ export interface EasyScoreDiagnostic extends EasyScoreSourceSpan {
137
+ code: string;
138
+ message: string;
139
+ line: number;
140
+ column: number;
141
+ measure?: number;
142
+ }
143
+ /** Parsed notation contains data only; no VexFlow elements or render context. */
144
+ export interface EasyScoreParsedPiece extends Piece {
145
+ source: EasyScoreSourceSpan;
146
+ }
147
+ export interface EasyScoreParseResult {
148
+ success: boolean;
149
+ pieces: EasyScoreParsedPiece[];
150
+ diagnostics: EasyScoreDiagnostic[];
151
+ }
152
+ /** The same diagnostics are available to callers that prefer exceptions. */
153
+ export declare class EasyScoreError extends RuntimeError {
154
+ readonly diagnostics: EasyScoreDiagnostic[];
155
+ constructor(diagnostics: EasyScoreDiagnostic[]);
156
+ }
157
+ /** Voice settings are applied before inserting notes, including strictness and resolution. */
158
+ export interface EasyScoreVoiceOptions {
159
+ time?: VoiceTime | string;
160
+ mode?: 'strict' | 'soft' | 'full' | VoiceMode;
161
+ softmaxFactor?: number;
162
+ /** Legacy spelling remains supported. */
163
+ options?: {
164
+ softmaxFactor: number;
165
+ };
166
+ }
167
+ /** Pure extension validation runs before any Factory construction or commit hook. */
168
+ export interface EasyScoreValidationContext {
169
+ piece: Readonly<EasyScoreParsedPiece>;
170
+ options: Readonly<BuilderOptions>;
98
171
  }
99
172
  export interface EasyScoreOptions {
100
173
  factory?: Factory;
101
174
  builder?: Builder;
102
175
  commitHooks?: CommitHook[];
103
176
  throwOnError?: boolean;
177
+ /** Reject unknown built-in options. Enabled by create(); legacy factories keep their extension behavior. */
178
+ strictOptions?: boolean;
179
+ /** Extra option names consumed by application commit hooks in strict mode. */
180
+ extensions?: readonly string[];
181
+ /** Throw to return a source diagnostic. Must not mutate input or application state. */
182
+ validate?: (context: EasyScoreValidationContext) => void;
104
183
  }
105
184
  export interface EasyScoreDefaults extends Record<string, any> {
106
185
  clef?: string;
107
- time?: string;
186
+ time?: VoiceTime | string;
108
187
  stem?: string;
109
188
  }
110
189
  /**
@@ -112,6 +191,54 @@ export interface EasyScoreDefaults extends Record<string, any> {
112
191
  */
113
192
  export declare class EasyScore {
114
193
  static DEBUG: boolean;
194
+ private references;
195
+ /** The complete measure input, when parse() is constructing a trimmed measure. */
196
+ private sourceContext?;
197
+ /** Inspect notation provenance without installing a global Registry. Useful for visual tooling. */
198
+ static getSource(element: Element): EasyScoreSource | undefined;
199
+ /** Look up a native object in this score. Missing IDs return undefined. */
200
+ getElement(id: string): Element | undefined;
201
+ /** Resolve a named note for typed relationship APIs. Missing IDs and non-notes throw. */
202
+ getNote(id: string): Note;
203
+ /** Return a defensive copy of a generated element's source, or undefined for native objects. */
204
+ getSource(element: Element): EasyScoreSource | undefined;
205
+ /** Explicitly join a native extension to this score's ownership and drawing lifecycle. */
206
+ adopt<T extends Element>(element: T, role: FactoryElementRole): T;
207
+ /** Stage local references together with Factory queues and ambient registry entries. */
208
+ private transaction;
209
+ /** Create a strict EasyScore facade with its own Factory. Load fonts before constructing notation. */
210
+ static create(options: FactoryOptions, scoreOptions?: Omit<EasyScoreOptions, 'factory' | 'builder'>): EasyScore;
211
+ /** Typed constructors return native objects and share the facade's transaction boundary. */
212
+ readonly make: EasyScoreElements;
213
+ /** Attach a modifier once. Native custom modifiers are welcome; foreign Factory objects are rejected. */
214
+ attach<T extends Note>(note: T, modifier: Modifier, index?: number): T;
215
+ /** Attach staff notation once; the stave owns its drawing lifecycle. */
216
+ attachToStave<T extends Stave>(stave: T, modifier: StaveModifier, position?: number): T;
217
+ /** Apply temporary defaults to synchronous managed construction; restore them on success or failure. */
218
+ withDefaults<T>(defaults: EasyScoreDefaults, construct: (score: EasyScore) => T & (T extends PromiseLike<unknown> ? never : unknown)): T;
219
+ /** Construct aligned measures and resolve forward references before layout or drawing. */
220
+ compose(spec: EasyScoreCompositionSpec): EasyScoreComposition;
221
+ /** Build a normal System; its staff API and formatter options stay available. */
222
+ system(options?: SystemOptions): System;
223
+ /** Create a native responsive Sheet. Its systems remain managed by this Factory. */
224
+ sheet(options?: Omit<SheetOptions, 'factory'>): Sheet;
225
+ /**
226
+ * Stage a group of synchronous construction calls. Failed groups release their new objects and IDs.
227
+ * Existing-object setters and application side effects remain the caller's responsibility.
228
+ */
229
+ build<T>(construct: (score: EasyScore) => T & (T extends PromiseLike<unknown> ? never : unknown)): T;
230
+ /** Apply the Factory foreground defaults without changing global metrics or fonts. */
231
+ setStyle(style: Pick<ElementStyle, 'fillStyle' | 'strokeStyle'>): this;
232
+ /** Delegate drawing and the existing opt-in retained lifecycle to Factory. */
233
+ draw(options?: {
234
+ retain?: boolean;
235
+ }): void;
236
+ /** Release queued notation and the builder's last result. */
237
+ reset(): this;
238
+ /** Endpoints and voice notes must share this facade's Factory. */
239
+ private requireOwned;
240
+ /** Reject invalid chord-head references before attaching or queuing notation. */
241
+ private checkIndex;
115
242
  defaults: EasyScoreDefaults;
116
243
  options: EasyScoreOptions;
117
244
  factory: Factory;
@@ -134,7 +261,18 @@ export declare class EasyScore {
134
261
  */
135
262
  setOptions(options: EasyScoreOptions): this;
136
263
  setContext(context: RenderContext): this;
264
+ /** Parse and validate without touching this builder, its hooks, Factory queues, or registries. */
265
+ parseNotation(line: string, options?: BuilderOptions): EasyScoreParseResult;
266
+ /** Validate built-in fields before allocating notes. Extension values are left to application hooks. */
267
+ private validatePiece;
268
+ /** Observe source ranges only during this parse, including legacy partial results. */
137
269
  parse(line: string, options?: BuilderOptions): Result;
270
+ /** Strict construction is transactional; the legacy non-throwing parser retains partial output. */
271
+ private parseInput;
272
+ /**
273
+ * Resolve automatic stems for the whole group while respecting explicit stems.
274
+ * autoStem: true overrides explicit directions; false preserves all directions.
275
+ */
138
276
  beam(notes: StemmableNote[], options?: {
139
277
  autoStem?: boolean;
140
278
  secondaryBeamBreaks?: number[];
@@ -142,19 +280,23 @@ export declare class EasyScore {
142
280
  [noteIndex: number]: PartialBeamDirection;
143
281
  };
144
282
  }): StemmableNote[];
283
+ /** Generate and own native beam groups without changing rhythmic duration. */
284
+ autoBeam(notes: StemmableNote[], options?: EasyScoreAutoBeamOptions): import("./beam").Beam[];
285
+ /** Explicit pitched stems constrain the group; conflicting explicit stems remain mixed. */
286
+ private resolveBeamStems;
145
287
  tuplet(notes: StemmableNote[], options?: TupletOptions): StemmableNote[];
146
288
  notes(line: string, options?: BuilderOptions): StemmableNote[];
289
+ /** Mix notation fragments, full native note structs, and already-owned native tickables. */
290
+ sequence(items: readonly (string | StaveNoteStruct | Tickable)[], options?: BuilderOptions): Tickable[];
147
291
  /**
148
292
  * Parse bar-separated measures. Durations carry across bars; notes() is unchanged.
149
293
  * A bar may have adjacent commas. Quoted option values may contain literal bars.
150
294
  * Empty measures and invalid notation throw, rather than returning partial music.
151
295
  */
152
296
  measures(line: string, options?: BuilderOptions): StemmableNote[][];
153
- voice(notes: Note[], options?: {
154
- time?: string;
155
- options?: {
156
- softmaxFactor: number;
157
- };
158
- }): Voice;
297
+ /** Split only unquoted bars and retain each trimmed measure's original source offset. */
298
+ private splitMeasures;
299
+ /** Configure time, mode, and spacing before inserting tickables. */
300
+ voice(notes: Tickable[], options?: EasyScoreVoiceOptions): Voice;
159
301
  addCommitHook(commitHook: CommitHook): void;
160
302
  }
@@ -84,6 +84,8 @@ export declare class Element {
84
84
  /** Distinguishes caller overrides from built-in metric colors. */
85
85
  protected styleExplicit: boolean;
86
86
  protected registry?: Registry;
87
+ /** Independent ID indexes can validate changes without replacing the default Registry. */
88
+ private idListeners?;
87
89
  protected _fontInfo: Required<FontInfo>;
88
90
  protected fontScale: number;
89
91
  protected _text: string;
@@ -150,7 +152,7 @@ export declare class Element {
150
152
  /** Remove a class label (An element can have multiple class labels). */
151
153
  removeClass(className: string): this;
152
154
  /** Call back from registry after the element is registered. */
153
- onRegister(registry: Registry): this;
155
+ onRegister(registry?: Registry): this;
154
156
  /** Return the rendered status. */
155
157
  isRendered(): boolean;
156
158
  /** Set the rendered status. */
@@ -161,6 +163,8 @@ export declare class Element {
161
163
  getAttribute(name: string): any;
162
164
  /** Return associated SVGElement. */
163
165
  getSVGElement(suffix?: string): SVGElement | undefined;
166
+ /** @internal Subscribe a local ID index. All validators run before an ID is changed. */
167
+ onIdChange(validate: (id: string | undefined) => void, changed: () => void): () => void;
164
168
  /** Set an attribute such as 'id', 'class', or 'type'. */
165
169
  setAttribute(name: string, value: string | undefined): this;
166
170
  /** Get the boundingBox. */
@@ -3,9 +3,13 @@ import { Annotation, AnnotationHorizontalJustify, AnnotationVerticalJustify } fr
3
3
  import { Articulation } from './articulation';
4
4
  import { BarNote } from './barnote';
5
5
  import { Beam, PartialBeamDirection } from './beam';
6
+ import { Bend } from './bend';
6
7
  import { ChordSymbol } from './chordsymbol';
8
+ import { Clef } from './clef';
7
9
  import { ClefNote } from './clefnote';
10
+ import { Crescendo } from './crescendo';
8
11
  import { Curve, CurveOptions } from './curve';
12
+ import { Dot } from './dot';
9
13
  import { EasyScore, EasyScoreOptions } from './easyscore';
10
14
  import { Element } from './element';
11
15
  import { FontInfo } from './font';
@@ -15,35 +19,53 @@ import { GhostNote } from './ghostnote';
15
19
  import { GlyphNote, GlyphNoteOptions } from './glyphnote';
16
20
  import { GraceNote, GraceNoteStruct } from './gracenote';
17
21
  import { GraceNoteGroup } from './gracenotegroup';
22
+ import { GraceTabNote } from './gracetabnote';
23
+ import { KeySignature } from './keysignature';
18
24
  import { KeySigNote } from './keysignote';
25
+ import { Modifier } from './modifier';
19
26
  import { ModifierContext } from './modifiercontext';
20
27
  import { MultiMeasureRest, MultimeasureRestRenderOptions } from './multimeasurerest';
21
28
  import { Note, NoteStruct } from './note';
22
29
  import { NoteSubGroup } from './notesubgroup';
23
30
  import { Ornament } from './ornament';
31
+ import { Parenthesis } from './parenthesis';
24
32
  import { PedalMarking } from './pedalmarking';
25
33
  import { RenderContext } from './rendercontext';
26
34
  import { RepeatNote } from './repeatnote';
27
35
  import { Sheet, SheetOptions } from './sheet';
28
36
  import { Stave, StaveOptions } from './stave';
29
- import { BarlineType } from './stavebarline';
37
+ import { Barline, BarlineType } from './stavebarline';
30
38
  import { StaveConnector, StaveConnectorType } from './staveconnector';
39
+ import { StaveHairpin, StaveHairpinRenderOptions } from './stavehairpin';
31
40
  import { StaveLine } from './staveline';
32
41
  import { StaveNote, StaveNoteStruct } from './stavenote';
42
+ import { Repetition } from './staverepetition';
43
+ import { StaveSection } from './stavesection';
44
+ import { StaveTempo } from './stavetempo';
45
+ import { StaveText } from './stavetext';
33
46
  import { StaveTie } from './stavetie';
47
+ import { Volta } from './stavevolta';
34
48
  import { StemmableNote } from './stemmablenote';
35
49
  import { StringNumber } from './stringnumber';
50
+ import { Stroke } from './strokes';
36
51
  import { System, SystemOptions } from './system';
37
52
  import { TabNote, TabNoteStruct } from './tabnote';
53
+ import { TabSlide } from './tabslide';
38
54
  import { TabStave } from './tabstave';
55
+ import { TabTie } from './tabtie';
39
56
  import { TextBracket } from './textbracket';
40
57
  import { TextDynamics } from './textdynamics';
41
58
  import { TextNote, TextNoteStruct } from './textnote';
42
59
  import { TickContext } from './tickcontext';
60
+ import { TimeSignature } from './timesignature';
43
61
  import { TimeSigNote } from './timesignote';
62
+ import { Tremolo } from './tremolo';
44
63
  import { Tuplet, TupletOptions } from './tuplet';
64
+ import { Vibrato } from './vibrato';
45
65
  import { VibratoBracket } from './vibratobracket';
46
66
  import { Voice, VoiceTime } from './voice';
67
+ /** Explicit drawing role for a native extension adopted into a Factory. */
68
+ export type FactoryElementRole = 'note' | 'modifier' | 'staveModifier' | 'drawable';
47
69
  export interface FactoryOptions {
48
70
  stave?: {
49
71
  space: number;
@@ -81,6 +103,24 @@ export declare class Factory {
81
103
  protected systems: System[];
82
104
  protected sheets: Sheet[];
83
105
  private retained;
106
+ /** Ownership survives drawing; weak keys do not retain discarded notation. */
107
+ private static owners;
108
+ private constructionScopes;
109
+ private groupScopes;
110
+ private static groups;
111
+ /** A grouped note draws only through its modifier, never through a main voice or queue. */
112
+ static getGroup(note: Note): Modifier | undefined;
113
+ /** Identify the Factory that created an element, without changing its draw role. */
114
+ static getOwner(element: Element): Factory | undefined;
115
+ /** Record ownership independently of whether the element draws itself or attaches to a note. */
116
+ private own;
117
+ /**
118
+ * Adopt a native extension without guessing its drawing role. Attachment and layout remain explicit.
119
+ * Repeating adoption cannot enqueue an element twice. Ownership survives draw/reset.
120
+ */
121
+ adopt<T extends Element>(element: T, role: FactoryElementRole): T;
122
+ /** Stage synchronous construction. Failed operations preserve existing queues and registry entries. */
123
+ transaction<T>(build: () => T): T;
84
124
  /** Foreground defaults survive reset(), like renderer options. */
85
125
  protected style: {
86
126
  fillStyle?: string;
@@ -121,6 +161,32 @@ export declare class Factory {
121
161
  width?: number;
122
162
  options?: StaveOptions;
123
163
  }): TabStave;
164
+ /** Construct a native Bend with an explicit drawing role. */
165
+ Bend(...args: ConstructorParameters<typeof Bend>): Bend;
166
+ /** Construct a native Clef with an explicit drawing role. */
167
+ Clef(...args: ConstructorParameters<typeof Clef>): Clef;
168
+ /** Construct a native KeySignature with an explicit drawing role. */
169
+ KeySignature(...args: ConstructorParameters<typeof KeySignature>): KeySignature;
170
+ /** Construct a native TimeSignature with an explicit drawing role. */
171
+ TimeSignature(...args: ConstructorParameters<typeof TimeSignature>): TimeSignature;
172
+ /** Construct a native Barline with an explicit drawing role. */
173
+ Barline(...args: ConstructorParameters<typeof Barline>): Barline;
174
+ /** Construct a native Repetition with an explicit drawing role. */
175
+ Repetition(...args: ConstructorParameters<typeof Repetition>): Repetition;
176
+ /** Construct a native Volta with an explicit drawing role. */
177
+ Volta(...args: ConstructorParameters<typeof Volta>): Volta;
178
+ /** Construct a native StaveSection with an explicit drawing role. */
179
+ StaveSection(...args: ConstructorParameters<typeof StaveSection>): StaveSection;
180
+ /** Construct a native StaveTempo with an explicit drawing role. */
181
+ StaveTempo(...args: ConstructorParameters<typeof StaveTempo>): StaveTempo;
182
+ /** Construct a native StaveText with an explicit drawing role. */
183
+ StaveText(...args: ConstructorParameters<typeof StaveText>): StaveText;
184
+ /** Construct a native TabTie with an explicit drawing role. */
185
+ TabTie(...args: ConstructorParameters<typeof TabTie>): TabTie;
186
+ /** Construct a native TabSlide with an explicit drawing role. */
187
+ TabSlide(...args: ConstructorParameters<typeof TabSlide>): TabSlide;
188
+ /** Grace tab children draw through a GraceNoteGroup, never as standalone tickables. */
189
+ GraceTabNote(options: TabNoteStruct): GraceTabNote;
124
190
  StaveNote(noteStruct: StaveNoteStruct): StaveNote;
125
191
  GlyphNote(glyph: string, noteStruct: NoteStruct, options?: GlyphNoteOptions): GlyphNote;
126
192
  RepeatNote(type: string, noteStruct?: NoteStruct, options?: GlyphNoteOptions): RepeatNote;
@@ -143,8 +209,9 @@ export declare class Factory {
143
209
  key: string;
144
210
  cancelKey?: string;
145
211
  alterKey?: string[];
212
+ clef?: string;
146
213
  }): KeySigNote;
147
- TabNote(noteStruct: TabNoteStruct): TabNote;
214
+ TabNote(noteStruct: TabNoteStruct, drawStem?: boolean): TabNote;
148
215
  GraceNote(noteStruct: GraceNoteStruct): GraceNote;
149
216
  GraceNoteGroup(params: {
150
217
  notes: StemmableNote[];
@@ -177,12 +244,7 @@ export declare class Factory {
177
244
  lowerAccidental?: string;
178
245
  delayed?: boolean;
179
246
  }): Ornament;
180
- TextDynamics(params?: {
181
- text?: string;
182
- duration?: string;
183
- dots?: number;
184
- line?: number;
185
- }): TextDynamics;
247
+ TextDynamics(params?: Partial<TextNoteStruct>): TextDynamics;
186
248
  Fingering(params: {
187
249
  number?: string;
188
250
  position?: string;
@@ -283,6 +345,27 @@ export declare class Factory {
283
345
  NoteSubGroup(params?: {
284
346
  notes?: Note[];
285
347
  }): NoteSubGroup;
348
+ /** Transfer unvoiced notes to one modifier. Validation happens before native voice assignment. */
349
+ groupNotes<T extends Modifier>(notes: Note[], construct: () => T): T;
350
+ /** Construct a native Dot for attachment; preserve its full constructor options. */
351
+ Dot(...args: ConstructorParameters<typeof Dot>): Dot;
352
+ /** Construct a native Parenthesis for attachment; preserve its full constructor options. */
353
+ Parenthesis(...args: ConstructorParameters<typeof Parenthesis>): Parenthesis;
354
+ /** Construct a native Stroke for attachment; preserve its full constructor options. */
355
+ Stroke(...args: ConstructorParameters<typeof Stroke>): Stroke;
356
+ /** Construct a native Tremolo for attachment; preserve its full constructor options. */
357
+ Tremolo(...args: ConstructorParameters<typeof Tremolo>): Tremolo;
358
+ /** Construct a native Vibrato for attachment; preserve its full constructor options. */
359
+ Vibrato(...args: ConstructorParameters<typeof Vibrato>): Vibrato;
360
+ /** Timed crescendo note; span hairpins have a separate constructor. */
361
+ Crescendo(...args: ConstructorParameters<typeof Crescendo>): Crescendo;
362
+ /** Stave-bound hairpin. The native renderer requires both endpoints. */
363
+ StaveHairpin(params: {
364
+ from: Note;
365
+ to: Note;
366
+ type: number;
367
+ options?: Partial<StaveHairpinRenderOptions>;
368
+ }): StaveHairpin;
286
369
  /** Render the score. */
287
370
  draw(options?: {
288
371
  retain?: boolean;
@@ -1,5 +1,6 @@
1
1
  import { BoundingBox } from './boundingbox';
2
2
  import { ModifierContext } from './modifiercontext';
3
+ import { ProportionalSpacing } from './proportionalformatter';
3
4
  import { RenderContext } from './rendercontext';
4
5
  import { Stave } from './stave';
5
6
  import { StemmableNote } from './stemmablenote';
@@ -8,7 +9,10 @@ import { TabStave } from './tabstave';
8
9
  import { Tickable } from './tickable';
9
10
  import { TickContext } from './tickcontext';
10
11
  import { Voice } from './voice';
12
+ export type { ProportionalSpacing } from './proportionalformatter';
11
13
  export interface FormatterOptions {
14
+ /** Omit to use the default engraving layout. */
15
+ spacing?: ProportionalSpacing;
12
16
  /** Defaults to Tables.SOFTMAX_FACTOR. */
13
17
  softmaxFactor?: number;
14
18
  /** Defaults to `false`. */
@@ -69,7 +73,9 @@ export declare class Formatter {
69
73
  protected totalCost: number;
70
74
  protected totalShift: number;
71
75
  protected tickContexts: AlignmentTickContexts;
72
- protected formatterOptions: Required<FormatterOptions>;
76
+ protected formatterOptions: Required<Omit<FormatterOptions, 'spacing'>> & Pick<FormatterOptions, 'spacing'>;
77
+ /** Present only for the opt-in rational timeline. */
78
+ private proportional?;
73
79
  protected modifierContexts: AlignmentModifierContexts[];
74
80
  protected voices: Voice[];
75
81
  protected lossHistory: number[];