@sudobility/music_drawing 0.0.1

package/dist/note-color.js

@@ -0,0 +1,81 @@
+/**
+ * Highest precedence first. `playing` wins so playback stays followable even
+ * over a selection; `regenerated` beats `selected` so a just-regenerated
+ * passage stays visible while it is still selected.
+ *
+ * Pressing play clears the selection, so `playing` and `selected` do not
+ * normally coexist — this ordering only resolves the case where the user
+ * selects notes while playback is already running.
+ */
+const PRECEDENCE = [
+    'playing',
+    'regenerated',
+    'selected',
+    'normal',
+];
+/**
+ * The role to draw a VexFlow note with, given every domain event id it
+ * represents (>1 for a chord, or for one segment of a duration-decomposed
+ * long note). Ids absent from `noteColors` count as `normal`.
+ */
+export function resolveNoteColorRole(eventIds, noteColors) {
+    if (!noteColors || noteColors.size === 0)
+        return 'normal';
+    let best = PRECEDENCE.length - 1;
+    for (const eventId of eventIds) {
+        const role = noteColors.get(eventId);
+        if (!role)
+            continue;
+        const rank = PRECEDENCE.indexOf(role);
+        if (rank !== -1 && rank < best)
+            best = rank;
+    }
+    return PRECEDENCE[best];
+}
+/**
+ * The non-color half of a note's state cue (spec §27: "do not rely on color
+ * alone"). The old highlight overlay carried this with solid/dashed/dotted
+ * stroke patterns; those went away with the rectangles, so the weight of the
+ * glyph carries it now — a thicker `lineWidth` on stems, flags and beams.
+ *
+ * Deliberately NOT a shadow. An earlier version added `shadowBlur` so the cue
+ * would reach a notehead too (a filled glyph, which no stroke width can
+ * thicken). Canvas shadows force the rasterizer down a separate blur pass per
+ * draw, and this is applied to precisely the notes that change most often —
+ * every note-on and note-off during playback, on the thread Tone.js schedules
+ * from. Playback hesitated. The cue is worth less than smooth audio.
+ *
+ * The cost of that trade: a *stemless* whole note now has color as its only
+ * cue. Every other note keeps the stroke-weight channel, and the selection
+ * summary in the status bar and screen-reader text still names the state.
+ *
+ * One emphasis level for every non-normal state rather than three: the
+ * perceptually important distinction is "is this note affected" versus "is it
+ * not". `selected` and `regenerated` are mutually exclusive anyway
+ * (`regenerated` is a property of the whole selection), and `playing` is
+ * transient and accompanied by the moving caret.
+ */
+export function noteEmphasisFor(role) {
+    return { lineWidth: role === 'normal' ? 1 : 2.5 };
+}
+/**
+ * The theme color a role draws in.
+ *
+ * Only `normal` varies by track. A selected, regenerated or playing note keeps
+ * its state color wherever it is: those states are the reason to look at the
+ * note, and cmd-shift-click selects across every track, so dimming a selection
+ * because it is not on the active track would hide what the user just did.
+ */
+export function noteColorFor(role, theme, onActiveTrack = true) {
+    switch (role) {
+        case 'playing':
+            return theme.notePlaying;
+        case 'regenerated':
+            return theme.noteRegenerated;
+        case 'selected':
+            return theme.noteSelected;
+        case 'normal':
+            return onActiveTrack ? theme.noteNormal : theme.noteInactive;
+    }
+}
+//# sourceMappingURL=note-color.js.map

