@sudobility/music_drawing 0.0.33 → 0.0.35

package/dist/score-canvas.d.ts

@@ -0,0 +1,280 @@
+/**
+ * The score canvas: one contract between the drawn score and what drives it.
+ *
+ * See `docs/score-canvas.md` for the interface and the expectations the tests
+ * pin. In short: playback, selection and the active track talk to a
+ * `ScoreCanvas`; the canvas owns every geometric decision (layout, units, the
+ * cursor path, hit-testing, where following playback scrolls); and each app
+ * supplies only a `ScoreCanvasSurface` that puts pixels on its platform. Both
+ * apps therefore answer "where is tick N" and "what is under this point" with
+ * the same code.
+ */
+import type { Pitch, PitchDisplay, Score, SoundingNote } from '@sudobility/music_types';
+import type { CanvasRenderOptions, CanvasRenderResult } from './canvas-renderer.js';
+import type { LayoutPlan } from './layout.js';
+import type { PlaybackScrollTarget } from './playback-scroll.js';
+import type { LayoutMode, RenderTheme } from './types.js';
+import type { CursorGeometry, CursorMotion, CursorPath } from './cursor.js';
+import type { PaintFrame } from './layered-paint.js';
+/** What the canvas is showing and at what size. `width`/`height` are view px. */
+export type ScoreCanvasView = {
+    width: number;
+    height: number;
+    zoom: number;
+    layoutMode: LayoutMode;
+    theme: RenderTheme;
+    /** Tracks to draw, top to bottom; omitted means all. */
+    trackIds?: string[];
+    devicePixelRatio?: number;
+};
+/** A point in view px: relative to the visible top-left, scroll not added. */
+export type ViewPoint = {
+    x: number;
+    y: number;
+};
+export type ScoreCanvasHit = {
+    kind: 'trackGutter';
+    trackId: string;
+} | {
+    kind: 'measureNumber';
+    measureIndex: number;
+} | {
+    kind: 'note';
+    /** Every event sharing the notehead's box: a chord is one target. */
+    eventIds: string[];
+    trackId: string;
+    measureIndex: number;
+    tick: number;
+} | {
+    kind: 'stave';
+    trackId: string;
+    measureIndex: number;
+    tick: number;
+    /** The pitch *as drawn* at that point, when the point is on a stave. */
+    pitch: Pitch | null;
+};
+/** What a platform provides. */
+export interface ScoreCanvasSurface {
+    /**
+     * Draw the window described by `options` with a `CanvasScoreRenderer` the
+     * surface keeps for its life (its column cache is what makes a repaint cheap),
+     * and return what it returned. The surface renders because only it has a
+     * drawing context: Skia's exists only inside a picture recording.
+     *
+     * `frame.baseVersion` is unchanged from the last paint when only the lit
+     * notes have changed, which is what lets a surface built on
+     * `createLayeredPaint` keep its base and redraw the active track alone.
+     */
+    paint(score: Score, options: CanvasRenderOptions, frame: PaintFrame): CanvasRenderResult | null;
+    /**
+     * Show the cursor moving along `path` per `motion` (held when the rate is 0),
+     * or hide it with `null`. Called only when either changes.
+     */
+    showCursor(path: CursorPath | null, motion: CursorMotion): void;
+    /** Scroll the view to a content-px target. */
+    scrollTo?(target: PlaybackScrollTarget, how: 'jump' | 'smooth'): void;
+    /**
+     * Build, without drawing, some of what a later paint of `options` will need
+     * — `CanvasScoreRenderer.prepare` on the surface's renderer — and answer how
+     * much is still missing. The canvas calls it during playback, a slice per
+     * task, for the window following the music is about to move to.
+     */
+    prepare?(score: Score, options: CanvasRenderOptions): number;
+    /**
+     * How long a painted frame takes to reach the screen after `paint` returns,
+     * in ms — the part of highlight latency the canvas cannot time itself. One
+     * frame when omitted: a browser composites the canvas at the next frame, and
+     * the native app's React commit and Skia draw land about a frame later too.
+     */
+    readonly presentLatencyMs?: number;
+}
+/**
+ * Time and frames, injected.
+ *
+ * Required rather than defaulted: this package names no host global (see
+ * `globals.d.ts`), so a web host passes `requestAnimationFrame` and a native one
+ * whatever its runtime offers.
+ */
+export type CanvasScheduler = {
+    /** Run `callback` before the next paint; returns a canceller. */
+    frame(callback: () => void): () => void;
+    /** Run `callback` after `ms`; returns a canceller. */
+    timeout(callback: () => void, ms: number): () => void;
+    /** `performance.now()`. */
+    now(): number;
+};
+export type ScoreCanvasOptions = {
+    surface: ScoreCanvasSurface;
+    scheduler: CanvasScheduler;
+};
+export declare class ScoreCanvas {
+    private readonly surface;
+    private readonly scheduler;
+    private score;
+    /** What `setStoredScore` was last given, so a repeat call does no work. */
+    private stored;
+    private pitchDisplay;
+    private view;
+    private scrollLeft;
+    private scrollTop;
+    private activeTrackId;
+    private playing;
+    private selectedIds;
+    private regenerated;
+    private outOfRangeIds;
+    private selectedMeasureIds;
+    private lastFrame;
+    /** The plan the last frame was drawn against is only trusted while this matches. */
+    private currentPlan;
+    private starts;
+    private cancelPaint;
+    /** What the drawn window last showed, so an invisible colour change skips the paint. */
+    private paintedSignature;
+    /**
+     * Moves whenever something other than the lit notes changes what a paint
+     * draws; see `PaintFrame`. Bumped lazily, at the next paint, so a burst of
+     * changes costs one version.
+     */
+    private baseVersion;
+    private baseDirty;
+    /**
+     * Moves with every change `baseDirty` records, eagerly — the base colour
+     * signature is cached against it, and that cache is read between paints.
+     */
+    private baseEpoch;
+    private baseSignatureCache;
+    /** When the lit notes last changed without being painted yet. */
+    private highlightRequestedAt;
+    private highlightSamples;
+    private highlightLatency;
+    private readonly highlightListeners;
+    private motion;
+    private path;
+    private shownMotion;
+    private cancelWrap;
+    /** The look-ahead preparation in progress, and the window it is for. */
+    private cancelLookahead;
+    private lookaheadKey;
+    private lookaheadPlan;
+    constructor({ surface, scheduler }: ScoreCanvasOptions);
+    /**
+     * The score as the store holds it — sounding pitch, before any lens — and
+     * the reading mode to draw it in.
+     *
+     * The preferred way in. The canvas applies `displayScore` itself and scans
+     * the stored score with `outOfRangeNoteIds`, so no host has to remember
+     * either half: the scan must see **stored** pitch (the compass is sounding
+     * pitch) while the paint must see the **display** score, and a host handed
+     * only one of the two was always one line away from colouring a clarinet's
+     * part a tone out, or from marking nothing at all.
+     *
+     * The ids it marks survive the lenses — both keep event ids — so they colour
+     * the drawn notes correctly in either mode. Calling again with the same
+     * score and mode does nothing. A later `setOutOfRangeNotes` overrides the
+     * marks until the stored score next changes.
+     */
+    setStoredScore(score: Score | null, pitchDisplay?: PitchDisplay): void;
+    /**
+     * The **display** score, lenses already applied.
+     *
+     * Lower level than `setStoredScore`: the host owns the lenses and, if it
+     * wants out-of-range marks, must pass them to `setOutOfRangeNotes` from a
+     * scan of the stored score. Kept for hosts that have not moved over.
+     */
+    setScore(score: Score | null): void;
+    setView(view: ScoreCanvasView): void;
+    /** Content px. */
+    setScroll(left: number, top: number): void;
+    setCursorTick(tick: number): void;
+    animateCursor(motion: CursorMotion): void;
+    setActiveTrack(trackId: string | null): void;
+    setPlayingNotes(notes: readonly SoundingNote[]): void;
+    setSelectedNotes(ids: readonly string[], options?: {
+        regenerated?: boolean;
+    }): void;
+    setSelectedMeasures(ids: readonly string[]): void;
+    setOutOfRangeNotes(ids: readonly string[]): void;
+    /** The layout the canvas draws against, or null with no score or view. */
+    get plan(): LayoutPlan | null;
+    /** What the last paint drew, while it still describes the current layout. */
+    get frame(): CanvasRenderResult | null;
+    get zoom(): number;
+    /** How large the scrollable content is, in content px. */
+    contentSize(): {
+        width: number;
+        height: number;
+    };
+    /** Content px. */
+    cursorGeometry(tick: number): CursorGeometry | null;
+    hitTest(point: ViewPoint): ScoreCanvasHit | null;
+    /** The tick under a view point: the inverse of the cursor. */
+    tickAt(point: ViewPoint): number | null;
+    /** Drawn notes inside a view-px rectangle spanned by two corners. */
+    noteIdsInRect(a: ViewPoint, b: ViewPoint): string[];
+    /** The bar index `tick` falls in, or null — following playback decides per bar. */
+    measureIndexAt(tick: number): number | null;
+    /**
+     * Ticks per second at `tick` from the written tempo — a first guess for a
+     * cursor that has just started moving, before the real rate is measured.
+     */
+    writtenTicksPerSecond(tick: number): number;
+    /** Where following playback should scroll for `tick`, or null to stay. */
+    followTarget(tick: number): PlaybackScrollTarget | null;
+    /** Scroll so `tick` is in view: a jump for more than a screen, else smooth. */
+    scrollToFollow(tick: number): void;
+    /**
+     * How long a change of lit notes takes to reach the screen here, in seconds:
+     * waiting for the frame, drawing, and presenting.
+     *
+     * Measured rather than assumed because it is a property of the host. A web
+     * canvas repaints a window of notation in a few milliseconds; the native app
+     * records a Skia picture and waits a React commit, measured at 45–70ms on a
+     * dense score. The player publishes the lit notes this far ahead
+     * (`setSoundingRenderDelay`), which is what keeps them with the sound on
+     * both. The median of recent paints, so one stalled frame does not move it.
+     */
+    get highlightLatencySeconds(): number;
+    subscribeHighlightLatency(listener: (seconds: number) => void): () => void;
+    /** Paint now rather than on the next frame — for a host that must, like a resize. */
+    paintNow(): void;
+    dispose(): void;
+    private layoutOptions;
+    private positions;
+    private invalidateLayout;
+    /** Schedules a paint for a colour change; says whether one was needed. */
+    private scheduleColourPaint;
+    private markBaseDirty;
+    /**
+     * What colour the drawn window shows, as a string two states compare by.
+     *
+     * In two parts, because they change at very different rates. Everything but
+     * the lit notes — the active track, the selection, the out-of-range marks,
+     * the selected bars — changes when somebody does something, and is cached
+     * until then; the lit notes change on every note during playback, and are a
+     * handful. Building the whole string on every change of lit notes cost time
+     * in proportion to every coloured note in the window, which on an import
+     * full of out-of-range notes is most of them. A playing note is drawn playing
+     * whatever else it is (`buildNoteColors` applies it last), so the two parts
+     * together decide the colours exactly.
+     */
+    private colourSignature;
+    private baseSignature;
+    /** The drawn notes lit now: the active track's sounding notes on screen. */
+    private playingSignature;
+    private noteColors;
+    private schedulePaint;
+    private paint;
+    /**
+     * While the cursor moves, builds the window following it will show next —
+     * the music just past what is drawn, where `followTarget` would put it — a
+     * slice per task, so the frame that scrolls there only has to paint.
+     *
+     * Keyed on the plan and that window, so each is prepared once however many
+     * paints happen while it is the next one.
+     */
+    private scheduleLookahead;
+    private measureHighlight;
+    private refreshCursor;
+    private show;
+}
+//# sourceMappingURL=score-canvas.d.ts.map

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

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