@braccato/core 1.18.0 → 1.19.1

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;
@@ -2024,7 +2031,7 @@ function prepareUpcomingLineScroll(engine, lines, activeLine, scrollDeltaPx, fro
     }
 }
 // -- Skip Scrolls Decay --------------------------
-function decaySkipScrolls(engine, now) {
+function decaySkipScrolls(engine, now, keepsReserve) {
     let j = 0;
     for (; j < engine.skipScrollsDecayTimes.length; j++) {
         if (engine.skipScrollsDecayTimes[j] > now) {
@@ -2032,10 +2039,7 @@ function decaySkipScrolls(engine, now) {
         }
     }
     engine.skipScrollsDecayTimes = engine.skipScrollsDecayTimes.slice(j);
-    engine.skipScrolls -= j;
-    if (engine.skipScrolls < 1) {
-        engine.skipScrolls = 1;
-    }
+    engine.skipScrolls = Math.max(keepsReserve ? 1 : 0, engine.skipScrolls - j);
 }
 // -- Passive Scroll Engine --------------------------
 /**
@@ -2135,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.
@@ -2236,6 +2243,7 @@ export function resolveTickOptions(options) {
         passiveScrollEnabled: options.passiveScrollEnabled ?? false,
         playbackRate: resolvePlaybackRate(options.playbackRate),
         followPausedSeeks: options.followPausedSeeks ?? false,
+        countEveryUserScroll: options.countEveryUserScroll ?? false,
     };
 }
 // A rate of zero or less would freeze every animation that follows the song, which is a second
@@ -2885,9 +2893,12 @@ export function tickView(engine, currentTime, options) {
                 }
                 scrollTop = scrollPos;
                 engine.scrollPos = scrollTop;
+                const scrollTopBeforeWrite = tabRenderer.scrollTop;
                 tabRenderer.scrollTop = scrollTop;
-                engine.skipScrolls += 1;
-                engine.skipScrollsDecayTimes.push(Date.now() + 2000);
+                if (tabRenderer.scrollTop !== scrollTopBeforeWrite) {
+                    engine.skipScrolls += 1;
+                    engine.skipScrollsDecayTimes.push(Date.now() + 2000);
+                }
             }
         }
         if (engine.wasUserScrolling && engine.scrollResumeTime < Date.now()) {
@@ -2895,7 +2906,7 @@ export function tickView(engine, currentTime, options) {
             lyricsElement.classList.remove(USER_SCROLLING_CLASS);
             engine.wasUserScrolling = false;
         }
-        decaySkipScrolls(engine, now);
+        decaySkipScrolls(engine, now, !options.countEveryUserScroll);
     }
     catch (err) {
         if (!err.message?.includes("undefined")) {

package/dist/types.d.ts

@@ -41,6 +41,13 @@ export interface TickOptions {
      * new time, as an editor scrubbing a paused song needs. Defaults to false.
      */
     followPausedSeeks?: boolean;
+    /**
+     * Whether every user scroll the host reports can pause autoscroll of synced lyrics. By default
+     * the view always holds one scroll back, for the one a refocused window fires, and a host that
+     * ticks every frame spends that reserve on each scroll the reader makes. Unsynced lyrics drifting
+     * on their own are not covered. Defaults to false.
+     */
+    countEveryUserScroll?: boolean;
 }
 /**
  * A tick with nothing left out. The engine reads every field unconditionally, so the defaults are

package/package.json

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