@braccato/core 0.1.7 → 1.0.0

package/dist/engine.d.ts

@@ -0,0 +1,309 @@
+import type { LineData } from "./inject.js";
+import type { LyricsRendererHost, LyricSyncType, ResolvedTickOptions, TickOptions } from "./types.js";
+/**
+ * Everything that belongs to a single rendered lyrics view: one scroll container, one selection,
+ * one set of pending scroll work.
+ */
+interface AnimEngineViewState {
+    /**
+     * The render records this view built, one per lyric line. They hold this view's elements and
+     * this view's `Animation` objects, so a second view never shares them.
+     */
+    lines: LineData[];
+    lyricsContainer: HTMLElement | null;
+    syncType: LyricSyncType;
+    lyricWidth: number;
+    lyricHeight: number;
+    skipScrolls: number;
+    skipScrollsDecayTimes: number[];
+    scrollResumeTime: number;
+    scrollPos: number;
+    selectedElementIndex: number;
+    nextScrollAllowedTime: number;
+    wasUserScrolling: boolean;
+    lastActiveElements: LineData[];
+    queuedScroll: boolean;
+    lastScrollDebugContext: {
+        activeElms: LineData[];
+        centers: number[];
+        lyricScrollTime: number;
+    };
+    passiveScrollAccumulatedTime: number;
+    passiveLastWallTime: number;
+}
+/**
+ * `Window` alone types neither `ResizeObserver` nor `DOMMatrix`: both are ambient `var`
+ * declarations, so they only appear through `typeof globalThis`.
+ */
+type EngineWindow = Window & typeof globalThis;
+export interface AnimationEngineInstance extends AnimEngineViewState {
+    document: Document;
+    window: EngineWindow;
+    host: LyricsRendererHost;
+    cachedTabRendererHeight: number | null;
+    tabRendererResizeObserver: ResizeObserver | null;
+    observedTabRenderer: HTMLElement | null;
+    lineScrollAnimations: LineScrollAnimationRecord[];
+    lineScrollAnimationToken: number;
+    pendingLineScroll: PendingLineScroll | null;
+    lineScrollElementTokens: WeakMap<HTMLElement, number>;
+    visibleWillChangeElements: Set<HTMLElement>;
+    cachedDurations: Map<string, number>;
+    cachedCSSValues: Map<string, string>;
+    cachedAnimationSettings: AnimationSettings | null;
+    /**
+     * Last value the tick was given. The passive scroll loop runs from an animation frame rather than
+     * from a tick, so it has no options object to read.
+     */
+    passiveScrollEnabled: boolean;
+    passiveRAFId: number | null;
+    pendingLyricsUpdateFrame: number | null;
+    learnedAnimationTimingOffsetMs: number;
+    animationTimingVisibilityLogUntil: number;
+    /**
+     * Releases everything the instance holds on its window: the reduced motion listener, the tab
+     * renderer observer and any frame it still has queued.
+     */
+    destroy(): void;
+}
+/**
+ * Runs an operation against every live instance. Cheap enough for a scroll or a song change, and
+ * deliberately not used inside the tick, which runs per frame and per line.
+ */
+export declare function forEveryLiveView(runOperation: (engine: AnimationEngineInstance) => void): void;
+export declare function createAnimationEngineInstance(engineDocument: Document, engineWindow: EngineWindow, host: LyricsRendererHost): AnimationEngineInstance;
+/**
+ * Forgets the last player snapshot, so the next tick is treated as the first one of a new song
+ * rather than as a jump away from the previous one.
+ */
+export declare function resetPlaybackClock(): void;
+/**
+ * The user asked for autoscroll back, now.
+ */
+export declare function resetScrollResume(engine: AnimationEngineInstance): void;
+/**
+ * The user asked for autoscroll back, now. Resuming is a property of playback rather than of one
+ * view, so every live instance resumes. Published in this shape rather than as the registry walk
+ * and the per view operation it is built from, so that nothing outside the module gets to name a
+ * particular view.
+ */
+export declare function resumeAllAutoscroll(): void;
+/**
+ * The user scrolled this view. Scrolls the engine itself performed are swallowed one at a time;
+ * a real one pauses autoscroll long enough to read where it landed, and offers the way back.
+ *
+ * @param isPassive - Whether the lyrics on screen are unsynced, and so are drifting on their own
+ *   rather than following the song. Those resume sooner.
+ */
+export declare function noteUserScroll(engine: AnimationEngineInstance, isPassive: boolean): void;
+/**
+ * Reports whether the container is a different size than the lines were last measured against, and
+ * clears the scroll cooldown when it is so the caller's re-measurement can scroll immediately. The
+ * new size is recorded by that re-measurement, not here.
+ */
+export declare function noteContainerResize(engine: AnimationEngineInstance, width: number, height: number): boolean;
+/**
+ * Takes the lines this view is showing off the screen, keeping the container they were in, and
+ * reports whether there was anything there to take.
+ */
+export declare function clearOnScreenLyrics(engine: AnimationEngineInstance): boolean;
+export declare function hasRenderedLines(engine: AnimationEngineInstance): boolean;
+/**
+ * The render records this view built. Handing them out is a leak: they carry this view's elements
+ * and its `Animation` objects, so a caller that rewrites line times or hangs translations off them
+ * can only ever reach one view. Phase 5 revisits it, when both of those have to reach two.
+ */
+export declare function getRenderedLines(engine: AnimationEngineInstance): LineData[];
+export declare function getRenderedSyncType(engine: AnimationEngineInstance): LyricSyncType;
+/**
+ * Drops the song this view was rendering: its selection, its pending scroll work, its animations
+ * and its render records. The records go before the caller clears the DOM, so the elements they
+ * hold are released along with it.
+ */
+export declare function clearLyrics(engine: AnimationEngineInstance): void;
+type LineScrollSide = "above" | "active" | "below";
+interface LineScrollAnimationRecord {
+    animation: Animation;
+    lineElement: HTMLElement;
+    token: number;
+}
+interface AnimationConfig {
+    enabled: {
+        lineScale: boolean;
+        wordWobble: boolean;
+        highlightSwipe: boolean;
+        highlightGlow: boolean;
+        highlightFade: boolean;
+        scroll: boolean;
+        instrumental: boolean;
+    };
+    line: {
+        durationMs: number;
+        enterEasing: string;
+        exitEasing: string;
+        enterFrom: string;
+        enterTo: string;
+        exitFrom: string;
+        exitTo: string;
+    };
+    highlight: {
+        fadeInDurationMs: number;
+        fadeOutDurationMs: number;
+        fadeInEasing: string;
+        fadeOutEasing: string;
+        swipeEasing: string;
+        swipeStartFrom: string;
+        swipeEndFrom: string;
+        swipeStartTo: string;
+        swipeEndTo: string;
+        glowFrom: string;
+        glowTo: string;
+        glowDurationRatio: number;
+        glowMinDurationMs: number;
+        glowEasing: string;
+    };
+    word: {
+        wobbleDurationMs: number;
+        wobbleEasing: string;
+        wobblePeakEasing: string;
+        wobbleEndEasing: string;
+        wobbleFrom: string;
+        wobblePeak: string;
+        wobbleSettle: string;
+        wobbleTo: string;
+        wobblePeakOffset: number;
+        wobbleSettleOffset: number;
+    };
+    instrumental: {
+        fillFadeDurationMs: number;
+        fillFadeEasing: string;
+        fillFrom: string;
+        fillTo: string;
+        fillEasing: string;
+        waveFrom: string;
+        waveTo: string;
+        waveEasing: string;
+        waveOscillationDurationMs: number;
+        waveOscillationEasing: string;
+    };
+    scroll: {
+        durationMs: number;
+        easing: string;
+    };
+    lineScroll: {
+        durationMs: number;
+        easing: string;
+        differentialEffects: boolean;
+    };
+}
+interface AnimationSettings {
+    config: AnimationConfig;
+    scrollTiming: {
+        earlyScrollConsiderS: number;
+        queueScrollMs: number;
+    };
+}
+export declare function noteVisibilityChange(engine: AnimationEngineInstance): void;
+export declare function clearStyleCaches(engine: AnimationEngineInstance): void;
+interface PreparedLineScroll {
+    lineElement: HTMLElement;
+    side: LineScrollSide;
+    token: number;
+}
+interface ResolvedLineScroll extends PreparedLineScroll {
+    durationMs: number;
+    startEasing: string;
+    endEasing: string;
+    startTranslate: string;
+    endTranslate: string;
+}
+interface LineScrollPlan {
+    items: ResolvedLineScroll[];
+}
+interface PendingLineScroll {
+    plan: LineScrollPlan;
+    activeLineElement: HTMLElement;
+    fromScrollTop: number;
+    toScrollTop: number;
+}
+/**
+ * Unsynced lyrics that this view still has on screen. `syncType` outlives the lyrics it was derived
+ * from, so the container is the term that says they are still there.
+ */
+export declare function hasUnsyncedLyrics(engine: AnimationEngineInstance): boolean;
+/**
+ * "lyrics-missing" means this instance has nothing left to render. Whether that ends ticking is the
+ * driver's call, not the instance's: one instance running dry must not silence another.
+ */
+export type AnimationTickStatus = "ok" | "lyrics-missing";
+/**
+ * Fills in everything a caller left out of a tick. The tick reads each of these arithmetically, so
+ * a missing one would not fail: it would quietly turn the playback time into NaN and leave the view
+ * matching no line at all.
+ */
+export declare function resolveTickOptions(options: TickOptions): ResolvedTickOptions;
+/**
+ * Renders one view against a tick with nothing left out.
+ */
+export declare function tickView(engine: AnimationEngineInstance, currentTime: number, options: ResolvedTickOptions): AnimationTickStatus;
+/**
+ * What a view has to know to size its scroll padding. Split out from the element reads so the
+ * arithmetic can be checked against the degenerate cases, which is where it went wrong: an
+ * unrendered container answers zero to every measurement.
+ */
+interface ScrollPaddingMeasurements {
+    viewportHeight: number;
+    targetScrollRatio: number;
+    /** The container's own height with whatever bottom padding it currently carries taken back off. */
+    contentHeight: number;
+    firstLineHeight: number;
+    /** Distance from the top of the container to the middle of the last line, or null with no lines. */
+    lastLineCentre: number | null;
+    lastLineHeight: number;
+    footerHeight: number;
+}
+/**
+ * Sizes the padding above the first line and below the last one so either can sit at the view's
+ * target scroll position.
+ *
+ * The first two candidates are exact, and both are measured from the container. They are worth
+ * nothing while it is not rendering: every line reports zero, which reads as content that already
+ * runs past the last line and asks for no padding at all, and the last lines of the song then have
+ * nowhere to scroll to. The viewport keeps its height whether the lyrics render or not, so the
+ * space it alone demands below the last line is always knowable, and it is the floor. Over-padding
+ * costs nothing visible; under-padding strands the end of every song.
+ */
+export declare function computeScrollPadding(measurements: ScrollPaddingMeasurements): {
+    top: number;
+    bottom: number;
+};
+/**
+ * Re-reads the view's layout: the scroll padding first, then the line positions the padding moved.
+ *
+ * @param measureLines - Pass false while the lines are not being rendered. An unrendered container
+ *   measures every line as zero height at zero offset, which would leave the scroll maths with
+ *   nothing to work from once rendering resumes.
+ */
+export declare function relayout(engine: AnimationEngineInstance, measureLines: boolean): void;
+/**
+ * Renders this view again against the last player snapshot, without moving the clock on. The
+ * options are built now rather than handed in, so a caller that reads settings at tick time still
+ * reads them at tick time.
+ *
+ * @param buildTickOptions - Given the snapshot the tick will run against, returns what to render it
+ *   with.
+ */
+export declare function retickFromPlaybackClock(engine: AnimationEngineInstance, buildTickOptions: (eventCreationTime: number, isPlaying: boolean) => TickOptions): AnimationTickStatus;
+/**
+ * Called when a new lyrics element is added to trigger re-sync.
+ * Debounced via requestAnimationFrame to avoid O(n²) layout thrashing
+ * when translations/romanizations load (each addition would otherwise
+ * re-measure ALL lines).
+ *
+ * @param isViewRendering - Asked on the frame rather than now. A driver that has stopped ticking is
+ *   one whose lines may no longer be rendered, and an unrendered line measures as nothing, so a
+ *   false answer declines both the re-measurement and the re-tick.
+ * @param retick - Runs after the re-measurement, on the frame.
+ */
+export declare function scheduleLyricPositionUpdate(engine: AnimationEngineInstance, isViewRendering: () => boolean, retick: () => void): void;
+export {};