@braccato/core 1.8.0 → 1.10.0

package/README.md

@@ -150,6 +150,46 @@ stylesheet must not be able to configure the module by accident. An empty theme
 back to its default. The stylesheet itself goes into the document head under the
 `blyrics-custom-style` id.
 
+A comment setting holds one value for every view in the bundle. The target scroll position can
+also be set per view: when `--blyrics-target-scroll-pos-ratio` resolves on `.blyrics-container`, it
+wins over `blyrics-target-scroll-pos-ratio`, so an ordinary selector scopes it to one view. It takes
+a unitless number, clamped to `0` to `1`; anything else falls back to the comment setting. Like the
+other custom properties the module reads, it is read once per theme, so the selector has to match
+before the theme is applied.
+
+```css
+/* blyrics-target-scroll-pos-ratio = 0.5; */
+.pip-view .blyrics-container {
+  --blyrics-target-scroll-pos-ratio: 0.37;
+}
+```
+
+### Autoscroll grouping and animation
+
+`blyrics-early-scroll-consider-s` is a comment setting with an independent default of `0.54`
+seconds. When a lyric reaches its scroll time, the renderer includes nearby upcoming lines in
+its target calculation. Entering the lookahead window alone does not scroll. A line already
+included in a committed scroll does not scroll again when its own time arrives. Seeking,
+resuming autoscroll and relayout can still reposition the view.
+
+```css
+/* blyrics-early-scroll-consider-s = 0.54; */
+/* blyrics-line-scroll-duration = 750ms; */
+```
+
+New groups scroll immediately. Previous per-line `translate` animations continue and compose
+additively, so their duration does not block the next scroll. The line-scroll duration knobs
+control visual motion. The legacy `--blyrics-lyric-scroll-duration` variable and its
+`--blyrics-lyric-transition-duration` alias have been removed, along with the container transform
+transition. `blyrics-queue-scroll-ms` is ignored, and no timing equation needs balancing.
+Missing or invalid line durations fall back to an internal `750ms` duration; nonpositive resolved
+durations also use that fallback. Themes should set the line-scroll duration knobs directly
+instead of referencing the removed variables.
+
+Themes that previously relied on duration-derived lookahead should set their preferred
+`blyrics-early-scroll-consider-s` explicitly. The default remains close to the former default
+of approximately `0.54s`, but a custom animation duration no longer changes grouping.
+
 There is no `longWordThreshold`, `lineSyncedDelay` or `disableRichsync` property. Those are theme
 settings (`blyrics-long-word-threshold`, `blyrics-line-synced-animation-delay`,
 `blyrics-disable-richsync`), read from the stylesheet you already hand over. A theme that set one

package/dist/README.md

@@ -150,6 +150,46 @@ stylesheet must not be able to configure the module by accident. An empty theme
 back to its default. The stylesheet itself goes into the document head under the
 `blyrics-custom-style` id.
 
