@sudobility/music_drawing 0.0.1

package/dist/display-timing.d.ts

@@ -0,0 +1,68 @@
+import type { MusicalEvent } from '@sudobility/music_types';
+/** Ticks per display grid step. At the usual 480 ppq this is 60. */
+export declare function displayGridTicks(ppq: number): number;
+/**
+ * One drawn tickable: the events that sound at this point, and how long it
+ * occupies the bar. A chord is several events in one group.
+ */
+export type DisplayGroup = {
+    /**
+     * The events sounding at this point. **Empty means a spacer**: time that has
+     * to be accounted for so the voice still sums to the bar, but that draws
+     * nothing. `buildVoiceContent` renders those as VexFlow `GhostNote`s.
+     */
+    events: MusicalEvent[];
+    /** Always a whole number of grid steps; the groups sum to the measure. */
+    durationTicks: number;
+};
+/**
+ * Where this voice's notes begin, snapped to the display grid.
+ *
+ * Exported for layout: the number of distinct onsets across a measure's tracks
+ * is the number of tick contexts VexFlow will build, and therefore what its
+ * minimum width is proportional to. Counting raw events instead over-allocated
+ * badly — a drum bar of 37 recorded hits draws as 16 tickables once
+ * near-simultaneous strikes are chorded, and it was being given width for 37.
+ */
+export declare function snappedOnsetTicks(events: MusicalEvent[], measureStartTick: number, measureDurationTicks: number, ppq: number): number[];
+/**
+ * Groups `events` (one voice of one measure, in ascending start order) into
+ * drawable tickables whose durations sum to exactly `measureDurationTicks`.
+ *
+ * `measureStartTick` is subtracted first, so callers pass absolute domain
+ * ticks and this works in measure-relative space throughout.
+ *
+ * Each group runs until the next one begins, which is what a single melodic
+ * line wants: the notes join up and the bar is accounted for with no spacers.
+ *
+ * Events that snap to the same grid step become one group — which is how a
+ * rolled chord recorded three ticks apart is drawn as the chord it is, rather
+ * than as three consecutive notes that between them overrun the bar.
+ */
+export declare function displayGroups(events: MusicalEvent[], measureStartTick: number, measureDurationTicks: number, ppq: number): DisplayGroup[];
+/**
+ * The same onsets, laid out for a drum staff: each hit runs to the next one,
+ * but never long enough for its notehead to turn hollow.
+ *
+ * A kit part is not a melodic line, and a drum's recorded length is an
+ * artifact — a struck cymbal rings however long the MIDI note says. What
+ * matters is the rhythmic slot, so a hit runs to the next hit and the leftover
+ * becomes spacers.
+ *
+ * The cap is what makes it readable. Stretching a kick to reach the next kick
+ * two beats later would draw it as a half note, and half notes are hollow: a
+ * kick on beats one and three would come out as two open noteheads, which
+ * reads as a different instruction entirely. A quarter is the longest value
+ * that is still filled and still obviously a hit.
+ *
+ * Using each hit's own recorded length instead does not work: drum hits are
+ * recorded a few ticks long, so every one became the shortest drawable note
+ * followed by a spacer — and spacers break beam groups, which turned a running
+ * hi-hat into a row of flagged thirty-seconds.
+ *
+ * Spacers rather than rests: with hands and feet on one staff, a rest drawn in
+ * the feet voice under a running hi-hat is clutter that says nothing a reader
+ * needs. Drum charts routinely leave it out.
+ */
+export declare function drumDisplayGroups(events: MusicalEvent[], measureStartTick: number, measureDurationTicks: number, ppq: number): DisplayGroup[];
+//# sourceMappingURL=display-timing.d.ts.map

