@music-lyric-player/base 0.13.0 → 0.15.0

package/dist/index.ecma.d.ts

@@ -10,14 +10,18 @@ export declare class BaseLyricPlayer {
     private state;
     private active;
     private time;
-    private offset;
     private info;
+    private merger;
+    private offset;
+    private driver;
     constructor();
     private onConfigUpdate;
     private handleGetCurrentTime;
     private handleGetEffectiveTime;
-    private handleRefreshOffset;
-    private handleGetLineTime;
+    /**
+     * Rebuild the merged line-end table from the current lyric and merge config.
+     */
+    private handleBuildMergedLineEnd;
     private handleGetActiveIndex;
     private handleBridgeActive;
     private handleEmitLinesUpdate;
@@ -27,6 +31,7 @@ export declare class BaseLyricPlayer {
     updateLyric(info: Lyric.Info): void;
     /**
      * Start playback
+     *
      * @param time Optional time in ms to seek to before starting playback. If not provided, playback will start from the current position.
      */
     play(time?: number): void;
@@ -40,13 +45,17 @@ export declare class BaseLyricPlayer {
     dispose(): void;
     /**
      * Update the temp offset in ms (the user's temporary adjustment).
+     *
      * Stacked on top of the global config offset and the lyric's meta offset, then resyncs immediately.
+     *
      * @param value temp offset in ms; non-finite values are treated as 0.
      */
     updateTempOffset(value: number): void;
     /**
      * Find all active lines at the given time (ms). Does not mutate internal state.
+     *
      * Assumes `info.lines` is sorted by `time.start` ascending.
+     *
      * @param time time in ms to find active lines for.
      */
     matchLinesWithTime(time: number): {
@@ -55,7 +64,9 @@ export declare class BaseLyricPlayer {
     };
     /**
      * Convert a content (lyric) time to the playback clock by removing the active offset.
+     *
      * Seeking playback to the returned time makes a line at `contentTime` become active.
+     *
      * @param contentTime content time in ms (e.g. a line's start).
      */
     convertContentTime(contentTime: number): number;
@@ -169,6 +180,26 @@ declare interface Root {
      * @default true
      */
     bridgeActive?: boolean;
+    /**
+     * Merge the deactivation of consecutive lines whose raw end times fall within this many ms,
+     * so close‑ending lines leave the active state together instead of one‑by‑one, avoiding a double scroll jump.
+     *
+     * Earlier‑ending lines are only ever extended to the cluster's later end, never cut short.
+     * `0` disables merging.
+     *
+     * @default 300
+     */
+    mergeWindow?: number;
+    /**
+     * Maximum number of consecutive lines that {@link mergeWindow} may fold into a single deactivation batch.
+     *
+     * When a run of close‑ending lines is longer than this, the batch is force‑flushed every `mergeLimit` lines so no batch ever holds more than this many lines.
+     *
+     * A value of `0` or less removes the cap; `1` effectively disables merging.
+     *
+     * @default 3
+     */
+    mergeLimit?: number;
     /**
      * Lyric time offset settings.
      */