package/dist/note-color.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"note-color.js","sourceRoot":"","sources":["../src/note-color.ts"],"names":[],"mappings":"AAOA;;;;;;;;GAQG;AACH,MAAM,UAAU,GAA6B;IAC3C,SAAS;IACT,aAAa;IACb,UAAU;IACV,QAAQ;CACT,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAClC,QAA2B,EAC3B,UAA0D;IAE1D,IAAI,CAAC,UAAU,IAAI,UAAU,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,QAAQ,CAAC;IAC1D,IAAI,IAAI,GAAG,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC;IACjC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,IAAI,GAAG,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACrC,IAAI,CAAC,IAAI;YAAE,SAAS;QACpB,MAAM,IAAI,GAAG,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACtC,IAAI,IAAI,KAAK,CAAC,CAAC,IAAI,IAAI,GAAG,IAAI;YAAE,IAAI,GAAG,IAAI,CAAC;IAC9C,CAAC;IACD,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,eAAe,CAAC,IAAmB;IACjD,OAAO,EAAE,SAAS,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;AACpD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAC1B,IAAmB,EACnB,KAAkB,EAClB,aAAa,GAAG,IAAI;IAEpB,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,SAAS;YACZ,OAAO,KAAK,CAAC,WAAW,CAAC;QAC3B,KAAK,aAAa;YAChB,OAAO,KAAK,CAAC,eAAe,CAAC;QAC/B,KAAK,UAAU;YACb,OAAO,KAAK,CAAC,YAAY,CAAC;QAC5B,KAAK,QAAQ;YACX,OAAO,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC;IACjE,CAAC;AACH,CAAC"}

package/dist/pagination.d.ts

@@ -0,0 +1,57 @@
+import type { Track } from '@sudobility/music_types';
+import type { LayoutPlan } from './layout.js';
+export type PaperSize = 'a4' | 'letter' | 'legal';
+export type PaperOrientation = 'portrait' | 'landscape';
+/** Portrait dimensions in millimetres; landscape swaps them. */
+export declare const PAPER_DIMENSIONS_MM: Record<PaperSize, {
+    width: number;
+    height: number;
+}>;
+/**
+ * The margin the printed page reserves on every side.
+ *
+ * The single source: the `@page` rule is emitted from this, and the height
+ * below is computed from it. Two numbers here means pagination that silently
+ * disagrees with what the printer does.
+ */
+export declare const PAGE_MARGIN_MM = 12;
+/**
+ * How much height `logicalWidth` units of layout buy on this paper.
+ *
+ * Paper only ever enters as a ratio: the layout is computed at a fixed logical
+ * width and each page is displayed at the paper's printable width, so the
+ * scale is uniform and millimetres cancel.
+ */
+export declare function usablePageHeight(paper: PaperSize, orientation: PaperOrientation, logicalWidth: number, marginMm?: number): number;
+/** The systems printed on one page, by index into `LayoutPlan.systems`. */
+export type PrintPage = {
+    systemIndices: number[];
+};
+/**
+ * How many systems earlier than the greedy break a page may end.
+ *
+ * Two. Every system pulled back makes the part longer, and a turn bought three
+ * systems early costs more paper than it saves the player.
+ */
+export declare const MAX_PULL_BACK = 2;
+/**
+ * Bars `track`'s player has free across a turn taken after system
+ * `lastSystemIndex`.
+ *
+ * They may begin turning once their last note on the page has finished and
+ * must be reading again by their first on the next, so both sides count.
+ * Zero after the last system: there is no turn there.
+ */
+export declare function turnFreeBars(plan: LayoutPlan, track: Track, lastSystemIndex: number): number;
+/**
+ * Which systems go on which page.
+ *
+ * Greedy: take systems in order while they fit. A system taller than the page
+ * still gets its own page — it overflows, which is better than dropping it and
+ * better than never advancing.
+ *
+ * With `turnTrack`, each break is then pulled back up to `MAX_PULL_BACK`
+ * systems if that buys its player a better page turn.
+ */
+export declare function paginate(plan: LayoutPlan, pageHeight: number, turnTrack?: Track): PrintPage[];
+//# sourceMappingURL=pagination.d.ts.map

package/dist/pagination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../src/pagination.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAW,KAAK,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAgB,MAAM,aAAa,CAAC;AAE5D,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,QAAQ,GAAG,OAAO,CAAC;AAClD,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,WAAW,CAAC;AAExD,gEAAgE;AAChE,eAAO,MAAM,mBAAmB,EAAE,MAAM,CACtC,SAAS,EACT;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAKlC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,KAAK,CAAC;AAEjC;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,SAAS,EAChB,WAAW,EAAE,gBAAgB,EAC7B,YAAY,EAAE,MAAM,EACpB,QAAQ,GAAE,MAAuB,GAChC,MAAM,CAOR;AAED,2EAA2E;AAC3E,MAAM,MAAM,SAAS,GAAG;IAAE,aAAa,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAOpD;;;;;GAKG;AACH,eAAO,MAAM,aAAa,IAAI,CAAC;AA6B/B;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,UAAU,EAChB,KAAK,EAAE,KAAK,EACZ,eAAe,EAAE,MAAM,GACtB,MAAM,CAQR;AA8BD;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CACtB,IAAI,EAAE,UAAU,EAChB,UAAU,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,KAAK,GAChB,SAAS,EAAE,CA+Bb"}

