@barmark/render 0.7.3 → 0.9.0

package/CHANGELOG.md

@@ -6,6 +6,39 @@ package uses [semantic versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-11-03
+
+### Added
+
+- **Rehearsal marks** draw as a boxed label at the start of their bar
+  (`part="mark"`), spoken "rehearsal B". Bar numbers skip them.
+- **Words on a bar** draw small, above the slot they precede, or at the
+  bar's end (`part="words"`), and are spoken in place: "bar 1: “solo” D,
+  A".
+- **Accents and hits** draw `>` or `^` above the chord
+  (`data-articulation`), spoken "accented D" and "D short hit".
+- **Pushes** draw `‹` (an eighth) or `«` (a sixteenth) before the slot
+  (`data-push`), spoken "D pushed" and "D pushed a sixteenth".
+- **Omissions** are spoken "C seven no third".
+- **Voicings** draw the chord's name; a screen reader hears the notes:
+  "C major seven voiced E3 G3 B3 C4".
+
+## [0.8.0] - 2026-11-03
+
+Requires `barmark` 0.11.0.
+
+### Changed
+
+- **Depends on `barmark` `^0.11.0`** (was `^0.10.0`).
+
+### Added
+
+- **Endings:** an ending row has a bracket over its bars and a `1.`, `2.`
+  or `1.–3.` label; screen readers hear "ending for pass 1".
+- **Directions:** Segno and Coda as their signs, To Coda with the coda
+  sign, Fine and the jumps as words. Each is spoken ("dal segno al
+  coda"). Bar numbers skip them, since they are not bars.
+
 ## [0.7.3] - 2026-11-03
 
 Requires `barmark` 0.10.0. No change to the renderer's code: a page that
@@ -223,7 +256,9 @@ that needs no script or as the `<barmark-chart>` web component. Requires
   zoom without sideways scrolling, the element renders and re-renders, and
   a screen reader hears "bar 9: D". Run them with `bun run test:browser`.
 
-[Unreleased]: https://github.com/kevinpeckham/barmark/compare/render-v0.7.3...HEAD
+[Unreleased]: https://github.com/kevinpeckham/barmark/compare/render-v0.9.0...HEAD
+[0.9.0]: https://github.com/kevinpeckham/barmark/compare/render-v0.8.0...render-v0.9.0
+[0.8.0]: https://github.com/kevinpeckham/barmark/compare/render-v0.7.3...render-v0.8.0
 [0.7.3]: https://github.com/kevinpeckham/barmark/compare/render-v0.7.2...render-v0.7.3
 [0.7.2]: https://github.com/kevinpeckham/barmark/compare/render-v0.7.1...render-v0.7.2
 [0.7.1]: https://github.com/kevinpeckham/barmark/compare/render-v0.7.0...render-v0.7.1

package/dist/html.js

@@ -1,3 +1,9 @@
+/**
+ * The chart model as HTML: a <barmark-chart> holding a declarative shadow
+ * root, or the bare markup for pages that bring the stylesheet themselves.
+ * Every string from the chart is escaped; every bar carries its spoken name.
+ */
+import { printDirection, printPasses, } from "barmark";
 import { glyphs, NUMERALS, splitPitch, typesetChord, typesetNumeral, } from "./chord.js";
 import { escapeHtml } from "./escape.js";
 import { fontFaceCss } from "./font.js";
@@ -91,11 +97,20 @@ function fitWidth(block) {
     return FIT_STEPS.find((step) => step >= total) ?? FIT_STEPS.at(-1) ?? 0;
 }
 /** Em per bar: padding, plus each slot's text and the gap after it. */
-const cellWidth = (cell) => cell.kind === "fermata"
-    ? MIN_BAR
-    : Math.max(MIN_BAR, 1.5 + (cell.meter ? 0.8 : 0) + cell.slots.reduce((w, s) => w + slotWidth(s), 0));
-/** Roughly: 0.65em a baseline character, 0.4em a superscript one, 0.6em between slots. */
+function cellWidth(cell) {
+    if (cell.kind === "direction")
+        return 1 + 0.55 * printDirection(cell.direction).length;
+    if (cell.kind === "rehearsal")
+        return 1.4 + 0.6 * cell.label.length;
+    if (cell.kind === "fermata")
+        return MIN_BAR;
+    return Math.max(MIN_BAR, 1.5 + (cell.meter ? 0.8 : 0) + cell.slots.reduce((w, s) => w + slotWidth(s), 0));
+}
+/** Roughly: 0.65em a baseline character, 0.4em a superscript one, 0.6em between slots, 0.45em a push mark. */
 function slotWidth(slot) {
+    return ("push" in slot && slot.push ? 0.45 : 0) + unmarkedWidth(slot);
+}
+function unmarkedWidth(slot) {
     if (slot.kind === "group")
         return slot.members.reduce((w, m) => w + slotWidth(m), 0.2);
     if (slot.kind !== "chord")
@@ -145,15 +160,28 @@ function rowHtml(row, columns, settings) {
         ? `<span class="bm-bar-number" part="bar-number" aria-hidden="true">${row.barNumber ?? ""}</span>`
         : "";
     let n = row.barNumber;
+    const label = row.ending ? endingLabel(row.ending) : null;
     const cells = row.cells.map((cell, i) => {
-        const html = cellHtml(cell, n, repeatMarks(row, i), settings.numerals);
+        const ending = i === 0 && label ? ` data-ending="${label.shown}"` : "";
+        const html = cellHtml(cell, n, repeatMarks(row, i) + ending, settings.numerals);
         if (n !== null && cell.kind === "slots")
             n++;
         return html;
     });
     const empty = `<span class="bm-empty" aria-hidden="true"></span>`.repeat(Math.max(0, columns - row.cells.length));
     const opens = row.opens || typeof row.repeat === "number" || row.repeat === "open";
-    return `<div class="bm-row">${opens ? `<span class="bm-sr">repeat start</span>` : ""}${number}${cells.join("")}${empty}<span class="bm-repeat">${rowRepeatHtml(row)}</span></div>`;
+    const ending = label ? `<span class="bm-sr">${label.spoken}</span>` : "";
+    return `<div class="bm-row${label ? " bm-ending" : ""}">${opens ? `<span class="bm-sr">repeat start</span>` : ""}${ending}${number}${cells.join("")}${empty}<span class="bm-repeat">${rowRepeatHtml(row)}</span></div>`;
+}
+/** An ending's passes as printed, "1.", "1.–3.", "1., 3.", and spoken, "ending for passes 1 to 3". */
+function endingLabel(passes) {
+    const parts = printPasses(passes)
+        .split(",")
+        .map((part) => part.split("-"));
+    const shown = parts.map((p) => p.map((n) => `${n}.`).join("–")).join(", ");
+    const said = parts.map((p) => p.join(" to "));
+    const list = said.length > 1 ? `${said.slice(0, -1).join(", ")} and ${said.at(-1)}` : said[0];
+    return { shown, spoken: `ending for pass${passes.length > 1 ? "es" : ""} ${list}` };
 }
 /** Repeat bar lines: ‖: on a row's first bar, :‖ on its last. */
 function repeatMarks(row, i) {
@@ -170,17 +198,77 @@ function rowRepeatHtml(row) {
 function cellHtml(cell, barNumber, marks, numerals) {
     const view = numerals && cell.kind === "slots" && cell.key ? { style: numerals, key: cell.key } : null;
     const spoken = `<span class="bm-sr">${escapeHtml(speakBar(barNumber, cell, view !== null))}</span>`;
-    if (cell.kind === "fermata")
-        return `<div class="bm-bar bm-fermata" part="bar"${marks}>${spoken}<span aria-hidden="true">${FERMATA}</span></div>`;
+    if (cell.kind !== "slots")
+        return betweenBarsHtml(cell, spoken, marks);
     const meter = cell.meter
         ? `<span class="bm-meter"><span>${cell.meter.n}</span><span>${cell.meter.d}</span></span>`
         : "";
     const cut = cell.cut ? `<span class="bm-cut">cut</span>` : "";
     const change = cell.tempoChange ? ` data-tempo-change="${cell.tempoChange}"` : "";
-    return `<div class="bm-bar" part="bar"${cell.cut ? " data-cut" : ""}${change}${marks}>${spoken}<span class="bm-bar-body" aria-hidden="true">${meter}${cell.slots.map((s) => slotHtml(s, view)).join("")}${cut}</span></div>`;
+    const [slots, end] = slotsWithWords(cell, view);
+    return `<div class="bm-bar" part="bar"${cell.cut ? " data-cut" : ""}${change}${marks}>${spoken}<span class="bm-bar-body" aria-hidden="true">${meter}${slots.join("")}${cut}</span>${end}</div>`;
 }
+/** A bar's slots, each under any words before it, and the words after the last slot. */
+function slotsWithWords(cell, view) {
+    const words = (at) => (cell.words ?? [])
+        .filter((w) => w.at === at)
+        .map((w) => escapeHtml(w.text))
+        .join(" ");
+    const slots = cell.slots.map((s, i) => {
+        const said = words(i);
+        const html = slotHtml(s, view);
+        return said
+            ? `<span class="bm-worded"><span class="bm-words" part="words">${said}</span>${html}</span>`
+            : html;
+    });
+    const after = words(cell.slots.length);
+    return [
+        slots,
+        after
+            ? `<span class="bm-words bm-words-end" part="words" aria-hidden="true">${after}</span>`
+            : "",
+    ];
+}
+/** A fermata, a rehearsal mark or a direction: a place between bars, drawn as its sign. */
+function betweenBarsHtml(cell, spoken, marks) {
+    if (cell.kind === "fermata")
+        return `<div class="bm-bar bm-fermata" part="bar"${marks}>${spoken}<span aria-hidden="true">${FERMATA}</span></div>`;
+    if (cell.kind === "rehearsal")
+        return `<div class="bm-bar bm-mark" part="mark"${marks}>${spoken}<span class="bm-box" aria-hidden="true">${escapeHtml(cell.label)}</span></div>`;
+    return `<div class="bm-bar bm-direction" part="direction" data-direction="${cell.direction.kind}"${marks}>${spoken}<span aria-hidden="true">${directionGlyph(cell.direction)}</span></div>`;
+}
+/** Segno and coda as the score's signs; To Coda and the jumps as their words. */
+function directionGlyph(d) {
+    if (d.kind === "segno")
+        return SEGNO;
+    if (d.kind === "coda")
+        return CODA;
+    const words = `<span class="bm-direction-words">${escapeHtml(printDirection(d))}</span>`;
+    return d.kind === "to coda" ? `${words} ${CODA}` : words;
+}
+const SEGNO = `<svg class="bm-sign" viewBox="0 0 20 28" width="0.9em" height="1.25em"><path d="M14.5 6.5c-1-3-6.5-3.5-7.5-.5s3 4.5 4.5 5.5 5 3.5 3 7-7.5 2-8-1" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round"/><path d="M4 24 16 3" stroke="currentColor" stroke-width="1.6"/><circle cx="4.5" cy="13" r="1.6" fill="currentColor"/><circle cx="15.5" cy="15" r="1.6" fill="currentColor"/></svg>`;
+const CODA = `<svg class="bm-sign" viewBox="0 0 24 24" width="1em" height="1em"><circle cx="12" cy="12" r="6.5" fill="none" stroke="currentColor" stroke-width="2"/><path d="M12 1v22M1 12h22" stroke="currentColor" stroke-width="1.6"/></svg>`;
 const FERMATA = `<svg class="bm-fermata-glyph" viewBox="0 0 24 14" width="1.4em" height="0.8em"><path d="M2 13 A10 10 0 0 1 22 13" fill="none" stroke="currentColor" stroke-width="1.8"/><circle cx="12" cy="11" r="1.8" fill="currentColor"/></svg>`;
+/** `‹` for an eighth push, `«` for a sixteenth. */
+const PUSH_MARK = { eighth: "‹", sixteenth: "«" };
+const ARTICULATION_MARK = { accent: ">", hit: "^" };
+const marksOf = (slot) => ({
+    push: "push" in slot ? (slot.push ?? null) : null,
+    articulation: slot.kind === "chord" ? (slot.articulation ?? null) : null,
+});
+/** A slot with its push mark before it and its accent or hit above it. */
 function slotHtml(slot, view) {
+    const body = unmarkedSlotHtml(slot, view);
+    const { push, articulation } = marksOf(slot);
+    if (!push && !articulation)
+        return body;
+    const data = `${push ? ` data-push="${push}"` : ""}${articulation ? ` data-articulation="${articulation}"` : ""}`;
+    const above = articulation
+        ? `<span class="bm-artic">${ARTICULATION_MARK[articulation]}</span>`
+        : "";
+    return `<span class="bm-marked"${data}>${push ? `<span class="bm-push" aria-hidden="true">${PUSH_MARK[push]}</span>` : ""}${above}${body}</span>`;
+}
+function unmarkedSlotHtml(slot, view) {
     switch (slot.kind) {
         case "chord":
             return chordHtml(slot.chord, view);

package/dist/model.js

@@ -220,7 +220,7 @@ function layoutRow(l, played, previous, ctx) {
     let prev = previous;
     for (const cell of l.cells) {
         const model = layoutCell(cell, played[bar] ?? written[bar], prev);
-        if (cell.kind !== "fermata")
+        if (cell.kind === "slots" || cell.kind === "simile")
             bar++;
         if (model.kind === "slots")
             prev = model;
@@ -234,6 +234,7 @@ function layoutRow(l, played, previous, ctx) {
         opens: l.opens,
         closes: l.closes,
         repeat: l.repeat,
+        ending: l.ending,
         cells,
     };
 }
@@ -241,14 +242,23 @@ function layoutRow(l, played, previous, ctx) {
 function layoutCell(cell, played, previous) {
     if (cell.kind === "fermata")
         return { kind: "fermata" };
-    const from = cell.kind === "slots" ? cell : previous;
-    return withPlayed({
+    if (cell.kind === "direction" || cell.kind === "rehearsal")
+        return cell;
+    return withPlayed(layoutBar(cell, played, previous), played);
+}
+/** A bar or `%`, with the slots it plays. */
+function layoutBar(cell, played, previous) {
+    const own = cell.kind === "slots" ? cell : null;
+    return {
         kind: "slots",
-        meter: from?.meter ?? null,
-        slots: played?.slots ?? (cell.kind === "slots" ? cell.slots : []),
+        meter: (own ?? previous)?.meter ?? null,
+        slots: played?.slots ?? own?.slots ?? [],
         cut: false,
-    }, played);
+        ...wordsOf(cell),
+    };
 }
+/** The words written on a bar, as a field to spread; nothing when it has none. */
+const wordsOf = (cell) => cell.words ? { words: cell.words } : {};
 /** What the parser says about the bar as played: inside a rit. or accel., and its key. */
 function withPlayed(cell, played) {
     const change = played?.tempoChange?.kind;

package/dist/speech.js

@@ -2,7 +2,7 @@
  * Spoken names: how a screen reader reads a chart as music. Built from the
  * parsed structure, never from the symbol's text.
  */
-import { degreeOf } from "barmark";
+import { degreeOf, } from "barmark";
 const NUMBERS = {
     "1": "one",
     "2": "two",
@@ -60,7 +60,10 @@ function speakPitch(label) {
     return `${m[1]}${ACCIDENTAL[m[2] ?? ""] ?? ""}${octave}`;
 }
 /** `b9` → "flat nine"; a natural tone is added: `9` → "add nine". */
+const LEFT_OUT = { no3: "no third", no5: "no fifth" };
 function speakTone(tone) {
+    if (LEFT_OUT[tone])
+        return LEFT_OUT[tone];
     const m = /^(#|b)?(\d+)$/.exec(tone);
     if (!m)
         return tone;
@@ -102,10 +105,23 @@ export function speakChord(record, key) {
     const degree = key ? speakDegree(record.parts.root, key) : "";
     return `${degree ? `${degree}, ` : ""}${speakParts(record.parts)}`;
 }
+const PUSHED = { eighth: "pushed", sixteenth: "pushed a sixteenth" };
+/** A chord with its voicing and articulation: "accented D", "G short hit", "C major seven voiced E3 G3". */
+function speakChordSlot(slot, key) {
+    const name = speakChord(slot.chord, key);
+    const voiced = slot.voicing ? `${name} voiced ${slot.voicing.pitches.join(" ")}` : name;
+    if (slot.articulation === "accent")
+        return `accented ${voiced}`;
+    return slot.articulation === "hit" ? `${voiced} short hit` : voiced;
+}
 export function speakSlot(slot, key) {
+    const said = speakUnpushed(slot, key);
+    return "push" in slot && slot.push ? `${said} ${PUSHED[slot.push]}` : said;
+}
+function speakUnpushed(slot, key) {
     switch (slot.kind) {
         case "chord":
-            return speakChord(slot.chord, key);
+            return speakChordSlot(slot, key);
         case "hold":
             return "hold";
         case "nc":
@@ -118,11 +134,24 @@ export function speakSlot(slot, key) {
             return `${GROUPS[slot.members.length] ?? `group of ${slot.members.length}`}: ${slot.members.map((m) => speakSlot(m, key)).join(", ")}`;
     }
 }
+/** "segno", "to coda", "dal segno al coda", "da capo al fine". */
+function speakDirection(d) {
+    if (d.kind !== "jump")
+        return d.kind;
+    return `${d.to === "start" ? "da capo" : "dal segno"}${d.al ? ` al ${d.al}` : ""}`;
+}
 /** "bar 9: G, hold, D, hold"; a fermata is held until cued. With `numerals`, each chord's degree comes first. */
 export function speakBar(barNumber, cell, numerals = false) {
     if (cell.kind === "fermata")
         return "fermata: hold until cued";
+    if (cell.kind === "direction")
+        return speakDirection(cell.direction);
+    if (cell.kind === "rehearsal")
+        return `rehearsal ${cell.label}`;
     const meter = cell.meter ? `, in ${cell.meter.n}/${cell.meter.d}` : "";
     const cut = cell.cut ? ", cut on this pass" : "";
-    return `bar${barNumber === null ? "" : ` ${barNumber}`}${meter}: ${cell.slots.map((s) => speakSlot(s, numerals ? cell.key : undefined)).join(", ")}${cut}`;
+    const words = (at) => (cell.words ?? []).filter((w) => w.at === at).map((w) => `“${w.text}”`);
+    const slots = cell.slots.map((s, i) => [...words(i), speakSlot(s, numerals ? cell.key : undefined)].join(" "));
+    const spoken = [...slots, ...words(cell.slots.length)].join(", ");
+    return `bar${barNumber === null ? "" : ` ${barNumber}`}${meter}: ${spoken}${cut}`;
 }

package/dist/styles.js

@@ -116,6 +116,21 @@ const css = `
 .bm-tuplet::after{border-left:none;margin-left:.3em}
 .bm-meter{display:inline-flex;flex-direction:column;align-items:center;align-self:center;font:700 ${em(SIZES.meter)}/.95 ${SANS};color:var(--bm-muted)}
 .bm-fermata-glyph{display:block;color:var(--bm-ink)}
+.bm-row>div.bm-direction{min-width:0;padding-inline:.35em;border-right:none;align-items:flex-start;color:var(--bm-ink)}
+.bm-sign{display:inline-block;vertical-align:middle}
+.bm-direction-words{font:italic ${em(SIZES.repeat)}/1.2 Georgia,serif;white-space:nowrap}
+.bm-row>div.bm-mark{min-width:0;padding-inline:.3em;border-right:none;align-items:flex-start}
+.bm-box{display:inline-block;padding:.05em .3em;border:.08em solid var(--bm-ink);border-radius:.15em;font:700 .85em/1.1 system-ui,sans-serif;color:var(--bm-ink)}
+.bm-worded{position:relative}
+.bm-marked{position:relative;display:inline-flex;align-items:baseline}
+.bm-push{font:700 .8em/1 system-ui,sans-serif;color:var(--bm-muted);margin-right:.08em}
+.bm-artic{position:absolute;left:50%;top:-.95em;transform:translateX(-50%);font:700 .7em/1 system-ui,sans-serif;color:var(--bm-ink)}
+.bm-marked[data-push]>.bm-artic{left:calc(50% + .25em)}
+.bm-words{position:absolute;left:0;top:-1.05em;font:italic .62em/1 Georgia,serif;color:var(--bm-muted);white-space:nowrap}
+.bm-bar>.bm-words-end{left:auto;right:.5em;top:.15em}
+.bm-bar[data-ending]::after{content:attr(data-ending);position:absolute;left:.45em;top:.2em;font:italic .75em/1 Georgia,serif;color:var(--bm-muted)}
+.bm-ending>.bm-bar{border-top:.06em solid var(--bm-muted)}
+.bm-ending>.bm-bar[data-ending]{box-shadow:inset .06em 0 var(--bm-muted)}
 .bm-bar[data-tempo-change]::before{content:"";position:absolute;inset:.15em 0 auto;border-top:.08em dashed var(--barmark-directive,var(--bm-muted))}
 .bm-bar[data-cut]{outline:.08em dashed var(--bm-muted);outline-offset:-.25em}
 .bm-cut{position:absolute;top:.3em;right:.45em;font:${em(SIZES.cut)}/1 ${SANS};color:var(--bm-muted)}

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import type { ChartDiagnostic, Directives, Key, Meter, Repeat, Slot } from "barmark";
+import type { ChartDiagnostic, Direction, Directives, Key, Meter, Repeat, Slot, Words } from "barmark";
 export type LayoutOptions = {
     rehearsalLetters?: boolean;
 };
@@ -30,6 +30,8 @@ export type BlockItem = {
     opens: boolean;
     closes: boolean;
     repeat: Repeat;
+    /** The passes an ending plays on; null for any other row. */
+    ending: number[] | null;
     cells: CellModel[];
 }
 /** `note` marks a `###` line, whose text is given without the marks. */
@@ -55,6 +57,18 @@ export type CellModel = {
     tempoChange?: "rit" | "accel";
     /** The key the bar is played in, when the chart names one. */
     key?: Key;
+    /** Words written on the bar (barmark's grammar 2.6), each before slot `at`. */
+    words?: Words[];
 } | {
     kind: "fermata";
+}
+/** A segno, coda or jump between bars (barmark's grammar 5.2). */
+ | {
+    kind: "direction";
+    direction: Direction;
+}
+/** A rehearsal mark on the bar after it (barmark's grammar 2.5). */
+ | {
+    kind: "rehearsal";
+    label: string;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@barmark/render",
-	"version": "0.7.3",
+	"version": "0.9.0",
 	"description": "Render barmark chord charts as a clean, accessible bar grid: HTML with Declarative Shadow DOM, or the <barmark-chart> web component.",
 	"type": "module",
 	"exports": {
@@ -47,7 +47,7 @@
 		"url": "https://github.com/kevinpeckham/barmark/issues"
 	},
 	"dependencies": {
-		"barmark": "^0.10.0"
+		"barmark": "^0.12.0"
 	},
 	"scripts": {
 		"build": "rm -rf dist && tsc -p tsconfig.build.json",