libbitsub 1.9.0 → 1.10.0

package/dist/ts/renderers.d.ts

@@ -2,7 +2,7 @@
  * High-level video-integrated subtitle renderers for libbitsub.
  * Handles canvas overlay, video sync, and subtitle fetching.
  */
-import type { AutoVideoSubtitleOptions, SubtitleCueMetadata, SubtitleData, SubtitleDisplaySettings, SubtitleParserMetadata, SubtitleRendererBackend, SubtitleRendererEvent, VideoSubtitleOptions, VideoVobSubOptions } from './types';
+import type { AutoVideoSubtitleOptions, SubtitleCacheStats, SubtitleCueMetadata, SubtitleData, SubtitleDiagnosticWarning, SubtitleDisplaySettings, SubtitleLastRenderInfo, SubtitleParserMetadata, SubtitleRendererBackend, SubtitleRendererEvent, VideoSubtitleOptions, VideoVobSubOptions, WorkerRendererState } from './types';
 import { WebGPURenderer } from './webgpu-renderer';
 import { WebGL2Renderer } from './webgl2-renderer';
 interface SubtitleRenderLayout {
@@ -12,6 +12,11 @@ interface SubtitleRenderLayout {
     shiftY: number;
     opacity: number;
 }
+interface RenderFrameOutcome {
+    status: 'rendered' | 'cleared' | 'pending' | 'empty' | 'failed';
+    data: SubtitleData | null;
+    warning: SubtitleDiagnosticWarning | null;
+}
 /** Performance statistics for subtitle renderer */
 export interface SubtitleRendererStats {
     /** Total frames rendered since initialization */
@@ -70,7 +75,10 @@ declare abstract class BaseVideoSubtitleRenderer {
     protected prefetchBefore: number;
     protected prefetchAfter: number;
     protected onEvent?: (event: SubtitleRendererEvent) => void;
+    protected onWarning?: (warning: SubtitleDiagnosticWarning) => void;
     protected currentRendererBackend: SubtitleRendererBackend | null;
+    protected readonly debug: boolean;
+    protected lastRenderInfo: SubtitleLastRenderInfo | null;
     private loadedMetadataHandler;
     private seekedHandler;
     protected webgpuRenderer: WebGPURenderer | null;
@@ -92,6 +100,10 @@ declare abstract class BaseVideoSubtitleRenderer {
     getDisplaySettings(): SubtitleDisplaySettings;
     /** Get performance statistics */
     abstract getStats(): SubtitleRendererStats;
+    /** Get cache-related diagnostics for the active renderer session. */
+    getCacheStats(): SubtitleCacheStats;
+    /** Get the most recent render attempt when debug mode is enabled. */
+    getLastRenderInfo(): SubtitleLastRenderInfo | null;
     /** Get parser metadata for the active subtitle track. */
     getMetadata(): SubtitleParserMetadata | null;
     /** Get the most recently displayed cue metadata. */
@@ -113,11 +125,13 @@ declare abstract class BaseVideoSubtitleRenderer {
     /** Create the canvas overlay positioned over the video. */
     protected createCanvas(): void;
     protected emitEvent(event: SubtitleRendererEvent): void;
+    protected emitWarning(warning: SubtitleDiagnosticWarning): void;
     protected setParserMetadata(metadata: SubtitleParserMetadata | null): void;
     protected emitWorkerState(enabled: boolean, ready: boolean, sessionId: string | null, fallback?: boolean): void;
     protected emitCacheChange(cachedFrames: number, pendingRenders: number): void;
     protected emitCueChange(cue: SubtitleCueMetadata | null): void;
     protected emitRendererBackend(renderer: SubtitleRendererBackend): void;
+    protected recordLastRenderInfo(info: SubtitleLastRenderInfo): void;
     private initWebGPU;
     private initWebGL2;
     /** Initialize Canvas2D renderer. */
@@ -138,12 +152,13 @@ declare abstract class BaseVideoSubtitleRenderer {
     protected abstract findCurrentIndex(time: number): number;
     protected abstract renderAtIndex(index: number): SubtitleData | undefined;
     protected abstract buildCueMetadata(index: number): SubtitleCueMetadata | null;
+    protected abstract getWorkerRendererState(): WorkerRendererState;
     /** Check if a render is pending for the given index (async loading in progress) */
     protected abstract isPendingRender(index: number): boolean;
     /** Start the render loop. */
     protected startRenderLoop(): void;
     /** Render a subtitle frame to the canvas. */
-    protected renderFrame(time: number, index: number): void;
+    protected renderFrame(time: number, index: number): RenderFrameOutcome;
     protected computeLayout(data: SubtitleData): SubtitleRenderLayout;
     /** Render using WebGPU. */
     private renderFrameWebGPU;
@@ -167,6 +182,7 @@ export declare class PgsRenderer extends BaseVideoSubtitleRenderer {
     constructor(options: VideoSubtitleOptions);
     protected loadSubtitles(): Promise<void>;
     private loadOnMainThread;
+    protected getWorkerRendererState(): WorkerRendererState;
     /** Yield to main thread to prevent UI blocking */
     private yieldToMain;
     protected renderAtTime(time: number): SubtitleData | undefined;
@@ -202,6 +218,7 @@ export declare class VobSubRenderer extends BaseVideoSubtitleRenderer {
     constructor(options: VideoVobSubOptions);
     protected loadSubtitles(): Promise<void>;
     private loadOnMainThread;
+    protected getWorkerRendererState(): WorkerRendererState;
     /** Yield to main thread to prevent UI blocking */
     private yieldToMain;
     protected renderAtTime(time: number): SubtitleData | undefined;

package/dist/ts/renderers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"renderers.d.ts","sourceRoot":"","sources":["../../src/ts/renderers.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"renderers.d.ts","sourceRoot":"","sources":["../../src/ts/renderers.ts"],"names":[],"mappings":"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"}

package/dist/ts/renderers.js

@@ -2,6 +2,7 @@
  * High-level video-integrated subtitle renderers for libbitsub.
  * Handles canvas overlay, video sync, and subtitle fetching.
  */
+import { createSubtitleDiagnosticError, createSubtitleWarning, formatSubtitleWarningForConsole, normalizeSubtitleError, warningFromRenderIssue } from './diagnostics';
 import { initWasm } from './wasm';
 import { getOrCreateWorker, sendToWorker } from './worker';
 import { binarySearchTimestamp, convertFrameData, createWorkerSessionId, createWorkerState, detectSubtitleFormat, getSubtitleBounds, isMksSource, setCacheLimit as applyCacheLimit, setCachedFrame } from './utils';
@@ -59,7 +60,10 @@ class BaseVideoSubtitleRenderer {
     prefetchBefore = 0;
     prefetchAfter = 0;
     onEvent;
+    onWarning;
     currentRendererBackend = null;
+    debug;
+    lastRenderInfo = null;
     loadedMetadataHandler = null;
     seekedHandler = null;
     // WebGPU renderer (optional, falls back to WebGL2 then Canvas2D)
@@ -87,6 +91,8 @@ class BaseVideoSubtitleRenderer {
         this.onWebGPUFallback = options.onWebGPUFallback;
         this.onWebGL2Fallback = options.onWebGL2Fallback;
         this.onEvent = options.onEvent;
+        this.onWarning = options.onWarning;
+        this.debug = Boolean(options.debug);
         this.displaySettings = { ...DEFAULT_DISPLAY_SETTINGS, ...options.displaySettings };
         this.timeOffset = options.timeOffset ?? 0;
         this.cacheLimit = Math.max(0, Math.floor(options.cacheLimit ?? 24));
@@ -97,6 +103,29 @@ class BaseVideoSubtitleRenderer {
     getDisplaySettings() {
         return { ...this.displaySettings };
     }
+    /** Get cache-related diagnostics for the active renderer session. */
+    getCacheStats() {
+        const state = this.getWorkerRendererState();
+        return {
+            cacheLimit: this.cacheLimit,
+            cachedFrames: state.frameCache.size,
+            pendingRenders: state.pendingRenders.size,
+            totalEntries: state.timestamps.length,
+            usingWorker: state.useWorker && state.workerReady,
+            workerReady: state.workerReady,
+            sessionId: state.sessionId
+        };
+    }
+    /** Get the most recent render attempt when debug mode is enabled. */
+    getLastRenderInfo() {
+        if (!this.lastRenderInfo)
+            return null;
+        return {
+            ...this.lastRenderInfo,
+            cache: { ...this.lastRenderInfo.cache },
+            cue: this.lastRenderInfo.cue ? { ...this.lastRenderInfo.cue } : null
+        };
+    }
     /** Get parser metadata for the active subtitle track. */
     getMetadata() {
         return this.parserMetadata;
@@ -165,7 +194,7 @@ class BaseVideoSubtitleRenderer {
     /** Start initialization. */
     startInit() {
         this.init().catch((error) => {
-            this.emitEvent({ type: 'error', format: this.format, error: error instanceof Error ? error : new Error(String(error)) });
+            this.emitEvent({ type: 'error', format: this.format, error: normalizeSubtitleError(error, { format: this.format }) });
         });
     }
     /** Initialize the renderer. */
@@ -216,6 +245,13 @@ class BaseVideoSubtitleRenderer {
     emitEvent(event) {
         this.onEvent?.(event);
     }
+    emitWarning(warning) {
+        this.onWarning?.(warning);
+        this.emitEvent({ type: 'warning', warning });
+        if (this.debug && !this.onWarning) {
+            console.warn(formatSubtitleWarningForConsole(warning), warning.details ?? {});
+        }
+    }
     setParserMetadata(metadata) {
         this.parserMetadata = metadata;
         if (metadata) {
@@ -243,6 +279,11 @@ class BaseVideoSubtitleRenderer {
         this.currentRendererBackend = renderer;
         this.emitEvent({ type: 'renderer-change', renderer });
     }
+    recordLastRenderInfo(info) {
+        if (!this.debug)
+            return;
+        this.lastRenderInfo = info;
+    }
     /** Initialize WebGPU renderer. */
     async initWebGPU() {
         try {
@@ -378,8 +419,9 @@ class BaseVideoSubtitleRenderer {
                 const currentIndex = this.findCurrentIndex(currentTime);
                 // Only re-render if index changed
                 if (currentIndex !== this.lastRenderedIndex) {
+                    const cacheHit = currentIndex >= 0 && this.getWorkerRendererState().frameCache.has(currentIndex);
                     const startTime = performance.now();
-                    this.renderFrame(currentTime, currentIndex);
+                    const outcome = this.renderFrame(currentTime, currentIndex);
                     const endTime = performance.now();
                     // Track performance
                     const renderTime = endTime - startTime;
@@ -396,9 +438,28 @@ class BaseVideoSubtitleRenderer {
                     if (renderTime > frameBudget) {
                         this.perfStats.framesDropped++;
                     }
+                    if (outcome.warning) {
+                        this.emitWarning(outcome.warning);
+                    }
                     this.lastRenderedIndex = currentIndex;
                     this.lastRenderedTime = currentTime;
-                    this.emitCueChange(currentIndex >= 0 ? this.buildCueMetadata(currentIndex) : null);
+                    const cue = currentIndex >= 0 ? this.buildCueMetadata(currentIndex) : null;
+                    this.emitCueChange(cue);
+                    this.recordLastRenderInfo({
+                        time: currentTime,
+                        index: currentIndex,
+                        status: outcome.status,
+                        backend: this.currentRendererBackend,
+                        usingWorker: this.getCacheStats().usingWorker,
+                        cacheHit,
+                        renderDuration: Math.round(renderTime * 100) / 100,
+                        frameWidth: outcome.data?.width ?? null,
+                        frameHeight: outcome.data?.height ?? null,
+                        compositionCount: outcome.data?.compositionData.length ?? 0,
+                        cue,
+                        cache: this.getCacheStats(),
+                        capturedAt: endTime
+                    });
                     this.emitEvent({ type: 'stats', stats: this.getStats() });
                     if (currentIndex >= 0 && (this.prefetchBefore > 0 || this.prefetchAfter > 0)) {
                         const prefetch = this.prefetchAroundTime;
@@ -412,8 +473,9 @@ class BaseVideoSubtitleRenderer {
     }
     /** Render a subtitle frame to the canvas. */
     renderFrame(time, index) {
-        if (!this.canvas)
-            return;
+        if (!this.canvas) {
+            return { status: 'failed', data: null, warning: null };
+        }
         // Get the data for this index
         const data = index >= 0 ? this.renderAtIndex(index) : undefined;
         // If data is undefined, it means async loading is in progress
@@ -424,9 +486,11 @@ class BaseVideoSubtitleRenderer {
             // If not pending, it means the render returned no data immediately
             if (this.isPendingRender(index)) {
                 // Don't clear - keep showing the last frame while loading
-                return;
+                return { status: 'pending', data: null, warning: null };
             }
         }
+        const renderIssue = index >= 0 ? this.getWorkerRendererState().renderIssues.get(index) ?? null : null;
+        const warning = warningFromRenderIssue(renderIssue, { format: this.format, cueIndex: index });
         // Use best available renderer
         if (this.useWebGPU && this.webgpuRenderer) {
             this.renderFrameWebGPU(data, index);
@@ -437,6 +501,16 @@ class BaseVideoSubtitleRenderer {
         else {
             this.renderFrameCanvas2D(data, index);
         }
+        if (index < 0) {
+            return { status: 'cleared', data: null, warning: null };
+        }
+        if (warning) {
+            return { status: 'failed', data: data ?? null, warning };
+        }
+        if (!data || data.compositionData.length === 0) {
+            return { status: 'empty', data: data ?? null, warning: null };
+        }
+        return { status: 'rendered', data, warning: null };
     }
     computeLayout(data) {
         if (!this.canvas) {
@@ -600,6 +674,7 @@ class BaseVideoSubtitleRenderer {
         this.lastRenderedData = null;
         this.currentCueMetadata = null;
         this.parserMetadata = null;
+        this.lastRenderInfo = null;
         this.useWebGPU = false;
         this.useWebGL2 = false;
     }
@@ -668,6 +743,10 @@ export class PgsRenderer extends BaseVideoSubtitleRenderer {
                 catch (workerError) {
                     this.state.useWorker = false;
                     this.emitWorkerState(false, false, this.state.sessionId, true);
+                    this.emitWarning(createSubtitleWarning('WORKER_FALLBACK', 'PGS worker initialization failed, falling back to main-thread rendering.', {
+                        format: 'pgs',
+                        details: { reason: workerError instanceof Error ? workerError.message : String(workerError) }
+                    }));
                     if (!this.subContent && this.subUrl && data.byteLength === 0) {
                         const response = await fetch(this.subUrl);
                         if (!response.ok)
@@ -681,7 +760,7 @@ export class PgsRenderer extends BaseVideoSubtitleRenderer {
             this.onLoaded?.();
         }
         catch (error) {
-            const resolvedError = error instanceof Error ? error : new Error(String(error));
+            const resolvedError = normalizeSubtitleError(error, { format: 'pgs' });
             this.emitEvent({ type: 'error', format: 'pgs', error: resolvedError });
             this.onError?.(resolvedError);
         }
@@ -689,7 +768,7 @@ export class PgsRenderer extends BaseVideoSubtitleRenderer {
     async loadOnMainThread(data) {
         // Yield to browser before heavy parsing
         await this.yieldToMain();
-        this.pgsParser = new PgsParser();
+        this.pgsParser = new PgsParser({ debug: this.debug, onWarning: (warning) => this.emitWarning(warning) });
         // Parse in a microtask to allow UI to update
         await new Promise((resolve) => {
             // Use requestIdleCallback if available, otherwise setTimeout
@@ -702,10 +781,16 @@ export class PgsRenderer extends BaseVideoSubtitleRenderer {
                 this.state.metadata = this.pgsParser.getMetadata();
                 this.isLoaded = true;
                 this.setParserMetadata(this.state.metadata);
+                if (count === 0) {
+                    this.state.renderIssues.set(-1, 'INVALID_SUBTITLE_DATA');
+                }
                 resolve();
             });
         });
     }
+    getWorkerRendererState() {
+        return this.state;
+    }
     /** Yield to main thread to prevent UI blocking */
     yieldToMain() {
         // Use scheduler.yield if available (Chrome 115+)
@@ -732,19 +817,28 @@ export class PgsRenderer extends BaseVideoSubtitleRenderer {
         }
         if (this.state.useWorker && this.state.workerReady) {
             if (!this.state.pendingRenders.has(index)) {
-                const renderPromise = sendToWorker({
+                const renderTask = sendToWorker({
                     type: 'renderPgsAtIndex',
                     sessionId: this.state.sessionId,
                     index
-                }).then((response) => (response.type === 'pgsFrame' && response.frame ? convertFrameData(response.frame) : null));
+                }).then((response) => {
+                    if (response.type === 'pgsFrame') {
+                        return {
+                            frame: response.frame ? convertFrameData(response.frame) : null,
+                            renderIssue: response.renderIssue?.trim() || null
+                        };
+                    }
+                    return { frame: null, renderIssue: null };
+                });
+                const renderPromise = renderTask.then(({ frame }) => frame);
                 this.state.pendingRenders.set(index, renderPromise);
                 this.emitCacheChange(this.state.frameCache.size, this.state.pendingRenders.size);
-                renderPromise.then((result) => {
-                    setCachedFrame(this.state, index, result);
+                renderTask.then(({ frame, renderIssue }) => {
+                    setCachedFrame(this.state, index, frame, renderIssue);
                     this.state.pendingRenders.delete(index);
                     this.emitCacheChange(this.state.frameCache.size, this.state.pendingRenders.size);
                     // Force re-render on next frame by resetting lastRenderedIndex
-                    if (this.findCurrentIndex(this.video.currentTime) === index) {
+                    if (this.findCurrentIndex(this.video.currentTime + this.timeOffset) === index) {
                         this.lastRenderedIndex = -1;
                     }
                 });
@@ -753,7 +847,7 @@ export class PgsRenderer extends BaseVideoSubtitleRenderer {
             return undefined;
         }
         const rendered = this.pgsParser?.renderAtIndex(index) ?? null;
-        setCachedFrame(this.state, index, rendered);
+        setCachedFrame(this.state, index, rendered, this.pgsParser?.getLastRenderIssue() ?? null);
         this.emitCacheChange(this.state.frameCache.size, this.state.pendingRenders.size);
         return rendered ?? undefined;
     }
@@ -784,6 +878,7 @@ export class PgsRenderer extends BaseVideoSubtitleRenderer {
     }
     onSeek() {
         this.state.frameCache.clear();
+        this.state.renderIssues.clear();
         this.state.pendingRenders.clear();
         this.emitCacheChange(this.state.frameCache.size, this.state.pendingRenders.size);
         if (this.state.useWorker && this.state.workerReady) {
@@ -797,6 +892,7 @@ export class PgsRenderer extends BaseVideoSubtitleRenderer {
     }
     clearFrameCache() {
         this.state.frameCache.clear();
+        this.state.renderIssues.clear();
         this.state.pendingRenders.clear();
         this.lastRenderedIndex = -1;
         if (this.state.useWorker && this.state.workerReady) {
@@ -837,6 +933,7 @@ export class PgsRenderer extends BaseVideoSubtitleRenderer {
     dispose() {
         super.dispose();
         this.state.frameCache.clear();
+        this.state.renderIssues.clear();
         this.state.pendingRenders.clear();
         if (this.state.useWorker && this.state.workerReady) {
             sendToWorker({ type: 'disposePgs', sessionId: this.state.sessionId }).catch(() => { });
@@ -898,8 +995,9 @@ export class VobSubRenderer extends BaseVideoSubtitleRenderer {
             // Fetch missing parts
             const promises = [];
             if (!subArrayBuffer) {
-                if (!this.subUrl)
-                    throw new Error('No SUB content or URL provided');
+                if (!this.subUrl) {
+                    throw createSubtitleDiagnosticError('MISSING_INPUT', 'No SUB content or URL provided.', { format: 'vobsub' });
+                }
                 promises.push(fetch(this.subUrl)
                     .then((r) => {
                     if (!r.ok)
@@ -911,8 +1009,9 @@ export class VobSubRenderer extends BaseVideoSubtitleRenderer {
                 }));
             }
             if (!useMksSource && !idxData) {
-                if (!this.idxUrl)
-                    throw new Error('No IDX content or URL provided');
+                if (!this.idxUrl) {
+                    throw createSubtitleDiagnosticError('MISSING_INPUT', 'No IDX content or URL provided.', { format: 'vobsub' });
+                }
                 promises.push(fetch(this.idxUrl)
                     .then((r) => {
                     if (!r.ok)
@@ -927,7 +1026,7 @@ export class VobSubRenderer extends BaseVideoSubtitleRenderer {
                 await Promise.all(promises);
             }
             if (!subArrayBuffer || (!useMksSource && !idxData)) {
-                throw new Error('Failed to load VobSub data');
+                throw createSubtitleDiagnosticError('MISSING_INPUT', 'Failed to load VobSub data.', { format: 'vobsub' });
             }
             let subData = new Uint8Array(subArrayBuffer);
             if (this.state.useWorker) {
@@ -949,6 +1048,11 @@ export class VobSubRenderer extends BaseVideoSubtitleRenderer {
                             subData: transferableSubData
                         });
                     if (loadResponse.type === 'vobSubLoaded') {
+                        if (!useMksSource && idxData && loadResponse.count === 0) {
+                            throw createSubtitleDiagnosticError('BAD_IDX', 'IDX metadata did not yield any subtitle timestamps.', {
+                                format: 'vobsub'
+                            });
+                        }
                         this.state.workerReady = true;
                         this.state.metadata = loadResponse.metadata;
                         this.state.timestamps = loadResponse.timestamps;
@@ -965,6 +1069,10 @@ export class VobSubRenderer extends BaseVideoSubtitleRenderer {
                 catch (workerError) {
                     this.state.useWorker = false;
                     this.emitWorkerState(false, false, this.state.sessionId, true);
+                    this.emitWarning(createSubtitleWarning('WORKER_FALLBACK', 'VobSub worker initialization failed, falling back to main-thread rendering.', {
+                        format: 'vobsub',
+                        details: { reason: workerError instanceof Error ? workerError.message : String(workerError) }
+                    }));
                     if (!this.subContent && this.subUrl && subData.byteLength === 0) {
                         const response = await fetch(this.subUrl);
                         if (!response.ok)
@@ -978,7 +1086,7 @@ export class VobSubRenderer extends BaseVideoSubtitleRenderer {
             this.onLoaded?.();
         }
         catch (error) {
-            const resolvedError = error instanceof Error ? error : new Error(String(error));
+            const resolvedError = normalizeSubtitleError(error, { format: 'vobsub' });
             this.emitEvent({ type: 'error', format: 'vobsub', error: resolvedError });
             this.onError?.(resolvedError);
         }
@@ -986,7 +1094,7 @@ export class VobSubRenderer extends BaseVideoSubtitleRenderer {
     async loadOnMainThread(subData, idxData, useMksSource = false) {
         // Yield to browser before heavy parsing
         await this.yieldToMain();
-        this.vobsubParser = new VobSubParserLowLevel();
+        this.vobsubParser = new VobSubParserLowLevel({ debug: this.debug, onWarning: (warning) => this.emitWarning(warning) });
         // Parse in a microtask to allow UI to update
         await new Promise((resolve) => {
             const scheduleTask = typeof requestIdleCallback !== 'undefined'
@@ -1010,6 +1118,9 @@ export class VobSubRenderer extends BaseVideoSubtitleRenderer {
             });
         });
     }
+    getWorkerRendererState() {
+        return this.state;
+    }
     /** Yield to main thread to prevent UI blocking */
     yieldToMain() {
         const globalScheduler = globalThis.scheduler;
@@ -1063,19 +1174,28 @@ export class VobSubRenderer extends BaseVideoSubtitleRenderer {
         if (this.state.useWorker && this.state.workerReady) {
             // Start async render if not already pending
             if (!this.state.pendingRenders.has(index)) {
-                const renderPromise = sendToWorker({
+                const renderTask = sendToWorker({
                     type: 'renderVobSubAtIndex',
                     sessionId: this.state.sessionId,
                     index
-                }).then((response) => (response.type === 'vobSubFrame' && response.frame ? convertFrameData(response.frame) : null));
+                }).then((response) => {
+                    if (response.type === 'vobSubFrame') {
+                        return {
+                            frame: response.frame ? convertFrameData(response.frame) : null,
+                            renderIssue: response.renderIssue?.trim() || null
+                        };
+                    }
+                    return { frame: null, renderIssue: null };
+                });
+                const renderPromise = renderTask.then(({ frame }) => frame);
                 this.state.pendingRenders.set(index, renderPromise);
                 this.emitCacheChange(this.state.frameCache.size, this.state.pendingRenders.size);
-                renderPromise.then((result) => {
-                    setCachedFrame(this.state, index, result);
+                renderTask.then(({ frame, renderIssue }) => {
+                    setCachedFrame(this.state, index, frame, renderIssue);
                     this.state.pendingRenders.delete(index);
                     this.emitCacheChange(this.state.frameCache.size, this.state.pendingRenders.size);
                     // Force re-render on next frame by resetting lastRenderedIndex
-                    if (this.findCurrentIndex(this.video.currentTime) === index) {
+                    if (this.findCurrentIndex(this.video.currentTime + this.timeOffset) === index) {
                         this.lastRenderedIndex = -1;
                     }
                 });
@@ -1084,7 +1204,7 @@ export class VobSubRenderer extends BaseVideoSubtitleRenderer {
             return undefined;
         }
         const rendered = this.vobsubParser?.renderAtIndex(index) ?? null;
-        setCachedFrame(this.state, index, rendered);
+        setCachedFrame(this.state, index, rendered, this.vobsubParser?.getLastRenderIssue() ?? null);
         this.emitCacheChange(this.state.frameCache.size, this.state.pendingRenders.size);
         return rendered ?? undefined;
     }
@@ -1117,6 +1237,7 @@ export class VobSubRenderer extends BaseVideoSubtitleRenderer {
     }
     onSeek() {
         this.state.frameCache.clear();
+        this.state.renderIssues.clear();
         this.state.pendingRenders.clear();
         // Clear cached index lookup on seek
         this.cachedIndex = -1;
@@ -1134,6 +1255,7 @@ export class VobSubRenderer extends BaseVideoSubtitleRenderer {
     }
     clearFrameCache() {
         this.state.frameCache.clear();
+        this.state.renderIssues.clear();
         this.state.pendingRenders.clear();
         this.cachedIndex = -1;
         this.cachedIndexTime = -1;
@@ -1214,6 +1336,7 @@ export class VobSubRenderer extends BaseVideoSubtitleRenderer {
     dispose() {
         super.dispose();
         this.state.frameCache.clear();
+        this.state.renderIssues.clear();
         this.state.pendingRenders.clear();
         if (this.state.useWorker && this.state.workerReady) {
             sendToWorker({ type: 'disposeVobSub', sessionId: this.state.sessionId }).catch(() => { });