@braccato/core 1.13.2 → 1.15.0

package/README.md

@@ -345,14 +345,15 @@ refactor. Import them from `@braccato/core/constants` instead of typing them out
 
 ## Stylesheets
 
-Three sheets ship with the package, and loading them is yours, the way any package's CSS is. Leave
+Four sheets ship with the package, and loading them is yours, the way any package's CSS is. Leave
 them out and you get lines that are in the document and unstyled, rather than lines that are missing.
 
 | File                                     | What it carries                                                                                                        |
 | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `@braccato/core/styles/variables.css`    | Every `--blyrics-*` default. It goes first, because the other two read from it.                                           |
+| `@braccato/core/styles/variables.css`    | Every `--blyrics-*` default. It goes first, because the others read from it.                                              |
 | `@braccato/core/styles/lyrics.css`       | The container, the lines, the words and the sweep, plus two `@property` registrations the word animation interpolates through. |
 | `@braccato/core/styles/instrumental.css` | The waveform that fills a bar nobody sings over, and the animation that walks it.                                          |
+| `@braccato/core/styles/stage.css`        | Placement for the stage layout, and nothing else. Only a renderer created with `layout: "stage"` needs it.                  |
 
 One thing they do not do for you. The module measures the room the first and last lines need to reach
 the view's target scroll position and writes it on the root as `--blyrics-padding-top` and
@@ -382,6 +383,26 @@ catch the layout up: the hung line floats into place while the lines around it s
 rather than the rest of the lyric jumping down. `--blyrics-animate-decoration-entry` set to `0` drops
 both for an instant insert, and reduced-motion does the same.
 
+`createLyricsRenderer({ layout: "stage" })` builds a view for subtitles over a video: one line at a
+time, and only while it is being sung. It fills its nearest positioned ancestor. There is no scroll
+element to hand it, no scroll padding written and no line culling. Unsynced lyrics show nothing, because
+a stage places lines by their time and unsynced lines have none.
+
+The engine owns where a line is and whether you can see it. It moves each line with a `translate` Web
+Animation and fades it through `--blyrics-stage-opacity`, blurring it slightly on the way in and out so
+one line reads as turning into the next. Each line carries `data-stage-role` (`current`, `previous`,
+`queued` or `gone`) and the container carries `data-layout="stage"`. `stage.css` sets a stage line's
+`opacity` from that property with `!important` inside a cascade layer, and keeps the line
+`visibility: hidden` until it is marked `data-stage-visible`. Layered important declarations outrank
+unlayered ones whatever their specificity, so a theme that forces `opacity: 1 !important` on active
+lines, which some do, can neither reveal a queued line nor hold one that is leaving. In a duet (any line sung by `v2` or `v3`) the
+container also gets `data-stage-duet` and each singer keeps to their side, mirrored for right-to-left
+lines; lines for everyone stay centred.
+
+Everything else is the theme's. Lines are styled exactly as they would be in a scrolling view.
+`host.onStageLayout(box)` reports the box around the sung lines in the container's coordinates, or null
+when nothing sung is on stage, so you can draw a backdrop outside the container the theme styles.
+
 `@braccato/core/element` registers `<braccato-lyrics>`, and `<better-lyrics>` beside it, on import.
 Registration is a side effect, which is why it is entered separately.
 
@@ -429,7 +450,10 @@ swapping `audio.src` between songs without playing goes on reporting the old pos
 
 Two renderers in one document write over each other, so the module supports one. It is a constraint
 rather than a setting, and it is stated rather than enforced: none of the points where two of them
-collide is a crash.
+collide is a crash. A stage renderer is the exception. It writes no scroll padding, so it can sit in
+the same document as a scrolling one, with three rules: give both the same theme, tick both with the
+same time and wall time in the same frame (whichever ticks first is the one that sees a seek), and if
+the stage renderer applied the theme first, destroy it first, because its `<style>` element goes with it.
 
 Two things are written per document and belong to whichever renderer wrote them last: the theme's
 `<style>` element, and the scroll padding on the root. Two more are per bundle, because a settings
@@ -479,3 +503,42 @@ loading regional CJK web fonts should set `--noto-sans-universal` on these eleme
 `--blyrics-font-family` and `--blyrics-translated-font-family` remain explicit theme overrides.
 They are unset by default; custom CSS that reads them directly should use
 `var(--blyrics-font-family, var(--blyrics-default-font-family))` for the default stack.
