@barmark/score 0.0.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,96 @@
1
+ # Changelog
2
+
3
+ All notable changes to `@barmark/score` are recorded here. The format
4
+ follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the
5
+ package uses [semantic versioning](https://semver.org/).
6
+
7
+ ## [Unreleased]
8
+
9
+ ## [0.1.1] - 2026-11-09
10
+
11
+ Requires `@barmark/musicxml` 0.7.2.
12
+
13
+ ### Fixed
14
+
15
+ - **A chord symbol is drawn as the chart spells it.** Verovio 6.4 appends
16
+ every `<degree>` to the kind text, `print-object="no"` or not, so
17
+ `D7sus4` was drawn `D7sus4(7)` and `G5(7)` as `G5(7)(no3)`. The score
18
+ now drops a degree that is not printed before Verovio reads the
19
+ MusicXML (with `@barmark/musicxml`'s next release, which hides a degree
20
+ its kind text already spells). `Engraved.xml` is the export unchanged.
21
+ The pass is linear (a single `indexOf` scan, no backtracking regex), so a
22
+ hostile MusicXML given to `engraveXml` cannot stall it.
23
+ - **The Grid / Score switch follows the element's `theme`.** It sits
24
+ outside the grid's themed `.bm-chart`, and render's `:host{all:initial}`
25
+ reset its colour and font, so on a dark page it was black text in the
26
+ browser's serif. It now takes render's ink and rule for `theme="dark"`,
27
+ for `auto` (or no theme) under a dark colour scheme, and light ones
28
+ otherwise and in print, honouring `--barmark-ink` and `--barmark-rule`,
29
+ in render's label font (`--barmark-label-font`). A page no longer has to
30
+ colour the host itself.
31
+ - **Chord accidentals and the tempo's note draw in Chromium.** Verovio
32
+ declares its Leipzig font (the ♯, ♭ and ♩) inside the score's SVG, in the
33
+ shadow root, where Chromium never registers a font face, so `C♯m7` drew
34
+ as `C m7`. The element now copies that face, once per document, into a
35
+ `<style data-barmark-score-font>` in the head. A page that copied it
36
+ itself can drop the copy.
37
+
38
+ ## [0.1.0] - 2026-11-08
39
+
40
+ First release.
41
+
42
+ ### Added
43
+
44
+ - `<barmark-score>` (import `@barmark/score/element`, which also registers
45
+ `<barmark-chart>`): the chart as the bar grid or as a full score, with a
46
+ Grid / Score switch (a keyboard radio group). Its chart comes from `text`,
47
+ `src` or a script child, as `<barmark-chart>`'s does, and it takes every
48
+ grid attribute plus `view` (`grid` | `score`) and `verovio-url` (resolved
49
+ against the page, http(s) only); a `viewchange` event follows the view. A
50
+ `view="score"` set before the chart arrives waits for it. The score engine
51
+ loads only on the first switch to the score, engraves at the element's
52
+ width (again after a resize), and shows "Loading score…" meanwhile, the
53
+ first time; a re-engrave keeps the score shown, marked `aria-busy`, until
54
+ the new one lands, so a resize does not blank it. The drawn score is one
55
+ image (`role="img"`) named for the chart's title, or "Score". A score that
56
+ can't be drawn leaves the grid with a note by the switch; a new chart or a
57
+ new `verovio-url` lets the Score radio try again. While `view="score"`
58
+ waits for its chart, Grid is the radio checked, as the grid is what
59
+ shows. Every element on a page shares one worker, so the first
60
+ `verovio-url` that loads is the one used. A shadow
61
+ root drawn by `renderScoreHtml` is taken over without redrawing the grid.
62
+ Importing the package root registers no element.
63
+ - `renderScoreHtml` (from `@barmark/score/server`, which never reaches
64
+ Verovio) draws `<barmark-score>` on the server: the bar grid, the Grid /
65
+ Score switch and the chart text, so the grid shows before any script runs;
66
+ any `view` but `"score"` reads as the grid, and `view: "score"` checks the
67
+ Grid radio (the grid is what shows) while the element keeps `view="score"`
68
+ and switches once it loads. `decodeCarried` reads the text back.
69
+ - `engraveChart` turns a chart into a full score (MusicXML from
70
+ `@barmark/musicxml`, engraved by Verovio) as one SVG column, or says why
71
+ it cannot (a chart that will not export, a score Verovio cannot read or
72
+ one with no pages: `ok: false`, never a throw; a refusal about the whole
73
+ chart does not read "Line 0: …").
74
+ - Safe, themed score markup: `cleanSvg` is an allow-list. A hand-written
75
+ scanner keeps only the elements and attributes Verovio emits (and its own
76
+ two stylesheets) and drops anything else with its content: scripts,
77
+ `foreignObject`, `on*` attributes, links that leave the page and
78
+ attributes whose value holds a character reference. It throws on markup it
79
+ cannot read cleanly (a self-closing `style` or `title`), which
80
+ `engraveChart` turns into `ok: false`. `scorePane` wraps the pages in
81
+ render's `.bm-chart[data-theme]` so the score follows the palette (light,
82
+ dark, auto, print), including the notes, which override Verovio's
83
+ `color="black"`; `scoreStyles` is the score's own layout. `scorePane`
84
+ takes the score's accessible name as an optional third argument (default
85
+ "Score").
86
+ - A shared Verovio worker: `engine()` runs every score of a page through one
87
+ module Worker that loads Verovio on first use, and for each element only
88
+ the newest request is answered (`createEngine` takes any `WorkerLike`); a
89
+ crashed worker rejects what is pending and is replaced on the next call.
90
+ - The README says how to use the element with Vite: Vite 8 (and Vite+)
91
+ needs no config; Vite 7 needs `optimizeDeps.exclude` and
92
+ `worker.format: "es"`.
93
+
94
+ [Unreleased]: https://github.com/kevinpeckham/barmark/compare/score-v0.1.1...HEAD
95
+ [0.1.1]: https://github.com/kevinpeckham/barmark/compare/score-v0.1.0...score-v0.1.1
96
+ [0.1.0]: https://github.com/kevinpeckham/barmark/releases/tag/score-v0.1.0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Kevin Peckham
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,146 @@
1
1
  # @barmark/score
