@braccato/core 1.9.0 → 1.11.0

package/README.md

@@ -7,6 +7,9 @@ than a shadow root, so the CSS already on your page reaches them.
 Extracted from the [Better Lyrics](https://better-lyrics.boidu.dev) rendering engine, which is still
 where it runs.
 
+The [renderer guide](https://docs.betterlyrics.org/braccato/renderer) on the docs site covers properties, events,
+scrolling and theming with lyrics from the Better Lyrics API. This README is still the full reference.
+
 ## Install
 
 ```bash
@@ -150,6 +153,20 @@ 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`
@@ -278,6 +295,7 @@ refactor. Import them from `@braccato/core/constants` instead of typing them out
 | `BACKGROUND_LYRIC_CLASS`  | `blyrics-background-lyric`  | A background vocal, sung over the line it answers.           |
 | `USER_SCROLLING_CLASS`    | `blyrics-user-scrolling`    | Set while a reader has scrolled away and autoscroll waits.   |
 | `TRANSLATED_LYRICS_CLASS` | `blyrics--translated`       | A translation hung off a line that was already built.        |
+| `EXPLICIT_WORD_CLASS`     | `blyrics-explicit`          | A word the lyrics flag as explicit. Unstyled unless a theme styles it. |
 | `CUSTOM_THEME_STYLE_ID`   | `blyrics-custom-style`      | The id of the `<style>` the theme lands in.                  |
 
 ## Stylesheets

package/dist/README.md

@@ -7,6 +7,9 @@ than a shadow root, so the CSS already on your page reaches them.
 Extracted from the [Better Lyrics](https://better-lyrics.boidu.dev) rendering engine, which is still
 where it runs.
 
+The [renderer guide](https://docs.betterlyrics.org/braccato/renderer) on the docs site covers properties, events,
+scrolling and theming with lyrics from the Better Lyrics API. This README is still the full reference.
+
 ## Install
 
 ```bash
@@ -150,6 +153,20 @@ 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`
@@ -278,6 +295,7 @@ refactor. Import them from `@braccato/core/constants` instead of typing them out
 | `BACKGROUND_LYRIC_CLASS`  | `blyrics-background-lyric`  | A background vocal, sung over the line it answers.           |
 | `USER_SCROLLING_CLASS`    | `blyrics-user-scrolling`    | Set while a reader has scrolled away and autoscroll waits.   |
 | `TRANSLATED_LYRICS_CLASS` | `blyrics--translated`       | A translation hung off a line that was already built.        |
+| `EXPLICIT_WORD_CLASS`     | `blyrics-explicit`          | A word the lyrics flag as explicit. Unstyled unless a theme styles it. |
 | `CUSTOM_THEME_STYLE_ID`   | `blyrics-custom-style`      | The id of the `<style>` the theme lands in.                  |
 
 ## Stylesheets

package/dist/engine.js

@@ -1116,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
@@ -1989,7 +1994,7 @@ export function tickView(engine, currentTime, options) {
                 activeElems.push(lines[0]);
             }
             // 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) => {
@@ -2172,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

@@ -215,11 +215,6 @@
 	color: color-mix(in srgb, var(--blyrics-lyric-inactive-color) 78%, transparent);
 }
 
-.blyrics-explicit {
-	text-decoration: line-through;
-	text-decoration-thickness: 0.08em;
-}
-
 .blyrics--translated,
 .blyrics--romanized {
 	animation: blyrics-decoration-in calc(var(--blyrics-animate-decoration-entry) * 0.35s)

package/package.json

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