@barmark/render 0.8.0 → 0.9.1

package/CHANGELOG.md

@@ -6,6 +6,35 @@ package uses [semantic versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.9.1] - 2026-11-03
+
+### Fixed
+
+- **Bar numbers count the bars as written** (issue #92), each once, as a
+  band counts them and as `PlayedBar.written` gives them. Before, the
+  margin counted played bars, so a second ending or anything after a
+  repeat or a jump numbered past the printed score. A replayed section
+  now shows the numbers it was written with; the coda after a
+  `D.S. al Coda`, and bars after an open repeat, are numbered instead
+  of left blank. Screen readers hear the same numbers.
+
+## [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.
@@ -239,7 +268,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.8.0...HEAD
+[Unreleased]: https://github.com/kevinpeckham/barmark/compare/render-v0.9.1...HEAD
+[0.9.1]: https://github.com/kevinpeckham/barmark/compare/render-v0.9.0...render-v0.9.1
+[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

package/README.md

@@ -178,8 +178,10 @@ At the default size chords are 16px and no label is under 12px.
 
 Chords appear in their canonical form whatever the author typed (`Cø`
 shows as Cm⁷(♭5)). `%` is drawn as the bar it copies; a replayed section
-is drawn in full with its own bar numbers, and its own lyrics replace the
-written section's. A line with an error shows as written, underlined,
+is drawn in full, and its own lyrics replace the written section's. Bar
+numbers count the bars as written, each once, as a band counts them: a
+repeat, an ending, a jump or a replay doesn't move them, so a replayed
+section shows the numbers it was written with. A line with an error shows as written, underlined,
 with its message. `layoutChart(text)` returns all of this as data, if
 you want to draw it yourself.
 

package/dist/html.js

@@ -97,13 +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 === "direction"
-    ? 1 + 0.55 * printDirection(cell.direction).length
-    : 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")
@@ -198,12 +205,36 @@ function cellHtml(cell, barNumber, marks, numerals) {
         : "";
     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 or a direction: a place between bars, drawn as its sign. */
+/** 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. */
@@ -218,7 +249,26 @@ function directionGlyph(d) {
 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

@@ -13,7 +13,6 @@ export function layoutChart(text, options = {}) {
         parse,
         source: text.split(/\r?\n/),
         errors: errorsByLine(parse),
-        lastKnownBar: lastKnownBar(parse.events),
         written: new Map(groups.flatMap((g) => (g.heading ? [[g.heading.line, g]] : []))),
     };
     const blocks = groups.map((g) => layoutGroup(g, ctx));
@@ -44,27 +43,6 @@ function errorsByLine(parse) {
     }
     return errors;
 }
-/** The count of bars up to the end of the first open repeat (all of them if there is none). */
-function lastKnownBar(events) {
-    let count = 0;
-    const countBars = (es) => {
-        for (const e of es) {
-            if (e.kind === "bar")
-                count++;
-            else if (e.kind === "open")
-                countBars(e.events);
-        }
-    };
-    for (const e of events) {
-        if (e.kind === "open") {
-            countBars(e.events);
-            return count;
-        }
-        if (e.kind === "bar")
-            count++;
-    }
-    return Number.POSITIVE_INFINITY;
-}
 /** The title line, and the directives before any other content, form the header. */
 function splitHeader(lines) {
     const header = {};
@@ -220,17 +198,17 @@ 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" && cell.kind !== "direction")
+        if (cell.kind === "slots" || cell.kind === "simile")
             bar++;
         if (model.kind === "slots")
             prev = model;
         cells.push(model);
     }
-    const firstIndex = played[0]?.index;
     return {
         kind: "row",
         line: l.line,
-        barNumber: firstIndex !== undefined && firstIndex <= ctx.lastKnownBar ? firstIndex : null,
+        // Numbered as written, as a band counts (issue #92): repeats, endings, jumps and replays don't move it.
+        barNumber: (played[0] ?? written[0])?.written ?? null,
         opens: l.opens,
         closes: l.closes,
         repeat: l.repeat,
@@ -242,16 +220,23 @@ function layoutRow(l, played, previous, ctx) {
 function layoutCell(cell, played, previous) {
     if (cell.kind === "fermata")
         return { kind: "fermata" };
-    if (cell.kind === "direction")
+    if (cell.kind === "direction" || cell.kind === "rehearsal")
         return cell;
-    const from = cell.kind === "slots" ? cell : previous;
-    return withPlayed({
+    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

@@ -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":
@@ -130,7 +146,12 @@ export function speakBar(barNumber, cell, numerals = false) {
         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

@@ -119,6 +119,15 @@ const css = `
 .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)}

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import type { ChartDiagnostic, Direction, Directives, Key, Meter, Repeat, Slot } from "barmark";
+import type { ChartDiagnostic, Direction, Directives, Key, Meter, Repeat, Slot, Words } from "barmark";
 export type LayoutOptions = {
     rehearsalLetters?: boolean;
 };
@@ -25,7 +25,7 @@ export type SectionBlock = {
 export type BlockItem = {
     kind: "row";
     line: number;
-    /** The play-order number of the row's first bar on its first pass. */
+    /** The written number of the row's first bar (`PlayedBar.written`); a replay shows its section's numbers. Null for a row with no bar. */
     barNumber: number | null;
     opens: boolean;
     closes: boolean;
@@ -57,6 +57,8 @@ 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";
 }
@@ -64,4 +66,9 @@ export type CellModel = {
  | {
     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.8.0",
+	"version": "0.9.1",
 	"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.11.0"
+		"barmark": "^0.12.0"
 	},
 	"scripts": {
 		"build": "rm -rf dist && tsc -p tsconfig.build.json",