2
2
 
3
- A chart drawn as a full score. The first release is coming: see https://github.com/kevinpeckham/barmark
3
+ Shows a [barmark](https://github.com/kevinpeckham/barmark) chord chart as
4
+ the bar grid or as a full engraved score. The chart is exported to MusicXML
5
+ by `@barmark/musicxml` and engraved by Verovio in a Web Worker; the score
6
+ adds no music of its own.
7
+
8
+ ```
9
+ npm install @barmark/score
10
+ ```
11
+
12
+ ## Two components
13
+
14
+ - **`<barmark-chart>`** from [`@barmark/render`](../render/) is the light
15
+ one: the bar grid, no Verovio.
16
+ - **`<barmark-score>`** from this package is the heavier one: the same grid,
17
+ plus a Grid / Score switch to a full score. Verovio (about 7 MB) loads
18
+ only on the first switch to the score, never on page load, and one copy
19
+ serves every score on the page.
20
+
21
+ Use `<barmark-chart>` when the grid is enough.
22
+
23
+ ## As a web component
24
+
25
+ ```html
26
+ <script type="module">import "@barmark/score/element";</script>
27
+
28
+ <barmark-score src="/charts/peaceful-dreams.chart.md"></barmark-score>
29
+
30
+ <barmark-score view="score" theme="dark">
31
+ <script type="text/barmark">
32
+ ## Verse
33
+ | D | A | Bm | G |
34
+ </script>
35
+ </barmark-score>
36
+ ```
37
+
38
+ Importing `@barmark/score/element` also registers `<barmark-chart>` (it
39
+ builds on it). Importing the package root registers nothing.
40
+
41
+ The chart comes from the `text` property, the `src` URL or a child
42
+ `<script type="text/barmark">`, exactly as for `<barmark-chart>`. The score
43
+ is engraved at the element's width and again after a resize; the score shown
44
+ stays (with `aria-busy="true"`) until the new one is ready. To assistive
45
+ technology the score is one image named for the chart's title, or "Score".
46
+
47
+ | Attribute (property) | |
48
+ |---|---|
49
+ | `src`, `theme`, `bar-numbers`, `rehearsal-letters`, `numerals`, `wrap`, `show-part` | the grid's own, as in [`@barmark/render`](../render/README.md#options-and-attributes) |
50
+ | `view` (`view`) | `"grid"` (default) or `"score"`; the view being shown. Set before the chart arrives, `"score"` waits for it |
51
+ | `verovio-url` | where to load Verovio from (below) |
52
+
53
+ The `text` property is the chart's text (`null` goes back to `src` or the
54
+ script child). The element fires a `viewchange` event, with
55
+ `detail.view`, whenever the view changes, from the switch or from script.
56
+
57
+ ```js
58
+ const score = document.querySelector("barmark-score");
59
+ score.addEventListener("viewchange", (e) => console.log(e.detail.view));
60
+ score.view = "score";
61
+ ```
62
+
63
+ ### Bundling the worker
64
+
65
+ The engine runs in a module Worker, created as
66
+ `new Worker(new URL("./worker.js", import.meta.url), { type: "module" })`.
67
+ That is the pattern Vite and webpack follow, so a bundler finds the worker
68
+ and Verovio for you.
69
+
70
+ Vite 8 (and Vite+) needs no config, in `vite dev` or a build. Vite 7 needs
71
+ two lines: its dev pre-bundler moves the element away from the worker and
72
+ the font it finds by URL, and it builds workers as `iife`, which cannot
73
+ load Verovio on demand.
74
+
75
+ ```js
76
+ // vite.config.js, for Vite 7 (harmless on Vite 8)
77
+ export default {
78
+ optimizeDeps: { exclude: ["@barmark/score"] },
79
+ worker: { format: "es" },
80
+ };
81
+ ```
82
+
83
+ Without a bundler, a page's import map does not reach a worker, so the
84
+ worker's bare imports (`verovio/esm`, `barmark`, `@barmark/musicxml`)
85
+ fail. Serve a bundled `worker.js` at the package's URL. `verovio-url` can
86
+ then point at a Verovio module you host (for example
87
+ `verovio/dist/verovio-module.mjs` from the `verovio` package) instead of
88
+ bundling the 7 MB inside the worker; it only changes where that module
89
+ comes from. The URL is resolved against the page and must be http(s);
90
+ anything else is refused and the score is not drawn. The first
91
+ `verovio-url` that loads wins for the whole page: every element shares one
92
+ worker, so a later or different URL is not loaded.
93
+
94
+ ### When the score can't be drawn
95
+
96
+ If Verovio fails to load, or rejects the MusicXML, or the chart will not
97
+ export, the grid stays and a note by the switch says "The score couldn't
98
+ be drawn". The reason goes to the console.
99
+
100
+ ## On the server
101
+
102
+ ```js
103
+ import { renderScoreHtml } from "@barmark/score/server";
104
+
105
+ const html = renderScoreHtml(chartText, { fontUrl: "/fonts/Edwin-Roman.otf" });
106
+ ```
107
+
108
+ `renderScoreHtml` takes `@barmark/render`'s options plus `view`. It never
109
+ loads Verovio: it draws the bar grid and the Grid / Score switch in a
110
+ declarative shadow root, so the chart shows before any script runs. The
111
+ score is engraved once `<barmark-score>` upgrades in the browser, taking
112
+ over the markup without redrawing the grid. Like `renderChart`, insert it
113
+ by parsing HTML (or `setHTMLUnsafe`), not `innerHTML`.
114
+
115
+ ## Engraving directly
116
+
117
+ ```js
118
+ import createVerovioModule from "verovio/wasm";
119
+ import { VerovioToolkit } from "verovio/esm";
120
+ import { engraveChart } from "@barmark/score";
121
+
122
+ const vrv = new VerovioToolkit(await createVerovioModule());
123
+ const result = engraveChart(vrv, chartText, { width: 800 });
124
+ if (result.ok) document.body.innerHTML = result.svg;
125
+ else console.warn(result.reason);
126
+ ```
127
+
128
+ The SVG is cleaned with an allow-list (`cleanSvg`) before it is returned;
129
+ `scorePane` and `scoreStyles` wrap it so it follows the grid's light and
130
+ dark palette. `engraveChart` and `engraveXml` drop a chord `<degree>`
131
+ marked `print-object="no"` before Verovio reads the MusicXML, as Verovio
132
+ 6.4 prints every degree after the chord's text (`D7sus4(7)`); `result.xml`
133
+ is the export unchanged.
134
+
135
+ ## Licence
136
+
137
+ This package is MIT. It uses [Verovio](https://github.com/rism-digital/verovio),
138
+ which is LGPL-3.0-only, as an ordinary npm dependency, loaded unchanged at
139
+ run time; its code is never copied into this package. barmark's own code
140
+ stays MIT. Verovio's licence text is
141
+ [COPYING.LESSER](https://github.com/rism-digital/verovio/blob/develop/COPYING.LESSER).
142
+
143
+ A site that bundles the worker ships Verovio inside its bundle. Keeping
144
+ Verovio a separate file (through `verovio-url`, or the bundler's own
145
+ chunk) and keeping its notice is the easy way to meet the LGPL. This is
146
+ not legal advice.
@@ -0,0 +1,13 @@
1
+ /**
2
+ * `<barmark-score>`: a chart as barmark's bar grid or as a full score, with a
3
+ * Grid / Score switch. Its chart comes from the `text` property, a `src` URL or
4
+ * a child `<script type="text/barmark">`, as `<barmark-chart>`'s does. A shadow
5
+ * root drawn by `renderScoreHtml` is reused. The score engine (Verovio, in a
6
+ * worker) loads on the first switch to the score, never before. Importing
7
+ * this module registers the element (once) and the font (once per document).
8
+ */
9
+ import type { Engine } from "./engine.js";
10
+ type EngineFactory = () => Engine | Promise<Engine>;
11
+ /** For tests only: an engine to use in place of the worker's, or null for the real one. */
12
+ export declare function setEngineForTests(factory: EngineFactory | null): void;
13
+ export {};