+
+### Theme-provided image fills
+
+Image highlights are optional. Enable them in a theme comment:
+
+```css
+/* blyrics-image-highlights = true; */
+.blyrics-container {
+  --blyrics-highlight-image: url("my-image.jpg");
+  --blyrics-image-glow-opacity-from: 0.5;
+  --blyrics-image-glow-opacity-to: 0;
+}
+```
+
+Changing this setting requests a lyric rebuild through the existing `setTheme` return value.
+Without it, the renderer adds no image or glow layers and keeps its shadow animation. With it,
+the sharp fill and a separate blurred copy share the word reveal, letter motion, opacity, pause,
+seek and playback-rate handling. Existing glow radius, duration and easing properties still apply;
+the two image-glow opacity properties replace the solid shadow color's alpha.
+
+The image may be an SDR texture or an HDR gain-map asset. The theme owns HDR media queries
+and `dynamic-range-limit`; the core never opts into extra display brightness. Ordinary active
+text color backs up the image fill, while the note keeps its original color path until its
+SVG image loads. The note image reuses the original animated wave clip and fade group.
+
+The glow layer is outside the paint's mask, avoiding clipped halos at word edges. Bidi-sensitive
+runs and fragmented long words use a parallel inline text run for the glow, so the browser
+reproduces the same ordering and wrapped fragments. Its reveal and visibility use the same
+animation clock as the sharp text. No generated text or per-frame geometry reads are needed.
+Joining-script word groups retain contextual joining by using whole-word sweeps instead of
+inline-block letter waves, including when image highlights are disabled.
+Forced colors suppress the image and halo in favor of system text colors.
+
+For real-browser regression checks, build the package, serve the repository root and open
+`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.
+
+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

@@ -345,14 +345,15 @@ refactor. Import them from `@braccato/core/constants` instead of typing them out
 
 ## Stylesheets
 
-Three sheets ship with the package, and loading them is yours, the way any package's CSS is. Leave
+Four sheets ship with the package, and loading them is yours, the way any package's CSS is. Leave
 them out and you get lines that are in the document and unstyled, rather than lines that are missing.
 
 | File                                     | What it carries                                                                                                        |
 | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `@braccato/core/styles/variables.css`    | Every `--blyrics-*` default. It goes first, because the other two read from it.                                           |
+| `@braccato/core/styles/variables.css`    | Every `--blyrics-*` default. It goes first, because the others read from it.                                              |
 | `@braccato/core/styles/lyrics.css`       | The container, the lines, the words and the sweep, plus two `@property` registrations the word animation interpolates through. |
 | `@braccato/core/styles/instrumental.css` | The waveform that fills a bar nobody sings over, and the animation that walks it.                                          |
+| `@braccato/core/styles/stage.css`        | Placement for the stage layout, and nothing else. Only a renderer created with `layout: "stage"` needs it.                  |
 
 One thing they do not do for you. The module measures the room the first and last lines need to reach
 the view's target scroll position and writes it on the root as `--blyrics-padding-top` and
@@ -382,6 +383,26 @@ catch the layout up: the hung line floats into place while the lines around it s
 rather than the rest of the lyric jumping down. `--blyrics-animate-decoration-entry` set to `0` drops
 both for an instant insert, and reduced-motion does the same.
 
+`createLyricsRenderer({ layout: "stage" })` builds a view for subtitles over a video: one line at a
+time, and only while it is being sung. It fills its nearest positioned ancestor. There is no scroll
+element to hand it, no scroll padding written and no line culling. Unsynced lyrics show nothing, because
+a stage places lines by their time and unsynced lines have none.
+
+The engine owns where a line is and whether you can see it. It moves each line with a `translate` Web
+Animation and fades it through `--blyrics-stage-opacity`, blurring it slightly on the way in and out so
+one line reads as turning into the next. Each line carries `data-stage-role` (`current`, `previous`,
+`queued` or `gone`) and the container carries `data-layout="stage"`. `stage.css` sets a stage line's
+`opacity` from that property with `!important` inside a cascade layer, and keeps the line
+`visibility: hidden` until it is marked `data-stage-visible`. Layered important declarations outrank
+unlayered ones whatever their specificity, so a theme that forces `opacity: 1 !important` on active
+lines, which some do, can neither reveal a queued line nor hold one that is leaving. In a duet (any line sung by `v2` or `v3`) the
+container also gets `data-stage-duet` and each singer keeps to their side, mirrored for right-to-left
+lines; lines for everyone stay centred.
+
+Everything else is the theme's. Lines are styled exactly as they would be in a scrolling view.
+`host.onStageLayout(box)` reports the box around the sung lines in the container's coordinates, or null
+when nothing sung is on stage, so you can draw a backdrop outside the container the theme styles.
+
 `@braccato/core/element` registers `<braccato-lyrics>`, and `<better-lyrics>` beside it, on import.
 Registration is a side effect, which is why it is entered separately.
 
@@ -429,7 +450,10 @@ swapping `audio.src` between songs without playing goes on reporting the old pos
 
 Two renderers in one document write over each other, so the module supports one. It is a constraint
 rather than a setting, and it is stated rather than enforced: none of the points where two of them
-collide is a crash.
+collide is a crash. A stage renderer is the exception. It writes no scroll padding, so it can sit in
+the same document as a scrolling one, with three rules: give both the same theme, tick both with the
+same time and wall time in the same frame (whichever ticks first is the one that sees a seek), and if
+the stage renderer applied the theme first, destroy it first, because its `<style>` element goes with it.
 
 Two things are written per document and belong to whichever renderer wrote them last: the theme's
 `<style>` element, and the scroll padding on the root. Two more are per bundle, because a settings
@@ -479,3 +503,42 @@ loading regional CJK web fonts should set `--noto-sans-universal` on these eleme
 `--blyrics-font-family` and `--blyrics-translated-font-family` remain explicit theme overrides.
 They are unset by default; custom CSS that reads them directly should use
 `var(--blyrics-font-family, var(--blyrics-default-font-family))` for the default stack.
+
+### Theme-provided image fills
+
+Image highlights are optional. Enable them in a theme comment:
+
+```css
+/* blyrics-image-highlights = true; */
+.blyrics-container {
+  --blyrics-highlight-image: url("my-image.jpg");
+  --blyrics-image-glow-opacity-from: 0.5;
+  --blyrics-image-glow-opacity-to: 0;
+}
+```
+
+Changing this setting requests a lyric rebuild through the existing `setTheme` return value.
+Without it, the renderer adds no image or glow layers and keeps its shadow animation. With it,
+the sharp fill and a separate blurred copy share the word reveal, letter motion, opacity, pause,
+seek and playback-rate handling. Existing glow radius, duration and easing properties still apply;
+the two image-glow opacity properties replace the solid shadow color's alpha.
+
+The image may be an SDR texture or an HDR gain-map asset. The theme owns HDR media queries
+and `dynamic-range-limit`; the core never opts into extra display brightness. Ordinary active
+text color backs up the image fill, while the note keeps its original color path until its
+SVG image loads. The note image reuses the original animated wave clip and fade group.
+
+The glow layer is outside the paint's mask, avoiding clipped halos at word edges. Bidi-sensitive
+runs and fragmented long words use a parallel inline text run for the glow, so the browser
+reproduces the same ordering and wrapped fragments. Its reveal and visibility use the same
+animation clock as the sharp text. No generated text or per-frame geometry reads are needed.
+Joining-script word groups retain contextual joining by using whole-word sweeps instead of
+inline-block letter waves, including when image highlights are disabled.
+Forced colors suppress the image and halo in favor of system text colors.
+
+For real-browser regression checks, build the package, serve the repository root and open
+`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.
+
+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

