@braccato/core 1.16.6 → 1.16.8

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.
@@ -557,5 +586,7 @@ For real-browser regression checks, build the package, serve the repository root
 `tooling/browser/image-highlights.html`. Import `image-highlights-checks.js` from that page and
 call `runImageHighlightChecks(testView)`. The default fixture uses an SDR image; a `theme` query
 parameter can point at a consumer's HDR stylesheet for physical-display testing.
+`runLetterInkChecks(testView)` in the same module checks that letter masks cover glyph overhang,
+such as a `j`'s hook or an italic `f`, without moving any letter.
 
 Words that mix RTL characters with LTR letters or numbers retain native text shaping instead of per-letter motion. Image glow, letter masks and letter motion retain their current paint during the line exit fade.

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.
@@ -557,5 +586,7 @@ For real-browser regression checks, build the package, serve the repository root
 `tooling/browser/image-highlights.html`. Import `image-highlights-checks.js` from that page and
 call `runImageHighlightChecks(testView)`. The default fixture uses an SDR image; a `theme` query
 parameter can point at a consumer's HDR stylesheet for physical-display testing.
+`runLetterInkChecks(testView)` in the same module checks that letter masks cover glyph overhang,
+such as a `j`'s hook or an italic `f`, without moving any letter.
 
 Words that mix RTL characters with LTR letters or numbers retain native text shaping instead of per-letter motion. Image glow, letter masks and letter motion retain their current paint during the line exit fade.

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 --------------------------
 /**
@@ -847,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
@@ -1078,6 +1101,16 @@ function startWordAnimations(engine, part, config, currentTime, appliedTimingOff
                     });
                     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);
@@ -2286,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/image-highlights.css

@@ -17,6 +17,11 @@
   color: transparent;
   -webkit-text-fill-color: transparent;
 }
+/* The content-box copy keeps each letter's image; the padding-box copy carries it under glyph overhang. */
+.blyrics-word-highlight.blyrics-image-highlight .blyrics--letter {
+  background-image: var(--blyrics-highlight-image, none), var(--blyrics-highlight-image, none);
+  background-origin: content-box, padding-box;
+}
 .blyrics-image-highlight:not(.blyrics-word-highlight--lettered) .blyrics-image-fill {
   --blyrics-image-sweep-angle: 90deg;
   mask-image: linear-gradient(var(--blyrics-image-sweep-angle),

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,11 +177,22 @@
 	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;
 }
 
+/* A mask clips to the border box, cutting off glyph overhang (a j's hook, italics). The padding
+   widens that clip without moving layout, and the content-box origin keeps the sweep geometry. */
 .blyrics-word-highlight .blyrics--letter {
+	padding-inline: 0.25em;
+	margin-inline: -0.25em;
+	-webkit-mask-origin: content-box;
+	mask-origin: content-box;
 	color: var(--blyrics-lyric-active-color);
 	-webkit-mask-image: linear-gradient(90deg, #000 0, #000 50%, #0000 calc(50% + var(--mask-fade, 3%)));
 	mask-image: linear-gradient(90deg, #000 0, #000 50%, #0000 calc(50% + var(--mask-fade, 3%)));

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.6",
+  "version": "1.16.8",
   "description": "Synchronized lyrics renderer with word-by-word animations",
   "type": "module",
   "license": "MIT",