@braccato/core 1.16.5 → 1.16.7

package/README.md

@@ -328,6 +328,35 @@ It is written only when a word's state changes rather than every frame, so selec
 theme nothing per tick. A line synced word, which has no duration of its own, is `active` from its
 start until the next word begins.
 
+### Browser engine
+
+On Firefox the container carries `data-browser-engine="gecko"`. The renderer's Gecko-only CSS keys on
+it, and a theme can do the same to target Firefox without sniffing the user agent. It is detected from
+a feature only Gecko ships, so forks of Firefox carry it too. Script reads the same answer from
+`isGecko()` in `@braccato/core/util`, which the renderer's Gecko-only script checks once on load.
+
+```css
+.blyrics-container[data-browser-engine="gecko"] .blyrics--line {
+  /* Firefox only */
+}
+```
+
+The letter wave uses both. WebRender rounds text moved by a 2D translation to whole device
+pixels, and it only redraws a cached tile once something on it has moved a quarter of a pixel, so the
+wave stepped on Firefox. Lettered words on animating lines get a distant `perspective` there, and each
+base letter in the wave runs an invisible additive opacity ripple that changes every frame and forces the
+redraw. Chromium gets neither.
+
+The playback clock checks `isGecko()`. Firefox advances a media element's `currentTime` about every 40ms, so
+each read lags the true time by a different amount and never leads it. The renderer took each new lag
+for drift and reseeked the line, so the highlight swipe jumped back mid-word. On Firefox the tick keeps
+its own clock instead: a read ahead of it is taken, a read behind it pulls it back by a tenth per
+second, and a read more than 60ms off, about one Firefox step plus margin, counts as a seek.
+
+The instrumental fill uses the attribute. Gecko resolves a `fill-box` transform origin wrongly for a shape
+inside a `clipPath`, so the flattening wave crest came loose from the rising fill. On Firefox the wave
+scales from its floor in user units instead, which Chromium already renders identically.
+
 ### Class names
 
 These are published API rather than implementation. Renaming one costs a migration rather than a
@@ -428,7 +457,7 @@ Four leaves import nothing at all, so taking one does not pull the engine into y
 - `@braccato/core/constants` for the class names and element ids above
 - `@braccato/core/text` for script detection: `testRtl`, `containsNonLatin`, `detectNonLatinLanguage`
 - `@braccato/core/themeSettings` for `parseThemeConfig`
-- `@braccato/core/util` for pure helpers such as `clamp` and `toMs`
+- `@braccato/core/util` for pure helpers such as `clamp` and `toMs`, and `isGecko` for engine-specific fixes
 
 Two notes on the element entry point. A browser extension's isolated world has no custom element
 registry, so `window.customElements` is null there and importing this file throws where it registers.

package/dist/README.md

@@ -328,6 +328,35 @@ It is written only when a word's state changes rather than every frame, so selec
 theme nothing per tick. A line synced word, which has no duration of its own, is `active` from its
 start until the next word begins.
 
+### Browser engine
+
+On Firefox the container carries `data-browser-engine="gecko"`. The renderer's Gecko-only CSS keys on
+it, and a theme can do the same to target Firefox without sniffing the user agent. It is detected from
+a feature only Gecko ships, so forks of Firefox carry it too. Script reads the same answer from
+`isGecko()` in `@braccato/core/util`, which the renderer's Gecko-only script checks once on load.
+
+```css
+.blyrics-container[data-browser-engine="gecko"] .blyrics--line {
+  /* Firefox only */
+}
+```
+
+The letter wave uses both. WebRender rounds text moved by a 2D translation to whole device
+pixels, and it only redraws a cached tile once something on it has moved a quarter of a pixel, so the
+wave stepped on Firefox. Lettered words on animating lines get a distant `perspective` there, and each
+base letter in the wave runs an invisible additive opacity ripple that changes every frame and forces the
+redraw. Chromium gets neither.
+
+The playback clock checks `isGecko()`. Firefox advances a media element's `currentTime` about every 40ms, so
+each read lags the true time by a different amount and never leads it. The renderer took each new lag
+for drift and reseeked the line, so the highlight swipe jumped back mid-word. On Firefox the tick keeps
+its own clock instead: a read ahead of it is taken, a read behind it pulls it back by a tenth per
+second, and a read more than 60ms off, about one Firefox step plus margin, counts as a seek.
+
+The instrumental fill uses the attribute. Gecko resolves a `fill-box` transform origin wrongly for a shape
+inside a `clipPath`, so the flattening wave crest came loose from the rising fill. On Firefox the wave
+scales from its floor in user units instead, which Chromium already renders identically.
+
 ### Class names
 
 These are published API rather than implementation. Renaming one costs a migration rather than a