package/dist/pagination.js

@@ -0,0 +1,152 @@
+/**
+ * Which systems go on which page, and where a page turn should fall.
+ *
+ * Pure over a `LayoutPlan` — no DOM, no canvas, no React — so the decisions
+ * about paper and page turns are testable without printing anything.
+ *
+ * Feature 1 left pagination to the browser: every system was a block with
+ * `break-inside: avoid`, and the browser fitted as many as the paper allowed.
+ * That has no opinion about *where* the break falls, and a turn in the middle
+ * of a phrase costs a real player a hand.
+ */
+import { isSilentMeasure } from '@sudobility/music_types';
+/** Portrait dimensions in millimetres; landscape swaps them. */
+export const PAPER_DIMENSIONS_MM = {
+    a4: { width: 210, height: 297 },
+    letter: { width: 215.9, height: 279.4 }, // 8.5in x 11in
+    legal: { width: 215.9, height: 355.6 }, // 8.5in x 14in
+};
+/**
+ * The margin the printed page reserves on every side.
+ *
+ * The single source: the `@page` rule is emitted from this, and the height
+ * below is computed from it. Two numbers here means pagination that silently
+ * disagrees with what the printer does.
+ */
+export const PAGE_MARGIN_MM = 12;
+/**
+ * How much height `logicalWidth` units of layout buy on this paper.
+ *
+ * Paper only ever enters as a ratio: the layout is computed at a fixed logical
+ * width and each page is displayed at the paper's printable width, so the
+ * scale is uniform and millimetres cancel.
+ */
+export function usablePageHeight(paper, orientation, logicalWidth, marginMm = PAGE_MARGIN_MM) {
+    const { width, height } = PAPER_DIMENSIONS_MM[paper];
+    const shortSide = orientation === 'portrait' ? width : height;
+    const longSide = orientation === 'portrait' ? height : width;
+    return ((logicalWidth * (longSide - 2 * marginMm)) / (shortSide - 2 * marginMm));
+}
+/** A system's full printed height, measure-number band included. */
+function systemHeight(system) {
+    return system.yBottom - system.gutterTop;
+}
+/**
+ * How many systems earlier than the greedy break a page may end.
+ *
+ * Two. Every system pulled back makes the part longer, and a turn bought three
+ * systems early costs more paper than it saves the player.
+ */
+export const MAX_PULL_BACK = 2;
+/** How many bars `measure` stands for — a multi-measure rest stands for its count. */
+function barSpan(measure) {
+    return measure.multiMeasureRestCount ?? 1;
+}
+/** Silent bars at the end of `indices`. */
+function trailingFreeBars(track, indices) {
+    let bars = 0;
+    for (let i = indices.length - 1; i >= 0; i -= 1) {
+        const measure = track.measures[indices[i]];
+        if (!measure || !isSilentMeasure(measure))
+            break;
+        bars += barSpan(measure);
+    }
+    return bars;
+}
+/** Silent bars at the start of `indices`. */
+function leadingFreeBars(track, indices) {
+    let bars = 0;
+    for (const index of indices) {
+        const measure = track.measures[index];
+        if (!measure || !isSilentMeasure(measure))
+            break;
+        bars += barSpan(measure);
+    }
+    return bars;
+}
+/**
+ * Bars `track`'s player has free across a turn taken after system
+ * `lastSystemIndex`.
+ *
+ * They may begin turning once their last note on the page has finished and
+ * must be reading again by their first on the next, so both sides count.
+ * Zero after the last system: there is no turn there.
+ */
+export function turnFreeBars(plan, track, lastSystemIndex) {
+    const last = plan.systems[lastSystemIndex];
+    const next = plan.systems[lastSystemIndex + 1];
+    if (!last || !next)
+        return 0;
+    return (trailingFreeBars(track, last.measureIndices) +
+        leadingFreeBars(track, next.measureIndices));
+}
+/**
+ * The end index (exclusive) that buys the best turn, at most `MAX_PULL_BACK`
+ * systems back from `greedyEnd` and never emptying the page.
+ *
+ * Searched downward with a strict improvement test, so a tie keeps the fullest
+ * page — pulling back with nothing to show for it is pure loss.
+ */
+function bestTurn(plan, track, start, greedyEnd) {
+    let best = greedyEnd;
+    let bestScore = turnFreeBars(plan, track, greedyEnd - 1);
+    const earliest = Math.max(start + 1, greedyEnd - MAX_PULL_BACK);
+    for (let end = greedyEnd - 1; end >= earliest; end -= 1) {
+        const score = turnFreeBars(plan, track, end - 1);
+        if (score > bestScore) {
+            best = end;
+            bestScore = score;
+        }
+    }
+    return best;
+}
+/**
+ * Which systems go on which page.
+ *
+ * Greedy: take systems in order while they fit. A system taller than the page
+ * still gets its own page — it overflows, which is better than dropping it and
+ * better than never advancing.
+ *
+ * With `turnTrack`, each break is then pulled back up to `MAX_PULL_BACK`
+ * systems if that buys its player a better page turn.
+ */
+export function paginate(plan, pageHeight, turnTrack) {
+    const pages = [];
+    let start = 0;
+    while (start < plan.systems.length) {
+        let end = start;
+        let used = 0;
+        while (end < plan.systems.length) {
+            const height = systemHeight(plan.systems[end]);
+            // `end > start` is what guarantees progress: the first system on a page
+            // always goes on it, however tall it is.
+            if (end > start && used + height > pageHeight)
+                break;
+            used += height;
+            end += 1;
+        }
+        // Only worth doing when there *is* a turn: the last page ends the piece.
+        // A whole-score print passes no track — "the player rests" means nothing
+        // when a dozen staves share the page, and a conductor turns at will.
+        if (turnTrack && end < plan.systems.length) {
+            end = bestTurn(plan, turnTrack, start, end);
+        }
+        const systemIndices = [];
+        for (let i = start; i < end; i += 1)
+            systemIndices.push(i);
+        pages.push({ systemIndices });
+        start = end;
+    }
+    return pages;
+}
+//# sourceMappingURL=pagination.js.map