@@ -1,5 +1,6 @@
 import type { LineData } from "./inject.js";
-import type { LyricsRendererHost, LyricSyncType, ResolvedTickOptions, TickOptions } from "./types.js";
+import { type StageBox, type StageMetrics } from "./stage.js";
+import type { LyricsLayout, LyricsRendererHost, LyricSyncType, ResolvedTickOptions, TickOptions } from "./types.js";
 /**
  * Everything that belongs to a single rendered lyrics view: one scroll container, one selection,
  * one set of pending scroll work.
@@ -69,6 +70,15 @@ export interface AnimationEngineInstance extends AnimEngineViewState {
     pendingLyricsUpdateFrame: number | null;
     learnedAnimationTimingOffsetMs: number;
     animationTimingVisibilityLogUntil: number;
+    layout: LyricsLayout;
+    stageKey: string;
+    stageBox: StageBox | null;
+    stageMetrics: Map<HTMLElement, StageMetrics>;
+    stageY: Map<HTMLElement, number>;
+    stageMoves: Map<HTMLElement, Animation>;
+    stageFades: Map<HTMLElement, Animation>;
+    stageBlurs: Map<HTMLElement, Animation>;
+    stageFontSize: number;
     /**
      * Releases everything the instance holds on its window: the reduced motion listener, the tab
      * renderer observer and any frame it still has queued.
@@ -80,7 +90,7 @@ export interface AnimationEngineInstance extends AnimEngineViewState {
  * deliberately not used inside the tick, which runs per frame and per line.
  */
 export declare function forEveryLiveView(runOperation: (engine: AnimationEngineInstance) => void): void;
-export declare function createAnimationEngineInstance(engineDocument: Document, engineWindow: EngineWindow, host: LyricsRendererHost): AnimationEngineInstance;
+export declare function createAnimationEngineInstance(engineDocument: Document, engineWindow: EngineWindow, host: LyricsRendererHost, layout?: LyricsLayout): AnimationEngineInstance;
 /**
  * Forgets the last player snapshot, so the next tick is treated as the first one of a new song
  * rather than as a jump away from the previous one.
@@ -171,6 +181,10 @@ interface AnimationConfig {
         swipeEndFrom: string;
         swipeStartTo: string;
         swipeEndTo: string;
+        imageGlowFrom: string;
+        imageGlowTo: string;
+        imageGlowOpacityFrom: string;
+        imageGlowOpacityTo: string;
         glowFrom: string;
         glowTo: string;
         glowDurationRatio: number;
@@ -334,6 +348,7 @@ export type AnimationTickStatus = "ok" | "lyrics-missing";
  * matching no line at all.
  */
 export declare function resolveTickOptions(options: TickOptions): ResolvedTickOptions;
+export declare function measureStage(engine: AnimationEngineInstance): void;
 /**
  * Renders one view against a tick with nothing left out.
  */