+A comment setting holds one value for every view in the bundle. The target scroll position can
+also be set per view: when `--blyrics-target-scroll-pos-ratio` resolves on `.blyrics-container`, it
+wins over `blyrics-target-scroll-pos-ratio`, so an ordinary selector scopes it to one view. It takes
+a unitless number, clamped to `0` to `1`; anything else falls back to the comment setting. Like the
+other custom properties the module reads, it is read once per theme, so the selector has to match
+before the theme is applied.
+
+```css
+/* blyrics-target-scroll-pos-ratio = 0.5; */
+.pip-view .blyrics-container {
+  --blyrics-target-scroll-pos-ratio: 0.37;
+}
+```
+
+### Autoscroll grouping and animation
+
+`blyrics-early-scroll-consider-s` is a comment setting with an independent default of `0.54`
+seconds. When a lyric reaches its scroll time, the renderer includes nearby upcoming lines in
+its target calculation. Entering the lookahead window alone does not scroll. A line already
+included in a committed scroll does not scroll again when its own time arrives. Seeking,
+resuming autoscroll and relayout can still reposition the view.
+
+```css
+/* blyrics-early-scroll-consider-s = 0.54; */
+/* blyrics-line-scroll-duration = 750ms; */
+```
+
+New groups scroll immediately. Previous per-line `translate` animations continue and compose
+additively, so their duration does not block the next scroll. The line-scroll duration knobs
+control visual motion. The legacy `--blyrics-lyric-scroll-duration` variable and its
+`--blyrics-lyric-transition-duration` alias have been removed, along with the container transform
+transition. `blyrics-queue-scroll-ms` is ignored, and no timing equation needs balancing.
+Missing or invalid line durations fall back to an internal `750ms` duration; nonpositive resolved
+durations also use that fallback. Themes should set the line-scroll duration knobs directly
+instead of referencing the removed variables.
+
+Themes that previously relied on duration-derived lookahead should set their preferred
+`blyrics-early-scroll-consider-s` explicitly. The default remains close to the former default
+of approximately `0.54s`, but a custom animation duration no longer changes grouping.
+
 There is no `longWordThreshold`, `lineSyncedDelay` or `disableRichsync` property. Those are theme
 settings (`blyrics-long-word-threshold`, `blyrics-line-synced-animation-delay`,
 `blyrics-disable-richsync`), read from the stylesheet you already hand over. A theme that set one

package/dist/engine.d.ts