package/dist/pagination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../src/pagination.ts"],"names":[],"mappings":"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"}

package/dist/percussion.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Where a drum sits on the staff, and what its notehead looks like.
+ *
+ * A percussion track's "pitch" is not a pitch — it is which drum was struck.
+ * General MIDI puts the kick at 35/36 and the snare at 38, which as pitches
+ * are B1 and D2: drawn literally they land six or seven ledger lines below a
+ * treble staff, with stems long enough to reach into the next track's row.
+ * That is what a drum part looked like here.
+ *
+ * Percussion notation answers a different question — not "how high is it" but
+ * "which instrument is it" — so each drum gets a fixed line or space and, for
+ * anything struck with a stick or shaken rather than hit like a drum, a cross
+ * notehead. The positions below are the common drum-set convention: kick in
+ * the bottom space, snare in the third space, hi-hat above the top line, toms
+ * descending between them, cymbals crossed at the top.
+ *
+ * The keys are VexFlow's `note/octave/notehead` form, and the octaves in them
+ * are staff positions read as if in treble clef, not sounding pitches. Nothing
+ * outside this file should read them as pitch.
+ */
+/** Whether `midi` is struck with a foot rather than a hand. */
+export declare function isFootDrum(midi: number): boolean;
+/**
+ * The stem base offsets that join a stem to `keys`, or `null` when they need
+ * none.
+ *
+ * Only when *every* head in the group is a cross: the stem attaches to one
+ * outer head, and in a mixed chord that may be an ordinary one, which already
+ * meets its stem correctly.
+ */
+export declare function crossHeadStemOffsets(keys: string[]): {
+    stem_up_y_base_offset: number;
+    stem_down_y_base_offset: number;
+} | null;
+/** The VexFlow key for General MIDI percussion note `midi`. */
+export declare function percussionVexKey(midi: number): string;
+/**
+ * Whether `midi` has a staff position of its own.
+ *
+ * Exposed because `UNMAPPED` is `b/4`, which is also a real position — Low Tom
+ * sits there — so the return of `percussionVexKey` cannot be used to tell a
+ * drum this table knows from one it does not. `gm-percussion.ts` pins its own
+ * coverage against this, since a drum in one and not the other is either drawn
+ * without a name or named without a place to draw it.
+ */
+export declare function hasPercussionMapping(midi: number): boolean;
+//# sourceMappingURL=percussion.d.ts.map

