@braccato/core 1.1.0 → 1.2.0

package/README.md

@@ -179,6 +179,13 @@ The ones a theme reaches for first. `variables.css` declares the rest.
 `line-height`. Every word is given the glow, so a theme that wants it to mean something selects on
 `data-long-word`, which the module sets on any part held past `blyrics-long-word-threshold`.
 
+The instrumental ripple is the one place a property carries geometry rather than a value.
+`--blyrics-instrumental-wave-path-high` and `--blyrics-instrumental-wave-path-low` are the two shapes
+it morphs between, each a `path()`, and a theme redrawing them is how the wave changes amplitude or
+frequency. Both must use the same commands in the same order with the same number of arguments: a
+browser only interpolates two paths smoothly when their command sequences match, and a mismatched
+pair snaps at the halfway point instead of flowing.
+
 ### Class names
 
 These are published API rather than implementation. Renaming one costs a migration rather than a

package/dist/README.md

@@ -179,6 +179,13 @@ The ones a theme reaches for first. `variables.css` declares the rest.
 `line-height`. Every word is given the glow, so a theme that wants it to mean something selects on
 `data-long-word`, which the module sets on any part held past `blyrics-long-word-threshold`.
 
+The instrumental ripple is the one place a property carries geometry rather than a value.
+`--blyrics-instrumental-wave-path-high` and `--blyrics-instrumental-wave-path-low` are the two shapes
+it morphs between, each a `path()`, and a theme redrawing them is how the wave changes amplitude or
+frequency. Both must use the same commands in the same order with the same number of arguments: a
+browser only interpolates two paths smoothly when their command sequences match, and a mismatched
+pair snaps at the halfway point instead of flowing.
+
 ### Class names
 
 These are published API rather than implementation. Renaming one costs a migration rather than a

package/dist/engine.d.ts

@@ -184,6 +184,8 @@ interface AnimationConfig {
         waveFrom: string;
         waveTo: string;
         waveEasing: string;
+        wavePathHigh: string;
+        wavePathLow: string;
         waveOscillationDurationMs: number;
         waveOscillationEasing: string;
     };

package/dist/engine.js

@@ -17,6 +17,7 @@
 // module is bundled into the isolated world and the page world separately, so those are two clocks
 // that never meet. `themeSettings.ts` holds the third thing under that rule.
 import { ANIMATING_CLASS, CURRENT_LYRICS_CLASS, FOOTER_CLASS, LINE_CLASS, PAUSED_CLASS, USER_SCROLLING_CLASS, } from "./constants.js";
+import { INSTRUMENTAL_WAVE_PATH_HIGH, INSTRUMENTAL_WAVE_PATH_LOW } from "./instrumental.js";
 import { registerThemeSetting } from "./themeSettings.js";
 import { clamp, getRelativeLayoutBounds, positiveModulo, roundedMs, toMs } from "./util.js";
 const NO_LYRICS_ELEMENT_LOG = "No lyrics element found on the page, skipping lyrics injection";
@@ -326,8 +327,8 @@ const WORD_HIGHLIGHT_SELECTOR = ".blyrics-word-highlight";
 const INSTRUMENTAL_FILL_SELECTOR = ".blyrics--instrumental-fill";
 const INSTRUMENTAL_WAVE_CLIP_SELECTOR = ".blyrics--wave-clip";
 const INSTRUMENTAL_WAVE_PATH_SELECTOR = ".blyrics--wave-path";
-const INSTRUMENTAL_WAVE_PATH_HIGH = 'path("M -4 3 Q 1 2 5 3 Q 10 4 14 3 Q 18 2 22 3 Q 26 4 30 3 L 30 4 L -4 4 Z")';
-const INSTRUMENTAL_WAVE_PATH_LOW = 'path("M -4 3 Q 1 4 5 3 Q 10 2 14 3 Q 18 4 22 3 Q 26 2 30 3 L 30 4 L -4 4 Z")';
+const INSTRUMENTAL_WAVE_PATH_HIGH_FALLBACK = `path("${INSTRUMENTAL_WAVE_PATH_HIGH}")`;
+const INSTRUMENTAL_WAVE_PATH_LOW_FALLBACK = `path("${INSTRUMENTAL_WAVE_PATH_LOW}")`;
 const LINE_SCROLL_INDEX_PROPERTY = "--blyrics-line-scroll-index";
 const LINE_SCROLL_ACTIVE_INDEX_PROPERTY = "--blyrics-line-scroll-active-index";
 const LINE_SCROLL_RELATIVE_INDEX_PROPERTY = "--blyrics-line-scroll-relative-index";
