@braccato/core 0.1.6 → 1.0.0

package/dist/types.d.ts

@@ -0,0 +1,199 @@
+import type { Lyric, LyricPart, LyricSyncType } from "@braccato/types";
+import type { AnimationTickStatus } from "./engine.js";
+import type { LineData } from "./inject.js";
+import type { SetLyricsOptions } from "./view.js";
+export type { Lyric, LyricPart, LyricSyncType };
+/**
+ * The play state is the only thing a tick cannot be given a sensible default for. Everything else
+ * describes a setting the consumer may not have, so it may be left out.
+ */
+export interface TickOptions {
+    /**
+     * Wall clock timestamp of the player snapshot the time came from, in milliseconds.
+     * Defaults to -1, which reads as a time that was not sampled from a live player.
+     */
+    eventCreationTime?: number;
+    isPlaying: boolean;
+    /** Defaults to true. */
+    smoothScroll?: boolean;
+    /**
+     * User offsets, in seconds, subtracted from the playback time before matching. Each defaults to 0.
+     */
+    globalLyricOffset?: number;
+    lyricOffset?: number;
+    richsyncOffsetTrim?: number;
+    lineOffsetTrim?: number;
+    /**
+     * Whether the user has passive scrolling switched on. Only unsynced lyrics use it. Defaults to
+     * false.
+     */
+    passiveScrollEnabled?: boolean;
+}
+/**
+ * A tick with nothing left out. The engine reads every field unconditionally, so the defaults are
+ * filled in at the edge rather than guessed at each read.
+ */
+export type ResolvedTickOptions = Required<TickOptions>;
+export interface LyricsRendererDebugSink {
+    /**
+     * Clears the debug surface and returns a context translated to the given scroll offset.
+     */
+    beginFrame(scrollOffset: number): CanvasRenderingContext2D | null;
+    resize(): void;
+}
+export interface LyricsRendererHost {
+    isViewVisible(): boolean;
+    isLoaderActive(): boolean;
+    /**
+     * Reports whether an ad is playing, and lets the host move whatever it shows in place of lyrics
+     * into the matching state. One call rather than a query and a command, because the renderer never
+     * needs one without the other and the host already knows the answer when it is asked.
+     */
+    syncAdState(): boolean;
+    /**
+     * Resolved per tick rather than handed over once: YouTube Music swaps its scroll container out,
+     * and the renderer is constructed before that container exists.
+     */
+    getScrollElement(): HTMLElement | null;
+    /**
+     * Shows or puts away whatever the host offers for resuming autoscroll. The host decides what it
+     * looks like and where it lives; the renderer only says whether it is wanted.
+     */
+    setResumeAffordanceVisible(visible: boolean): void;
+    /**
+     * Called when a lyric line is clicked. How the seek reaches the player is the host's business:
+     * this extension dispatches an event at the page world, another consumer might set
+     * currentTime on a media element directly.
+     */
+    seek(timeS: number): void;
+    /**
+     * Where the view's diagnostics go. The host owns the prefix and whether logging is on at all.
+     */
+    log(...args: unknown[]): void;
+    debug?: LyricsRendererDebugSink;
+}
+export interface LyricsRendererOptions {
+    document: Document;
+    window: Window;
+    /**
+     * Where the lyrics are built. `setLyrics` takes one too, for a consumer whose mount only exists
+     * once there is something to put in it; the last one given is the one in use.
+     */
+    mount?: HTMLElement;
+    /**
+     * Every member has a default, so a consumer with nothing to say about its surroundings says
+     * nothing at all.
+     */
+    host?: Partial<LyricsRendererHost>;
+}
+/**
+ * One rendered lyrics view, and everything it takes to keep it measured. The consumer owns the
+ * clock and the lyrics; the renderer owns the DOM it builds from them and every re-measurement that
+ * DOM needs.
+ */
+export interface LyricsRenderer {
+    /**
+     * Replaces whatever this renderer last built. Every option has a default, so a consumer with an
+     * opinion about only one of them says only that one. The mount rides along with the CSS flags
+     * rather than taking a parameter of its own: it is an option of this call like the others, and a
+     * third parameter would have every caller that only wants to move the mount pass over the two in
+     * front of it.
+     */
+    setLyrics(lyrics: Lyric[], options?: Partial<SetLyricsOptions> & {
+        mount?: HTMLElement;
+    }): void;
+    /**
+     * Applies a compiled theme. The `blyrics-*` configuration in its comments becomes the module's
+     * theme settings, and the stylesheet itself is applied to the document this renderer builds in.
+     *
+     * The settings are the module's rather than this instance's, so a second renderer in the same
+     * realm renders against the last theme any of them was given. The stylesheet is per document.
+     *
+     * @returns Whether a setting the lines are built out of changed, so the caller can hand the
+     * lyrics back. The renderer does not hold them, so it cannot rebuild them itself.
+     */
+    setTheme(css: string): boolean;
+    /**
+     * Renders the view at a playback time, in seconds. The module owns no clock, so this is the whole
+     * of how the song reaches it, and the answer says whether there was a view here to render.
+     */
+    tick(currentTimeS: number, options: TickOptions): AnimationTickStatus;
+    /**
+     * Re-reads the layout and renders nothing, leaving the lines it just re-read to the next tick.
+     *
+     * @param measureLines - Defaults to true, and asking is not the same as getting: lines the page is
+     *   not rendering measure as zero height at zero offset, so the renderer holds the line
+     *   measurement back itself while they are off the screen. Pass false to rewrite only the padding,
+     *   which is sized against the viewport and so is knowable either way.
+     */
+    relayout(measureLines?: boolean): void;
+    /**
+     * Drops the song and the DOM built for it. The renderer built that DOM, so it takes it away again.
+     */
+    clear(): void;
+    /**
+     * Clears, and gives up the window and document it was holding. Final: everything here does
+     * nothing afterwards.
+     */
+    destroy(): void;
+    /**
+     * The user scrolled the view. Whether that resumes sooner because the lyrics are unsynced is the
+     * renderer's own reading of what it has on screen, not something the caller has to supply.
+     */
+    noteUserScroll(): void;
+    /**
+     * The document this view is in was shown or hidden. Nothing is reset either way, and a view told
+     * nothing goes on rendering: this is where the view records what it decided about the animations
+     * it is running, and only when a theme has asked for the timing diagnostics.
+     */
+    noteVisibilityChange(): void;
+    resumeAutoscroll(): void;
+    /**
+     * Takes this view's lines off the screen, keeping the container they were in, and reports whether
+     * there were any there to take. For a consumer that is about to build the next song into the same
+     * place and wants the last one gone in the meantime: `clear` is the one that drops the song, and
+     * this one drops only what is on the screen.
+     */
+    clearOnScreenLyrics(): boolean;
+    /**
+     * Re-measures the lines on the next frame and renders the view again against them. The predicate
+     * is the caller's half of whether that frame does anything, and only that half: whether the lines
+     * are on the screen to be measured at all is the renderer's own question, and it asks it itself.
+     *
+     * @param isTicking - Whether whoever drives this view is still driving it, asked on the frame
+     *   rather than now. A driver that has stopped is one whose lines may no longer be rendered, and
+     *   an unrendered line measures as zero height at zero offset, which is what every scroll target
+     *   for the rest of the song would then be read off. A false answer declines both the
+     *   re-measurement and the render.
+     * @param retick - Runs after the re-measurement, on the frame.
+     */
+    scheduleLyricPositionUpdate(isTicking: () => boolean, retick: () => void): void;
+    /**
+     * Renders this view again against the last player snapshot, measuring nothing, which is what an
+     * offset nudge needs.
+     *
+     * The snapshot is the module's rather than this renderer's: whichever view in this bundle ticked
+     * last is the one that wrote it, so two renderers in one realm replay each other's clock here.
+     * That is the same constraint the theme settings are under, and `resetPlaybackClock` is what
+     * forgets the snapshot.
+     *
+     * @param buildOptions - Given the snapshot the tick will run against, returns what to render it
+     *   with. Built here rather than handed in, so a caller that reads its settings at tick time still
+     *   reads them at tick time.
+     */
+    retickFromPlaybackClock(buildOptions: (eventCreationTime: number, isPlaying: boolean) => TickOptions): AnimationTickStatus;
+    /** The element this view built its lines into, and null before it has built any. */
+    readonly container: HTMLElement | null;
+    /**
+     * The render records this view built, which are the view's own live state rather than a copy of
+     * it: each one holds the line's element and the `Animation` objects running against it.
+     *
+     * `readonly` freezes the array and nothing else. The records are writable, deliberately, because
+     * rewriting a line's time or hanging a translation off its element is how a consumer decorates a
+     * song that is already built. What it does not do is reach a second view: these elements belong
+     * to this renderer, so a consumer with two of them decorates each one.
+     */
+    readonly lines: readonly LineData[];
+    /** How the loaded lyrics are timed, and `"none"` once there are none loaded. */
+    readonly syncType: LyricSyncType;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/util.d.ts

@@ -0,0 +1,21 @@
+export declare function clamp(value: number, min: number, max: number): number;
+export declare function positiveModulo(value: number, divisor: number): number;
+export declare function roundedMs(value: number): number;
+/**
+ * Converts CSS duration value to milliseconds.
+ *
+ * @returns Duration in milliseconds
+ */
+export declare function toMs(cssDuration: string): number;
+/**
+ * Forces a reflow/repaint of the element by accessing its offsetHeight.
+ *
+ * @param elt - Element to reflow
+ */
+export declare function reflow(elt: HTMLElement): void;
+/**
+ * Returns layout position/dimensions without including transient CSS transforms.
+ * This is important for lyric scroll math because line-scale and per-line scroll
+ * animations are transform based.
+ */
+export declare function getRelativeLayoutBounds(parent: HTMLElement, child: HTMLElement): DOMRect;

package/dist/util.js

@@ -0,0 +1,64 @@
+export function clamp(value, min, max) {
+    return Math.max(min, Math.min(max, value));
+}
+export function positiveModulo(value, divisor) {
+    return ((value % divisor) + divisor) % divisor;
+}
+export function roundedMs(value) {
+    return Math.round(value * 10) / 10;
+}
+/**
+ * Converts CSS duration value to milliseconds.
+ *
+ * @returns Duration in milliseconds
+ */
+export function toMs(cssDuration) {
+    if (!cssDuration)
+        return 0;
+    if (cssDuration.endsWith("ms")) {
+        return parseFloat(cssDuration.slice(0, -2));
+    }
+    else if (cssDuration.endsWith("s")) {
+        return parseFloat(cssDuration.slice(0, -1)) * 1000;
+    }
+    return 0;
+}
+/**
+ * Forces a reflow/repaint of the element by accessing its offsetHeight.
+ *
+ * @param elt - Element to reflow
+ */
+export function reflow(elt) {
+    void elt.offsetHeight;
+}
+/**
+ * Returns the position and dimensions of a child element relative to its parent.
+ *
+ * @param parent - The parent element
+ * @param child - The child element
+ * @returns Rectangle with relative position and dimensions
+ */
+function getRelativeBounds(parent, child) {
+    const parentBound = parent.getBoundingClientRect();
+    const childBound = child.getBoundingClientRect();
+    return new DOMRect(childBound.x - parentBound.x, childBound.y - parentBound.y, childBound.width, childBound.height);
+}
+/**
+ * Returns layout position/dimensions without including transient CSS transforms.
+ * This is important for lyric scroll math because line-scale and per-line scroll
+ * animations are transform based.
+ */
+export function getRelativeLayoutBounds(parent, child) {
+    let x = 0;
+    let y = 0;
+    let element = child;
+    while (element && element !== parent) {
+        x += element.offsetLeft;
+        y += element.offsetTop;
+        element = element.offsetParent;
+    }
+    if (element !== parent) {
+        return getRelativeBounds(parent, child);
+    }
+    return new DOMRect(x, y, Math.max(child.offsetWidth, child.scrollWidth), Math.max(child.offsetHeight, child.scrollHeight));
+}

package/dist/view.d.ts

@@ -0,0 +1,22 @@
+import type { AnimationEngineInstance } from "./engine.js";
+import type { Lyric } from "./types.js";
+export interface SetLyricsOptions {
+    /**
+     * Whether the loader is still covering the view. Recorded on the container for CSS to key on.
+     */
+    loaderVisible: boolean;
+    /**
+     * These lyrics are a "not found" placeholder rather than a real result.
+     */
+    noLyrics: boolean;
+}
+/**
+ * Replaces whatever the mount holds with a container built from these lyrics, and hands the render
+ * records, the container and its measured size to the engine that animates them.
+ *
+ * @param engine - Instance that owns the document to build in and the host to seek through
+ * @param mount - Element whose children the built container replaces
+ * @param lyrics - Lines to render, left untouched
+ * @param options - What the container records for CSS to key on
+ */
+export declare function setLyrics(engine: AnimationEngineInstance, mount: HTMLElement, lyrics: Lyric[], options: SetLyricsOptions): void;

package/dist/view.js

@@ -0,0 +1,93 @@
+// Builds the view: one container under the mount, one element per lyric line, and the render
+// records the engine animates them through. `inject.ts` builds what goes inside a line; this builds
+// the line and everything around it.
+//
+// A song replaces the whole view rather than being diffed into the last one. Every record the
+// engine holds points at an element built here and carries the `Animation` objects running against
+// it, so a partial update would leave the engine holding pieces of the song before.
+//
+// This is also the one place outside the engine that writes engine view state, because building the
+// lines is where those values are first knowable: the container, the records, the sync type, the
+// size they were measured at, and the scrolls to swallow before the view has settled.
+import { LINE_CLASS, LYRICS_CLASS, RTL_CLASS } from "./constants.js";
+import { addSeekHandler, applyDirection, buildLineSyncedParts, createLyricsLine, deriveSyncType, disableRichsync, findNearestAgent, isNearestLyricRtl, newLineData, } from "./inject.js";
+import { createInstrumentalElement } from "./instrumental.js";
+const INITIAL_SKIP_SCROLLS = 2;
+const SKIP_SCROLL_DECAY_MS = 2000;
+function buildInstrumentalLine(doc, lyricElement, lyrics, lineIndex) {
+    createInstrumentalElement(doc, lyricElement, lyrics[lineIndex].durationMs, lineIndex);
+    lyricElement.dataset.instrumental = "true";
+    const agent = findNearestAgent(lyrics, lineIndex);
+    if (agent) {
+        lyricElement.dataset.agent = agent;
+    }
+    if (isNearestLyricRtl(lyrics, lineIndex)) {
+        lyricElement.classList.add(RTL_CLASS);
+        lyricElement.dataset.direction = "rtl";
+    }
+}
+function buildSungLine(doc, lyricElement, lyricItem, line) {
+    // Rebuilt parts stay local so the provider's lyrics survive injection intact and a second
+    // build over the same array produces the same result.
+    const parts = lyricItem.parts && lyricItem.parts.length > 0 && !disableRichsync.getBooleanValue()
+        ? lyricItem.parts
+        : buildLineSyncedParts(lyricItem);
+    applyDirection(lyricElement, lyricItem.words);
+    createLyricsLine(doc, parts, line, lyricElement);
+    lyricElement.style.setProperty("--blyrics-duration", lyricItem.durationMs + "ms");
+    if (lyricItem.agent) {
+        lyricElement.dataset.agent = lyricItem.agent;
+    }
+}
+/**
+ * Replaces whatever the mount holds with a container built from these lyrics, and hands the render
+ * records, the container and its measured size to the engine that animates them.
+ *
+ * @param engine - Instance that owns the document to build in and the host to seek through
+ * @param mount - Element whose children the built container replaces
+ * @param lyrics - Lines to render, left untouched
+ * @param options - What the container records for CSS to key on
+ */
+export function setLyrics(engine, mount, lyrics, options) {
+    const doc = engine.document;
+    const container = doc.createElement("div");
+    container.className = LYRICS_CLASS;
+    mount.replaceChildren(container);
+    const allZero = lyrics.every(item => item.startTimeMs === 0);
+    const seek = (timeS) => engine.host.seek(timeS);
+    const lines = [];
+    const syncType = deriveSyncType(lyrics);
+    for (const [lineIndex, lyricItem] of lyrics.entries()) {
+        const lyricElement = doc.createElement("div");
+        const line = newLineData(lyricElement, lyricItem.startTimeMs, lyricItem.durationMs);
+        lyricElement.dataset.time = String(line.time);
+        lyricElement.dataset.duration = String(line.duration);
+        lyricElement.dataset.lineNumber = String(lineIndex);
+        lyricElement.classList.add(LINE_CLASS);
+        lyricElement.dir = "auto";
+        addSeekHandler(seek, lyricElement, allZero);
+        lines.push(line);
+        if (lyricItem.isInstrumental) {
+            buildInstrumentalLine(doc, lyricElement, lyrics, lineIndex);
+        }
+        else {
+            buildSungLine(doc, lyricElement, lyricItem, line);
+        }
+        container.appendChild(lyricElement);
+    }
+    engine.skipScrolls = INITIAL_SKIP_SCROLLS;
+    engine.skipScrollsDecayTimes = Array.from({ length: INITIAL_SKIP_SCROLLS }, () => Date.now() + SKIP_SCROLL_DECAY_MS);
+    engine.scrollResumeTime = 0;
+    container.dataset.sync = syncType;
+    container.dataset.loaderVisible = String(options.loaderVisible);
+    if (options.noLyrics) {
+        container.dataset.noLyrics = "true";
+    }
+    engine.lines = lines;
+    engine.lyricsContainer = container;
+    engine.syncType = syncType;
+    // Measured last: the container is in the document, filled, and carrying the attributes CSS
+    // sizes it by.
+    engine.lyricWidth = container.clientWidth;
+    engine.lyricHeight = container.clientHeight;
+}

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@braccato/core",
-  "version": "0.1.6",
-  "description": "Synchronized lyrics web component with word-by-word animations",
+  "version": "1.0.0",
+  "description": "Synchronized lyrics renderer with word-by-word animations",
   "type": "module",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/better-lyrics/braccato",
+    "url": "git+https://github.com/better-lyrics/braccato.git",
     "directory": "packages/core"
   },
   "homepage": "https://braccato.boidu.dev",
