vexflow 5.1.1 → 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 (96) hide show
  1. package/README.md +8 -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 +2916 -484
  7. package/build/cjs/vexflow-debug-with-tests.js.map +1 -1
  8. package/build/cjs/vexflow-debug.js +2761 -451
  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/chordkerning.js +98 -0
  16. package/build/esm/src/chordsymbol.js +108 -27
  17. package/build/esm/src/clef.js +3 -0
  18. package/build/esm/src/clefnote.js +5 -1
  19. package/build/esm/src/dot.js +1 -1
  20. package/build/esm/src/easyscore/composition.js +297 -0
  21. package/build/esm/src/easyscore/elementindex.js +81 -0
  22. package/build/esm/src/easyscore/elements.js +324 -0
  23. package/build/esm/src/easyscore/policies.js +69 -0
  24. package/build/esm/src/easyscore/rhythm.js +42 -0
  25. package/build/esm/src/easyscore.js +448 -26
  26. package/build/esm/src/element.js +13 -2
  27. package/build/esm/src/factory.js +256 -60
  28. package/build/esm/src/formatter.js +32 -4
  29. package/build/esm/src/keysignature.js +9 -1
  30. package/build/esm/src/keysignote.js +2 -2
  31. package/build/esm/src/note.js +5 -0
  32. package/build/esm/src/parenthesis.js +1 -1
  33. package/build/esm/src/parser.js +6 -1
  34. package/build/esm/src/proportionalformatter.js +186 -0
  35. package/build/esm/src/registry.js +27 -0
  36. package/build/esm/src/sheet.js +20 -3
  37. package/build/esm/src/stave.js +9 -2
  38. package/build/esm/src/stavenote.js +12 -12
  39. package/build/esm/src/stemmablenote.js +6 -1
  40. package/build/esm/src/tickable.js +5 -0
  41. package/build/esm/src/tuplet.js +3 -2
  42. package/build/esm/src/version.js +3 -3
  43. package/build/esm/src/vexflow.js +2 -1
  44. package/build/esm/tests/beam_tests.js +35 -0
  45. package/build/esm/tests/easyscore_tests.js +40 -0
  46. package/build/esm/tests/easyscore_types.js +65 -0
  47. package/build/esm/tests/formatter_tests.js +41 -0
  48. package/build/esm/tests/node/chord-kerning-tests.mjs +173 -0
  49. package/build/esm/tests/node/easyscore-rendering-tests.mjs +332 -0
  50. package/build/esm/tests/node/easyscore-tests.mjs +953 -0
  51. package/build/esm/tests/node/proportional-spacing-tests.mjs +214 -0
  52. package/build/esm/tests/node/tool-security-tests.mjs +85 -0
  53. package/build/esm/tools/easyscore-api-audit.mjs +58 -0
  54. package/build/esm/tools/easyscore-composition.mjs +62 -0
  55. package/build/esm/tools/easyscore-example.mjs +16 -0
  56. package/build/esm/tools/easyscore-families.mjs +61 -0
  57. package/build/esm/tools/easyscore-references-example.mjs +26 -0
  58. package/build/esm/tools/easyscore-rhythm.mjs +58 -0
  59. package/build/esm/tools/easyscore-structure.mjs +88 -0
  60. package/build/esm/tools/explorer/catalog/entries.mjs +6 -0
  61. package/build/esm/tools/explorer/catalog/expression.mjs +68 -0
  62. package/build/esm/tools/explorer/catalog/helpers.mjs +29 -0
  63. package/build/esm/tools/explorer/catalog/layout.mjs +109 -0
  64. package/build/esm/tools/explorer/catalog/notes.mjs +61 -0
  65. package/build/esm/tools/explorer/catalog/staves.mjs +85 -0
  66. package/build/esm/tools/explorer/catalog/strings.mjs +25 -0
  67. package/build/esm/tools/explorer/catalog.mjs +14 -0
  68. package/build/types/src/accidental.d.ts +2 -0
  69. package/build/types/src/articulation.d.ts +6 -0
  70. package/build/types/src/beam.d.ts +2 -0
  71. package/build/types/src/chordkerning.d.ts +42 -0
  72. package/build/types/src/chordsymbol.d.ts +19 -0
  73. package/build/types/src/clef.d.ts +2 -0
  74. package/build/types/src/easyscore/composition.d.ts +107 -0
  75. package/build/types/src/easyscore/elementindex.d.ts +30 -0
  76. package/build/types/src/easyscore/elements.d.ts +156 -0
  77. package/build/types/src/easyscore/policies.d.ts +12 -0
  78. package/build/types/src/easyscore/rhythm.d.ts +9 -0
  79. package/build/types/src/easyscore.d.ts +153 -11
  80. package/build/types/src/element.d.ts +5 -1
  81. package/build/types/src/factory.d.ts +91 -8
  82. package/build/types/src/formatter.d.ts +7 -1
  83. package/build/types/src/keysignature.d.ts +3 -0
  84. package/build/types/src/keysignote.d.ts +1 -1
  85. package/build/types/src/note.d.ts +2 -0
  86. package/build/types/src/parser.d.ts +5 -0
  87. package/build/types/src/proportionalformatter.d.ts +30 -0
  88. package/build/types/src/registry.d.ts +4 -0
  89. package/build/types/src/stave.d.ts +2 -0
  90. package/build/types/src/stavenote.d.ts +1 -1
  91. package/build/types/src/stemmablenote.d.ts +6 -1
  92. package/build/types/src/tickable.d.ts +2 -0
  93. package/build/types/src/vexflow.d.ts +2 -1
  94. package/changelog/CHANGELOG.md +57 -0
  95. package/package.json +19 -7
  96. package/tests/flow.html +10 -3