@@ -856,9 +857,9 @@ function startInstrumentalAnimations(engine, lineData, config, currentTime, appl
             fill: "both",
         }, { appliedTimingOffsetMs, offsetMs: 0 });
         waveOscillationAnimation = animateInstrumentalChild(engine, lineData, INSTRUMENTAL_WAVE_PATH_SELECTOR, [
-            { d: INSTRUMENTAL_WAVE_PATH_HIGH },
-            { d: INSTRUMENTAL_WAVE_PATH_LOW, offset: 0.5 },
-            { d: INSTRUMENTAL_WAVE_PATH_HIGH },
+            { d: config.instrumental.wavePathHigh },
+            { d: config.instrumental.wavePathLow, offset: 0.5 },
+            { d: config.instrumental.wavePathHigh },
         ], {
             duration: config.instrumental.waveOscillationDurationMs,
             easing: config.instrumental.waveOscillationEasing,
@@ -1016,6 +1017,8 @@ function readAnimationConfig(engine, lyricsElement) {
             waveFrom: getCSSValue(engine, lyricsElement, "--blyrics-instrumental-wave-transform-from", "scaleY(1.2)"),
             waveTo: getCSSValue(engine, lyricsElement, "--blyrics-instrumental-wave-transform-to", "scaleY(0.0001)"),
             waveEasing: getCSSValue(engine, lyricsElement, "--blyrics-instrumental-wave-easing", "ease-in"),
+            wavePathHigh: getCSSValue(engine, lyricsElement, "--blyrics-instrumental-wave-path-high", INSTRUMENTAL_WAVE_PATH_HIGH_FALLBACK),
+            wavePathLow: getCSSValue(engine, lyricsElement, "--blyrics-instrumental-wave-path-low", INSTRUMENTAL_WAVE_PATH_LOW_FALLBACK),
             waveOscillationDurationMs: getCSSDurationWithFallback(engine, lyricsElement, "--blyrics-instrumental-wave-oscillation-duration", "1.25s"),
             waveOscillationEasing: getCSSValue(engine, lyricsElement, "--blyrics-instrumental-wave-oscillation-easing", "ease-in-out"),
         },
@@ -1560,6 +1563,7 @@ export function tickView(engine, currentTime, options) {
         }
         const tabRendererHeight = engine.cachedTabRendererHeight ?? tabRenderer.getBoundingClientRect().height;
         let scrollTop = tabRenderer.scrollTop;
+        const maxScrollTop = Math.max(0, tabRenderer.scrollHeight - tabRenderer.clientHeight);
         if (animationConfig.enabled.scroll) {
             updateVisibleLyricWillChange(engine, lines, scrollTop, engine.pendingLineScroll?.toScrollTop ?? scrollTop, tabRendererHeight);
         }
@@ -1713,8 +1717,9 @@ export function tickView(engine, currentTime, options) {
             scrollPos = Math.max(scrollPos, lastActiveLyric.position - tabRendererHeight + lastActiveLyric.height);
             // Make sure top of last active lyric is visible.
             scrollPos = Math.min(scrollPos, lastActiveLyric.position);
-            // Make sure we're not trying to scroll to negative values
-            scrollPos = Math.max(0, scrollPos);
+            // Past either end the browser clamps the write and reports nothing, leaving the view aiming
+            // at a position it never reached and re-aiming once per remaining line.
+            scrollPos = clamp(scrollPos, 0, maxScrollTop);
             if (ENABLE_DEBUG_RENDER.getBooleanValue()) {
                 let transform = engine.window.getComputedStyle(lyricsElement).transform;
                 const matrix = new engine.window.DOMMatrix(transform);
@@ -1899,6 +1904,9 @@ function applyScrollPadding(engine) {
     });
     engine.document.documentElement.style.setProperty("--blyrics-padding-top", top + "px");
     engine.document.documentElement.style.setProperty("--blyrics-padding-bottom", bottom + "px");
+    // Inline, because a theme's own `.blyrics-container { padding }` is appended after the package's
+    // stylesheet at the same weight and would otherwise take this room away.
+    lyricsElement.style.setProperty("padding-bottom", bottom + "px");
 }
 /**
  * Re-reads the view's layout: the scroll padding first, then the line positions the padding moved.

package/dist/instrumental.d.ts

@@ -1,3 +1,5 @@
+export declare const INSTRUMENTAL_WAVE_PATH_HIGH = "M -4 3 Q 1 2 5 3 Q 10 4 14 3 Q 18 2 22 3 Q 26 4 30 3 L 30 4 L -4 4 Z";
+export declare const INSTRUMENTAL_WAVE_PATH_LOW = "M -4 3 Q 1 4 5 3 Q 10 2 14 3 Q 18 4 22 3 Q 26 2 30 3 L 30 4 L -4 4 Z";
 /**
  * Creates an HTML element representing an instrumental break in the lyrics.
  *

package/dist/instrumental.js

@@ -1,3 +1,5 @@
+export const INSTRUMENTAL_WAVE_PATH_HIGH = "M -4 3 Q 1 2 5 3 Q 10 4 14 3 Q 18 2 22 3 Q 26 4 30 3 L 30 4 L -4 4 Z";
+export const INSTRUMENTAL_WAVE_PATH_LOW = "M -4 3 Q 1 4 5 3 Q 10 2 14 3 Q 18 4 22 3 Q 26 2 30 3 L 30 4 L -4 4 Z";
 /**
  * Creates an HTML element representing an instrumental break in the lyrics.
  *
@@ -56,8 +58,7 @@ export function createInstrumentalElement(doc, container, durationMs, lineIndex)
     // This only contains the surface water. It closes at y=4.
     const wavePath = doc.createElementNS(svgNS, "path");
     wavePath.classList.add("blyrics--wave-path");
-    // Initial draw (matches the 0% keyframe below)
-    wavePath.setAttribute("d", "M -4 3 Q 1 2 5 3 Q 10 4 14 3 Q 18 2 22 3 Q 26 4 30 3 L 30 4 L -4 4 Z");
+    wavePath.setAttribute("d", INSTRUMENTAL_WAVE_PATH_HIGH);
     clipPath.appendChild(wavePath);
     defs.appendChild(clipPath);
     svg.appendChild(defs);

package/dist/renderer.js

@@ -269,6 +269,10 @@ export function createLyricsRenderer(rendererOptions) {
             // Everything the engine resolved off the document was resolved against the theme that just
             // went away.
             clearEngineStyleCaches(engine);
+            // The target scroll position is one of the settings a theme carries, and the scroll padding is
+            // sized against it, so a theme that moves the target moves the layout even when no rule in it
+            // does.
+            measure();
             return needsLyricRebuild;
         },
         tick(currentTimeS, options) {

package/dist/styles/instrumental.css

@@ -69,6 +69,8 @@
 
 	/* Prepare the WAAPI flatten transition. */
 	transform: scaleY(1.2);
+
+	d: var(--blyrics-instrumental-wave-path-high);
 }
 
 /* Trigger the Flattening */
@@ -90,14 +92,3 @@
 	transition-timing-function: ease-out;
 	transition-delay: 0s;
 }