@@ -428,7 +457,7 @@ Four leaves import nothing at all, so taking one does not pull the engine into y
 - `@braccato/core/constants` for the class names and element ids above
 - `@braccato/core/text` for script detection: `testRtl`, `containsNonLatin`, `detectNonLatinLanguage`
 - `@braccato/core/themeSettings` for `parseThemeConfig`
-- `@braccato/core/util` for pure helpers such as `clamp` and `toMs`
+- `@braccato/core/util` for pure helpers such as `clamp` and `toMs`, and `isGecko` for engine-specific fixes
 
 Two notes on the element entry point. A browser extension's isolated world has no custom element
 registry, so `window.customElements` is null there and importing this file throws where it registers.

package/dist/engine.d.ts

@@ -98,6 +98,7 @@ export declare function createAnimationEngineInstance(engineDocument: Document,
  * rather than as a jump away from the previous one.
  */
 export declare function resetPlaybackClock(): void;
+export declare function smoothedPlaybackTime(previousTime: number, previousAt: number, rawTime: number, now: number, playbackRate: number): number;
 /**
  * The user asked for autoscroll back, now.
  */

package/dist/engine.js

@@ -20,7 +20,7 @@ import { ANIMATING_CLASS, CREDITS_CLASS, CURRENT_LYRICS_CLASS, FOOTER_CLASS, LIN
 import { INSTRUMENTAL_WAVE_PATH_HIGH, INSTRUMENTAL_WAVE_PATH_LOW } from "./instrumental.js";
 import { layoutStage, planStage, queuedStageY, stageTextSpan, } from "./stage.js";
 import { registerThemeSetting } from "./themeSettings.js";
-import { clamp, getRelativeLayoutBounds, positiveModulo, roundedMs, toMs } from "./util.js";
+import { clamp, getRelativeLayoutBounds, isGecko, positiveModulo, roundedMs, toMs } from "./util.js";
 const NO_LYRICS_ELEMENT_LOG = "No lyrics element found on the page, skipping lyrics injection";
 const LYRICS_CHECK_INTERVAL_ERROR = "Error in lyrics check interval:";
 const PAUSING_LYRICS_SCROLL_LOG = "Pausing Lyrics Autoscroll Due to User Scroll";
@@ -29,6 +29,11 @@ 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.54);
 const TIME_JUMP_THRESHOLD = 0.5;
+// Gecko steps media time every ~40ms, so reads lag by a random amount (never lead) that reseeks lines as drift.
+const SMOOTH_PLAYBACK_CLOCK = isGecko();
+// One Gecko step (~45ms) plus margin: a read further off is a seek or a timer spike, not media lag.
+const CLOCK_RESYNC_THRESHOLD_S = 0.06;
+const CLOCK_SLEW_PER_S = 0.1;
 const REDUCED_MOTION_QUERY = "(prefers-reduced-motion: reduce)";
 const SCROLL_PREPARE_LEAD_MS = 120;
 const LINE_SCROLL_FALLBACK_DURATION_MS = 750;
@@ -185,6 +190,8 @@ const playbackClock = {
     lastTime: 0,
     lastPlayState: false,
     lastEventCreationTime: NO_PLAYER_SNAPSHOT,
+    smoothedTime: 0,
+    smoothedAt: NO_PLAYER_SNAPSHOT,
 };
 /**
  * Forgets the last player snapshot, so the next tick is treated as the first one of a new song
@@ -194,6 +201,17 @@ export function resetPlaybackClock() {
     playbackClock.lastTime = 0;
     playbackClock.lastPlayState = false;
     playbackClock.lastEventCreationTime = NO_PLAYER_SNAPSHOT;
+    playbackClock.smoothedAt = NO_PLAYER_SNAPSHOT;
+}
+export function smoothedPlaybackTime(previousTime, previousAt, rawTime, now, playbackRate) {
+    if (previousAt === NO_PLAYER_SNAPSHOT)
+        return rawTime;
+    const elapsedS = Math.max(0, now - previousAt) / 1000;
+    const predictedTime = previousTime + elapsedS * playbackRate;
+    const errorS = rawTime - predictedTime;
+    if (errorS >= 0 || Math.abs(errorS) >= CLOCK_RESYNC_THRESHOLD_S)
+        return rawTime;
+    return predictedTime + errorS * Math.min(1, elapsedS * CLOCK_SLEW_PER_S);
 }
 // -- View operations --------------------------
 /**
@@ -436,7 +454,7 @@ function mirrorImageHighlightAnimations(part, animations) {
         mirror.currentTime = animation.currentTime;
         const timing = animationTimingTracks.get(animation);
         if (timing)
-            animationTimingTracks.set(mirror, timing);
+            animationTimingTracks.set(mirror, { ...timing, skipDriftSample: true });
         mirrors.push(mirror);
     }
     return mirrors;
@@ -529,8 +547,11 @@ function timingValueToMs(value) {
 function animationCurrentTimeMs(animation) {
     return timingValueToMs(animation.currentTime);
 }
-function animationActiveDurationMs(animation) {
-    return timingValueToMs(animation.effect?.getComputedTiming().activeDuration);
+// A finished animation's currentTime stops at its end time, which counts the delay, so that is where
+// the expected time has to stop too. Clamping to the active duration alone saturates a delayed
+// animation as soon as it is created and hides any drift in it.
+function animationEndTimeMs(animation) {
+    return timingValueToMs(animation.effect?.getComputedTiming().endTime);
 }
 function wrappedTimingOffsetMs(actualTimeMs, expectedTimeMs, wrapDurationMs) {
     return positiveModulo(actualTimeMs - expectedTimeMs + wrapDurationMs / 2, wrapDurationMs) - wrapDurationMs / 2;
@@ -542,18 +563,18 @@ function normalizeAnimationTimeMs(animation, timeMs, timing) {
     if (timing.wrapDurationMs && timing.wrapDurationMs > 0) {
         return positiveModulo(timeMs, timing.wrapDurationMs);
     }
-    const activeDurationMs = animationActiveDurationMs(animation);
-    if (activeDurationMs !== null && Number.isFinite(activeDurationMs)) {
-        return Math.min(timeMs, activeDurationMs);
+    const endTimeMs = animationEndTimeMs(animation);
+    if (endTimeMs !== null && Number.isFinite(endTimeMs)) {
+        return Math.min(timeMs, endTimeMs);
     }
     return timeMs;
 }
 function animationTimingSample(part, animation, currentTime) {
-    if (animation.playState === "idle") {
+    const timing = animationTimingTracks.get(animation);
+    if (!timing || timing.skipDriftSample) {
         return null;
     }
-    const timing = animationTimingTracks.get(animation);
-    if (!timing) {
+    if (animation.playState === "idle") {
         return null;
     }
     const actualTimeMs = animationCurrentTimeMs(animation);
@@ -844,6 +865,11 @@ function swipeRamp(config) {
 }
 // How far through its float a letter crests, as a keyframe offset.
 const LETTER_WAVE_CREST_OFFSET = 0.4;
+// WebRender redraws a cached tile only after a quarter device pixel of movement, so Gecko letters step.
+// An invisible additive opacity ripple changes every frame and forces the redraw.
+const GECKO_REDRAW = isGecko();
+const GECKO_REDRAW_KEYFRAMES = [{ opacity: 0 }, { opacity: -0.002 }, { opacity: 0 }];
+const GECKO_REDRAW_PERIOD_MS = 200;
 // When each letter's wave starts, counted from the start of the word, and how long it lasts. A letter
 // crests just as the swipe finishes lighting it. If the swipe lights it faster than the float rises,
 // it starts early enough to make that, which on a short word means before the word itself does. If the
@@ -887,7 +913,11 @@ function startRichSyncedHighlightAnimations(engine, part, config, swipeTimeMs, w
                         offset: frame.offset,
                         maskPosition: frame.maskPosition,
                         WebkitMaskPosition: frame.maskPosition,
-                    })), { duration: sweep.durationMs, delay: sweep.delayMs, easing: sweep.easing, fill: "both" }), swipeTiming);
+                    })), { duration: sweep.durationMs, delay: sweep.delayMs, easing: sweep.easing, fill: "both" }), 
+                    // The last letter's sweep ends last, so it alone covers the whole word.
+                    index === sweeps.length - 1 && target === highlightLetters[index]
+                        ? swipeTiming
+                        : { ...swipeTiming, skipDriftSample: true });
                     animation.currentTime = swipeCurrentTimeMs;
                     if (index === 0)
                         swipeAnimation = animation;
@@ -1042,20 +1072,50 @@ function startWordAnimations(engine, part, config, currentTime, appliedTimingOff
             // as the wave running behind once it finishes. Run the wave's clock ahead by the head start
             // instead, the way the swipe carries its lead, so every delay stays at zero or above.
             const waveLeadMs = Math.max(0, -Math.min(...waves.map(wave => wave.delayMs)));
-            const cascadeDurationMs = waveLeadMs + Math.max(...waves.map(wave => wave.delayMs + wave.durationMs));
+            const waveEndsMs = waves.map(wave => wave.delayMs + wave.durationMs);
+            const lastWaveEndMs = Math.max(...waveEndsMs);
+            const lastEndingWaveIndex = waveEndsMs.lastIndexOf(lastWaveEndMs);
+            const cascadeDurationMs = waveLeadMs + lastWaveEndMs;
             const floatStartMs = correctedAnimationTimeMs(wordTimeMs + waveLeadMs, appliedTimingOffsetMs, cascadeDurationMs);
             const floatKeyframeSignature = JSON.stringify(floatKeyframes);
-            for (const set of [part.letterElements, part.highlightLetterElements, part.imageLayers?.glowLetters]) {
-                set?.forEach((letterElement, index) => {
+            // Glow letters only show while the glow does: never when it is off or renders nothing for this
+            // word, and not once it has faded out. Their waves stop there instead of running to the end.
+            const glowLetters = config.enabled.highlightGlow && !part.glowSuppressed ? part.imageLayers?.glowLetters : undefined;
+            const glowEndMs = Number.parseFloat(config.highlight.imageGlowOpacityTo) === 0 ? waveLeadMs + glowDurationMs : Infinity;
+            const animateLetters = (letters, endMs, sampled) => {
+                letters?.forEach((letterElement, index) => {
+                    const delayMs = waves[index].delayMs + waveLeadMs;
+                    if (delayMs >= endMs)
+                        return;
+                    const endDelayMs = Math.min(0, endMs - delayMs - waves[index].durationMs);
                     const animation = trackLyricAnimationTiming(engine, acquireWaveAnimation(engine, letterElement, floatKeyframes, floatKeyframeSignature, {
                         duration: waves[index].durationMs,
-                        delay: waves[index].delayMs + waveLeadMs,
+                        delay: delayMs,
+                        endDelay: endDelayMs,
                         fill: "forwards",
-                    }), { appliedTimingOffsetMs, offsetMs: waveLeadMs });
+                    }), {
+                        appliedTimingOffsetMs,
+                        offsetMs: waveLeadMs,
+                        // The wave that ends last covers the whole word. A theme's swipe ramp can make that an early letter.
+                        skipDriftSample: !sampled || index !== lastEndingWaveIndex,
+                    });
                     animation.currentTime = floatStartMs;
                     wobbleAnimations.push(animation);
+                    if (!GECKO_REDRAW || !sampled)
+                        return;
+                    const redraw = trackLyricAnimationTiming(engine, letterElement.animate(GECKO_REDRAW_KEYFRAMES, {
+                        duration: GECKO_REDRAW_PERIOD_MS,
+                        iterations: waves[index].durationMs / GECKO_REDRAW_PERIOD_MS,
+                        delay: delayMs,
+                        composite: "add",
+                    }), { appliedTimingOffsetMs, offsetMs: waveLeadMs, skipDriftSample: true });
+                    redraw.currentTime = floatStartMs;
+                    wobbleAnimations.push(redraw);
                 });
-            }
+            };
+            animateLetters(part.letterElements, Infinity, true);
+            animateLetters(part.highlightLetterElements, Infinity, false);
+            animateLetters(glowLetters, glowEndMs, false);
         }
     }
     part.animations = [
@@ -2259,6 +2319,13 @@ export function tickView(engine, currentTime, options) {
         timeOffset = 0;
     }
     currentTime += timeOffset / 1000;
+    if (SMOOTH_PLAYBACK_CLOCK) {
+        if (isPlaying && !timeJumped) {
+            currentTime = smoothedPlaybackTime(playbackClock.smoothedTime, playbackClock.smoothedAt, currentTime, now, engine.playbackRate);
+        }
+        playbackClock.smoothedTime = currentTime;
+        playbackClock.smoothedAt = isPlaying ? now : NO_PLAYER_SNAPSHOT;
+    }
     if (!engine.host.isViewVisible()) {
         clearVisibleLyricWillChange(engine);
         return "ok";

package/dist/styles/instrumental.css

@@ -68,6 +68,12 @@
 	d: var(--blyrics-instrumental-wave-path-high);
 }
 
+/* Gecko misplaces a fill-box origin inside a clipPath, so pin the wave's floor (y=4) in user units. */
+.blyrics-container[data-browser-engine="gecko"] .blyrics--wave-path {
+	transform-box: view-box;
+	transform-origin: 0 4px;
+}
+
 /* Trigger the Flattening */
 .blyrics--instrumental.blyrics--animating:not(.blyrics--paused) .blyrics--wave-path {
 	/* Flatten the wave to 0 height */

package/dist/styles/lyrics.css

@@ -177,6 +177,11 @@
 	unicode-bidi: isolate;
 }
 
+/* WebRender snaps 2D-translated glyphs to whole pixels; perspective rasterizes them in local space. */
+.blyrics-container[data-browser-engine="gecko"] .blyrics--animating .blyrics-word--lettered {
+	perspective: 100000px;
+}
+
 .blyrics-word-highlight.blyrics-word-highlight--lettered {
 	background-image: none;
 }

package/dist/util.d.ts

@@ -1,5 +1,10 @@
 export declare function clamp(value: number, min: number, max: number): number;
 export declare function positiveModulo(value: number, divisor: number): number;
+/**
+ * Whether the page renders with Gecko (Firefox). Detects the engine by a feature only it ships, so
+ * spoofed user agents and Firefox forks resolve the same way.
+ */
+export declare function isGecko(): boolean;
 export declare function roundedMs(value: number): number;
 /**
  * Converts CSS duration value to milliseconds.

package/dist/util.js

@@ -4,6 +4,13 @@ export function clamp(value, min, max) {
 export function positiveModulo(value, divisor) {
     return ((value % divisor) + divisor) % divisor;
 }
+/**
+ * Whether the page renders with Gecko (Firefox). Detects the engine by a feature only it ships, so
+ * spoofed user agents and Firefox forks resolve the same way.
+ */
+export function isGecko() {
+    return typeof CSS !== "undefined" && CSS.supports("-moz-appearance", "none");
+}
 export function roundedMs(value) {
     return Math.round(value * 10) / 10;
 }

package/dist/view.js

@@ -15,6 +15,7 @@ import { addSeekHandler, applyDirection, buildLineSyncedParts, createLyricsLine,
 import { refreshInstrumentalImages } from "./imageHighlights.js";
 import { createInstrumentalElement } from "./instrumental.js";
 import { applyLyricLanguage, resolveLyricLanguages } from "./language.js";
+import { isGecko } from "./util.js";
 const INITIAL_SKIP_SCROLLS = 2;
 const SKIP_SCROLL_DECAY_MS = 2000;
 function buildInstrumentalLine(doc, lyricElement, lyrics, lineIndex) {
@@ -73,6 +74,8 @@ export function setLyrics(engine, mount, lyrics, options) {
     const doc = engine.document;
     const container = doc.createElement("div");
     container.className = LYRICS_CLASS;
+    if (isGecko())
+        container.dataset.browserEngine = "gecko";
     mount.replaceChildren(container);
     const allZero = lyrics.every(item => item.startTimeMs === 0);
     const seek = (timeS) => engine.host.seek(timeS);

package/package.json

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