@@ -1,7 +1,9 @@
1
1
  import { BoundingBox } from './boundingbox';
2
+ import { ChordSymbolKerningProfile, ChordSymbolRun } from './chordkerning';
2
3
  import { Element } from './element';
3
4
  import { Modifier } from './modifier';
4
5
  import { ModifierContextState } from './modifiercontext';
6
+ export type { ChordSymbolKerningPair, ChordSymbolKerningProfile, ChordSymbolPosition } from './chordkerning';
5
7
  export declare class ChordSymbolBlock extends Element {
6
8
  symbolModifier: SymbolModifiers;
7
9
  vAlign: boolean;
@@ -51,6 +53,22 @@ export declare class ChordSymbol extends Modifier {
51
53
  protected horizontal: number;
52
54
  protected vertical: number;
53
55
  protected reportWidth: boolean;
56
+ /** Default rendering stays compatible; only a matching opt-in profile uses shaped runs. */
57
+ protected kerning: 'auto' | 'none';
58
+ protected kerningProfile?: ChordSymbolKerningProfile;
59
+ protected kernedRuns?: ChordSymbolRun[];
60
+ protected kerningMeasurement?: Element;
61
+ protected kerningOrigin: {
62
+ x: number;
63
+ y: number;
64
+ };
65
+ /** Select optical kerning. Format the score again after changing layout settings. */
66
+ setKerning(mode: 'auto' | 'none'): this;
67
+ getKerning(): 'auto' | 'none';
68
+ /** Replace the font-specific table for this chord only. Omit the profile to restore built-ins. */
69
+ setKerningProfile(profile?: ChordSymbolKerningProfile): this;
70
+ /** Re-measure on every format pass; Element's shared cache handles font loading and reuse. */
71
+ protected formatKerning(): number | undefined;
54
72
  constructor();
55
73
  /**
56
74
  * The offset is specified in `em`. Scale this value by the font size in pixels.
@@ -105,5 +123,6 @@ export declare class ChordSymbol extends Modifier {
105
123
  getHorizontal(): number;
106
124
  /** Render text and glyphs above/below the note. */
107
125
  draw(): void;
126
+ /** Return fresh ink bounds, including script offsets and overhangs. Empty symbols have empty bounds. */
108
127
  getBoundingBox(): BoundingBox;
109
128
  }
@@ -27,6 +27,8 @@ export declare class Clef extends StaveModifier {
27
27
  }>;
28
28
  /** Create a new clef. */
29
29
  constructor(type: string, size?: string, annotation?: string);
30
+ /** Return the named clef so staff attachments can retain musical state. */
31
+ getType(): string;
30
32
  /** Set clef type, size and annotation. */
31
33
  setType(type: string, size?: string, annotation?: string): this;
32
34
  /** Get point for clefs. */
@@ -0,0 +1,107 @@
1
+ import type { EasyScore, EasyScoreVoiceOptions } from '../easyscore';
2
+ import type { Element } from '../element';
3
+ import { Factory } from '../factory';
4
+ import { Note } from '../note';
5
+ import { Sheet, SheetOptions } from '../sheet';
6
+ import { Stave, StaveOptions } from '../stave';
7
+ import { StaveNoteStruct } from '../stavenote';
8
+ import { System, SystemOptions } from '../system';
9
+ import { TabNoteStruct } from '../tabnote';
10
+ import { Tickable } from '../tickable';
11
+ import { TupletOptions } from '../tuplet';
12
+ import { Voice, VoiceTime } from '../voice';
13
+ import { EasyScoreAutoBeamOptions } from './rhythm';
14
+ /** Written pitches stay literal, even when a key signature is displayed. */
15
+ export interface EasyScoreStaffState {
16
+ clef?: string;
17
+ key?: string;
18
+ time?: string;
19
+ }
20
+ /** Typed wrappers add IDs and cross-staff assignment without changing native note fields. */
21
+ export type EasyScoreContent = string | StaveNoteStruct | Tickable | {
22
+ note: StaveNoteStruct;
23
+ id?: string;
24
+ stave?: string;
25
+ } | {
26
+ tab: TabNoteStruct;
27
+ id?: string;
28
+ stave?: string;
29
+ drawStem?: boolean;
30
+ } | {
31
+ change: EasyScoreStaffState;
32
+ };
33
+ /** Tuplet indexes count timed notes, excluding inline signatures and barlines. */
34
+ export interface EasyScoreVoiceSpec {
35
+ notes: string | readonly EasyScoreContent[];
36
+ stem?: 'auto' | 'up' | 'down';
37
+ options?: Omit<EasyScoreVoiceOptions, 'time' | 'mode'>;
38
+ tuplets?: readonly {
39
+ start: number;
40
+ count: number;
41
+ options?: TupletOptions;
42
+ }[];
43
+ autoBeam?: boolean | EasyScoreAutoBeamOptions;
44
+ }
45
+ /** span is the actual duration of a pickup; time remains its displayed meter. */
46
+ export interface EasyScoreMeasureSpec extends EasyScoreStaffState {
47
+ voices: readonly EasyScoreVoiceSpec[];
48
+ span?: VoiceTime | string;
49
+ }
50
+ /** Staves have aligned measure arrays. Missing or uneven measures are errors. */
51
+ export interface EasyScoreStaveSpec extends EasyScoreStaffState {
52
+ id: string;
53
+ kind?: 'stave' | 'tab';
54
+ options?: StaveOptions;
55
+ spaceAbove?: number;
56
+ spaceBelow?: number;
57
+ measures: readonly EasyScoreMeasureSpec[];
58
+ }
59
+ /** IDs resolve only after all notes exist. Native handles remain available afterward. */
60
+ export type EasyScoreSpanSpec = {
61
+ kind: 'tie';
62
+ from?: string;
63
+ to?: string;
64
+ firstIndexes?: number[];
65
+ lastIndexes?: number[];
66
+ text?: string;
67
+ } | {
68
+ kind: 'curve';
69
+ from?: string;
70
+ to?: string;
71
+ options?: Parameters<Factory['Curve']>[0]['options'];
72
+ } | {
73
+ kind: 'hairpin';
74
+ from: string;
75
+ to: string;
76
+ type: number;
77
+ options?: Parameters<Factory['StaveHairpin']>[0]['options'];
78
+ };
79
+ /** Layout policies are explicit. Sheet does not split spans or repeat signatures at row starts. */
80
+ export interface EasyScoreCompositionSpec {
81
+ staves: readonly EasyScoreStaveSpec[];
82
+ sheet?: Omit<SheetOptions, 'factory'>;
83
+ system?: Omit<SystemOptions, 'factory' | 'width' | 'autoWidth' | 'noJustification'>;
84
+ accidentals?: 'literal' | 'key-aware';
85
+ signatures?: 'changes' | 'every-measure';
86
+ spans?: readonly EasyScoreSpanSpec[];
87
+ crossMeasureSpans?: 'reject' | 'manual';
88
+ }
89
+ /** Structured warnings identify deliberate native layout limitations. */
90
+ export interface EasyScoreCompositionDiagnostic {
91
+ code: 'ManualSpan' | 'SignaturePolicy';
92
+ message: string;
93
+ }
94
+ /** Arrays are measure-first, then stave, then voice. Layout remains mutable through native objects. */
95
+ export interface EasyScoreComposition {
96
+ sheet: Sheet;
97
+ systems: System[];
98
+ staves: Stave[][];
99
+ voices: Voice[][][];
100
+ notes: Tickable[][][][];
101
+ spans: Element[];
102
+ diagnostics: EasyScoreCompositionDiagnostic[];
103
+ getElement: (id: string) => Element | undefined;
104
+ getNote: (id: string) => Note;
105
+ }
106
+ /** Compose aligned measure arrays atomically. Formatting and drawing remain explicit native operations. */
107
+ export declare function compose(score: EasyScore, spec: EasyScoreCompositionSpec): EasyScoreComposition;
@@ -0,0 +1,30 @@
1
+ import type { EasyScoreSourceSpan } from '../easyscore';
2
+ import type { Element } from '../element';
3
+ /** Original notation input and its UTF-16, end-exclusive range. Measures are one-based. */
4
+ export interface EasyScoreSource extends EasyScoreSourceSpan {
5
+ input: string;
6
+ measure?: number;
7
+ }
8
+ /** One index per EasyScore. Weak provenance also lets visual debuggers inspect an element directly. */
9
+ export declare class EasyScoreReferences {
10
+ private static sources;
11
+ private ids;
12
+ private entries;
13
+ private scopes;
14
+ /** Return a copy so tools cannot change the stored source range. */
15
+ static sourceOf(element: Element): EasyScoreSource | undefined;
16
+ /** Missing IDs are ordinary lookup misses, including after reset. */
17
+ get(id: string): Element | undefined;
18
+ /** Only members of this score have instance-local source metadata. */
19
+ getSource(element: Element): EasyScoreSource | undefined;
20
+ /** Reject empty or duplicate IDs before registration or native ID mutation. */
21
+ private validate;
22
+ /** Repeated registration is harmless. Native ID changes keep the index synchronized. */
23
+ add<T extends Element>(element: T, source?: EasyScoreSource): T;
24
+ /** Release exactly this score's subscription and provenance. */
25
+ private remove;
26
+ /** Preserve references across draw(); reset explicitly ends the editing session. */
27
+ clear(): void;
28
+ /** Nested failed construction releases subscriptions as well as visible references. */
29
+ transaction<T>(build: () => T): T;
30
+ }
@@ -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. */