@braccato/core 1.19.0 → 1.20.0

package/dist/engine.d.ts

@@ -31,6 +31,8 @@ interface AnimEngineViewState {
     };
     passiveScrollAccumulatedTime: number;
     passiveLastWallTime: number;
+    /** Where the passive drift last put the scroll, so a scroll that lands anywhere else is the reader's. */
+    passiveScrollTop: number | null;
 }
 /**
  * `Window` alone types neither `ResizeObserver` nor `DOMMatrix`: both are ambient `var`
@@ -116,7 +118,7 @@ export declare function resetScrollResume(engine: AnimationEngineInstance): void
  */
 export declare function resumeAllAutoscroll(): void;
 /**
- * The user scrolled this view. Scrolls the engine itself performed are swallowed one at a time;
+ * The user scrolled this view. Scrolls the engine itself performed are swallowed;
  * 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

package/dist/engine.js

@@ -26,6 +26,7 @@ const LYRICS_CHECK_INTERVAL_ERROR = "Error in lyrics check interval:";
 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 PASSIVE_DRIFT_SCROLL_TOLERANCE_PX = 1;
 const LYRIC_ENDING_THRESHOLD_S = registerThemeSetting("blyrics-lyric-ending-threshold-s", 0.5);
 const EARLY_SCROLL_CONSIDER = registerThemeSetting("blyrics-early-scroll-consider-s", 0.54);
 const TIME_JUMP_THRESHOLD = 0.5;
@@ -134,6 +135,7 @@ export function createAnimationEngineInstance(engineDocument, engineWindow, host
         },
         passiveScrollAccumulatedTime: 0,
         passiveLastWallTime: 0,
+        passiveScrollTop: null,
         cachedTabRendererHeight: null,
         cachedScrollInsets: NO_SCROLL_INSETS,
         cachedFooterItem: null,
@@ -231,14 +233,18 @@ export function resumeAllAutoscroll() {
     forEveryLiveView(resetScrollResume);
 }
 /**
- * The user scrolled this view. Scrolls the engine itself performed are swallowed one at a time;
+ * The user scrolled this view. Scrolls the engine itself performed are swallowed;
  * 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 function noteUserScroll(engine, isPassive) {
-    if (engine.skipScrolls > 0) {
+    if (isPassive) {
+        if (isPassiveDriftScroll(engine))
+            return;
+    }
+    else if (engine.skipScrolls > 0) {
         engine.skipScrolls--;
         engine.skipScrollsDecayTimes.shift();
         return;
@@ -314,6 +320,7 @@ export function clearLyrics(engine) {
     engine.lastScrollDebugContext.centers = [];
     engine.passiveScrollAccumulatedTime = 0;
     engine.passiveLastWallTime = 0;
+    engine.passiveScrollTop = null;
     stopPassiveScrollLoop(engine);
     engine.lines = [];
     engine.cachedFooterItem = null;
@@ -2132,15 +2139,18 @@ function passiveScrollEngine(engine, isPlaying) {
         // Phase 4: hold at top
         targetScroll = 0;
     }
-    const prevScrollTop = tabRenderer.scrollTop;
     tabRenderer.scrollTop = targetScroll;
-    const appliedScrollTop = tabRenderer.scrollTop;
-    // Only skip the next scroll event if scrollTop actually changed.
-    // When it doesn't change (pause phases, sub-pixel rounding), no programmatic
-    // scroll event fires, so setting skipScrolls would eat user scroll events instead.
-    if (appliedScrollTop !== prevScrollTop) {
-        engine.skipScrolls = 1;
-    }
+    engine.passiveScrollTop = tabRenderer.scrollTop;
+}
+/**
+ * The drift writes the scroll every frame, and a browser folds that scroll and the reader's into one
+ * event, so the drift's own scrolls are told apart by where they land rather than by counting them.
+ */
+function isPassiveDriftScroll(engine) {
+    const scrollTop = engine.host.getScrollElement()?.scrollTop;
+    return (engine.passiveScrollTop !== null &&
+        scrollTop !== undefined &&
+        Math.abs(scrollTop - engine.passiveScrollTop) < PASSIVE_DRIFT_SCROLL_TOLERANCE_PX);
 }
 /**
  * Sets up a ResizeObserver on the tab renderer to cache its height.

package/dist/inject.js

@@ -140,6 +140,7 @@ function splitPartIntoTokens(part) {
             part: {
                 words: chunk,
                 isBackground: part.isBackground,
+                backgroundGroup: part.backgroundGroup,
                 explicit: part.explicit,
             },
         });
@@ -166,7 +167,7 @@ function splitPartIntoTokens(part) {
 function normalizeParts(parts) {
     return parts.flatMap(splitPartIntoTokens);
 }
-function groupTokensByWord(tokens) {
+function groupTokensByWord(tokens, splitBackgroundGroups) {
     const groups = [];
     let current = null;
     const flush = () => {
@@ -182,9 +183,10 @@ function groupTokensByWord(tokens) {
             continue;
         }
         const isBackground = token.part?.isBackground === true;
-        if (!current || current.isBackground !== isBackground) {
+        const backgroundGroup = splitBackgroundGroups ? token.part?.backgroundGroup : undefined;
+        if (!current || current.isBackground !== isBackground || current.backgroundGroup !== backgroundGroup) {
             flush();
-            current = { text: "", isBackground, tokens: [] };
+            current = { text: "", isBackground, backgroundGroup, tokens: [] };
         }
         current.text += token.text;
         current.tokens.push(token);
@@ -331,24 +333,36 @@ export function createLyricsLine(doc, parts, line, lyricElement, options = { spl
             .map(part => part.words)
             .join("")
         : lineText;
-    const backgroundText = parts
-        .filter(part => part.isBackground === true)
+    const backgroundTextOf = (group) => parts
+        .filter(part => part.isBackground === true && (part.backgroundGroup ?? 0) === group)
         .map(part => part.words)
         .join("");
     const main = createContentLine(doc, LINE_MAIN_CLASS, mainText);
     const mainRun = createBidiRun(doc, mainText);
     const mainHighlightRun = createHighlightRun(doc, mainText);
-    const groupedTokens = groupTokensByWord(normalizeParts(parts));
-    const backgroundLine = createContentLine(doc, BACKGROUND_LINE_CLASS, backgroundText);
-    const backgroundRun = createBidiRun(doc, backgroundText);
-    const backgroundHighlightRun = createHighlightRun(doc, backgroundText);
-    let hasBackground = false;
+    const groupedTokens = groupTokensByWord(normalizeParts(parts), options.splitBackgroundLine);
+    const backgroundRows = new Map();
+    const backgroundRowOf = (group) => {
+        let row = backgroundRows.get(group);
+        if (!row) {
+            const text = backgroundTextOf(group);
+            row = {
+                line: createContentLine(doc, BACKGROUND_LINE_CLASS, text),
+                run: createBidiRun(doc, text),
+                highlightRun: createHighlightRun(doc, text),
+                used: false,
+            };
+            row.line.appendChild(row.highlightRun);
+            row.line.appendChild(row.run);
+            backgroundRows.set(group, row);
+        }
+        return row;
+    };
+    backgroundRowOf(0);
     let pendingForegroundSpace = "";
     let pendingBackgroundSpace = "";
     main.appendChild(mainHighlightRun);
     main.appendChild(mainRun);
-    backgroundLine.appendChild(backgroundHighlightRun);
-    backgroundLine.appendChild(backgroundRun);
     for (const item of groupedTokens) {
         if ("kind" in item) {
             // Is a RenderToken, not a WordGroup, only whitespace should enter this path
@@ -357,8 +371,9 @@ export function createLyricsLine(doc, parts, line, lyricElement, options = { spl
         }
         else {
             const shouldUseBackgroundLine = options.splitBackgroundLine && item.isBackground;
-            const target = shouldUseBackgroundLine ? backgroundRun : mainRun;
-            const highlightRun = shouldUseBackgroundLine ? backgroundHighlightRun : mainHighlightRun;
+            const backgroundRow = shouldUseBackgroundLine ? backgroundRowOf(item.backgroundGroup ?? 0) : null;
+            const target = backgroundRow ? backgroundRow.run : mainRun;
+            const highlightRun = backgroundRow ? backgroundRow.highlightRun : mainHighlightRun;
             const pendingSpace = shouldUseBackgroundLine ? pendingBackgroundSpace : pendingForegroundSpace;
             if (target.childNodes.length > 0 && pendingSpace.length > 0) {
                 target.appendChild(createSpaceNode(doc, pendingSpace, shouldUseBackgroundLine));
@@ -367,8 +382,8 @@ export function createLyricsLine(doc, parts, line, lyricElement, options = { spl
             const { lyricGroup, highlightGroup } = createWordGroup(doc, item, line);
             target.appendChild(lyricGroup);
             highlightRun.appendChild(highlightGroup);
-            if (shouldUseBackgroundLine) {
-                hasBackground = true;
+            if (backgroundRow) {
+                backgroundRow.used = true;
                 pendingBackgroundSpace = "";
             }
             else {
@@ -376,13 +391,16 @@ export function createLyricsLine(doc, parts, line, lyricElement, options = { spl
             }
         }
     }
+    const usedBackgroundRows = [...backgroundRows]
+        .filter(([, row]) => row.used)
+        .sort(([a], [b]) => a - b)
+        .map(([, row]) => row);
     alignImageGlowRun(mainHighlightRun, line.parts);
-    if (hasBackground)
-        alignImageGlowRun(backgroundHighlightRun, line.parts);
+    for (const row of usedBackgroundRows)
+        alignImageGlowRun(row.highlightRun, line.parts);
     lyricElement.appendChild(main);
-    if (hasBackground) {
-        lyricElement.appendChild(backgroundLine);
-    }
+    for (const row of usedBackgroundRows)
+        lyricElement.appendChild(row.line);
     return main;
 }
 export function buildLineSyncedParts(item) {

package/dist/view.js

@@ -114,6 +114,7 @@ function lineSignature(lyrics, lineIndex) {
         part.durationMs,
         part.words,
         part.isBackground === true,
+        part.backgroundGroup ?? null,
         part.explicit === true,
     ]);
     // An instrumental line takes its side and direction from the lines around it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@braccato/core",
-  "version": "1.19.0",
+  "version": "1.20.0",
   "description": "Synchronized lyrics renderer with word-by-word animations",
   "type": "module",
   "license": "MIT",
@@ -57,7 +57,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@braccato/types": "^1.0.0"
+    "@braccato/types": "^1.1.0"
   },
   "scripts": {
     "build": "tsx ../../tooling/build-package.ts",