package/dist/display-timing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"display-timing.d.ts","sourceRoot":"","sources":["../src/display-timing.ts"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAoB5D,oEAAoE;AACpE,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB;;;;OAIG;IACH,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,0EAA0E;IAC1E,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,YAAY,EAAE,EACtB,gBAAgB,EAAE,MAAM,EACxB,oBAAoB,EAAE,MAAM,EAC5B,GAAG,EAAE,MAAM,GACV,MAAM,EAAE,CAKV;AA+DD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,YAAY,EAAE,EACtB,gBAAgB,EAAE,MAAM,EACxB,oBAAoB,EAAE,MAAM,EAC5B,GAAG,EAAE,MAAM,GACV,YAAY,EAAE,CAahB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,YAAY,EAAE,EACtB,gBAAgB,EAAE,MAAM,EACxB,oBAAoB,EAAE,MAAM,EAC5B,GAAG,EAAE,MAAM,GACV,YAAY,EAAE,CA8BhB"}

package/dist/display-timing.js

@@ -0,0 +1,192 @@
+/**
+ * Turning a voice's recorded timing into timing that can actually be notated.
+ *
+ * A recorded performance does not land on note values. This score has onsets
+ * at ticks 0, 3, 233, 355, 1113 — and there is no such thing as a 233-tick
+ * note. `ticksToVexDuration` therefore rounds every duration to the nearest
+ * value it *can* draw, and those roundings accumulate: one voice of a 1920-tick
+ * bar came out notated as 3360 ticks, and five voices of another bar each
+ * drifted by a different amount.
+ *
+ * That is not merely cosmetic. VexFlow positions notes by accumulating each
+ * voice's notated durations, so voices that disagree about how long the bar is
+ * end up on different timelines: the same tick drew at x=407 on one stave and
+ * x=599 on another, and voices whose arithmetic happened to come out short were
+ * squeezed into the left third of the bar while the longest one filled it.
+ *
+ * The fix is to decide display timing *before* anything is rounded. Onsets snap
+ * to a grid, each group runs until the next one starts, and the last runs to the
+ * barline. Two properties follow, and they are the whole point:
+ *
+ *   - every duration is a whole number of grid steps, which
+ *     `decomposeDuration` represents exactly (verified across every multiple up
+ *     to a full bar), so nothing rounds and nothing drifts; and
+ *   - the durations sum to exactly the bar, for every voice, so every stave
+ *     shares one timeline.
+ *
+ * A score that was already quantized passes through unchanged: its onsets are
+ * already on the grid, and a gap-filled voice's durations already are the gaps.
+ * So this only ever moves notes that could not have been drawn correctly.
+ */
+import { isNoteEvent } from '@sudobility/music_types';
+/**
+ * The display grid, as a divisor of the quarter note: 8 gives a 1/32 note.
+ *
+ * Not a free parameter. `decomposeDuration` must represent every multiple of
+ * the grid exactly or the drift this module exists to remove comes straight
+ * back, and 1/32 is the finest grid for which that holds — at 1/64 twenty-one
+ * of the sixty-four multiples in a 4/4 bar cannot be written, and finer grids
+ * are worse. Triplets are already approximated here (nothing in this adapter
+ * draws tuplets), so the grid costs them nothing they had.
+ */
+const GRID_DIVISOR = 8;
+/**
+ * The longest note value that still draws a filled notehead, in quarters.
+ * A half note is hollow, and a hollow drum hit reads as the wrong instruction.
+ */
+const LONGEST_FILLED_QUARTERS = 1;
+/** Ticks per display grid step. At the usual 480 ppq this is 60. */
+export function displayGridTicks(ppq) {
+    return Math.max(1, Math.round(ppq / GRID_DIVISOR));
+}
+/**
+ * Where this voice's notes begin, snapped to the display grid.
+ *
+ * Exported for layout: the number of distinct onsets across a measure's tracks
+ * is the number of tick contexts VexFlow will build, and therefore what its
+ * minimum width is proportional to. Counting raw events instead over-allocated
+ * badly — a drum bar of 37 recorded hits draws as 16 tickables once
+ * near-simultaneous strikes are chorded, and it was being given width for 37.
+ */
+export function snappedOnsetTicks(events, measureStartTick, measureDurationTicks, ppq) {
+    if (events.length === 0 || measureDurationTicks <= 0)
+        return [];
+    return snappedOnsets(events, measureStartTick, measureDurationTicks, ppq).map(o => o.start);
+}
+/**
+ * The events of one voice, grouped onto snapped onsets and sorted.
+ *
+ * Shared by both layouts below so they cannot disagree about where a note
+ * begins — only about how long it is drawn.
+ */
+function snappedOnsets(events, measureStartTick, measureDurationTicks, ppq) {
+    const grid = displayGridTicks(ppq);
+    // An onset that rounds up to the barline is the next bar's note recorded a
+    // few ticks early, not an onset in this one. This score has such a note at
+    // tick 1915 of a 1920-tick bar. Giving it its own step would open a tick
+    // context one grid step before the barline, and VexFlow spends width on a
+    // context in proportion to it *being* one, not to how long it lasts: that
+    // sliver took a fifth of the bar, squeezing the sixteen real notes into 80%
+    // of the width and leaving what looked like a gap before the barline.
+    //
+    // So it joins the last real onset instead. Only onsets that round to the
+    // barline are touched — a genuine note a grid step before it rounds to its
+    // own step and keeps it.
+    const atBarline = [];
+    const byStart = new Map();
+    for (const event of events) {
+        const snapped = Math.max(0, Math.round((event.startTick - measureStartTick) / grid) * grid);
+        if (snapped >= measureDurationTicks) {
+            atBarline.push(event);
+            continue;
+        }
+        const at = byStart.get(snapped);
+        if (at)
+            at.push(event);
+        else
+            byStart.set(snapped, [event]);
+    }
+    for (const event of atBarline) {
+        const last = byStart.size > 0 ? Math.max(...byStart.keys()) : 0;
+        const at = byStart.get(last);
+        if (at)
+            at.push(event);
+        else
+            byStart.set(last, [event]);
+    }
+    return ([...byStart.keys()]
+        .sort((a, b) => a - b)
+        // A rest that snapped onto a note's step would draw a rest through a
+        // sounding note, so notes win their step and the rest simply vanishes —
+        // it was silence that turned out to be shorter than the grid.
+        // `?? []` rather than `!`: the keys come from this very map, so the
+        // lookup cannot miss — and an empty group is a harmless answer if it
+        // ever did, where an assertion would be a crash.
+        .map(start => ({ start, events: preferNotes(byStart.get(start) ?? []) })));
+}
+/**
+ * Groups `events` (one voice of one measure, in ascending start order) into
+ * drawable tickables whose durations sum to exactly `measureDurationTicks`.
+ *
+ * `measureStartTick` is subtracted first, so callers pass absolute domain
+ * ticks and this works in measure-relative space throughout.
+ *
+ * Each group runs until the next one begins, which is what a single melodic
+ * line wants: the notes join up and the bar is accounted for with no spacers.
+ *
+ * Events that snap to the same grid step become one group — which is how a
+ * rolled chord recorded three ticks apart is drawn as the chord it is, rather
+ * than as three consecutive notes that between them overrun the bar.
+ */
+export function displayGroups(events, measureStartTick, measureDurationTicks, ppq) {
+    if (events.length === 0 || measureDurationTicks <= 0)
+        return [];
+    const onsets = snappedOnsets(events, measureStartTick, measureDurationTicks, ppq);
+    return onsets.map((onset, index) => ({
+        events: onset.events,
+        durationTicks: (onsets[index + 1]?.start ?? measureDurationTicks) - onset.start,
+    }));
+}
+/**
+ * The same onsets, laid out for a drum staff: each hit runs to the next one,
+ * but never long enough for its notehead to turn hollow.
+ *
+ * A kit part is not a melodic line, and a drum's recorded length is an
+ * artifact — a struck cymbal rings however long the MIDI note says. What
+ * matters is the rhythmic slot, so a hit runs to the next hit and the leftover
+ * becomes spacers.
+ *
+ * The cap is what makes it readable. Stretching a kick to reach the next kick
+ * two beats later would draw it as a half note, and half notes are hollow: a
+ * kick on beats one and three would come out as two open noteheads, which
+ * reads as a different instruction entirely. A quarter is the longest value
+ * that is still filled and still obviously a hit.
+ *
+ * Using each hit's own recorded length instead does not work: drum hits are
+ * recorded a few ticks long, so every one became the shortest drawable note
+ * followed by a spacer — and spacers break beam groups, which turned a running
+ * hi-hat into a row of flagged thirty-seconds.
+ *
+ * Spacers rather than rests: with hands and feet on one staff, a rest drawn in
+ * the feet voice under a running hi-hat is clutter that says nothing a reader
+ * needs. Drum charts routinely leave it out.
+ */
+export function drumDisplayGroups(events, measureStartTick, measureDurationTicks, ppq) {
+    if (events.length === 0 || measureDurationTicks <= 0)
+        return [];
+    const onsets = snappedOnsets(events, measureStartTick, measureDurationTicks, ppq);
+    const groups = [];
+    // Time before the first hit still has to be accounted for, or the voice
+    // would be short and every stave would disagree about the bar's length.
+    if (onsets[0].start > 0)
+        groups.push({ events: [], durationTicks: onsets[0].start });
+    onsets.forEach((onset, index) => {
+        const until = onsets[index + 1]?.start ?? measureDurationTicks;
+        const available = until - onset.start;
+        // The cap is about noteheads, so it applies to hits only. A rest has no
+        // head to turn hollow and must span its whole silence: capped, a bar of
+        // silence drew a quarter rest with the remaining three beats blank.
+        const sounded = onset.events.some(isNoteEvent)
+            ? Math.min(available, LONGEST_FILLED_QUARTERS * ppq)
+            : available;
+        groups.push({ events: onset.events, durationTicks: sounded });
+        if (available > sounded)
+            groups.push({ events: [], durationTicks: available - sounded });
+    });
+    return groups;
+}
+function preferNotes(events) {
+    const notes = events.filter(isNoteEvent);
+    return notes.length > 0 ? notes : events;
+}
+//# sourceMappingURL=display-timing.js.map

package/dist/display-timing.js.map

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

package/dist/icon-canvas.d.ts

@@ -0,0 +1,12 @@
+import type { InstrumentIconArt } from '@sudobility/music_types';
+/**
+ * Strokes `art` in the current `strokeStyle`, scaled into a `size`-square box
+ * whose top-left corner is (`x`, `y`).
+ *
+ * One `beginPath`/`stroke` pair for the whole icon: the shapes are all the same
+ * colour and weight, so there is nothing to gain from stroking them separately.
+ * `save`/`restore` bracket the transform, so the caller's — the gutter's pinned,
+ * zoom-and-DPR-scaled one — survives.
+ */
+export declare function strokeInstrumentIcon(ctx: CanvasRenderingContext2D, art: InstrumentIconArt, x: number, y: number, size: number): void;
+//# sourceMappingURL=icon-canvas.d.ts.map

package/dist/icon-canvas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"icon-canvas.d.ts","sourceRoot":"","sources":["../src/icon-canvas.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAa,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAuC5E;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,wBAAwB,EAC7B,GAAG,EAAE,iBAAiB,EACtB,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,IAAI,EAAE,MAAM,GACX,IAAI,CAiBN"}

package/dist/icon-canvas.js

@@ -0,0 +1,62 @@
+/**
+ * Draws `InstrumentIconArt` onto a 2D canvas context.
+ *
+ * The SVG side of the same art lives in the app's `InstrumentIcon` component;
+ * both replay the shape list, so an icon added to `gm-icon.ts` appears in the
+ * gutter and the DOM without either renderer being touched.
+ */
+import { ICON_STROKE_WIDTH, ICON_VIEWBOX, parseIconPath, } from '@sudobility/music_types';
+function appendShape(ctx, shape) {
+    if (shape.kind === 'circle') {
+        // `arc` draws a line from the current point to the arc's start, which
+        // would tie every circle to whatever was drawn before it.
+        ctx.moveTo(shape.cx + shape.r, shape.cy);
+        ctx.arc(shape.cx, shape.cy, shape.r, 0, Math.PI * 2);
+        return;
+    }
+    for (const segment of parseIconPath(shape.d)) {
+        switch (segment.kind) {
+            case 'move':
+                ctx.moveTo(segment.x, segment.y);
+                break;
+            case 'line':
+                ctx.lineTo(segment.x, segment.y);
+                break;
+            case 'cubic':
+                ctx.bezierCurveTo(segment.x1, segment.y1, segment.x2, segment.y2, segment.x, segment.y);
+                break;
+            case 'quad':
+                ctx.quadraticCurveTo(segment.x1, segment.y1, segment.x, segment.y);
+                break;
+            case 'close':
+                ctx.closePath();
+                break;
+        }
+    }
+}
+/**
+ * Strokes `art` in the current `strokeStyle`, scaled into a `size`-square box
+ * whose top-left corner is (`x`, `y`).
+ *
+ * One `beginPath`/`stroke` pair for the whole icon: the shapes are all the same
+ * colour and weight, so there is nothing to gain from stroking them separately.
+ * `save`/`restore` bracket the transform, so the caller's — the gutter's pinned,
+ * zoom-and-DPR-scaled one — survives.
+ */
+export function strokeInstrumentIcon(ctx, art, x, y, size) {
+    const scale = size / ICON_VIEWBOX;
+    ctx.save();
+    ctx.translate(x, y);
+    ctx.scale(scale, scale);
+    // Set inside the scaled space, so the weight scales with the art rather than
+    // going hairline at gutter size and heavy at display size.
+    ctx.lineWidth = ICON_STROKE_WIDTH;
+    ctx.lineJoin = 'round';
+    ctx.lineCap = 'round';
+    ctx.beginPath();
+    for (const shape of art.shapes)
+        appendShape(ctx, shape);
+    ctx.stroke();
+    ctx.restore();
+}
+//# sourceMappingURL=icon-canvas.js.map

package/dist/icon-canvas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"icon-canvas.js","sourceRoot":"","sources":["../src/icon-canvas.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,aAAa,GACd,MAAM,yBAAyB,CAAC;AAGjC,SAAS,WAAW,CAAC,GAA6B,EAAE,KAAgB;IAClE,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC5B,sEAAsE;QACtE,0DAA0D;QAC1D,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,GAAG,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC;QACzC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;QACrD,OAAO;IACT,CAAC;IAED,KAAK,MAAM,OAAO,IAAI,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7C,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;YACrB,KAAK,MAAM;gBACT,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;gBACjC,MAAM;YACR,KAAK,MAAM;gBACT,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;gBACjC,MAAM;YACR,KAAK,OAAO;gBACV,GAAG,CAAC,aAAa,CACf,OAAO,CAAC,EAAE,EACV,OAAO,CAAC,EAAE,EACV,OAAO,CAAC,EAAE,EACV,OAAO,CAAC,EAAE,EACV,OAAO,CAAC,CAAC,EACT,OAAO,CAAC,CAAC,CACV,CAAC;gBACF,MAAM;YACR,KAAK,MAAM;gBACT,GAAG,CAAC,gBAAgB,CAAC,OAAO,CAAC,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;gBACnE,MAAM;YACR,KAAK,OAAO;gBACV,GAAG,CAAC,SAAS,EAAE,CAAC;gBAChB,MAAM;QACV,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAClC,GAA6B,EAC7B,GAAsB,EACtB,CAAS,EACT,CAAS,EACT,IAAY;IAEZ,MAAM,KAAK,GAAG,IAAI,GAAG,YAAY,CAAC;IAElC,GAAG,CAAC,IAAI,EAAE,CAAC;IACX,GAAG,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACpB,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IACxB,6EAA6E;IAC7E,2DAA2D;IAC3D,GAAG,CAAC,SAAS,GAAG,iBAAiB,CAAC;IAClC,GAAG,CAAC,QAAQ,GAAG,OAAO,CAAC;IACvB,GAAG,CAAC,OAAO,GAAG,OAAO,CAAC;IAEtB,GAAG,CAAC,SAAS,EAAE,CAAC;IAChB,KAAK,MAAM,KAAK,IAAI,GAAG,CAAC,MAAM;QAAE,WAAW,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACxD,GAAG,CAAC,MAAM,EAAE,CAAC;IAEb,GAAG,CAAC,OAAO,EAAE,CAAC;AAChB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @sudobility/music_drawing — the notation renderer.
+ *
+ * Everything that turns a `Score` into pixels: the layout that decides where
+ * each system and measure sits, the VexFlow objects that draw a bar, and the
+ * windowed canvas renderer that paints only what is on screen.
+ *
+ * Its own package because it is the one part of the frontend that is *large,
+ * self-contained and about drawing*. It depends on `@sudobility/music_types`
+ * for the model and on `vexflow` to draw, and on nothing else — no store, no
+ * network, no audio, no React. That is what makes it usable from the editor,
+ * the print view and the public score page alike, and what keeps `music_lib`
+ * from having to carry a rendering engine to offer business logic.
+ *
+ * The canvas is the deliberate choice here. Drawing only the visible systems
+ * per scroll or resize frame *is* the virtualization — one canvas, no
+ * per-glyph DOM — which is what makes an unbounded score scroll smoothly.
+ */
+export * from './types.js';
+export * from './layout.js';
+export * from './pagination.js';
+export * from './display-timing.js';
+export * from './convert.js';
+export * from './measure-content.js';
+export * from './canvas-renderer.js';
+export * from './note-color.js';
+export * from './playhead.js';
+export * from './percussion.js';
+export * from './icon-canvas.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC;AAC7B,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,30 @@
+/**
+ * @sudobility/music_drawing — the notation renderer.
+ *
+ * Everything that turns a `Score` into pixels: the layout that decides where
+ * each system and measure sits, the VexFlow objects that draw a bar, and the
+ * windowed canvas renderer that paints only what is on screen.
+ *
+ * Its own package because it is the one part of the frontend that is *large,
+ * self-contained and about drawing*. It depends on `@sudobility/music_types`
+ * for the model and on `vexflow` to draw, and on nothing else — no store, no
+ * network, no audio, no React. That is what makes it usable from the editor,
+ * the print view and the public score page alike, and what keeps `music_lib`
+ * from having to carry a rendering engine to offer business logic.
+ *
+ * The canvas is the deliberate choice here. Drawing only the visible systems
+ * per scroll or resize frame *is* the virtualization — one canvas, no
+ * per-glyph DOM — which is what makes an unbounded score scroll smoothly.
+ */
+export * from './types.js';
+export * from './layout.js';
+export * from './pagination.js';
+export * from './display-timing.js';
+export * from './convert.js';
+export * from './measure-content.js';
+export * from './canvas-renderer.js';
+export * from './note-color.js';
+export * from './playhead.js';
+export * from './percussion.js';
+export * from './icon-canvas.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC;AAC7B,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC"}

package/dist/layout.d.ts

@@ -0,0 +1,159 @@
+/**
+ * System layout (spec §7, §26): decides which measures share a system
+ * ("row") and the box (x, y, width, height) each track's stave occupies
+ * for every measure, for both "page" (wraps to `options.width`) and
+ * "continuous" (everything in one system) layout modes.
+ *
+ * Measure width is derived from how many onsets a bar actually draws, times a
+ * per-onset budget measured from VexFlow's own minimum — close enough that a
+ * dense bar is neither cramped nor half empty, without laying every glyph out
+ * twice to find out exactly.
+ *
+ * Units are LOGICAL (design-time) pixels, independent of `options.zoom`.
+ * Zoom is applied once, uniformly, as a canvas transform scale in
+ * `canvas-renderer.ts` (`ctx.setTransform(zoom·dpr, …)`) so glyphs/text
+ * scale along with spacing instead of staying a fixed size while only the
+ * layout stretches. The one place zoom enters this module is dividing the
+ * *available* screen width by zoom to get the logical width budget for
+ * page-mode wrapping (a more zoomed-in view fits fewer logical pixels in
+ * the same screen width). Callers needing final on-screen coordinates
+ * (e.g. `CanvasRenderResult` bboxes) must multiply this module's output by
+ * `zoom` themselves.
+ */
+import type { Score, Track } from '@sudobility/music_types';
+import type { RenderOptions } from './types.js';
+export type StaveBox = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+export type MeasureLayout = {
+    measureIndex: number;
+    isFirstInSystem: boolean;
+    box: StaveBox;
+};
+export type TrackLayout = {
+    track: Track;
+    measures: MeasureLayout[];
+};
+/** A brace/connector-worthy row: the outer bounds of every track's stave sharing this system. */
+export type SystemLayout = {
+    measureIndices: number[];
+    xLeft: number;
+    xRight: number;
+    /** Top of the measure-number band; always `yTop - MEASURE_HEADER_HEIGHT`. */
+    gutterTop: number;
+    yTop: number;
+    yBottom: number;
+};
+export type LayoutPlan = {
+    tracks: Track[];
+    trackLayouts: TrackLayout[];
+    systems: SystemLayout[];
+    /** Logical (unscaled) units — multiply by zoom for the final on-screen SVG canvas size. */
+    totalWidth: number;
+    /** Logical (unscaled) units — multiply by zoom for the final on-screen SVG canvas size. */
+    totalHeight: number;
+};
+export declare const BASE_MEASURE_WIDTH = 160;
+/**
+ * Width budget per drawn onset.
+ *
+ * Measured, not guessed: `Formatter.preCalculateMinTotalWidth` asks 446 units
+ * for a bar of sixteen sixteenths, which is 27.9 each, and the same 27.9
+ * whether or not every one of them carries an accidental. Rounded up to 28, so
+ * a dense bar is given at least what VexFlow will ask for and never has to
+ * overflow into the next measure's space — which would break the shared
+ * barline across tracks.
+ *
+ * A measure with more onsets than the base width comfortably holds grows
+ * proportionally (`max(BASE, onsets * SLOT + PADDING)`), and the count is the
+ * union across every track, so all tracks agree on the shared width.
+ */
+export declare const NOTE_SLOT_WIDTH = 28;
+/** Breathing room added to a density-derived measure width (start padding + last note's stem/flag overhang + barline clearance). */
+export declare const DENSE_MEASURE_PADDING = 35;
+/** Extra width reserved on a system's first measure for clef + key signature + time signature. */
+export declare const SYSTEM_HEADER_WIDTH = 90;
+/** The whole vertical row one track occupies in a system. Exported so the renderer can cull staves against the viewport. */
+export declare const STAVE_HEIGHT = 100;
+/**
+ * Vertical distance between adjacent staff positions, in logical units — one
+ * line to the space beside it.
+ *
+ * VexFlow spaces its five lines 10 units apart and the renderer does not
+ * override that, so a staff position is half of it. Exported because dragging a
+ * note up and down the staff needs to turn pixels into positions, and deriving
+ * that from `STAVE_HEIGHT` would be wrong: that is the whole row a track is
+ * given, padding included, not the ruled staff.
+ */
+export declare const STAVE_POSITION_HEIGHT = 5;
+/**
+ * Distance from a track box's top edge down to the stave's **top line**.
+ *
+ * VexFlow reserves headroom above the ruled staff for anything that sits over
+ * it — `space_above_staff_ln: 4` line-spaces, at its 10-unit line distance — so
+ * the `y` a `Stave` is constructed with is not where the music starts. Exported
+ * because the track-info gutter aligns its instrument row to the first line the
+ * reader actually sees, and eyeballing that offset would drift the moment the
+ * stave's options changed.
+ */
+export declare const STAVE_TOP_LINE_OFFSET: number;
+/**
+ * Width reserved at the left of every system for the track-info gutter (track
+ * name, instrument, mute/solo), and the width the app's track editing panel
+ * matches.
+ *
+ * Reserving it here is what makes the gutter's alignment with the staves
+ * structural: it lives in the same coordinate space, so there is nothing to
+ * synchronise. The previous approach positioned a DOM list against reported
+ * geometry and had to be stopped from scrolling independently.
+ */
+export declare const TRACK_INFO_WIDTH = 220;
+/**
+ * Height of the measure-number band above each system's top stave (also the
+ * click target for measure selection).
+ *
+ * Systems after the first take it out of `SYSTEM_GAP`, so nothing reflows.
+ * The first system has only `TOP_MARGIN` above it — not enough — so the
+ * effective top margin is raised by this much, which is why `totalHeight`
+ * grows by twice this value (the margin is counted at both ends).
+ */
+export declare const MEASURE_HEADER_HEIGHT = 18;
+/** Guards against a zero/negative/non-finite zoom breaking division or `context.scale`. */
+export declare function resolveZoom(zoom: number): number;
+/**
+ * Computes per-track, per-measure stave boxes and per-system outer bounds
+ * (for brace/connector drawing), all in LOGICAL (unscaled) units — see the
+ * module doc. Assumes all selected tracks share the same measure count; a
+ * track with fewer measures than the score's max simply has no box for the
+ * missing trailing measures (defensive, not expected in practice — spec §4
+ * keeps tracks aligned to the same measure grid).
+ */
+export declare function computeLayout(score: Score, options: RenderOptions): LayoutPlan;
+/**
+ * The stave box for `measureIndex` on `plan.trackLayouts[trackIndex]`
+ * (logical units), or `null` if that track/measure index isn't present in
+ * the plan. Lets a caller locate a measure's position (e.g. to scroll to
+ * it during playback) directly from layout, independent of whether that
+ * measure fell inside the drawn window of a windowed canvas render pass
+ * (system boxes never shift with what a given frame chooses to draw).
+ */
+export declare function boxForMeasureIndex(plan: LayoutPlan, trackIndex: number, measureIndex: number): StaveBox | null;
+/** Binary search over the y-sorted `plan.systems` for the system containing logical `y`; `null` in inter-system gaps or outside the score. O(log n). */
+export declare function systemAtY(plan: LayoutPlan, y: number): SystemLayout | null;
+/**
+ * Binary search over `system`'s x-sorted measures (first track's layouts)
+ * for the measure containing logical `x`, clamping x into the system's
+ * measure span (clicks left of the clef resolve to the first measure,
+ * right of the last barline to the last). `null` only when the system
+ * resolves to no measure layouts. O(log n).
+ *
+ * Indexing note: `computeLayout` pushes one `MeasureLayout` per measure in
+ * ascending order for every track that has the measure, so for track 0
+ * `trackLayouts[0].measures[i].measureIndex === i` — direct indexing by
+ * `system.measureIndices` values is safe (and bounds-guarded here anyway).
+ */
+export declare function measureAtXInSystem(plan: LayoutPlan, system: SystemLayout, x: number): MeasureLayout | null;
+//# sourceMappingURL=layout.d.ts.map

package/dist/layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../src/layout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AAE5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,MAAM,MAAM,QAAQ,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/E,MAAM,MAAM,aAAa,GAAG;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,OAAO,CAAC;IACzB,GAAG,EAAE,QAAQ,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,EAAE,aAAa,EAAE,CAAC;CAC3B,CAAC;AAEF,iGAAiG;AACjG,MAAM,MAAM,YAAY,GAAG;IACzB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,2FAA2F;IAC3F,UAAU,EAAE,MAAM,CAAC;IACnB,2FAA2F;IAC3F,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,eAAO,MAAM,kBAAkB,MAAM,CAAC;AAUtC;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,eAAe,KAAK,CAAC;AAClC,oIAAoI;AACpI,eAAO,MAAM,qBAAqB,KAAK,CAAC;AACxC,kGAAkG;AAClG,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAUtC,4HAA4H;AAC5H,eAAO,MAAM,YAAY,MAAM,CAAC;AAEhC;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,QAA4B,CAAC;AAM/D;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAGpC;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAExC,2FAA2F;AAC3F,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD;AA+CD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,aAAa,GACrB,UAAU,CAyMZ;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,UAAU,EAChB,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,GACnB,QAAQ,GAAG,IAAI,CAMjB;AAED,wJAAwJ;AACxJ,wBAAgB,SAAS,CAAC,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAY1E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,YAAY,EACpB,CAAC,EAAE,MAAM,GACR,aAAa,GAAG,IAAI,CAuBtB"}