-
-/* Update Keyframes for the "Split" shape */
-/* These paths must close at 'L 30 4 L -4 4' to match the static rect overlap */
-@keyframes blyrics-wave {
-	0%, 100% {
-		d: path("M -4 3 Q 1 2 5 3 Q 10 4 14 3 Q 18 2 22 3 Q 26 4 30 3 L 30 4 L -4 4 Z");
-	}
-	50% {
-		d: path("M -4 3 Q 1 4 5 3 Q 10 2 14 3 Q 18 4 22 3 Q 26 2 30 3 L 30 4 L -4 4 Z");
-	}
-}

package/dist/styles/variables.css

@@ -117,6 +117,8 @@
 	--blyrics-instrumental-wave-transform-from: scaleY(1.2);
 	--blyrics-instrumental-wave-transform-to: scaleY(0.0001);
 	--blyrics-instrumental-wave-easing: ease-in;
+	--blyrics-instrumental-wave-path-high: path("M -4 3 Q 1 2 5 3 Q 10 4 14 3 Q 18 2 22 3 Q 26 4 30 3 L 30 4 L -4 4 Z");
+	--blyrics-instrumental-wave-path-low: path("M -4 3 Q 1 4 5 3 Q 10 2 14 3 Q 18 4 22 3 Q 26 2 30 3 L 30 4 L -4 4 Z");
 	--blyrics-instrumental-wave-oscillation-duration: 1.25s;
 	--blyrics-instrumental-wave-oscillation-easing: ease-in-out;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@braccato/core",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Synchronized lyrics renderer with word-by-word animations",
   "type": "module",
   "license": "MIT",