@braccato/core 1.16.14 → 1.17.1

package/README.md

@@ -80,6 +80,40 @@ view.lyricsOptions = { songwriters: parser.metadata(text).songwriters };
 view.lyrics = parser.parse(text, player.duration * 1000);
 ```
 
+### Replacing lyrics
+
+Write a new array whenever the song's lyrics change, as often as they change: a better source
+arriving for the song already playing, or an editor handing over every edit. Give each update the
+same `songKey` (a `setLyrics` option, or a field of the element's `lyricsOptions`), and lyrics for the
+song already on screen are swapped into it rather than built over it, so the only thing that changes
+on screen is what changed in the lyrics. Lyrics with no `songKey`, or another song's, are built anew,
+so a new song starts at the top with nothing of the last one's scroll.
+
+- A line that builds the same as one already shown, by its words, timing, parts, singer, translation
+  and romanization, keeps that element and the animations running on it. The arrays do not need to be the same objects,
+  so a consumer that parses its source again on every change loses nothing.
+- Lines that differ are built again in place. A line built where another one stood takes over that
+  line's place in the scroll, and on the stage its role and position, so a retimed line being sung
+  does not fade in again. A stage line replaced mid-glide finishes the glide it was in, unless the
+  new line is a different height, which moves it straight to its new place.
+- The scroll stays where it was. When lines above the one being followed grow, shrink, arrive or go,
+  the scroll moves by however far that line moved, so it holds still on screen, and the lines that
+  moved relative to it slide there. A reader who scrolled away stays scrolled away.
+- Translations and romanizations hung on a kept line stay, and so do those on a line rebuilt only for
+  its timing. Injecting the same one again does nothing, and injecting a different one replaces it. A
+  line whose `translation`, `translations`, `romanization` or `timedRomanization` changed is rebuilt
+  bare, ready to be decorated again. To drop one a consumer no longer wants, such as a translation
+  the listener turned off, call `removeTranslation` or `removeRomanization` (see Entry points).
+- A swap that lands while the lines are still scrolling to the last line leaves the kept lines to
+  finish that scroll, and the new ones start at rest.
+
+Some changes rebuild the whole view: another `songKey` or none, a different mount, a theme setting
+that changes how lines are built, lyrics that gain or lose their timing, and anything written after
+`clear()` or an empty array. A line whose times you changed after it was built, such as with an
+offset you apply after every build, is built again from the lyrics rather than kept, so the offset is
+not applied twice. A line built in place of another only takes over its place and sung state when
+the two are sung over the same time.
+
 ## Properties
 
 Every one of these may be written before the element is in a document. The renderer is built when it
@@ -408,12 +442,15 @@ package's stylesheets are yours to load for the same reason.
 
 `@braccato/core` is the facade and registers nothing. `createLyricsRenderer(options)` returns one
 `LyricsRenderer`: give it lyrics, tick it, and it owns the DOM it builds and every re-measurement
-that DOM needs. `resetPlaybackClock`, `resumeAllAutoscroll`, `injectRomanization` and
-`injectTranslation` are published beside it, for what one instance cannot answer for on its own. Hang
-one onto a built line and call `renderer.scheduleLyricPositionUpdate` the way you already would to
-catch the layout up: the hung line floats into place while the lines around it slide to make room,
-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.
+that DOM needs. `resetPlaybackClock`, `resumeAllAutoscroll`, `injectRomanization`,
+`injectTranslation`, `removeRomanization` and `removeTranslation` are published beside it, for what
+one instance cannot answer for on its own. Hang one onto a built line and call
+`renderer.scheduleLyricPositionUpdate` the way you already would to catch the layout up: the hung line
+floats into place while the lines around it slide to make room, 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. Taking one off with `removeTranslation(lineElement)` or
+`removeRomanization(lineElement, line)` is the same: call `scheduleLyricPositionUpdate` after, and the
+lines below slide up into the space.
 
 `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

package/dist/README.md

@@ -80,6 +80,40 @@ view.lyricsOptions = { songwriters: parser.metadata(text).songwriters };
 view.lyrics = parser.parse(text, player.duration * 1000);
 ```
 
+### Replacing lyrics
+
+Write a new array whenever the song's lyrics change, as often as they change: a better source
+arriving for the song already playing, or an editor handing over every edit. Give each update the
+same `songKey` (a `setLyrics` option, or a field of the element's `lyricsOptions`), and lyrics for the
+song already on screen are swapped into it rather than built over it, so the only thing that changes
+on screen is what changed in the lyrics. Lyrics with no `songKey`, or another song's, are built anew,
+so a new song starts at the top with nothing of the last one's scroll.
+
+- A line that builds the same as one already shown, by its words, timing, parts, singer, translation
+  and romanization, keeps that element and the animations running on it. The arrays do not need to be the same objects,
+  so a consumer that parses its source again on every change loses nothing.
+- Lines that differ are built again in place. A line built where another one stood takes over that
+  line's place in the scroll, and on the stage its role and position, so a retimed line being sung
+  does not fade in again. A stage line replaced mid-glide finishes the glide it was in, unless the
+  new line is a different height, which moves it straight to its new place.
+- The scroll stays where it was. When lines above the one being followed grow, shrink, arrive or go,
+  the scroll moves by however far that line moved, so it holds still on screen, and the lines that
+  moved relative to it slide there. A reader who scrolled away stays scrolled away.
+- Translations and romanizations hung on a kept line stay, and so do those on a line rebuilt only for
+  its timing. Injecting the same one again does nothing, and injecting a different one replaces it. A
+  line whose `translation`, `translations`, `romanization` or `timedRomanization` changed is rebuilt
+  bare, ready to be decorated again. To drop one a consumer no longer wants, such as a translation
+  the listener turned off, call `removeTranslation` or `removeRomanization` (see Entry points).
+- A swap that lands while the lines are still scrolling to the last line leaves the kept lines to
+  finish that scroll, and the new ones start at rest.
+
+Some changes rebuild the whole view: another `songKey` or none, a different mount, a theme setting
+that changes how lines are built, lyrics that gain or lose their timing, and anything written after
+`clear()` or an empty array. A line whose times you changed after it was built, such as with an
+offset you apply after every build, is built again from the lyrics rather than kept, so the offset is
+not applied twice. A line built in place of another only takes over its place and sung state when
+the two are sung over the same time.
+
 ## Properties
 
 Every one of these may be written before the element is in a document. The renderer is built when it
@@ -408,12 +442,15 @@ package's stylesheets are yours to load for the same reason.
 
 `@braccato/core` is the facade and registers nothing. `createLyricsRenderer(options)` returns one
 `LyricsRenderer`: give it lyrics, tick it, and it owns the DOM it builds and every re-measurement
-that DOM needs. `resetPlaybackClock`, `resumeAllAutoscroll`, `injectRomanization` and
-`injectTranslation` are published beside it, for what one instance cannot answer for on its own. Hang
-one onto a built line and call `renderer.scheduleLyricPositionUpdate` the way you already would to
-catch the layout up: the hung line floats into place while the lines around it slide to make room,
-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.
+that DOM needs. `resetPlaybackClock`, `resumeAllAutoscroll`, `injectRomanization`,
+`injectTranslation`, `removeRomanization` and `removeTranslation` are published beside it, for what
+one instance cannot answer for on its own. Hang one onto a built line and call
+`renderer.scheduleLyricPositionUpdate` the way you already would to catch the layout up: the hung line
+floats into place while the lines around it slide to make room, 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. Taking one off with `removeTranslation(lineElement)` or
+`removeRomanization(lineElement, line)` is the same: call `scheduleLyricPositionUpdate` after, and the
+lines below slide up into the space.
 
 `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