package/dist/percussion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"percussion.d.ts","sourceRoot":"","sources":["../src/percussion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAoGH,+DAA+D;AAC/D,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhD;AAyBD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EAAE,GACb;IAAE,qBAAqB,EAAE,MAAM,CAAC;IAAC,uBAAuB,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAM3E;AAED,+DAA+D;AAC/D,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE1D"}

package/dist/percussion.js

@@ -0,0 +1,172 @@
+/**
+ * Where a drum sits on the staff, and what its notehead looks like.
+ *
+ * A percussion track's "pitch" is not a pitch — it is which drum was struck.
+ * General MIDI puts the kick at 35/36 and the snare at 38, which as pitches
+ * are B1 and D2: drawn literally they land six or seven ledger lines below a
+ * treble staff, with stems long enough to reach into the next track's row.
+ * That is what a drum part looked like here.
+ *
+ * Percussion notation answers a different question — not "how high is it" but
+ * "which instrument is it" — so each drum gets a fixed line or space and, for
+ * anything struck with a stick or shaken rather than hit like a drum, a cross
+ * notehead. The positions below are the common drum-set convention: kick in
+ * the bottom space, snare in the third space, hi-hat above the top line, toms
+ * descending between them, cymbals crossed at the top.
+ *
+ * The keys are VexFlow's `note/octave/notehead` form, and the octaves in them
+ * are staff positions read as if in treble clef, not sounding pitches. Nothing
+ * outside this file should read them as pitch.
+ */
+/**
+ * Cross (`noteheadXBlack`): sticks, cymbals, shakers — anything that is not a
+ * drumhead.
+ */
+const X = 'x';
+/**
+ * Circled cross (`noteheadCircleX`): the standard "let it ring" mark, which is
+ * how an open hi-hat is told from a closed one.
+ *
+ * Verified against VexFlow's own codes rather than assumed: `x` and `x2` are
+ * both `noteheadXBlack`, `x3` is `noteheadCircleX`, and `ci` is
+ * `noteheadCircledBlack` — a filled head inside a circle, which means nothing
+ * here and is what open hi-hat was wrongly drawn with.
+ */
+const CIRCLE_X = 'x3';
+/** Diamond: bells and cups. */
+const DIAMOND = 'd';
+/** Triangle: the cowbell's usual mark. */
+const TRIANGLE = 'tu';
+/**
+ * General MIDI percussion (35-81) to staff position.
+ *
+ * Numbers outside this range are not General MIDI percussion; `percussionVexKey`
+ * keeps them on the middle line rather than inventing a position, so an
+ * unexpected note is visible and obviously unplaced instead of flying off the
+ * staff.
+ */
+const DRUM_MAP = {
+    35: 'f/4', // Acoustic Bass Drum
+    36: 'f/4', // Bass Drum 1
+    37: `c/5/${X}`, // Side Stick
+    38: 'c/5', // Acoustic Snare
+    39: `c/5/${X}`, // Hand Clap
+    40: 'c/5', // Electric Snare
+    41: 'g/4', // Low Floor Tom
+    42: `g/5/${X}`, // Closed Hi-Hat
+    43: 'a/4', // High Floor Tom
+    44: `d/4/${X}`, // Pedal Hi-Hat
+    45: 'b/4', // Low Tom
+    46: `g/5/${CIRCLE_X}`, // Open Hi-Hat
+    47: 'd/5', // Low-Mid Tom
+    48: 'e/5', // Hi-Mid Tom
+    49: `a/5/${X}`, // Crash Cymbal 1
+    50: 'f/5', // High Tom
+    51: `f/5/${X}`, // Ride Cymbal 1
+    52: `b/5/${CIRCLE_X}`, // Chinese Cymbal
+    53: `f/5/${DIAMOND}`, // Ride Bell
+    54: `d/5/${X}`, // Tambourine
+    55: `b/5/${X}`, // Splash Cymbal
+    56: `e/5/${TRIANGLE}`, // Cowbell
+    57: `a/5/${X}`, // Crash Cymbal 2
+    58: `b/4/${X}`, // Vibraslap
+    59: `f/5/${X}`, // Ride Cymbal 2
+    // 60-81 are hand and Latin percussion rather than kit pieces, so there is no
+    // drum-set convention to follow. They are spread over the staff by family,
+    // pitched pairs keeping high above low, so a part stays readable.
+    60: 'e/5', // Hi Bongo
+    61: 'c/5', // Low Bongo
+    62: 'd/5', // Mute Hi Conga
+    63: 'd/5', // Open Hi Conga
+    64: 'b/4', // Low Conga
+    65: 'e/5', // High Timbale
+    66: 'c/5', // Low Timbale
+    67: `f/5/${X}`, // High Agogo
+    68: `d/5/${X}`, // Low Agogo
+    69: `g/5/${X}`, // Cabasa
+    70: `g/5/${X}`, // Maracas
+    71: `a/5/${X}`, // Short Whistle
+    72: `a/5/${X}`, // Long Whistle
+    73: `f/5/${X}`, // Short Guiro
+    74: `f/5/${X}`, // Long Guiro
+    75: `e/5/${X}`, // Claves
+    76: `e/5/${X}`, // Hi Wood Block
+    77: `c/5/${X}`, // Low Wood Block
+    78: `d/5/${X}`, // Mute Cuica
+    79: `d/5/${X}`, // Open Cuica
+    80: `a/5/${X}`, // Mute Triangle
+    81: `a/5/${CIRCLE_X}`, // Open Triangle
+};
+/**
+ * The middle line — where anything unrecognised goes, so it stays on the staff.
+ *
+ * The staff runs from line 1 (bottom, E4) to line 5 (top, F5) in VexFlow's
+ * numbering; every mapping above stays within one ledger of that, and the
+ * pedal hi-hat is deliberately just below it, as convention has it.
+ */
+const UNMAPPED = 'b/4';
+/**
+ * The kit pieces played with the feet: both bass drums and the hi-hat pedal.
+ *
+ * They are stemmed downward against the hands, which is what lets a drum staff
+ * carry a whole kit on five lines and still be read at a glance.
+ */
+const FOOT_DRUMS = new Set([35, 36, 44]);
+/** Whether `midi` is struck with a foot rather than a hand. */
+export function isFootDrum(midi) {
+    return FOOT_DRUMS.has(midi);
+}
+/**
+ * How far a cross notehead's stem must reach into the glyph to join it.
+ *
+ * A stem meets a notehead at its right (or left) edge, halfway up. On an oval
+ * that is solid ink; on a cross it is the hollow middle, and the only ink at
+ * that edge is the two arm tips at the corners. VexFlow's default stops the
+ * stem four units short of even the halfway point, so it grazed the upper tip
+ * at a single point and read as a separate mark sitting above the note.
+ *
+ * Half a notehead — five units at the default glyph scale — runs the stem the
+ * full height of the glyph, bridging both arm tips, which is what reads as
+ * joined. Measured from the rendered SVG in both directions: +5 lands an
+ * up-stem exactly on the head's bottom edge and -5 lands a down-stem exactly
+ * on its top edge, while -9 and beyond overshoot past the glyph.
+ */
+const CROSS_STEM_OVERLAP = 5;
+/** Whether `key` (VexFlow `note/octave/head` form) draws as a cross. */
+function isCrossHead(key) {
+    const head = key.split('/')[2];
+    return head === X || head === CIRCLE_X;
+}
+/**
+ * The stem base offsets that join a stem to `keys`, or `null` when they need
+ * none.
+ *
+ * Only when *every* head in the group is a cross: the stem attaches to one
+ * outer head, and in a mixed chord that may be an ordinary one, which already
+ * meets its stem correctly.
+ */
+export function crossHeadStemOffsets(keys) {
+    if (keys.length === 0 || !keys.every(isCrossHead))
+        return null;
+    return {
+        stem_up_y_base_offset: CROSS_STEM_OVERLAP,
+        stem_down_y_base_offset: -CROSS_STEM_OVERLAP,
+    };
+}
+/** The VexFlow key for General MIDI percussion note `midi`. */
+export function percussionVexKey(midi) {
+    return DRUM_MAP[midi] ?? UNMAPPED;
+}
+/**
+ * Whether `midi` has a staff position of its own.
+ *
+ * Exposed because `UNMAPPED` is `b/4`, which is also a real position — Low Tom
+ * sits there — so the return of `percussionVexKey` cannot be used to tell a
+ * drum this table knows from one it does not. `gm-percussion.ts` pins its own
+ * coverage against this, since a drum in one and not the other is either drawn
+ * without a name or named without a place to draw it.
+ */
+export function hasPercussionMapping(midi) {
+    return midi in DRUM_MAP;
+}
+//# sourceMappingURL=percussion.js.map