@@ -14,19 +14,41 @@
     "lyrics",
     "sync",
     "web-component",
-    "lit",
     "music",
     "karaoke",
     "ttml"
   ],
-  "sideEffects": true,
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "sideEffects": [
+    "./dist/element.js",
+    "./dist/styles/*.css"
+  ],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
-    }
+    },
+    "./element": {
+      "types": "./dist/element.d.ts",
+      "import": "./dist/element.js"
+    },
+    "./constants": {
+      "types": "./dist/constants.d.ts",
+      "import": "./dist/constants.js"
+    },
+    "./text": {
+      "types": "./dist/text.d.ts",
+      "import": "./dist/text.js"
+    },
+    "./themeSettings": {
+      "types": "./dist/themeSettings.d.ts",
+      "import": "./dist/themeSettings.js"
+    },
+    "./util": {
+      "types": "./dist/util.d.ts",
+      "import": "./dist/util.js"
+    },
+    "./styles/*.css": "./dist/styles/*.css",
+    "./package.json": "./package.json"
   },
   "files": [
     "dist"
@@ -35,21 +57,12 @@
     "access": "public"
   },
   "dependencies": {
-    "lit": "^3.2.1",
-    "@braccato/parsers": "^0.1.2"
-  },
-  "devDependencies": {
-    "jsdom": "^28.1.0",
-    "typescript": "^5.7.3",
-    "vite": "^6.0.7",
-    "vite-plugin-dts": "^4.3.0",
-    "vitest": "^3.0.4"
+    "@braccato/types": "^1.0.0"
   },
   "scripts": {
-    "build": "vite build",
-    "dev": "vite build --watch",
+    "build": "tsx ../../tooling/build-package.ts",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest"
+    "selfcheck": "tsx ../../tooling/run-selfchecks.ts",
+    "clean": "rm -rf dist"
   }
 }