package/dist/engine.d.ts

@@ -1,4 +1,4 @@
-import type { LineData } from "./inject.js";
+import type { LineData, PartData } from "./inject.js";
 import { type StageBox, type StageMetrics } from "./stage.js";
 import type { LyricsLayout, LyricsRendererHost, LyricSyncType, ResolvedTickOptions, TickOptions } from "./types.js";
 /**
@@ -148,6 +148,42 @@ export declare function getRenderedSyncType(engine: AnimationEngineInstance): Ly
  * hold are released along with it.
  */
 export declare function clearLyrics(engine: AnimationEngineInstance): void;
+/**
+ * How far a scroll still running has carried a line from its place, or zero with none running on it.
+ */
+export declare function lineScrollOffset(engine: AnimationEngineInstance, element: HTMLElement): number;
+/**
+ * Hands the engine the lines of a song swapped into the view it already holds. A kept line is the
+ * same record and keeps everything; a dropped line's animations stop and nothing goes on holding it;
+ * a line built in place of one is handed what the engine held for that one, so the scroll does not
+ * see a line it has not met and the stage does not fade in a line that was already up.
+ *
+ * @param lines - The new song's records, kept ones included, in order
+ * @param dropped - Records of the song before that the new one no longer has
+ * @param replaced - Each new record built in place of a dropped one, to the one it replaced
+ */
+export declare function replaceRenderedLines(engine: AnimationEngineInstance, lines: LineData[], dropped: readonly LineData[], replaced: ReadonlyMap<LineData, LineData>): void;
+/**
+ * Carries a swapped view across the layout change it caused. The line the reader is following holds
+ * still on screen: the scroll moves by however far that line moved in the container. Every other
+ * line that moved, relative to it, slides from where it was rather than jumping.
+ *
+ * Which line is followed depends on who owns the scroll. While the engine does, it is the line the
+ * last scroll aimed at; while the reader does, it is the first line they could see.
+ *
+ * @param before - Where each line was in the container before the swap and how tall, from `swapLyrics`
+ * @param scrollTopBefore - The scroll position the swap began at
+ */
+export declare function settleSwappedLines(engine: AnimationEngineInstance, before: ReadonlyMap<LineData, {
+    position: number;
+    height: number;
+    offset: number;
+}>, scrollTopBefore: number): void;
+/**
+ * Lets go of a part moving to another line or leaving the view: its animations stop, back to the pool
+ * they came from, and it shows no sung state until a line that is being sung sets it up again.
+ */
+export declare function releasePart(part: PartData): void;
 export declare function updateWordStates(lineData: LineData, currentTime: number): void;
 type LineScrollSide = "above" | "active" | "below";
 interface LineScrollItem {

package/dist/engine.js

@@ -323,6 +323,185 @@ export function clearLyrics(engine) {
     engine.waveAnimationPool.length = 0;
     resetStage(engine);
 }
+/**
+ * How far a scroll still running has carried a line from its place, or zero with none running on it.
+ */
+export function lineScrollOffset(engine, element) {
+    if (!engine.lineScrollAnimations.some(record => record.lineElement === element))
+        return 0;
+    return currentTranslateY(engine, element, 0);
+}
+/**
+ * Hands the engine the lines of a song swapped into the view it already holds. A kept line is the
+ * same record and keeps everything; a dropped line's animations stop and nothing goes on holding it;
+ * a line built in place of one is handed what the engine held for that one, so the scroll does not
+ * see a line it has not met and the stage does not fade in a line that was already up.
+ *
+ * @param lines - The new song's records, kept ones included, in order
+ * @param dropped - Records of the song before that the new one no longer has
+ * @param replaced - Each new record built in place of a dropped one, to the one it replaced
+ */
+export function replaceRenderedLines(engine, lines, dropped, replaced) {
+    const successors = new Map();
+    for (const [line, previous] of replaced)
+        successors.set(previous, line);
+    const droppedElements = new Set(dropped.map(line => line.lyricElement));
+    const carry = (line) => successors.get(line) ?? (droppedElements.has(line.lyricElement) ? null : line);
+    const carryAll = (from) => from.map(carry).filter((line) => line !== null);
+    // The line being sung is still the line being sung, so a theme keyed on those classes does not dim it
+    // and bring it back. Its animations are set up again from the new timing on the next tick. Read
+    // before the dropped lines are let go, which clears their selection.
+    for (const [line, previous] of replaced) {
+        line.isScrolled = previous.isScrolled;
+        line.isSelected = previous.isSelected;
+        togglePartClass(line, CURRENT_LYRICS_CLASS, previous.lyricElement.classList.contains(CURRENT_LYRICS_CLASS));
+        togglePartClass(line, ANIMATING_CLASS, previous.lyricElement.classList.contains(ANIMATING_CLASS));
+    }
+    // A planned scroll was planned against lines and places this swap is about to change.
+    dropPendingLineScroll(engine);
+    for (const record of [...engine.lineScrollAnimations]) {
+        if (!droppedElements.has(record.lineElement))
+            continue;
+        record.animation.cancel();
+        removeLineScrollAnimation(engine, record);
+    }
+    for (const line of dropped) {
+        resetLineAnimationState(line);
+        line.isSelected = false;
+        engine.visibleWillChangeElements.delete(line.lyricElement);
+        engine.culledLineElements.delete(line.lyricElement);
+    }
+    engine.lastScrollElements = carryAll(engine.lastScrollElements);
+    engine.lastScrollDebugContext.activeElms = carryAll(engine.lastScrollDebugContext.activeElms);
+    engine.pinnedScrollLine = engine.pinnedScrollLine === null ? null : carry(engine.pinnedScrollLine);
+    engine.lines = lines;
+    if (engine.layout === "stage")
+        replaceStageElements(engine, dropped, replaced);
+}
+/**
+ * Starts the same animation on another element at the point the first one has reached, or answers
+ * null when there is nothing left of it to carry on.
+ */
+function continueAnimation(animation, element) {
+    const effect = animation?.effect;
+    if (!animation || !effect || typeof effect.getKeyframes !== "function" || animation.playState === "finished") {
+        return null;
+    }
+    if (animation.playState === "idle")
+        return null;
+    const continued = element.animate(effect.getKeyframes(), { ...effect.getTiming(), composite: effect.composite });
+    continued.playbackRate = animation.playbackRate;
+    continued.currentTime = animation.currentTime;
+    if (animation.playState === "paused")
+        continued.pause();
+    return continued;
+}
+/**
+ * Moves what the stage held for each replaced line onto the line built in its place, and lets go of
+ * every dropped line. A replacement starts exactly where and as visible as the line it replaced, so
+ * placing the stage afterwards only moves it if the new song puts it somewhere else.
+ */
+function replaceStageElements(engine, dropped, replaced) {
+    for (const [line, previous] of replaced) {
+        const element = line.lyricElement;
+        const role = previous.lyricElement.dataset.stageRole;
+        const y = engine.stageY.get(previous.lyricElement);
+        if (role === undefined || y === undefined)
+            continue;
+        element.dataset.stageRole = role;
+        const visible = previous.lyricElement.dataset.stageVisible !== undefined;
+        if (visible)
+            element.dataset.stageVisible = "";
+        // A line replaced mid-glide carries on gliding from wherever the one it replaced had got to.
+        const move = continueAnimation(engine.stageMoves.get(previous.lyricElement), element);
+        if (move === null) {
+            snapStageElement(engine, element, y);
+        }
+        else {
+            engine.stageMoves.set(element, move);
+            engine.stageY.set(element, y);
+        }
+        const fade = continueAnimation(engine.stageFades.get(previous.lyricElement), element) ??
+            element.animate([{ [STAGE_OPACITY_PROPERTY]: isStageRoleVisible(role) ? 1 : 0 }], {
+                duration: 0,
+                fill: "forwards",
+            });
+        if (!isStageRoleVisible(role)) {
+            fade.onfinish = () => {
+                if (engine.stageFades.get(element) === fade)
+                    delete element.dataset.stageVisible;
+            };
+        }
+        engine.stageFades.set(element, fade);
+        const blur = continueAnimation(engine.stageBlurs.get(previous.lyricElement), element);
+        if (blur !== null)
+            engine.stageBlurs.set(element, blur);
+    }
+    for (const line of dropped) {
+        const element = line.lyricElement;
+        for (const animations of [engine.stageMoves, engine.stageFades, engine.stageBlurs]) {
+            animations.get(element)?.cancel();
+            animations.delete(element);
+        }
+        engine.stageY.delete(element);
+        engine.stageMetrics.delete(element);
+    }
+    // The roles are planned again against the new lines, even where they come out the same.
+    engine.stageKey = "";
+}
+/**
+ * Carries a swapped view across the layout change it caused. The line the reader is following holds
+ * still on screen: the scroll moves by however far that line moved in the container. Every other
+ * line that moved, relative to it, slides from where it was rather than jumping.
+ *
+ * Which line is followed depends on who owns the scroll. While the engine does, it is the line the
+ * last scroll aimed at; while the reader does, it is the first line they could see.
+ *
+ * @param before - Where each line was in the container before the swap and how tall, from `swapLyrics`
+ * @param scrollTopBefore - The scroll position the swap began at
+ */
+export function settleSwappedLines(engine, before, scrollTopBefore) {
+    const container = engine.lyricsContainer;
+    const scrollElement = engine.host.getScrollElement();
+    if (container === null || scrollElement === null || engine.layout === "stage")
+        return;
+    const readerOwnsScroll = engine.scrollResumeTime > Date.now();
+    const followed = readerOwnsScroll
+        ? engine.lines.find(line => {
+            const was = before.get(line);
+            return was !== undefined && was.position + was.height > scrollTopBefore;
+        })
+        : (engine.lastScrollElements.findLast(line => before.has(line)) ??
+            engine.lines.find(line => before.has(line) && line.isScrolled));
+    const followedWas = followed === undefined ? undefined : before.get(followed)?.position;
+    // A line that has not been measured, because the view is not on screen, has nowhere to hold still.
+    if (followed !== undefined && followedWas !== undefined && followedWas >= 0 && followed.position >= 0) {
+        const moved = followed.position - followedWas;
+        if (Math.abs(moved) >= DECORATION_MIN_SHIFT_PX)
+            scrollElement.scrollTop = scrollTopBefore + moved;
+    }
+    // Read back rather than assumed: the browser may have clamped the write, or clamped the scroll for
+    // a song that got shorter before anything here wrote it. Either way the event that follows is not
+    // the reader's, and a write the browser clamped to nothing sends none.
+    const shift = scrollElement.scrollTop - scrollTopBefore;
+    if (shift !== 0) {
+        engine.skipScrolls += 1;
+        engine.skipScrollsDecayTimes.push(Date.now() + 2000);
+        if (engine.scrollPos >= 0)
+            engine.scrollPos += shift;
+    }
+    if (!decorationSlideAllowed(engine, container))
+        return;
+    for (const line of engine.lines) {
+        const was = before.get(line);
+        if (was === undefined || was.position < 0 || line.position < 0)
+            continue;
+        // From where it is on screen, which a line scroll still running carries away from its place.
+        const onScreenShift = was.position + was.offset - line.position + shift;
+        if (Math.abs(onScreenShift) >= DECORATION_MIN_SHIFT_PX)
+            slideElementBy(line.lyricElement, onScreenShift);
+    }
+}
 function resetStage(engine) {
     for (const animation of [
         ...engine.stageMoves.values(),
@@ -343,6 +522,19 @@ function resetStage(engine) {
         engine.host.onStageLayout?.(null);
     }
 }
+/**
+ * Lets go of a part moving to another line or leaving the view: its animations stop, back to the pool
+ * they came from, and it shows no sung state until a line that is being sung sets it up again.
+ */
+export function releasePart(part) {
+    resetPartAnimations(part);
+    togglePartClass(part, PAUSED_CLASS, false);
+    togglePartClass(part, ANIMATING_CLASS, false);
+    part.wordState = WORD_STATE_UPCOMING;
+    part.lyricElement.setAttribute(WORD_STATE_ATTR, WORD_STATE_UPCOMING);
+    part.highlightElement.setAttribute(WORD_STATE_ATTR, WORD_STATE_UPCOMING);
+    part.imageLayers?.highlight?.setAttribute(WORD_STATE_ATTR, WORD_STATE_UPCOMING);
+}
 function resetPartAnimations(part) {
     for (const animation of part.animations) {
         animation.cancel();
@@ -2353,6 +2545,9 @@ export function tickView(engine, currentTime, options) {
     const mediaSteppedBack = eventCreationTime === NO_PLAYER_SNAPSHOT &&
         isPlaying &&
         currentTime < playbackClock.lastTime - CLOCK_RESYNC_THRESHOLD_S;
+    // A clock that was already paused only moves when the host seeks it, however small the step, as a
+    // scrub does. The tick that pauses lands a moment past the last playing one and is not a seek.
+    const pausedSeek = !isPlaying && !playbackClock.lastPlayState && currentTime !== playbackClock.lastTime;
     if (timeJumped)
         dropPendingLineScroll(engine);
     playbackClock.lastTime = currentTime;
@@ -2465,7 +2660,7 @@ export function tickView(engine, currentTime, options) {
                         lineData.isAnimating = false; // reset the animation against current media time
                 }
                 // Lead-in animations have no timing sample for the drift check, so a jump while playing must reset them.
-                if (((timeJumped && isPlaying) || mediaSteppedBack) && lineData.isAnimating)
+                if (((timeJumped && isPlaying) || mediaSteppedBack || pausedSeek) && lineData.isAnimating)
                     resetLineAnimationState(lineData);
                 updateWordStates(lineData, currentTime);
                 const nativeTimingSample = lineNativeTimingSample(lineData, currentTime);
@@ -2500,7 +2695,7 @@ export function tickView(engine, currentTime, options) {
             else {
                 const staleAnimationEndTime = effectiveEndTime + animationConfig.highlight.fadeOutDurationMs / 1000 + 0.05;
                 if (lineData.isSelected) {
-                    if (isPlaying || timeJumped) {
+                    if (isPlaying || timeJumped || pausedSeek) {
                         if (currentTime > staleAnimationEndTime) {
                             logAnimationCleanup(engine, "selected-stale-reset", lineData, index, currentTime, staleAnimationEndTime);
                             resetLineAnimationState(lineData);

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { resetPlaybackClock, resumeAllAutoscroll } from "./engine.js";
-export { injectRomanization, injectTranslation, type LineData } from "./inject.js";
+export { injectRomanization, injectTranslation, type LineData, removeRomanization, removeTranslation, } from "./inject.js";
 export { createLyricsRenderer } from "./renderer.js";
 export type { Lyric, LyricsRenderer, LyricsRendererHost, TickOptions } from "./types.js";
 /** @public */

package/dist/index.js

@@ -7,5 +7,5 @@
 // answer for on its own: the song level operations address every live view at once, and the
 // injection helpers decorate lines that are already built.
 export { resetPlaybackClock, resumeAllAutoscroll } from "./engine.js";
-export { injectRomanization, injectTranslation } from "./inject.js";
+export { injectRomanization, injectTranslation, removeRomanization, removeTranslation, } from "./inject.js";
 export { createLyricsRenderer } from "./renderer.js";

package/dist/inject.d.ts

@@ -46,5 +46,22 @@ export declare function createLyricsLine(doc: Document, parts: LyricPart[], line
 }): HTMLElement;
 export declare function buildLineSyncedParts(item: Lyric): LyricPart[];
 export declare function addSeekHandler(seek: (timeS: number) => void, lyricElement: HTMLElement, allZero: boolean): void;
+/**
+ * Takes the romanization off a line, along with any timed parts it brought. A line a swap kept goes on
+ * carrying what was hung on it, so this is how a consumer drops one it no longer wants. Answers
+ * whether there was one to take off.
+ */
+export declare function removeRomanization(lyricElement: HTMLElement, lineData: LineData): boolean;
+/**
+ * Takes the translation off a line. A line a swap kept goes on carrying what was hung on it, so this is
+ * how a consumer drops one it no longer wants. Answers whether there was one to take off.
+ */
+export declare function removeTranslation(lyricElement: HTMLElement): boolean;
+/**
+ * Moves the translation and romanization hung on one line onto the line built in its place, with any
+ * timed parts they brought, so a line rebuilt for its timing keeps what the consumer hung on it. The
+ * parts are let go of whatever the old line was showing; the new line sets them up again with its own.
+ */
+export declare function moveDecorations(from: LineData, to: LineData): void;
 export declare function injectRomanization(doc: Document, lyricElement: HTMLElement, lineData: LineData, text: string, timedRomanization?: LyricPart[] | null): void;
 export declare function injectTranslation(doc: Document, lyricElement: HTMLElement, text: string, language?: string | null): void;

package/dist/inject.js

@@ -11,6 +11,7 @@
 // animates is one word, so every part is split on whitespace with its timing pro-rated across the
 // split by character count. A line that arrives with no timed parts at all is rebuilt the same way
 // into zero duration words, so line synced lyrics reach the DOM the sweep already knows.
+import { releasePart } from "./engine.js";
 import { alignImageGlowRun, wrapImageHighlight } from "./imageHighlights.js";
 import { normalizeLanguage } from "./language.js";
 import { BACKGROUND_LINE_CLASS, BACKGROUND_LYRIC_CLASS, BIDI_RUN_CLASS, BIDI_SENSITIVE_CLASS, CONTENT_LINE_CLASS, EXPLICIT_WORD_CLASS, HIGHLIGHT_RUN_CLASS, LETTER_CLASS, LINE_MAIN_CLASS, LINE_SYNCED_WORD_CLASS, LONG_WORD_GROUP_CLASS, ROMANIZED_LYRICS_CLASS, RTL_CLASS, TRANSLATED_LYRICS_CLASS, WORD_CLASS, WORD_GROUP_CLASS, WORD_HIGHLIGHT_CLASS, WORD_HIGHLIGHT_LETTERED_CLASS, WORD_STATE_ATTR, WORD_STATE_UPCOMING, ZERO_DURATION_ANIMATION_CLASS, } from "./constants.js";
@@ -421,8 +422,81 @@ function repeatsLine(lyricElement, text) {
     ].find(run => !run.classList.contains(HIGHLIGHT_RUN_CLASS));
     return mainRun?.textContent != null && isSameText(mainRun.textContent, text);
 }
+/**
+ * What each injected decoration was made from. A line a swap kept still carries what was hung on it,
+ * so injecting the same again is nothing to do and injecting something else replaces it.
+ */
+const decorationSources = new WeakMap();
+/**
+ * Has the next tick set a line's animations up again, the parts just added to it included. A line
+ * already being sung sets its parts up once, so parts added after that would stay still until the
+ * line came round again. Its running animations are left alone: the setup replaces each one, so
+ * nothing on the line goes still in between.
+ */
+function rearmLineAnimations(lineData) {
+    lineData.isAnimating = false;
+}
+/** Takes a decoration off its line, along with any timed parts it brought, and stops their animations. */
+function removeDecoration(lineData, decoration) {
+    lineData.parts = lineData.parts.filter(part => {
+        if (!decoration.contains(part.lyricElement))
+            return true;
+        releasePart(part);
+        return false;
+    });
+    decoration.remove();
+}
+/**
+ * Takes the romanization off a line, along with any timed parts it brought. A line a swap kept goes on
+ * carrying what was hung on it, so this is how a consumer drops one it no longer wants. Answers
+ * whether there was one to take off.
+ */
+export function removeRomanization(lyricElement, lineData) {
+    const existing = lyricElement.querySelector(`:scope > .${ROMANIZED_LYRICS_CLASS}`);
+    if (existing === null)
+        return false;
+    removeDecoration(lineData, existing);
+    return true;
+}
+/**
+ * Takes the translation off a line. A line a swap kept goes on carrying what was hung on it, so this is
+ * how a consumer drops one it no longer wants. Answers whether there was one to take off.
+ */
+export function removeTranslation(lyricElement) {
+    const existing = lyricElement.querySelector(`:scope > .${TRANSLATED_LYRICS_CLASS}`);
+    if (existing === null)
+        return false;
+    existing.remove();
+    return true;
+}
+/**
+ * Moves the translation and romanization hung on one line onto the line built in its place, with any
+ * timed parts they brought, so a line rebuilt for its timing keeps what the consumer hung on it. The
+ * parts are let go of whatever the old line was showing; the new line sets them up again with its own.
+ */
+export function moveDecorations(from, to) {
+    const decorations = Array.from(from.lyricElement.childNodes).filter((node) => node.classList?.contains(ROMANIZED_LYRICS_CLASS) === true ||
+        node.classList?.contains(TRANSLATED_LYRICS_CLASS) === true);
+    for (const decoration of decorations) {
+        from.parts = from.parts.filter(part => {
+            if (!decoration.contains(part.lyricElement))
+                return true;
+            releasePart(part);
+            to.parts.push(part);
+            return false;
+        });
+        to.lyricElement.appendChild(decoration);
+    }
+}
 export function injectRomanization(doc, lyricElement, lineData, text, timedRomanization = null) {
-    if (lyricElement.querySelector(`.${ROMANIZED_LYRICS_CLASS}`) || repeatsLine(lyricElement, text))
+    const source = JSON.stringify([text, timedRomanization ?? null]);
+    const existing = lyricElement.querySelector(`:scope > .${ROMANIZED_LYRICS_CLASS}`);
+    if (existing !== null) {
+        if (decorationSources.get(existing) === source)
+            return;
+        removeDecoration(lineData, existing);
+    }
+    if (repeatsLine(lyricElement, text))
         return;
     const romanizedLine = doc.createElement("div");
     romanizedLine.classList.add(ROMANIZED_LYRICS_CLASS, CONTENT_LINE_CLASS);
@@ -432,15 +506,24 @@ export function injectRomanization(doc, lyricElement, lineData, text, timedRoman
     applyDirection(romanizedLine, text);
     if (timedRomanization && timedRomanization.length > 0 && !disableRichsync.getBooleanValue()) {
         createLyricsLine(doc, timedRomanization, lineData, romanizedLine, { splitBackgroundLine: false });
+        rearmLineAnimations(lineData);
     }
     else {
         romanizedLine.textContent = text;
     }
+    decorationSources.set(romanizedLine, source);
     const translation = lyricElement.querySelector(`.${TRANSLATED_LYRICS_CLASS}`);
     lyricElement.insertBefore(romanizedLine, translation);
 }
 export function injectTranslation(doc, lyricElement, text, language) {
-    if (lyricElement.querySelector(`.${TRANSLATED_LYRICS_CLASS}`) || repeatsLine(lyricElement, text))
+    const source = JSON.stringify([text, normalizeLanguage(language)]);
+    const existing = lyricElement.querySelector(`:scope > .${TRANSLATED_LYRICS_CLASS}`);
+    if (existing !== null) {
+        if (decorationSources.get(existing) === source)
+            return;
+        existing.remove();
+    }
+    if (repeatsLine(lyricElement, text))
         return;
     const translatedLine = doc.createElement("div");
     translatedLine.classList.add(TRANSLATED_LYRICS_CLASS, CONTENT_LINE_CLASS);
@@ -448,5 +531,6 @@ export function injectTranslation(doc, lyricElement, text, language) {
     translatedLine.lang = normalizeLanguage(language);
     applyDirection(translatedLine, text);
     translatedLine.textContent = text;
+    decorationSources.set(translatedLine, source);
     lyricElement.appendChild(translatedLine);
 }

package/dist/renderer.js

@@ -11,10 +11,10 @@
 // diagnostic overlay supplies the sink, and one that says nothing draws nothing.
 import { imageHighlights, refreshInstrumentalImages } from "./imageHighlights.js";
 import { CUSTOM_THEME_STYLE_ID } from "./constants.js";
-import { clearLyrics, clearOnScreenLyrics as clearEngineOnScreenLyrics, clearStyleCaches as clearEngineStyleCaches, createAnimationEngineInstance, getRenderedLines, getRenderedSyncType, hasUnsyncedLyrics, noteContainerResize, noteUserScroll as noteEngineUserScroll, noteVisibilityChange as noteEngineVisibilityChange, relayout, resetScrollResume, resolveTickOptions, retickFromPlaybackClock as retickEngineFromPlaybackClock, scheduleLyricPositionUpdate as scheduleEngineLyricPositionUpdate, tickView, } from "./engine.js";
+import { clearLyrics, clearOnScreenLyrics as clearEngineOnScreenLyrics, clearStyleCaches as clearEngineStyleCaches, createAnimationEngineInstance, getRenderedLines, getRenderedSyncType, hasUnsyncedLyrics, noteContainerResize, noteUserScroll as noteEngineUserScroll, noteVisibilityChange as noteEngineVisibilityChange, relayout, resetScrollResume, resolveTickOptions, settleSwappedLines, retickFromPlaybackClock as retickEngineFromPlaybackClock, scheduleLyricPositionUpdate as scheduleEngineLyricPositionUpdate, tickView, } from "./engine.js";
 import { parseThemeConfig, setThemeSettings } from "./themeSettings.js";
 import { applyLyricLanguage, normalizeLanguage, resolveLyricLanguages } from "./language.js";
-import { setLyrics as buildLyricsView } from "./view.js";
+import { setLyrics as buildLyricsView, swapLyrics as swapLyricsView } from "./view.js";
 /**
  * What the default `seek` dispatches at the mount. A consumer that gave the renderer no way to
  * reach its player can listen for this instead of writing a host.
@@ -269,22 +269,34 @@ export function createLyricsRenderer(rendererOptions) {
             if (!nextMount) {
                 throw new Error("A lyrics renderer needs a mount: give one to createLyricsRenderer or to setLyrics");
             }
-            // Before the mount moves, so a second song built somewhere else takes the first one's
-            // container with it rather than orphaning it in the mount it was built in.
-            clearBuiltView();
-            mount = nextMount;
-            buildLyricsView(engine, nextMount, lyrics, {
+            const viewOptions = {
                 language: options?.language,
                 loaderVisible: options?.loaderVisible ?? false,
                 noLyrics: options?.noLyrics ?? false,
                 songwriters: options?.songwriters,
-            });
+                songKey: options?.songKey,
+            };
+            // Lyrics for the song already on screen are swapped in, so whatever the two share stays exactly
+            // as it was. Read before the swap: the scroll is where the reader was.
+            const scrollTopBefore = host.getScrollElement()?.scrollTop ?? 0;
+            const swapped = swapLyricsView(engine, nextMount, lyrics, viewOptions);
+            if (swapped === null) {
+                // Before the mount moves, so a second song built somewhere else takes the first one's
+                // container with it rather than orphaning it in the mount it was built in.
+                clearBuiltView();
+                mount = nextMount;
+                buildLyricsView(engine, nextMount, lyrics, viewOptions);
+            }
             syncImagePaint();
             currentLyrics = lyrics;
             currentLanguage = normalizeLanguage(options?.language);
             measure();
-            if (engine.lyricsContainer)
+            if (swapped !== null) {
+                settleSwappedLines(engine, swapped, scrollTopBefore);
+            }
+            else if (engine.lyricsContainer) {
                 observeContainer(engine.lyricsContainer);
+            }
         },
         setLanguage(language) {
             const normalized = normalizeLanguage(language);

package/dist/themeSettings.d.ts

@@ -21,3 +21,9 @@ export declare class Setting {
 export declare function parseThemeConfig(css: string): Map<string, string>;
 export declare function registerThemeSetting(key: string, defaultValue: number | boolean | string, requiresLyricReload?: boolean): Setting;
 export declare function setThemeSettings(map: Map<string, string>): boolean;
+/**
+ * The values of every setting that changes how lines are built, as one comparable string. Two builds
+ * that answer the same here built their lines the same way, so a line built under one can stand in
+ * for the same line built under the other.
+ */
+export declare function lyricBuildSettingsKey(): string;

package/dist/themeSettings.js

@@ -124,3 +124,16 @@ export function setThemeSettings(map) {
     }
     return needsLyricReload;
 }
+/**
+ * The values of every setting that changes how lines are built, as one comparable string. Two builds
+ * that answer the same here built their lines the same way, so a line built under one can stand in
+ * for the same line built under the other.
+ */
+export function lyricBuildSettingsKey() {
+    const values = [];
+    for (const [key, setting] of keyToSettingMap) {
+        if (setting.requiresLyricReload)
+            values.push(`${key}=${String(setting.value)}`);
+    }
+    return values.join(";");
+}

package/dist/types.d.ts

@@ -110,8 +110,9 @@ export interface LyricsRendererOptions {
  */
 export interface LyricsRenderer {
     /**
-     * Replaces whatever this renderer last built. Every option has a default, so a consumer with an
-     * opinion about only one of them says only that one. The mount rides along with the CSS flags
+     * Replaces whatever this renderer last built, or, given the `songKey` of the song on screen, swaps
+     * these lyrics into it so the lines the two share stay as they were. Every option has a default, so a
+     * consumer with an opinion about only one of them says only that one. The mount rides along with the CSS flags
      * rather than taking a parameter of its own: it is an option of this call like the others, and a
      * third parameter would have every caller that only wants to move the mount pass over the two in
      * front of it.

package/dist/view.d.ts

@@ -1,4 +1,5 @@
 import { type AnimationEngineInstance } from "./engine.js";
+import { type LineData } from "./inject.js";
 import type { Lyric } from "./types.js";
 export interface SetLyricsOptions {
     /** BCP 47 language of the original lyrics. Kana/Hangul provide a fallback when omitted. */
@@ -13,6 +14,12 @@ export interface SetLyricsOptions {
     noLyrics: boolean;
     /** Who wrote the song, shown after the last line. */
     songwriters?: readonly string[];
+    /**
+     * Which song these lyrics are for. Lyrics given with the key the view on screen was given are
+     * swapped into it, so lines the two share stay as they were; without a key, or with another one,
+     * the view is built anew.
+     */
+    songKey?: string;
 }
 /**
  * Replaces whatever the mount holds with a container built from these lyrics, and hands the render
@@ -24,3 +31,21 @@ export interface SetLyricsOptions {
  * @param options - What the container records for CSS to key on
  */
 export declare function setLyrics(engine: AnimationEngineInstance, mount: HTMLElement, lyrics: Lyric[], options: SetLyricsOptions): void;
+/**
+ * Where each line of a swap was before it, in the container's coordinates, and how tall it was: a
+ * kept line's own place, and for a line built in place of one, the place of the line it replaced.
+ */
+export type SwapPositions = Map<LineData, {
+    position: number;
+    height: number;
+    offset: number;
+}>;
+/**
+ * Swaps these lyrics into the view already on screen, rebuilding only the lines that differ, and
+ * answers where each line was before so the caller can carry the view across the change. Answers
+ * null without touching anything when the view cannot be swapped, and the caller builds it whole.
+ *
+ * Nothing about where the reader is goes back to the start of a song: the scroll, a pause the reader
+ * scrolled into, and the scrolls the engine is waiting to swallow are all the song's before.
+ */
+export declare function swapLyrics(engine: AnimationEngineInstance, mount: HTMLElement, lyrics: Lyric[], options: SetLyricsOptions): SwapPositions | null;

package/dist/view.js

@@ -2,19 +2,23 @@
 // records the engine animates them through. `inject.ts` builds what goes inside a line; this builds
 // the line and everything around it.
 //
-// A song replaces the whole view rather than being diffed into the last one. Every record the
-// engine holds points at an element built here and carries the `Animation` objects running against
-// it, so a partial update would leave the engine holding pieces of the song before.
+// A first song builds the whole view. A song given to a view that already holds one is swapped into
+// it line by line: a line that would build the same as one already on screen keeps that element, its
+// record and the animations running against it, and only the lines that differ are built again. The
+// engine is told which records went and which new ones stand where they stood, so nothing it holds
+// keeps pointing into the song before. Anything that changes every line at once (the mount, a theme
+// setting lines are built by, lyrics that lose or gain their timing) builds the whole view again.
 //
 // This is also the one place outside the engine that writes engine view state, because building the
 // lines is where those values are first knowable: the container, the records, the sync type, the
 // size they were measured at, and the scrolls to swallow before the view has settled.
 import { CREDITS_CLASS, CREDITS_NAMES_CLASS, CREDITS_TEXT_CLASS, LINE_CLASS, LYRICS_CLASS, RTL_CLASS, } from "./constants.js";
-import { playerTimeForLyricTime, setupLineCullObserver } from "./engine.js";
-import { addSeekHandler, applyDirection, buildLineSyncedParts, createLyricsLine, deriveSyncType, disableRichsync, findNearestAgent, hideCredits, isNearestLyricRtl, newLineData, } from "./inject.js";
+import { lineScrollOffset, playerTimeForLyricTime, replaceRenderedLines, setupLineCullObserver, } from "./engine.js";
+import { addSeekHandler, applyDirection, buildLineSyncedParts, createLyricsLine, deriveSyncType, disableRichsync, findNearestAgent, hideCredits, isNearestLyricRtl, moveDecorations, newLineData, } from "./inject.js";
 import { refreshInstrumentalImages } from "./imageHighlights.js";
 import { createInstrumentalElement } from "./instrumental.js";
 import { applyLyricLanguage, resolveLyricLanguages } from "./language.js";
+import { lyricBuildSettingsKey } from "./themeSettings.js";
 import { isGecko } from "./util.js";
 const INITIAL_SKIP_SCROLLS = 2;
 const SKIP_SCROLL_DECAY_MS = 2000;
@@ -61,6 +65,132 @@ function buildCredits(doc, songwriters) {
     credits.appendChild(text);
     return credits;
 }
+/** Everything a line's element is built from, so two lines that answer the same build the same. */
+const lineSignatures = new WeakMap();
+/**
+ * A line's words and what a consumer decorates it from. A line rebuilt for its timing alone answers
+ * the same, so the translation and romanization hung on the line it replaced still belong to it.
+ */
+const decorationKeys = new WeakMap();
+function decorationKey(item) {
+    return JSON.stringify([
+        item.words,
+        item.translation ?? null,
+        item.translations ?? null,
+        item.romanization ?? null,
+        item.timedRomanization ?? null,
+    ]);
+}
+/** What the lines on screen were built against: the mount, the settings and whether they carry time. */
+const builtViews = new WeakMap();
+/** A line's own timing as built, so a line whose times a consumer moved since is not kept as it is. */
+const builtTimings = new WeakMap();
+function lineTimings(line, parts = line.parts) {
+    return [line.time, line.duration, ...parts.flatMap(part => [part.time, part.duration])];
+}
+function timingsUnchanged(line) {
+    const built = builtTimings.get(line);
+    if (built === undefined)
+        return false;
+    const now = lineTimings(line, line.parts.slice(0, (built.length - 2) / 2));
+    return now.length === built.length && now.every((value, index) => value === built[index]);
+}
+function buildContext(engine, lyrics, options) {
+    return {
+        allZero: lyrics.every(item => item.startTimeMs === 0),
+        languages: resolveLyricLanguages(lyrics, options.language),
+        seek: timeS => engine.host.seek(playerTimeForLyricTime(engine, timeS)),
+    };
+}
+function viewKey(context) {
+    return `${context.allZero}|${lyricBuildSettingsKey()}`;
+}
+// The language is left out: it is an attribute rather than anything built, and a swap writes it onto
+// every kept line instead.
+function lineSignature(lyrics, lineIndex) {
+    const item = lyrics[lineIndex];
+    const parts = item.parts?.map(part => [
+        part.startTimeMs,
+        part.durationMs,
+        part.words,
+        part.isBackground === true,
+        part.explicit === true,
+    ]);
+    // An instrumental line takes its side and direction from the lines around it.
+    const neighbours = item.isInstrumental
+        ? [findNearestAgent(lyrics, lineIndex), isNearestLyricRtl(lyrics, lineIndex)]
+        : null;
+    return JSON.stringify([
+        item.startTimeMs,
+        item.durationMs,
+        item.words,
+        item.isInstrumental === true,
+        item.agent ?? null,
+        parts ?? null,
+        neighbours,
+        decorationKey(item),
+    ]);
+}
+function buildLine(doc, lyrics, lineIndex, context) {
+    const lyricItem = lyrics[lineIndex];
+    const lyricElement = doc.createElement("div");
+    const line = newLineData(lyricElement, lyricItem.startTimeMs, lyricItem.durationMs);
+    lyricElement.dataset.time = String(line.time);
+    lyricElement.dataset.duration = String(line.duration);
+    lyricElement.dataset.lineNumber = String(lineIndex);
+    lyricElement.classList.add(LINE_CLASS);
+    lyricElement.dir = "auto";
+    applyLyricLanguage(lyricElement, context.languages[lineIndex]);
+    addSeekHandler(context.seek, lyricElement, context.allZero);
+    if (lyricItem.isInstrumental) {
+        buildInstrumentalLine(doc, lyricElement, lyrics, lineIndex);
+    }
+    else {
+        buildSungLine(doc, lyricElement, lyricItem, line);
+        if (!lyricItem.words?.trim())
+            lyricElement.dataset.blank = "true";
+    }
+    lineSignatures.set(line, lineSignature(lyrics, lineIndex));
+    decorationKeys.set(line, decorationKey(lyricItem));
+    builtTimings.set(line, lineTimings(line));
+    return line;
+}
+/**
+ * Writes what the container records about the song as a whole, over whatever it recorded about the
+ * last one, and puts the credits after the last line.
+ */
+function writeContainerState(engine, container, lyrics, options, creditsBefore = null) {
+    const doc = engine.document;
+    const syncType = deriveSyncType(lyrics);
+    container.dataset.sync = syncType;
+    if (engine.layout === "stage") {
+        container.dataset.layout = "stage";
+        // Sides only when both are sung, so a song with one singer stays centred whichever voice it is.
+        const sung = lyrics.filter(item => !item.isInstrumental && item.words?.trim() && item.agent !== "v1000");
+        const onRight = (item) => item.agent === "v2" || item.agent === "v3";
+        if (sung.some(onRight) && sung.some(item => !onRight(item))) {
+            container.dataset.stageDuet = "";
+        }
+        else {
+            delete container.dataset.stageDuet;
+        }
+    }
+    container.dataset.loaderVisible = String(options.loaderVisible);
+    if (options.noLyrics) {
+        container.dataset.noLyrics = "true";
+    }
+    else {
+        delete container.dataset.noLyrics;
+    }
+    // Built again on every song, even the same names: consumers hang their own things off the credits
+    // once per build, and a kept one would collect them.
+    container.querySelector(`:scope > .${CREDITS_CLASS}`)?.remove();
+    const songwriters = options.songwriters ?? [];
+    if (songwriters.length > 0 && !options.noLyrics && !hideCredits.getBooleanValue()) {
+        container.insertBefore(buildCredits(doc, songwriters), creditsBefore);
+    }
+    engine.syncType = syncType;
+}
 /**
  * Replaces whatever the mount holds with a container built from these lyrics, and hands the render
  * records, the container and its measured size to the engine that animates them.
@@ -77,56 +207,20 @@ export function setLyrics(engine, mount, lyrics, options) {
     if (isGecko())
         container.dataset.browserEngine = "gecko";
     mount.replaceChildren(container);
-    const allZero = lyrics.every(item => item.startTimeMs === 0);
-    const seek = (timeS) => engine.host.seek(playerTimeForLyricTime(engine, timeS));
+    const context = buildContext(engine, lyrics, options);
     const lines = [];
-    const syncType = deriveSyncType(lyrics);
-    const languages = resolveLyricLanguages(lyrics, options.language);
-    for (const [lineIndex, lyricItem] of lyrics.entries()) {
-        const lyricElement = doc.createElement("div");
-        const line = newLineData(lyricElement, lyricItem.startTimeMs, lyricItem.durationMs);
-        lyricElement.dataset.time = String(line.time);
-        lyricElement.dataset.duration = String(line.duration);
-        lyricElement.dataset.lineNumber = String(lineIndex);
-        lyricElement.classList.add(LINE_CLASS);
-        lyricElement.dir = "auto";
-        applyLyricLanguage(lyricElement, languages[lineIndex]);
-        addSeekHandler(seek, lyricElement, allZero);
+    for (const lineIndex of lyrics.keys()) {
+        const line = buildLine(doc, lyrics, lineIndex, context);
         lines.push(line);
-        if (lyricItem.isInstrumental) {
-            buildInstrumentalLine(doc, lyricElement, lyrics, lineIndex);
-        }
-        else {
-            buildSungLine(doc, lyricElement, lyricItem, line);
-            if (!lyricItem.words?.trim())
-                lyricElement.dataset.blank = "true";
-        }
-        container.appendChild(lyricElement);
-    }
-    const songwriters = options.songwriters ?? [];
-    if (songwriters.length > 0 && !options.noLyrics && !hideCredits.getBooleanValue()) {
-        container.appendChild(buildCredits(doc, songwriters));
+        container.appendChild(line.lyricElement);
     }
     engine.skipScrolls = INITIAL_SKIP_SCROLLS;
     engine.skipScrollsDecayTimes = Array.from({ length: INITIAL_SKIP_SCROLLS }, () => Date.now() + SKIP_SCROLL_DECAY_MS);
     engine.scrollResumeTime = 0;
-    container.dataset.sync = syncType;
-    if (engine.layout === "stage") {
-        container.dataset.layout = "stage";
-        // Sides only when both are sung, so a song with one singer stays centred whichever voice it is.
-        const sung = lyrics.filter(item => !item.isInstrumental && item.words?.trim() && item.agent !== "v1000");
-        const onRight = (item) => item.agent === "v2" || item.agent === "v3";
-        if (sung.some(onRight) && sung.some(item => !onRight(item))) {
-            container.dataset.stageDuet = "";
-        }
-    }
-    container.dataset.loaderVisible = String(options.loaderVisible);
-    if (options.noLyrics) {
-        container.dataset.noLyrics = "true";
-    }
+    writeContainerState(engine, container, lyrics, options);
     engine.lines = lines;
     engine.lyricsContainer = container;
-    engine.syncType = syncType;
+    builtViews.set(engine, { mount, key: viewKey(context), songKey: options.songKey });
     refreshInstrumentalImages(container, engine.window);
     // Measured last: the container is in the document, filled, and carrying the attributes CSS
     // sizes it by.
@@ -134,3 +228,164 @@ export function setLyrics(engine, mount, lyrics, options) {
     engine.lyricHeight = container.clientHeight;
     setupLineCullObserver(engine);
 }
+/**
+ * Pairs each new line with an old one that builds the same, keeping their order, so a kept element is
+ * never moved: the longest run of matches, found after the ends both songs share are set aside.
+ */
+function matchLines(previous, next) {
+    const matches = next.map(() => null);
+    let start = 0;
+    while (start < previous.length && start < next.length && previous[start] === next[start]) {
+        matches[start] = start;
+        start++;
+    }
+    let previousEnd = previous.length;
+    let nextEnd = next.length;
+    while (previousEnd > start && nextEnd > start && previous[previousEnd - 1] === next[nextEnd - 1]) {
+        previousEnd--;
+        nextEnd--;
+        matches[nextEnd] = previousEnd;
+    }
+    const rows = previousEnd - start;
+    const columns = nextEnd - start;
+    // A whole new song is no match for the one before and costs nothing to find out. Past this size
+    // the middle is rebuilt rather than searched, which is what every song was before swaps existed.
+    if (rows === 0 || columns === 0 || rows * columns > MATCH_SEARCH_LIMIT)
+        return matches;
+    const lengths = new Uint16Array((rows + 1) * (columns + 1));
+    const at = (row, column) => row * (columns + 1) + column;
+    for (let row = rows - 1; row >= 0; row--) {
+        for (let column = columns - 1; column >= 0; column--) {
+            lengths[at(row, column)] =
+                previous[start + row] === next[start + column]
+                    ? lengths[at(row + 1, column + 1)] + 1
+                    : Math.max(lengths[at(row + 1, column)], lengths[at(row, column + 1)]);
+        }
+    }
+    let row = 0;
+    let column = 0;
+    while (row < rows && column < columns) {
+        if (previous[start + row] === next[start + column]) {
+            matches[start + column] = start + row;
+            row++;
+            column++;
+        }
+        else if (lengths[at(row + 1, column)] >= lengths[at(row, column + 1)]) {
+            row++;
+        }
+        else {
+            column++;
+        }
+    }
+    return matches;
+}
+const MATCH_SEARCH_LIMIT = 250_000;
+/**
+ * Takes the first old line sung over the same time as a new one, so a line rebuilt for a retiming or
+ * a richer source takes over its predecessor's place, and an unrelated line never inherits a sung state.
+ */
+function takeOverlapping(candidates, line) {
+    const end = line.time + line.duration;
+    const index = candidates.findIndex(old => {
+        const oldEnd = old.time + old.duration;
+        return old.time === line.time || (old.time < end && line.time < oldEnd);
+    });
+    return index === -1 ? undefined : candidates.splice(index, 1)[0];
+}
+/**
+ * Swaps these lyrics into the view already on screen, rebuilding only the lines that differ, and
+ * answers where each line was before so the caller can carry the view across the change. Answers
+ * null without touching anything when the view cannot be swapped, and the caller builds it whole.
+ *
+ * Nothing about where the reader is goes back to the start of a song: the scroll, a pause the reader
+ * scrolled into, and the scrolls the engine is waiting to swallow are all the song's before.
+ */
+export function swapLyrics(engine, mount, lyrics, options) {
+    const container = engine.lyricsContainer;
+    const built = builtViews.get(engine);
+    if (container === null || built === undefined || built.mount !== mount || container.parentElement !== mount) {
+        return null;
+    }
+    // Another song, or one nobody named, starts from nothing rather than inheriting this one's place.
+    if (options.songKey === undefined || options.songKey !== built.songKey)
+        return null;
+    // Lines a consumer took off the screen without dropping the song are not there to keep.
+    const previousLines = engine.lines;
+    // An empty song is a fresh start rather than a song to carry anything into.
+    if (lyrics.length === 0 || previousLines.length === 0)
+        return null;
+    if (previousLines.some(line => line.lyricElement.parentNode !== container))
+        return null;
+    const context = buildContext(engine, lyrics, options);
+    if (built.key !== viewKey(context))
+        return null;
+    const doc = engine.document;
+    // A line whose times a consumer moved after it was built is built again, so the move is not applied twice.
+    const previousSignatures = previousLines.map(line => timingsUnchanged(line) ? (lineSignatures.get(line) ?? "") : `\u0000moved:${lineSignatures.get(line)}`);
+    const nextSignatures = lyrics.map((_, lineIndex) => lineSignature(lyrics, lineIndex));
+    // Whatever a consumer put after the lines and the credits, such as a footer, stays after them.
+    const children = Array.from(container.childNodes);
+    const oldCredits = container.querySelector(`:scope > .${CREDITS_CLASS}`);
+    const lastOwned = oldCredits ?? previousLines[previousLines.length - 1].lyricElement;
+    const trailing = children[children.indexOf(lastOwned) + 1] ?? null;
+    const matches = matchLines(previousSignatures, nextSignatures);
+    const kept = new Set();
+    const lines = [];
+    // A new line stands in for an old one when both sit in the same gap between kept lines, in order,
+    // so the engine can hand it what it held for the line it replaced.
+    const replaced = new Map();
+    const positions = new Map();
+    let previousCursor = 0;
+    let unmatchedOld = [];
+    const collectUnmatchedUntil = (end) => {
+        unmatchedOld = previousLines.slice(previousCursor, end);
+        previousCursor = end;
+    };
+    for (const [lineIndex, match] of matches.entries()) {
+        if (match !== null) {
+            const line = previousLines[match];
+            previousCursor = match + 1;
+            unmatchedOld = [];
+            kept.add(line);
+            line.lyricElement.dataset.lineNumber = String(lineIndex);
+            applyLyricLanguage(line.lyricElement, context.languages[lineIndex]);
+            lines.push(line);
+            positions.set(line, { position: line.position, height: line.height, offset: 0 });
+            continue;
+        }
+        if (unmatchedOld.length === 0) {
+            const nextMatch = matches.slice(lineIndex).find(value => value !== null);
+            collectUnmatchedUntil(nextMatch ?? previousLines.length);
+        }
+        const line = buildLine(doc, lyrics, lineIndex, context);
+        const standsFor = takeOverlapping(unmatchedOld, line);
+        if (standsFor !== undefined) {
+            replaced.set(line, standsFor);
+            positions.set(line, {
+                position: standsFor.position,
+                height: standsFor.height,
+                // A kept line finishes its own line scroll; this one starts where the line it replaced was.
+                offset: lineScrollOffset(engine, standsFor.lyricElement),
+            });
+            if (decorationKeys.get(standsFor) === decorationKeys.get(line))
+                moveDecorations(standsFor, line);
+        }
+        lines.push(line);
+    }
+    const dropped = previousLines.filter(line => !kept.has(line));
+    // In order, each new line before whichever kept line follows it, so a kept element never leaves the
+    // document and never loses the animations running against it.
+    let following = oldCredits ?? trailing;
+    for (let index = lines.length - 1; index >= 0; index--) {
+        const element = lines[index].lyricElement;
+        if (!kept.has(lines[index]))
+            container.insertBefore(element, following);
+        following = element;
+    }
+    replaceRenderedLines(engine, lines, dropped, replaced);
+    for (const line of dropped)
+        line.lyricElement.remove();
+    writeContainerState(engine, container, lyrics, options, trailing);
+    refreshInstrumentalImages(container, engine.window);
+    return positions;
+}

package/package.json

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