package/dist/percussion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"percussion.js","sourceRoot":"","sources":["../src/percussion.ts"],"names":[],"mappings":"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"}

package/dist/playhead.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Playhead caret geometry: maps a playback tick to a vertical-line position
+ * on the notation canvas, and a canvas point back to a tick (click-to-seek).
+ * Pure functions over `LayoutPlan` (logical/unscaled units — callers
+ * multiply by zoom). Moved here from music_app's score-editor feature and
+ * re-based on the binary-search lookups so every call is O(log n) — part of
+ * the canvas renderer's "no O(score) interaction work" rule.
+ *
+ * The tick <-> x mapping interpolates linearly across each measure's stave
+ * box. VexFlow doesn't space notes perfectly linearly (and first-in-system
+ * measures spend their left edge on clef/key/time), so the caret is a close
+ * approximation rather than glyph-exact — the same trade every DAW-style
+ * ruler makes.
+ */
+import type { Score } from '@sudobility/music_types';
+import type { LayoutPlan } from './layout.js';
+export type CaretPosition = {
+    /** Logical x of the caret line. */
+    x: number;
+    /** Logical top/bottom of the system the tick falls in (the caret spans the whole system, all tracks). */
+    yTop: number;
+    yBottom: number;
+};
+/**
+ * Where the caret for `tick` sits on the canvas, or `null` when there is
+ * nothing to draw against (empty score / no layout). Ticks past the end of
+ * the score clamp to the final measure's right edge.
+ */
+export declare function caretPositionForTick(plan: LayoutPlan, score: Score, tick: number): CaretPosition | null;
+/**
+ * The tick a canvas click at logical `(x, y)` should seek to, or `null`
+ * when the point is in dead space between/outside systems. Horizontal
+ * positions left/right of a system's measures clamp to that system's
+ * first/last measure, so clicking the clef area seeks to the system start.
+ */
+export declare function tickForPoint(plan: LayoutPlan, score: Score, x: number, y: number): number | null;
+//# sourceMappingURL=playhead.d.ts.map

package/dist/playhead.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playhead.d.ts","sourceRoot":"","sources":["../src/playhead.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AAErD,OAAO,KAAK,EAAE,UAAU,EAAgB,MAAM,aAAa,CAAC;AAE5D,MAAM,MAAM,aAAa,GAAG;IAC1B,mCAAmC;IACnC,CAAC,EAAE,MAAM,CAAC;IACV,yGAAyG;IACzG,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AA2CF;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,UAAU,EAChB,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,MAAM,GACX,aAAa,GAAG,IAAI,CAsBtB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,UAAU,EAChB,KAAK,EAAE,KAAK,EACZ,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,GACR,MAAM,GAAG,IAAI,CAiBf"}