@@ -19,10 +19,8 @@ interface AnimEngineViewState {
     scrollResumeTime: number;
     scrollPos: number;
     selectedElementIndex: number;
-    nextScrollAllowedTime: number;
     wasUserScrolling: boolean;
-    lastActiveElements: LineData[];
-    queuedScroll: boolean;
+    lastScrollElements: LineData[];
     lastScrollDebugContext: {
         activeElms: LineData[];
         centers: number[];
@@ -210,12 +208,7 @@ interface AnimationConfig {
         waveOscillationDurationMs: number;
         waveOscillationEasing: string;
     };
-    scroll: {
-        durationMs: number;
-        easing: string;
-    };
     lineScroll: {
-        durationMs: number;
         easing: string;
         differentialEffects: boolean;
     };
@@ -224,7 +217,6 @@ interface AnimationSettings {
     config: AnimationConfig;
     scrollTiming: {
         earlyScrollConsiderS: number;
-        queueScrollMs: number;
     };
 }
 export declare function noteVisibilityChange(engine: AnimationEngineInstance): void;

package/dist/engine.js

@@ -26,18 +26,11 @@ const PAUSING_LYRICS_SCROLL_LOG = "Pausing Lyrics Autoscroll Due to User Scroll"
 const USER_SCROLL_RESUME_DELAY_MS = 25000;
 const PASSIVE_USER_SCROLL_RESUME_DELAY_MS = 5000;
 const LYRIC_ENDING_THRESHOLD_S = registerThemeSetting("blyrics-lyric-ending-threshold-s", 0.5);
-const EARLY_SCROLL_CONSIDER = registerThemeSetting("blyrics-early-scroll-consider-s", 0.62);
-const QUEUE_SCROLL_THRESHOLD = registerThemeSetting("blyrics-queue-scroll-ms", 150);
+const EARLY_SCROLL_CONSIDER = registerThemeSetting("blyrics-early-scroll-consider-s", 0.54);
 const TIME_JUMP_THRESHOLD = 0.5;
 const REDUCED_MOTION_QUERY = "(prefers-reduced-motion: reduce)";
-const SCROLL_TIMING_RATIO_BASE_DURATION_MS = 750;
-const SCROLL_TIMING_RATIO_BASE_EARLY_SCROLL_CONSIDER_S = 0.62;
-const SCROLL_TIMING_RATIO_BASE_QUEUE_SCROLL_THRESHOLD_MS = 150;
-const MAX_AUTO_QUEUE_SCROLL_THRESHOLD_MS = 200;
 const SCROLL_PREPARE_LEAD_MS = 120;
-const SCROLL_TIMING_RATIO_BASE_TOTAL_MS = SCROLL_TIMING_RATIO_BASE_EARLY_SCROLL_CONSIDER_S * 1000 + SCROLL_TIMING_RATIO_BASE_QUEUE_SCROLL_THRESHOLD_MS;
-const SCROLL_TIMING_BUFFER_MS = SCROLL_TIMING_RATIO_BASE_TOTAL_MS - SCROLL_TIMING_RATIO_BASE_DURATION_MS;
-const AUTO_QUEUE_SCROLL_RATIO = SCROLL_TIMING_RATIO_BASE_QUEUE_SCROLL_THRESHOLD_MS / SCROLL_TIMING_RATIO_BASE_TOTAL_MS;
+const LINE_SCROLL_FALLBACK_DURATION_MS = 750;
 const SWIPE_LEAD_RATIO = registerThemeSetting("blyrics-swipe-lead-ratio", 0.1);
 const SWIPE_DURATION_RATIO = registerThemeSetting("blyrics-swipe-duration-ratio", 1.6);
 const ENABLE_DEBUG_RENDER = registerThemeSetting("blyrics-debug-renderer", false);
@@ -125,10 +118,8 @@ export function createAnimationEngineInstance(engineDocument, engineWindow, host
         scrollResumeTime: 0,
         scrollPos: 0,
         selectedElementIndex: 0,
-        nextScrollAllowedTime: 0,
         wasUserScrolling: false,
-        lastActiveElements: [],
-        queuedScroll: false,
+        lastScrollElements: [],
         lastScrollDebugContext: {
             activeElms: [],
             centers: [],
@@ -237,7 +228,6 @@ export function noteUserScroll(engine, isPassive) {
 export function noteContainerResize(engine, width, height) {
     if (width === engine.lyricWidth && height === engine.lyricHeight)
         return false;
-    engine.nextScrollAllowedTime = 0;
     return true;
 }
 /**
@@ -282,10 +272,9 @@ export function clearLyrics(engine) {
         line.isSelected = false;
     }
     engine.skipScrollsDecayTimes = [];
-    engine.lastActiveElements = [];
+    engine.lastScrollElements = [];
     engine.lastScrollDebugContext.activeElms = [];
     engine.lastScrollDebugContext.centers = [];
-    engine.queuedScroll = false;
     engine.passiveScrollAccumulatedTime = 0;
     engine.passiveLastWallTime = 0;
     stopPassiveScrollLoop(engine);
@@ -1127,6 +1116,11 @@ function getCSSBoolean(engine, lyricsElement, property, fallback) {
 function getCSSOffset(engine, lyricsElement, property, fallback) {
     return Math.max(0, Math.min(1, getCSSNumber(engine, lyricsElement, property, fallback)));
 }
+// The comment setting is shared by every view in a bundle; the custom property lets a theme scope it to one.
+function getTargetScrollRatio(engine, lyricsElement) {
+    const scoped = Number.parseFloat(getCSSValue(engine, lyricsElement, "--blyrics-target-scroll-pos-ratio", ""));
+    return Number.isFinite(scoped) ? Math.max(0, Math.min(1, scoped)) : SCROLL_POS_OFFSET_RATIO.getNumberValue();
+}
 // Compose the glow filter so the color stays an unresolved var(--blyrics-glow-color).
 // Reading a fully composed --blyrics-highlight-glow-filter-* off the container resolves the
 // nested color there, which would defeat per-word overrides like
@@ -1198,7 +1192,6 @@ function isGlowRestingInvisible(glowTo) {
 }
 function readAnimationConfig(engine, lyricsElement) {
     const prefersReducedMotion = engine.window.matchMedia(REDUCED_MOTION_QUERY).matches;
-    const scrollDurationMs = getCSSDurationWithFallback(engine, lyricsElement, "--blyrics-lyric-scroll-duration", "650ms");
     const scrollEasing = getCSSValue(engine, lyricsElement, "--blyrics-lyric-scroll-timing-function", "cubic-bezier(0.86, 0, 0.2, 1)");
     return {
         enabled: {
@@ -1271,53 +1264,21 @@ function readAnimationConfig(engine, lyricsElement) {
             waveOscillationDurationMs: getCSSDurationWithFallback(engine, lyricsElement, "--blyrics-instrumental-wave-oscillation-duration", "1.25s"),
             waveOscillationEasing: getCSSValue(engine, lyricsElement, "--blyrics-instrumental-wave-oscillation-easing", "ease-in-out"),
         },
-        scroll: {
-            durationMs: scrollDurationMs,
-            easing: scrollEasing,
-        },
         lineScroll: {
-            durationMs: scrollDurationMs,
             easing: scrollEasing,
             differentialEffects: !prefersReducedMotion,
         },
     };
 }
-function readScrollTiming(scrollDurationMs) {
-    const totalMs = Math.max(0, scrollDurationMs + SCROLL_TIMING_BUFFER_MS);
-    const earlyScrollConsiderWasSet = EARLY_SCROLL_CONSIDER.isManuallySet();
-    const queueScrollWasSet = QUEUE_SCROLL_THRESHOLD.isManuallySet();
-    if (earlyScrollConsiderWasSet && queueScrollWasSet) {
-        return {
-            earlyScrollConsiderS: Math.max(0, EARLY_SCROLL_CONSIDER.getNumberValue()),
-            queueScrollMs: Math.max(0, QUEUE_SCROLL_THRESHOLD.getNumberValue()),
-        };
-    }
-    if (earlyScrollConsiderWasSet) {
-        const earlyScrollConsiderS = Math.max(0, EARLY_SCROLL_CONSIDER.getNumberValue());
-        return {
-            earlyScrollConsiderS,
-            queueScrollMs: Math.min(Math.max(0, totalMs - earlyScrollConsiderS * 1000), MAX_AUTO_QUEUE_SCROLL_THRESHOLD_MS),
-        };
-    }
-    if (queueScrollWasSet) {
-        const queueScrollMs = Math.max(0, QUEUE_SCROLL_THRESHOLD.getNumberValue());
-        return {
-            earlyScrollConsiderS: Math.max(0, (totalMs - queueScrollMs) / 1000),
-            queueScrollMs,
-        };
-    }
-    const queueScrollMs = Math.min(totalMs * AUTO_QUEUE_SCROLL_RATIO, MAX_AUTO_QUEUE_SCROLL_THRESHOLD_MS);
-    return {
-        earlyScrollConsiderS: Math.max(0, (totalMs - queueScrollMs) / 1000),
-        queueScrollMs,
-    };
+function readScrollTiming() {
+    return { earlyScrollConsiderS: Math.max(0, EARLY_SCROLL_CONSIDER.getNumberValue()) };
 }
 function getAnimationSettings(engine, lyricsElement) {
     if (!engine.cachedAnimationSettings) {
         const config = readAnimationConfig(engine, lyricsElement);
         engine.cachedAnimationSettings = {
             config,
-            scrollTiming: readScrollTiming(config.scroll.durationMs),
+            scrollTiming: readScrollTiming(),
         };
     }
     return engine.cachedAnimationSettings;
@@ -1557,9 +1518,9 @@ function prepareLineScrollOffsets(engine, lines, activeLineIndex, scrollDeltaPx,
     const misses = requests.filter(request => !request.timing);
     if (misses.length > 0) {
         const missItems = misses.map(request => request.item);
-        const durations = batchResolveLineScrollProperty(engine, missItems, "transition-duration", item => lineScrollDurationProperty(item.side, config.lineScroll.durationMs, config.lineScroll.differentialEffects), style => {
+        const durations = batchResolveLineScrollProperty(engine, missItems, "transition-duration", item => lineScrollDurationProperty(item.side, LINE_SCROLL_FALLBACK_DURATION_MS, config.lineScroll.differentialEffects), style => {
             const durationMs = toMs(style.transitionDuration.split(",")[0].trim());
-            return durationMs > 0 ? durationMs : config.lineScroll.durationMs;
+            return durationMs > 0 ? durationMs : LINE_SCROLL_FALLBACK_DURATION_MS;
         });
         const startEasings = batchResolveLineScrollProperty(engine, missItems, "transition-timing-function", item => lineScrollEasingProperty(item.side, "start", config.lineScroll.easing, config.lineScroll.differentialEffects), style => style.transitionTimingFunction.trim() || config.lineScroll.easing);
         const endEasings = batchResolveLineScrollProperty(engine, missItems, "transition-timing-function", item => lineScrollEasingProperty(item.side, "end", config.lineScroll.easing, config.lineScroll.differentialEffects), style => style.transitionTimingFunction.trim() || config.lineScroll.easing);
@@ -1918,7 +1879,7 @@ export function tickView(engine, currentTime, options) {
             if (lyricScrollTime >= time - scrollTiming.earlyScrollConsiderS &&
                 (lyricScrollTime < nextTime || lyricScrollTime < time + lineData.duration)) {
                 activeElems.push(lineData);
-                if (!engine.lastActiveElements.includes(lineData) && lyricScrollTime >= time) {
+                if (!engine.lastScrollElements.includes(lineData) && lyricScrollTime >= time) {
                     newLyricSelected = true;
                 }
                 // const timeDelta = lyricScrollTime - time;
@@ -2032,10 +1993,8 @@ export function tickView(engine, currentTime, options) {
             if (activeElems.length == 0) {
                 activeElems.push(lines[0]);
             }
-            engine.lastActiveElements = activeElems.filter(elm => lyricScrollTime >= elm.time // remove elements that haven't reached their scroll time yet.
-            );
             // Offset so lyrics appear towards the center of the screen.
-            const scrollPosOffset = tabRendererHeight * SCROLL_POS_OFFSET_RATIO.getNumberValue();
+            const scrollPosOffset = tabRendererHeight * getTargetScrollRatio(engine, lyricsElement);
             let lastActiveLyric = activeElems[activeElems.length - 1];
             let lyricPositions = activeElems
                 .filter((lineData, index) => {
@@ -2134,39 +2093,34 @@ export function tickView(engine, currentTime, options) {
                 !engine.wasUserScrolling &&
                 timeUntilUpcomingScrollMs > 0 &&
                 timeUntilUpcomingScrollMs <= SCROLL_PREPARE_LEAD_MS &&
-                Date.now() > engine.nextScrollAllowedTime &&
+                !engine.lastScrollElements.includes(lastActiveLyric) &&
                 Math.abs(scrollTop - scrollPos) > 2) {
                 updateVisibleLyricWillChange(engine, lines, scrollTop, scrollPos, tabRendererHeight);
                 prepareUpcomingLineScroll(engine, getLineScrollItems(engine, lines), lastActiveLyric, scrollPos - scrollTop, scrollTop, scrollPos, tabRendererHeight, animationConfig);
             }
-            if (engine.wasUserScrolling || newLyricSelected || engine.queuedScroll) {
-                if (Date.now() > engine.nextScrollAllowedTime) {
-                    engine.queuedScroll = false;
-                    engine.lastScrollDebugContext.lyricScrollTime = lyricScrollTime;
-                    engine.lastScrollDebugContext.centers = lyricPositions;
-                    engine.lastScrollDebugContext.activeElms = activeElems;
-                    if (smoothScroll && Math.abs(scrollTop - scrollPos) > 2) {
-                        const scrollDeltaPx = scrollPos - scrollTop;
-                        if (animationConfig.enabled.scroll) {
-                            updateVisibleLyricWillChange(engine, lines, scrollTop, scrollPos, tabRendererHeight);
-                            const lineScrollItems = getLineScrollItems(engine, lines);
-                            commitOrPrepareLineScroll(engine, lineScrollItems, lastActiveLyric, scrollDeltaPx, scrollTop, scrollPos, tabRendererHeight, animationConfig);
-                            engine.nextScrollAllowedTime = animationConfig.scroll.durationMs + Date.now() + 20;
-                        }
-                    }
-                    else {
-                        dropPendingLineScroll(engine);
+            if (engine.wasUserScrolling || newLyricSelected) {
+                // Remember future lines only when their group is committed, so they cannot scroll
+                // again at their start. Entering the lookahead window alone does not commit a group.
+                engine.lastScrollElements = activeElems;
+                engine.lastScrollDebugContext.lyricScrollTime = lyricScrollTime;
+                engine.lastScrollDebugContext.centers = lyricPositions;
+                engine.lastScrollDebugContext.activeElms = activeElems;
+                if (smoothScroll && Math.abs(scrollTop - scrollPos) > 2) {
+                    const scrollDeltaPx = scrollPos - scrollTop;
+                    if (animationConfig.enabled.scroll) {
+                        updateVisibleLyricWillChange(engine, lines, scrollTop, scrollPos, tabRendererHeight);
+                        const lineScrollItems = getLineScrollItems(engine, lines);
+                        commitOrPrepareLineScroll(engine, lineScrollItems, lastActiveLyric, scrollDeltaPx, scrollTop, scrollPos, tabRendererHeight, animationConfig);
                     }
-                    scrollTop = scrollPos;
-                    engine.scrollPos = scrollTop;
-                    tabRenderer.scrollTop = scrollTop;
-                    engine.skipScrolls += 1;
-                    engine.skipScrollsDecayTimes.push(Date.now() + 2000);
                 }
-                else if (engine.nextScrollAllowedTime - Date.now() < scrollTiming.queueScrollMs || timeJumped) {
-                    // just missed out on being able to scroll, queue this once we finish our current lyric
-                    engine.queuedScroll = true;
+                else {
+                    dropPendingLineScroll(engine);
                 }
+                scrollTop = scrollPos;
+                engine.scrollPos = scrollTop;
+                tabRenderer.scrollTop = scrollTop;
+                engine.skipScrolls += 1;
+                engine.skipScrollsDecayTimes.push(Date.now() + 2000);
             }
         }
         if (engine.wasUserScrolling && engine.scrollResumeTime < Date.now()) {
@@ -2223,7 +2177,7 @@ function applyScrollPadding(engine) {
     if (!lyricsElement || !tabRenderer)
         return;
     const tabRendererHeight = tabRenderer.getBoundingClientRect().height;
-    const scrollPosOffsetRatio = SCROLL_POS_OFFSET_RATIO.getNumberValue();
+    const scrollPosOffsetRatio = getTargetScrollRatio(engine, lyricsElement);
     const currentPaddingBottom = Number.parseFloat(engine.window.getComputedStyle(lyricsElement).paddingBottom) || 0;
     const lyricsHeightWithoutBottomPadding = Math.max(0, lyricsElement.scrollHeight - currentPaddingBottom);
     const lyricLines = lyricsElement.querySelectorAll(`:scope > .${LINE_CLASS}`);

package/dist/styles/lyrics.css

@@ -21,8 +21,6 @@
 	padding-bottom: calc(var(--blyrics-padding-bottom));
 	padding-top: 2rem;
 	position: relative !important;
-	transition: transform var(--blyrics-lyric-scroll-duration)
-		var(--blyrics-lyric-scroll-timing-function) 0s;
 	will-change: transform;
 	z-index: 1;
 }

package/dist/styles/variables.css

@@ -143,11 +143,7 @@
 	--blyrics-background-blur: 100px;
 	--blyrics-background-saturate: 2;
 
-	/* Lyric Transition Properties */
-	--blyrics-lyric-scroll-duration: var(
-		--blyrics-lyric-transition-duration,
-		650ms
-	);
+	/* Shared lyric scroll easing */
 	--blyrics-lyric-scroll-timing-function: var(
 		--blyrics-lyric-transition-timing-function,
 		cubic-bezier(0.86, 0, 0.2, 1)

package/package.json

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